Middleware HTTP

El middleware procesa solicitudes HTTP antes y después del manejo de rutas.

Cómo Funciona el Middleware

El middleware envuelve manejadores HTTP para agregar lógica de procesamiento. Cada middleware recibe un mapa de opciones y retorna un wrapper de manejador:

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

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

Pre-Match vs Post-Match

Pre-match se ejecuta antes del matching de rutas—para concerns transversales como CORS y compresión. Post-match se ejecuta después de que la ruta es matcheada—para autorización que necesita info de ruta. 
middleware:        # Pre-match
  - cors
  - compress
options:
  cors.allow.origins: "*"

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

Middleware Disponible

CORS {#cors}

Pre-match

Cross-Origin Resource Sharing para solicitudes de navegador.

middleware:
  - cors
options:
  cors.allow.origins: "https://app.example.com"
  cors.allow.credentials: "true"
Opción Por Defecto Descripción
cors.allow.origins * Orígenes permitidos (separados por coma, soporta *.example.com)
cors.allow.methods GET,POST,PUT,DELETE,OPTIONS,PATCH Métodos permitidos
cors.allow.headers Origin,Content-Type,Accept,Authorization,X-Requested-With Headers de solicitud permitidos
cors.expose.headers - Headers expuestos al cliente
cors.allow.credentials false Permitir cookies/auth
cors.max.age 86400 Caché de preflight (segundos)
cors.allow.private.network false Acceso a red privada

Las solicitudes preflight OPTIONS son manejadas automáticamente.

Rate Limiting {#ratelimit}

Pre-match

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

middleware:
  - ratelimit
options:
  ratelimit.requests: "100"
  ratelimit.window: "1m"
  ratelimit.key: "ip"
Opción Por Defecto Descripción
ratelimit.requests 100 Solicitudes por ventana
ratelimit.window 1m Ventana de tiempo
ratelimit.burst 20 Capacidad de ráfaga
ratelimit.key ip Estrategia de clave
ratelimit.cleanup_interval 5m Frecuencia de limpieza
ratelimit.entry_ttl 10m Expiración de entrada
ratelimit.max_entries 100000 Claves máximas rastreadas

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

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

Compresión {#compress}

Pre-match

Compresión Gzip para respuestas.

middleware:
  - compress
options:
  compress.level: "default"
  compress.min.length: "1024"
Opción Por Defecto Descripción
compress.level default fastest, default, o best
compress.min.length 1024 Tamaño mínimo de respuesta (bytes)

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

Real IP {#real_ip}

Pre-match

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"
Opción Por Defecto Descripción
real_ip.trusted.subnets Redes privadas CIDRs de proxy confiables
real_ip.trust_all false Confiar en todas las fuentes (inseguro)

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

Token Auth {#token_auth}

Pre-match

Autenticación basada en token. Ver Seguridad para configuración de almacén de tokens.

middleware:
  - token_auth
options:
  token_auth.store: "app:tokens"
Opción Por Defecto Descripción
token_auth.store requerido ID de registro del almacén de tokens
token_auth.header.name Authorization Nombre de header
token_auth.header.prefix Bearer Prefijo de header
token_auth.query.param x-auth-token Parámetro de query fallback
token_auth.cookie.name x-auth-token Cookie fallback

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

Metrics {#metrics}

Pre-match

Métricas HTTP estilo Prometheus. Sin opciones de configuración.

middleware:
  - metrics
Métrica Tipo Descripción
wippy_http_requests_total Counter Total de solicitudes
wippy_http_request_duration_seconds Histogram Latencia de solicitud
wippy_http_requests_in_flight Gauge Solicitudes concurrentes

Endpoint Firewall {#endpoint_firewall}

Post-match

Autorización basada en endpoint matcheado. Requiere actor de token_auth.

post_middleware:
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"
Opción Por Defecto Descripción
endpoint_firewall.action access Acción de permiso a verificar

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"
Opción Por Defecto Descripción
resource_firewall.action access Acción de permiso
resource_firewall.target requerido ID de registro del recurso

Sendfile {#sendfile}

Pre-match

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:

Header Descripción
X-Sendfile Ruta del archivo dentro del filesystem
X-File-Name Nombre de archivo para descarga

Soporta solicitudes de rango para descargas reanudables.

WebSocket Relay {#websocket_relay}

Post-match

Retransmite conexiones WebSocket a procesos. Ver WebSocket Relay.

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

Orden de Middleware

El middleware se ejecuta en el orden listado. Secuencia recomendada:

middleware:
  - real_ip       # 1. Extraer IP real primero
  - cors          # 2. Manejar preflight CORS
  - compress      # 3. Configurar compresión de respuesta
  - ratelimit     # 4. Verificar límites de tasa
  - metrics       # 5. Registrar métricas
  - token_auth    # 6. Autenticar solicitudes

post_middleware:
  - endpoint_firewall  # Autorizar después de match de ruta

Ver También