net/http: Handlers, Middleware, JSON, and Graceful Shutdown

Learning Objectives

By the end of this lesson you can:

• Implement typed JSON handlers with the standard library only, and know where the write order matters.
• Compose middleware as func(http.Handler) http.Handler and reason about chain order.
• Cap request bodies with http.MaxBytesReader and map overflow to a clean 413.
• Apply server-level timeouts and per-request deadlines so a slow client cannot hold a goroutine forever.
• Shut down with srv.Shutdown so in-flight requests finish instead of being cut mid-write.

Quick Review

In lesson 2.1 you built a skeleton where cmd/api owns construction and shutdown, while internal/ holds the implementation. Dependencies arrive as explicit arguments, not package-level globals. This lesson fills in the thing that skeleton serves: http.Handler values, wired the same explicit way (dependencies go into a struct, the struct owns methods that satisfy http.HandlerFunc).

Theory

Handlers are just an interface

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

Everything else is sugar. http.HandlerFunc adapts a plain function to that interface. A method on a struct holding your dependencies is the idiomatic way to inject services:

type API struct {
	store OrderStore
	log   *slog.Logger
}

func (a *API) handleCreateOrder(w http.ResponseWriter, r *http.Request) { /* uses a.store */ }

If you are on Go 1.22 or newer, ServeMux understands method and wildcard patterns: mux.Handle("POST /v1/orders", ...) and mux.HandleFunc("GET /v1/orders/{id}", ...) with r.PathValue("id"). That removes most hand-rolled routing and path-splitting.

Middleware is a handler decorator

The canonical shape is func(http.Handler) http.Handler. It receives the next handler, returns a new one, and can act before and after the call.

flowchart LR
    Req["📥<br/>Request"] --> Rec["🛡️<br/>recover"]
    Rec --> Log["📝<br/>logging"]
    Log --> Mux["🧭<br/>ServeMux"]
    Mux --> H["⚙️<br/>handler"]
    H --> Log
    Log --> Rec
    Rec --> Res["📤<br/>Response"]

Read the chain outside-in: withRecover(withLogging(mux)) means logging runs inside recover, so a panic that logging never sees still produces a 500. Ordering is a design decision, not a detail. Recovery outermost, request ID early, auth after logging (you want the 401 in the log), and anything that needs a deadline close to the handler.

func withLogging(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(rec, r)
		log.Printf("method=%s path=%s status=%d dur=%s",
			r.Method, r.URL.Path, rec.status, time.Since(start))
	})
}

statusRecorder exists because http.ResponseWriter does not expose the status you wrote. You have to capture it in WriteHeader.

JSON: three rules that cover most bugs

1. Set Content-Type, then WriteHeader(status), then encode. Once the status line is flushed, later Header().Set calls are silently ignored.
2. Encode, never marshal-then-write, for responses. On the decode side, use json.NewDecoder(r.Body) and call dec.DisallowUnknownFields() so typos in client payloads fail loudly instead of being dropped.
3. Pick one error envelope and use it everywhere: {"error": {"code": "invalid_payload", "message": "..."}}. Clients should never have to parse two shapes.

Cap the body, cap the time

http.MaxBytesReader wraps the body with a hard limit. When the limit is exceeded the read returns a *http.MaxBytesError, and you map that to 413. Without it, a client can stream gigabytes into your decoder.

On the server side, set all four timeouts. ReadHeaderTimeout is the one people skip and the one that stops slowloris clients from pinning connections open:

srv := &http.Server{
	Addr:              ":8080",
	Handler:           withRecover(withLogging(mux)),
	ReadHeaderTimeout: 2 * time.Second,
	ReadTimeout:       5 * time.Second,
	WriteTimeout:      10 * time.Second,
	IdleTimeout:       60 * time.Second,
}

Read this carefully: these are connection deadlines. When WriteTimeout fires, writes fail, but the handler goroutine keeps running. Only a context deadline actually stops work, which is why r.Context() should be passed into every database call and downstream request.

[!WARNING] http.TimeoutHandler is convenient but it buffers the entire response before sending, so it breaks streaming and long polls. Prefer a context deadline derived from r.Context() for those, and keep TimeoutHandler for small JSON endpoints.

Graceful shutdown

1. Create a context canceled by SIGINT/SIGTERM with `signal.NotifyContext`.
2. Start `ListenAndServe` in a goroutine and send only real errors to a buffered channel.
3. Block on `select` over that error channel and `ctx.Done()`.
4. On signal, call `srv.Shutdown` with a *fresh* context that has a timeout (10s is a good default).
5. Treat `http.ErrServerClosed` from `ListenAndServe` as success, not failure.

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

errCh := make(chan error, 1)
go func() {
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		errCh <- err
	}
}()

select {
case err := <-errCh:
	log.Fatalf("serve: %v", err)
case <-ctx.Done():
	stop() // a second Ctrl+C now kills the process immediately
}

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
	log.Printf("shutdown: %v", err)
}

Shutdown stops accepting new connections, closes idle ones, and waits for active requests. It does not wait for goroutines your handler spawned and forgot. That is the same errgroup discipline from module 1: track them, wait for them, then exit.

Worked Examples

1. Decode with a cap and a typed error

func decodeJSON(w http.ResponseWriter, r *http.Request, dst any) error {
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MiB
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields()
	return dec.Decode(dst)
}

In the handler, errors.As(err, new(*http.MaxBytesError)) selects the 413 branch, and everything else becomes 400 with your error envelope.

2. Write helper used by every endpoint

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(v)
}

Call it exactly once per request. A second call panics with "superfluous WriteHeader" and corrupts the body.

Discussion & Reflection

• Your logging middleware sits inside recovery. What information do you lose on a panic, and where would you move it?
• Shutdown returns context.DeadlineExceeded on a slow request. What should the process do next, and what did the client see?
• Which of your current handlers pass r.Context() into every blocking call, and which ones quietly use context.Background()?

Expert Corner

• Never wire the signal context into Server.BaseContext. Canceling it on SIGTERM kills in-flight request contexts instantly, which is the opposite of graceful.
• Set headers before WriteHeader. This is the single most common JSON bug in code review.
• TimeoutHandler and http.Flusher/Hijacker do not mix. Streaming and WebSocket endpoints need the raw writer.
• Read the body once. If you need it twice (signature check plus decode), buffer with io.ReadAll under the same MaxBytesReader.
• Log status codes through a recorder that also implements Flush and Hijack when you need streaming. A bare wrapper silently disables both.
• After Shutdown returns, close your database pool. Order: HTTP first, dependencies second.

Quick check on the key terms:

The handler interface requires a single method, {{c1::ServeHTTP}}, and http.HandlerFunc adapts a plain function to it. Middleware has the signature func(http.Handler) {{c2::http.Handler}}, which is why chains compose in either direction. When a body exceeds http.MaxBytesReader, decode returns a {{c3::*http.MaxBytesError}} that should become a 413. ListenAndServe reports {{c4::http.ErrServerClosed}} after a graceful shutdown, so treat it as success. Go 1.22 wildcards are read back with r.{{c5::PathValue}}("id"). And the timeout that stops slowloris attacks is {{c6::ReadHeaderTimeout}}.

Summary & Next Steps

Handlers are an interface, middleware is function composition, and both are invisible in behavior until you get the ordering and the write sequence right. Cap the body, set all four server timeouts, pass r.Context() everywhere, and shut down with a fresh deadline so in-flight requests finish. ==Graceful shutdown is a context problem, not a signal problem.==

Next up: you take this skeleton and put Postgres behind it, using database/sql and integration tests against real queries. Everything you wired here, the handler struct, the context propagation, the error envelope, becomes the seam those tests press on.

[
  { "front": "What method must a type implement to be an http.Handler?", "back": "ServeHTTP(http.ResponseWriter, *http.Request)." },
  { "front": "What does http.HandlerFunc do?", "back": "Adapts an ordinary function with the ServeHTTP signature into an http.Handler." },
  { "front": "Canonical middleware signature?", "back": "func(http.Handler) http.Handler." },
  { "front": "In withRecover(withLogging(mux)), which runs first on a request?", "back": "withRecover, the outermost wrapper, so logging runs inside it." },
  { "front": "Why must Content-Type be set before WriteHeader?", "back": "Headers are flushed with the status line; later Set calls are ignored." },
  { "front": "What error does http.MaxBytesReader return on overflow, and which status fits?", "back": "*http.MaxBytesError, mapped to 413 Request Entity Too Large." },
  { "front": "What does json.Decoder.DisallowUnknownFields change?", "back": "Unknown JSON fields become a decode error instead of being ignored." },
  { "front": "Which sentinel error does ListenAndServe return after Shutdown?", "back": "http.ErrServerClosed, which should be treated as success." },
  { "front": "Shutdown vs Close on http.Server?", "back": "Shutdown waits for in-flight requests; Close drops connections immediately." },
  { "front": "Which four http.Server timeouts should you set?", "back": "ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout." },
  { "front": "Do server connection timeouts cancel the handler goroutine?", "back": "No, writes fail but the handler keeps running; only a context deadline stops work." },
  { "front": "Why avoid http.TimeoutHandler for streaming endpoints?", "back": "It buffers the whole response before writing it out." },
  { "front": "What does srv.Shutdown return when in-flight work outlasts its context?", "back": "The context error, typically context.DeadlineExceeded." }
]