Go Context Usage

context.Context carries the cancellation, deadline, and request-scoped values for a single unit of work. Pass it explicitly through the entire call chain — never store it, never replace it with Background() mid-flight, never use it as a side-channel for ordinary parameters.

Core Rules

1. `ctx` is the first parameter, named ctx context.Context. No exceptions outside interface stubs imposed by external APIs.
2. Propagate the caller's `ctx` all the way down. Do not start a new tree with context.Background() inside a request path.
3. Do not store `Context` in a struct. Pass it to each method that needs it.
4. Always `defer cancel()` after WithCancel/WithTimeout/WithDeadline, unless ownership is explicitly transferred.
5. Context values are for request-scoped metadata only (request ID, auth principal, trace). Never for optional function parameters or config.
6. Value keys must be unexported named types to prevent cross-package collisions.

Where Does Data Belong?

Pick the most explicit option that fits — context values are the last resort.

Read references/values-and-keys.md for the unexported-key pattern, typed accessors, and OpenTelemetry/trace propagation.

Constructors

Propagation: The One Rule

// Bad — breaks the chain, downstream cannot be cancelled
func (s *OrderService) Create(ctx context.Context, o Order) error {
    return s.db.ExecContext(context.Background(), insertSQL, o.ID)
}

// Good — same ctx flows HTTP handler -> service -> DB -> external API
func (s *OrderService) Create(ctx context.Context, o Order) error {
    return s.db.ExecContext(ctx, insertSQL, o.ID)
}

Deriving and Cancelling

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel() // release resources even on the happy path

select {
case <-ctx.Done():
    return ctx.Err()
case res := <-doAsync(ctx):
    return res
}

Read references/cancellation-and-deadlines.md for WithoutCancel, AfterFunc, and long-running goroutine cancellation patterns.

Don't Wrap Context in Custom Types

// Bad — pollutes the standard signature
type MyCtx interface {
    context.Context
    UserID() string
}

// Good — keep the signature standard, extract via helper
func UserIDFrom(ctx context.Context) (string, bool) { /* ... */ }

Enforce With Linters

Most context mistakes are mechanical and a linter will catch them in CI before review:

• govet -vet=context — flags non-first context.Context parameters and lost cancels.
• staticcheck SA1012 — calls passing nil context.
• contextcheck (golangci-lint) — verifies downstream calls propagate ctx.
• noctx — flags HTTP/SQL APIs called without their *Context variant.

Run golangci-lint run --enable=contextcheck,noctx,staticcheck in CI for any project that exposes context.Context.

Anti-Patterns

Verification Checklist

• [ ] Every function that does I/O, blocks, or calls another ctx-aware API takes ctx context.Context as its first parameter.
• [ ] No context.Context field on any struct (search: ctx\s+context\.Context inside type ... struct).
• [ ] Every WithCancel/WithTimeout/WithDeadline is followed by defer cancel() on the next line.
• [ ] No context.Background() or context.TODO() calls inside request handlers.
• [ ] All context value keys are unexported named types, accessed via typed getters.
• [ ] golangci-lint run --enable=contextcheck,noctx passes.

References

• references/values-and-keys.md — unexported key types, typed accessors, trace propagation
• references/cancellation-and-deadlines.md — timeouts, WithoutCancel, AfterFunc, goroutine cancellation
• references/http-and-db.md — handlers, NewRequestWithContext, QueryContext/ExecContext