Global vs Per-Route Hooks

A hook — the words *middleware*, *filter* and *interceptor* all name the same idea in different framework families — is code that wraps request handling: it can inspect or change the request on the way in, delegate to the rest of the chain, and inspect or change the response on the way out. **Scope** is a separate axis from what the hook does. Scope answers only this: *for which requests does the framework splice this hook into the chain at all?* ## The three attachment scopes - **Global (application-wide).** Registered against the server or the application object rather than against any route. Every request the server accepts passes through it, whatever it is addressed to. - **Group, prefix or subtree.** Registered against a named collection of routes — a group object, a mounted sub-router, or everything under a path prefix. It runs for a request only if the route that matched belongs to that collection. - **Per-route.** Registered in the declaration of one route, alongside its handler. It runs only when that one route is the match. Most frameworks offer at least the global and the per-route form; the middle form is the one whose shape varies most, and in some frameworks the group is a real object you register routes into, while in others it is a path-pattern filter applied at request time. ## What scope changes | Question | Global | Group / prefix | Per-route | |---|---|---|---| | Runs for a request matching **no** route? | Yes, if attached before routing | No | No | | Runs for a route added **later** by someone else? | Yes | Yes, if added inside the group | No | | Default if a developer forgets it | Protected (opt-out) | Protected inside the group | Unprotected (opt-in) | | Visible in the route declaration | No | Only at the group declaration | Yes, next to the handler | | Cost when it should not apply | Paid on every request | Paid inside the subtree | Not paid | ## The default is the real difference The two forms are not interchangeable ways of saying the same thing, because they fail in opposite directions. With a global registration, adding a new route inherits the hook: the failure mode is a hook running where it was not wanted — a wasted lookup, an unwanted header, a body read that a streaming endpoint did not want. With a per-route registration, adding a new route inherits nothing: the failure mode is a hook *not* running where it was needed, and if that hook was authentication, the new endpoint is simply open. That asymmetry is why the usual advice is to attach anything that enforces a policy at the widest scope that policy covers, and to carve out the exceptions explicitly, rather than to opt each route in one at a time. Conversely, anything that is genuinely specific to one handler — parsing one endpoint's unusual body format, a cache policy that only one resource has — belongs on that route, where a reader of the route sees it. ## Scoping by checking the path inside a global hook A third option exists and is worth naming because candidates often propose it: register one global hook and have it inspect the request path itself, doing nothing when the path does not interest it. This is sometimes the right tool, but it is not equivalent to real scoping: 1. It usually runs **before routing**, so it compares a raw request path string, not the route that the router would have chosen. Trailing slashes, percent-encoding, case and duplicate separators are its problem now. 2. The scope becomes invisible: nothing in the route declarations says that this hook applies here and not there, so the only way to answer "what runs for this endpoint?" is to read the hook's body. 3. It still pays the cost of being invoked on every request, even if that cost is only a comparison. ## Choosing in practice - Put **policy** hooks — authentication, request-size limits, correlation identifiers — at the widest scope the policy covers. - Put **subtree** concerns on the group: everything under an administrative or internal subtree, for instance, shares a hook that nothing else should get. - Put **handler-specific** behaviour on the route, where the next reader of that route will see it. - Prefer moving a route into a differently-scoped group over adding a condition inside a hook: the group is declarative and greppable, the condition is not.