Decorator Pattern — Hands-on Tasks¶

Work through these in order. The first few drill the "wrap-and-delegate" shape from junior.md — a struct that implements the same interface, holds an Inner, and runs work around the call. The middle tasks force the design decisions in middle.md — struct vs function form, ordering invariants, statefulness, context propagation, embedding-based wrapping. The last few are open-ended mini-projects.

Run every solution with go vet ./... and go test ./... before moving on. Each task is self-contained — copy the solution into a fresh directory, go mod init scratch, then iterate.

You need Go 1.21 or later. Tasks 10 and 13 use generics. Task 7 and 19 use net/http. Task 8 uses compress/gzip. Task 16 uses github.com/prometheus/client_golang. Task 18 is a refactoring exercise — start from broken code, end with the decorator form.

Task 1: Logging decorator for a counter service (warm-up)¶

A trivial in-memory counter service that you'll wrap with a logging decorator. The counter has two operations: Incr(key string) and Value(key string) int. The decorator logs every call before delegating.

base := NewMemoryCounter()
counter := &LoggingCounter{Inner: base, Log: log.Default()}

counter.Incr("hits")
counter.Incr("hits")
fmt.Println(counter.Value("hits")) // 2
// Output (to stderr):
// counter: Incr(key=hits)
// counter: Incr(key=hits)
// counter: Value(key=hits) = 2

Acceptance criteria

• Counter interface with two methods: Incr(key string) and Value(key string) int.
• MemoryCounter is the base implementation using a map[string]int guarded by a mutex.
• LoggingCounter is a decorator that holds Inner Counter and Log *log.Logger, and logs each call before delegating.
• A main() exercises both directly and through the decorator.
• A test asserts that wrapping the counter does not change the observed values (transparency).

package main

import (
    "log"
    "os"
    "sync"
)

type Counter interface {
    Incr(key string)
    Value(key string) int
}

type MemoryCounter struct {
    mu sync.Mutex
    m  map[string]int
}

func NewMemoryCounter() *MemoryCounter {
    return &MemoryCounter{m: map[string]int{}}
}

func (c *MemoryCounter) Incr(key string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.m[key]++
}

func (c *MemoryCounter) Value(key string) int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.m[key]
}

type LoggingCounter struct {
    Inner Counter
    Log   *log.Logger
}

func (l *LoggingCounter) Incr(key string) {
    l.Log.Printf("counter: Incr(key=%s)", key)
    l.Inner.Incr(key)
}

func (l *LoggingCounter) Value(key string) int {
    v := l.Inner.Value(key)
    l.Log.Printf("counter: Value(key=%s) = %d", key, v)
    return v
}

func main() {
    base := NewMemoryCounter()
    counter := &LoggingCounter{Inner: base, Log: log.New(os.Stderr, "", 0)}
    counter.Incr("hits")
    counter.Incr("hits")
    counter.Value("hits")
}

Discussion. This is the entire Decorator pattern in 30 lines. Notice three properties: the wrapper and the base implement the same interface (Counter); the wrapper holds an Inner of interface type, not the concrete struct (so it could wrap any other Counter later); and the wrapper delegates — it doesn't try to do the increment itself. Get this shape right and every other decorator is a variation. If your code reaches inside Inner to mutate fields, or has a different return type from Inner's methods, something is off.

Task 2: Retry decorator for an HTTP client¶

An HTTP client interface with one method: Do(*http.Request) (*http.Response, error). Wrap it with a RetryClient decorator that retries transient failures up to N times with exponential backoff.

base := &http.Client{Timeout: 10 * time.Second}
client := &RetryClient{
    Inner:    base,
    Attempts: 3,
    Backoff:  100 * time.Millisecond,
}

resp, err := client.Do(req) // retries up to 3 times on 5xx or network error

Acceptance criteria

• HTTPDoer interface: Do(*http.Request) (*http.Response, error). (Match the http.Client.Do signature so *http.Client satisfies it directly.)
• RetryClient struct holds Inner HTTPDoer, Attempts int, Backoff time.Duration.
• Retry on network error (err != nil) or a 5xx status code.
• Do not retry 4xx — these are client errors, retrying won't help.
• Wait Backoff << attempt between tries (exponential).
• Honor req.Context() — abort retry loop if the context is cancelled.
• A test using httptest.NewServer returning 503 twice then 200 asserts exactly 3 calls were made.

package retryclient

import (
    "errors"
    "fmt"
    "net/http"
    "time"
)

type HTTPDoer interface {
    Do(*http.Request) (*http.Response, error)
}

type RetryClient struct {
    Inner    HTTPDoer
    Attempts int
    Backoff  time.Duration
}

func (r *RetryClient) Do(req *http.Request) (*http.Response, error) {
    if r.Attempts <= 0 {
        return nil, errors.New("RetryClient: Attempts must be > 0")
    }
    var lastErr error
    for i := 0; i < r.Attempts; i++ {
        resp, err := r.Inner.Do(req)
        if err == nil && resp.StatusCode < 500 {
            return resp, nil
        }
        if err == nil {
            // 5xx — discard the body so the connection can be reused.
            resp.Body.Close()
            lastErr = fmt.Errorf("status %d", resp.StatusCode)
        } else {
            lastErr = err
        }
        if i == r.Attempts-1 {
            break
        }
        wait := r.Backoff << i
        t := time.NewTimer(wait)
        select {
        case <-req.Context().Done():
            t.Stop()
            return nil, req.Context().Err()
        case <-t.C:
        }
    }
    return nil, fmt.Errorf("after %d attempts: %w", r.Attempts, lastErr)
}

Discussion. The decorator wraps any HTTPDoer — that includes *http.Client from the standard library, since its Do method has the matching signature. The interface is one method, defined in your package; *http.Client satisfies it implicitly. This is the small-interface dividend: you don't depend on the whole http.Client surface, just the method you care about.

Three subtleties worth internalizing: (1) status-code classification belongs in the decorator, not the caller — retry on 5xx, not 4xx; (2) the response body must be closed on the failure path or you'll leak file descriptors; (3) the context is a first-class citizen — every wait must be cancelable.

Task 3: Cache decorator for a repository¶

A user repository with one method: Get(ctx, id) (User, error). The base implementation hits the database. Wrap it with a CachedRepo decorator that caches results in memory with a TTL.

db := NewDBRepo(dbConn)
repo := NewCachedRepo(db, 5*time.Minute)

u, _ := repo.Get(ctx, 42) // DB call
u, _ = repo.Get(ctx, 42)  // cached, no DB call

Acceptance criteria

• Repo interface: Get(ctx context.Context, id int) (User, error).
• DBRepo simulates a DB by sleeping 10ms and returning User{ID: id, Name: fmt.Sprintf("user_%d", id)}. Track a call count to assert in tests.
• CachedRepo holds Inner Repo, a TTL, and a map of id -> (User, expiresAt), guarded by a mutex.
• On hit: return the cached value without calling Inner.
• On miss or expired: delegate to Inner, store the result, return it.
• Errors from Inner are not cached.
• A test asserts: two Get(42) calls in succession produce one DB call; after the TTL expires, a third call produces a second DB call.

package cacherepo

import (
    "context"
    "fmt"
    "sync"
    "sync/atomic"
    "time"
)

type User struct {
    ID   int
    Name string
}

type Repo interface {
    Get(ctx context.Context, id int) (User, error)
}

type DBRepo struct {
    Calls atomic.Int64
}

func NewDBRepo() *DBRepo { return &DBRepo{} }

func (d *DBRepo) Get(ctx context.Context, id int) (User, error) {
    d.Calls.Add(1)
    time.Sleep(10 * time.Millisecond)
    return User{ID: id, Name: fmt.Sprintf("user_%d", id)}, nil
}

type cacheEntry struct {
    user    User
    expires time.Time
}

type CachedRepo struct {
    Inner Repo
    TTL   time.Duration

    mu      sync.Mutex
    entries map[int]cacheEntry
}

func NewCachedRepo(inner Repo, ttl time.Duration) *CachedRepo {
    return &CachedRepo{Inner: inner, TTL: ttl, entries: map[int]cacheEntry{}}
}

func (c *CachedRepo) Get(ctx context.Context, id int) (User, error) {
    c.mu.Lock()
    e, ok := c.entries[id]
    c.mu.Unlock()
    if ok && time.Now().Before(e.expires) {
        return e.user, nil
    }
    u, err := c.Inner.Get(ctx, id)
    if err != nil {
        return User{}, err
    }
    c.mu.Lock()
    c.entries[id] = cacheEntry{user: u, expires: time.Now().Add(c.TTL)}
    c.mu.Unlock()
    return u, nil
}

Discussion. The decorator owns the cache state — concurrency, TTL, the data structure. The inner repo doesn't know caching exists. This is the payoff of small interfaces: a hundred-line decorator slots in front of a database with zero changes downstream. Two design choices to internalize: the cache state is inside the decorator (not on the inner type), and errors are never cached.

A common follow-up is "what about cache stampede?" — when ten goroutines simultaneously miss the same key and all hit the DB. The fix is singleflight.Group from golang.org/x/sync/singleflight, but adding it is another decorator level you'd layer on top. Don't blend concerns; each decorator does one thing.

Task 4: Tracing decorator for a database client¶

A database client interface with Query(ctx, sql, args...) and Exec(ctx, sql, args...). Wrap it with a TracingDB decorator that emits a span (logged to stdout for this exercise) per call, recording method, SQL, duration, and outcome.

db := &TracingDB{Inner: &PostgresDB{...}}
rows, err := db.Query(ctx, "SELECT * FROM users WHERE id=$1", 42)
// trace: Query sql="SELECT * FROM users WHERE id=$1" args=[42] duration=12.3ms status=ok

Acceptance criteria

• DB interface: Query(ctx, sql string, args ...any) ([]Row, error), Exec(ctx, sql string, args ...any) (int64, error).
• Row is map[string]any.
• MemDB is the base implementation — returns a single hard-coded row for Query, returns 1 for Exec.
• TracingDB wraps any DB and logs each call's method, SQL, args, duration, and status (ok or error: <msg>).
• The trace must include both successful and failed calls. Use a named return error so a defer can read it.
• The decorator must redact arguments that look like passwords (any arg with type string and key name password — for this exercise, any string arg starting with pw_ is "secret").
• A test captures stdout, runs a Query, and asserts the trace line matches the expected format.

func (t *TracingDB) Query(ctx context.Context, sql string, args ...any) (rows []Row, err error) {
    start := time.Now()
    defer func() { ... use err ... }()
    return t.Inner.Query(ctx, sql, args...)
}

package tracedb

import (
    "context"
    "fmt"
    "strings"
    "time"
)

type Row = map[string]any

type DB interface {
    Query(ctx context.Context, sql string, args ...any) ([]Row, error)
    Exec(ctx context.Context, sql string, args ...any) (int64, error)
}

type MemDB struct{}

func (MemDB) Query(ctx context.Context, sql string, args ...any) ([]Row, error) {
    return []Row{{"id": 1, "name": "alice"}}, nil
}

func (MemDB) Exec(ctx context.Context, sql string, args ...any) (int64, error) {
    return 1, nil
}

type TracingDB struct {
    Inner DB
}

func redact(args []any) []any {
    out := make([]any, len(args))
    for i, a := range args {
        if s, ok := a.(string); ok && strings.HasPrefix(s, "pw_") {
            out[i] = "***"
        } else {
            out[i] = a
        }
    }
    return out
}

func (t *TracingDB) Query(ctx context.Context, sql string, args ...any) (rows []Row, err error) {
    start := time.Now()
    defer func() {
        status := "ok"
        if err != nil {
            status = "error: " + err.Error()
        }
        fmt.Printf("trace: Query sql=%q args=%v duration=%s status=%s\n",
            sql, redact(args), time.Since(start), status)
    }()
    return t.Inner.Query(ctx, sql, args...)
}

func (t *TracingDB) Exec(ctx context.Context, sql string, args ...any) (affected int64, err error) {
    start := time.Now()
    defer func() {
        status := "ok"
        if err != nil {
            status = "error: " + err.Error()
        }
        fmt.Printf("trace: Exec sql=%q args=%v duration=%s status=%s\n",
            sql, redact(args), time.Since(start), status)
    }()
    return t.Inner.Exec(ctx, sql, args...)
}

Discussion. Named returns plus deferred closures is the idiom for observability decorators. The deferred function reads the error after the inner call returns, including the case where the inner panics — though for panic safety you'd combine with a recovery decorator (Task 7). The redaction logic shows another aspect of a tracing decorator: it's responsible for not leaking sensitive data into logs. Argument scrubbing belongs inside the tracer, not at every call site.

Production tracing in Go uses OpenTelemetry (otelhttp, otelsql). Those packages are sophisticated decorators with the same structure. Reading their source after you've built this one is a good way to bridge from toy to production.

Task 5: Rate-limit decorator¶

Wrap any operation with a rate-limit decorator that allows at most N calls per second. If the budget is exhausted, Wait(ctx) blocks until a token is available or the context is cancelled.

api := NewAPIClient(httpClient)
limited := &RateLimitedAPI{
    Inner:   api,
    Limiter: rate.NewLimiter(rate.Limit(10), 5), // 10 rps, burst 5
}

for i := 0; i < 20; i++ {
    limited.Call(ctx, req) // first 5 instant; rest spaced ~100ms
}

Acceptance criteria

• API interface: Call(ctx context.Context, req string) (string, error).
• MemAPI base implementation returns "resp:" + req after a short artificial delay.
• RateLimitedAPI holds Inner API and *rate.Limiter (from golang.org/x/time/rate).
• Call calls limiter.Wait(ctx) before delegating. If the wait fails (context cancelled), return the context error wrapped.
• A test fires 10 calls at a 5 rps limiter and asserts the elapsed time is at least 1 second (the limiter must have throttled).
• A test cancels the context during waiting and asserts the call returns the context error within ~10ms.

package rl

import (
    "context"
    "fmt"
    "time"

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

type API interface {
    Call(ctx context.Context, req string) (string, error)
}

type MemAPI struct{}

func (MemAPI) Call(ctx context.Context, req string) (string, error) {
    return "resp:" + req, nil
}

type RateLimitedAPI struct {
    Inner   API
    Limiter *rate.Limiter
}

func (r *RateLimitedAPI) Call(ctx context.Context, req string) (string, error) {
    if err := r.Limiter.Wait(ctx); err != nil {
        return "", fmt.Errorf("rate limited: %w", err)
    }
    return r.Inner.Call(ctx, req)
}

// Convenience constructor.
func NewRateLimitedAPI(inner API, rps float64, burst int) *RateLimitedAPI {
    return &RateLimitedAPI{Inner: inner, Limiter: rate.NewLimiter(rate.Limit(rps), burst)}
}

var _ time.Duration // keep time import in case test uses it

Discussion. The rate limiter from x/time/rate is already thread-safe; the decorator just delegates to it. That's the right division of responsibility — the decorator wires the limiter into the call path; the limiter handles the token-bucket math.

Two production refinements worth knowing: (1) per-key rate limiting — wrap a sync.Map of key -> *rate.Limiter, look up the limiter by the request's API key/user/route; (2) cooperative vs preemptive — Wait blocks; alternatively Allow() returns false immediately so the caller can fast-fail. Which one fits depends on whether the upstream tolerates retries with backoff or wants quick rejection.

Task 6: Circuit breaker decorator¶

Wrap a service with a circuit breaker. After N consecutive failures, the breaker opens — subsequent calls fail fast for a cooldown period. After the cooldown, the breaker goes half-open and allows one probe call; success closes the breaker, failure re-opens it.

breaker := &CircuitBreaker{
    Inner:            unreliableAPI,
    FailureThreshold: 5,
    OpenTimeout:      10 * time.Second,
}

_, err := breaker.Call(ctx, "ping") // fails fast if breaker is open

Acceptance criteria

• API interface: Call(ctx, req string) (string, error).
• CircuitBreaker has three states: Closed, Open, HalfOpen.
• Closed: all calls go through. Track consecutive failures.
• Open: all calls return ErrCircuitOpen immediately. After OpenTimeout, transition to HalfOpen.
• HalfOpen: one call may go through. Success → Closed (reset failure count). Failure → Open (reset timer).
• State transitions are guarded by a mutex.
• A test simulates 5 consecutive failures and asserts the 6th call returns ErrCircuitOpen without invoking Inner.
• A test asserts that after OpenTimeout, the breaker allows a probe.

package breaker

import (
    "context"
    "errors"
    "sync"
    "time"
)

type API interface {
    Call(ctx context.Context, req string) (string, error)
}

type breakerState int

const (
    Closed breakerState = iota
    Open
    HalfOpen
)

var ErrCircuitOpen = errors.New("circuit breaker open")

type CircuitBreaker struct {
    Inner            API
    FailureThreshold int
    OpenTimeout      time.Duration

    mu       sync.Mutex
    state    breakerState
    failures int
    opened   time.Time
}

func (b *CircuitBreaker) Call(ctx context.Context, req string) (string, error) {
    if !b.allow() {
        return "", ErrCircuitOpen
    }
    resp, err := b.Inner.Call(ctx, req)
    b.record(err)
    return resp, err
}

func (b *CircuitBreaker) allow() bool {
    b.mu.Lock()
    defer b.mu.Unlock()
    switch b.state {
    case Open:
        if time.Since(b.opened) > b.OpenTimeout {
            b.state = HalfOpen
            return true
        }
        return false
    case HalfOpen:
        // Allow exactly one probe — by transitioning back to Open until the probe
        // reports. The probe's record() call decides the next state.
        b.state = Open
        b.opened = time.Now()
        return true
    default:
        return true
    }
}

func (b *CircuitBreaker) record(err error) {
    b.mu.Lock()
    defer b.mu.Unlock()
    if err != nil {
        b.failures++
        if b.failures >= b.FailureThreshold {
            b.state = Open
            b.opened = time.Now()
        }
        return
    }
    b.state = Closed
    b.failures = 0
}

Discussion. Stateful decorators need state machines, and state machines need mutexes. This breaker is a small example: three states, two transitions on the call path. The non-trivial design choice is which probe is allowed in HalfOpen — if you naively return true whenever the state is HalfOpen, all concurrent goroutines slip through and stampede the upstream. The trick above is to flip back to Open inside allow() so the next probe re-checks the timer.

Real breakers (Sony/gobreaker, Netflix Hystrix) add more knobs: time windows for failure counting, percentage-based opening, half-open call quotas. The pattern stays the same — a decorator that wraps a Call method and decides whether to forward or short-circuit.

Task 7: HTTP middleware chain (logging + recovery + auth)¶

Build the three classical middlewares — logging, recovery, auth — and a chain helper that composes them. Verify the order is what you expect.

handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "hello")
})

h := Chain(handler, Logging, Recover, Auth)
http.ListenAndServe(":8080", h)

Acceptance criteria

• Middleware type: func(http.Handler) http.Handler.
• Logging logs <method> <path> <status> <duration>. Capture status via a ResponseWriter wrapper.
• Recover catches panics and writes 500.
• Auth checks the Authorization header; if empty, write 401 and short-circuit.
• Chain(h, mws...) composes left-to-right — the first middleware in the slice is the outermost.
• A test fires a request that panics; asserts that the response is 500 and a panic log was emitted.
• A test asserts that an unauthenticated request returns 401 and doesn't reach the handler.

package middleware

import (
    "log"
    "net/http"
    "runtime/debug"
    "time"
)

type Middleware func(http.Handler) http.Handler

type statusRecorder struct {
    http.ResponseWriter
    status int
}

func (s *statusRecorder) WriteHeader(code int) {
    s.status = code
    s.ResponseWriter.WriteHeader(code)
}

func Logging(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)
        log.Printf("%s %s %d %s", r.Method, r.URL.Path, rec.status, time.Since(start))
    })
}

func Recover(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if rec := recover(); rec != nil {
                log.Printf("panic: %v\n%s", rec, debug.Stack())
                http.Error(w, "internal error", http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}

func Auth(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Header.Get("Authorization") == "" {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        next.ServeHTTP(w, r)
    })
}

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

Discussion. Three middlewares, one chain helper, the canonical pattern for every Go HTTP server. Note the order in Chain(h, Logging, Recover, Auth): Logging is outermost — it sees the final status of every request including unauthorized ones and recovered panics. If you wanted to not log 401s, you'd reorder to Chain(h, Auth, Logging, Recover) — but then a panic in the handler would propagate up through Logging after Auth had been bypassed, and the log line would record a 500 from Recover. Each ordering is reasonable; choose deliberately.

The statusRecorder wrapper is itself a tiny decorator over http.ResponseWriter — the same pattern at a smaller scale. Once you start spotting decorators, you see them at every level of an HTTP server.

Task 8: Compression decorator (io.Reader wrapping)¶

Build a gzipReader decorator that wraps an io.Reader and transparently decompresses gzipped bytes. Then build a countingReader that wraps any reader and exposes the number of bytes read. Stack them.

f, _ := os.Open("data.gz")
defer f.Close()

gz, _ := newGzipReader(f)    // decompresses on the fly
ct := &countingReader{Inner: gz}

data, _ := io.ReadAll(ct)
fmt.Printf("decompressed %d bytes, read %d bytes from gz\n", len(data), ct.Count())

Acceptance criteria

• Both wrappers implement io.Reader.
• gzipReader uses compress/gzip internally; it satisfies io.Reader and io.Closer (close the underlying gzip reader on Close).
• countingReader wraps any io.Reader, forwards reads, and exposes a Count() int64 method.
• A test writes a known string into a bytes.Buffer via gzip.Writer, wraps the buffer with the two decorators, reads through, and asserts the count and decompressed content.

package iowrap

import (
    "compress/gzip"
    "io"
    "sync/atomic"
)

type gzipReader struct {
    gz *gzip.Reader
}

func newGzipReader(r io.Reader) (*gzipReader, error) {
    gz, err := gzip.NewReader(r)
    if err != nil {
        return nil, err
    }
    return &gzipReader{gz: gz}, nil
}

func (g *gzipReader) Read(p []byte) (int, error) { return g.gz.Read(p) }
func (g *gzipReader) Close() error               { return g.gz.Close() }

type countingReader struct {
    Inner io.Reader
    count atomic.Int64
}

func (c *countingReader) Read(p []byte) (int, error) {
    n, err := c.Inner.Read(p)
    c.count.Add(int64(n))
    return n, err
}

func (c *countingReader) Count() int64 { return c.count.Load() }

Discussion. This is decorator at the smallest scale — wrapping io.Reader, which has one method. The standard library is full of this: bufio.NewReader, gzip.NewReader, lz4.NewReader, tls.Client(conn, ...). Each adds one layer of capability while keeping the interface unchanged. The lesson: when an interface is small and pure (no state, no side effects on construction), decorators stack endlessly without coupling.

Stacking matters here. countingReader over gzipReader over *os.File counts decompressed bytes after gzip. countingReader directly on *os.File counts compressed bytes from disk. Same wrapper, different placement, different answer. That's the power and the trap of decorators — placement is meaning.

Task 9: Buffering decorator (io.Writer wrapping)¶

The mirror of Task 8 for the write side. Build a bufferedWriter decorator that buffers writes in memory and flushes on demand. Stack it with a countingWriter that tracks bytes written.

f, _ := os.Create("out.txt")
ct := &countingWriter{Inner: f}
bw := newBufferedWriter(ct, 1024)

bw.Write([]byte("hello"))   // goes to buffer, not yet to file
bw.Flush()                  // now to file via ct
fmt.Println(ct.Count())     // 5

Acceptance criteria

• Both wrappers implement io.Writer.
• bufferedWriter collects writes up to a configurable buffer size; when full, it auto-flushes. Exposes an explicit Flush() error.
• Close() on bufferedWriter flushes and (if Inner is also an io.Closer) closes the inner writer.
• countingWriter exposes Count() int64 for total bytes written to Inner.
• A test writes mixed-sized payloads, asserts that buffering triggers a flush only when full, and that the final Flush writes the residual.

package iowrap

import (
    "io"
    "sync/atomic"
)

type bufferedWriter struct {
    Inner io.Writer
    buf   []byte
    max   int
}

func newBufferedWriter(w io.Writer, size int) *bufferedWriter {
    return &bufferedWriter{Inner: w, buf: make([]byte, 0, size), max: size}
}

func (b *bufferedWriter) Write(p []byte) (int, error) {
    written := 0
    for len(p) > 0 {
        space := b.max - len(b.buf)
        if space == 0 {
            if err := b.Flush(); err != nil {
                return written, err
            }
            space = b.max
        }
        n := space
        if n > len(p) {
            n = len(p)
        }
        b.buf = append(b.buf, p[:n]...)
        p = p[n:]
        written += n
    }
    return written, nil
}

func (b *bufferedWriter) Flush() error {
    if len(b.buf) == 0 {
        return nil
    }
    _, err := b.Inner.Write(b.buf)
    b.buf = b.buf[:0]
    return err
}

func (b *bufferedWriter) Close() error {
    if err := b.Flush(); err != nil {
        return err
    }
    if c, ok := b.Inner.(io.Closer); ok {
        return c.Close()
    }
    return nil
}

type countingWriter struct {
    Inner io.Writer
    count atomic.Int64
}

func (c *countingWriter) Write(p []byte) (int, error) {
    n, err := c.Inner.Write(p)
    c.count.Add(int64(n))
    return n, err
}

func (c *countingWriter) Count() int64 { return c.count.Load() }

Discussion. The buffer decorator does something clever — it changes the timing of writes. The caller's perception is "Write returned, my data is safe", but the data is only in memory until Flush. This is one of the few times a decorator changes more than just "what runs around the call" — it changes the visible semantics of the operation. If the program crashes between Write and Flush, the buffered data is lost. That's the contract bufio.Writer carries too.

The "Close if io.Closer" idiom is worth memorizing. Many decorators must propagate Close — file descriptors, network connections, gzip footers — but the inner interface might not include Close. The type assertion is how you bridge the gap without expanding the interface.

Task 10: Generic Map/Filter pipeline (Go 1.18+) using decorator¶

A streaming iterator with map and filter operations chained via decorators. Each operation returns a new iterator that decorates the previous one.

nums := FromSlice([]int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10})
result := Filter(Map(nums, func(x int) int { return x * x }), func(x int) bool { return x > 20 })

for result.Next() {
    fmt.Println(result.Value()) // 25, 36, 49, 64, 81, 100
}

Acceptance criteria

• Iter[T any] interface: Next() bool, Value() T.
• FromSlice[T](s []T) Iter[T] returns a slice-backed iterator.
• Map[T, U any](in Iter[T], f func(T) U) Iter[U] decorates in with element-wise mapping.
• Filter[T any](in Iter[T], pred func(T) bool) Iter[T] decorates in with predicate filtering.
• Iterators are lazy — Map and Filter produce values on demand, not eagerly.
• A test asserts that the example above produces [25 36 49 64 81 100] in order.
• A test asserts that Map over an empty iterator returns no values.

package pipeline

type Iter[T any] interface {
    Next() bool
    Value() T
}

// slice-backed
type sliceIter[T any] struct {
    data []T
    pos  int
}

func FromSlice[T any](s []T) Iter[T] {
    return &sliceIter[T]{data: s, pos: -1}
}

func (s *sliceIter[T]) Next() bool {
    s.pos++
    return s.pos < len(s.data)
}

func (s *sliceIter[T]) Value() T {
    return s.data[s.pos]
}

// Map
type mapIter[T, U any] struct {
    in Iter[T]
    f  func(T) U
}

func Map[T, U any](in Iter[T], f func(T) U) Iter[U] {
    return &mapIter[T, U]{in: in, f: f}
}

func (m *mapIter[T, U]) Next() bool { return m.in.Next() }
func (m *mapIter[T, U]) Value() U   { return m.f(m.in.Value()) }

// Filter
type filterIter[T any] struct {
    in     Iter[T]
    pred   func(T) bool
    cached T
    has    bool
}

func Filter[T any](in Iter[T], pred func(T) bool) Iter[T] {
    return &filterIter[T]{in: in, pred: pred}
}

func (f *filterIter[T]) Next() bool {
    for f.in.Next() {
        v := f.in.Value()
        if f.pred(v) {
            f.cached = v
            f.has = true
            return true
        }
    }
    f.has = false
    return false
}

func (f *filterIter[T]) Value() T {
    return f.cached
}

Discussion. This is decorator composed through generics. Each combinator (Map, Filter) takes an Iter[T] and returns an Iter[U] that wraps it. Composition is just function application: Filter(Map(...)). The wrappers are lazy — values flow through the pipeline on demand, like UNIX pipes.

This is also how Go 1.23's iter.Seq[T] package shapes the standard streaming API. Once you've built this by hand, reading slices.All, maps.Keys, and the iter package documentation feels familiar — it's the same Decorator+Generics combo.

A caveat: error handling is missing from this design. Real iterator chains return either (T, error) or have a separate Err() method on the iterator. Decide upfront; retrofitting later is painful.

Task 11: Request-ID injection middleware¶

A middleware that injects a X-Request-ID into incoming requests (generating one if absent) and into outgoing responses, and exposes the ID via context.Context so handlers can log it.

chain := Chain(handler, RequestID, Logging)
http.Handle("/api", chain)
// Every request log line includes a unique request ID.
// Downstream handlers can call RequestIDFromContext(r.Context()) to retrieve it.

Acceptance criteria

• RequestID middleware: reads X-Request-ID header; if empty, generates a new ID (use crypto/rand to produce 8 random bytes hex-encoded).
• The middleware injects the ID into the request context via context.WithValue using a private key type.
• The middleware sets the X-Request-ID header on the response.
• An exported RequestIDFromContext(ctx context.Context) (string, bool) retrieves the ID.
• A Logging middleware that uses the request ID in its log line.
• A test sends a request without X-Request-ID, asserts the response has the header set, and the log line contains a non-empty ID.

package reqid

import (
    "context"
    "crypto/rand"
    "encoding/hex"
    "net/http"
)

type ctxKey struct{}

var requestIDKey = ctxKey{}

func RequestIDFromContext(ctx context.Context) (string, bool) {
    v, ok := ctx.Value(requestIDKey).(string)
    return v, ok
}

func generateID() string {
    var buf [8]byte
    _, _ = rand.Read(buf[:])
    return hex.EncodeToString(buf[:])
}

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

Discussion. The decorator does three things at once: generation, propagation via context, and reflection back via response header. Each is one line; together they're a critical operational tool. Request IDs in logs let you trace a single request across services — without them, distributed debugging is nearly impossible.

The private key type pattern (type ctxKey struct{}) is the standard Go idiom for context keys. The empty struct type is unforgeable from outside the package — no one can accidentally collide with your key. context.WithValue documentation explicitly recommends this.

A subtle point: the middleware sets the response header before the handler runs, but the handler might call WriteHeader (which "freezes" the headers). Order matters — set the header in the middleware, then call next.ServeHTTP.

Task 12: Timeout decorator using context¶

A timeout decorator that wraps any context-aware operation and aborts the inner call after a deadline.

op := &TimedOp{Inner: slowAPI, Timeout: 100 * time.Millisecond}
result, err := op.Run(ctx, "request")
// err is context.DeadlineExceeded if Inner takes >100ms

Acceptance criteria

• Op interface: Run(ctx context.Context, input string) (string, error).
• SlowOp base implementation sleeps a configurable duration before returning.
• TimedOp derives a context with context.WithTimeout and passes it to Inner.Run.
• The decorator must not discard the caller's context — derive from it.
• Cancel function must be deferred to avoid context leaks.
• A test asserts: SlowOp(50ms) wrapped with Timeout(100ms) succeeds; SlowOp(200ms) wrapped with Timeout(100ms) returns context.DeadlineExceeded.

package timed

import (
    "context"
    "time"
)

type Op interface {
    Run(ctx context.Context, input string) (string, error)
}

type SlowOp struct {
    Duration time.Duration
}

func (s SlowOp) Run(ctx context.Context, input string) (string, error) {
    select {
    case <-ctx.Done():
        return "", ctx.Err()
    case <-time.After(s.Duration):
        return "done:" + input, nil
    }
}

type TimedOp struct {
    Inner   Op
    Timeout time.Duration
}

func (t *TimedOp) Run(ctx context.Context, input string) (string, error) {
    ctx, cancel := context.WithTimeout(ctx, t.Timeout)
    defer cancel()
    return t.Inner.Run(ctx, input)
}

Discussion. Three rules for context decorators: (1) derive from the caller's context, never from context.Background() — otherwise you discard the parent's deadline and cancellation; (2) defer cancel — even if WithTimeout fires, calling cancel releases the timer resource; (3) the inner op must honor the context — wrapping a non-context-aware operation with a timeout is pointless because nothing will check ctx.Done().

Common bug: returning before defer cancel() is set up. If the decorator returns early without calling cancel, the goroutine that monitors the timeout leaks. defer first, then the call.

Task 13: gRPC unary interceptor (similar pattern)¶

A unary interceptor in gRPC has the signature func(ctx, req, info, handler). It's the gRPC framework's name for a decorator. Build a logging interceptor that wraps a fake gRPC-style handler chain.

type Handler func(ctx context.Context, req any) (any, error)
type Interceptor func(ctx context.Context, req any, info *Info, next Handler) (any, error)

chain := WrapInterceptors(handler, LoggingInterceptor, AuthInterceptor)
chain(ctx, request)

Acceptance criteria

• Handler type: func(ctx context.Context, req any) (any, error).
• Interceptor type: func(ctx, req, info *Info, next Handler) (any, error).
• Info struct holds Method string (the RPC method name).
• LoggingInterceptor: logs method, duration, and result status.
• AuthInterceptor: returns errUnauthenticated if Info.Method requires auth and ctx has no "user" value.
• WrapInterceptors(h Handler, info *Info, ics ...Interceptor) Handler composes interceptors with the first one outermost.
• A test asserts that an authenticated request reaches the handler and an unauthenticated one does not.

package interceptor

import (
    "context"
    "errors"
    "fmt"
    "log"
    "time"
)

type Handler func(ctx context.Context, req any) (any, error)

type Info struct {
    Method string
}

type Interceptor func(ctx context.Context, req any, info *Info, next Handler) (any, error)

var ErrUnauthenticated = errors.New("unauthenticated")

func LoggingInterceptor(ctx context.Context, req any, info *Info, next Handler) (any, error) {
    start := time.Now()
    resp, err := next(ctx, req)
    log.Printf("%s took %s err=%v", info.Method, time.Since(start), err)
    return resp, err
}

func AuthInterceptor(ctx context.Context, req any, info *Info, next Handler) (any, error) {
    if _, ok := ctx.Value("user").(string); !ok {
        return nil, fmt.Errorf("%s: %w", info.Method, ErrUnauthenticated)
    }
    return next(ctx, req)
}

func WrapInterceptors(h Handler, info *Info, ics ...Interceptor) Handler {
    // Compose so that ics[0] is outermost.
    for i := len(ics) - 1; i >= 0; i-- {
        ic := ics[i]
        inner := h
        h = func(ctx context.Context, req any) (any, error) {
            return ic(ctx, req, info, inner)
        }
    }
    return h
}