The HTTP server in Go: what net/http does by itself and what it does not do until asked

What is really being asked

The ladder is almost always this one:

1. "How do you build a web server in Go?" — the warm-up: http.HandleFunc and ListenAndServe.
2. "What are http.Handler and middleware?" — this checks whether the candidate sees the interface behind the function.
3. "How does net/http serve concurrent requests?" — the question whose answer explains half of the rest.
4. "Which timeouts do you set on a server?" — this shows whether the candidate has run a server in production.
5. "What happens to the work if the client has gone?" — about the request context.
6. "How do you stop the server without cutting requests?" — graceful shutdown, and the trap inside it.

The ladder has one spine: by default net/http limits nothing and waits for nothing by itself. Every "limit" and every "wait" is a line the developer writes, and the interview questions are about exactly those lines.

Base: Handler, ServeMux and middleware

Everything in net/http rests on one interface:

type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

http.HandlerFunc turns an ordinary function into a Handler, ServeMux is also a Handler that picks another handler by path, and http.Server takes one Handler and serves connections with it. Hence middleware — a function that takes a Handler and returns a Handler, wrapping the call in its own code:

func logging(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		next.ServeHTTP(w, r)
		log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
	})
}

A junior-level answer to "how do you build a web server": declare handlers — functions func(w http.ResponseWriter, r *http.Request) — register them in an http.ServeMux and run an http.Server with that multiplexer. A handler is the http.Handler interface, so middleware is written as a function Handler → Handler. And a caveat worth saying right away: in production you use not http.ListenAndServe(addr, mux) but your own http.Server — because only it has the timeout fields and the Shutdown method.

Mechanism 1: a goroutine per connection — and no built-in limit

Ten clients, each on its own connection, to a handler that sleeps 200 ms:

1) A GOROUTINE PER CONNECTION
─────────────────────────────
  10 requests, the handler sleeps 200 ms: 209 ms in total
  handlers at once, peak: 10

In this measurement every request went over its own connection. But a connection is not a request, and the model "one request = one connection = one goroutine" is wrong both ways:

1) HTTP/1.1 KEEP-ALIVE: REQUESTS IN SEQUENCE
────────────────────────────────────────────
  10 requests in sequence from one client: server connections 1

2) HTTP/2: CONCURRENT REQUESTS
──────────────────────────────
  10 concurrent requests: 202 ms, new connections 0, handlers at once 10, response 200 HTTP/2.0

Under HTTP/1.1 with keep-alive one connection serves requests one after another. Under HTTP/2 concurrent streams go over one connection, and each stream gets its own handler goroutine (a run of bench/gohttp/protocols.go, HTTP/2 without TLS through Server.Protocols in go1.24).

Three things worth being able to say follow from this.

• Handlers run at the same time. Mutable state that handlers access concurrently, with at least one writer, is a data race without a mutex or atomic operations (the lesson on data races). Immutable state — the configuration read at startup — can be shared freely.
• A slow handler by itself does not delay other connections. But a shared mutex, a database connection pool or a semaphore couple the latencies of requests: whoever waits for the shared resource waits for the slow neighbour too.
• There is no built-in limit on the number of requests. net/http keeps no fixed-size pool of handlers. There are limits, but different ones: file descriptors and the accept queue, memory, for HTTP/2 the number of concurrent streams per connection (per the HTTP2Config documentation, at least 100 by default), the load balancer in front of the server. Limits are set explicitly — with timeouts (Mechanism 2) or a semaphore in middleware.

Mechanism 2: four timeouts, all of them zero

http.Server has four timeout fields, and by default they are all zero:

What that means in practice: a client opened a connection, sent the start of its headers and went silent.

2) SERVER TIMEOUTS BY DEFAULT
─────────────────────────────
  http.Server{}: ReadTimeout=0s ReadHeaderTimeout=0s WriteTimeout=0s IdleTimeout=0s
  the client sent the start of its headers and went silent:
  ReadHeaderTimeout=0s     after 2000 ms: the connection is still open
  ReadHeaderTimeout=300ms  after  301 ms: the server closed the connection

2 s is the client's own waiting limit in the measurement; a server without a timeout would have waited longer. Each such connection holds a goroutine and a descriptor, and from Mechanism 1 we know there is no limit on them.

Which timeout limits what is the main thing asked here:

• ReadHeaderTimeout — only reading the headers. The documentation recommends it: most users will prefer ReadHeaderTimeout, because ReadTimeout does not let the handler decide what is too slow for a particular request body;
• ReadTimeout — all of reading the request, body included;
• WriteTimeout — counted from reading the headers, so it covers the handler's work too: a long handler hits it even if the response itself is written quickly;
• IdleTimeout — idle time between requests on a keep-alive connection.

The practical set for a short API that is named in an interview is ReadHeaderTimeout and IdleTimeout, plus WriteTimeout. It is a recommendation, not a rule: for streaming responses — SSE, long downloads, long-lived connections — a server-wide WriteTimeout would cut a legitimate response. There the write deadline is set per request through http.NewResponseController(w) and its SetWriteDeadline method, and only the header-reading protection is kept for the whole connection.

Next to the timeouts stands one more built-in limit, and this one is not zero: MaxHeaderBytes.

5) MaxHeaderBytes BY DEFAULT
────────────────────────────
  http.DefaultMaxHeaderBytes = 1048576
  header    4096 bytes: 200 OK
  header 2097152 bytes: 431 Request Header Fields Too Large

A megabyte of headers per request is a lot; if the service does not expect them, the limit is lowered.

Why a timeout limits waiting but not work, and why timeouts along a chain of services do not add up, is the lesson on timeouts and deadlines in the SRE track.

Mechanism 3: the client has gone — the context is cancelled, the work goes on

What the server does when the client stops waiting:

The context is cancelled when the server has detected the disconnect or the cancellation — it is a signal for code, not an instant notice that the client is gone. And the server does nothing more. Two handlers with the same 500 ms of work; the client waits 100 ms and leaves:

3) THE REQUEST CONTEXT WHEN THE CLIENT HAS GONE
───────────────────────────────────────────────
  the client waits 100 ms for a response and leaves; the handler's work is 500 ms
  listens to r.Context()  after  101 ms: stopped: context canceled
  ignores the context     after  500 ms: finished the work; context: context canceled

The second handler spent 400 ms on a response nobody will read — even though its context had been cancelled long before. Cancellation in Go is cooperative: only code that listens to ctx.Done() stops. That is why r.Context() is passed on — to a database query, to an outgoing HTTP request, to a long loop. How context cancellation works is covered in the lesson on context.

Where this context comes from is configurable too: Server.BaseContext sets the base context for all of the server's requests, Server.ConnContext the context of a connection. Through them handlers receive, for example, a shared stop signal or data about the connection.

Mechanism 4: Shutdown, Close — and the ListenAndServe that does not wait

There are two methods to stop a server. Shutdown closes the listeners, closes idle connections and waits for active ones to become idle. Close immediately closes the listeners and the ordinary connections — new, active and idle. Five requests of 300 ms each, the call 100 ms after they started:

4) STOPPING: Shutdown, Close AND THE RETURN FROM Serve
──────────────────────────────────────────────────────
  Shutdown 100 ms after five 300 ms requests started:
    Serve returned http: Server closed 0 ms after the call
    Shutdown returned after 276 ms
    requests in flight: 200 — 5, error — 0
    a new request after the call: rejected
  Close 100 ms after five 300 ms requests started:
    Serve returned http: Server closed 0 ms after the call
    Close returned after 1 ms
    requests in flight: 200 — 0, error — 5
    a new request after the call: rejected

Shutdown waited for all five, Close cut all five. But look at the first line of each block: Serve returned after 0 ms — in both cases, while the requests were still running. The documentation warns about this directly:

Typical code that looks right and cuts requests:

go func() {
	<-sigterm
	srv.Shutdown(ctx)
}()
log.Fatal(srv.ListenAndServe()) // returns at once — and main exits

ListenAndServe returned ErrServerClosed after 0 ms, log.Fatal ended the process — and Shutdown did not get to wait for a single request. The right order is the reverse: ListenAndServe in a goroutine, while main waits for the signal, calls Shutdown with a deadline context and waits for it to return. ErrServerClosed from ListenAndServe is not an error but the normal signal.

Hijacked connections are outside the server's lifecycle. WebSockets and anything a handler took over through Hijack are touched by neither Close nor Shutdown:

4) Close AND A HIJACKED CONNECTION
──────────────────────────────────
  after srv.Close() the hijacked connection answered: "echo: after Close"

For them there is RegisterOnShutdown: the function is called on Shutdown and must start the protocol-specific shutdown — for example, send a close frame to WebSocket clients — but not wait for it to complete. Waiting for the connections themselves is separate work for the application.

What to do before Shutdown — take the instance out of the load balancer, let it drain, fit into the orchestrator's grace period — is not specific to Go, and it is covered in the lesson on graceful shutdown in the SRE track.

Deeper: a panic in a handler and ServeMux patterns

A panic does not bring the process down. Unlike a panic in an ordinary goroutine, a panic in a handler is recovered by the server:

5) A PANIC IN A HANDLER
───────────────────────
  GET /boom: error on the client: true
  GET /ok after the panic: 200
  server log: http: panic serving 127.0.0.1:…: boom

The client got no response, the server wrote the stack to the log and carried on. What happened to the connection depends on the protocol — the documentation says the server either closes the network connection or sends an HTTP/2 RST_STREAM. The same handler under HTTP/1.1 and under HTTP/2:

3) A PANIC IN A HANDLER: HTTP/1.1 VERSUS HTTP/2
───────────────────────────────────────────────
  HTTP/1.1: /ok -> 200 HTTP/1.1; /boom -> error; /ok -> 200 HTTP/1.1
            connection reused: false, connections in total 3, /boom handler called 2 times
  HTTP/2  : /ok -> 200 HTTP/2.0; /boom -> error; /ok -> 200 HTTP/2.0
            connection reused: true, connections in total 1, /boom handler called 1 times

Under HTTP/1.1 the connection was closed, and the next request went over a new one. Under HTTP/2 only the request's stream was reset — the connection stayed alive and the next request went over it. And a finding nobody expected: under HTTP/1.1 the /boom handler was called twice — the client Transport retried the idempotent GET by itself after a network error on an already-used connection. For a handler with side effects on GET that means two executions.

The protection covers only the handler's goroutine: if the handler started a goroutine of its own and the panic happened there, the process crashes (the mechanism is in the lesson on defer, panic and recover). And "the effect is isolated to the request" is the server's assumption, not a guarantee: a mutex locked before the panic and not unlocked stays locked.

ServeMux patterns since Go 1.22 can carry a method and a path parameter:

6) ServeMux WITH GO 1.22 PATTERNS
─────────────────────────────────
  GET  /items/42    -> 200 id=42
  POST /items/42    -> 405 Method Not Allowed | Allow: GET, HEAD
  GET  /items/42/x  -> 404 404 page not found

The pattern is GET /items/{id}, the value comes from r.PathValue("id"); for another method — 405 with an Allow header, without a single line of code. If several patterns match a request, the most specific one is chosen:

Hence the trap the first practice problem checks: the server returns 405 only if the path matches no other pattern.

How to answer in an interview

Short answer: a handler is the http.Handler interface, ServeMux routes requests by path, middleware is a function Handler → Handler. The server serves each connection in its own goroutine (under HTTP/2, each stream), so mutable state shared by handlers must be protected. In production — your own http.Server with timeouts and stopping through Shutdown.

That is enough for a correct answer. What follows is what you add if the interviewer digs.

If the interviewer digs deeper

On "which timeouts" — what the default is. "http.Server{} has all four at zero, that is, none. A client that did not finish its headers still held the connection after 2 s in my run; with ReadHeaderTimeout of 300 ms it was closed after 301 ms. The minimum is ReadHeaderTimeout and IdleTimeout; WriteTimeout covers the handler's work too."

On "the client has gone" — cooperative cancellation. "r.Context() is cancelled, but only code that listens to it stops working: my handler without a context check finished 500 ms of work after the client left at 100. The request context is passed to the database and outgoing calls."

On graceful shutdown — the return trap. "Shutdown waits for requests, Close cuts them. But ListenAndServe returns ErrServerClosed right after Shutdown is called — after 0 ms in my run. If main exits there, the requests are cut. You wait for Shutdown to return."

On "what if a handler panics" — the boundary. "The server recovers a panic that reaches ServeHTTP and logs it; the process lives. Under HTTP/1.1 it closes the connection, under HTTP/2 it resets only the stream. But a panic in a goroutine started from the handler is not covered by this protection and crashes the process."

On "how does the server serve concurrent requests" — "a goroutine per connection, and under HTTP/2 per stream; there is no built-in pool and no limit on the number of requests: ten requests of 200 ms on ten connections took 209 ms in my run. A connection is not a request: keep-alive passes requests over it one after another, HTTP/2 concurrently."

Next they ask

Common misconceptions

Practice

Two problems. Answer first, then check against the real output: in both, the correct answer is taken from a run of the script rather than assigned.

mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "user ", r.PathValue("id"))
})
mux.HandleFunc("/users/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "fallback")
})

200 user 7
200 fallback
200 fallback

200 user 7
405 Method Not Allowed
200 fallback

200 user 7
405 Method Not Allowed
404 404 page not found

200 fallback
200 fallback
200 fallback

Knowledge check