Wrapping ResponseWriter

## Two method sets, one substitution `net/http` hands a handler a value whose concrete type implements far more than the `http.ResponseWriter` interface says. That extra behaviour is exposed as **optional interfaces**, discovered by asserting on the value at runtime: - `http.Flusher` — a `Flush()` method. - `http.Hijacker` — a `Hijack()` method returning the raw connection. - `io.ReaderFrom` — a `ReadFrom(io.Reader)` method the standard library uses as a fast write path. When middleware wraps the writer, the handler no longer holds `net/http`'s value; it holds yours. And a struct that embeds an **interface** gets exactly the methods that interface declares — three of them — promoted onto its own method set. `*recorder` therefore does not implement `http.Flusher`, no matter what the value stored inside it can do. ## Why it is silent Capability detection in Go is the comma-ok assertion: ```go if f, ok := w.(http.Flusher); ok { f.Flush() } ``` That is deliberately non-fatal — the whole point is to work with writers that lack the capability. So a wrapper inserted anywhere in the chain turns a working code path into a skipped one with no error, no log line and no compile failure. This is the single most common regression caused by response-writer middleware, and it is why reviewers treat a new wrapper as a behavioural change rather than a cosmetic one. Note the direction of the damage: the wrapper does not *break* the underlying writer, which is still perfectly capable. It hides it. ## The Unwrap convention and http.ResponseController The standard library's answer is `http.ResponseController`. A caller writes: ```go rc := http.NewResponseController(w) err := rc.SetWriteDeadline(time.Now().Add(30 * time.Second)) ``` `ResponseController` exposes the optional operations as ordinary methods that return an `error`. To find something able to perform each one, it inspects the writer it was given and, if that writer cannot do the job, looks for a method: ```go Unwrap() http.ResponseWriter ``` and repeats on whatever comes back. So a middleware wrapper's obligation is one line: ```go func (r *recorder) Unwrap() http.ResponseWriter { return r.ResponseWriter } ``` With that in place, any number of wrappers can be stacked and a caller using `ResponseController` still reaches a writer that can serve the request. If nothing in the chain can, the method returns an error matching `http.ErrNotSupported` — an explicit failure the caller can log or convert into a 500, instead of a silently skipped branch. Handle that error; do not discard it. ## What Unwrap does *not* do This is the part candidates most often get wrong. `Unwrap` is a convention that `ResponseController` knows about. It does **not** change your wrapper's method set, so a handler doing a direct `w.(http.Flusher)` assertion still fails. Implementing `Unwrap` fixes the callers who migrate to `ResponseController`; it does nothing for code you did not change, including library code you import and cannot edit. Nor does `ResponseController` cover every optional interface — it has no method for `io.ReaderFrom`, so a wrapper that wants to keep that fast path has to declare `ReadFrom` itself. ## Forwarding by hand, and why it gets ugly The alternative is to declare the extra methods on the wrapper so its own type satisfies the interfaces again. That restores direct assertions, but two problems follow. First, **it can lie**. If the wrapper unconditionally declares `Hijack`, every probe now succeeds even when the writer underneath cannot hijack — for example on an HTTP/2 connection — and a compile-time-looking capability check becomes a runtime error deep inside a handler. Forwarding honestly means constructing a wrapper whose type matches the exact capability set of the writer it wraps, which is a switch over every combination of the interfaces you care about: two interfaces mean four types, three mean eight. That is why such code is usually generated rather than written. Second, **it is a moving target**. Each optional interface added to `net/http` is one more combination to handle, whereas an `Unwrap` method keeps working. ## What to do in practice Always implement `Unwrap` — it costs one line and has no downside. Point handlers you control at `http.ResponseController` and handle its error. Only if you must keep unmigrated or third-party handlers working do you take on exact-capability forwarding, and then you write it once, in the shared layer, with tests that assert the wrapper's capability set equals the wrapped writer's rather than a fixed list.