context Package Best Practices

Team conventions for context keys, timeouts, and shutdown.

Apply these rules in code review, onboarding, and service templates so every handler, repository, and RPC client propagates cancellation consistently.

How to Use This List

• Tick rules as your service template adopts them.
• Encode Tier A items in golangci-lint custom checks or arch unit tests where possible.
• Document per-dependency timeout budgets in README or config next to the rule.
• Revisit quarterly when adding RPC clients or database drivers.

A - Function signatures and propagation

• Accept ctx context.Context as the first parameter on blocking APIs. Reviewers reject new I/O without context.
• Name the parameter ctx, not c or context. Matches Effective Go and staticcheck expectations.
• Pass ctx down unchanged except for intentional child deadlines or values. No fresh Background() mid-request.
• Return ctx.Err() when cancel ends work. Preserve with %w only when adding layer context.
• Replace Query/Exec with *Context variants on request paths. Ban non-context SQL in handlers.

B - HTTP and RPC entry points

• Root handler context at r.Context() or framework equivalent. chi/gin/echo wrappers still map to the request.
• Attach metadata in middleware via r.WithContext. Values and short timeouts wrap the incoming ctx.
• Map context.Canceled without noisy 500s when the response cannot flush. Log at debug for client aborts.
• Use http.NewRequestWithContext for outbound HTTP. Tie dependency lifetime to the caller.
• Pass ctx into gRPC stubs and honor deadlines server-side. Translate to codes.DeadlineExceeded when appropriate.

C - Timeouts and deadlines

• Publish a timeout table per dependency (DB, cache, auth). Shrink budgets at each hop from the edge SLO.
• Derive child timeouts from the parent, never from Background(). Preserves user cancel and upstream clocks.
• Always defer cancel() after WithCancel/WithTimeout/WithDeadline. Prevents timer leaks in tests and prod.
• Cap retries with smaller per-attempt contexts. Stop when the parent ctx is already done.
• Use Shutdown(ctx) with a bounded context on process exit. Pair with signal handling in main.

D - Values and keys

• Define context keys as unexported types in the owning package. Avoid string keys in libraries.
• Limit values to cross-cutting metadata (request ID, principal, locale). Business filters belong in structs.
• Expose typed accessors (User(ctx)) instead of raw Value calls. Keeps key types private.
• Do not store secrets or large blobs in context. Treat context as an in-process concern only.
• Document allowed keys in a package comment or ADR. Onboarding reads one list, not fifty middleware files.

E - Concurrency, testing, and ops

• Select on ctx.Done() in long loops and streams. gRPC Recv/Send loops check each iteration.
• Use context.WithoutCancel only for documented post-response work. Billing and audit are common cases.
• Table-test Canceled and DeadlineExceeded paths. Short timeouts beat time.Sleep in CI.
• Run -race on packages that spawn goroutines per request. Catches ignored cancel races.
• Log remaining deadline budget at service boundaries during debug incidents. Speeds up tail-latency triage.

FAQs

Related

• context.Context: Cancellation as a First-Class API - conceptual anchor
• context Basics - runnable starting examples
• Context Misuse Anti-Patterns - negative patterns to avoid
• Deadlines & Timeouts Across Service Boundaries - timeout table examples
• Testing Code That Accepts context.Context - verify cancel paths

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