Go Context

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