There's a moment in every Wheels app where you realise the thing you need doesn't belong in a controller. Timing every request and stamping the duration in a header. Denying traffic during a deploy window before any controller runs. Auditing every admin action without copy-pasting a beforeFilter into a dozen controllers. None of those is about a specific resource — they're about the request itself, the layer below your actions.

That layer is middleware, and in 4.0 you can write your own. This post is a companion to the earlier rate-limiting walkthrough — that one covered consuming the built-in RateLimiter; this one is authoring middleware from scratch.

Read: https://blog.wheels.dev/posts/writing-custom-middleware-wheels-4

What the post covers

The surface is genuinely small, which is the appeal:

• The one-method contract. Every middleware does component implements="wheels.middleware.MiddlewareInterface" and writes a single method: public string function handle(required struct request, required any next). No base component, no lifecycle hooks. Code before you call next() runs on the way in; code after runs on the way out; you return the string next() gave you (optionally after mutating headers).

• next is a closure. Calling next(request) runs the rest of the pipeline — every downstream middleware plus the controller — and returns the response as a string.

• request is not the CFML request scope. It's a plain struct Dispatch builds: {params, route, pathInfo, method}. This creates the single sharpest edge in the API — on Adobe CF the request parameter shadows the engine request scope, so a bare request.wheels.x = ... inside handle writes your passed struct, not the scope. The built-in RequestId works around it with a helper that has no request parameter.

The part that actually matters: the lifecycle

The reason the post exists is one rule: every middleware instance is a singleton, shared across every concurrent request, for the entire application lifetime. Global middleware is resolved once at Dispatch init; route-scoped string middleware is cached after first encounter. The same instance handles request #1 and request #50,000 — concurrently.

That makes thread-safety mandatory the moment you keep mutable state. The post builds an audit-logger whose request counter is mutated only inside a cflock, mirroring how the built-in RateLimiter backs its store with a ConcurrentHashMap and locks every read-modify-write. Per-request data goes in local or on the request struct — never on the instance.

Three worked components

1. RequestTiming — stamps an X-Response-Time header, with the flush-safe try/catch around cfheader that every built-in uses.
2. AuditLog — thread-safe, cflock-guarded counter; also shows why a string-registered middleware needs an init() that returns this (the resolver calls CreateObject(path).init() on string entries).
3. MaintenanceMode — returns a 503 body without calling next(), short-circuiting the controller during a deploy. Same technique RateLimiter (429) and Cors (OPTIONS preflight) use.

Registration

Both paths, and how they compose:

• Global — set(middleware=[...]) in config/settings.cfm. Array order = execution order, outermost-to-innermost. Entries can be object instances (new wheels.middleware.Cors(...), used as-is) or string paths ("app.middleware.RequestTiming", instantiated + cached).
• Route-scoped — .scope(path="/admin", middleware=[...]) in config/routes.cfm. Accepts an array or a comma-string; nested scopes inherit the parent's middleware (parent runs first).
• The fixed order: global always runs before route-scoped.

Discussion

A few things I'd genuinely like to hear from people on:

• Have you hit the request-scope-shadowing bug on Adobe CF? Did the helper-with-no-request-param workaround feel obvious, or is there a cleaner pattern you've used?
• What custom middleware have you actually shipped? The "auth before any controller" and "per-tenant resolution" cases seem common — curious what else people are putting in this layer.
• Anyone been bitten by the singleton lifecycle — stashing per-request state on the instance and watching it leak across requests under load?

Read the full post: https://blog.wheels.dev/posts/writing-custom-middleware-wheels-4