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-Token from headersX-Requested-By from 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
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:The legacy 3.x global-setting defaults are:
Consumers migrating from
set(allowCorsRequests=true) + set(accessControlAllow*=...)to the middleware will silently lose:X-Auth-Tokenfrom headersX-Requested-Byfrom headersWhy 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 towheels.middleware.Cors. If your app sent or receivedX-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