CORS
CORS ist eine Route-Direktive, keine gewöhnliche Middleware — ein
Preflight-OPTIONS-Request passt nie auf eine methoden-spezifische Route,
eine Middleware würde dafür also nie laufen. cors(options, child) ist eine
eigene Direktive, die der Compiler expandiert: sie dekoriert die echten
Responses mit den CORS-Headern und synthetisiert für jedes Pattern in
child eine OPTIONS-Preflight-Route.
import { cors, CorsOptions, concat, get, path, post } from 'actor-ts/http';
const corsOptions = CorsOptions.create() .withOrigins('https://app.example', 'https://admin.example') .withCredentials();
const routes = cors(corsOptions, path('api', concat( get(listHandler), post(createHandler),)));Der Compiler fügt OPTIONS /api automatisch hinzu; ein Browser-Preflight
erhält 204 mit den Access-Control-Allow-*-Headern, und die eigentlichen
GET/POST-Responses erhalten Access-Control-Allow-Origin +
Vary: Origin.
Konfiguration
Abschnitt betitelt „Konfiguration“| Builder-Methode | Feld | Zweck |
|---|---|---|
withOrigins(...o) | origins | Exakte Allowlist. Config: origins. |
withAnyOrigin() | origins | Jeden Origin erlauben (*). Muss explizit sein — nur im Code. |
withOriginPredicate(predicate) | origins | Pro Request entscheiden; ein werfendes Prädikat verweigert. Nur im Code. Ein Prädikat, das einen nicht wohlgeformten Origin akzeptiert, verweigert ebenfalls — siehe unten. |
withMethods(...m) | methods | Access-Control-Allow-Methods. Default: die am Pattern registrierten Methoden. Config: methods. |
withAllowedHeaders(...h) | allowedHeaders | Default: die Header-Namen des Requests echoen, gefiltert auf RFC-7230-Tokens — ein Name mit irgendetwas anderem darin fällt ganz weg, und bleibt nichts übrig, entfällt das Feld. Siehe unten. Config: allowed-headers. |
withExposedHeaders(...h) | exposedHeaders | Access-Control-Expose-Headers. Config: exposed-headers. |
withCredentials(flag?) | credentials | Access-Control-Allow-Credentials: true. Config: credentials. |
withMaxAge(seconds) | maxAge | Preflight-Cache-Dauer. Config: max-age. |
Jedes Feld außer der Wildcard und dem Prädikat ist auch über
actor-ts.http.cors setzbar, unter demselben Namen in kebab-case — origins,
methods, allowed-headers, exposed-headers, credentials, max-age. Es
gilt die übliche Reihenfolge, pro Feld: Was die Route im Code nennt,
gewinnt, dann der Config-Block, dann der eingebaute Default. Die Allowlist kann
also in der application.conf liegen, während withCredentials() im Code
bleibt — beides wirkt.
actor-ts.http.cors { origins = ["https://app.example", "https://admin.example"] max-age = 600 # Sekunden — kein Duration-String}Die beiden oben als nur im Code markierten Arme sind genau das: Für keinen
von beiden gibt es einen Key. Ein origins = ["*"] in einer Config-Datei wird
mit einem ConfigError abgelehnt, der den Key nennt — eine Zeile, die jede
cors()-Route im Prozess auf jeden Origin öffnet, ist genau das, was das
„muss explizit sein“ von withAnyOrigin() verhindern soll. Und ein Prädikat
ist eine Funktion, die HOCON gar nicht ausdrücken kann.
methods, allowed-headers und max-age liefern in reference.conf
keinen Wert aus, weil jedes einen Default hat, den ein publizierter
Literalwert zerstören würde: die am Pattern tatsächlich registrierten Methoden,
die geechoten Request-Header und „gar kein Access-Control-Max-Age senden“.
origins liefert ebenfalls keinen, damit ein cors() ohne jede Allowlist ein
lauter Fehler bleibt und kein stilles Deny-all wird. Gelesen werden alle vier
trotzdem, sobald ein Deployment sie setzt. Die Tabelle steht unter
Konfiguration → actor-ts.http.
Access-Control-Allow-Origin echot den Request-Origin (das literale *
wird nur bei withAnyOrigin() ohne Credentials gesendet), und
Vary: Origin wird ergänzt, sobald der Origin geechot wird, damit Caches
nicht falsch ausliefern. Das Ergänzen ist case-insensitiv und additiv: Ein
Handler, der bereits mit Vary: Cookie geantwortet hat, behält dieses Feld —
die Response geht als ein einzelnes Vary: Cookie, Origin raus.
Wie weiter
Abschnitt betitelt „Wie weiter“- Security-Header — die begleitenden Response-Header.
- CSRF — Schutz vor Cross-Site Request Forgery.
- Sicherheit — der empfohlene Stack + Reihenfolge.
