Middleware and Handler Chaining

Every handler in the service starts the same way: note the start time, recover from panics, stamp a request id, check auth. Someone writes those lines in twenty handlers, gets them slightly different in three of them, and the day a panic happens inside the auth check of handler #17, it takes down the connection with no log line.

The fix is to notice the shape of the duplication: wrap the handler, run something before it, run something after it, and return a handler. That shape has a name and a type:

func Logging(log *slog.Logger) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			start := time.Now()
			sw := &statusWriter{ResponseWriter: w, status: http.StatusOK}

			next.ServeHTTP(sw, r)

			log.InfoContext(r.Context(), "request",
				"method", r.Method,
				"path", r.URL.Path,
				"status", sw.status,
				"dur", time.Since(start),
			)
		})
	}
}

type statusWriter struct {
	http.ResponseWriter
	status int
}

func (w *statusWriter) WriteHeader(code int) {
	w.status = code
	w.ResponseWriter.WriteHeader(code)
}

Read the outer function as configuration: Logging(log) runs once at wiring time and closes over the logger; the returned function does the wrapping. You get one logger per middleware instead of a global, and tests construct the same middleware with a test logger.

The statusWriter exists because the handler writes through your wrapper, not the raw writer — without overriding WriteHeader every log would say 200 regardless of what happened. One caveat the override exposes: handlers that stream (SSE), hijack connections, or push resources check for http.Flusher, http.Hijacker, or http.Pusher on the writer. An embedded http.ResponseWriter alone fails those assertions, and the handler silently loses the capability. For those endpoints, forward the optional interfaces explicitly or use http.NewResponseController(w).Flush() from inside the handler, which abstracts the lookup.

The middleware contract composes because it speaks http.Handler end to end — the same interface the server mounts and the mux routes (Interfaces and Method Sets). Nothing about logging knows it is sitting in front of users, and nothing about auth knows there is a logger behind it. What decides whether the whole stack behaves is the order the layers wrap each other, which is where subtle production bugs live.

A team writes the stack like this and argues for an hour about why request ids are missing from panic logs:

h := routes()
h = Authentication(h)
h = RequestID(h)
h = Logging(h)

The mental model that ends the argument: the last middleware applied is the outermost layer — the first to see the request, the last to see the response. Draw it as an onion:

request -> Logging -> RequestID -> Authentication -> routes() -> response

Each arrow down runs before the handler; each arrow back up runs after. The code above gives you exactly that sequence, because Logging wraps everything wrapped so far. A declarative chain function makes the intent readable instead of assembled by hand:

func chain(h http.Handler, mws ...func(http.Handler) http.Handler) http.Handler {
	for i := len(mws) - 1; i >= 0; i-- {
		h = mws[i](h)
	}
	return h
}

// chain(routes(), Logging(log), Recovery(log), Authentication(validator))
// runs: Logging -> Recovery -> Authentication -> routes

With mws listed outside-in, the loop wraps right to left so the first listed layer ends up outermost. Now order is data you review in one line, not a sequence of assignments to re-derive.

Ordering rules worth committing to:

• Logging outermost (or nearly). It measures the full duration and observes the final status — including whatever the recovery layer decided. Logging inside recovery misses the panic response; logging inside auth skips unauthenticated traffic you may still want to count.
• Recovery just inside logging. It must wrap handlers and middleware that can panic, so place it before anything risky runs. A panic caught here becomes a clean 500; a panic with no recovery lets net/http handle it — the server logs to stderr and closes the connection with no response, so the client sees an empty reply and your structured logs see nothing.
• Auth before anything that uses the identity, outside anything that should run for anonymous traffic. Health checks and metrics endpoints often bypass auth entirely — mounting them on a separate branch of the mux is cleaner than an if path == "/healthz" escape hatch inside the middleware.

Two composition mistakes surface in review. Reusing a middleware instance per request (holding request-scoped state in the closure) races when the same stack serves concurrent requests — closure state is configuration, request state belongs in the *http.Request. And calling chain inside a handler instead of at wiring time re-creates every layer per request, throwing away the configuration step that made the pattern cheap.

Authentication middleware validates the token and now needs to tell handlers who the caller is. The tempting refactor: change every handler to func(w, r, user User). It violates the http.HandlerFunc contract the mux requires, ripples through every route, and forces each layer in between to carry a parameter it does not use.

Go's established answer: store the identity on the request's context. The context travels with *http.Request, requires no signature change, and dies with the request — no pooling, no cleanup.

package auth // unexported key: nobody outside can forge it

type ctxKey struct{}

type Principal struct {
	UserID int64
	Roles  []string
}

func Middleware(verify func(token string) (Principal, error)) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			tok := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
			p, err := verify(tok)
			if err != nil {
				http.Error(w, "unauthorized", http.StatusUnauthorized)
				return
			}
			ctx := context.WithValue(r.Context(), ctxKey{}, p)
			next.ServeHTTP(w, r.WithContext(ctx))
		})
	}
}

func PrincipalFrom(ctx context.Context) (Principal, bool) {
	p, ok := ctx.Value(ctxKey{}).(Principal)
	return p, ok
}

// in a handler
func handleDelete(w http.ResponseWriter, r *http.Request) {
	p, ok := auth.PrincipalFrom(r.Context())
	if !ok { // defensive: this route is mounted behind auth
		http.Error(w, "unauthorized", http.StatusUnauthorized)
		return
	}
	if !p.Can("orders:delete") {
		http.Error(w, "forbidden", http.StatusForbidden)
		return
	}
	// ...
}

The unexported ctxKey struct{} is the detail that prevents an entire bug class. Context keys compare by interface equality: if keys were exported strings like "user", any package — or any dependency's package — using the same string would overwrite or read your identity. A zero-size unexported struct type is forgeable only inside auth, so collisions cannot compile.

Three rules keep context honest. Values go in with r.WithContext(ctx) — never mutate r.Context() in place; the request value is what handlers downstream receive. Only cross-cutting, request-scoped data belongs there (identity, request id, trace id); business inputs travel as explicit parameters, because a context lookup hides a function's real dependencies (Context and Cancellation). And readers always handle the missing case — a route mounted outside the auth branch gets ok == false, which is a 401, not a panic.

With identity flowing, the last layer to place is the one that protects the whole stack from its own bugs: recovery and timeouts as middleware, not scattered defers.

A handler panics on a nil map read at 3 a.m. What each layer does next decides whether the incident is a log line or a support ticket.

Without recovery, net/http catches the panic at the connection goroutine: it logs the stack to stderr and closes the connection without writing a status. The client gets an empty response or a reset; your structured logs, metrics, and tracing see nothing, because the panic never became an event in your system. The recovery middleware turns it into all three — a 500 to the client, an error log with stack, a metrics increment:

func Recovery(log *slog.Logger) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			defer func() {
				if rec := recover(); rec != nil {
					log.ErrorContext(r.Context(), "panic recovered",
						"err", rec,
						"path", r.URL.Path,
						"stack", string(debug.Stack()),
					)
					http.Error(w, "internal error", http.StatusInternalServerError)
				}
			}()
			next.ServeHTTP(w, r)
		})
	}
}

One honesty note: if the handler already wrote the response header before panicking, http.Error cannot change the status — Go prints a superfluous WriteHeader warning and the client still sees the partial body. Recovery cannot un-write bytes; it can only ensure the stack is logged and the connection does not silently die. That is still the difference between debugging and guessing.

Timeouts follow the same logic. http.TimeoutHandler wraps a handler with a wall-clock limit and answers 503 when it fires, but it buffers the response — bad for streaming endpoints — and it does not cancel the handler's work; the database query keeps running after the client got 503. Prefer propagating a deadline through r.Context(): the server's read/write timeouts bound the connection, the handler passes r.Context() into every downstream call, and a cancelled context actually stops the work. Middleware's job is setting the deadline; context's job is honoring it.

Assemble the full stack in one reviewable line — chain(routes(), RequestID, Logging, Recovery, Timeouts, Authentication) — then take the same composition to tests: each layer is independently exercisable with httptest, and a regression in ordering shows up as a failing assertion rather than a Friday surprise (Testing Handlers with httptest).