Skip to content
v0.3

Overview

CORS on host.http is arc configuration with automatic preflight - not a middleware hook.

AI generated, pending review Updated 10 days ago · Flare 0.3

Cross-Origin Resource Sharing (CORS) lets browser clients on one origin call your API on another. On Flare, CORS is arc configuration, not middleware. You declare a policy with host.http.cors(config) (or g.cors(config) inside a route group). Flare answers preflight OPTIONS requests and sets Access-Control-* headers before your before hooks or route handlers run.

Do not hand-roll CORS with an OPTIONS handler or manual Access-Control-Allow-Origin headers unless you need behavior outside what CorsConfig supports.

Where policies attach

Section titled “Where policies attach”
ScopeAPIEffect
Arc-widehost.http.cors(config)Applies to every route not inside a group with its own g.cors()
Per groupg.cors(config) inside host.http.groupFully replaces the arc policy for routes in that group

Group g.cors() does not merge with the arc policy. Restate any headers, credentials, or maxAge you still want for that group’s routes.

Build-time validation

Section titled “Build-time validation”

host.build() validates CORS config:

  • credentials: true with origins: '*' throws CORS_CREDENTIALS_WILDCARD
  • Partial wildcards like '*.example.com' throw CORS_PARTIAL_WILDCARD
  • Negative maxAge throws CORS_NEGATIVE_MAX_AGE

Hand-rolled CORS is usually a middleware, and the placement is where it goes wrong. A preflight OPTIONS carries no credentials, so when it enters the pipeline ahead of the CORS logic it can trip an auth hook and come back as a 401 that the browser surfaces only as an opaque cross-origin failure. The credentials: true and wildcard-origin combination is a spec violation the browser silently drops, so the misconfiguration arrives as a bug report rather than an error. Flare answers preflight in the method-dispatch layer before any before hook runs, and that combination fails build() as CORS_CREDENTIALS_WILDCARD instead of failing quietly in a browser later.

Runtime behavior

Section titled “Runtime behavior”

A CORS preflight is an OPTIONS request whose path matched, whose pipeline has a CORS policy, and that carries both Origin and Access-Control-Request-Method. Flare short-circuits with 204 and the appropriate headers (or Allow only when the origin is denied).

Non-preflight OPTIONS without an explicit handler gets an auto 204 with Allow. See Routing behavior.

Section titled “Related”