review remediation: middleware lifecycle contract — cache route-scoped string middleware (stateful reset) + cache preflight-capability boolean

[bpamiri]

Problem

Route-scoped string middleware is re-instantiated on every request, and the preflight-capability scan re-runs per OPTIONS request even though the pipeline is fixed at $init. Line numbers verified against origin/develop @ 8971094.

1. Route-scoped string middleware re-instantiated per request — stateful middleware silently reset (R15 / MA12, High)
vendor/wheels/Dispatch.cfc:9, :61, :298-313, :377-401 — global middleware is built once at $init ($buildMiddlewarePipeline), but route-scoped string middleware (the documented form) is re-instantiated via CreateObject("component", mw).init() per request, a new Pipeline is built per request, and regex routes also re-Duplicate instance middleware. Consequence: a route-scoped in-memory RateLimiter gets a fresh empty store each request and never enforces — any stateful middleware is silently reset.

2. $hasPreflightCapableMiddleware re-runs IsInstanceOf over the pipeline on every OPTIONS request (R19 / MA15, Low)
vendor/wheels/Dispatch.cfc:298, :393-401 — the IsInstanceOf scan over the middleware pipeline runs on every OPTIONS request, but the pipeline is fixed at $init, so the boolean is invariant.

Impact

• Route-scoped stateful middleware (the documented registration form) is non-functional: a per-route in-memory RateLimiter never accumulates counts and never enforces. This is a correctness bug masquerading as a perf cost and interacts with the feat(testing): add browserLoginAsHandler override for /_browser/login-as fixture #2832 init() gotcha and SecurityHeaders HSTS defaults.
• Per-request instantiation + Pipeline rebuild + regex-route Duplicate are avoidable allocations on the dispatch hot path.

Suggested approach

This needs a deliberate singleton-vs-per-request contract for middleware, not an autonomous hot-path edit:

• Decide and document whether route-scoped string middleware is cached (singleton) or per-request, including the stateful-middleware implications and migration notes (interacts with feat(testing): add browserLoginAsHandler override for /_browser/login-as fixture #2832 init() requirement and HSTS defaults).
• Cache resolved route-scoped middleware instances in application scope (cleared on reload); exclude middleware from the per-request route Duplicate.
• Compute the preflight-capable boolean once in $buildMiddlewarePipeline and cache it at $init.
• Benchmark the dispatch hot path before/after.

Acceptance criteria

• A route-scoped in-memory RateLimiter enforces across requests (state survives).
• Documented contract for middleware lifecycle (singleton vs per-request) with migration notes.
• Route-scoped instances cached in application scope, cleared on reload; no per-request Duplicate of middleware.
• Preflight-capability boolean computed once at $init.
• Middleware + dispatch specs green cross-engine; benchmark recorded.

Source

Internal multi-agent framework review 2026-06-09, wave 2 (issues phase). Findings: routing R15/R19, middleware-auth MA12/MA15.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable wrong behavior with a concrete reproducer: a route-scoped in-memory RateLimiter "gets a fresh empty store each request and never enforces." Verified line references against develop @ 8971094 — vendor/wheels/Dispatch.cfc:61 ($resolveMiddlewareInstance) does CreateObject("component", arguments.middleware).init() on each call, and $getRouteMiddleware / the per-request Pipeline rebuild at :377-401 invoke that resolver per request. The "deliberate contract" framing is the proposed remediation, not a design-open question — the underlying defect (state lost between requests) is reproducible in isolation.

Suspected layer

middleware — see CLAUDE.md § "Middleware Quick Reference" for the canonical middleware registration patterns (no dedicated .ai/wheels/middleware/ doc exists yet; the dispatch-layer middleware integration lives in vendor/wheels/Dispatch.cfc).

Fix sketch

Primary file is vendor/wheels/Dispatch.cfc. Cache resolved route-scoped middleware instances in application scope keyed by component path (cleared on reload via the existing reload path); exclude middleware from the per-request route Duplicate so instance middleware isn't deep-copied per request; precompute the preflight-capability boolean inside $buildMiddlewarePipeline and store on variables so $hasPreflightCapableMiddleware becomes a single struct read. Touches $resolveMiddlewareInstance (:55-65), $getRouteMiddleware (:393-401+), $hasPreflightCapableMiddleware (:298-313), and $buildMiddlewarePipeline (:9, :61). Likely also needs an entry-point invalidation hook on reload. Specs land under vendor/wheels/tests/specs/middleware/ and vendor/wheels/tests/specs/dispatch/.

Confidence: medium

Auto-downgraded: the fix sits in middleware-lifecycle code (vendor/wheels/middleware/** adjacent — Dispatch.cfc orchestrates the pipeline) and requires a singleton-vs-per-request contract decision that has documented migration implications (interacts with #2832 init() requirement and HSTS defaults per the report).

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

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2964

Spec: vendor/wheels/tests/specs/middleware/RouteMiddlewareLifecycleSpec.cfc — 5/6 cases errored before the fix (the 6th, $copyRouteForRequest middleware-preservation, was Lucee-7-only luck since Duplicate() happens to share CFC references inside arrays there but not on Adobe CF), all 6 pass after.

Implementation: vendor/wheels/Dispatch.cfc

What changed:

• Route-scoped string middleware is now resolved once and cached under application[$appKey()].$middlewareInstanceCache keyed by component path. State survives across requests (the documented RateLimiter registration form now actually enforces).
• $copyRouteForRequest shallow-copies the route's middleware array instead of Duplicate()-ing it so Adobe CF doesn't deep-clone the cached CFC instances.
• The preflight-capability boolean is computed once at $init and stored on the Dispatch instance — $hasPreflightCapableMiddleware() becomes a single struct read instead of an IsInstanceOf scan per OPTIONS request.
• The three internal helpers ($resolveMiddlewareInstance, $getRouteMiddleware, $hasPreflightCapableMiddleware) were promoted from private to public so the regression specs can address them directly. They keep the $-prefix internal-by-convention marker.
• Documents the singleton lifecycle contract: middleware components must be safe to share across concurrent requests. Every built-in middleware (RateLimiter, Cors, SecurityHeaders, RequestId, TenantResolver, AuthMiddleware, BrowserTestFixtureGuard) already satisfies it.

Local test results (Lucee 7 + SQLite):

• wheels.tests.specs.middleware: 183 pass / 0 fail / 0 error
• wheels.tests.specs.dispatch: 106 pass / 0 fail / 0 error

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.