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
ctx, cancel := context.WithCancel(context.Background())
2
defer cancel() // always call this
3

4
// pass ctx to goroutines
5
// call cancel() when you're done

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
}

The ctx.Done() channel closes when cancellation happens. Checking it in a select gives your goroutine a clean exit path.

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

4
    // add timeout
5
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
6
    defer cancel()
7

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

18
    json.NewEncoder(w).Encode(result)
19
}

Notice how we derive from r.Context() instead of context.Background(). This way, if the client disconnects, our timeout context inherits that 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)

Goroutines and Context#

When you spawn a goroutine, pass it the context:

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

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

22
    return results, nil
23
}

Key points:

• Derive the child context with errgroup.WithContext so we can stop siblings on error
• Pass ctx to fetch() so it can respect cancellation
• g.Wait() waits for every goroutine and returns the first error

Common Mistakes#

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

1
select {
2
case <-ctx.Done():
3
    return nil // what happened?
4
}

1
case <-ctx.Done():
2
    return fmt.Errorf("fetch interrupted: %w", ctx.Err())

1
for i := 0; i < 1e9; i++ {
2
    // heavy computation
3
    // never checks ctx.Done()
4
}

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
}

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

1
func helper(ctx context.Context) {
2
    db.QueryContext(ctx, ...)
3
}

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
}

Rules for values:

• Use for request-scoped data (trace IDs, auth tokens), not application data
• Use typed keys to avoid collisions: type contextKey string
• Don’t use as a replacement for function parameters
• Document what keys your function expects

Graceful Shutdown#

The ultimate cancellation pattern: shutting down a server cleanly.

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)
13
        defer cancel()
14
        srv.Shutdown(shutdownCtx)
15
    }()
16

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

signal.NotifyContext creates a context that cancels on Ctrl+C. We use that to trigger a graceful shutdown with its own timeout.

Summary#

1. Always derive from the caller’s context — never create Background() deep in the stack
2. Pass context as the first parameter — make it obvious and consistent
3. Check ctx.Done() in loops and selects — give your goroutines an exit
4. Call cancel() in defer — clean up resources, prevent leaks
5. Use WithTimeout for external calls — protect against slow dependencies
6. Use values sparingly — they’re convenient but opaque

Context is about scope: every request gets a boundary, every goroutine lives within it, and when the boundary closes, everything inside knows to stop.

That’s how you build systems that don’t leak: memory, connections, or intentions.