Skip to content

The Context🔗

  • Server has metadata on individual requests which could be 2 types * Metadata related to request processing * Metadata related to stop processing the request
  • Example: tracking-id in an HTTP Server

What is the Context?🔗

  • A context is an instance that meets the Context interface defined in context package
  • Go encourages explicit data passing via function parameters
  • Go has convention that context is explicitly passed as first parameter of a function with name ctx 
    func logic(ctx context.Context, info string) (string, err) {
    // do something here
    return "", nil
}
  • context package has several factory functions for creating and wrapping contexts.
  • context.Background: creates empty initial context
  • Each time when metadata is added to a context, its done by wrapping the existing context by using one of factory methods in context NOTE: context was added much later in Go APIs after net/http was released, because of compatibility promise, there is no way to change http.Handler interface to add a context.Context parameter.

General Pattern with http.Handler * Context returns the context.Context associated with request * WithContext takes in a context.Context and returns a new http.Request with old request's state combined with the supplied context. 

// this middleware wraps the context with other code
func Middleware(handler http.Handler) http.Handler {
    return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        ctx := req.Context()
        // wrap context with stuff --
        req = req.WithContext(ctx)
        handler.ServeHTTP(rw, req)
    })
}
// now in handler function you can extract this context
// ctx := req.Context()

  • Derived Contexts * context.WithValue(parent, key, value) * context.WithDeadline(parent, time) * context.WithTimeout(parent, duration) * context.WithCancel(parent)

Values🔗

  • Data should be passed through explicit parameters
  • In some cases like HTTP request handler, we have two parameters : one for request, other for response, passing values explicitly is not possible.
  • context is used to make available a value to the handler in middleware
  • context.Withvalue takes three values * context (context.Context type) * key (any type, must be comparable) * value (any type) 
    ctx := context.Background()
if myVal, ok := ctx.Value(myKey).(int); !ok {
    fmt.Println("no value")
} else {
    fmt.Println("value:", myVal)
}
  • Two pattern to ensure key is unique and comparable
  • First Pattern * create unexported type for the key: type UserKey int based on int * declare unexported constant of type

// declaring unexported constant
const(
    _ userKey = iota
    key
)
* With Unexported Constant, you can be sure, no other package can modify/add data to your context that would cause collision. * Build an API to place/read value into context * Making these functions public/private is user's choice 
func ContextWithUser(ctx context.Context, user string) context.Context {
    return context.WithValue(ctx, key, user)
}

func UserFromContext(ctx context.Context) (string, bool) {
    user, ok := ctx.Value(key).(string)
    return user, ok
}

  • Second Option * define unexported key types as empty struct : type userKey struct{} 
    func ContextWithUser(ctx context.Context, user string) context.Context {
    return context.WithValue(ctx, userKey{}, user)
}

func UserFromContext(ctx context.Context) (string, bool) {
    user, ok := ctx.Value(userKey{}).(string)
    return user, ok
}

Example : middleware that extracts a user ID from a cookie

// a real implementation would be signed to make sure
// the user didn't spoof their identity
func extractUser(req *http.Request) (string, error) {
    userCookie, err := req.Cookie("identity")
    if err != nil {
        return "", err
    }
    return userCookie.Value, nil
}

func Middleware(h http.Handler) http.Handler {
    return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        user, err := extractUser(req)
        if err != nil {
            rw.WriteHeader(http.StatusUnauthorized)
            rw.Write([]byte("unauthorized"))
            return
        }
        ctx := req.Context()
        ctx = ContextWithUser(ctx, user)
        req = req.WithContext(ctx)
        h.ServeHTTP(rw, req)
    })
}
* In most cases, you want to extract the value from the context in your request handler and pass it in to your business logic explicitly. Go functions have explicit parameters, and you shouldn’t use the context as a way to sneak values past the API

Cancellation🔗

  • Context also allows to control responsiveness of application and co-ordinate concurrent goroutines
  • Scenario: Let's say there are multiple goroutines requesting HTTP resource concurrently, we want to cancel all goroutines if any one of them fails.
  • context.WithCancel takes context.Context and parameter and returns context.Context and a context.CancelFunc
  • cancel function must be called when context exits. Use defer to invoke it. 
    ctx, cancelFunc := context.WithCancel(context.Background())
defer cancelFunc()
  • how to detect context cancellation ? context.Context has a method called Done. It returns a channel of type struct{} (empty struct uses no memory :). This channel is closed when the cancel function is invoked.
  • First, create cancellable context, a channel to get data back from your goroutines, and sync.WaitGroup to allow wait until goroutines have completed

ctx, cancelFunc := context.WithCancel(context.Background())
defer cancelFunc()
ch := make(chan string)
var wg sync.WaitGroup
wg.add(2)
* Next launch 2 goroutines, one calls URL that randomly returns bad status, and other sends a canned JSON response after delay

    go func() {
        defer wg.Done()
        for {
            // return one of these status code at random
            resp, err := makeRequest(ctx,
                "http://httpbin.org/status/200,200,200,500")
            if err != nil {
                fmt.Println("error in status goroutine:", err)
                cancelFunc()
                return
            }
            if resp.StatusCode == http.StatusInternalServerError {
                fmt.Println("bad status, exiting")
                cancelFunc()
                return
            }
            select {
            case ch <- "success from status":
            case <-ctx.Done():
            }
            time.Sleep(1 * time.Second)
        }
    }()

// delay goroutine
    go func() {
        defer wg.Done()
        for {
            // return after a 1 second delay
            resp, err := makeRequest(ctx, "http://httpbin.org/delay/1")
            if err != nil {
                fmt.Println("error in delay goroutine:", err)
                cancelFunc()
                return
            }
            select {
            case ch <- "success from delay: " + resp.Header.Get("date"):
            case <-ctx.Done():
            }
        }
    }()

// finally use for/select pattern to read data from channel writen by goroutines and wait for cancellation

loop:
    for {
        select {
        case s := <-ch:
            fmt.Println("in main:", s)
        case <-ctx.Done():
            fmt.Println("in main: cancelled!")
            break loop
        }
    }
    wg.Wait()
  • above solution doesn't include the error that caused the cancellation
  • context.WithCancelCause can be used to report the cause of error.
// changes in main
ctx, cancelFunc := context.WithCancelCause(context.Background())
defer cancelFunc(nil)

// changes in reqeusts coroutine
resp, err := makeRequest(ctx, "http://httpbin.org/status/200,200,200,500")
if err != nil {
    cancelFunc(fmt.Errorf("in status goroutine: %w", err))
    return
}
if resp.StatusCode == http.StatusInternalServerError {
    cancelFunc(errors.New("bad status"))
    return
}
ch <- "success from status"
time.Sleep(1 * time.Second)


// changes in delay function
resp, err := makeRequest(ctx, "http://httpbin.org/delay/1")
if err != nil {
    fmt.Println("in delay goroutine:", err)
    cancelFunc(fmt.Errorf("in delay goroutine: %w", err))
    return
}
ch <- "success from delay: " + resp.Header.Get("date")


// changes to for/select
loop:
    for {
        select {
        case s := <-ch:
            fmt.Println("in main:", s)
        case <-ctx.Done():
            fmt.Println("in main: cancelled with error", context.Cause(ctx))
            break loop
        }
    }
    wg.Wait()
    fmt.Println("context cause:", context.Cause(ctx))

Contexts with Deadlines🔗

  • server cannot serve infinite request, to scale and handle load servers can * limit simultaneous requests * limit number of queued requests waiting to run * limit the amt of time a request can run * limit the resources per request can use (memory/disk)
  • Go provides tools to handle first 3 causes
  • Context provides limit on how long a code runs
  • Two functions that can be used to create time-limited context * context.WithTimeout : triggers cancellation after specified amount of time has elapsed * context.WithDeadline : triggers cancellation after specific time has elapsed
ctx := context.Background()
parent, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
child, cancel2 := context.WithTimeout(parent, 3*time.Second)
defer cancel2()
start := time.Now()
<-child.Done()   // wait for child context to finish
end := time.Now()
fmt.Println(end.Sub(start).Truncate(time.Second))

// output will be 2seconds, since child is derived from parent which should be cancelled in 2 seconds
  • in above example parent has 2 seconds timeout, child has 3 seconds of timeout.
  • The Err method returns nil if context is still active or it returns one of two sentinel errors : context.Cancelled or context.DeadlineExceeded

Context Cancellation in Your Own Code🔗

  • When to handle Context Cancellation ? * Usually not needed if your code runs quickly * Required when calling external services (e.g., HTTP requests, database queries) to propagate context for proper cancellation handling. * Important in long-running functions or channel-based communication in goroutines.
  • Key Situation to Handle Context Cancellations * When using select with channels * Always include a case for <-ctx.Done() to exit early. * When writing long-running code * Periodically check context.Cause(ctx), which returns an error if the context is canceled.
  • Cancellation Pattern in Long-Running Code * Ensures the function can gracefully exit if the context is canceled. * Can return partial results if needed 
    func longRunningComputation(ctx context.Context, data string) (string, error) {
    for {
        // Check for cancellation periodically
        if err := context.Cause(ctx); err != nil {
            return "", err // Exit early if canceled
        }
        // Continue processing
    }
}
  • Example: Calculating Ï€ with Cancellation 
    i := 0
for {
    if err := context.Cause(ctx); err != nil {
        fmt.Println("Cancelled after", i, "iterations")
        return sum.Text('g', 100), err
    }
    var diff big.Float
    diff.SetInt64(4)
    diff.Quo(&diff, &d)
    if i%2 == 0 {
        sum.Add(&sum, &diff)
    } else {
        sum.Sub(&sum, &diff)
    }
    d.Add(&d, two)
    i++
}
  • Uses the Leibniz algorithm to compute Ï€.
  • The loop checks context.Cause(ctx) to stop when canceled.
  • Allows control over how long the computation runs.