Skip to content
English

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.

Builder methodFieldPurpose
withOrigins(...o)originsExact-match allowlist. Config: origins.
withAnyOrigin()originsAllow any origin (*). Must be explicit — code-only.
withOriginPredicate(predicate)originsDecide 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)methodsAccess-Control-Allow-Methods. Default: the methods registered at the pattern. Config: methods.
withAllowedHeaders(...h)allowedHeadersDefault: 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)exposedHeadersAccess-Control-Expose-Headers. Config: exposed-headers.
withCredentials(flag?)credentialsAccess-Control-Allow-Credentials: true. Config: credentials.
withMaxAge(seconds)maxAgePreflight 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.

  • Security headers — the companion response headers.
  • CSRF — cross-site request forgery protection.
  • Security — the recommended stack + ordering.