Middleware HTTP

O middleware HTTP é executado em uma de duas cadeias do roteador: antes de os metadados do endpoint serem anexados ou depois de a rota fornecer seus parâmetros e o ID do endpoint.

Classificação: referência de middleware. Cada bloco YAML é um fragmento de roteador; ele pressupõe que o middleware nomeado esteja registrado e que qualquer token store, sistema de arquivos, endpoint, ator e política referenciados existam.

Como Middleware Funciona

Cada middleware recebe um mapa de opções e retorna um wrapper de handler:

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

Opções usam notação de ponto: middleware_name.option.name. Formato legado com underscore é suportado para compatibilidade retroativa.

Pré-handler e pós-match

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

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

Middleware Disponível

CORS {#cors}

Pré-handler

Cross-Origin Resource Sharing para requisições de navegador.

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

Requisições OPTIONS preflight são tratadas automaticamente.

Rate Limiting {#ratelimit}

Pré-handler

Rate limiting com token bucket e rastreamento por chave.

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

Estratégias de chave: ip, header:X-API-Key, query:api_key

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

Compressão {#compress}

Pré-handler

Compressão Gzip para respostas.

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

Comprime apenas quando cliente envia Accept-Encoding: gzip.

Real IP {#real_ip}

Pré-handler

Extrai IP do cliente de headers de proxy.

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

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

Token Auth {#token_auth}

Pré-handler

Autenticação baseada em token. Veja Segurança para configurar o token store.

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

Define ator e escopo de segurança no contexto para middleware downstream. Não bloqueia requisições - autorização acontece em middleware de firewall.

Métricas {#metrics}

Pré-handler

Métricas HTTP no estilo Prometheus. Esse middleware só é registrado quando há um coletor de métricas disponível e não possui opções de configuração.

middleware:
  - metrics

Firewall de Endpoint {#endpoint_firewall}

Pós-match

Autorização baseada no endpoint correspondente. Exige um ator e um escopo de segurança no contexto da requisição; token_auth é uma forma de fornecê-los.

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

Retorna 401 Unauthorized (sem ator) ou 403 Forbidden (permissão negada).

Firewall de Recurso {#resource_firewall}

Pós-match

Protege recursos específicos por ID. Útil no nível de roteador.

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

Sendfile {#sendfile}

Pré-handler

Serve arquivos via header X-Sendfile de handlers.

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

Handler define headers para disparar serviço de arquivo:

Suporta requisições de range para downloads resumíveis.

Relay WebSocket {#websocket_relay}

Pós-match

Retransmite conexões WebSocket para processos. Veja Relay WebSocket.

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

Relay SSE {#sse_relay}

Post-match

Transmite Server-Sent Events de processos. Veja Server-Sent Events.

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

OpenTelemetry {#otel}

Pré-handler

Registra spans de servidor OpenTelemetry para requisições recebidas. Sempre registrado; atua como no-op quando o OTel ou sua instrumentação HTTP está desabilitada.

middleware:
  - otel

Não aceita opções. Funciona junto com o middleware metrics; habilite ambos quando precisar de contadores Prometheus e traces OTel.

Ordem de Middleware

Nas requisições, o middleware é executado na ordem listada; o processamento da resposta é desenrolado na ordem inversa. Sequência 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

Veja Também

• Roteamento - Configuração de roteador
• Segurança - Token stores e políticas
• Relay WebSocket - Tratamento de WebSocket
• Server-Sent Events - Streaming SSE
• Terminal - Serviço de terminal