In a web framework's middleware chain, what does each element wrap, and what must it do for the request to continue?

## The chain is composed, not iterated Most people first picture a middleware chain as a list the framework walks: run element one, then element two, then the handler. The model server-side web frameworks actually use is **composition**. When the application starts, the pipeline is assembled from the inside out: the terminal step, usually the route handler that produces the response, is wrapped by the innermost element; that combined thing is wrapped by the element outside it; and so on until the outermost element encloses everything else. What arrives at an element at request time is therefore a **single callable that already represents the entire remainder of the pipeline**, collapsed into one invocation. It is commonly called `next`, or described as *the rest of the chain*. Three consequences follow immediately: - An element cannot tell how many elements remain or what they are. It holds one callable and gets back one result. - Control moves **inward** only through calls and **outward** only through returns. Nothing advances on its own. - While the innermost handler runs, every element that delegated is still live, suspended in the middle of its own body, waiting for its call to come back. ## The shape of one element ``` element(request, next): # before phase - only the request exists started = now() response = next(request) # the delegation call # after phase - the response exists response.header("x-elapsed", now() - started) return response ``` The body has exactly three regions, and the delegation call is the hinge between them: 1. **Before phase** - the request is in hand and nothing has been produced yet. 2. **The delegation call** - the request moves inward, and this element waits for the remainder to finish. 3. **After phase** - the value returned is the response produced by everything inside, and this element may inspect it before handing it outward. Returning that value matters as much as making the call: what an element returns is what its own enclosing element receives. An element that makes the call but discards the result has broken the chain just as surely as one that never called at all. ## Why the onion picture is accurate The difference between a flat callback list and a wrapping chain is not cosmetic; it changes what a single element can do. | Question | Flat list of callbacks | Wrapping chain | |---|---|---| | Who advances the request? | the framework, after each callback returns | the element itself, by invoking the callable it holds | | Can one step see the response? | only if a separate outbound callback exists | yes, it is the return value of its own call | | Where does state between the two phases live? | in a shared per-request bag | in the element's own local variables | | What does a bug look like? | a forgotten flag or a wrong return value | a forgotten call | The wrapping form is why a single element can bracket the whole remainder with a timer, a trace span, or a resource that must be released afterwards. All of that is ordinary code around one call. ## What explicit delegation buys, and what it costs Because the call is a statement the author writes, an element can: - **Bracket** everything inside it, measuring or tagging the inner work from both sides. - **Wrap** what it passes down, handing the remainder an adjusted request or a response object whose writes it can observe. - **Decide** whether to make the call at all, and in rare, deliberate cases more than once. The same property is the cost. Passing the request on is one statement, so any branch that returns without it removes the rest of the pipeline and the handler from that request: an early return in a validation guard, a conditional whose other branch was only meant to log, a refactoring that moved the call into a helper which is not always reached. Reviewers of pipeline code look for the delegation call on every path before they look at anything else, and an element with several exit paths deserves a test per path. ## What the wrapping model does not decide The model answers one question, *what does an element hold and how does the request advance*, and leaves others open on purpose. Which element ends up outside which, what happens when something inside throws, and where the chain sits relative to route matching are separate concerns with their own rules. Keeping them apart is useful when debugging: **did it run at all** is a question about delegation, while **did it run early enough** is a question about arrangement. ## The same shape under different execution models In a thread-per-request style, the delegation call blocks until the inner work is finished, so the three regions read straight down the page. In non-blocking styles the call may hand back a pending result immediately, and the after phase has to be attached to that result's completion rather than written as the next statement. The wrapping shape is identical in both; only the meaning of *after the call returns* changes.