In a middleware chain, why do after-phases run in reverse registration order, and which hook touches the response last?

## Two directions through one list A middleware chain is traversed twice per request. Inbound, control travels from the outermost hook to the innermost and finally into the route handler. Outbound, it travels the same path backwards. Only one list exists, and the second direction is not configured anywhere — it is a consequence of how the first direction works. The reason is that delegation is a **call**, not a handoff. When a hook passes control to the rest of the chain, it does not end; it is sitting in the middle of its own execution, waiting for that call to return. Everything nested inside it must finish before it resumes. When it does resume, the response exists, and whatever the hook does from that point is its **after-phase**. ## Why reversal is forced, not chosen Because each layer resumes only after everything inside it has returned, the last layer to be entered is the first to resume, and the first layer entered is the last. Hooks therefore finish in strict reverse order of entry: - registered **first** → entered first → resumes **last** → sees the most finished response; - registered **last** → entered last → resumes **first** → sees the response closest to the handler, before any outer hook has touched it; - the **handler** sits innermost, produces the response, and has no after-phase of this kind at all. ## What each position can and cannot do | Registered | Inbound | Outbound | Sees a response that | |---|---|---|---| | early (outermost) | runs first | runs last | every inner hook has already transformed | | late (innermost hook) | runs last before the handler | runs first | the handler just produced, untouched by others | | the handler | runs last | n/a | it created itself | The practical reading of that table is a rule of thumb: **to observe something, be inside it; to wrap something, be outside it.** A hook that needs the raw handler output registers late. A hook that needs the finished article registers early. ## Consequences worth naming - **Total-duration timing belongs outermost.** A timer registered early brackets every other hook plus the handler; registered late it measures only the part of the pipeline nested inside it. - **Response-body transformation belongs outermost.** A hook that re-encodes or compresses the outgoing body must run after every hook that might still append to it, which means being registered first among them. If it sits deep in the chain, an outer hook can append content after the transformation has already happened, producing a body that no longer matches its declared encoding or length. - **A header added on the way out is added by whoever resumes.** Two hooks both writing the same response header will fight, and the outermost one writes last — which usually means it wins, though frameworks differ on whether a second write replaces or appends. - **Commit is a hard boundary.** Once the first bytes of the response have been flushed, the status line and headers are already on the wire. After-phases nested outside that point may still run, but attempts to change status or headers are silently ignored or raise — so an outer hook that intends to rewrite headers must ensure nothing inside it has committed early. ## The mistake this produces in practice The reversal is easy to state and easy to forget under pressure. The usual failure is reasoning about a pipeline in one direction only: someone adds a hook at the end of the registration list because the concern feels like a finishing touch, and is then surprised that it sees a partially built response rather than the final one. The fix is not to add it later still — there is no 'later' that gets you outward — but to register it **earlier** so it becomes an outer layer. The symmetrical mistake also exists: registering something first because it feels important, when what it actually needed was to be inside another hook in order to see that hook's inbound work applied to the response. ## How to reason about it quickly 1. Write the registration list top to bottom; that is the inbound order. 2. Read the same list bottom to top; that is the outbound order. 3. For each hook, ask which of the two phases carries its real work, and place it accordingly — outermost when the work is on the way out, innermost when the work depends on how far inbound processing has already got.