HTTP Middleware

Middleware обрабатывают HTTP-запросы до и после выполнения обработчика маршрута.

Как работают middleware

Middleware оборачивают HTTP-обработчики, добавляя логику обработки. Каждый middleware получает карту опций и возвращает обёртку обработчика:

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

Опции используют точечную нотацию: middleware_name.option.name. Устаревший формат с подчёркиваниями поддерживается для обратной совместимости.

Pre-Match vs Post-Match

middleware:        # Pre-match
  - cors
  - compress
options:
  cors.allow.origins: "*"

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

Доступные middleware

CORS {#cors}

Pre-match

Cross-Origin Resource Sharing для браузерных запросов.

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

OPTIONS preflight-запросы обрабатываются автоматически.

Rate Limiting {#ratelimit}

Pre-match

Ограничение частоты запросов на основе token bucket с отслеживанием по ключам.

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

Стратегии ключа: ip, header:X-API-Key, query:api_key

Возвращает 429 Too Many Requests с заголовками: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Сжатие {#compress}

Pre-match

Gzip-сжатие ответов.

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

Сжимает только при наличии Accept-Encoding: gzip от клиента.

Real IP {#real_ip}

Pre-match

Извлечение реального IP клиента из заголовков прокси.

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

Приоритет заголовков: True-Client-IP > X-Real-IP > X-Forwarded-For

Token Auth {#token_auth}

Pre-match

Аутентификация на основе токенов. См. Безопасность для настройки хранилища токенов.

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

Устанавливает актёра и область безопасности в контексте для последующих middleware. Не блокирует запросы — авторизация происходит в firewall middleware.

Метрики {#metrics}

Pre-match

HTTP-метрики в стиле Prometheus. Без параметров конфигурации.

middleware:
  - metrics

Endpoint Firewall {#endpoint_firewall}

Post-match

Авторизация на основе сопоставленного эндпоинта. Требует актёра из token_auth.

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

Возвращает 401 Unauthorized (нет актёра) или 403 Forbidden (нет прав).

Resource Firewall {#resource_firewall}

Post-match

Защита конкретных ресурсов по ID. Полезен на уровне роутера.

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

Sendfile {#sendfile}

Pre-match

Отдача файлов через заголовок X-Sendfile из обработчиков.

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

Обработчик устанавливает заголовки для запуска отдачи файла:

Поддерживает range-запросы для возобновляемой загрузки.

WebSocket Relay {#websocket_relay}

Post-match

Проксирование WebSocket-соединений в процессы. См. WebSocket Relay.

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

Порядок middleware

Middleware выполняются в порядке перечисления. Рекомендуемая последовательность:

middleware:
  - real_ip       # 1. Сначала извлечь реальный IP
  - cors          # 2. Обработать CORS preflight
  - compress      # 3. Настроить сжатие ответа
  - ratelimit     # 4. Проверить лимиты
  - metrics       # 5. Записать метрики
  - token_auth    # 6. Аутентифицировать запросы

post_middleware:
  - endpoint_firewall  # Авторизовать после сопоставления маршрута

См. также

• Маршрутизация — конфигурация роутера
• Безопасность — хранилища токенов и политики
• WebSocket Relay — обработка WebSocket
• Терминал — терминальный сервис