Using Go’s Context for Request‑Scoped Cancellation and Timeout in HTTP Servers

Desired Outcome

Guarantee that every HTTP handler in a Go server respects client cancellations and server‑defined timeouts. The goal is to prevent goroutine leaks, avoid unnecessary work, and return the appropriate HTTP status codes (e.g., 499 for client cancel, 504 for timeout).

Prerequisites

• Go 1.13+ (context package stable)
• Basic net/http server setup
• Understanding of context.Context and its propagation rules
• Access to a terminal with curl or similar HTTP client

Focused Procedure

1. Import the package

   import (
       "context"
       "net/http"
   )

2. Change the handler signature

   Standard http.HandlerFunc receives http.ResponseWriter and *http.Request. Extract the context from the request and pass it explicitly to the handler logic.

   func main() {
       http.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
           // Extract context once and use it throughout.
           ctx := r.Context()
           if err := doWork(ctx, w); err != nil {
               handleErr(w, err)
           }
       })
       http.ListenAndServe(":8080", nil)
   }

3. Propagate the context to downstream operations

   When calling database drivers, HTTP clients, or any long‑running goroutine, forward ctx instead of context.Background() or a new context. Example with a simulated delay:

   func doWork(ctx context.Context, w http.ResponseWriter) error {
       // Simulate a long task that should be cancelable.
       select {
       case <-time.After(5 * time.Second):
           // Task completed.
           _, _ = w.Write([]byte("done"))
           return nil
       case <-ctx.Done():
           // Context was cancelled or timed out.
           return ctx.Err()
       }
   }

4. Wrap the server with a timeout handler (optional)

   If you want the server to enforce a hard timeout regardless of handler code, use http.TimeoutHandler or set the ReadTimeout / WriteTimeout on the http.Server struct.

   srv := &http.Server{
       Addr:         ":8080",
       Handler:      http.TimeoutHandler(http.DefaultServeMux, 2*time.Second, "timeout"),
       ReadTimeout:   5 * time.Second,
       WriteTimeout:  5 * time.Second,
       IdleTimeout:   120 * time.Second,
   }
   if err := srv.ListenAndServe(); err != nil { log.Fatal(err) }

5. Handle context errors in the response

   Map context.Canceled to 499 and context.DeadlineExceeded to 504. This keeps the client informed and lets upstream services know the outcome.

   func handleErr(w http.ResponseWriter, err error) {
       switch err {
       case context.Canceled:
           w.WriteHeader(499) // Client closed the connection.
           _, _ = w.Write([]byte("request cancelled"))
       case context.DeadlineExceeded:
           w.WriteHeader(504) // Server timed out.
           _, _ = w.Write([]byte("request timed out"))
       default:
           w.WriteHeader(500)
           _, _ = w.Write([]byte("internal error"))
       }
   }

Expected Checks

• Run curl --max-time 1 http://localhost:8080/work and observe a 499 response and a context.Canceled log entry.
• Set the server timeout to 200ms and send a request that sleeps for 500ms; the client should receive a 504 and the handler should exit early with context.DeadlineExceeded.
• Use go test -race on any concurrent code inside doWork to ensure no data races are introduced by using ctx.
• Run go vet ./... and confirm no unused context variables or global context leaks.

Recovery Options

• If ctx.Err() is not nil, log the error, release any held resources (database connections, file handles, etc.), and terminate the goroutine chain.
• When using third‑party libraries that do not accept a context, wrap them in a goroutine and use select on ctx.Done() to cancel the operation. Example: select { case result := lib.DoWork(); case <-ctx.Done(): return ctx.Err() }
• For long‑running pipelines, consider using context.WithCancel at the top level of the handler and propagate the returned cancel function to all downstream stages. Call the cancel function in a defer block to ensure cleanup even if the handler panics.

Limitations & Practical Checks

• Do not store a request’s context in a global variable; it will bleed across requests and cause subtle bugs.
• Never use context.Background() for request‑scoped work; it ignores cancellations and can lead to orphaned goroutines.
• Be aware that http.TimeoutHandler writes its own timeout response and may mask the original error. If you need custom error handling, implement the timeout logic manually inside the handler.
• Check that your database driver supports context; many drivers expose QueryContext or ExecContext methods.
• After deploying, monitor your application’s goroutine count with pprof or go tool pprof to detect leaks when cancellations occur.

Concrete Example: Simulated Long‑Running Task

Below is a minimal server that demonstrates the full flow. The handler sleeps for 10 seconds unless the client cancels or the server times out at 3 seconds.

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "time"
)

func main() {
    http.HandleFunc("/slow", slowHandler)
    srv := &http.Server{
        Addr:         ":8080",
        ReadTimeout:  10 * time.Second,
        WriteTimeout: 10 * time.Second,
        IdleTimeout: 120 * time.Second,
    }
    log.Println("Listening on :8080")
    if err := srv.ListenAndServe(); err != nil {
        log.Fatal(err)
    }
}

func slowHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    if err := doWork(ctx, w); err != nil {
        handleErr(w, err)
    }
}

func doWork(ctx context.Context, w http.ResponseWriter) error {
    // Simulate a 10s operation.
    select {
    case <-time.After(10 * time.Second):
        _, _ = w.Write([]byte("completed"))
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

func handleErr(w http.ResponseWriter, err error) {
    switch err {
    case context.Canceled:
        w.WriteHeader(499)
        _, _ = w.Write([]byte("client cancelled"))
    case context.DeadlineExceeded:
        w.WriteHeader(504)
        _, _ = w.Write([]byte("server timeout"))
    default:
        w.WriteHeader(500)
        _, _ = w.Write([]byte("internal error"))
    }
}

Run the server, then in a separate terminal:

curl -v http://localhost:8080/slow
# Wait 5 seconds, then cancel:
# (Ctrl+C or curl --max-time 5)

You should see a 499 response and the log entry client cancelled. If you set the server’s ReadTimeout to 3s, the client will receive a 504 after 3 seconds.

Conclusion

By explicitly extracting the request context, propagating it, and handling ctx.Done() correctly, you can build robust HTTP servers that respect client intent and avoid leaking resources. The pattern scales to microservices, database access, and any concurrent work that benefits from cancellation and deadlines.