Health and Readiness Handlers

## Two endpoints, two questions A long-running Go HTTP service normally exposes two health endpoints, and the whole design follows from the fact that the platform reacts to them differently. - **Liveness** asks: *is this process wedged in a way that only a restart can fix?* A failing liveness check gets the process killed and started again. - **Readiness** asks: *should this instance receive traffic right now?* A failing readiness check only removes the instance from routing; the process keeps running. Because the consequences differ that sharply, the two handlers should not share an implementation. Reusing one handler for both means every condition that should merely shed traffic instead restarts the process. ## What the liveness handler looks like in Go The honest implementation is a few lines: ```go mux := http.NewServeMux() mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) }) ``` `http.HandlerFunc` is the adapter that lets a plain `func(http.ResponseWriter, *http.Request)` be used where an `http.Handler` is wanted, and `ServeMux.HandleFunc` does that wrapping for you. Nothing else belongs in the body. If you want a body at all, a literal `io.WriteString(w, "ok")` is enough; note that writing a body implicitly sends 200 anyway, so the explicit `WriteHeader` is only for clarity. ## Why "touches nothing" is the rule, not a style preference The handler runs on a goroutine like any other request. Anything it blocks on becomes a reason to kill the process: - **A mutex.** If the handler takes a `sync.Mutex` that the hot request path also holds, then under contention - a slow query holding the lock, say - the health handler simply waits. The probe times out, the check fails, and the platform restarts a process whose only problem was that it was busy. Restarting it drops in-flight work and moves the load onto the remaining instances, which makes contention worse. - **A database or a downstream call.** Now every instance's liveness depends on one shared thing. When that thing has a blip, every replica fails liveness at the same moment and the whole fleet restarts together. This is the classic self-inflicted outage, and it is why the default posture is that liveness performs no I/O at all. - **Aggregating a status report.** Building a JSON document out of "database: ok, cache: ok, queue: ok" is useful for a human debugging endpoint, but it is the wrong body for a liveness probe, because every subsystem it touches is a new way to fail. ## Practical details that come up - **Give it its own path and keep it cheap.** Probes run every few seconds, forever, on every instance. A handler that allocates or logs on each call is measurable noise in profiles and in the access log; many services skip logging the health path entirely so real traffic stays readable. - **Handle it before your middleware chain, or exempt it.** If authentication, rate limiting or request-body reading wraps the health path, then the probe's success depends on that middleware too - which reintroduces exactly the coupling you were avoiding. - **Do not report per-request failures through it.** A handler that starts failing liveness after N 500s is a restart loop waiting to happen: the errors are usually caused by something outside the process, and restarting will not fix them. - **The status code is the payload.** Probes look at the status code. 200 means alive; anything else, or no answer, means not. Do not encode "degraded" as a 200 with a body field that nothing parses. ## The mental model Liveness is a heartbeat, not a diagnosis. It answers "is the runtime still scheduling my goroutines and can the HTTP server still write a response" - which is precisely the condition where a restart genuinely helps. Everything richer than that (is the database reachable, is the cache warm, is the queue backed up) is either readiness or a metric, and belongs where a false alarm costs a routing change or a page, not a process kill.