wheels.middleware.Cors cannot short-circuit OPTIONS preflight — middleware runs after route dispatch

[bpamiri]

Severity: high — the new middleware is unusable for the canonical CORS use-case (cross-origin POST/PUT/PATCH/DELETE) without an upstream fix.

Surfaced by: titan Phase 2.6 (Wheels 4.0 upgrade), 2026-05-15. The legacy set(allowCorsRequests=true) global path handled preflight; the new middleware cannot.

Repro

Configure a Wheels 4.0 app with no explicit OPTIONS route on /api/v1/*:

set(middleware = [
    new wheels.middleware.Cors(allowOrigins="https://portal.pai.com")
]);

Then:

OPTIONS /api/v1/jvm HTTP/1.1
Origin: https://portal.pai.com
Access-Control-Request-Method: POST

→ HTTP/1.1 404 with Wheels.RouteNotFound — Incorrect HTTP Verb for route (from Dispatch.cfc:214).

Expected: 204 No Content with Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers. Browsers will block the actual cross-origin request when preflight fails.

Root cause

In vendor/wheels/Dispatch.cfc:$request():

• Line 260: $paramParser() runs
• Line 260+: $findMatchingRoute() 404s when no OPTIONS route matches
• Line 320: middleware pipeline is built — never reached on the OPTIONS path

wheels.middleware.Cors has explicit preflight-handling code at Cors.cfc:89-95 that is unreachable.

For comparison, the legacy set(allowCorsRequests=true) path aborts OPTIONS at EventMethods.cfc:255-262, BEFORE dispatch route-matching.

Suggested fix

One of:

1. Run a pre-route middleware pass (CORS middleware specifically — or a designated subset — runs before $findMatchingRoute()).
2. Auto-register an OPTIONS verb on every route added via .resources() and friends, dispatching to a built-in preflight handler when CORS middleware is present.
3. Special-case OPTIONS in the dispatcher: if the middleware pipeline contains a wheels.middleware.Cors instance, route OPTIONS to its preflight handler before 404'ing.

Why this matters for v4.0.1

This is the entire reason apps reach for a CORS middleware over the legacy global setting. Without preflight handling, the middleware is strictly less capable than the 3.x setting it's meant to replace.

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

middleware — but the actual fix lives in the dispatch pipeline (vendor/wheels/Dispatch.cfc) since route matching currently runs before the middleware chain. The middleware component itself (vendor/wheels/middleware/Cors.cfc:80-95) already has correct preflight-handling code; it is unreachable for unmatched OPTIONS verbs.

Fix sketch

Touch points: vendor/wheels/Dispatch.cfc $request() (around the $paramParser() → $findMatchingRoute() → middleware-pipeline ordering documented at lines 260/320), and possibly vendor/wheels/middleware/Pipeline.cfc. The reporter's option 1 (run CORS-class middleware as a pre-route pass) is the most surgical and matches the legacy EventMethods.cfc:255-262 short-circuit point. Option 3 (special-case OPTIONS when a wheels.middleware.Cors is present in the pipeline) is an even narrower variant. Option 2 (auto-register OPTIONS on every resource route) is wider blast radius and probably wrong as a default. Either way, a regression test belongs under vendor/wheels/tests/specs/middleware/ exercising an OPTIONS request against a route that only declares POST.

Confidence: medium

Touches vendor/wheels/middleware/** and the dispatch pipeline, which triggers the auto-downgrade rule even though the report is clear and the fix shape is well-scoped.

<!-- wheels-bot:triage:2703 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2728

Spec: vendor/wheels/tests/specs/middleware/CorsPreflightDispatchSpec.cfc — failing → passing (3 specs: OPTIONS-with-CORS no longer 404s, OPTIONS-without-CORS still 404s, GET-with-CORS still 404s on unmatched).
Implementation: vendor/wheels/Dispatch.cfc — $request() checks the verb before $paramParser() and, when it is OPTIONS and the global pipeline contains a wheels.middleware.Cors instance ($hasPreflightCapableMiddleware() via IsInstanceOf), runs the pipeline against a no-op core handler so CORS can set headers and short-circuit before route matching. Mirrors the legacy set(allowCorsRequests=true) short-circuit point in EventMethods.cfc.

Full core test suite passes (3556 pass / 0 fail / 0 error, Lucee 7 + SQLite). The triage's medium-confidence gate (touches dispatch/middleware) was honored — the change is narrowly scoped to the OPTIONS path and gated on an actual wheels.middleware.Cors instance, so non-CORS apps see no behavior change.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.