Timeouts, body limits and slow clients

An HTTP server without limits fails in a way that looks like a network problem: a few slow clients hold every connection, a single large body fills memory, and a burst of requests makes every handler slower until they time out. Four settings and a semaphore cover most of it. This lesson runs each of them against a real client in the same process.

The four server timeouts

ReadHeaderTimeout bounds the request line and headers, which is the one a slow client attacks first. ReadTimeout bounds the whole request including the body, WriteTimeout the response, and IdleTimeout a kept-alive connection between requests. The program sets all four, serves one request and prints two of them.

package main import ( "context" "fmt" "io" "net" "net/http" "time" ) func main() { mux := http.NewServeMux() mux.HandleFunc("GET /hello", func(w http.ResponseWriter, r *http.Request) { fmt.Fprintln(w, "hello") }) srv := &http.Server{ Handler: mux, ReadHeaderTimeout: time.Second, ReadTimeout: 2 * time.Second, WriteTimeout: 2 * time.Second, IdleTimeout: 30 * time.Second, } ln, err := net.Listen("tcp", "127.0.0.1:0") if err != nil { panic(err) } go srv.Serve(ln) resp, err := http.Get("http://" + ln.Addr().String() + "/hello") if err != nil { panic(err) } body, _ := io.ReadAll(resp.Body) resp.Body.Close() fmt.Println("read header timeout:", srv.ReadHeaderTimeout) fmt.Println("idle timeout:", srv.IdleTimeout) fmt.Print("body: ", string(body)) ctx, cancel := context.WithTimeout(context.Background(), time.Second) defer cancel() _ = srv.Shutdown(ctx) }

go build -o app main.go && ./app

read header timeout: 1s
idle timeout: 30s
body: hello

The zero value of each timeout means no limit, which is the default of http.ListenAndServe and the wrong default for a service. The numbers above are a starting point for an internal API; a public one keeps the header timeout short, the write timeout longer than its slowest handler, and the idle timeout shorter than the load balancer's.

A body limit

http.MaxBytesReader wraps the request body and stops the read one byte past the limit with a *http.MaxBytesError. The handler turns that into 413 and does not store anything. A JSON API needs this before json.Decode, or a client can send a gigabyte of valid JSON and the decoder reads it all.

package main import ( "bytes" "errors" "fmt" "io" "net/http" "net/http/httptest" ) func main() { mux := http.NewServeMux() mux.HandleFunc("POST /notes", func(w http.ResponseWriter, r *http.Request) { limited := http.MaxBytesReader(w, r.Body, 100) _, err := io.ReadAll(limited) var maxErr *http.MaxBytesError if errors.As(err, &maxErr) { http.Error(w, "body too large", http.StatusRequestEntityTooLarge) return } if err != nil { http.Error(w, "bad body", http.StatusBadRequest) return } fmt.Fprintln(w, "stored") }) srv := httptest.NewServer(mux) defer srv.Close() payload := bytes.Repeat([]byte("x"), 200) resp, err := http.Post(srv.URL+"/notes", "text/plain", bytes.NewReader(payload)) if err != nil { panic(err) } body, _ := io.ReadAll(resp.Body) resp.Body.Close() fmt.Println("status:", resp.StatusCode) fmt.Print("body: ", string(body)) }

go build -o app main.go && ./app

status: 413
body: body too large

Two hundred bytes against a limit of one hundred ended at the limit, and the response says why. The same pattern guards a form parser and a file upload. A proxy in front may have its own limit and answer 413 before the handler runs, which is why the limit is documented with the deployment, not hidden in a constant.

A slow client

The attack is a connection that sends half a header and then nothing. The server with a ReadHeaderTimeout of twenty milliseconds accepts it, waits, and closes the connection; the handler never runs. The program below makes exactly that connection, writes an incomplete request and reports what came back.

package main import ( "bufio" "context" "fmt" "io" "net" "net/http" "time" ) func main() { ran := make(chan struct{}, 1) mux := http.NewServeMux() mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) { select { case ran <- struct{}{}: default: } fmt.Fprintln(w, "ok") }) srv := &http.Server{ Handler: mux, ReadHeaderTimeout: 20 * time.Millisecond, } ln, err := net.Listen("tcp", "127.0.0.1:0") if err != nil { panic(err) } go srv.Serve(ln) defer func() { ctx, cancel := context.WithTimeout(context.Background(), time.Second) defer cancel() _ = srv.Shutdown(ctx) }() conn, err := net.Dial("tcp", ln.Addr().String()) if err != nil { panic(err) } defer conn.Close() fmt.Fprint(conn, "GET / HTTP/1.1\r\nHost: slow\r\n") data, err := io.ReadAll(bufio.NewReader(conn)) fmt.Println("read error:", err) fmt.Println("response bytes:", len(data)) select { case <-ran: fmt.Println("handler ran: true") case <-time.After(100 * time.Millisecond): fmt.Println("handler ran: false") } }

go build -o app main.go && ./app

read error: <nil>
response bytes: 0
handler ran: false

The connection closed with no response and the handler never ran, which is the timeout working: the client learned nothing and the server spent twenty milliseconds, not a connection slot for a minute. A server without the setting keeps that connection until the client or the operating system gives up.

A concurrency limit

A timeout bounds one request and a semaphore bounds how many run at once. The handler below takes one of one slots without waiting; a second request that finds the slot taken gets 503 at once. That is load shedding: an answer in a millisecond, even a refusal, is better than a queue that grows until every request times out.

package main import ( "fmt" "net/http" "net/http/httptest" "time" ) func main() { slots := make(chan struct{}, 1) started := make(chan struct{}) release := make(chan struct{}) mux := http.NewServeMux() mux.HandleFunc("GET /work", func(w http.ResponseWriter, r *http.Request) { select { case slots <- struct{}{}: defer func() { <-slots }() close(started) <-release fmt.Fprintln(w, "done") default: w.WriteHeader(http.StatusServiceUnavailable) fmt.Fprintln(w, "busy") } }) srv := httptest.NewServer(mux) defer srv.Close() go func() { resp, err := http.Get(srv.URL + "/work") if err == nil { resp.Body.Close() } }() <-started resp, err := http.Get(srv.URL + "/work") if err != nil { panic(err) } fmt.Println("second status:", resp.StatusCode) var body [32]byte n, _ := resp.Body.Read(body[:]) resp.Body.Close() fmt.Print("second body: ", string(body[:n])) close(release) time.Sleep(10 * time.Millisecond) }

go build -o app main.go && ./app

second status: 503
second body: busy

The second request was refused while the first held the slot, and the first finished when the program released it. A service sizes the semaphore from its database pool and its CPU count, not from a guess, and a 503 tells the client to back off, which a queue does not.

The limits that keep a server up

A public server has a budget for each resource: header bytes, body bytes, time, connections and concurrent handlers. The standard library gives the first four through the server settings and MaxBytesReader, and the fifth is a channel. A proxy in front adds its own limits, and a service that documents them together is the one that degrades instead of collapsing.

The capstone service sets all of them and its deploy lesson measures the shutdown against the same budget. Part 9 starts below the server, with reflection: the mechanism encoding/json uses to read a struct without knowing it.

Exercises

  1. Set ReadHeaderTimeout to zero and run the slow-client program again. What changes, and how long does the connection stay open?
  2. Lower the body limit to ten bytes and post twenty. What does the handler receive, and which error matches?
  3. Change the semaphore to block instead of returning 503 and time the second request. What does the client see, and why is that worse under load?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does ReadHeaderTimeout bound?

    Answer

    The request line and headers

    It is the first line of defence against a slow client.

  2. What is the zero value of a server timeout?

    Answer

    No limit

    That is why a service sets them.

  3. What does http.MaxBytesReader do?

    Answer

    Stops the body read at the limit with a MaxBytesError

    The handler maps it to 413.

  4. Which status fits a body over the limit?

    Answer

    413

    Request Entity Too Large.

  5. What happens to a slow client with ReadHeaderTimeout set?

    Answer

    The connection is closed and the handler never runs

    The server spends the timeout, not a slot.

  6. Why answer 503 instead of queueing?

    Answer

    A fast refusal beats a queue in which every request times out

    It is load shedding.

  7. How is a concurrency limit built from channels?

    Answer

    A buffered channel as a semaphore, taken in a non-blocking select

    The buffer size is the limit.

  8. Which budget does a public server need?

    Answer

    Header bytes, body bytes, time, connections and concurrent handlers

    Each resource fails in its own way.

  9. Where should the limits be documented?

    Answer

    With the deployment, next to the proxy limits

    The proxy may answer 413 first.

  10. What does WriteTimeout bound?

    Answer

    The response write

    It must exceed the slowest handler.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev