The Problem: Orphaned Work#

Imagine a handler that queries three databases in parallel:

1
func handleRequest(w http.ResponseWriter, r *http.Request) {
2
    var wg sync.WaitGroup
3
    wg.Add(3)
4

5
    go func() { defer wg.Done(); queryDB1() }()
6
    go func() { defer wg.Done(); queryDB2() }()
7
    go func() { defer wg.Done(); queryDB3() }()
8

9
    wg.Wait()
10
    // ... respond
11
}

What happens when the client disconnects after 50ms? The goroutines keep running. The databases keep working. Resources burn for a request that will never be answered.

This is the orphaned work problem. And it’s everywhere in concurrent code.

What Context Gives You#

context.Context is a request-scoped value that carries:

1. Cancellation signals: tell goroutines to stop
2. Deadlines: automatic cancellation after a timeout
3. Key-value pairs: request-scoped metadata (trace IDs, user info)

The key insight: context flows down. You create it at the top of a request, pass it to every function and goroutine, and everything respects the same lifecycle.

The Three Flavors#

1
ctx := context.Background()

1
func helper() {
2
    ctx := context.Background() // wrong
3
    db.QueryContext(ctx, ...)
4
}

1
ctx, cancel := context.WithCancel(context.Background())
2
defer cancel() // releases the timer early

1
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
2
defer cancel()

Listening for Cancellation#

A context doesn’t stop goroutines by force. It asks politely. You have to listen:

1
func queryWithContext(ctx context.Context, db *sql.DB) error {
2
    rows, err := db.QueryContext(ctx, "SELECT ...")
3
    if err != nil {
4
        return err
5
    }
6
    defer rows.Close()
7

8
    for rows.Next() {
9
        select {
10
        case <-ctx.Done():
11
            return ctx.Err() // context cancelled
12
        default:
13
            // process row
14
        }
15
    }
16
    return rows.Err()
17
}

db.QueryContext and rows.Next() already watch the context for you: they return context.DeadlineExceeded or context.Canceled as soon as the context is done. The explicit select here is belt-and-suspenders for the body of the row loop, where the driver has handed control back to you.

A common mistake: a goroutine does <-ctx.Done() and silently returns nil. The caller has no idea anything went wrong. Retries pile up, and production logs a vague “intermittent failure.” Wrap the cause with ctx.Err() so the error chain carries the cause back to the source.

The Pattern: Per-Request Context#

In HTTP handlers, the request already carries a context:

1
func handler(w http.ResponseWriter, r *http.Request) {
2
    ctx := r.Context() // use this!
3
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
4
    defer cancel()
5

6
    result, err := service.Process(ctx, r.Body)
7
    if err != nil {
8
        if errors.Is(err, context.DeadlineExceeded) {
9
            http.Error(w, "timeout", http.StatusGatewayTimeout)
10
            return
11
        }
12
        http.Error(w, err.Error(), http.StatusInternalServerError)
13
        return
14
    }
15

16
    json.NewEncoder(w).Encode(result)
17
}

We derive from r.Context() so the timeout context inherits client-disconnect cancellation.

Propagation: The Golden Rule#

Every function that does I/O or spawns goroutines should take context.Context as its first parameter.

This is the convention. Follow it even when you don’t think you need it. The caller knows their constraints better than you do.

Bad:

1
func FetchUser(userID string) (*User, error)

Good:

1
func FetchUser(ctx context.Context, userID string) (*User, error)

Here’s the trap: someone stuffs ctx into a struct field because “this service needs context everywhere”:

1
type Service struct {
2
    ctx context.Context // DON'T
3
}

A Service with a ctx field has an ambiguous lifetime: is the request still alive, or are we holding onto a cancelled context the next call will inherit? Context is a parameter. Keep it out of structs.

Goroutines and Context#

Pass context to every goroutine you spawn. For fan-out work, golang.org/x/sync/errgroup gives you cancellation and error propagation without hand-rolling channel bookkeeping:

1
go get golang.org/x/sync/errgroup

1
func fetchAll(ctx context.Context, urls []string) ([]Result, error) {
2
    g, ctx := errgroup.WithContext(ctx)
3

4
    results := make([]Result, len(urls))
5

6
    g.SetLimit(8) // cap concurrency so we don't hammer the database
7

8
    for i, url := range urls {
9
        idx, u := i, url
10
        g.Go(func() error {
11
            res, err := fetch(ctx, u)
12
            if err != nil {
13
                return err
14
            }
15
            results[idx] = res
16
            return nil
17
        })
18
    }
19

20
    if err := g.Wait(); err != nil {
21
        return nil, err
22
    }
23

24
    return results, nil
25
}

1
for i := 0; i < 1e9; i++ {
2
    if i % 1000 == 0 {
3
        select {
4
        case <-ctx.Done():
5
            return ctx.Err()
6
        default:
7
        }
8
    }
9
    // heavy computation
10
}

Values: Use Sparingly#

Context values carry request-scoped metadata:

1
type contextKey string
2

3
const traceIDKey contextKey = "traceID"
4

5
ctx = context.WithValue(ctx, traceIDKey, traceID)

Access them with a type check:

1
traceID, ok := ctx.Value(traceIDKey).(string)
2
if !ok {
3
    return errors.New("missing trace ID")
4
}

Reach for a context value only when the data is genuinely request-scoped: trace IDs, auth principals, locale, the kind of thing that would otherwise have to be threaded through every function on the call path. Treat the context package as a request-scoped bag. Typed keys prevent collisions, and context should never be the only place something lives.

If a function needs data to do its job, that data is an argument; if it’s just convenient, the context can carry it. Document which keys your code reads. The compiler won’t remind you.

Graceful Shutdown#

A long-running server with thousands of requests and hundreds of goroutines per second needs a way to say “we’re done” and have it propagate through every layer. That’s graceful shutdown: take a SIGTERM, cancel the root context, watch every active request wind down, exit cleanly. Without it, Kubernetes kicks the pod, mid-flight queries get truncated, and the next deploy starts with a cascade of panics from leaked goroutines.

1
func main() {
2
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
3
    defer stop()
4

5
    srv := &http.Server{
6
        Addr:    ":8080",
7
        Handler: http.HandlerFunc(handler),
8
    }
9

10
    go func() {
11
        <-ctx.Done()
12
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second) // fresh root: signal ctx is already cancelled
13
        defer cancel()
14
        if err := srv.Shutdown(shutdownCtx); err != nil {
15
            log.Printf("graceful shutdown failed: %v", err)
16
        }
17
    }()
18

19
    if err := srv.ListenAndServe(); err != http.ErrServerClosed {
20
        log.Fatal(err)
21
    }
22
}

Read this from the bottom up. ListenAndServe blocks until either the server fails or Shutdown is called. The goroutine waits for ctx.Done() (the signal), opens a fresh 30-second timeout context, and walks connections to a clean goodbye via srv.Shutdown. http.ErrServerClosed is the success signal from ListenAndServe; anything else is a real error worth log.Fatal-ing. signal.NotifyContext ties it all to a single cancellation source: the same context flows through handlers, workers, and DB calls.

Testing Cancellation#

The real test for a context-aware function is whether it stops when asked. Returning the right value is table stakes; cancellation is the contract. A 5-line test using context.WithTimeout(ctx, 1*time.Millisecond) and a slow stub is usually enough to prove it. I wrote about testing the boundary in TDD Isn’t About Bugs — It’s Your Permission to Refactor.

Summary#

Context is about scope: every request gets a boundary, every goroutine lives within it, and when the boundary closes, everything inside knows to stop. Pass it from the top down, always derive, always call cancel in a defer. That’s how you build systems that don’t leak memory, connections, or intentions.

Series Navigation#

This article is part of the Go Patterns series:

• Previous: Go Pipeline Pattern: Turning Streams into Useful Data
• Next: Go Goroutines vs C# async/await: Who Carries the Cognitive Load?
• Series: Go Patterns

If you want to experiment with the code examples, you can find them on my GitHub repository.