allowCorsRequests global setting still works in 4.0 but upgrade guide only describes the new wheels.middleware.Cors path

[bpamiri]

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) and set(accessControlAllow*) family of settings is still honored. No migration required for apps that only use these.
• The new wheels.middleware.Cors is 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

[wheels-bot]

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 the v4-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 setting set(allowCorsRequests=true) and the accessControlAllow* family are still honored in 4.0 with no migration required, (b) a short comparison vs. the new wheels.middleware.Cors (deny-all default, per-route scoping), (c) the precedence/interaction when both are active — to be confirmed by reading vendor/wheels/Global.cfc, vendor/wheels/events/init/security.cfm, and vendor/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: high

The 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]

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 1
• web/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.