Fail-Fast — Practice Tasks¶

package pricing

import (
    "fmt"
    "math"
)

// Senior decision: this is a domain function called from HTTP, CLI, and
// internal batch code. All three sources can produce bad input. Returning
// an error (not panicking) lets every caller decide policy — HTTP returns
// 400, CLI prints a usage line, batch logs and skips. Panicking would
// force all three to wrap calls in recover, which is worse than the
// branch-on-error they already have to write.
func Discount(price float64, percent int) (float64, error) {
    if math.IsNaN(price) || math.IsInf(price, 0) {
        return 0, fmt.Errorf("discount: price must be finite, got %v", price)
    }
    if price < 0 {
        return 0, fmt.Errorf("discount: price must be >= 0, got %v", price)
    }
    if percent < 0 || percent > 100 {
        return 0, fmt.Errorf("discount: percent must be in [0,100], got %d", percent)
    }
    // Senior decision: every assumption is now checked. The body cannot
    // produce a negative number unless price overflows, which the IsInf
    // guard rules out. Past this line the code is "trusted".
    discount := price * float64(percent) / 100
    return price - discount, nil
}

package validate

import (
    "errors"
    "fmt"
    "strings"
)

// Senior decision: sentinel + wrap. The HTTP layer wants
// errors.Is(err, ErrInvalidEmail) to map to 400. The metrics layer wants
// to count "invalid email" without parsing a string. Sentinel-with-wrap
// gives both for the cost of one variable.
var ErrInvalidEmail = errors.New("invalid email")

const maxEmailLen = 254 // RFC 5321 SMTP path limit

func ValidateEmail(s string) error {
    if s == "" {
        return fmt.Errorf("%w: empty", ErrInvalidEmail)
    }
    if len(s) > maxEmailLen {
        // Senior decision: length check before scanning. An adversary
        // sending a 1 MB string should be rejected in O(1), not after
        // we walk it counting '@'.
        return fmt.Errorf("%w: too long (%d > %d)", ErrInvalidEmail, len(s), maxEmailLen)
    }
    if strings.TrimSpace(s) != s {
        return fmt.Errorf("%w: leading or trailing whitespace", ErrInvalidEmail)
    }
    at := strings.Count(s, "@")
    if at != 1 {
        return fmt.Errorf("%w: must contain exactly one '@' (got %d)", ErrInvalidEmail, at)
    }
    local, domain, _ := strings.Cut(s, "@")
    if local == "" {
        return fmt.Errorf("%w: empty local part", ErrInvalidEmail)
    }
    if domain == "" {
        return fmt.Errorf("%w: empty domain", ErrInvalidEmail)
    }
    if !strings.Contains(domain, ".") {
        return fmt.Errorf("%w: domain missing '.'", ErrInvalidEmail)
    }
    return nil
}

var _ = errors.Is // keep import if trimmed elsewhere

package httpapi

import (
    "encoding/json"
    "fmt"
    "net/http"
    "strings"
)

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
}

func createUserHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        w.Header().Set("Allow", "POST")
        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
        return
    }
    // Senior decision: enforce Content-Type at the gate. A client sending
    // form-encoded bytes with our JSON struct tags would otherwise hit
    // confusing decode errors deep inside json.Decoder.
    if ct := r.Header.Get("Content-Type"); !strings.HasPrefix(ct, "application/json") {
        http.Error(w, "Content-Type must be application/json", http.StatusUnsupportedMediaType)
        return
    }
    // Senior decision: cap the body. An attacker shouldn't be able to
    // OOM us with a 10 GiB JSON payload before validation runs.
    r.Body = http.MaxBytesReader(w, r.Body, 1<<20)

    var req CreateUserRequest
    dec := json.NewDecoder(r.Body)
    dec.DisallowUnknownFields()
    if err := dec.Decode(&req); err != nil {
        http.Error(w, fmt.Sprintf("invalid JSON: %v", err), http.StatusBadRequest)
        return
    }
    if req.Name == "" {
        http.Error(w, "name: required", http.StatusBadRequest)
        return
    }
    if len(req.Name) > 100 {
        http.Error(w, "name: too long (max 100)", http.StatusBadRequest)
        return
    }
    if err := ValidateEmail(req.Email); err != nil {
        http.Error(w, "email: "+err.Error(), http.StatusBadRequest)
        return
    }
    if req.Age < 0 || req.Age > 150 {
        http.Error(w, fmt.Sprintf("age: must be in [0,150], got %d", req.Age), http.StatusBadRequest)
        return
    }
    // Senior decision: createUser receives a fully-validated struct.
    // It does NOT re-validate. The handler is the boundary; the service
    // layer trusts the handler. Re-validating everywhere kills perf and
    // doubles the surface area where the rules can drift.
    if err := createUser(req); err != nil {
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

func createUser(req CreateUserRequest) error { return nil }

// ValidateEmail from Task 2.
func ValidateEmail(s string) error { return nil }

package urls

import (
    "fmt"
    "net/url"
)

func ParseURL(s string) (*url.URL, error) {
    u, err := url.Parse(s)
    if err != nil {
        return nil, fmt.Errorf("parse url %q: %w", s, err)
    }
    if u.Scheme == "" || u.Host == "" {
        // Senior decision: url.Parse accepts almost anything — even an
        // empty string parses without error. Fail-Fast means we add the
        // "must look like an absolute URL" check ourselves.
        return nil, fmt.Errorf("parse url %q: missing scheme or host", s)
    }
    return u, nil
}

// Senior decision: MustParseURL is a startup-only convenience. It panics
// because the only legitimate caller is package init where a malformed
// constant is a programmer bug, not user input. Same exact contract as
// template.Must — don't reinvent the convention.
func MustParseURL(s string) *url.URL {
    u, err := ParseURL(s)
    if err != nil {
        panic("MustParseURL: " + err.Error())
    }
    return u
}

// Example uses:
//
//   var defaultAPI = urls.MustParseURL("https://api.example.com/v1")
//        // OK — constant, validated once at startup.
//
//   func handle(target string) {
//       u, err := urls.ParseURL(target)
//        // OK — user input, recoverable.
//       if err != nil { /* ... */ }
//   }
//
//   var x = urls.MustParseURL(os.Getenv("API_URL"))
//        // NOT OK — runtime input + panic. Move to main with a real
//        // error path.

package validate

import (
    "errors"
    "fmt"
    "strings"
)

// Senior decision: typed errors over string matching. When you have ten
// fields and three layers (handler, service, DB) all generating errors,
// "string contains 'email'" patterns break the moment someone changes a
// log line. A typed error survives refactors and supports structured
// logging directly.
type ValidationError struct {
    Field  string
    Reason string
}

func (v *ValidationError) Error() string {
    return fmt.Sprintf("field %q: %s", v.Field, v.Reason)
}

type ValidationErrors []*ValidationError

func (v ValidationErrors) Error() string {
    if len(v) == 0 {
        return "no validation errors"
    }
    parts := make([]string, len(v))
    for i, e := range v {
        parts[i] = e.Error()
    }
    return strings.Join(parts, "; ")
}

// Senior decision: Unwrap returning []error lets errors.As/Is recurse
// into the slice. Without this the outer ValidationErrors is opaque to
// the stdlib walker — callers can't ask "did any of these mention the
// email field?" structurally.
func (v ValidationErrors) Unwrap() []error {
    out := make([]error, len(v))
    for i, e := range v {
        out[i] = e
    }
    return out
}

// Convenience constructor.
func NewVE(field, reason string) *ValidationError {
    return &ValidationError{Field: field, Reason: reason}
}

var _ = errors.As // keep import if trimmed elsewhere

// Example use:
//
//   var verrs ValidationErrors
//   if req.Name == "" {
//       verrs = append(verrs, NewVE("name", "required"))
//   }
//   if err := ValidateEmail(req.Email); err != nil {
//       verrs = append(verrs, NewVE("email", err.Error()))
//   }
//   if len(verrs) > 0 { return verrs }
//
//   // Caller:
//   var ve *ValidationError
//   if errors.As(err, &ve) {
//       log.Printf("field=%s reason=%s", ve.Field, ve.Reason)
//   }

package validate

import (
    "errors"
    "fmt"
)

type Validator[T any] interface {
    Validate(T) error
}

type User struct {
    Email string
    Age   int
}

type UserValidator struct{}

func (UserValidator) Validate(u User) error {
    if err := ValidateEmail(u.Email); err != nil {
        return fmt.Errorf("user: %w", err)
    }
    if u.Age < 0 || u.Age > 150 {
        return fmt.Errorf("user: age out of range: %d", u.Age)
    }
    return nil
}

type Order struct {
    SKU      string
    Quantity int
}

type OrderValidator struct{}

func (OrderValidator) Validate(o Order) error {
    if o.SKU == "" {
        return errors.New("order: sku required")
    }
    if o.Quantity <= 0 {
        return fmt.Errorf("order: quantity must be > 0, got %d", o.Quantity)
    }
    return nil
}

// Senior decision: RunAll fails fast on the first bad item and tells you
// the index. Alternative (collect all errors) is a separate function —
// RunAllCollect — because the caller knows which behaviour they need.
// Mixing both into one function with a bool flag is the classic flag
// argument code smell.
func RunAll[T any](v Validator[T], items []T) error {
    for i, item := range items {
        if err := v.Validate(item); err != nil {
            return fmt.Errorf("item %d: %w", i, err)
        }
    }
    return nil
}

func RunAllCollect[T any](v Validator[T], items []T) error {
    var verrs ValidationErrors
    for i, item := range items {
        if err := v.Validate(item); err != nil {
            verrs = append(verrs, NewVE(fmt.Sprintf("item[%d]", i), err.Error()))
        }
    }
    if len(verrs) > 0 {
        return verrs
    }
    return nil
}

package validate

import "fmt"

type Mode int

const (
    FailFast Mode = iota
    Collect
)

type Chain[T any] struct {
    validators []Validator[T]
    mode       Mode
}

func NewChain[T any](mode Mode, vs ...Validator[T]) *Chain[T] {
    return &Chain[T]{validators: vs, mode: mode}
}

// Senior decision: Chain itself implements Validator. This lets you nest
// chains (basic checks then expensive checks) and pass the result to
// RunAll. The pattern composes; the API doesn't grow.
func (c *Chain[T]) Validate(t T) error {
    switch c.mode {
    case FailFast:
        for i, v := range c.validators {
            if err := v.Validate(t); err != nil {
                return fmt.Errorf("validator[%d]: %w", i, err)
            }
        }
        return nil
    case Collect:
        var verrs ValidationErrors
        for i, v := range c.validators {
            if err := v.Validate(t); err != nil {
                verrs = append(verrs, NewVE(
                    fmt.Sprintf("validator[%d]", i),
                    err.Error(),
                ))
            }
        }
        if len(verrs) > 0 {
            return verrs
        }
        return nil
    default:
        return fmt.Errorf("chain: unknown mode %d", c.mode)
    }
}

// Real-world chain:
//
//   user := NewChain[User](FailFast,
//       requiredFields{},     // cheap
//       emailFormat{},        // cheap
//       passwordStrength{},   // cheap
//   )
//   serverSide := NewChain[User](FailFast,
//       user,                  // run all cheap checks first
//       emailNotTaken{db: db}, // expensive — DB hit
//   )
//
// Senior decision: order the chain by COST. Cheap checks first. By the
// time the expensive ones run, you've already rejected 95% of bad input
// at near-zero cost. Reversing the order is one of the most common
// undetected perf bugs in validation code.

package validate

import (
    "fmt"
    "reflect"
    "strconv"
    "strings"
)

// Senior decision: Collect mode by default. Tag-driven validators almost
// always front a form; the user wants every wrong field highlighted at
// once. The few API-style callers can wrap in their own first-error
// adaptor — this matches go-playground/validator's choice for the same
// reason.
func ValidateStruct(v any) error {
    rv := reflect.ValueOf(v)
    if rv.Kind() == reflect.Pointer {
        rv = rv.Elem()
    }
    if rv.Kind() != reflect.Struct {
        // Senior decision: this is a PROGRAMMER error — passing a
        // non-struct to a struct validator. Panic, don't return error.
        // No production code path should ever get here with anything but
        // a struct.
        panic(fmt.Sprintf("ValidateStruct: expected struct, got %s", rv.Kind()))
    }
    var verrs ValidationErrors
    rt := rv.Type()
    for i := 0; i < rt.NumField(); i++ {
        sf := rt.Field(i)
        tag, ok := sf.Tag.Lookup("validate")
        if !ok {
            continue
        }
        fv := rv.Field(i)
        if err := applyRules(sf.Name, fv, tag); err != nil {
            verrs = append(verrs, NewVE(sf.Name, err.Error()))
        }
    }
    if len(verrs) > 0 {
        return verrs
    }
    return nil
}

func applyRules(name string, fv reflect.Value, tag string) error {
    for _, rule := range strings.Split(tag, ",") {
        rule = strings.TrimSpace(rule)
        if rule == "" {
            continue
        }
        key, val, _ := strings.Cut(rule, "=")
        switch key {
        case "required":
            if fv.IsZero() {
                return fmt.Errorf("required")
            }
        case "min":
            n, err := strconv.Atoi(val)
            if err != nil {
                return fmt.Errorf("bad rule min=%q", val)
            }
            if err := minCheck(fv, n); err != nil {
                return err
            }
        case "max":
            n, err := strconv.Atoi(val)
            if err != nil {
                return fmt.Errorf("bad rule max=%q", val)
            }
            if err := maxCheck(fv, n); err != nil {
                return err
            }
        default:
            return fmt.Errorf("unknown rule %q", key)
        }
    }
    return nil
}

func minCheck(fv reflect.Value, n int) error {
    switch fv.Kind() {
    case reflect.String:
        if len(fv.String()) < n {
            return fmt.Errorf("length must be >= %d", n)
        }
    case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
        if fv.Int() < int64(n) {
            return fmt.Errorf("must be >= %d", n)
        }
    default:
        return fmt.Errorf("min not supported on %s", fv.Kind())
    }
    return nil
}

func maxCheck(fv reflect.Value, n int) error {
    switch fv.Kind() {
    case reflect.String:
        if len(fv.String()) > n {
            return fmt.Errorf("length must be <= %d", n)
        }
    case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
        if fv.Int() > int64(n) {
            return fmt.Errorf("must be <= %d", n)
        }
    default:
        return fmt.Errorf("max not supported on %s", fv.Kind())
    }
    return nil
}

// Example:
//   type SignUp struct {
//       Username string `validate:"required,min=3,max=32"`
//       Age      int    `validate:"required,min=13,max=120"`
//   }
//   err := ValidateStruct(SignUp{Username: "ab"})
//   // returns ValidationErrors: field "Username": length must be >= 3
//   //                           field "Age": required

package compute

import "context"

// Senior decision: check ctx.Err() every 1024 iterations, not every one.
// On a hot loop, the check itself shows up in profiles. 1024 is small
// enough that we respond to cancellation within milliseconds for any
// realistic per-iteration work, and large enough that the check is
// noise.
const cancelCheckInterval = 1024

func Sum(ctx context.Context, nums []int) (int, error) {
    // Senior decision: cheap up-front check. If the caller already
    // cancelled, don't even start. This is the purest form of Fail-Fast:
    // detect "no longer wanted" before spending a cycle.
    if err := ctx.Err(); err != nil {
        return 0, err
    }
    var sum int
    for i, n := range nums {
        if i%cancelCheckInterval == 0 && i > 0 {
            if err := ctx.Err(); err != nil {
                return 0, err
            }
        }
        sum += n
    }
    return sum, nil
}

// Test sketch:
//   func TestSumCancels(t *testing.T) {
//       ctx, cancel := context.WithCancel(context.Background())
//       cancel() // pre-cancelled
//       _, err := Sum(ctx, make([]int, 1_000_000))
//       if !errors.Is(err, context.Canceled) {
//           t.Fatalf("want Canceled, got %v", err)
//       }
//   }
//
//   func TestSumRespectsDeadline(t *testing.T) {
//       ctx, cancel := context.WithTimeout(context.Background(), 1*time.Microsecond)
//       defer cancel()
//       _, err := Sum(ctx, make([]int, 100_000_000))
//       if !errors.Is(err, context.DeadlineExceeded) {
//           t.Fatalf("want DeadlineExceeded, got %v", err)
//       }
//   }

package grpcvalidate

import (
    "context"

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

// Senior decision: define the interface locally rather than importing
// the validator runtime. Loose coupling — any message that implements
// Validate() can be checked, including hand-written ones. We pay zero
// extra dependencies for that flexibility.
type validator interface {
    Validate() error
}

// Senior decision: an extended variant exists too: ValidateAll() returns
// a multi-error. Some teams prefer that for form-style RPCs. We default
// to fail-fast Validate() because gRPC clients are typically machines,
// not humans filling in a form. Aggregating errors costs allocations
// every call.
type validatorAll interface {
    ValidateAll() error
}

func UnaryInterceptor() grpc.UnaryServerInterceptor {
    return func(
        ctx context.Context,
        req any,
        info *grpc.UnaryServerInfo,
        handler grpc.UnaryHandler,
    ) (any, error) {
        // Senior decision: check ctx.Err() before paying for the
        // type assertion. If the client gave up while we were queued,
        // dump the request now.
        if err := ctx.Err(); err != nil {
            return nil, status.Error(codes.Canceled, err.Error())
        }
        if v, ok := req.(validator); ok {
            if err := v.Validate(); err != nil {
                // Senior decision: codes.InvalidArgument is the only
                // semantically correct mapping. Internal, Unknown, or
                // FailedPrecondition would mislead clients into
                // retrying — they won't succeed by retrying with the
                // same bad payload.
                return nil, status.Error(codes.InvalidArgument, err.Error())
            }
        }
        return handler(ctx, req)
    }
}

// StreamInterceptor variant — same idea, validates each message read.
func StreamInterceptor() grpc.StreamServerInterceptor {
    return func(
        srv any,
        ss grpc.ServerStream,
        info *grpc.StreamServerInfo,
        handler grpc.StreamHandler,
    ) error {
        wrapped := &validatingStream{ServerStream: ss}
        return handler(srv, wrapped)
    }
}

type validatingStream struct{ grpc.ServerStream }

func (v *validatingStream) RecvMsg(m any) error {
    if err := v.ServerStream.RecvMsg(m); err != nil {
        return err
    }
    if val, ok := m.(validator); ok {
        if err := val.Validate(); err != nil {
            return status.Error(codes.InvalidArgument, err.Error())
        }
    }
    return nil
}

var _ validatorAll = (*dummyAll)(nil)

type dummyAll struct{}

func (dummyAll) ValidateAll() error { return nil }

package middleware

import (
    "context"
    "net/http"
)

// Senior decision: unexported context key type. A string key would let
// any package overwrite it; an exported type would let any package
// fabricate one. ctxKey is the standard idiom — read it in the stdlib
// http/server.go for the prior art.
type ctxKey int

const (
    keyRequestID ctxKey = iota
    keyTenantID
)

func RequireHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        reqID := r.Header.Get("X-Request-ID")
        if reqID == "" {
            http.Error(w, "missing X-Request-ID", http.StatusBadRequest)
            return
        }
        if len(reqID) > 128 {
            // Senior decision: cap header length. Otherwise an attacker
            // can store arbitrary bytes in context and blow up downstream
            // log fields.
            http.Error(w, "X-Request-ID too long", http.StatusBadRequest)
            return
        }
        tenantID := r.Header.Get("X-Tenant-ID")
        if tenantID == "" {
            http.Error(w, "missing X-Tenant-ID", http.StatusBadRequest)
            return
        }
        if len(tenantID) > 64 {
            http.Error(w, "X-Tenant-ID too long", http.StatusBadRequest)
            return
        }
        ctx := r.Context()
        ctx = context.WithValue(ctx, keyRequestID, reqID)
        ctx = context.WithValue(ctx, keyTenantID, tenantID)
        // Senior decision: also echo X-Request-ID on the response so the
        // client can correlate. Free, and downstream operators thank you.
        w.Header().Set("X-Request-ID", reqID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// Typed extractors — callers never touch ctx.Value directly.
func RequestID(ctx context.Context) string {
    v, _ := ctx.Value(keyRequestID).(string)
    return v
}

func TenantID(ctx context.Context) string {
    v, _ := ctx.Value(keyTenantID).(string)
    return v
}

// Senior decision: MustRequestID panics if absent. Use in handlers wired
// behind RequireHeaders — if it ever returns "" there it's a wiring bug,
// not a runtime condition.
func MustRequestID(ctx context.Context) string {
    v := RequestID(ctx)
    if v == "" {
        panic("middleware: RequestID missing from context — wiring bug")
    }
    return v
}

package breaker

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

type State int

const (
    Closed State = iota
    Open
    HalfOpen
)

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

type Breaker struct {
    failuresToOpen int
    cooldown       time.Duration

    mu       sync.Mutex
    state    State
    failures int
    openedAt time.Time
}

func New(failuresToOpen int, cooldown time.Duration) *Breaker {
    if failuresToOpen <= 0 {
        panic("breaker: failuresToOpen must be > 0")
    }
    if cooldown <= 0 {
        panic("breaker: cooldown must be > 0")
    }
    return &Breaker{
        failuresToOpen: failuresToOpen,
        cooldown:       cooldown,
        state:          Closed,
    }
}

func (b *Breaker) Do(ctx context.Context, fn func(context.Context) error) error {
    if err := b.preflight(); err != nil {
        // Senior decision: this is the Fail-Fast pay-off. Open state
        // skips the wrapped call entirely. Downstream gets to recover;
        // we don't waste a timeout on a service we know is sick.
        return err
    }
    err := fn(ctx)
    b.record(err)
    return err
}

func (b *Breaker) preflight() error {
    b.mu.Lock()
    defer b.mu.Unlock()
    switch b.state {
    case Closed:
        return nil
    case Open:
        if time.Since(b.openedAt) < b.cooldown {
            return ErrOpen
        }
        // Senior decision: cooldown elapsed -> HalfOpen, let ONE call
        // through. Concurrent calls in this window race the mutex; only
        // the first sees HalfOpen and proceeds, the rest see Open again.
        b.state = HalfOpen
        return nil
    case HalfOpen:
        // Another call is currently probing — fail fast for everyone else.
        return ErrOpen
    }
    return nil
}

func (b *Breaker) record(err error) {
    b.mu.Lock()
    defer b.mu.Unlock()
    if err != nil {
        b.failures++
        if b.state == HalfOpen || b.failures >= b.failuresToOpen {
            b.state = Open
            b.openedAt = time.Now()
        }
        return
    }
    // Success — reset.
    b.failures = 0
    b.state = Closed
}

// Caller pattern:
//   err := br.Do(ctx, func(ctx context.Context) error {
//       return httpClient.Get(ctx, url)
//   })
//   switch {
//   case errors.Is(err, breaker.ErrOpen):
//       // fail fast — return cached result or 503, do NOT retry the
//       // same downstream; it's known sick.
//   case err != nil:
//       // real error — log, maybe retry once.
//   }

package idempotency

import (
    "bytes"
    "context"
    "net/http"
    "sync"
    "time"
)

type state int

const (
    stateInflight state = iota
    stateCompleted
)

type entry struct {
    state   state
    expires time.Time
    status  int
    body    []byte
    headers http.Header
}

type Store struct {
    ttl time.Duration
    mu  sync.Mutex
    m   map[string]*entry
}

func New(ttl time.Duration) *Store {
    if ttl <= 0 {
        panic("idempotency: ttl must be > 0")
    }
    s := &Store{ttl: ttl, m: map[string]*entry{}}
    go s.janitor(context.Background())
    return s
}

func (s *Store) janitor(ctx context.Context) {
    // Senior decision: single janitor sweeps the whole map. A timer per
    // entry would be O(keys) goroutines and a heap; one ticker is O(1).
    t := time.NewTicker(s.ttl / 2)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return
        case now := <-t.C:
            s.mu.Lock()
            for k, e := range s.m {
                if now.After(e.expires) {
                    delete(s.m, k)
                }
            }
            s.mu.Unlock()
        }
    }
}

func (s *Store) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Method != http.MethodPost {
            next.ServeHTTP(w, r)
            return
        }
        key := r.Header.Get("Idempotency-Key")
        if key == "" {
            // Senior decision: REQUIRE the header on POST. Optional
            // idempotency keys are a foot-shooting interface — callers
            // forget, retry double-charges. Stripe's API enforces this
            // for the same reason.
            http.Error(w, "Idempotency-Key required", http.StatusBadRequest)
            return
        }
        if len(key) > 128 {
            http.Error(w, "Idempotency-Key too long", http.StatusBadRequest)
            return
        }

        s.mu.Lock()
        if e, ok := s.m[key]; ok && time.Now().Before(e.expires) {
            switch e.state {
            case stateInflight:
                s.mu.Unlock()
                // Senior decision: 409 for in-flight, not "wait and
                // return the result". Waiting holds an HTTP connection
                // open indefinitely; failing fast lets the client poll
                // with the same key after a backoff.
                http.Error(w, "request with this key is in flight", http.StatusConflict)
                return
            case stateCompleted:
                defer s.mu.Unlock()
                for k, vs := range e.headers {
                    for _, v := range vs {
                        w.Header().Add(k, v)
                    }
                }
                w.WriteHeader(e.status)
                _, _ = w.Write(e.body)
                return
            }
        }
        // Mark in-flight under the lock so concurrent retries see it.
        s.m[key] = &entry{
            state:   stateInflight,
            expires: time.Now().Add(s.ttl),
        }
        s.mu.Unlock()

        rec := &recorder{ResponseWriter: w, body: &bytes.Buffer{}, headers: http.Header{}}
        next.ServeHTTP(rec, r)

        s.mu.Lock()
        s.m[key] = &entry{
            state:   stateCompleted,
            expires: time.Now().Add(s.ttl),
            status:  rec.status,
            body:    rec.body.Bytes(),
            headers: rec.headers,
        }
        s.mu.Unlock()
    })
}

type recorder struct {
    http.ResponseWriter
    status  int
    body    *bytes.Buffer
    headers http.Header
}

func (r *recorder) WriteHeader(code int) {
    r.status = code
    for k, v := range r.ResponseWriter.Header() {
        r.headers[k] = v
    }
    r.ResponseWriter.WriteHeader(code)
}

func (r *recorder) Write(b []byte) (int, error) {
    if r.status == 0 {
        r.status = http.StatusOK
    }
    r.body.Write(b)
    return r.ResponseWriter.Write(b)
}