Cancellation and deadlines in Go with context.Context

Goal

Make every request-scoped piece of work in a Go service stoppable from the outside, with a bounded lifetime, using the standard library's context package rather than home-grown stop channels.

Prerequisites

The package documentation's rules: a Context is the first parameter, named ctx; it is not stored in a struct; nil is never passed (context.TODO() when unsure); values carry only request-scoped data crossing API boundaries, not optional parameters. Knowledge of which libraries accept a context (net/http requests, database/sql, most clients).

Steps

1. Start from the root: an HTTP handler gets r.Context(), which the net/http documentation says is cancelled when the client's connection closes, when the request is cancelled (HTTP/2) or when ServeHTTP returns; a main or worker creates one with signal.NotifyContext so that SIGTERM cancels it.
2. Derive a child for each bounded operation: ctx, cancel := context.WithTimeout(ctx, 2*time.Second) followed immediately by defer cancel(). The documentation states that failing to call the cancel function leaks the child until the parent is cancelled, and that go vet checks for this.
3. Pass ctx into every call that can block: http.NewRequestWithContext, db.QueryContext, and channel operations wrapped in a select with a case <-ctx.Done().
4. In loops and long computations, check ctx.Err() at iteration boundaries and return it; the value is context.Canceled or context.DeadlineExceeded.
5. When cancelling deliberately, use context.WithCancelCause and record why; callers read it with context.Cause(ctx) (Go 1.20 and later).
6. For work that must outlive the request (an audit write, a cache fill), derive from context.WithoutCancel(ctx) (Go 1.21) so values survive but cancellation does not propagate, and give it its own timeout.
7. Test the cancellation path: cancel a context in the middle of a call and assert that the function returns promptly with an error that wraps ctx.Err().

Expected result

A cancelled request or an expired deadline unwinds the whole call tree; no goroutine keeps querying a database for a client that has gone. Timeouts are set once, near the boundary, and shrink naturally along the chain because a child deadline later than its parent's is ignored.

Limits and test basis

Cancellation is cooperative: code that ignores ctx keeps running until it returns on its own, and a CPU-bound loop that never checks ctx.Err() is not interrupted. The steps follow the cited package documentation and the Go blog's introduction; no timing claims are made.

Shutdown is not cancellation

The context from signal.NotifyContext should trigger the stop, not be the parent of every request. Wiring it into http.Server.BaseContext cancels all in-flight requests the moment SIGTERM arrives, which is the failure burst a graceful stop exists to avoid. Instead, wait for the signal context, then call srv.Shutdown(shutdownCtx) with a fresh context.WithTimeout(context.Background(), 20*time.Second): the server stops accepting, and active requests keep their own contexts until they return or the deadline passes. Use the signal context directly only for work that should stop at once: queue consumers, polling loops, background schedulers. Shutdown does not wait for hijacked connections such as WebSockets; close those from a RegisterOnShutdown callback.