SyntaxPilot
Courses/Go Programming/Lesson 62
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 62 of 89

HTTP servers in production

http.Server structReadTimeoutReadHeaderTimeoutWriteTimeoutIdleTimeoutwhy defaults are unsafegraceful shutdown with Server.Shutdownrequest context (r.Context)cancelling work when clients disconnecthttp.MaxBytesReaderListenAndServeTLSHTTP/2 supportstreaming responses and http.Flusherserver-sent events

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 like http.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. The http.Server field docs: ReadTimeout is "the maximum duration for reading the entire request, including the body"; ReadHeaderTimeout is "the amount of time allowed to read request headers"; WriteTimeout is "the maximum duration before timing out writes of the response"; IdleTimeout is "the maximum amount of time to wait for the next request when keep-alives are enabled". For all four, zero means no timeout (IdleTimeout and ReadHeaderTimeout fall back to ReadTimeout).
  • 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 -n shows 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/http runs every connection on its own goroutine.
  • Context (episode 51): a context.Context carries 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:

  • ListenAndServe returns http.ErrServerClosed ("http: Server closed") as soon as Shutdown or Close is 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 ListenAndServe returns right away, main must wait for Shutdown to return; if main exits, the program dies and in-flight requests die with it.
  • If the context runs out first, Shutdown returns context 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
  • Shutdown does not wait for hijacked connections such as WebSockets; use srv.RegisterOnShutdown to 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
  • httptest servers need EnableHTTP2 = true before StartTLS(); a real http.Server with TLS enables HTTP/2 on its own.
  • The plain http.Get refused 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) (or srv.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), or golang.org/x/crypto/acme/autocert gets 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 WriteTimeout will cut long streams. Either leave it at 0 for a streaming server and rely on other limits, or extend it per request with http.NewResponseController(w).SetWriteDeadline(...) (Go 1.20+).
  • Stop the stream when r.Context().Done() fires (the browser tab closed).
  • Wrapping w in middleware can hide Flush; http.NewResponseController(w).Flush() looks through wrappers that have an Unwrap method (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

  1. GET /menu returns the menu.
  2. POST /orders accepts at most 1 KB (413 otherwise) and answers 201.
  3. GET /cook takes 1 second and stops early when the client leaves.
  4. GET /status streams three server-sent events, flushed one by one.
  5. An http.Server with timeouts and MaxHeaderBytes, shut down gracefully on Ctrl+C / SIGTERM.
  6. 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

  1. Set only ReadTimeout: 2 * time.Second. What are ReadHeaderTimeout and IdleTimeout in effect?
  2. A file-upload endpoint must accept up to 50 MB, every other endpoint 1 MB. Where do you put each limit?
  3. Change the kitchen so it also passes its context to a helper fetchPrice(ctx, item). What should fetchPrice do when ctx is cancelled?
  4. Your Kubernetes pod gets 30 seconds after SIGTERM before it is killed. What timeout do you give Shutdown, and why?
  5. Write the handler line that sends one SSE event named price with data 20.
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

  1. Why is http.ListenAndServe not production-ready? It uses an http.Server with no timeouts, so slow or idle clients can hold connections and file descriptors indefinitely.
  2. ReadTimeout vs ReadHeaderTimeout? ReadHeaderTimeout covers only the request line and headers; ReadTimeout covers the whole request including the body. ReadHeaderTimeout stops slow-header clients without punishing slow uploads.
  3. What does WriteTimeout do 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.
  4. How do you limit request body size? http.MaxBytesReader; check for *http.MaxBytesError and answer 413.
  5. When is r.Context() cancelled? When the client's connection closes, the request is cancelled (HTTP/2), or ServeHTTP returns.
  6. Shutdown vs Close? Close closes everything immediately; Shutdown stops accepting, closes idle connections and waits for active ones until the context ends.
  7. What signal does Kubernetes send to stop a pod? SIGTERM, then SIGKILL after the grace period; catch SIGTERM with signal.NotifyContext.
  8. How do you get HTTP/2 in Go? Serve over TLS; net/http enables HTTP/2 automatically (since Go 1.6).
  9. How do you stream a response? Write, then Flush via http.Flusher or http.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.ListenAndServe has no timeouts: a slow client can hold a connection forever. Use an http.Server with ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout and MaxHeaderBytes.
  • Limit bodies with http.MaxBytesReader (413) and headers with MaxHeaderBytes (431).
  • r.Context() is cancelled when the client leaves; check it and pass it down.
  • Stop with signal.NotifyContext + srv.Shutdown(ctx), not Close; ListenAndServe returns http.ErrServerClosed.
  • TLS with ListenAndServeTLS (or a proxy) gives HTTPS, and Go speaks HTTP/2 over it automatically.
  • Stream with http.Flusher / ResponseController.Flush; SSE is text/event-stream with data: 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.