HTTP-Middleware

Middleware verarbeitet HTTP-Anfragen vor und nach der Routen-Behandlung.

Wie Middleware funktioniert

Middleware umhüllt HTTP-Handler um Verarbeitungslogik hinzuzufügen. 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-Match vs Post-Match

Pre-Match läuft vor dem Routen-Matching - für Querschnittsbelange wie CORS und Komprimierung. Post-Match läuft nachdem die Route gematcht ist - für Autorisierung die Routen-Info benötigt.

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

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

Verfügbare Middleware

CORS {#cors}

Pre-Match

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

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

Option	Standard	Beschreibung
`cors.allow.origins`	`*`	Erlaubte Origins (kommasepariert, unterstützt `*.example.com`)
`cors.allow.methods`	`GET,POST,PUT,DELETE,OPTIONS,PATCH`	Erlaubte Methoden
`cors.allow.headers`	`Origin,Content-Type,Accept,Authorization,X-Requested-With`	Erlaubte Request-Header
`cors.expose.headers`	-	Dem Client exponierte Header
`cors.allow.credentials`	`false`	Cookies/Auth erlauben
`cors.max.age`	`86400`	Preflight-Cache (Sekunden)
`cors.allow.private.network`	`false`	Privater Netzwerkzugriff

OPTIONS-Preflight-Anfragen werden automatisch behandelt.

Rate-Limiting {#ratelimit}

Pre-Match

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

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

Option	Standard	Beschreibung
`ratelimit.requests`	`100`	Anfragen pro Fenster
`ratelimit.window`	`1m`	Zeitfenster
`ratelimit.burst`	`20`	Burst-Kapazität
`ratelimit.key`	`ip`	Schlüssel-Strategie
`ratelimit.cleanup_interval`	`5m`	Bereinigungs-Frequenz
`ratelimit.entry_ttl`	`10m`	Eintrags-Ablauf
`ratelimit.max_entries`	`100000`	Max verfolgte Schlüssel

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-Remaining, X-RateLimit-Reset.

Komprimierung {#compress}

Pre-Match

Gzip-Komprimierung für Responses.

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

Option	Standard	Beschreibung
`compress.level`	`default`	`fastest`, `default` oder `best`
`compress.min.length`	`1024`	Minimale Response-Größe (Bytes)

Komprimiert nur wenn Client Accept-Encoding: gzip sendet.

Real IP {#real_ip}

Pre-Match

Client-IP aus Proxy-Headern extrahieren.

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

Option	Standard	Beschreibung
`real_ip.trusted.subnets`	Private Netzwerke	Vertrauenswürdige Proxy-CIDRs
`real_ip.trust_all`	`false`	Allen Quellen vertrauen (unsicher)

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

Token-Auth {#token_auth}

Pre-Match

Token-basierte Authentifizierung. Siehe Sicherheit für Token-Store-Konfiguration.

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

Option	Standard	Beschreibung
`token_auth.store`	erforderlich	Token-Store-Registry-ID
`token_auth.header.name`	`Authorization`	Header-Name
`token_auth.header.prefix`	`Bearer`	Header-Präfix
`token_auth.query.param`	`x-auth-token`	Query-Parameter-Fallback
`token_auth.cookie.name`	`x-auth-token`	Cookie-Fallback

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

Metriken {#metrics}

Pre-Match

Prometheus-Style HTTP-Metriken. Keine Konfigurationsoptionen.

middleware:
  - metrics

Metrik	Typ	Beschreibung
`wippy_http_requests_total`	Counter	Gesamte Anfragen
`wippy_http_request_duration_seconds`	Histogram	Request-Latenz
`wippy_http_requests_in_flight`	Gauge	Gleichzeitige Anfragen

Endpoint-Firewall {#endpoint_firewall}

Post-Match

Autorisierung basierend auf gematchtem Endpunkt. Erfordert Actor von token_auth.

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

Option	Standard	Beschreibung
`endpoint_firewall.action`	`access`	Zu prüfende Berechtigungs-Aktion

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"

Option	Standard	Beschreibung
`resource_firewall.action`	`access`	Berechtigungs-Aktion
`resource_firewall.target`	erforderlich	Ressourcen-Registry-ID

Sendfile {#sendfile}

Pre-Match

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

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

Handler setzt Header um Datei-Bereitstellung auszulösen:

Header	Beschreibung
`X-Sendfile`	Dateipfad innerhalb des Dateisystems
`X-File-Name`	Download-Dateiname

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-match

Zeichnet OpenTelemetry-Spans und -Metriken fuer eingehende Anfragen auf. Wird automatisch registriert, wenn OTel aktiviert ist; wirkt andernfalls als No-Op.

middleware:
  - otel

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

Middleware-Reihenfolge

Middleware wird in aufgelisteter Reihenfolge ausgeführt. Empfohlene Sequenz:

middleware:
  - real_ip       # 1. Real IP zuerst extrahieren
  - cors          # 2. CORS-Preflight behandeln
  - compress      # 3. Response-Komprimierung einrichten
  - ratelimit     # 4. Rate-Limits prüfen
  - metrics       # 5. Metriken aufzeichnen
  - token_auth    # 6. Anfragen authentifizieren

post_middleware:
  - endpoint_firewall  # Nach Routen-Match autorisieren

Siehe auch

Routing - Router-Konfiguration
Sicherheit - Token-Stores und Richtlinien
WebSocket-Relay - WebSocket-Behandlung
Server-Sent Events - SSE-Streaming
Terminal - Terminal-Dienst