Middleware HTTP

El middleware HTTP se ejecuta en una de dos cadenas del router: antes de adjuntar los metadatos del endpoint o después de que la ruta proporcione sus parámetros y el ID del endpoint.

Clasificación: referencia de middleware. Cada bloque YAML es un fragmento de router; presupone que el middleware indicado está registrado y que existen todas las entradas referenciadas de almacén de tokens, sistema de archivos, endpoint, actor y política.

Cómo Funciona el Middleware

Cada middleware recibe un mapa de opciones y devuelve un wrapper de handler:

middleware:
  - cors
  - ratelimit
options:
  cors.allow.origins: "https://example.com"
  ratelimit.requests: "100"

Las opciones usan notación de punto: middleware_name.option.name. El formato heredado con guion bajo es soportado para compatibilidad hacia atrás.

Pre-handler y post-match

middleware:        # Before endpoint metadata
  - cors
  - compress
options:
  cors.allow.origins: "*"

post_middleware:   # Post-match
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"

Middleware Disponible

CORS {#cors}

Pre-handler

Cross-Origin Resource Sharing para solicitudes de navegador.

middleware:
  - cors
options:
  cors.allow.origins: "https://app.example.com"
  cors.allow.credentials: "true"

Las solicitudes preflight OPTIONS son manejadas automáticamente.

Rate Limiting {#ratelimit}

Pre-handler

Limitación de tasa con token bucket y tracking por clave.

middleware:
  - ratelimit
options:
  ratelimit.requests: "100"
  ratelimit.window: "1m"
  ratelimit.key: "ip"

Estrategias de clave: ip, header:X-API-Key, query:api_key

Retorna 429 Too Many Requests con headers: X-RateLimit-Limit, X-RateLimit-Window.

Compresión {#compress}

Pre-handler

Compresión Gzip para respuestas.

middleware:
  - compress
options:
  compress.level: "default"
  compress.min.length: "1024"

Solo comprime cuando el cliente envía Accept-Encoding: gzip.

Real IP {#real_ip}

Pre-handler

Extrae IP del cliente de headers de proxy.

middleware:
  - real_ip
options:
  real_ip.trusted.subnets: "10.0.0.0/8,172.16.0.0/12"

Prioridad de header: True-Client-IP > X-Real-IP > X-Forwarded-For

Token Auth {#token_auth}

Pre-handler

Autenticación basada en token. Consulte Seguridad para configurar el almacén de tokens.

middleware:
  - token_auth
options:
  token_auth.store: "app:tokens"

Establece actor y scope de seguridad en contexto para middleware downstream. No bloquea solicitudes—la autorización ocurre en middleware firewall.

Metrics {#metrics}

Pre-handler

Métricas HTTP estilo Prometheus. Este middleware solo se registra cuando hay disponible un recolector de métricas y no admite opciones de configuración.

middleware:
  - metrics

Endpoint Firewall {#endpoint_firewall}

Post-match

Autorización basada en el endpoint coincidente. Requiere un actor y un scope de seguridad en el contexto de la solicitud; token_auth es una forma de proporcionarlos.

post_middleware:
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"

Retorna 401 Unauthorized (sin actor) o 403 Forbidden (permiso denegado).

Resource Firewall {#resource_firewall}

Post-match

Proteger recursos específicos por ID. Útil a nivel de router.

post_middleware:
  - resource_firewall
post_options:
  resource_firewall.action: "admin"
  resource_firewall.target: "app:admin-panel"

Sendfile {#sendfile}

Pre-handler

Servir archivos vía header X-Sendfile desde handlers.

middleware:
  - sendfile
options:
  sendfile.fs: "app:downloads"

El handler establece headers para activar el servicio de archivos:

Soporta solicitudes de rango para descargas reanudables.

WebSocket Relay {#websocket_relay}

Post-match

Retransmite conexiones WebSocket a procesos. Consulte WebSocket Relay.

post_middleware:
  - websocket_relay
post_options:
  wsrelay.allowed.origins: "https://app.example.com"

SSE Relay {#sse_relay}

Post-match

Transmite Server-Sent Events desde procesos. Consulte Server-Sent Events.

post_middleware:
  - sse_relay
post_options:
  sserelay.allowed.origins: "https://app.example.com"

OpenTelemetry {#otel}

Pre-handler

Registra spans de servidor OpenTelemetry para solicitudes entrantes. Siempre está registrado; actúa como no-op cuando OTel o su instrumentación HTTP están deshabilitados.

middleware:
  - otel

No acepta opciones. Funciona junto al middleware metrics; habilita ambos cuando necesites contadores Prometheus y trazas OTel.

Orden de Middleware

En las solicitudes, el middleware se ejecuta en el orden indicado; el procesamiento de la respuesta se desenrolla en orden inverso. Secuencia recomendada:

middleware:
  - real_ip       # 1. Extract real IP first
  - cors          # 2. Handle CORS preflight
  - compress      # 3. Set up response compression
  - ratelimit     # 4. Check rate limits
  - metrics       # 5. Record metrics
  - token_auth    # 6. Authenticate requests

post_middleware:
  - endpoint_firewall  # Authorize after route match

Véase también

• Enrutamiento - Configuración del router
• Seguridad - Almacenes de tokens y políticas
• Relay WebSocket - Manejo de WebSocket
• Server-Sent Events - Streaming SSE
• Terminal - Servicio de terminal