How do you gate a Go readiness handler on an atomic.Bool so it answers 503 once the process starts draining?

## The shape of the state Readiness is one bit of shared state with a very lopsided access pattern: written a handful of times over the process's life (once at the end of warm-up, once when draining starts), read on every probe. That is the textbook case for `sync/atomic`: ```go var ready atomic.Bool ``` `atomic.Bool` has `Load() bool`, `Store(bool)`, `Swap(bool) bool` and `CompareAndSwap(old, new bool) bool`. You almost always need only `Load` and `Store` here. ## Why not a plain bool One goroutine writes the variable while handler goroutines read it concurrently. In Go's memory model that is a data race - not a theoretical one: build with `-race` and the detector will report it the first time a probe overlaps the flip. Two things go wrong without synchronisation. First, the program is simply undefined under the memory model; there is no guarantee that a reading goroutine ever observes the write, so the instance could keep answering 200 forever after it began draining. Second, races are exactly the kind of bug that hides in testing and appears under production load. A `sync.RWMutex` around a plain bool would also be correct, but it is more code and more contention for one word - `atomic.Bool` is the idiomatic answer. ## The handler ```go func readyz(w http.ResponseWriter, r *http.Request) { if !ready.Load() { w.Header().Set("Retry-After", "5") w.WriteHeader(http.StatusServiceUnavailable) return } w.WriteHeader(http.StatusOK) } ``` Two mechanical details matter here. **Header ordering.** `w.Header()` returns the map that will be written; mutating it after `w.WriteHeader` (or after the first `w.Write`) has no effect, because by then the status line and header block are already committed. Set `Retry-After` first, then the status. Getting this backwards is a common bug that silently drops the header without any error - net/http will only complain if you call `WriteHeader` twice, logging a "superfluous response.WriteHeader call". **503 is the right code.** 503 Service Unavailable is the "I am up but cannot take this right now" answer, which is precisely what a draining or still-warming instance means. `Retry-After: 5` on it is a hint, in seconds, that the condition is transient. ## The two transitions **False to true, once, at the end of warm-up.** The zero value of `atomic.Bool` is false, which is the correct starting state: an instance that has not finished loading configuration, running migrations or filling a cache should not be sent traffic. Store true only after the last of those completes. This is the piece people forget - they register the handler and never flip it, or they flip it before the warm-up goroutine has finished, and the platform sends traffic into an instance that immediately errors. **True to false, once, when draining starts.** The termination signal arrives on a channel from `os/signal`: ```go sig := make(chan os.Signal, 1) signal.Notify(sig, syscall.SIGTERM, os.Interrupt) go func() { <-sig ready.Store(false) }() ``` The channel is buffered with capacity 1 because `signal.Notify` never blocks delivering a signal - it drops the signal if the receiver is not ready, so an unbuffered channel can miss it. ## What failing readiness does and does not do This is the part interviewers probe. Storing false changes exactly one thing: the readiness endpoint's answer. The server keeps listening, keeps accepting, and keeps serving every request that arrives - which is not a bug but the entire point. Requests are still in flight, and requests will keep arriving for a while because routing is updated asynchronously by whatever sits in front of the instance. If flipping the flag also stopped the server, you would be dropping exactly the traffic you were trying to protect. So during a drain the instance is in a deliberate split state: readiness says 503, liveness still says 200, and real traffic is served normally. Liveness must keep answering 200 throughout, or the platform will kill the process in the middle of the drain. ## Extensions people reach for, and when they are worth it - **A reason string.** Storing an `atomic.Pointer[string]` or an `atomic.Value` alongside the flag so the 503 body can say "draining" versus "warming" is cheap and helps whoever reads the logs. - **More than one gate.** If several subsystems must be ready, prefer one flag flipped by the code that waits for all of them over a handler that checks several flags - it keeps the readiness decision in one place. - **Dependency checks.** Any check that touches something shared makes readiness correlated across the fleet: one dependency blip takes every instance out of rotation at once. That is a policy decision, not a mechanical one, and it should be made deliberately.