These are the notes for Go episode 62. Last time Raju's menu went online with http.ListenAndServe. That one-liner is perfect on your laptop and dangerous on the internet. In this episode every problem shows up for real first: a slow client that holds a connection forever, a 10 MB order the server swallows, a kitchen that keeps cooking after the customer has left, a Ctrl+C that cuts a customer off mid-order, and a status page that arrives all at once. Each fix is one piece of the standard library: the http.Server struct and its timeouts, MaxHeaderBytes and http.MaxBytesReader, the request context, graceful shutdown, TLS and HTTP/2, and streaming with http.Flusher and server-sent events.
All outputs are from real runs (Go 1.24.7, linux/amd64). Ports, timestamps and exact timings change between runs.
Facts and sources
- The complete guide to Go net/http timeouts by Filippo Valsorda (Cloudflare blog, 29 June 2016): the package-level convenience functions such as
http.ListenAndServe"leave the Timeouts to their default off value, with no way of enabling them", and without timeouts "you'll soon be leaking connections and run out of file descriptors". It also notes that the package-level client functions likehttp.Get"use a Client without timeouts". go doc net/http(Go 1.24.7): "Starting with Go 1.6, the http package has transparent support for the HTTP/2 protocol when using HTTPS."DefaultMaxHeaderBytes = 1 << 20 // 1 MB. Thehttp.Serverfield docs:ReadTimeoutis "the maximum duration for reading the entire request, including the body";ReadHeaderTimeoutis "the amount of time allowed to read request headers";WriteTimeoutis "the maximum duration before timing out writes of the response";IdleTimeoutis "the maximum amount of time to wait for the next request when keep-alives are enabled". For all four, zero means no timeout (IdleTimeoutandReadHeaderTimeoutfall back toReadTimeout).- Decoding the Pod Termination Lifecycle in Kubernetes (CNCF blog, 19 Dec 2024): Kubernetes "sends a SIGTERM signal to the main process in each container of the pod", gives a grace period (30 seconds by default), then "sends a SIGKILL signal to force the process to terminate".
- Everything else (status codes, error messages, timings) is from the real runs below.
Before we start: the words this episode relies on
- Server: a program that waits for requests and answers them. Client: the program that sends the request (a browser, a phone app,
http.Get). - Connection: an open TCP line between a client and the server (episode 60). The operating system tracks each one with a file descriptor: a small number the OS hands out for every open file or socket. A process may only have a limited number open at once (on many Linux systems the default soft limit is 1024;
ulimit -nshows yours). - Timeout: the longest you are willing to wait for something before giving up.
- Keep-alive: HTTP/1.1 keeps a connection open after a response, so the next request on it skips the TCP setup.
- Production: the real, public deployment that real users hit, as opposed to your laptop.
- Goroutine (episode 43): Go's lightweight thread;
net/httpruns every connection on its own goroutine. - Context (episode 51): a
context.Contextcarries a cancel signal (Done()channel) and the reason (Err()).
Why the defaults are unsafe: a slow client
Real-life example: a customer walks up to Raju's counter and starts ordering... one word every few minutes. If Raju has no rule like "order within a minute or step aside", that one customer blocks the counter for the whole day. Send 1,000 such customers and the shop is closed.
On the internet this is a slow client attack (the classic name is Slowloris): open many connections and send the request a few bytes at a time, never finishing. Each open connection costs the server a goroutine and a file descriptor, and file descriptors run out.
http.ListenAndServe(addr, h) builds an http.Server with every timeout at zero, which means "no timeout". Let's prove it. slowClient sends one header line every 200 ms and never sends the blank line that ends the headers:
package main
import (
"errors"
"fmt"
"net"
"net/http"
"os"
"time"
)
// slowClient sends one header line every 200 ms and never finishes its request.
func slowClient(addr string) {
c, _ := net.Dial("tcp", addr)
defer c.Close()
fmt.Fprint(c, "GET /menu HTTP/1.1\r\nHost: raju\r\n")
start := time.Now()
for time.Since(start) < 3*time.Second {
fmt.Fprint(c, "X-Slow: 1\r\n")
c.SetReadDeadline(time.Now().Add(200 * time.Millisecond))
_, err := c.Read(make([]byte, 100))
if !errors.Is(err, os.ErrDeadlineExceeded) { // not "nothing yet"
fmt.Printf(" server hung up after %.1fs\n", time.Since(start).Seconds())
return
}
}
fmt.Println(" still holding the connection after 3s... and forever")
}
func main() {
menu := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { fmt.Fprintln(w, "chai ₹20") })
for _, srv := range []*http.Server{
{Handler: menu}, // what http.ListenAndServe uses: no timeouts
{Handler: menu, ReadHeaderTimeout: time.Second},
} {
ln, _ := net.Listen("tcp", "127.0.0.1:0")
go srv.Serve(ln)
fmt.Println("ReadHeaderTimeout =", srv.ReadHeaderTimeout)
slowClient(ln.Addr().String())
}
}
Real run:
ReadHeaderTimeout = 0s
still holding the connection after 3s... and forever
ReadHeaderTimeout = 1s
server hung up after 1.0s
With the defaults, the server is still holding the connection after 3 seconds, and it would hold it forever. With ReadHeaderTimeout: time.Second the server hangs up after exactly one second.
The http.Server struct
http.ListenAndServe is a shortcut. The real thing is a struct you fill in yourself:
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 5 * time.Second,
ReadTimeout: 10 * time.Second,
WriteTimeout: 15 * time.Second,
IdleTimeout: 60 * time.Second,
MaxHeaderBytes: 64 << 10,
}
log.Fatal(srv.ListenAndServe())
| Field | What it limits | Real-life version | Zero means |
|---|---|---|---|
ReadHeaderTimeout |
reading the request line and headers | "say what you want within 5 s" | uses ReadTimeout (no limit if that is 0 too) |
ReadTimeout |
reading the whole request, body included | "hand over the order slip and the money within 10 s" | no limit |
WriteTimeout |
writing the response (reset at each new request's headers) | "your parcel must be handed over within 15 s" | no limit |
IdleTimeout |
how long a kept-alive connection may wait for the next request | "if you're not ordering anything else, free the table" | uses ReadTimeout |
MaxHeaderBytes |
size of the request line + headers | "the order slip is one page" | DefaultMaxHeaderBytes = 1 MB |
ReadHeaderTimeout is the one that stops slow clients. ReadTimeout covers the body too, which can be unfair to large uploads on slow networks, so many servers set a generous ReadTimeout or rely on per-handler limits. WriteTimeout must be longer than your slowest handler; it does not stop the handler, it only kills the connection, so a too-short value looks like this (real run, WriteTimeout: time.Second, handler sleeps 2 s):
package main
import (
"fmt"
"net"
"net/http"
"time"
)
func main() {
srv := &http.Server{
WriteTimeout: time.Second,
Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
time.Sleep(2 * time.Second) // slower than WriteTimeout
fmt.Fprintln(w, "report")
}),
}
ln, _ := net.Listen("tcp", "127.0.0.1:0")
go srv.Serve(ln)
start := time.Now()
_, err := http.Get("http://" + ln.Addr().String())
fmt.Printf("after %.1fs: %v\n", time.Since(start).Seconds(), err)
}
after 2.0s: Get "http://127.0.0.1:46639": EOF
The handler still ran for 2 seconds; the client got nothing but EOF. That is a bug that's hard to debug, so pick WriteTimeout with care (and for streaming endpoints, see the end of these notes).
Limits: MaxHeaderBytes and http.MaxBytesReader
Real-life example: Raju's order slips are one page. Someone hands him a 500-page "order". He shouldn't read it all before saying no.
First the obvious version, with no body limit. It reads whatever arrives with io.ReadAll:
package main
import (
"errors"
"fmt"
"io"
"net/http"
"net/http/httptest"
"strings"
)
func order(w http.ResponseWriter, r *http.Request) {
b, err := io.ReadAll(r.Body)
var tooBig *http.MaxBytesError
if errors.As(err, &tooBig) {
http.Error(w, err.Error(), http.StatusRequestEntityTooLarge) // 413
return
}
fmt.Fprintf(w, "order of %d bytes accepted\n", len(b))
}
func main() {
srv := httptest.NewUnstartedServer(http.HandlerFunc(order))
srv.Config.MaxHeaderBytes = 4096 // headers: about 4 KB (+ Go's 4 KB slack)
srv.Start()
defer srv.Close()
send := func(name string, header, body int) {
req, _ := http.NewRequest("POST", srv.URL+"/orders", strings.NewReader(strings.Repeat("x", body)))
req.Header.Set("X-Note", strings.Repeat("n", header))
resp, err := http.DefaultClient.Do(req)
if err != nil {
fmt.Println(name, "->", err)
return
}
b, _ := io.ReadAll(resp.Body)
resp.Body.Close()
fmt.Printf("%-13s -> %d %s\n", name, resp.StatusCode, strings.TrimSpace(string(b)))
}
send("normal order", 10, 200)
send("10 MB body", 10, 10<<20)
send("20 KB header", 20<<10, 10)
}
normal order -> 200 order of 200 bytes accepted
10 MB body -> 200 order of 10485760 bytes accepted
20 KB header -> 431 431 Request Header Fields Too Large
The server happily read a 10 MB body into memory. A thousand such requests at once is 10 GB of RAM. (The 20 KB header was already refused with 431 Request Header Fields Too Large, because we set MaxHeaderBytes = 4096. Go adds about 4 KB of slack on top of the value you set, so the real cut-off is a little higher than the number.)
The fix: wrap the body in http.MaxBytesReader(w, r.Body, n). It returns a reader that fails with *http.MaxBytesError ("http: request body too large") once more than n bytes are read, and tells the server to close the connection afterwards. We check for it with errors.As (episode 25) and answer 413 Request Entity Too Large (http.StatusRequestEntityTooLarge; newer RFCs call it "Content Too Large"):
package main
import (
"errors"
"fmt"
"io"
"net/http"
"net/http/httptest"
"strings"
)
func order(w http.ResponseWriter, r *http.Request) {
r.Body = http.MaxBytesReader(w, r.Body, 1024) // at most 1 KB of body
b, err := io.ReadAll(r.Body)
var tooBig *http.MaxBytesError
if errors.As(err, &tooBig) {
http.Error(w, err.Error(), http.StatusRequestEntityTooLarge) // 413
return
}
fmt.Fprintf(w, "order of %d bytes accepted\n", len(b))
}
func main() {
srv := httptest.NewUnstartedServer(http.HandlerFunc(order))
srv.Config.MaxHeaderBytes = 4096 // headers: about 4 KB (+ Go's 4 KB slack)
srv.Start()
defer srv.Close()
send := func(name string, header, body int) {
req, _ := http.NewRequest("POST", srv.URL+"/orders", strings.NewReader(strings.Repeat("x", body)))
req.Header.Set("X-Note", strings.Repeat("n", header))
resp, err := http.DefaultClient.Do(req)
if err != nil {
fmt.Println(name, "->", err)
return
}
b, _ := io.ReadAll(resp.Body)
resp.Body.Close()
fmt.Printf("%-13s -> %d %s\n", name, resp.StatusCode, strings.TrimSpace(string(b)))
}
send("normal order", 10, 200)
send("10 MB body", 10, 10<<20)
send("20 KB header", 20<<10, 10)
}
normal order -> 200 order of 200 bytes accepted
10 MB body -> 413 http: request body too large
20 KB header -> 431 431 Request Header Fields Too Large
| Limit | Protects | Default | Error |
|---|---|---|---|
Server.MaxHeaderBytes |
request line + headers | 1 MB | 431 Request Header Fields Too Large |
http.MaxBytesReader |
the body, per handler | none | http: request body too large → you answer 413 |
The request context: stop when the customer leaves
Real-life example: a customer orders a five-dish thali, waits half a second and walks out. A good kitchen stops cooking. A bad one cooks all five dishes for nobody.
Every *http.Request carries a context, r.Context(). The server cancels it when the client disconnects (or when the request finishes, or when an HTTP/2 stream is reset). The obvious kitchen ignores it:
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"time"
)
func cook(w http.ResponseWriter, r *http.Request) { // 5 dishes, 200 ms each
for i := 1; i <= 5; i++ {
time.Sleep(200 * time.Millisecond) // cook one dish
}
fmt.Println(" kitchen: cooked all 5 dishes")
fmt.Fprintln(w, "thali ready")
}
func main() {
srv := httptest.NewServer(http.HandlerFunc(cook))
defer srv.Close()
for _, wait := range []time.Duration{2 * time.Second, 500 * time.Millisecond} {
client := &http.Client{Timeout: wait} // how long the customer waits
_, err := client.Get(srv.URL)
fmt.Printf("customer waits %v: err = %v\n", wait, err)
time.Sleep(300 * time.Millisecond)
}
}
kitchen: cooked all 5 dishes
customer waits 2s: err = <nil>
customer waits 500ms: err = Get "http://127.0.0.1:34501": context deadline exceeded (Client.Timeout exceeded while awaiting headers)
kitchen: cooked all 5 dishes
The second customer gave up after 500 ms (their http.Client{Timeout: ...}, more in episode 63), but the kitchen still "cooked all 5 dishes". In a real server that's wasted database queries and CPU for a user who is gone.
The fix: between steps, select on r.Context().Done():
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"time"
)
func cook(w http.ResponseWriter, r *http.Request) { // 5 dishes, 200 ms each
for i := 1; i <= 5; i++ {
select {
case <-r.Context().Done(): // the customer left: stop cooking
fmt.Printf(" kitchen: stopped after %d dishes: %v\n", i-1, r.Context().Err())
return
case <-time.After(200 * time.Millisecond):
}
}
fmt.Println(" kitchen: cooked all 5 dishes")
fmt.Fprintln(w, "thali ready")
}
func main() {
srv := httptest.NewServer(http.HandlerFunc(cook))
defer srv.Close()
for _, wait := range []time.Duration{2 * time.Second, 500 * time.Millisecond} {
client := &http.Client{Timeout: wait} // how long the customer waits
_, err := client.Get(srv.URL)
fmt.Printf("customer waits %v: err = %v\n", wait, err)
time.Sleep(300 * time.Millisecond)
}
}
kitchen: cooked all 5 dishes
customer waits 2s: err = <nil>
kitchen: stopped after 2 dishes: context canceled
customer waits 500ms: err = Get "http://127.0.0.1:42669": context deadline exceeded (Client.Timeout exceeded while awaiting headers)
Now the kitchen "stopped after 2 dishes: context canceled". The same context should be passed to everything the handler calls that can take a while: db.QueryContext(r.Context(), ...), http.NewRequestWithContext(r.Context(), ...) and so on (episode 51: the context is the first parameter).
Graceful shutdown
Real-life example: closing time. A bad shop pulls the shutter down on customers who are mid-order. A good shop turns the sign to "closed", lets the people inside finish, then locks up.
When you deploy a new version, the old process must stop. Docker and Kubernetes send SIGTERM (a polite "please stop" signal), and pressing Ctrl+C in a terminal sends SIGINT (an "interrupt" signal). signal.NotifyContext gives you a context that is cancelled when one of those signals arrives. In the demo the program sends SIGINT to itself with syscall.Kill so the run is repeatable.
The obvious way to stop is srv.Close(), which closes every connection immediately:
package main
import (
"context"
"fmt"
"io"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /pack", func(w http.ResponseWriter, r *http.Request) {
time.Sleep(time.Second) // packing an order takes a second
fmt.Fprintln(w, "order packed")
})
srv := &http.Server{Addr: "127.0.0.1:8090", Handler: mux}
go func() {
err := srv.ListenAndServe() // blocks until the server stops
fmt.Println("ListenAndServe returned:", err)
}()
go func() { // a customer is waiting for an order
time.Sleep(100 * time.Millisecond)
resp, err := http.Get("http://127.0.0.1:8090/pack")
if err != nil {
fmt.Println("customer:", err)
return
}
b, _ := io.ReadAll(resp.Body)
fmt.Printf("customer: %d %s", resp.StatusCode, b)
}()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
time.Sleep(300 * time.Millisecond)
syscall.Kill(os.Getpid(), syscall.SIGINT) // as if you pressed Ctrl+C
<-ctx.Done()
fmt.Println("got Ctrl+C, stopping...")
start := time.Now()
srv.Close() // stop NOW
fmt.Printf("stopped in %.1fs\n", time.Since(start).Seconds())
time.Sleep(200 * time.Millisecond)
}
got Ctrl+C, stopping...
ListenAndServe returned: http: Server closed
customer: Get "http://127.0.0.1:8090/pack": EOF
stopped in 0.0s
The customer's order was cut off: EOF. The fix is srv.Shutdown(ctx): stop listening (no new customers), close idle connections, wait for running requests to finish, then return. The context sets the longest you'll wait:
package main
import (
"context"
"fmt"
"io"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /pack", func(w http.ResponseWriter, r *http.Request) {
time.Sleep(time.Second) // packing an order takes a second
fmt.Fprintln(w, "order packed")
})
srv := &http.Server{Addr: "127.0.0.1:8090", Handler: mux}
go func() {
err := srv.ListenAndServe() // blocks until the server stops
fmt.Println("ListenAndServe returned:", err)
}()
go func() { // a customer is waiting for an order
time.Sleep(100 * time.Millisecond)
resp, err := http.Get("http://127.0.0.1:8090/pack")
if err != nil {
fmt.Println("customer:", err)
return
}
b, _ := io.ReadAll(resp.Body)
fmt.Printf("customer: %d %s", resp.StatusCode, b)
}()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
time.Sleep(300 * time.Millisecond)
syscall.Kill(os.Getpid(), syscall.SIGINT) // as if you pressed Ctrl+C
<-ctx.Done()
fmt.Println("got Ctrl+C, stopping...")
start := time.Now()
sctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err := srv.Shutdown(sctx) // stop new requests, let running ones finish
fmt.Printf("Shutdown: %v, after %.1fs\n", err, time.Since(start).Seconds())
time.Sleep(200 * time.Millisecond)
}
got Ctrl+C, stopping...
ListenAndServe returned: http: Server closed
customer: 200 order packed
Shutdown: <nil>, after 1.1s
Things to notice:
ListenAndServereturnshttp.ErrServerClosed("http: Server closed") as soon asShutdownorCloseis called. That's the normal way to stop, not a failure, so check!errors.Is(err, http.ErrServerClosed)before treating it as an error.- Because
ListenAndServereturns right away,mainmust wait forShutdownto return; ifmainexits, the program dies and in-flight requests die with it. - If the context runs out first,
Shutdownreturnscontext deadline exceeded, and the remaining requests are cut off when the process exits. Real run with a 200 ms deadline:
got Ctrl+C, stopping...
ListenAndServe returned: http: Server closed
Shutdown: context deadline exceeded, after 0.2s
Shutdowndoes not wait for hijacked connections such as WebSockets; usesrv.RegisterOnShutdownto tell those to finish.
TLS, ListenAndServeTLS and HTTP/2
TLS (Transport Layer Security) encrypts the connection so nobody on the network can read or change the traffic; HTTP over TLS is HTTPS. The server proves who it is with a certificate (a signed file saying "this key belongs to raju.in") and keeps the matching private key secret. A client trusts a certificate only if a certificate authority (CA) it already trusts signed it.
HTTP/2 is the newer version of HTTP: the same methods, headers and status codes, but sent as binary frames, with many requests sharing one connection at once (multiplexing) and compressed headers. Go's server and client speak HTTP/2 automatically over HTTPS (since Go 1.6).
package main
import (
"crypto/tls"
"fmt"
"io"
"net/http"
"net/http/httptest"
)
func main() {
h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "you came over %s\n", r.Proto)
})
srv := httptest.NewUnstartedServer(h)
srv.EnableHTTP2 = true
srv.StartTLS() // HTTPS with a test certificate
defer srv.Close()
fmt.Println("server:", srv.URL)
_, err := http.Get(srv.URL) // a client that doesn't trust the test certificate
fmt.Println("plain client:", err)
resp, err := srv.Client().Get(srv.URL) // a client that trusts it
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Printf("trusted client: %s, %s, body: %s", resp.Proto, tls.VersionName(resp.TLS.Version), b)
err = http.ListenAndServeTLS("127.0.0.1:8443", "cert.pem", "key.pem", h)
fmt.Println("ListenAndServeTLS:", err)
}
server: https://127.0.0.1:33167
2026/11/13 11:29:14 http: TLS handshake error from 127.0.0.1:44838: remote error: tls: bad certificate
plain client: Get "https://127.0.0.1:33167": tls: failed to verify certificate: x509: certificate signed by unknown authority
trusted client: HTTP/2.0, TLS 1.3, body: you came over HTTP/2.0
ListenAndServeTLS: open cert.pem: no such file or directory
httptestservers needEnableHTTP2 = truebeforeStartTLS(); a realhttp.Serverwith TLS enables HTTP/2 on its own.- The plain
http.Getrefused the test certificate:x509: certificate signed by unknown authority, and the server logged the failed handshake.srv.Client()is a client set up to trust the test certificate, and it got HTTP/2.0 over TLS 1.3. http.ListenAndServeTLS(addr, certFile, keyFile, h)(orsrv.ListenAndServeTLS(certFile, keyFile)) is how a real server starts HTTPS. Without the files:open cert.pem: no such file or directory. Real certificates come from a CA such as Let's Encrypt (free, automated), orgolang.org/x/crypto/acme/autocertgets them for you. Often a load balancer or reverse proxy does TLS and the Go server speaks plain HTTP behind it.
Streaming responses: http.Flusher and server-sent events
Real-life example: a delivery-tracking page. You want "order received", then "chai brewing", then "out for delivery" as each happens, not all three at the end.
ResponseWriter buffers (collects) what you write and sends it in chunks or at the end, which is efficient but bad for live updates. A writer that also implements http.Flusher has a Flush() method that sends everything buffered now. We check for it with a type assertion (episode 22): f, ok := w.(http.Flusher).
Server-sent events (SSE) is a simple standard for a server pushing updates to a browser over one long HTTP response: Content-Type: text/event-stream, and each event is a data: ... line followed by a blank line. In a browser, new EventSource("/status") receives them.
package main
import (
"bufio"
"fmt"
"net/http"
"net/http/httptest"
"time"
)
func status(w http.ResponseWriter, r *http.Request) { // order status, live
w.Header().Set("Content-Type", "text/event-stream") // server-sent events
f, canFlush := w.(http.Flusher)
for _, s := range []string{"order received", "chai brewing", "out for delivery"} {
fmt.Fprintf(w, "data: %s\n\n", s) // one event = "data: ..." + blank line
if canFlush && r.URL.Query().Get("flush") == "yes" {
f.Flush() // send what we have NOW
}
time.Sleep(500 * time.Millisecond)
}
}
func main() {
srv := httptest.NewServer(http.HandlerFunc(status))
defer srv.Close()
for _, flush := range []string{"no", "yes"} {
fmt.Println("flush =", flush)
start := time.Now()
resp, _ := http.Get(srv.URL + "?flush=" + flush)
sc := bufio.NewScanner(resp.Body)
for sc.Scan() {
if sc.Text() != "" {
fmt.Printf(" at %.1fs %s\n", time.Since(start).Seconds(), sc.Text())
}
}
resp.Body.Close()
}
}
flush = no
at 1.5s data: order received
at 1.5s data: chai brewing
at 1.5s data: out for delivery
flush = yes
at 0.0s data: order received
at 0.5s data: chai brewing
at 1.0s data: out for delivery
Without flushing, all three events arrived together at 1.5 s, when the handler returned. With Flush() after each one, they arrived at 0.0, 0.5 and 1.0 s: live.
Notes for streaming in production:
- A server-wide
WriteTimeoutwill cut long streams. Either leave it at 0 for a streaming server and rely on other limits, or extend it per request withhttp.NewResponseController(w).SetWriteDeadline(...)(Go 1.20+). - Stop the stream when
r.Context().Done()fires (the browser tab closed). - Wrapping
win middleware can hideFlush;http.NewResponseController(w).Flush()looks through wrappers that have anUnwrapmethod (episode 64).
A production-ready server template
Every piece together: timeouts, a header limit, signals, and graceful shutdown.
// A production-ready starting point for a Go HTTP server.
package main
import (
"context"
"errors"
"fmt"
"log"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /menu", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "masala chai ₹20")
})
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 5 * time.Second, // slow clients can't hold a connection while sending headers
ReadTimeout: 10 * time.Second, // the whole request, body included
WriteTimeout: 15 * time.Second, // writing the response
IdleTimeout: 60 * time.Second, // keep-alive connections waiting for the next request
MaxHeaderBytes: 64 << 10, // 64 KB of headers (default 1 MB)
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
go func() {
log.Printf("listening on %s", srv.Addr)
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatalf("listen: %v", err) // a real failure, e.g. port in use
}
}()
<-ctx.Done() // Ctrl+C or SIGTERM (what Docker/Kubernetes send)
log.Println("shutting down...")
sctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
if err := srv.Shutdown(sctx); err != nil {
log.Printf("shutdown: %v", err) // context deadline exceeded: some requests didn't finish in time
}
log.Println("bye")
}
Real run (go build -o app ., start it, curl localhost:8080/menu, then Ctrl+C via kill -INT):
2026/11/13 11:25:16 listening on :8080
masala chai ₹20
2026/11/13 11:25:16 shutting down...
2026/11/13 11:25:16 bye
Pick values that fit your app: ReadHeaderTimeout small (a few seconds), WriteTimeout above your slowest handler, Shutdown timeout below the time your platform waits before killing the process (Kubernetes sends SIGTERM, waits a grace period of 30 seconds by default, then sends SIGKILL).
Mini project: Raju's production menu server
GET /menureturns the menu.POST /ordersaccepts at most 1 KB (413 otherwise) and answers 201.GET /cooktakes 1 second and stops early when the client leaves.GET /statusstreams three server-sent events, flushed one by one.- An
http.Serverwith timeouts andMaxHeaderBytes, shut down gracefully on Ctrl+C / SIGTERM. - Tests for the body limit and the event stream.
Solution
shop.go:
// Raju's production menu server (Go episode 62 mini project).
package main
import (
"context"
"errors"
"fmt"
"io"
"log"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
// Routes builds all the handlers.
func Routes() http.Handler {
mux := http.NewServeMux()
mux.HandleFunc("GET /menu", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "masala chai ₹20")
})
mux.HandleFunc("POST /orders", func(w http.ResponseWriter, r *http.Request) {
r.Body = http.MaxBytesReader(w, r.Body, 1024) // 1 KB is plenty for an order
b, err := io.ReadAll(r.Body)
var tooBig *http.MaxBytesError
if errors.As(err, &tooBig) {
http.Error(w, err.Error(), http.StatusRequestEntityTooLarge)
return
}
if err != nil {
http.Error(w, "bad body", http.StatusBadRequest)
return
}
w.WriteHeader(http.StatusCreated)
fmt.Fprintf(w, "order of %d bytes accepted\n", len(b))
})
mux.HandleFunc("GET /cook", func(w http.ResponseWriter, r *http.Request) {
for i := 1; i <= 5; i++ {
select {
case <-r.Context().Done(): // the customer left
log.Printf("cook: stopped after %d dishes: %v", i-1, r.Context().Err())
return
case <-time.After(200 * time.Millisecond):
}
}
fmt.Fprintln(w, "thali ready")
})
mux.HandleFunc("GET /status", func(w http.ResponseWriter, r *http.Request) {
f, ok := w.(http.Flusher)
if !ok {
http.Error(w, "streaming unsupported", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-cache")
for _, s := range []string{"order received", "chai brewing", "out for delivery"} {
select {
case <-r.Context().Done():
return
default:
}
fmt.Fprintf(w, "data: %s\n\n", s)
f.Flush()
time.Sleep(300 * time.Millisecond)
}
})
return mux
}
// NewServer returns an http.Server with safe limits.
func NewServer(addr string) *http.Server {
return &http.Server{
Addr: addr,
Handler: Routes(),
ReadHeaderTimeout: 5 * time.Second,
ReadTimeout: 10 * time.Second,
WriteTimeout: 0, // 0 on purpose: /status streams; per-request deadlines instead
IdleTimeout: 60 * time.Second,
MaxHeaderBytes: 64 << 10,
}
}
func main() {
srv := NewServer(":8080")
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
go func() {
if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
log.Fatal(err)
}
}()
log.Println("Raju's server on :8080")
<-ctx.Done()
sctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
log.Println("shutdown:", srv.Shutdown(sctx))
}
shop_test.go:
package main
import (
"bufio"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
func TestOrders(t *testing.T) {
for _, tc := range []struct {
name string
size int
want int
}{{"small", 100, 201}, {"huge", 2048, 413}} {
rec := httptest.NewRecorder()
req := httptest.NewRequest("POST", "/orders", strings.NewReader(strings.Repeat("x", tc.size)))
Routes().ServeHTTP(rec, req)
if rec.Code != tc.want {
t.Errorf("%s: got %d, want %d", tc.name, rec.Code, tc.want)
}
t.Logf("%-5s %d %q", tc.name, rec.Code, rec.Body.String())
}
}
func TestStatusStream(t *testing.T) {
srv := httptest.NewServer(Routes())
defer srv.Close()
resp, err := http.Get(srv.URL + "/status")
if err != nil {
t.Fatal(err)
}
defer resp.Body.Close()
if ct := resp.Header.Get("Content-Type"); ct != "text/event-stream" {
t.Errorf("Content-Type = %q", ct)
}
sc := bufio.NewScanner(resp.Body)
var events []string
for sc.Scan() {
if line, ok := strings.CutPrefix(sc.Text(), "data: "); ok {
events = append(events, line)
}
}
t.Logf("events: %q", events)
if len(events) != 3 {
t.Errorf("got %d events, want 3", len(events))
}
}
Real run:
$ go vet . && go test -v .
=== RUN TestOrders
shop_test.go:23: small 201 "order of 100 bytes accepted\n"
shop_test.go:23: huge 413 "http: request body too large\n"
--- PASS: TestOrders (0.00s)
=== RUN TestStatusStream
shop_test.go:45: events: ["order received" "chai brewing" "out for delivery"]
--- PASS: TestStatusStream (0.90s)
PASS
ok shop 0.907s
WriteTimeout is 0 on purpose because /status streams; the other limits still protect the server, and a long stream could use http.NewResponseController(w).SetWriteDeadline per request instead.
Common mistakes (and the real messages)
| Mistake | What you see | Why | Fix |
|---|---|---|---|
http.ListenAndServe on the internet |
slow clients hold connections forever; file descriptors run out | every timeout is 0 = none | an http.Server with ReadHeaderTimeout etc. |
| no body limit | a 10 MB body read into memory | io.ReadAll reads everything |
http.MaxBytesReader → http: request body too large, 413 |
WriteTimeout shorter than the handler |
client gets EOF, handler keeps running |
the connection is killed, not the handler | longer WriteTimeout or per-request deadlines |
ignoring r.Context() |
work continues after the client left | nobody checks the cancel signal | select on r.Context().Done(), pass the context down |
srv.Close() on deploy |
customer gets EOF |
closes connections immediately | srv.Shutdown(ctx) |
treating ErrServerClosed as a failure |
log.Fatal prints http: Server closed and exits before Shutdown finishes |
it's the normal stop result | !errors.Is(err, http.ErrServerClosed) |
main returns right after calling Shutdown in a goroutine |
requests cut off | the program exited | wait for Shutdown to return |
| Shutdown timeout too short | context deadline exceeded |
requests needed longer | bigger timeout (below the platform's kill time) |
| missing certificate files | open cert.pem: no such file or directory |
wrong path | correct paths, or autocert / a proxy doing TLS |
| self-signed cert with a normal client | x509: certificate signed by unknown authority |
no trusted CA signed it | a real CA cert (tests: srv.Client()) |
streaming without Flush |
everything arrives at the end | the writer buffers | http.Flusher / ResponseController.Flush |
Practice
- Set only
ReadTimeout: 2 * time.Second. What areReadHeaderTimeoutandIdleTimeoutin effect? - A file-upload endpoint must accept up to 50 MB, every other endpoint 1 MB. Where do you put each limit?
- Change the kitchen so it also passes its context to a helper
fetchPrice(ctx, item). What shouldfetchPricedo whenctxis cancelled? - Your Kubernetes pod gets 30 seconds after SIGTERM before it is killed. What timeout do you give
Shutdown, and why? - Write the handler line that sends one SSE event named
pricewith data20.
Solutions
1. Both use ReadTimeout when they are zero, so both are effectively 2 seconds.
2. http.MaxBytesReader(w, r.Body, 50<<20) in the upload handler and http.MaxBytesReader(w, r.Body, 1<<20) in the others (often in a middleware that skips the upload route, episode 64). MaxHeaderBytes stays small for all.
3. Return early with ctx.Err() (or use the context in its own I/O, e.g. http.NewRequestWithContext(ctx, ...) so the call is cancelled too).
4. Something under 30 s, like 20-25 s, so Shutdown finishes (or gives up cleanly and you log it) before the kill arrives.
5. fmt.Fprintf(w, "event: price\ndata: 20\n\n") followed by f.Flush(). A browser listens with es.addEventListener("price", ...).
Quick quiz
1. A server is started with http.ListenAndServe(":8080", mux). A client sends headers one byte per minute. When does the server give up? (From the video.)
A. after 30 seconds · B. after 1 minute · C. never · D. after the 1 MB header limit
Answer
C. Every timeout is zero, which means no timeout. (D only applies if the client ever sends 1 MB.)
2. srv.Shutdown(ctx) is called while one request is running. What does ListenAndServe return, and when?
Answer
http.ErrServerClosed ("http: Server closed"), immediately. Shutdown itself returns once the running request finishes (or the context expires).
3. A handler writes three SSE events with a 500 ms sleep between them but never flushes. When does the browser see the first event?
Answer
When the handler returns (after 1.5 s in the video), all three together.
Interview questions
- Why is
http.ListenAndServenot production-ready? It uses anhttp.Serverwith no timeouts, so slow or idle clients can hold connections and file descriptors indefinitely. ReadTimeoutvsReadHeaderTimeout?ReadHeaderTimeoutcovers only the request line and headers;ReadTimeoutcovers the whole request including the body.ReadHeaderTimeoutstops slow-header clients without punishing slow uploads.- What does
WriteTimeoutdo to a slow handler? Nothing to the handler; when the deadline passes, writes fail and the connection is closed, so the client sees a dropped connection. - How do you limit request body size?
http.MaxBytesReader; check for*http.MaxBytesErrorand answer 413. - When is
r.Context()cancelled? When the client's connection closes, the request is cancelled (HTTP/2), orServeHTTPreturns. ShutdownvsClose?Closecloses everything immediately;Shutdownstops accepting, closes idle connections and waits for active ones until the context ends.- What signal does Kubernetes send to stop a pod? SIGTERM, then SIGKILL after the grace period; catch SIGTERM with
signal.NotifyContext. - How do you get HTTP/2 in Go? Serve over TLS;
net/httpenables HTTP/2 automatically (since Go 1.6). - How do you stream a response? Write, then
Flushviahttp.Flusherorhttp.NewResponseController(w).Flush(); for browsers, use SSE (text/event-stream).
Glossary
| Term | Meaning | Example |
|---|---|---|
| Production | the real deployment real users use | Raju's public server |
| Client / server | who asks / who answers | http.Get / http.Server |
| Connection | an open TCP line between client and server | one per browser tab (HTTP/1.1) |
| File descriptor | the OS's number for an open file or socket; limited per process | ulimit -n → 1024 |
| Timeout | the longest wait before giving up | 5 * time.Second |
| Slow client (Slowloris) | a client that sends a request very slowly to hold a connection | one header line every 200 ms |
http.Server |
the struct that configures and runs an HTTP server | &http.Server{Addr: ":8080"} |
Addr |
the address to listen on | ":8080" |
ReadHeaderTimeout |
time allowed to read the request headers | 5 * time.Second |
ReadTimeout |
time allowed to read the whole request | 10 * time.Second |
WriteTimeout |
time allowed to write the response | 15 * time.Second |
IdleTimeout |
how long a keep-alive connection waits for the next request | 60 * time.Second |
| Keep-alive | reusing one connection for many requests | HTTP/1.1 default |
MaxHeaderBytes |
maximum size of the request line and headers | 64 << 10 |
DefaultMaxHeaderBytes |
the default header limit | 1 MB |
| 431 Request Header Fields Too Large | headers over the limit | a 20 KB header |
http.MaxBytesReader |
wraps a body so reading more than n bytes fails | http.MaxBytesReader(w, r.Body, 1024) |
*http.MaxBytesError |
the error type returned when the limit is hit | http: request body too large |
| 413 Request Entity Too Large | status for a too-big body | http.StatusRequestEntityTooLarge |
errors.As |
finds an error of a given type in a chain | errors.As(err, &tooBig) |
r.Context() |
the request's context, cancelled when the client leaves | <-r.Context().Done() |
context canceled |
the error after a context is cancelled | kitchen stopped after 2 dishes |
context deadline exceeded |
the error after a context's time runs out | short Shutdown timeout |
| Graceful shutdown | stop taking new work, finish the current work, then exit | srv.Shutdown(ctx) |
Server.Shutdown |
graceful stop with a context for the maximum wait | srv.Shutdown(sctx) |
Server.Close |
immediate stop, drops connections | customer gets EOF |
http.ErrServerClosed |
what ListenAndServe returns after Shutdown/Close |
http: Server closed |
EOF |
"end of file": the other side closed the connection | Get "...": EOF |
| Signal | a message from the OS to a process | SIGINT, SIGTERM |
| SIGINT | interrupt signal, sent by Ctrl+C | os.Interrupt |
| SIGTERM | polite stop signal from Docker/Kubernetes | syscall.SIGTERM |
signal.NotifyContext |
a context cancelled when a signal arrives | signal.NotifyContext(ctx, os.Interrupt) |
| TLS | encryption and identity for a connection | TLS 1.3 |
| HTTPS | HTTP over TLS | https://raju.in |
| Certificate | a signed statement that a key belongs to a site | cert.pem |
| Private key | the secret half of the key pair | key.pem |
| Certificate authority (CA) | an organisation clients trust to sign certificates | Let's Encrypt |
x509 |
the standard format of certificates; Go's crypto/x509 checks them |
x509: certificate signed by unknown authority |
ListenAndServeTLS |
starts an HTTPS server with a cert and key file | srv.ListenAndServeTLS("cert.pem", "key.pem") |
| HTTP/2 | binary, multiplexed version of HTTP; automatic over TLS in Go | resp.Proto == "HTTP/2.0" |
| Multiplexing | many requests at the same time on one connection | HTTP/2 streams |
httptest.NewUnstartedServer |
a test server you configure before starting | EnableHTTP2, StartTLS() |
| Streaming response | a response sent in pieces over time | live order status |
| Buffer | memory that collects output before sending | ResponseWriter's buffer |
http.Flusher |
interface with Flush(): send buffered data now |
w.(http.Flusher) |
http.ResponseController |
Go 1.20+ helper to Flush, set deadlines, through wrappers | http.NewResponseController(w).Flush() |
| Server-sent events (SSE) | text/event-stream responses of data: ... events |
data: chai brewing |
EventSource |
the browser API that reads SSE | new EventSource("/status") |
Summary
http.ListenAndServehas no timeouts: a slow client can hold a connection forever. Use anhttp.ServerwithReadHeaderTimeout,ReadTimeout,WriteTimeout,IdleTimeoutandMaxHeaderBytes.- Limit bodies with
http.MaxBytesReader(413) and headers withMaxHeaderBytes(431). r.Context()is cancelled when the client leaves; check it and pass it down.- Stop with
signal.NotifyContext+srv.Shutdown(ctx), notClose;ListenAndServereturnshttp.ErrServerClosed. - TLS with
ListenAndServeTLS(or a proxy) gives HTTPS, and Go speaks HTTP/2 over it automatically. - Stream with
http.Flusher/ResponseController.Flush; SSE istext/event-streamwithdata:lines.
Next episode: HTTP clients done right: http.Client timeouts, the Transport and connection pooling, always closing resp.Body, contexts, retries with backoff and jitter, idempotency, circuit breakers and cookie jars.