Decorator Pattern — Senior¶

1. The architectural question¶

Junior taught the shape — wrap an object that implements interface I in another object that also implements I, do work around the delegated call. Middle taught the chain — ordering invariants, recovery, stateful decorators, the price of allocation. Senior is what happens when a decorator stops being a local convenience and becomes a load-bearing piece of the system.

The day your http.Handler middleware ships in v1.0.0 of an open-source library, every downstream consumer's chain order depends on it. The day your gRPC UnaryServerInterceptor ships in grpc-go-middleware, its semantics get baked into hundreds of production services. The day your Tracer decorator on database/sql panics on a particular driver, your customers' incident channels light up.

The senior-level forces:

1. Distributed decorators — interceptors in gRPC, sidecar filters in service meshes, server-scoped vs request-scoped wrappers. The middleware that runs on every RPC across forty services.
2. Library design — publishing decorators that downstream consumers will compose into chains you don't control. Backwards-compatible evolution of decorator APIs.
3. Contract enforcement — Liskov for decorator chains: the chain must behave like the inner. Decorators that silently change semantics (swallow errors, mutate ctx values, drop deadlines) are the source of half the production incidents in microservice fleets.
4. Concurrency and lifecycle — decorators that hold goroutines, request-scoped goroutines that outlive the request, leak prevention.
5. Performance at scale — PGO devirtualization of decorator chains, allocation hotspots in middleware setup, inlining limits, escape analysis at the boundary.
6. Cross-cutting observability — OpenTelemetry's otelhttp and otelgrpc are decorators. So are Prometheus collectors. So are Datadog tracers. The composition of three vendors' decorators on one handler is a real situation.
7. Anti-pattern resistance — decorator soup (twenty layers, none of which can be removed because nobody knows why they're there), hidden state, ordering accidents.

This file walks the senior-level shape of all of it. Sections 3-7 cover distributed decorators and middleware libraries. Sections 8-10 cover gRPC interceptors and OpenTelemetry. Sections 11-13 cover library design and contract testing. Sections 14-17 cover concurrency, performance, anti-patterns. Section 18 is postmortems. The rest is cross-language comparison, mistakes, questions, and reference material.

2. Table of Contents¶

1. The architectural question
2. Table of Contents
3. Distributed decorators: the picture from 30,000 feet
4. Request-scoped vs server-scoped decorators
5. Middleware libraries in the Go ecosystem
6. chi, gorilla/mux, echo, gin: same idea, different ergonomics
7. gRPC unary and stream interceptors
8. OpenTelemetry: otelhttp and otelgrpc as decorators
9. Sidecar patterns: decorators that live in another process
10. Resilience decorators: gobreaker, rate.Limiter, hystrix-go
11. Library design: publishing decorators for downstream consumers
12. Decorator API evolution across major versions
13. Liskov and contract testing for decorator chains
14. Concurrency: decorators that hold goroutines, leak prevention
15. Performance at scale: PGO, devirtualization, allocation hotspots
16. Anti-patterns: decorator soup, hidden state, ordering accidents
17. Profiling and debugging decorator chains in production
18. Postmortems
19. Cross-language comparison
20. Common senior-level mistakes
21. Tricky questions
22. Cheat sheet
23. Further reading

3. Distributed decorators: the picture from 30,000 feet¶

A request in a modern microservice fleet passes through dozens of decorators before any business logic runs. Most of them are invisible to application code — they're attached by frameworks, libraries, or infrastructure.

Trace one HTTP request entering a service and the decorator chain looks like this:

Each box is a decorator. Each box satisfies the same interface as the box it wraps:

• The edge proxy is an http.Handler that wraps another http.Handler (the upstream).
• The mesh sidecar is an L7 proxy that wraps the application; from the application's perspective it's transparent.
• Inside the process, every middleware is a func(http.Handler) http.Handler.
• Inside the gRPC client, every interceptor is a grpc.UnaryClientInterceptor.
• The retry and circuit-breaker wrappers are grpc.UnaryClientInterceptor too, sitting between the application code and the actual transport.

The architectural payoff: each concern (tracing, metrics, retry, recovery, auth) is one layer, owned by one team, swappable in isolation. The application code is func(ctx context.Context, req *Request) (*Response, error) — and stays that way no matter how many cross-cutting concerns the platform team adds.

The architectural risk: each layer has a contract that nobody documented. Reorder them and behaviour changes in non-obvious ways. Remove one and the system seems to keep working until the next incident, at which point you discover the recovery middleware was the only thing keeping panics from killing the process.

3.1 The "decorator stack" as system architecture¶

A useful mental model: the decorator stack is the system, viewed from the request's perspective. Application code is the innermost 5% of what runs. The other 95% is infrastructure decorators.

HTTP request
  → TLS termination          (5 μs)
  → HTTP/2 framing           (2 μs)
  → Mesh sidecar policies    (200 μs)
  → Tracing span start       (1 μs)
  → Metrics counter inc      (50 ns)
  → Panic recovery defer     (~0 ns until panic)
  → Auth (JWT validate)      (50 μs)
  → Rate limit check         (200 ns)
  → Request validation       (5 μs)
  → Handler                  (10 ms) ← business logic
  → Tracing span end         (1 μs)
  → Metrics histogram obs    (200 ns)
  → Response serialization   (5 μs)

The handler is two orders of magnitude more expensive than any single decorator, so the decorator overhead is invisible — until you have ten of them, or one of them does network I/O it shouldn't, or one of them allocates per-request when it shouldn't, or the auth decorator decides to hit Redis instead of using a JWT.

3.2 The "interceptor" terminology¶

Different libraries use different words for the same idea:

They're all the same pattern. The naming reflects the ecosystem's history (Java's "servlet filter" came from the Servlet API; gRPC's "interceptor" came from the original gRPC C++ codebase). When reading any cloud-native Go codebase, treat all of these as "decorator" and apply the same reasoning.

4. Request-scoped vs server-scoped decorators¶

A core distinction that determines lifecycle, state ownership, and concurrency rules.

4.1 Server-scoped decorators¶

Created once at startup. Live for the lifetime of the process. Shared across every request.

// Server-scoped — one instance, used by every request
type Metrics struct {
    requests *prometheus.CounterVec
    latency  *prometheus.HistogramVec
}

func NewMetrics(reg prometheus.Registerer) *Metrics {
    m := &Metrics{
        requests: prometheus.NewCounterVec(prometheus.CounterOpts{
            Name: "http_requests_total",
        }, []string{"method", "path", "status"}),
        latency: prometheus.NewHistogramVec(prometheus.HistogramOpts{
            Name: "http_request_duration_seconds",
        }, []string{"method", "path"}),
    }
    reg.MustRegister(m.requests, m.latency)
    return m
}

func (m *Metrics) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        rec := &statusRecorder{ResponseWriter: w, status: 200}
        next.ServeHTTP(rec, r)
        m.requests.WithLabelValues(r.Method, r.URL.Path, strconv.Itoa(rec.status)).Inc()
        m.latency.WithLabelValues(r.Method, r.URL.Path).Observe(time.Since(start).Seconds())
    })
}

The Metrics struct holds the Prometheus collectors. The closure returned by Middleware captures the struct. Every request increments the same counters. The struct is read-write from every goroutine; the Prometheus client library guarantees thread-safety internally.

The lifecycle is bound to the server: create at startup, register with Prometheus, attach to the mux, never replaced. If you want to swap implementations, you swap the entire chain (rebuild and redeploy).

4.2 Request-scoped decorators¶

Conceptually "created per request" — but in Go this is misleading. The middleware function is created once at startup; what's per-request is the state it allocates inside its closure on each call.

// Request-scoped state — local to each invocation
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(), requestIDKey, id)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

id is a per-request variable. ctx is a per-request derived context. They live on the goroutine's stack during the request and are GC'd afterward. There's no shared mutable state.

This is the right shape for anything that: - Generates per-request data (request ID, trace ID, deadline). - Reads per-request input (auth tokens, query parameters). - Writes per-request output (Set-Cookie, response headers).

4.3 The hybrid: server-scoped state, request-scoped logic¶

Most middlewares are both:

type Auth struct {
    publicKey ed25519.PublicKey  // server-scoped, immutable
    cache     *jwtCache          // server-scoped, thread-safe
}

func (a *Auth) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // request-scoped
        token := r.Header.Get("Authorization")
        claims, err := a.validate(r.Context(), token)
        if err != nil {
            http.Error(w, "unauthorized", 401)
            return
        }
        ctx := context.WithValue(r.Context(), claimsKey, claims)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func (a *Auth) validate(ctx context.Context, token string) (*Claims, error) {
    if c, ok := a.cache.Get(token); ok {
        return c, nil
    }
    c, err := jwt.Verify(token, a.publicKey)
    if err != nil {
        return nil, err
    }
    a.cache.Put(token, c)
    return c, nil
}

The struct holds the public key and the JWT cache — both shared, both thread-safe. The closure produces per-request claims and a per-request context. The function call boundary cleanly separates the two scopes.

4.4 The "request-scoped goroutine" trap¶

A common senior-level mistake: starting a goroutine in a request-scoped middleware that outlives the request.

// ANTI-PATTERN
func AuditAsync(audit AuditService) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            rec := &captureRecorder{ResponseWriter: w}
            next.ServeHTTP(rec, r)

            // BAD: goroutine outlives the request, captures r
            go audit.Log(r.Context(), r.Method, r.URL.Path, rec.status)
        })
    }
}

Three problems: 1. r.Context() is cancelled when the request handler returns. The audit call now runs with a cancelled context and likely fails. 2. r may be reused by net/http's pooling. The request object is not stable beyond ServeHTTP's return. 3. Goroutine leak under load. If the audit service is slow, goroutines pile up. A few thousand RPS with a 10-second audit latency = tens of thousands of goroutines waiting.

The fix: copy what you need, use a server-scoped context (or a derived background context with a timeout), bound concurrency with a worker pool.

type AsyncAudit struct {
    svc     AuditService
    queue   chan auditEvent
    workers int
}

func (a *AsyncAudit) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        rec := &captureRecorder{ResponseWriter: w}
        next.ServeHTTP(rec, r)

        select {
        case a.queue <- auditEvent{
            method: r.Method,
            path:   r.URL.Path,  // path is a string — safe to copy
            status: rec.status,
            time:   time.Now(),
        }:
        default:
            // Queue full — drop (or block, depending on policy)
            a.dropped.Inc()
        }
    })
}

func (a *AsyncAudit) worker(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            return
        case e := <-a.queue:
            a.svc.Log(ctx, e)
        }
    }
}

The queue caps backpressure. The workers are server-scoped. The context is server-scoped. The middleware copies the data it needs out of r. No leaks, no use-after-pool.

5. Middleware libraries in the Go ecosystem¶

The middleware-as-decorator pattern is so dominant in Go that several ecosystems have grown up around it. Knowing the shape of each helps you read other people's code and choose the right tool.

5.1 The standard library baseline¶

net/http defines http.Handler and http.HandlerFunc. Middleware is func(http.Handler) http.Handler. There's no built-in chain; you wrap manually:

h := http.HandlerFunc(handle)
var server http.Handler = h
server = Logging(server)
server = Auth(server)
server = Recovery(server)
http.Handle("/api", server)

Pros: zero dependencies, completely transparent. Cons: order is visually inverted (last call = outermost), no helpers for grouping or per-route middleware.

5.2 chi (github.com/go-chi/chi)¶

Lightweight router with first-class middleware support. The canonical "stdlib-compatible" choice.

r := chi.NewRouter()
r.Use(middleware.RequestID)
r.Use(middleware.Logger)
r.Use(middleware.Recoverer)

r.Route("/api", func(r chi.Router) {
    r.Use(authMiddleware)
    r.Get("/users", listUsers)
    r.Post("/users", createUser)
})

Middleware signature is func(http.Handler) http.Handler — identical to stdlib. chi.Router.Use(...) appends to the router's middleware slice. Route(...) creates a sub-router with its own middleware. Middleware applied at the parent router runs before middleware applied at the sub-router.

The chain is built lazily at first request and cached. Per-request cost is one indirect call per middleware layer.

go-chi/render adds JSON/XML encoding decorators around responses; go-chi/cors adds CORS handling; go-chi/jwtauth adds JWT validation. The ecosystem composes because every piece is func(http.Handler) http.Handler.

5.3 gorilla/mux (github.com/gorilla/mux)¶

Older, more mature router. Middleware via Router.Use(...):

r := mux.NewRouter()
r.Use(loggingMiddleware)
r.Use(authMiddleware)
r.HandleFunc("/api/users", listUsers).Methods("GET")

Same signature, same shape. gorilla/mux's middleware applies to all routes registered on the router; sub-routers via Subrouter() get their own middleware stack. The library was archived in 2022 (handed off to a community fork), so new projects should prefer chi or echo, but you'll meet gorilla/mux in any codebase older than 2020.

5.4 gin (github.com/gin-gonic/gin)¶

Faster but with its own handler signature: func(*gin.Context) instead of (http.ResponseWriter, *http.Request). Middleware is gin.HandlerFunc too:

r := gin.New()
r.Use(gin.Logger())
r.Use(gin.Recovery())

api := r.Group("/api")
api.Use(authMiddleware)
api.GET("/users", listUsers)

The "next" handler is invoked by calling c.Next():

func authMiddleware(c *gin.Context) {
    token := c.GetHeader("Authorization")
    if !validate(token) {
        c.AbortWithStatus(401)
        return
    }
    c.Next()  // explicit delegation
}

This is a different shape from the wrapper pattern — gin uses an "explicit chain" model where each middleware sees a Context that carries a pointer to the next handler. It's equivalent in expressiveness; the syntactic difference is that you call c.Next() instead of next.ServeHTTP(w, r).

Performance: gin claims ~40x faster than stdlib net/http for routing, mostly due to its radix-tree router and avoidance of reflection. The middleware dispatch overhead is in the same order of magnitude as chi's.

5.5 echo (github.com/labstack/echo)¶

Similar shape to gin: custom echo.Context, func(echo.Context) error handlers, middleware as func(echo.HandlerFunc) echo.HandlerFunc.

e := echo.New()
e.Use(middleware.Logger())
e.Use(middleware.Recover())

g := e.Group("/api")
g.Use(authMiddleware)
g.GET("/users", listUsers)

func authMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
    return func(c echo.Context) error {
        if !validate(c.Request().Header.Get("Authorization")) {
            return echo.NewHTTPError(401)
        }
        return next(c)
    }
}

Echo's middleware shape is exactly func(Handler) Handler — the same pattern as stdlib, just with echo.HandlerFunc instead of http.Handler. No c.Next() indirection.

5.6 The choice¶

For new code in 2026, chi is the dominant choice if you want to stay close to stdlib semantics. Gin/echo are common for high-throughput JSON APIs. The decorator pattern is identical across all of them; only the type signatures change.

6. chi, gorilla/mux, echo, gin: same idea, different ergonomics¶

A side-by-side of how each library expresses the same middleware.

6.1 The task: log every request with method, path, status, duration¶

Stdlib:

func Logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        rec := &recorder{ResponseWriter: w, status: 200}
        next.ServeHTTP(rec, r)
        log.Printf("%s %s %d %s",
            r.Method, r.URL.Path, rec.status, time.Since(start))
    })
}

type recorder struct {
    http.ResponseWriter
    status int
}

func (r *recorder) WriteHeader(code int) {
    r.status = code
    r.ResponseWriter.WriteHeader(code)
}

chi (identical signature):

r := chi.NewRouter()
r.Use(Logging)

Or use chi's built-in middleware.Logger:

r.Use(middleware.Logger)

gin:

func Logging() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        c.Next()
        log.Printf("%s %s %d %s",
            c.Request.Method, c.Request.URL.Path,
            c.Writer.Status(), time.Since(start))
    }
}

r := gin.New()
r.Use(Logging())

echo:

func Logging(next echo.HandlerFunc) echo.HandlerFunc {
    return func(c echo.Context) error {
        start := time.Now()
        err := next(c)
        log.Printf("%s %s %d %s",
            c.Request().Method, c.Request().URL.Path,
            c.Response().Status, time.Since(start))
        return err
    }
}

e := echo.New()
e.Use(Logging)

The pattern is identical. The signature is different. The cognitive model — "wrap the next handler, do work around it" — translates one-to-one.

6.2 Comparison table¶

The senior takeaway: pick the library by ergonomics and ecosystem fit, not by the middleware model. The model is the same.

7. gRPC unary and stream interceptors¶

gRPC's interceptor is the decorator pattern with two specializations: unary (request-response) and streaming (one-or-both sides streaming).

7.1 Unary server interceptor¶

type UnaryServerInterceptor func(
    ctx context.Context,
    req interface{},
    info *UnaryServerInfo,
    handler UnaryHandler,
) (resp interface{}, err error)

type UnaryHandler func(ctx context.Context, req interface{}) (interface{}, error)

The interceptor receives the request, info about the method being called, and a handler (the next link in the chain). It must call handler(ctx, req) to delegate.

func Logging(logger *log.Logger) grpc.UnaryServerInterceptor {
    return func(
        ctx context.Context,
        req interface{},
        info *grpc.UnaryServerInfo,
        handler grpc.UnaryHandler,
    ) (interface{}, error) {
        start := time.Now()
        resp, err := handler(ctx, req)
        logger.Printf("%s took %s err=%v",
            info.FullMethod, time.Since(start), err)
        return resp, err
    }
}

This is structurally identical to HTTP middleware. The interface boundary is UnaryHandler instead of http.Handler; the chain composes the same way.

Server setup:

s := grpc.NewServer(
    grpc.ChainUnaryInterceptor(
        recovery.UnaryServerInterceptor(),
        tracing.UnaryServerInterceptor(),
        metrics.UnaryServerInterceptor(),
        auth.UnaryServerInterceptor(authFn),
        logging.UnaryServerInterceptor(logger),
    ),
)

grpc.ChainUnaryInterceptor applies interceptors in order, with the first interceptor in the list being the outermost. Same convention as chi, gorilla/mux, and most HTTP middleware libraries.

7.2 Unary client interceptor¶

Mirror image — wraps outgoing calls:

type UnaryClientInterceptor func(
    ctx context.Context,
    method string,
    req, reply interface{},
    cc *ClientConn,
    invoker UnaryInvoker,
    opts ...CallOption,
) error

Used for client-side concerns: retries, circuit breakers, client-side tracing, request ID propagation.

func RetryInterceptor(maxAttempts int) grpc.UnaryClientInterceptor {
    return func(
        ctx context.Context,
        method string,
        req, reply interface{},
        cc *grpc.ClientConn,
        invoker grpc.UnaryInvoker,
        opts ...grpc.CallOption,
    ) error {
        var lastErr error
        for i := 0; i < maxAttempts; i++ {
            err := invoker(ctx, method, req, reply, cc, opts...)
            if err == nil {
                return nil
            }
            if !isRetryable(err) {
                return err
            }
            lastErr = err
            // exponential backoff with jitter
            backoff := time.Duration(1<<i) * 100 * time.Millisecond
            backoff += time.Duration(rand.Int63n(int64(backoff)))
            select {
            case <-time.After(backoff):
            case <-ctx.Done():
                return ctx.Err()
            }
        }
        return fmt.Errorf("after %d attempts: %w", maxAttempts, lastErr)
    }
}

Client setup:

conn, err := grpc.NewClient(addr,
    grpc.WithChainUnaryInterceptor(
        tracing.UnaryClientInterceptor(),
        metrics.UnaryClientInterceptor(),
        RetryInterceptor(3),
        TimeoutInterceptor(5*time.Second),
    ),
)

7.3 Stream interceptors¶

Stream RPCs (server-streaming, client-streaming, bidirectional) need different shapes because the call doesn't return a single response — it returns a grpc.ServerStream (server side) or grpc.ClientStream (client side) that is read/written incrementally.

type StreamServerInterceptor func(
    srv interface{},
    ss ServerStream,
    info *StreamServerInfo,
    handler StreamHandler,
) error

To decorate the stream, you wrap the ServerStream:

type wrappedServerStream struct {
    grpc.ServerStream
    ctx context.Context
}

func (w *wrappedServerStream) Context() context.Context { return w.ctx }

func TracingStream(tracer trace.Tracer) grpc.StreamServerInterceptor {
    return func(
        srv interface{},
        ss grpc.ServerStream,
        info *grpc.StreamServerInfo,
        handler grpc.StreamHandler,
    ) error {
        ctx, span := tracer.Start(ss.Context(), info.FullMethod)
        defer span.End()

        return handler(srv, &wrappedServerStream{
            ServerStream: ss,
            ctx:          ctx,
        })
    }
}

Note the nested decorator pattern: we decorate the interceptor and we decorate the ServerStream. Both wrap; both implement the same interface as what they wrap. Stream interceptors are decorators all the way down.

7.4 The grpc-ecosystem/go-grpc-middleware library¶

The de facto collection of interceptors for production gRPC services. Wraps:

• recovery — panic recovery, optional custom handler.
• logging — slog, zap, zerolog adapters.
• auth — pluggable token validation.
• validator — request validation via protoc-gen-validate.
• retry — client-side retry with policies.
• ratelimit — server-side rate limiting.
• tags — context tags for cross-cutting metadata.

Every entry in that list is a decorator. The library's design choice — provide each as a separate factory function returning an interceptor — means you compose only what you need, in the order you want.

7.5 Ordering rules for gRPC interceptors¶

Same principles as HTTP middleware, slight shifts:

grpc.ChainUnaryInterceptor(
    recovery.UnaryServerInterceptor(),     // outermost — catches panics from everything below
    tracing.UnaryServerInterceptor(),      // wraps everything in a span
    metrics.UnaryServerInterceptor(),      // sees final status + duration
    auth.UnaryServerInterceptor(authFn),   // reject before handler runs
    validator.UnaryServerInterceptor(),    // validate after auth
    logging.UnaryServerInterceptor(),      // log final outcome
    // handler runs here
)

Recovery outermost: a panic in any interceptor or handler is caught. Tracing next: every request gets a span, including auth failures. Metrics next: every request is counted. Auth before validator: don't validate unauthenticated requests. Logging innermost (of the cross-cutters): logs see the resolved authentication context.

Get this wrong and your panics aren't recovered, your traces are incomplete, your metrics under-count, your logs leak unauthenticated request details. Each row in that order represents a production incident someone had.

8. OpenTelemetry: otelhttp and otelgrpc as decorators¶

OpenTelemetry's Go SDK ships instrumentation as decorators. Studying them is instructive because they're well-engineered, widely deployed, and demonstrate non-trivial decorator design.

8.1 otelhttp server-side¶

import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"

handler := otelhttp.NewHandler(
    http.HandlerFunc(myAPIHandler),
    "/api/v1",  // operation name
    otelhttp.WithSpanNameFormatter(func(_ string, r *http.Request) string {
        return r.Method + " " + r.URL.Path
    }),
    otelhttp.WithFilter(func(r *http.Request) bool {
        return !strings.HasPrefix(r.URL.Path, "/health")
    }),
)

otelhttp.NewHandler is a decorator factory. It returns an http.Handler that wraps the input handler, extracts the incoming trace context from headers (via the configured propagator), starts a span, runs the inner handler, ends the span with status, and records metrics.

The decoration is substantial — it touches: - Request headers (extract trace context). - Request context (inject span). - ResponseWriter (intercept status code for span attributes). - Response headers (inject trace context for downstream — only on server, not on client). - Metrics (request count, duration histogram).

The trick: it does all of this without breaking the http.Handler contract. The wrapped handler still satisfies http.Handler, callers can't tell from the type whether tracing is enabled, and the chain composes with any other middleware.

8.2 otelhttp client-side¶

client := &http.Client{
    Transport: otelhttp.NewTransport(
        http.DefaultTransport,
        otelhttp.WithSpanNameFormatter(func(_ string, r *http.Request) string {
            return r.Method + " " + r.URL.Host
        }),
    ),
}

otelhttp.NewTransport decorates http.RoundTripper. Same pattern, different interface. Every outbound request from client gets traced, headers injected, metrics recorded.

http.RoundTripper is one of the cleanest decorator interfaces in the stdlib:

type RoundTripper interface {
    RoundTrip(*Request) (*Response, error)
}

One method. Any wrapper of RoundTripper is a decorator. The standard library uses this for http2.Transport, httputil.NewSingleHostReverseProxy, and third-party libraries use it for retries, caching, rate limiting, mocking. Every observability vendor (Datadog, New Relic, Honeycomb, otel) ships a RoundTripper decorator.

8.3 otelgrpc interceptors¶

import "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"

s := grpc.NewServer(
    grpc.ChainUnaryInterceptor(
        otelgrpc.UnaryServerInterceptor(),
        otelgrpc.StreamServerInterceptor(),  // for streaming
    ),
)

conn, _ := grpc.NewClient(addr,
    grpc.WithChainUnaryInterceptor(otelgrpc.UnaryClientInterceptor()),
    grpc.WithChainStreamInterceptor(otelgrpc.StreamClientInterceptor()),
)

Same shape, gRPC-specific. The interceptors extract the trace context from gRPC metadata (gRPC's equivalent of HTTP headers), start spans, propagate context, record metrics.

8.4 The "stats handler" alternative¶

gRPC has a second extension point — stats.Handler — that's more powerful than interceptors for observability. Otel moved its gRPC instrumentation to stats.Handler in 2023.

s := grpc.NewServer(
    grpc.StatsHandler(otelgrpc.NewServerHandler()),
)

stats.Handler sees more events (connection establishment, header send/recv, payload size) than interceptors do, and runs without participating in the interceptor chain. For pure observability, it's a better fit. For modifying behaviour (auth, retry, validation), interceptors remain the right choice.

The lesson: the same problem (observe RPCs) can be solved by two different decorator-shaped extension points, and the library's choice between them is an architectural decision. Interceptors are simpler to reason about. Stats handlers are more powerful but don't compose with interceptors directly.

8.5 The cost¶

Otel's instrumentation isn't free. Each span allocates ~1-2 KB on the heap (span context, attributes, links). At 50K RPS that's ~50-100 MB/s of allocation pressure — visible in heap profiles, occasionally triggering GC.

For latency-sensitive services, otel ships a sampling layer:

import "go.opentelemetry.io/otel/sdk/trace"

provider := trace.NewTracerProvider(
    trace.WithSampler(trace.ParentBased(
        trace.TraceIDRatioBased(0.01),  // sample 1% of root spans
    )),
)

Unsampled spans are no-ops with minimal allocation. The decorator is still in the chain; it just emits less. The 1% sample rate is a common production setting; some critical paths sample 100% (paid-tier APIs); some hot paths sample 0.01% (per-byte read paths).

The senior takeaway: instrumentation decorators are mandatory but expensive. Choose the sampling layer carefully and measure the impact in heap profiles, not just in latency.

9. Sidecar patterns: decorators that live in another process¶

When a decorator gets too big, too cross-cutting, or too operationally distinct from the application, you can push it out of the process into a sidecar.

A sidecar is a separate process running on the same machine (usually the same Kubernetes pod) that intercepts traffic to/from the application. From the application's perspective, the sidecar is transparent — it talks to localhost. From the network's perspective, the sidecar is the visible endpoint.

9.1 What a sidecar typically decorates¶

Sidecar = decorator at the network boundary. The mental model is the same — wrap the next layer, do work around it, delegate.

9.2 When sidecar wins¶

• Polyglot fleet. Twenty services in eight languages. Implementing the same circuit breaker in eight languages is wasteful and inconsistent. A sidecar implements it once.
• Operational independence. Platform team owns the sidecar; product teams own application code. Upgrading TLS policy is a sidecar redeploy, not a fleet-wide application redeploy.
• Security boundary. mTLS keys live in the sidecar's filesystem, not the application's. Application bugs can't leak them.
• Centralised policy. Rate limits and routing are configured in Istio/Consul, not in twenty different config files.

9.3 When sidecar loses¶

• Latency. A sidecar adds ~100-500µs per request (process boundary, possibly mTLS, possibly proxy re-encoding). For sub-millisecond budgets, this is too much.
• Operational complexity. Sidecar lifecycle is coupled to application pod lifecycle. Pod restarts, sidecar restarts, race conditions during startup.
• Resource overhead. Envoy uses ~50-100 MB RAM per pod even idle. For high-pod-count fleets, that's substantial.
• Debugging. A 502 from the sidecar is ambiguous — was it the application, the network, the sidecar config, or the upstream? Three logs to correlate.

9.4 The in-process middleware + sidecar combination¶

In practice, production services use both. Cross-cutting concerns that benefit from polyglot consistency (mTLS, basic retry, tracing context propagation) go to the sidecar. Concerns that need application-specific logic (business rules, custom auth, custom metrics labels) stay in-process.

The application's decorators complement the sidecar's. Each layer does what it's best at; together they cover everything.

9.5 The "decorator at every layer" rule¶

For distributed observability to work, every layer in the chain must propagate the trace context correctly:

1. The external client must inject traceparent headers.
2. The sidecar must preserve them.
3. The application's HTTP middleware must extract them.
4. The application's business logic must accept context and pass it down.
5. The outbound gRPC interceptor must inject them into outgoing metadata.
6. The outbound sidecar must preserve them.
7. The remote service repeats the process.

If any layer drops the headers, the trace is broken from that point. The decorator pattern is what makes this possible — every layer has a hook, every hook can read/write headers, every layer composes. But it's also what makes it fragile — one misconfigured decorator silently breaks observability for the whole fleet.

10. Resilience decorators: gobreaker, rate.Limiter, hystrix-go¶

The three canonical resilience decorators in Go: circuit breaker, rate limiter, hedging/timeout. Each is a small library that ships a decorator.

10.1 gobreaker — circuit breaker (github.com/sony/gobreaker)¶

A circuit breaker is a state machine: Closed (calls pass through), Open (calls fail fast), HalfOpen (one trial call decides).

import "github.com/sony/gobreaker"

cb := gobreaker.NewCircuitBreaker(gobreaker.Settings{
    Name:        "stripe-charge",
    MaxRequests: 1,
    Interval:    60 * time.Second,
    Timeout:     30 * time.Second,
    ReadyToTrip: func(counts gobreaker.Counts) bool {
        return counts.ConsecutiveFailures > 5
    },
    OnStateChange: func(name string, from, to gobreaker.State) {
        log.Printf("circuit %s: %s -> %s", name, from, to)
    },
})

// Use it as a decorator:
type BreakerCharger struct {
    Inner Charger
    CB    *gobreaker.CircuitBreaker
}

func (b *BreakerCharger) Charge(ctx context.Context, amount int) error {
    _, err := b.CB.Execute(func() (interface{}, error) {
        return nil, b.Inner.Charge(ctx, amount)
    })
    return err
}

CircuitBreaker.Execute is the integration point. It's not itself a decorator — but it's used inside a decorator. The decorator (BreakerCharger) wraps Charger; the breaker tracks state.

Why a separate library and not just write your own: the state machine is non-trivial. gobreaker handles: - Sliding window of success/failure counts. - Probabilistic half-open transitions. - Cooldown timing with jitter. - Concurrent safety for the state.

Writing this from scratch and getting it right is hours of work. Using gobreaker is five lines.

10.2 rate.Limiter — token bucket (golang.org/x/time/rate)¶

The standard token-bucket rate limiter. Thread-safe. Used everywhere.

import "golang.org/x/time/rate"

type RateLimitedCharger struct {
    Inner   Charger
    Limiter *rate.Limiter
}

func NewRateLimitedCharger(inner Charger, rps int, burst int) *RateLimitedCharger {
    return &RateLimitedCharger{
        Inner:   inner,
        Limiter: rate.NewLimiter(rate.Limit(rps), burst),
    }
}

func (r *RateLimitedCharger) Charge(ctx context.Context, amount int) error {
    if err := r.Limiter.Wait(ctx); err != nil {
        return fmt.Errorf("rate limit: %w", err)
    }
    return r.Inner.Charge(ctx, amount)
}

Three methods on rate.Limiter: - Allow() — non-blocking check, returns true if a token is available. - Wait(ctx) — blocks until a token is available, or ctx cancels. - Reserve() — reserves a future token, returns a Reservation you can cancel.

For decorators, Wait is usually what you want — it respects context cancellation, and the caller gets back-pressure instead of errors.

10.3 hystrix-go — Netflix-style command isolation (github.com/afex/hystrix-go)¶

Older library, modelled on Netflix's Hystrix. Combines circuit breaker, timeout, and bulkhead (semaphore-based concurrency limit) into one "command":

import "github.com/afex/hystrix-go/hystrix"

hystrix.ConfigureCommand("charge", hystrix.CommandConfig{
    Timeout:                1000,  // ms
    MaxConcurrentRequests:  100,
    RequestVolumeThreshold: 20,
    SleepWindow:            5000,  // ms
    ErrorPercentThreshold:  50,
})

func (h *HystrixCharger) Charge(ctx context.Context, amount int) error {
    return hystrix.Do("charge", func() error {
        return h.Inner.Charge(ctx, amount)
    }, func(err error) error {
        // fallback
        return ErrDegradedService
    })
}

Hystrix is no longer actively developed (Netflix archived it in 2020). New code should prefer gobreaker + rate.Limiter + explicit timeout context. But hystrix-go is in many production codebases and worth recognising.

10.4 The composed resilience chain¶

The senior version of "wrap with resilience":

type ResilientCharger struct {
    Inner Charger
}

func WithResilience(inner Charger, opts ResilienceOpts) Charger {
    var c Charger = inner

    // Innermost: timeout, so it bounds the actual call
    c = WithTimeout(c, opts.Timeout)

    // Then retry — each retry gets its own timeout budget? Or shares the budget?
    // Senior choice: shared, via the outer ctx. Pass that down.
    c = WithRetry(c, opts.MaxAttempts, opts.RetryableErrors)

    // Then circuit breaker — it tracks the aggregate retry outcome
    c = WithBreaker(c, opts.BreakerSettings)

    // Then rate limit — even rejected requests count against the limit
    c = WithRateLimit(c, opts.RPS, opts.Burst)

    // Outermost: metrics, so we observe everything including rejections
    c = WithMetrics(c, opts.MetricsRegistry)

    return c
}

The ordering reflects what each layer should see:

• Metrics outermost: records every call, including ones rejected by rate limit or circuit breaker.
• Rate limit next: rejects excess load before any expensive logic.
• Circuit breaker next: stops calls when downstream is unhealthy.
• Retry next: handles transient failures.
• Timeout innermost: bounds individual call latency.

A common mistake: putting retry inside timeout. The total time budget is then attempts × timeout instead of timeout, which blows the SLA budget on requests that should have failed fast.

Another common mistake: putting the circuit breaker inside the retry. Then a single failure triggers attempts failed calls before the breaker even sees them. The breaker's trip threshold is now threshold × attempts real failures.

The compositional reasoning matters. Each layer has a clear job; the order encodes the policy.

11. Library design: publishing decorators for downstream consumers¶

When you ship a library, your decorators become other people's middleware. The design rules are stricter than for application code.

11.1 Rule 1: expose the interface, not the decorator type¶

Bad:

// myhttp/myhttp.go
type LoggingMiddleware struct {
    Logger *log.Logger
}

func (l *LoggingMiddleware) Wrap(next http.Handler) http.Handler { ... }

Consumers now depend on *LoggingMiddleware. They can't easily replace it, can't easily test against a mock.

Good:

func NewLogging(logger *log.Logger) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // ...
            next.ServeHTTP(w, r)
        })
    }
}

The factory returns a func(http.Handler) http.Handler — the standard middleware signature. Consumers integrate with any router that accepts that signature.

11.2 Rule 2: provide configurability via functional options¶

type Option func(*config)

type config struct {
    logger      *log.Logger
    skipPaths   []string
    statusLevel map[int]slog.Level
    formatter   func(*http.Request, int, time.Duration) string
}

func WithLogger(l *log.Logger) Option { return func(c *config) { c.logger = l } }
func WithSkipPaths(paths ...string) Option { return func(c *config) { c.skipPaths = paths } }
func WithFormatter(f func(*http.Request, int, time.Duration) string) Option {
    return func(c *config) { c.formatter = f }
}

func NewLogging(opts ...Option) func(http.Handler) http.Handler {
    cfg := defaultConfig()
    for _, opt := range opts {
        opt(&cfg)
    }
    return func(next http.Handler) http.Handler {
        // use cfg.logger, cfg.skipPaths, cfg.formatter
        return ...
    }
}

Functional options let you add knobs over time without breaking existing callers. New options have safe defaults; old callers don't change.

This pattern is everywhere in mature Go libraries: gRPC's grpc.ServerOption, otel's trace.TracerOption, AWS SDK's per-service WithRegion, etc.

11.3 Rule 3: don't lock callers into your context keys¶

Bad:

type contextKey int
const userKey contextKey = 0

func Auth(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        user := authenticate(r)
        ctx := context.WithValue(r.Context(), userKey, user)  // unexported key
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Consumers downstream of Auth can't get the user out of context — the key is unexported.

Good:

type ContextKey struct{ name string }

var UserContextKey = ContextKey{"user"}

func UserFromContext(ctx context.Context) (*User, bool) {
    u, ok := ctx.Value(UserContextKey).(*User)
    return u, ok
}

Expose the key as a value and provide a typed accessor. Consumers use the accessor, never touch the raw key.

The struct-as-key trick (type ContextKey struct{ name string }) prevents accidental key collisions with other packages — two packages with type ContextKey int; const Key ContextKey = 0 would collide; struct keys are unique by package path.

11.4 Rule 4: never silently change ResponseWriter behaviour¶

Decorators that wrap http.ResponseWriter to capture status codes are common:

type recorder struct {
    http.ResponseWriter
    status int
}

func (r *recorder) WriteHeader(code int) {
    r.status = code
    r.ResponseWriter.WriteHeader(code)
}

Looks fine. But http.ResponseWriter has optional extension interfaces — http.Flusher, http.Hijacker, http.Pusher, http.CloseNotifier. If the inner writer implements them, your wrapper does not, because the wrapper only exposes what's on its method set.

Downstream code that does w.(http.Flusher).Flush() now fails with a type assertion panic.

The fix: implement the extension interfaces conditionally:

type recorder struct {
    http.ResponseWriter
    status int
}

func (r *recorder) WriteHeader(code int) {
    r.status = code
    r.ResponseWriter.WriteHeader(code)
}

func (r *recorder) Flush() {
    if f, ok := r.ResponseWriter.(http.Flusher); ok {
        f.Flush()
    }
}

func (r *recorder) Hijack() (net.Conn, *bufio.ReadWriter, error) {
    if h, ok := r.ResponseWriter.(http.Hijacker); ok {
        return h.Hijack()
    }
    return nil, nil, errors.New("hijack not supported")
}

Or use a library like github.com/felixge/httpsnoop that handles all the combinatorics for you.

The general principle: a transparent decorator must preserve all interfaces the underlying type implements. Type assertions are how Go programmers detect optional capabilities; breaking them silently is breaking the API contract.

11.5 Rule 5: document ordering requirements loudly¶

A decorator that has order requirements should say so in its godoc:

// NewRequestID returns middleware that attaches a request ID to the context
// and as a response header.
//
// Order: this middleware should be placed near the outermost layer, before
// logging, tracing, or metrics that may want to reference the request ID.
//
// If a request ID is already present in the X-Request-ID header, it is
// preserved.
func NewRequestID(opts ...Option) func(http.Handler) http.Handler { ... }

The "should be placed near the outermost layer" sentence saves consumers from learning the ordering rule the hard way.

11.6 Rule 6: version the interface, not the implementation¶

If your decorator wraps an interface you don't control (e.g., http.Handler), versioning is trivial — the inner interface is the contract.

If your decorator wraps a library-internal interface (e.g., a custom Charger), you have to commit to that interface's stability. Adding a method breaks downstream implementers. Make the interface as small as possible from day one.

We cover this in §12.

12. Decorator API evolution across major versions¶

A library that ships decorators commits to compatibility for the lifetime of the major version. Evolving the API without breaking consumers requires discipline.

12.1 What's a breaking change for a decorator?¶

Any of these in v1 → v2 breaks consumers:

1. Renaming or removing the factory function.
2. Changing the factory function's signature (adding required parameters, changing parameter types).
3. Adding a method to a decorated interface if implementers are downstream.
4. Changing the decorator's wrapping order (if the library was responsible for composition).
5. Changing context keys consumers depend on.
6. Changing log/metric format (consumers depend on labels for alerts).
7. Changing default behaviour (a metric that was opt-in becomes opt-out).

Each of these has a different mitigation.

12.2 Pattern: optional parameters via functional options¶

Adding new behaviour: introduce a new Option.

// v1.0
func NewLogging() func(http.Handler) http.Handler { ... }

// v1.1 — adds skip-paths feature
func NewLogging(opts ...Option) func(http.Handler) http.Handler { ... }
func WithSkipPaths(paths ...string) Option { ... }

Both NewLogging() and NewLogging(WithSkipPaths("/health")) compile. Existing callers don't change.

If NewLogging() had a required parameter that's becoming optional, you can't easily reverse — once the type is fixed, it's fixed. So default to functional options from v1.

12.3 Pattern: deprecation cycle for removal¶

// v1.5 — deprecating Old in favour of New
//
// Deprecated: use NewLoggingHandler instead.
func NewLogging(opts ...Option) func(http.Handler) http.Handler { ... }

// New, preferred name with better semantics
func NewLoggingHandler(opts ...Option) func(http.Handler) http.Handler { ... }

The Deprecated: comment is a convention go vet and IDEs recognise. Consumers see warnings; existing code keeps compiling. In v2.0, remove NewLogging.

12.4 Pattern: capability detection for optional methods¶

If you need consumers' implementations to support a new method, do it via an optional interface:

// v1.0
type Charger interface {
    Charge(ctx context.Context, amount int) error
}

// v1.5 — some implementations support refund
type Refunder interface {
    Refund(ctx context.Context, chargeID string) error
}

// Decorator can use Refund if available
func (l *LoggingDecorator) Refund(ctx context.Context, chargeID string) error {
    log.Printf("refund: %s", chargeID)
    if r, ok := l.Inner.(Refunder); ok {
        return r.Refund(ctx, chargeID)
    }
    return ErrRefundNotSupported
}

The original Charger interface is frozen; the new capability is segregated. Existing implementations don't break.

12.5 The "decorator wraps an interface you don't control" case¶

If you wrap http.Handler, you're fine — http.Handler is frozen.

If you wrap your own Charger interface, every change to Charger is a breaking change. Three strategies:

1. Don't change Charger. Freeze v1, add new behaviour via segregated optional interfaces.
2. Major version bump. v2 has a new Charger with the new method. Ship v2 as a separate module (github.com/me/lib/v2). Consumers migrate at their pace.
3. Wrapper interface. Add a new type that wraps the old interface and the new behaviour. Consumers using the old interface continue to work; consumers wanting the new behaviour use the wrapper.

None of these are free. The senior choice depends on how widely deployed v1 is. For libraries with thousands of users, the deprecation cycle stretches across years.

12.6 Real example: gRPC interceptor evolution¶

gRPC-go's UnaryServerInterceptor signature has been stable since v1.0 (2016). Adding new metadata fields would break every implementation. So gRPC-go's strategy:

• The info *UnaryServerInfo parameter is a struct. New fields can be added to the struct without breaking implementations (they just don't read the new fields).
• The req interface{} is intentionally interface{} (now any) so the type can be specialised by the service definition.
• Cross-cutting metadata (auth tokens, deadlines, tracing) lives in metadata.MD accessed via the context, not in the interceptor signature.

This is deliberate API design for evolution. The signature can't grow new positional parameters, so all extension goes through info (struct, additive) or ctx (key-value, additive).

12.7 OpenTelemetry's signature evolution¶

OpenTelemetry-Go shipped v1.0 in late 2021 with a stable API. The library's commitment: no breaking changes to the v1.x API. Internally, every change goes through:

1. Add new functionality in a separate package or as a new option.
2. Mark the old way Deprecated: if it's being replaced.
3. Wait at least 6 months and a minor version before removing.
4. Major version bumps are explicitly planned and announced.

The result: otel-go has had ~40 minor versions in 4 years, zero breaking changes for code that follows the stable surface. This is the gold standard.

For your own libraries: pick a level of stability commitment, document it, stick to it. "I'll just rename this method in v1.2" is how you lose users.

13. Liskov and contract testing for decorator chains¶

Liskov substitution for decorators says: a decorated value must behave like the inner value, except for the documented additions. The chain RetryingCharger(StripeGateway) must still satisfy the contract of Charger. If Charger.Charge says "returns ErrInsufficientFunds for insufficient balance", the wrapped version must, too.

Decorators that violate this are the source of half the production incidents in middleware-heavy codebases. They look right, they compile, they pass unit tests, and they silently change semantics in ways that break callers.

13.1 The common violations¶

1. Swallowing errors. A logging decorator that logs the error and returns nil.
2. Swallowing panics. A recovery decorator that catches panics and returns nil instead of a typed error.
3. Changing the context. A timeout decorator that derives from context.Background() instead of the inner ctx.
4. Dropping deadlines. A retry decorator that doesn't respect ctx cancellation.
5. Changing return values. A caching decorator that returns stale data without indicating staleness.
6. Adding side effects. A metrics decorator that increments a counter but also writes to a database.
7. Changing concurrency semantics. A decorator that adds a mutex around a previously lock-free interface.

Each of these is a violation. None will be caught by the compiler. Most won't be caught by unit tests of the decorator alone (because the unit test exercises the decorator's added behaviour, not its conformance to the inner contract).

13.2 The contract test pattern¶

For an interface that has decorators, ship a shared test suite that every decorator (and every base implementation) must pass:

// ChargerContract asserts the behavioural contract for any Charger.
// Run this for every implementation, including decorators wrapping
// the test fake.
func ChargerContract(t *testing.T, newCharger func() Charger) {
    t.Run("Positive amount succeeds", func(t *testing.T) {
        c := newCharger()
        _, err := c.Charge(context.Background(), 1000)
        if err != nil { t.Fatal(err) }
    })

    t.Run("Honours context cancellation", func(t *testing.T) {
        c := newCharger()
        ctx, cancel := context.WithCancel(context.Background())
        cancel()
        _, err := c.Charge(ctx, 1000)
        if !errors.Is(err, context.Canceled) {
            t.Errorf("got %v, want %v", err, context.Canceled)
        }
    })

    t.Run("Errors are propagated", func(t *testing.T) {
        c := newCharger()
        // simulate inner error somehow (depends on test fixture)
        _, err := c.Charge(context.Background(), 1)  // amount=1 triggers fake error
        if err == nil {
            t.Error("expected error, got nil")
        }
    })

    t.Run("Concurrent calls are safe", func(t *testing.T) {
        c := newCharger()
        var wg sync.WaitGroup
        for i := 0; i < 50; i++ {
            wg.Add(1)
            go func() {
                defer wg.Done()
                c.Charge(context.Background(), 1000)
            }()
        }
        wg.Wait()
    })

    t.Run("Deadline is respected", func(t *testing.T) {
        c := newCharger()
        ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
        defer cancel()
        time.Sleep(20 * time.Millisecond) // ensure timeout fires
        _, err := c.Charge(ctx, 1000)
        if !errors.Is(err, context.DeadlineExceeded) {
            t.Errorf("got %v, want %v", err, context.DeadlineExceeded)
        }
    })
}

Now every implementation and every decorator wrapping a test fake gets tested:

// stripe_test.go
func TestStripeContract(t *testing.T) {
    ChargerContract(t, func() Charger {
        return NewStripeGateway(testAPIKey)
    })
}

// logging_decorator_test.go
func TestLoggingDecoratorContract(t *testing.T) {
    ChargerContract(t, func() Charger {
        return NewLoggingDecorator(newTestFakeCharger(), log.Default())
    })
}

// retry_decorator_test.go
func TestRetryDecoratorContract(t *testing.T) {
    ChargerContract(t, func() Charger {
        return NewRetryDecorator(newTestFakeCharger(), 3)
    })
}

// composed chain test
func TestComposedChainContract(t *testing.T) {
    ChargerContract(t, func() Charger {
        c := newTestFakeCharger()
        c = NewLoggingDecorator(c, log.Default())
        c = NewRetryDecorator(c, 3)
        c = NewMetricsDecorator(c, testRegistry)
        return c
    })
}

When a decorator violates the contract (e.g., a retry decorator that doesn't honour context cancellation), the contract test for that decorator fails. The bug is caught in CI, not in production at 3 AM.

13.3 What about decorator-specific behaviour?¶

Contract tests verify the common contract. Decorator-specific behaviour (the retry actually retries; the cache actually caches) needs its own tests:

func TestRetryDecoratorRetries(t *testing.T) {
    fake := newTestFakeCharger()
    fake.errOnAttempt = []bool{true, true, false}  // fail twice, succeed

    c := NewRetryDecorator(fake, 3)
    _, err := c.Charge(context.Background(), 1000)
    if err != nil { t.Fatal(err) }
    if fake.attempts != 3 {
        t.Errorf("expected 3 attempts, got %d", fake.attempts)
    }
}

Contract tests + decorator-specific tests = full coverage.

13.4 Fuzz testing decorator chains¶

For decorators that wrap encoders, decoders, or parsers, fuzz testing finds disagreements between the base and the decorated version:

func FuzzCachedRepo(f *testing.F) {
    f.Add(uint32(1))
    f.Fuzz(func(t *testing.T, id uint32) {
        base := newTestRepo()
        cached := NewCachedRepo(base, time.Minute)

        // First call: should match base
        u1, err1 := base.Get(context.Background(), int(id))
        u2, err2 := cached.Get(context.Background(), int(id))
        if !reflect.DeepEqual(u1, u2) || !errorsMatch(err1, err2) {
            t.Errorf("mismatch: base=(%v, %v), cached=(%v, %v)", u1, err1, u2, err2)
        }

        // Second call to cached: should be identical (cache hit)
        u3, err3 := cached.Get(context.Background(), int(id))
        if !reflect.DeepEqual(u2, u3) || !errorsMatch(err2, err3) {
            t.Errorf("cache inconsistency: first=(%v, %v), second=(%v, %v)", u2, err2, u3, err3)
        }
    })
}