Middleware Chains & Request Context

Middleware wraps http.Handler to run cross-cutting logic before and after your route handlers.

Request-scoped metadata flows through r.Context() using typed, unexported context keys.

Summary

A middleware function accepts an inner handler and returns a new handler that delegates to it.

Chains nest wrappers: the outermost middleware sees the request first and the response last.

r.Context() is the standard carrier for cancellation, deadlines, and request metadata.

Use r.WithContext to attach values immutably; never mutate the request in place without cloning.

Libraries like chi provide Use helpers, but the underlying model is identical to stdlib composition.

Recipe

Quick-reference recipe card - copy-paste ready.

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
}
 
func requestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-ID")
        if id == "" {
            id = uuid.NewString()
        }
        ctx := context.WithValue(r.Context(), reqIDKey{}, id)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

When to reach for this:

• Adding logging, auth, metrics, and recovery uniformly across routes.
• Propagating request IDs and principal info to downstream calls.
• Building framework-free services that still need cross-cutting concerns.

Working Example

package main
 
import (
    "context"
    "log"
    "net/http"
    "time"
)
 
type ctxKey int
 
const userKey ctxKey = 1
 
type statusWriter struct {
    http.ResponseWriter
    code int
}
 
func (w *statusWriter) WriteHeader(code int) {
    w.code = code
    w.ResponseWriter.WriteHeader(code)
}
 
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
}
 
func recoverer(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if v := recover(); v != nil {
                log.Printf("panic: %v", v)
                http.Error(w, "internal error", http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}
 
func authenticate(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        ctx := context.WithValue(r.Context(), userKey, "demo-user")
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}
 
func accessLog(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        sw := &statusWriter{ResponseWriter: w, code: http.StatusOK}
        start := time.Now()
        next.ServeHTTP(sw, r)
        log.Printf("%s %s %d %s", r.Method, r.URL.Path, sw.code, time.Since(start))
    })
}
 
func userFrom(ctx context.Context) (string, bool) {
    u, ok := ctx.Value(userKey).(string)
    return u, ok
}
 
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /me", func(w http.ResponseWriter, r *http.Request) {
        user, ok := userFrom(r.Context())
        if !ok {
            http.Error(w, "no user", http.StatusInternalServerError)
            return
        }
        w.Write([]byte(user))
    })
 
    handler := chain(mux, recoverer, authenticate, accessLog)
    http.ListenAndServe(":8080", handler)
}

What this demonstrates:

• Explicit middleware chain construction order.
• Auth middleware short-circuits with 401 before inner handlers run.
• Typed private context key for user identity.
• statusWriter wrapper capturing HTTP status for logs.
• Panic recovery at the outermost layer.

Deep Dive

How It Works

• Each middleware returns a new http.Handler closure over the inner handler.
• Short-circuiting skips inner handlers by returning early without calling next.ServeHTTP.
• r.WithContext returns a shallow copy of the request with a new context tree.
• Downstream code reads values with typed accessors, not raw string keys.

Middleware Ordering

Request -->
  recoverer -->
    authenticate -->
      accessLog -->
        mux / business handler
Response <--

Outer middleware should include recovery and tracing; auth sits inside recovery but outside business logic.

Go Notes

// chi equivalent (stdlib handlers underneath):
// r.Use(middleware.Recoverer, middleware.RequestID)
// r.Get("/me", handler)
 
// Prefer accessors:
func User(ctx context.Context) (string, bool) {
    u, ok := ctx.Value(userKey).(string)
    return u, ok
}

Context Value Rules

Gotchas

• Wrong middleware order - Logging inside auth may leak unauthenticated paths; recovery must be outermost. Fix: Document order: recover -> trace -> auth -> log -> routes.
• String context keys - Collide across packages silently. Fix: Use private type ctxKey int constants.
• Storing request in context - Creates circular references and confuses lifetimes. Fix: Store only the few values handlers need.
• Mutating r.URL without Clone - Race when middleware shares requests. Fix: Use r.Clone(ctx) when altering URL or headers for sub-routers.
• Forgetting to call next.ServeHTTP - Silently drops requests. Fix: Lint or test middleware with httptest asserting body reached.
• Passing context.Background() downstream - Loses cancel on client disconnect. Fix: Start from r.Context() for all child contexts.

Alternatives

FAQs

Related

• HTTP Servers, Handlers & ServeMux Patterns - mount wrapped mux
• Cancellation Propagation in HTTP Handlers - ctx propagation
• Context Values: When and When Not - value rules
• Middleware & Decorator Patterns - general pattern
• net/http Basics - simple logging middleware

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).