In a web framework's middleware chain, what work belongs before the delegation call and what belongs after it returns?

## One body, two phases, one hinge An element in a wrapping middleware chain is a single function whose body is split by one delegation call. Everything above the call is the **before phase**, everything below it is the **after phase**, and the split is not a convention the framework enforces: it is just what has happened yet. Before the call, the remainder of the pipeline has not run. After it returns, the remainder has run to completion and handed back its result. That makes the choice of phase a question of availability rather than taste. Put work where the data it needs exists. ## What each phase can see | What you need | Before the call | After the call returns | |---|---|---| | Request line, headers, attributes | available | available, plus anything the inner chain attached | | Response status and headers | not produced yet | available; still changeable only if nothing has been sent | | Response body bytes | not produced yet | observable only if this element installed a wrapper beforehand | | Duration of the inner work | start the measurement here | finish the measurement here | | Whether the handler ran at all | unknown | inferable from the result | Two entries in that table are easy to get wrong. A metric labelled with the response status cannot be recorded before delegating, because the status does not exist; and the body cannot be inspected afterwards unless the element arranged to capture it on the way in, since by then the bytes have gone wherever they were being written. ## State that spans both phases The wrapping shape gives cross-phase state for free. A value the element computes before the call is an ordinary local variable, and it is still in scope after the call, because the element never left its own frame: ``` element(request, next): started = now() response = next(request) record_duration(now() - started, response.status) return response ``` This is one of the practical advantages of the wrapping model over a style with separate before and after callbacks, where the same measurement needs a shared per-request map keyed by something, plus cleanup so entries do not accumulate. Here the language's own scoping does the bookkeeping. ## The commit boundary A response becomes **committed** at the moment its first bytes reach the client: status line and headers are on the wire and cannot be recalled. A streaming handler may commit long before it finishes, so an after phase can easily find itself holding a response that is already partly delivered. Frameworks differ in how they react to a late header write: some raise an error, some log a warning and ignore it, some silently drop it. None of them can unsend bytes. The practical consequences: - Headers that **must** be present, such as security or caching headers, are set before delegating rather than after, so they are in place no matter when the inner work starts writing. - An element that genuinely needs to decide a header from the finished body has to buffer the response instead of letting it stream, which trades memory and time-to-first-byte for the ability to change its mind. - Read-only after-phase work, such as logging or metrics, is unaffected by commitment; only mutation is. ## Typical phase assignments 1. **Attach a correlation value** to the request: before, so everything inside can use it. 2. **Validate or normalise** what the handler will read: before, because afterwards the handler has already read it. 3. **Start a span or timer**: before; **end it**: after, using the local variable captured on the way in. 4. **Write the access log line**: after, since the status and byte count only exist then. 5. **Release a resource acquired for the inner work**: after, and never before, or the handler loses it mid-use. ## Where this goes wrong - Reading the status in the before phase and reporting a default value for every request, which looks like a working metric until someone notices every response is the same. - Calling a before-phase log line an access log, so failures never appear in it because the line is written whether or not the request was served. - Setting a header after the call on a streaming endpoint and only seeing it on small responses, because the small ones had not committed yet. - Assuming the after phase is a separate invocation of the element and re-reading the request from scratch instead of using the state already captured. One more caveat sits deliberately outside this topic: whether the after phase runs at all when the inner work fails, and how that failure travels outward, is governed by its own rules. The phase split described here is the normal path, where the delegation call returns a response.