HTTP-Middleware

HTTP-Middleware läuft in einer von zwei Router-Ketten: bevor Endpunktmetadaten angefügt werden oder nachdem die Route ihre Parameter und Endpunkt-ID bereitgestellt hat.

Klassifikation: Middleware-Referenz. Jeder YAML-Block ist ein Router-Fragment. Er setzt voraus, dass die genannte Middleware registriert ist und alle referenzierten Token-Store-, Dateisystem-, Endpunkt-, Actor- und Richtlinieneinträge vorhanden sind.

Wie Middleware funktioniert

Jede Middleware erhält eine Options-Map und gibt einen Handler-Wrapper zurück:

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

Optionen verwenden Punkt-Notation: middleware_name.option.name. Legacy-Unterstrich-Format wird für Abwärtskompatibilität unterstützt.

Pre-Handler und Post-Match

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

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

Verfügbare Middleware

CORS {#cors}

Pre-Handler

Cross-Origin Resource Sharing für Browser-Anfragen.

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

OPTIONS-Preflight-Anfragen werden automatisch behandelt.

Rate-Limiting {#ratelimit}

Pre-Handler

Token-Bucket-Rate-Limiting mit Per-Key-Tracking.

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

Schlüssel-Strategien: ip, header:X-API-Key, query:api_key

Gibt 429 Too Many Requests mit Headern zurück: X-RateLimit-Limit, X-RateLimit-Window.

Komprimierung {#compress}

Pre-Handler

Gzip-Komprimierung für Responses.

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

Komprimiert nur wenn Client Accept-Encoding: gzip sendet.

Real IP {#real_ip}

Pre-Handler

Client-IP aus Proxy-Headern extrahieren.

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

Header-Priorität: True-Client-IP > X-Real-IP > X-Forwarded-For

Token-Auth {#token_auth}

Pre-Handler

Token-basierte Authentifizierung. Informationen zur Token-Store-Konfiguration finden Sie unter Sicherheit.

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

Setzt Actor und Sicherheits-Scope im Kontext für nachgelagerte Middleware. Blockiert keine Anfragen - Autorisierung erfolgt in Firewall-Middleware.

Metriken {#metrics}

Pre-Handler

HTTP-Metriken im Prometheus-Stil. Diese Middleware wird nur registriert, wenn ein Metrik-Collector verfügbar ist, und besitzt keine Konfigurationsoptionen.

middleware:
  - metrics

Endpoint-Firewall {#endpoint_firewall}

Post-Match

Autorisierung anhand des abgeglichenen Endpunkts. Sie erfordert einen Actor und Sicherheits-Scope im Request-Kontext; token_auth ist eine Möglichkeit, beide bereitzustellen.

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

Gibt 401 Unauthorized (kein Actor) oder 403 Forbidden (Berechtigung verweigert) zurück.

Resource-Firewall {#resource_firewall}

Post-Match

Bestimmte Ressourcen nach ID schützen. Nützlich auf Router-Ebene.

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

Sendfile {#sendfile}

Pre-Handler

Dateien über X-Sendfile-Header von Handlern bereitstellen.

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

Handler setzt Header um Datei-Bereitstellung auszulösen:

Unterstützt Range-Requests für fortsetzbare Downloads.

WebSocket-Relay {#websocket_relay}

Post-Match

WebSocket-Verbindungen an Prozesse weiterleiten. Siehe WebSocket-Relay.

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

SSE-Relay {#sse_relay}

Post-match

Server-Sent Events von Prozessen streamen. Siehe Server-Sent Events.

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

OpenTelemetry {#otel}

Pre-Handler

Zeichnet OpenTelemetry-Server-Spans fuer eingehende Anfragen auf. Wird immer registriert; wirkt als No-Op, wenn OTel oder dessen HTTP-Instrumentierung deaktiviert ist.

middleware:
  - otel

Nimmt keine Optionen entgegen. Funktioniert zusammen mit der metrics-Middleware; aktivieren Sie beide, wenn Sie Prometheus-Counter und OTel-Traces benötigen.

Middleware-Reihenfolge

Bei Anfragen läuft Middleware in der aufgeführten Reihenfolge; die Response-Verarbeitung wird in umgekehrter Reihenfolge abgewickelt. Empfohlene Sequenz:

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

Siehe auch

• Routing – Router-Konfiguration
• Sicherheit – Token-Stores und Richtlinien
• WebSocket-Relay – WebSocket-Verarbeitung
• Server-Sent Events – SSE-Streaming
• Terminal – Terminaldienst