CORS
CORS is a route directive, not a plain middleware — a preflight
OPTIONS request never matches a method-specific route, so a middleware
would never run for it. cors(options, child) is a dedicated directive
that the compiler expands: it decorates the real responses with the CORS
headers and synthesises an OPTIONS preflight route for every pattern
in child.
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),)));The compiler adds OPTIONS /api automatically; a browser preflight gets
204 with the Access-Control-Allow-* headers, and the actual GET/POST
responses get Access-Control-Allow-Origin + Vary: Origin.
Configuration
Section titled “Configuration”| Builder method | Field | Purpose |
|---|---|---|
withOrigins(...o) | origins | Exact-match allowlist. Config: origins. |
withAnyOrigin() | origins | Allow any origin (*). Must be explicit — code-only. |
withOriginPredicate(predicate) | origins | Decide per request; a throwing predicate denies. A predicate that accepts a value which is not a well-formed origin also denies — see below. Code-only. |
withMethods(...m) | methods | Access-Control-Allow-Methods. Default: the methods registered at the pattern. Config: methods. |
withAllowedHeaders(...h) | allowedHeaders | Default: echo the request’s header names, filtered to RFC 7230 tokens — a name carrying anything else is dropped whole, and the field is omitted when none survive. See below. 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 duration. Config: max-age. |
Every field except the wildcard and the predicate is also settable from
actor-ts.http.cors, under the same name in kebab-case — origins,
methods, allowed-headers, exposed-headers, credentials, max-age.
The order is the usual one, per field: what the route names in code wins,
then the config block, then the built-in default. So the allowlist can live in
application.conf while withCredentials() stays in code, and each takes
effect.
actor-ts.http.cors { origins = ["https://app.example", "https://admin.example"] max-age = 600 # seconds — not a duration string}The two arms marked code-only above are exactly that: there is no key for
either. origins = ["*"] in a config file is refused with a ConfigError
naming the key — one line that widened every cors() route in the process to
any origin is what withAnyOrigin()’s “must be explicit” exists to prevent —
and a predicate is a function, which HOCON cannot express at all.
methods, allowed-headers and max-age ship no value in
reference.conf, because each has a default that a published literal would
destroy: the methods actually registered at the pattern, the echoed request
headers, and “send no Access-Control-Max-Age at all”. origins ships none
either, so that a cors() with no allowlist anywhere stays a loud error
instead of becoming a silent deny-all. All four are still read when a
deployment sets them. See
Configuration → actor-ts.http for the table.
Access-Control-Allow-Origin echoes the request origin (the literal * is
sent only for withAnyOrigin() without credentials), and Vary: Origin
is merged whenever the origin is echoed so caches don’t cross-serve. The
merge is case-insensitive and additive: a handler that already answered with
Vary: Cookie keeps that field, and the response goes out as a single
Vary: Cookie, Origin.
Where to next
Section titled “Where to next”- Security headers — the companion response headers.
- CSRF — cross-site request forgery protection.
- Security — the recommended stack + ordering.
