Timeouts and limits: the zero values that hold connections forever

The Server timeouts nobody sets

Why does an API die with 4% CPU and an idle database? Almost certainly because you let the zero value decide — and in Go, zero timeout means infinite. Here is what you set instead.

http.ListenAndServe(addr, h) is production-hostile for exactly one reason: you cannot set timeouts on it. The four fields that matter live on http.Server, and each guards a different phase of the connection:

srv := &http.Server{
	Addr:              ":8080",
	Handler:           mux,
	ReadHeaderTimeout: 5 * time.Second,   // request line + headers
	ReadTimeout:       10 * time.Second,  // headers AND full body
	WriteTimeout:      30 * time.Second,  // from end-of-headers to last response byte
	IdleTimeout:       120 * time.Second, // keep-alive gap between requests
}
log.Fatal(srv.ListenAndServe())

• ReadHeaderTimeout is the slowloris killer: the peer must deliver the complete header block within it. Cheap to set tight (2–5 s) because honest clients send headers in one packet.
• ReadTimeout covers headers plus the entire body. A tight value here breaks legitimate large uploads — which is why many services set ReadHeaderTimeout small and ReadTimeout generous, or manage body deadlines per-route.
• WriteTimeout caps writing the response. Brutal detail: the deadline is absolute from when header reading ended, not per-write — a streaming endpoint that sends events for longer than WriteTimeout gets its connection closed mid-stream no matter how lively it is.
• IdleTimeout bounds how long a keep-alive connection may sit between requests; unset it falls back to ReadTimeout, and if that is also zero, idle connections live forever. 60–120 s is conventional.

One more honesty check: WriteTimeout does not stop your handler. When it fires, net/http closes the connection; the handler goroutine keeps computing until it finishes and its writes fail. Timeouts on the Server protect connections and FDs, not CPU.

Per-request deadlines: context, and what actually cancels

Server timeouts are connection plumbing; work is bounded per request, with the context:

func handler(w http.ResponseWriter, r *http.Request) {
	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
	defer cancel()

	row := db.QueryRowContext(ctx, query, id) // honors the deadline
	// r.Context() is also canceled if the CLIENT disconnects —
	// downstream work stops when nobody is waiting for the answer.
}

r.Context() is canceled when the client goes away or the connection breaks, so passing it into every database call and downstream request is free load-shedding: work for an abandoned request stops instead of completing into the void. Layer your own WithTimeout on top for per-route budgets. The discipline that makes this real: every blocking call in the handler must accept the ctx — one QueryRow instead of QueryRowContext and your 2-second budget has a hole in it. The stdlib also offers http.TimeoutHandler(h, 2*time.Second, "timeout"), which returns 503 at the deadline; honest caveat — like WriteTimeout, it cannot kill the handler goroutine, it just stops waiting for it (and its ResponseWriter hides Flusher, breaking streaming inside it).

The client side: the default http.Client waits forever

The same zero-value trap exists outbound, and it is worse because http.DefaultClient is so convenient. It has no timeout of any kind: a hung upstream holds your goroutine, its FD, and whatever request-scoped memory it captured, forever. Production config sets budgets at two levels:

client := &http.Client{
	Timeout: 10 * time.Second, // hard cap: dial + TLS + headers + FULL BODY READ
	Transport: &http.Transport{
		DialContext:           (&net.Dialer{Timeout: 2 * time.Second}).DialContext,
		TLSHandshakeTimeout:   3 * time.Second,
		ResponseHeaderTimeout: 5 * time.Second,  // upstream "thinking time"
		IdleConnTimeout:       90 * time.Second, // pooled conn lifetime
		MaxIdleConnsPerHost:   32,               // default 2 throttles fan-out
	},
}

Client.Timeout is the blunt instrument — it spans everything including reading the body, so it must exceed your slowest legitimate full exchange. The Transport fields cut finer: dial, TLS handshake, and time-to-first-header-byte are where hung upstreams actually hang. Two defaults bite hard in production: MaxIdleConnsPerHost is 2, so a service fanning out 200 concurrent calls to one host churns 198 fresh connections (TLS handshakes, TIME_WAIT pileup); and per-request deadlines still belong to the context — http.NewRequestWithContext(ctx, ...) — so the caller’s budget propagates instead of every hop waiting its own full 10 s.

MaxBytesReader: the limit on what you will swallow

Timeouts bound time; you must also bound bytes. An unauthenticated io.ReadAll(r.Body) is an invitation: a 2 GB JSON body is a 2 GB allocation, and a few concurrent ones OOM the pod. The stdlib answer:

func createUser(w http.ResponseWriter, r *http.Request) {
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MiB cap
	if err := json.NewDecoder(r.Body).Decode(&u); err != nil {
		var mbe *http.MaxBytesError
		if errors.As(err, &mbe) {
			http.Error(w, "body too large", http.StatusRequestEntityTooLarge)
			return // 413, and the server stops reading the rest
		}
		http.Error(w, "bad json", http.StatusBadRequest)
		return
	}
}

MaxBytesReader does more than truncate: on overflow it returns *http.MaxBytesError, and it tells the Server to stop reading the connection so a hostile client cannot keep pumping. Set it per route — 1 MiB for JSON APIs, larger only on upload endpoints — and remember Content-Length is a claim, not a guarantee; the reader enforces actual bytes.