Repository navigation
allowCorsRequests global setting still works in 4.0 but upgrade guide only describes the new wheels.middleware.Cors path #2633
Description
Describe the issue
The Wheels 3.x global setting set(allowCorsRequests=true) is still honored in 4.0 — the framework checks it in vendor/wheels/Global.cfc (around line 3536), defaults it to false in vendor/wheels/events/init/security.cfm line 17, and has dedicated tests under vendor/wheels/tests/specs/dispatch/setCorsHeadersSpec.cfc and corsSecurityDefaultsSpec.cfc.
But the 3.x → 4.0 upgrade guide item 1 (CORS default flips from wildcard to deny-all) and the CHANGELOG #2039 only describe the new wheels.middleware.Cors middleware.
3.x apps that use the global setting (titan does) have no documented:
- Confirmation that the old global setting still works
- Comparison of when to use the old setting vs the new middleware
- Migration path from the global setting to the middleware
- Precedence order when both are configured
Why this matters
Real-world 3.x apps configured CORS via set(allowCorsRequests=true) and the accessControlAllow* family of settings — not via the middleware. After upgrading to 4.0, they will either:
- Assume the upgrade guide's middleware changes apply to them and refactor unnecessarily, OR
- Assume the changes don't apply and not realize the new middleware exists at all (and miss out on the per-route configurability + secure default it provides)
Neither outcome is good.
Suggested fix
Add a short section to the canonical 3.x → 4.0 guide under the CORS breaker (or as a new "CORS — two paths in 4.0" section) covering:
- The old global
set(allowCorsRequests=true)andset(accessControlAllow*)family of settings is still honored. No migration required for apps that only use these. - The new
wheels.middleware.Corsis a separate, more configurable path with deny-all default and per-route scoping. - Both paths can be active simultaneously — document the precedence (does the middleware run before or after the global setting's header emission? Both? Neither overrides the other?).
- Recommendation: new code should use the middleware; existing global-setting configs are fine to leave during the upgrade window.
Environment
- Wheels: 4.0.0-SNAPSHOT+1779
🤖 Filed by Claude Code while assisting with a 4.0 upgrade testbed
Activity
wheels-bot commentedon May 13, 2026
Wheels Bot — Triage
Classified as docs-request.
Docs scope
Add a new section to
web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx(and thev4-0-1-snapshot/copy) under the CORS breaker, titled something like "CORS — two paths in 4.0." Content should cover: (a) confirmation that the 3.x global settingset(allowCorsRequests=true)and theaccessControlAllow*family are still honored in 4.0 with no migration required, (b) a short comparison vs. the newwheels.middleware.Cors(deny-all default, per-route scoping), (c) the precedence/interaction when both are active — to be confirmed by readingvendor/wheels/Global.cfc,vendor/wheels/events/init/security.cfm, andvendor/wheels/middleware/Cors.cfc, and (d) a recommendation that new code use the middleware while existing global-setting configs can remain. Roughly a single MDX section (~40–80 lines).Confidence:
highThe gap is concrete, the target page already exists and is named by the reporter, and the work is primarily translation-of-code (read the three referenced files plus the dispatch CORS specs to confirm precedence) rather than a structural docs-architecture decision.
<!-- wheels-bot:triage:2633 -->
<!-- wheels-bot:triage-class:docs-request -->
<!-- wheels-bot:docs-confidence:high -->
wheels-bot commentedon May 13, 2026
Wheels Bot — Docs proposed
Draft PR: #2638
Pages updated:
web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx— new sub-section "CORS — two paths in 4.0" added under section 1web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx— same section (snapshot copy)Screenshots needed: none
The new section confirms the global setting still works, adds a comparison table, documents the split behavior when both paths are active (global setting wins OPTIONS preflight, middleware wins everything else), and gives a clear recommendation. A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly.