go-middleware

Go HTTP Middleware

Quick Reference

Topic	Reference
Context keys, request IDs, user metadata	references/context-propagation.md
slog setup, logging middleware, child loggers	references/structured-logging.md
AppHandler pattern, domain errors, recovery	references/error-handling-middleware.md

Middleware Signature

All middleware follows the standard func(http.Handler) http.Handler pattern. This is the composable building block for cross-cutting concerns in Go HTTP servers.

// Standard middleware signature
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.New().String()
        }
        ctx := context.WithValue(r.Context(), requestIDKey, id)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// Type-safe context keys
type contextKey string
const requestIDKey contextKey = "request_id"

func RequestIDFromContext(ctx context.Context) string {
    id, _ := ctx.Value(requestIDKey).(string)
    return id
}

Key points:

• Accept http.Handler, return http.Handler -- always
• Call next.ServeHTTP(w, r) to pass control to the next handler
• Work before the call (pre-processing) or after (post-processing) or both
• Use r.WithContext(ctx) to propagate new context values downstream

Context Propagation

Use context.WithValue for request-scoped data that crosses API boundaries (request IDs, authenticated users, tenant IDs). Always use typed keys to avoid collisions.

type contextKey string

const (
    requestIDKey contextKey = "request_id"
    userKey      contextKey = "user"
)

Provide typed helper functions for extraction:

func RequestIDFromContext(ctx context.Context) string {
    id, _ := ctx.Value(requestIDKey).(string)
    return id
}