Repository navigation
wheels.middleware.Cors defaults differ in spelling from legacy global settings — silent drift on swap #2708
Description
Severity: docs / upgrade-guide gap. Real-world impact: silently lost allow-list entries on swap.
Surfaced by: titan Phase 2.6 (Wheels 4.0 upgrade), 2026-05-15.
Description
The 4.0 wheels.middleware.Cors.init() defaults are:
allowMethods = \"GET,POST,PUT,PATCH,DELETE,OPTIONS\"
allowHeaders = \"Content-Type,Authorization,X-Requested-With\"
The legacy 3.x global-setting defaults are:
accessControlAllowMethods = \"GET, POST, PATCH, PUT, DELETE, OPTIONS\"
accessControlAllowHeaders = \"Origin, Content-Type, X-Auth-Token, X-Requested-By, X-Requested-With\"
Consumers migrating from set(allowCorsRequests=true) + set(accessControlAllow*=...) to the middleware will silently lose:
X-Auth-Tokenfrom headersX-Requested-Byfrom headers- The comma-space formatting (cosmetic but noticeable)
Why this matters
The upgrade guide currently presents the middleware as the canonical path forward but doesn't call out the defaults drift. Apps doing a like-for-like swap won't realize their allow-list shrank until a request with X-Auth-Token: ... gets rejected.
Suggested fix
Add a section to the 3.x→4.0 upgrade guide under CORS: "Default allow-list values changed when moving from set(accessControlAllow*) globals to wheels.middleware.Cors. If your app sent or received X-Auth-Token, X-Requested-By, or other headers not in the new defaults, pass them explicitly to the middleware constructor."
Optionally: align the middleware's defaults with the legacy globals (additive change, no risk).
cc @bpamiri
Activity
wheels-bot commentedon May 15, 2026
Wheels Bot — Triage
Classified as docs-request.
Docs scope
Add a CORS-defaults-drift callout to the 3.x→4.0 upgrade guide at
web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx(and the matchingv4-0-0/page if it carries the same content). The new section should compare the legacyset(accessControlAllow*)defaults to thewheels.middleware.Cors.init()defaults, call out the headers dropped on a like-for-like swap (X-Auth-Token,X-Requested-By), and show the explicit-constructor-args fix. A cross-link fromdigging-deeper/cors.mdxto the upgrade-guide section is the natural complement so readers landing on the CORS reference don't miss it. The optional middleware-defaults realignment proposed in the issue is a framework change, not a docs change, and is out of scope here.Confidence:
highThe gap is concrete (specific header names and exact default strings to document), the target page already exists, and the work is mechanical translation of values already present in the issue body and
vendor/wheels/middleware/Cors.cfc.<!-- wheels-bot:triage:2708 -->
<!-- wheels-bot:triage-class:docs-request -->
<!-- wheels-bot:docs-confidence:high -->
wheels-bot commentedon May 15, 2026
Wheels Bot — Docs proposed
Draft PR: #2721
Pages updated:
web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx— new "Migrating from global settings to the middleware" subsection with defaults comparison table, code example, and common-issues entryweb/sites/guides/src/content/docs/v4-0-0/digging-deeper/cors.mdx— migration callout Aside after the configuration options tableweb/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx— same as v4-0-0 aboveweb/sites/guides/src/content/docs/v4-0-1-snapshot/digging-deeper/cors.mdx— same as v4-0-0 aboveScreenshots needed: none
A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly.