Go Context Usage

context.Context carries security credentials, tracing information, deadlines, and cancellation signals across API and process boundaries. Go programs pass contexts explicitly along the entire function call chain.

Based on Go Wiki CodeReviewComments – Contexts.

Context as First Parameter

Functions that use a Context should accept it as their first parameter:

// Good: Context is first parameter
func F(ctx context.Context, /* other arguments */) error {
    // ...
}

func ProcessRequest(ctx context.Context, req *Request) (*Response, error) {
    // ...
}

This is a strong convention in Go that makes context flow visible and consistent across codebases.

Don’t Store Context in Structs

Do not add a Context member to a struct type. Instead, pass ctx as a parameter to each method that needs it:

// Bad: Context stored in struct
type Worker struct {
    ctx context.Context  // Don't do this
    // ...
}

func (w *Worker) Process() error {
    // Uses w.ctx - context lifetime unclear
}

// Good: Context passed to methods
type Worker struct {
    // ...
}

func (w *Worker) Process(ctx context.Context) error {
    // Context explicitly passed - lifetime clear
}

Exception: Methods whose signature must match an interface in the standard library or a third-party library may need to work around this.

Don’t Create Custom Context Types

Do not create custom Context types or use interfaces other than context.Context in function signatures:

// Bad: Custom context type
type MyContext interface {
    context.Context
    GetUserID() string
}

func Process(ctx MyContext) error { ... }

// Good: Use standard context.Context
func Process(ctx context.Context) error {
    userID := GetUserID(ctx)  // Extract from context value
    // ...
}

Where to Put Application Data

If you have application data to pass around, consider these options in order of preference:

1. Function parameters – Most explicit and type-safe
2. Receiver – For data that belongs to the type
3. Globals – For truly global configuration (use sparingly)
4. Context value – Only if it truly belongs there (request-scoped data)

// Good: Explicit parameter
func ProcessOrder(ctx context.Context, userID string, order *Order) error {
    // userID is explicit
}

// Good: Context value for request-scoped data
func ProcessOrder(ctx context.Context, order *Order) error {
    // Request ID from context is appropriate - it's request-scoped
    reqID := RequestIDFromContext(ctx)
    // ...
}

Context values are appropriate for:

• Request IDs and trace IDs
• Authentication/authorization info that flows with requests
• Deadlines and cancellation signals

Context values are not appropriate for:

• Optional function parameters
• Data that could be passed explicitly
• Configuration that doesn’t vary per-request

Context Immutability

Contexts are immutable. It’s safe to pass the same ctx to multiple calls that share the same deadline, cancellation signal, credentials, and parent trace:

// Good: Same context to multiple calls
func ProcessBatch(ctx context.Context, items []Item) error {
    for _, item := range items {
        // Safe to pass same ctx to each call
        if err := process(ctx, item); err != nil {
            return err
        }
    }
    return nil
}

// Good: Same context to concurrent calls
func ProcessConcurrently(ctx context.Context, a, b *Data) error {
    g, ctx := errgroup.WithContext(ctx)
    g.Go(func() error { return processA(ctx, a) })
    g.Go(func() error { return processB(ctx, b) })
    return g.Wait()
}

When to Use context.Background()

Use context.Background() only for functions that are never request-specific:

// Good: Main function or initialization
func main() {
    ctx := context.Background()
    if err := run(ctx); err != nil {
        log.Fatal(err)
    }
}

// Good: Top-level background task
func startBackgroundWorker() {
    ctx := context.Background()
    go worker(ctx)
}

Default to passing a Context even if you think you don’t need to. Only use context.Background() directly if you have a good reason why passing a context would be a mistake:

// Prefer: Accept context even for "simple" operations
func LoadConfig(ctx context.Context) (*Config, error) {
    // Even if not using ctx now, accepting it allows future
    // additions without API changes
}

Common Patterns

Deriving Contexts

// Add timeout
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()

// Add cancellation
ctx, cancel := context.WithCancel(ctx)
defer cancel()

// Add deadline
ctx, cancel := context.WithDeadline(ctx, time.Now().Add(time.Hour))
defer cancel()

// Add value (use sparingly)
ctx = context.WithValue(ctx, requestIDKey, reqID)

Checking Cancellation

func LongRunningOperation(ctx context.Context) error {
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            // Do work
        }
    }
}

Respecting Cancellation in HTTP Handlers

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    
    result, err := slowOperation(ctx)
    if err != nil {
        if errors.Is(err, context.Canceled) {
            // Client disconnected
            return
        }
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    json.NewEncoder(w).Encode(result)
}

Quick Reference

See Also

• go-concurrency: Goroutine patterns, cancellation, and coordination
• go-error-handling: Handling context cancellation errors
• go-interfaces: Interface design patterns for context-accepting APIs