[Intermediate] — The standard library as a production HTTP server, and the configuration that separates a toy from something you’d put on the internet.
Source: [reference]. Assumes the Go course and backend foundations.
The two interfaces
The entire server API is two types:
type Handler interface {
ServeHTTP(w http.ResponseWriter, r *http.Request)
}
type HandlerFunc func(http.ResponseWriter, *http.Request) // adapts a func to HandlerThat’s it. Every router, every middleware, every framework in Go is built on Handler — which is why they interoperate. A Chi router is an http.Handler; so is a Gin engine; so is your own function. You can mix them in one process without adapters.
This is unusual. Express middleware doesn’t work in Nest, and a Spring filter isn’t a servlet you can hand elsewhere. Go’s single small interface is the reason its HTTP ecosystem composes.
Routing (Go 1.22+)
mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", getUser)
mux.HandleFunc("POST /users", createUser)
mux.HandleFunc("DELETE /users/{id}", deleteUser)
mux.HandleFunc("GET /files/{path...}", serveFile) // trailing wildcard
mux.HandleFunc("/", notFound) // catch-all
func getUser(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")
}Go 1.22 gave the standard mux method matching and path wildcards, which is the change that made third-party routers optional. Before it, mux.HandleFunc("/users/", ...) matched a prefix and you parsed the method and the ID yourself — genuinely painful, and the reason everyone reached for Chi or Gin.
Precedence is most-specific-wins, not registration order: /users/{id} beats /users/, and a pattern with a method beats one without.
mux.Handle("/api/", http.StripPrefix("/api", apiMux)) // sub-router by compositionThe server, configured properly
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 5 * time.Second,
ReadTimeout: 10 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 120 * time.Second,
MaxHeaderBytes: 1 << 20,
ErrorLog: log.New(os.Stderr, "http: ", log.LstdFlags),
}
log.Fatal(srv.ListenAndServe())
http.ListenAndServe(":8080", mux)has no timeouts at all. A client that opens a connection and sends one byte per minute holds a goroutine and a file descriptor indefinitely. That’s slowloris, and it’s the single most common production mistake in Go web code.
What each timeout covers:
| Field | Covers |
|---|---|
ReadHeaderTimeout | connection accepted → headers fully read. The slowloris defence |
ReadTimeout | connection accepted → request body fully read |
WriteTimeout | end of headers → response written |
IdleTimeout | keep-alive idle time between requests |
WriteTimeout is a wall-clock deadline covering the whole response, so it must exceed your slowest legitimate handler. For streaming or long-poll endpoints, set it to 0 and enforce per-request deadlines with context instead. → Context
The response writer
func handler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json") // headers FIRST
w.WriteHeader(http.StatusCreated) // status SECOND
json.NewEncoder(w).Encode(user) // body LAST
}Order matters and is not enforced. Writing the body implicitly calls WriteHeader(200), so a status set afterwards is silently ignored and logged as superfluous response.WriteHeader call. Headers set after the first write don’t appear at all.
The consequence for error handling: you must decide the status before writing anything. A handler that streams a partial response and then hits an error cannot change its mind — the status is already on the wire.
http.Error(w, "not found", http.StatusNotFound) // sets Content-Type, status, body
http.Redirect(w, r, "/new", http.StatusFound)
http.NotFound(w, r)Reading a request
func createUser(w http.ResponseWriter, r *http.Request) {
ctx := r.Context() // cancelled when the client disconnects
r.URL.Query().Get("filter")
r.Header.Get("Authorization")
r.PathValue("id")
var req CreateUserRequest
dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)) // CAP THE BODY
dec.DisallowUnknownFields()
if err := dec.Decode(&req); err != nil {
http.Error(w, "invalid body", http.StatusBadRequest)
return
}
}Three things worth making habits:
http.MaxBytesReader — without it, json.Decode will happily read a 10GB body into memory. The server does not bound request bodies for you.
DisallowUnknownFields — turns a typo’d field name from a silently-ignored zero value into a 400.
r.Context() — cancelled on client disconnect. Pass it into every database call and outbound request, or you’ll keep doing work for a client that left. This is the whole point of context and it’s the most commonly skipped step.
r.Body is closed by the server; you don’t need to. But if you don’t read it to completion, the connection can’t be reused for keep-alive.
Graceful shutdown
func main() {
srv := &http.Server{Addr: ":8080", Handler: mux}
go func() {
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatalf("listen: %v", err)
}
}()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done() // wait for SIGINT/SIGTERM
shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
log.Printf("forced shutdown: %v", err)
}
}Shutdown stops accepting new connections and waits for in-flight requests to finish, up to the deadline. Without it, a deploy kills requests mid-flight.
This matters more than it sounds under Kubernetes: the moment a pod is marked terminating, it gets SIGTERM while the load balancer may still send it traffic for a few seconds. Handle the signal, drain, then exit.
ErrServerClosed is the expected return from ListenAndServe after Shutdown — treating it as an error is a common noisy-log bug.
As a client
client := &http.Client{
Timeout: 10 * time.Second, // the DEFAULT CLIENT HAS NO TIMEOUT
Transport: &http.Transport{
MaxIdleConns: 100,
MaxIdleConnsPerHost: 10, // default is 2 — usually too low
IdleConnTimeout: 90 * time.Second,
},
}
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
resp, err := client.Do(req)
if err != nil { return err }
defer resp.Body.Close() // MANDATORY
io.Copy(io.Discard, resp.Body) // drain, so the connection is reusedThree real bugs live here:
http.DefaultClient waits forever. Always construct your own with a timeout.
A body you don’t close leaks the connection, and the goroutine reading it. This is the most common source of “my Go service slowly runs out of file descriptors”.
MaxIdleConnsPerHost: 2 is the default, which throttles you badly when calling one backend heavily — connections get closed and reopened instead of pooled.
Reuse one http.Client. Creating one per request defeats connection pooling entirely.
TLS
srv.ListenAndServeTLS("cert.pem", "key.pem")In practice you usually terminate TLS at a reverse proxy or load balancer and run plain HTTP behind it. If you do terminate in Go, autocert handles Let’s Encrypt. → TLS
What the stdlib doesn’t give you
Being honest about the gaps, because “the stdlib is enough” is true but not unconditionally:
- No middleware chaining helper — trivial to write, and note 02 does
- No request validation — you write it or use a library
- No structured request logging — you write it
- No route grouping with shared middleware — the main thing routers add
- No graceful-shutdown wiring — the code above, every time
- No dependency injection — deliberate; Go uses struct fields
None of these are hard. They’re each 10–50 lines you write once. The question is whether you’d rather write and own them or take a dependency — which is what note 03 is about.
Related
- Middleware as Composition — the next layer up
- Testing and Production —
httptestand observability - Go: The Standard Library — the
iointerfaces underneath - The Request Lifecycle — the model this implements
- Go backends
Software engineering
Infrastructure & security
Computer science
Hardware & engineering