Preflight Request Optimization & Caching Strategies

The WHATWG Fetch Standard (§4.8–4.10) defines a preflight as a synthetic OPTIONS request the browser dispatches before any cross-origin request that falls outside the simple request classification. Eliminating or caching that round trip requires precise alignment between server response headers, browser-enforced TTL limits, and infrastructure routing — all three layers must cooperate for optimization to hold.

Key Architectural Principles

• Access-Control-Max-Age is a browser-side directive; the server proposes a TTL but each engine enforces its own hard cap, silently overriding higher values.
• The preflight cache is keyed on (serialized URL, method, sorted request-header names) — a single extra header in one request breaks the cache hit for all subsequent requests with the same URL and method.
• Credential-bearing requests (credentials: "include") require the server to reflect the exact Origin value; * is forbidden by spec and causes an immediate browser rejection.
• Vary: Origin is mandatory on any resource whose CORS headers differ by origin — missing it causes CDNs to serve a cached response to an unintended origin.
• HTTP/2 and HTTP/3 reduce preflight cost through multiplexing, but do not eliminate the cache-miss round trip; only correct Access-Control-Max-Age configuration does that.
• Eliminating preflights via a reverse proxy is architecturally safe: the browser never sees a cross-origin boundary, so neither CORS nor the Same-Origin Policy applies.
• OPTIONS handlers must return zero-body 204 No Content responses; any middleware that reads session state or writes to a database on the OPTIONS path adds latency with no security benefit.

Preflight Flow Diagram

Core Mechanics: How the Browser Enforces Preflight

The WHATWG Fetch algorithm evaluates each cross-origin request against a simple request classification matrix before deciding whether to dispatch an OPTIONS request. The evaluation is purely client-side: the server has no say in whether a preflight is triggered.

After a successful preflight, the browser stores the response in a per-partition CORS cache. The cache entry records the allowed methods and headers for the exact (URL, method, header set) tuple. On subsequent requests that match that tuple, the browser skips the OPTIONS call entirely — provided the entry has not expired or been invalidated by a credential change.

Cache invalidation happens in four scenarios:

1. Access-Control-Max-Age expires.
2. The request adds a header not listed in the cached Access-Control-Allow-Headers value.
3. The request uses a method not listed in the cached Access-Control-Allow-Methods value.
4. The user’s credential state changes (login/logout), which the browser treats as a new trust context.

Understanding these rules is the foundation for all optimization work covered on this page.

Request Classification Matrix

The Content-Type: application/json case is the most common production surprise. Many teams assume a POST without Authorization will avoid a preflight — it will not, because application/json is not in the allowed Content-Type set for simple requests.

Cache Duration Tuning & Max-Age Configuration

The cache duration tuning workflow begins with a single fact: Access-Control-Max-Age is advisory. Each browser engine enforces a hard cap it will not exceed, regardless of the server’s value.

Setting Access-Control-Max-Age: 600 gives consistent behaviour across all production browsers. Values above 600 benefit Firefox users only; Chrome and Safari silently ignore the excess.

When the header is absent entirely, Blink and Gecko default to 5 seconds — meaning a user refreshing a page every 10 seconds triggers a preflight on every load. Even a modest Access-Control-Max-Age: 60 reduces preflight frequency by 12× in that scenario.

Canonical OPTIONS response:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-ID
Access-Control-Max-Age: 600
Vary: Origin

The Vary: Origin header is not part of the preflight cache mechanism itself, but it is mandatory on the same-origin resource response to prevent CDNs from serving a cached CORS-permissive response to a same-origin request (or vice versa).

Header Deduplication & Cache Key Management

Because the preflight cache key includes the sorted set of request header names, every unique header combination in your codebase generates a distinct cache entry. A client that sometimes sends X-Request-ID and sometimes omits it will cache-miss on every other preflight even if the URL and method are identical.

Header deduplication techniques address this at the API client layer:

• Consolidate authentication metadata into a single Authorization: Bearer <token> header rather than splitting tokens across X-Auth-Token, X-User-ID, and X-Session-ID.
• Remove legacy cross-origin headers (X-Requested-With, X-CSRF-Token) from fetch calls unless a specific backend middleware requires them.
• Standardize client interceptors to emit a deterministic header set per API domain — intercept at the fetch wrapper or Axios instance level, not per-component.

The Vary header on the resource response (not the preflight) affects CDN caching separately. Overly broad Vary values (e.g., Vary: Accept-Encoding, Origin, Accept-Language, Authorization) fragment CDN cache storage geometrically. Audit Vary values on your API gateway and reduce them to the minimum set required for correctness.

Server-Side OPTIONS Endpoint Architecture

An OPTIONS handler has one job: return CORS authorization metadata as fast as possible. Any middleware that queries a database, reads session storage, or renders a template on the OPTIONS path is wasted compute.

Express.js — zero-overhead OPTIONS handler:

// Register OPTIONS handler before any auth middleware
app.options('/api/*', (req, res) => {
  const allowed = ['https://app.example.com', 'https://staging.example.com'];
  const origin = req.headers.origin;
  if (allowed.includes(origin)) {
    res.set('Access-Control-Allow-Origin', origin);
    res.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
    res.set('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-Request-ID');
    res.set('Access-Control-Max-Age', '600');
    res.set('Vary', 'Origin');
  }
  res.status(204).end();
});

// Auth middleware applies only to non-OPTIONS routes
app.use('/api/*', requireAuth);

Nginx — edge-level OPTIONS interception:

location /api/ {
  if ($request_method = OPTIONS) {
    add_header Access-Control-Allow-Origin  $http_origin always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE" always;
    add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Request-ID" always;
    add_header Access-Control-Max-Age       600 always;
    add_header Vary                         Origin always;
    return 204;
  }
  proxy_pass http://backend;
}

The always flag ensures these headers are appended even if the upstream returns a non-2xx status. Without always, a backend error on a non-OPTIONS request strips the CORS headers and the browser raises a network error that masks the real failure.

For the full OPTIONS endpoint design reference, including rate-limiting patterns and connection-pooling configuration, see the dedicated section.

Fetch API — confirming the preflight is skipped:

// After the first successful preflight (max-age: 600),
// subsequent requests skip the OPTIONS round trip for 10 minutes
const res = await fetch('https://api.example.com/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  credentials: 'include',
});

Security Boundary Mapping

Optimization must operate within the constraints of the Same-Origin Policy. Relaxing CORS headers beyond what the spec permits introduces data exfiltration vectors, not just performance gains.

Credential isolation rules

When credentials: "include" is set, the WHATWG Fetch spec (§3.2.3) requires:

• Access-Control-Allow-Origin must reflect the exact Origin request header value — * is forbidden.
• Access-Control-Allow-Credentials: true must be present.
• The origin reflected must be one the server has explicitly validated against its allowlist. Echoing the Origin header without validation introduces a universal CORS bypass.

Wildcard prohibitions

Access-Control-Allow-Origin: * is legitimate for truly public, non-credentialed resources (public CDN assets, open APIs). It is inappropriate for any endpoint that reads session cookies, issues tokens, or returns user-scoped data — even if the endpoint does not currently require credentials: "include", because a future caller might.

Vary requirements

Per dynamic origin validation patterns, whenever the server conditionally reflects the Origin header, the resource response must include Vary: Origin. Omitting Vary: Origin when using dynamic origin reflection causes CDN nodes to cache the first response and serve it to all subsequent requesters, regardless of their origin — a cross-tenant data leak.

Audit trail for proxy bypass

Every proxy rewrite or edge rule that eliminates preflights must be version-controlled. Infrastructure drift — a proxy rule removed during a platform migration — silently re-exposes the API to the full CORS flow, which may break clients that never implemented preflight handling.

Infrastructure Interaction: CDN, WAF, and Reverse Proxy

Preflight caching interacts with infrastructure layers in ways that are not always obvious from the CORS spec alone.

Reverse Proxy Bypass

Routing the frontend and API through the same origin eliminates preflights entirely. The browser never initiates a cross-origin request, so the Same-Origin Policy never applies.

Proxy bypass strategies cover three patterns:

Subdomains are not same-origin. app.example.com and api.example.com are distinct origins under the WHATWG origin tuple definition — a reverse proxy on app.example.com/api/* is required to collapse them.

CDN Preflight Caching

CDNs can cache OPTIONS responses safely when:

1. Cache keys include Origin (often configured as a custom cache key header).
2. Vary: Origin is present on the cached response.
3. The CDN’s cache TTL is set to match or be less than Access-Control-Max-Age.

Without condition 2, a CDN caches the preflight response for Origin: https://app.example.com and serves it to Origin: https://attacker.example.com. The attacker’s browser then believes the server has authorized its origin.

WAF Interaction

Web Application Firewalls that rate-limit by IP can incorrectly throttle OPTIONS requests from CDN edge nodes, because all preflight requests from a PoP share the same egress IP. Configure WAF rules to whitelist OPTIONS requests from known CDN CIDR ranges, or key rate limiting on the Origin header rather than the source IP.

HTTP/2 and HTTP/3 reduce per-connection overhead for remaining preflights through header compression (HPACK/QPACK) and stream multiplexing — but they do not affect whether the browser sends an OPTIONS request. The cache miss path still costs one full round trip before the actual request.

Debugging Workflow: DevTools + curl Trace

Step 1 — Capture the preflight in DevTools

1. Open Chrome DevTools → Network tab.
2. Enable Preserve log and Disable cache.
3. Trigger the cross-origin request.
4. Filter by Method: OPTIONS — each row is a preflight.
5. Select a row → Headers tab → verify Access-Control-Max-Age is present in the response.
6. Select the same row → Timing tab → check for (preflight) in the initiator chain on subsequent requests. If the initiator row shows (from preflight cache), the cache is working.

Step 2 — Confirm the cache hit

Reload the page without disabling the cache. The OPTIONS row should disappear from the Network panel for all requests within the TTL window. If it reappears, the cache key has changed — compare the Access-Control-Request-Headers value between the two captures.

Step 3 — curl probe for the OPTIONS response

curl -si -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Authorization, Content-Type" \
  https://api.example.com/data

Expected output:

HTTP/2 204
access-control-allow-origin: https://app.example.com
access-control-allow-methods: GET, POST, PUT, DELETE
access-control-allow-headers: Authorization, Content-Type, X-Request-ID
access-control-max-age: 600
vary: Origin

Error code → cause mapping

Common Implementation Mistakes

FAQ