Skip to main content

​
The Context Package

The context package is essential for production Go. It provides a standardized way to carry deadlines, cancellation signals, and request-scoped values across API boundaries and between goroutines. Think of context as a “request passport” that travels with every function call in a request’s lifecycle. When a user cancels their browser request, that cancellation ripples through your HTTP handler, down to your database query, and out to any external API calls — all because each layer checks the same context. Without context, you would need to manually wire cancellation signals through every function, which is error-prone and messy.

​
Why Context?

In real-world applications, you need to:
  • Cancel operations when a client disconnects
  • Set timeouts for database queries, HTTP requests
  • Pass request-scoped data like request IDs, user info
  • Propagate cancellation through a chain of function calls
Without context, you’d need to implement these features manually for every function.

​
Context Basics

​
The Context Interface

type Context interface {
    // Deadline returns the time when work should be cancelled
    Deadline() (deadline time.Time, ok bool)
    
    // Done returns a channel that's closed when work should be cancelled
    Done() <-chan struct{}
    
    // Err returns why the context was cancelled
    Err() error
    
    // Value returns the value associated with a key
    Value(key interface{}) interface{}
}

​
Creating Contexts

// Background context - the root of any context tree
ctx := context.Background()

// TODO context - use when unsure which context to use (placeholder)
ctx := context.TODO()

​
Cancellation

​
context.WithCancel

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    
    go worker(ctx)
    
    time.Sleep(3 * time.Second)
    cancel() // Signal worker to stop
    
    time.Sleep(1 * time.Second) // Give worker time to clean up
}

func worker(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("Worker: Received cancellation signal")
            fmt.Println("Worker: Reason:", ctx.Err())
            return
        default:
            fmt.Println("Worker: Working...")
            time.Sleep(500 * time.Millisecond)
        }
    }
}

​
Cancellation Propagation

Child contexts are cancelled when their parent is cancelled: 
func main() {
    parent, parentCancel := context.WithCancel(context.Background())
    
    child1, _ := context.WithCancel(parent)
    child2, _ := context.WithCancel(parent)
    
    go func() {
        <-child1.Done()
        fmt.Println("Child 1 cancelled")
    }()
    
    go func() {
        <-child2.Done()
        fmt.Println("Child 2 cancelled")
    }()
    
    parentCancel() // Cancels parent AND both children
    time.Sleep(100 * time.Millisecond)
}

​
Timeouts and Deadlines

​
context.WithTimeout

func fetchWithTimeout(url string) ([]byte, error) {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel() // Always call cancel to release resources
    
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, err
    }
    
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        if ctx.Err() == context.DeadlineExceeded {
            return nil, fmt.Errorf("request timed out after 5 seconds")
        }
        return nil, err
    }
    defer resp.Body.Close()
    
    return io.ReadAll(resp.Body)
}

​
context.WithDeadline

func processOrder(orderID string) error {
    // Must complete by midnight
    midnight := time.Now().Truncate(24 * time.Hour).Add(24 * time.Hour)
    ctx, cancel := context.WithDeadline(context.Background(), midnight)
    defer cancel()
    
    return processOrderWithContext(ctx, orderID)
}

​
Checking Deadline

func longOperation(ctx context.Context) error {
    deadline, hasDeadline := ctx.Deadline()
    if hasDeadline {
        remaining := time.Until(deadline)
        if remaining < time.Minute {
            return errors.New("not enough time to complete operation")
        }
        fmt.Printf("Have %v to complete operation\n", remaining)
    }
    
    // Do work...
    return nil
}

​
Context Values

​
Storing and Retrieving Values

type contextKey string

const (
    requestIDKey contextKey = "requestID"
    userIDKey    contextKey = "userID"
)

func main() {
    ctx := context.Background()
    ctx = context.WithValue(ctx, requestIDKey, "req-123")
    ctx = context.WithValue(ctx, userIDKey, "user-456")
    
    handleRequest(ctx)
}

func handleRequest(ctx context.Context) {
    requestID := ctx.Value(requestIDKey).(string)
    userID := ctx.Value(userIDKey).(string)
    
    fmt.Printf("Request %s by user %s\n", requestID, userID)
}

​
Type-Safe Context Values

type RequestContext struct {
    RequestID string
    UserID    string
    TraceID   string
    StartTime time.Time
}

type requestContextKey struct{}

func WithRequestContext(ctx context.Context, rc *RequestContext) context.Context {
    return context.WithValue(ctx, requestContextKey{}, rc)
}

func GetRequestContext(ctx context.Context) (*RequestContext, bool) {
    rc, ok := ctx.Value(requestContextKey{}).(*RequestContext)
    return rc, ok
}

// Usage
func handler(w http.ResponseWriter, r *http.Request) {
    rc := &RequestContext{
        RequestID: uuid.New().String(),
        UserID:    getUserID(r),
        TraceID:   r.Header.Get("X-Trace-ID"),
        StartTime: time.Now(),
    }
    
    ctx := WithRequestContext(r.Context(), rc)
    processRequest(ctx)
}

func processRequest(ctx context.Context) {
    if rc, ok := GetRequestContext(ctx); ok {
        log.Printf("[%s] Processing request for user %s", rc.RequestID, rc.UserID)
    }
}

​
Context in HTTP Servers

​
Request Context

Every http.Request carries a context: 
func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context() // Already has deadline if client sets timeout
    
    result, err := doExpensiveOperation(ctx)
    if err != nil {
        if ctx.Err() == context.Canceled {
            // Client disconnected
            log.Println("Client disconnected")
            return
        }
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    json.NewEncoder(w).Encode(result)
}

func doExpensiveOperation(ctx context.Context) (*Result, error) {
    resultCh := make(chan *Result, 1)
    errCh := make(chan error, 1)
    
    go func() {
        // Long running operation
        result, err := queryDatabase()
        if err != nil {
            errCh <- err
            return
        }
        resultCh <- result
    }()
    
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    case err := <-errCh:
        return nil, err
    case result := <-resultCh:
        return result, nil
    }
}

​
Adding Request Timeout

func timeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            ctx, cancel := context.WithTimeout(r.Context(), timeout)
            defer cancel()
            
            r = r.WithContext(ctx)
            
            done := make(chan struct{})
            go func() {
                next.ServeHTTP(w, r)
                close(done)
            }()
            
            select {
            case <-done:
                return
            case <-ctx.Done():
                http.Error(w, "Request timeout", http.StatusGatewayTimeout)
            }
        })
    }
}

​
Context in Database Operations

​
With sql.DB

func (r *UserRepository) GetUser(ctx context.Context, id string) (*User, error) {
    query := "SELECT id, name, email FROM users WHERE id = $1"
    
    row := r.db.QueryRowContext(ctx, query, id)
    
    var user User
    if err := row.Scan(&user.ID, &user.Name, &user.Email); err != nil {
        if ctx.Err() == context.DeadlineExceeded {
            return nil, fmt.Errorf("database query timed out: %w", err)
        }
        return nil, err
    }
    
    return &user, nil
}

func (r *UserRepository) CreateUser(ctx context.Context, user *User) error {
    query := "INSERT INTO users (id, name, email) VALUES ($1, $2, $3)"
    
    _, err := r.db.ExecContext(ctx, query, user.ID, user.Name, user.Email)
    return err
}

​
Transaction with Context

func (r *OrderRepository) CreateOrder(ctx context.Context, order *Order) error {
    tx, err := r.db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    
    defer func() {
        if err != nil {
            tx.Rollback()
        }
    }()
    
    // Insert order
    _, err = tx.ExecContext(ctx,
        "INSERT INTO orders (id, user_id, total) VALUES ($1, $2, $3)",
        order.ID, order.UserID, order.Total,
    )
    if err != nil {
        return err
    }
    
    // Insert order items
    for _, item := range order.Items {
        _, err = tx.ExecContext(ctx,
            "INSERT INTO order_items (order_id, product_id, quantity) VALUES ($1, $2, $3)",
            order.ID, item.ProductID, item.Quantity,
        )
        if err != nil {
            return err
        }
    }
    
    return tx.Commit()
}

​
Context Best Practices

​
DO’s

// ✅ Pass context as the first parameter
func ProcessOrder(ctx context.Context, orderID string) error

// ✅ Use context.Background() at the top of main, tests, and init
func main() {
    ctx := context.Background()
    run(ctx)
}

// ✅ Always call cancel when done
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()

// ✅ Check ctx.Done() in long-running loops
for {
    select {
    case <-ctx.Done():
        return ctx.Err()
    default:
        // do work
    }
}

// ✅ Use typed keys for context values
type requestIDKey struct{}
ctx = context.WithValue(ctx, requestIDKey{}, "123")

​
DON’Ts

// ❌ Don't store context in structs
type BadService struct {
    ctx context.Context // Don't do this!
}

// ❌ Don't use string keys for context values
ctx = context.WithValue(ctx, "requestID", "123") // Collision risk!

// ❌ Don't pass nil context
processOrder(nil, orderID) // Use context.TODO() instead

// ❌ Don't use context for passing optional parameters
// Use functional options or config structs instead
ctx = context.WithValue(ctx, "retries", 3) // Bad!

​
Context Cause (Go 1.20+)

Go 1.20 introduced context.WithCancelCause for better error context: 
func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    
    go func() {
        if err := doWork(ctx); err != nil {
            cancel(fmt.Errorf("work failed: %w", err))
        }
    }()
    
    <-ctx.Done()
    
    // Get the cause of cancellation
    cause := context.Cause(ctx)
    fmt.Println("Cancelled because:", cause)
}

​
AfterFunc (Go 1.21+)

Go 1.21 added context.AfterFunc to schedule cleanup: 
func processWithCleanup(ctx context.Context) {
    resource := acquireResource()
    
    // Schedule cleanup when context is done
    stop := context.AfterFunc(ctx, func() {
        resource.Release()
        log.Println("Resource released due to context cancellation")
    })
    
    // If we finish normally, stop the scheduled cleanup
    defer stop()
    
    // Do work...
    useResource(resource)
    
    // Normal cleanup
    resource.Release()
}

​
Real-World Example: HTTP Service

package main

import (
    "context"
    "encoding/json"
    "log"
    "net/http"
    "time"
)

type OrderService struct {
    db     *sql.DB
    cache  *redis.Client
    notify *NotificationService
}

func (s *OrderService) CreateOrder(ctx context.Context, order *Order) error {
    // Add timeout for the entire operation
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()
    
    // Step 1: Validate inventory (5s timeout)
    inventoryCtx, _ := context.WithTimeout(ctx, 5*time.Second)
    if err := s.validateInventory(inventoryCtx, order); err != nil {
        return fmt.Errorf("inventory validation failed: %w", err)
    }
    
    // Step 2: Process payment (10s timeout)
    paymentCtx, _ := context.WithTimeout(ctx, 10*time.Second)
    if err := s.processPayment(paymentCtx, order); err != nil {
        return fmt.Errorf("payment failed: %w", err)
    }
    
    // Step 3: Save to database
    if err := s.saveOrder(ctx, order); err != nil {
        // Payment succeeded but save failed - need compensation
        s.refundPayment(context.Background(), order) // Use background for cleanup
        return fmt.Errorf("failed to save order: %w", err)
    }
    
    // Step 4: Send notification (non-critical, don't fail the order)
    go s.notify.SendOrderConfirmation(context.Background(), order)
    
    return nil
}

func (s *OrderService) Handler(w http.ResponseWriter, r *http.Request) {
    // Extract request context
    ctx := r.Context()
    
    // Add request metadata
    ctx = context.WithValue(ctx, requestIDKey{}, r.Header.Get("X-Request-ID"))
    
    var order Order
    if err := json.NewDecoder(r.Body).Decode(&order); err != nil {
        http.Error(w, "Invalid request", http.StatusBadRequest)
        return
    }
    
    if err := s.CreateOrder(ctx, &order); err != nil {
        if ctx.Err() == context.Canceled {
            // Client disconnected
            log.Printf("Client disconnected during order creation")
            return
        }
        if ctx.Err() == context.DeadlineExceeded {
            http.Error(w, "Request timeout", http.StatusGatewayTimeout)
            return
        }
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(order)
}

​
Interview Questions

Resources are leaked! The goroutine managing the context’s timer continues running until the parent context is cancelled. Always defer cancel() immediately after creating a cancellable context.
No, contexts are immutable. WithValue returns a new context with the added value. The original context is unchanged.
Functionally identical, but semantically different:
  • Background(): Use at the top of the call chain (main, init, tests)
  • TODO(): Temporary placeholder when you’re not sure which context to use
Generally no. Context should flow through your program via function parameters. Storing in structs can lead to stale contexts and unclear lifecycle management.
When a parent context is cancelled, all child contexts are also cancelled. The cancellation is detected by receiving from ctx.Done(). Child context cancellation doesn’t affect the parent.

​
Summary

FunctionPurpose
context.Background()Root context for main, init, tests
context.TODO()Placeholder when unsure
context.WithCancel()Manual cancellation
context.WithTimeout()Cancel after duration
context.WithDeadline()Cancel at specific time
context.WithValue()Attach request-scoped data
context.WithCancelCause()Cancellation with reason (Go 1.20+)
context.AfterFunc()Schedule cleanup (Go 1.21+)

​
Interview Deep-Dive

Strong Answer:
  • Context represents the lifetime and cancellation scope of a single request or operation. Storing it in a struct field decouples the context from the call chain, creating two problems. First, lifecycle ambiguity: the context might be cancelled (because the original request finished) while the struct is still alive and being used for a different request. Second, stale contexts: if the struct is reused across requests (like a service singleton), the stored context from the first request would be used for all subsequent requests, which is both logically wrong and can cause premature cancellation.
  • The correct pattern is to pass context as the first parameter of every function that needs it: func (s *Service) CreateOrder(ctx context.Context, order *Order) error. The context flows through the call chain, and each function can derive child contexts (with timeout, with values) as needed. When the request ends, the context is cancelled, and all derived contexts are cancelled too.
  • The one exception is when a struct represents a single operation with a defined lifetime, like an http.Request which carries its own context via r.Context(). But even there, the context is accessed via a method, not used directly as a field. The net/http package set this precedent intentionally.
  • In practice, if you find yourself wanting to store a context, it usually means your struct’s lifetime does not match the context’s lifetime. Restructure so the context is passed through function parameters instead.
Follow-up: What happens if you forget to call the cancel function returned by context.WithTimeout?The timer goroutine that manages the timeout continues running until the parent context is cancelled or the program exits. This is a goroutine and memory leak. Each uncancelled timeout context keeps its timer goroutine alive, accumulating over time. In a high-throughput HTTP server handling 10,000 requests per second, forgetting defer cancel() would leak 10,000 goroutines per second, each waiting for their timeout to expire. Even after the timeout fires, the context’s resources are not fully freed until cancel is called. This is why go vet warns about uncancelled contexts and why the idiomatic pattern is always ctx, cancel := context.WithTimeout(parentCtx, duration); defer cancel() — the defer ensures cancel runs even on early return or panic.
Strong Answer:
  • The middleware extracts or generates a request ID, attaches it to the context using context.WithValue, and passes the enriched context downstream. Key design decisions:
  • First, use an unexported struct type as the context key, not a string. String keys risk collision: two packages using context.WithValue(ctx, "requestID", ...) would overwrite each other. An unexported struct type like type requestIDKey struct{} is globally unique because it belongs to your package and cannot be referenced from outside.
  • Second, provide exported accessor functions: func WithRequestID(ctx context.Context, id string) context.Context and func RequestID(ctx context.Context) string. These encapsulate the key type and provide a clean API. The getter should return a sensible default (empty string or “unknown”) if the value is not present, rather than panicking.
  • Third, check for an existing request ID in the incoming request headers (like X-Request-ID or X-Trace-ID). If present, use it — this enables distributed tracing across services. If absent, generate a new UUID. This way the same request ID follows a request through your entire microservice chain.
  • Fourth, add the request ID to the structured logger in the same middleware, so every log line in the request’s lifecycle includes it. This makes correlating logs across a request trivial: grep for the request ID and you see the full story.
Follow-up: Context values are often criticized. What are the legitimate use cases versus the anti-patterns?Legitimate uses: request-scoped metadata that crosses API boundaries without being part of the function signature — request IDs, trace IDs, authentication claims, and deadline information. These are truly cross-cutting concerns that every function in the chain might need but that should not pollute business logic signatures. Anti-patterns: using context values to pass optional function parameters (use functional options or config structs instead), storing mutable state in context (context values should be immutable), passing dependencies through context (use constructor injection). The rule of thumb: context values should be data that originates from the request and is consumed by infrastructure (logging, tracing, auth), not data that is part of the business logic. If removing the context value would change the function’s behavior (not just its logging), it probably should be a regular parameter.
Strong Answer:
  • The child context inherits the parent’s deadline. Since the parent expires in 2 seconds, the child will also be cancelled at 2 seconds, even though you requested 5 seconds. context.WithTimeout creates a context that expires at the earlier of: the parent’s deadline or now + the specified duration. It never extends the parent’s deadline.
  • This is by design. A child context can only narrow the constraints (shorter timeout, additional values), never widen them. If the parent says “this request must complete in 2 seconds,” no child can override that to say “actually, I need 5 seconds.” This ensures that cancellation always propagates downward and timeout guarantees are always honored.
  • You can check the effective deadline with ctx.Deadline(). The function returns the actual deadline and a boolean indicating whether one exists. A well-designed function that needs a minimum amount of time should check the remaining time before starting expensive work: if deadline, ok := ctx.Deadline(); ok && time.Until(deadline) < minRequired { return ErrInsufficientTime }.
  • In production, this behavior sometimes surprises developers who set generous timeouts on database queries but forget that the HTTP handler’s context has a tighter timeout. The database query context is derived from the request context, so the handler’s timeout wins. The fix is to set appropriate timeouts at each level, understanding that the tightest timeout in the chain always dominates.
Follow-up: When would you use context.Background() instead of passing the parent context, and is this ever acceptable in production?Use context.Background() for operations that must complete regardless of the original request’s lifecycle. The classic example: a payment was successfully charged but the database save failed. You need to issue a refund, and that refund must happen even if the HTTP request was cancelled. Using context.Background() (or context.WithTimeout(context.Background(), 30*time.Second)) ensures the refund is not cancelled when the request context expires. Other legitimate uses: background cleanup goroutines, periodic tasks (health checks, metrics flushing), and shutdown operations. The key principle: use the request context for work that is part of the request, use context.Background() for work that must survive the request. If you find yourself using context.Background() in a handler’s main logic path, that is a code smell — it means you are bypassing the request’s cancellation semantics.