Draining and Graceful Shutdown

## The two ways an http.Server can stop An `http.Server` owns two things: one or more listeners (the sockets it accepts new connections on) and a set of live connections, each of which may be idle between requests or actively running a handler. Stopping the server means dealing with both, and `net/http` gives you two methods that make opposite tradeoffs. ### Server.Close — immediate ```go err := srv.Close() ``` `Close` closes the listeners and then closes every connection the server is tracking, whatever state it is in — brand new, actively serving a request, or idle. It returns as soon as that is done, and it returns the error from closing the listeners. There is no waiting and no argument: a client that was three seconds into a two-minute report download simply sees the connection drop, and its HTTP library reports a truncated body or an unexpected EOF. `Close` is the right call for a test that is finished with its server, or as the last resort when a graceful drain has already failed. ### Server.Shutdown — graceful, and bounded by you ```go err := srv.Shutdown(ctx) ``` `Shutdown` runs three steps. First it closes the listeners, so no new connection is accepted (this is also why the serve call returns straight away — see the sentinel error below). Second it closes the connections that are currently idle, because nobody is waiting on them. Third it waits, polling, until every remaining connection has gone idle, and closes each one as it does; connections are not reused for a further request once shutdown has begun, so an active connection goes idle exactly once, when its handler returns and the response is written. The context is the whole point of the method. `Shutdown(context.Background())` waits forever; `Shutdown(ctx)` with a deadline waits at most that long and then returns `ctx.Err()`. What people get wrong is the second half of that sentence: returning the deadline error is all it does. `Shutdown` does not then kill the connections it gave up on, does not cancel the handlers' request contexts, and does not stop the goroutines running them. If you want those requests to actually stop, you have to say so: ```go ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) defer cancel() if err := srv.Shutdown(ctx); err != nil { _ = srv.Close() } ``` That pair — a bounded `Shutdown`, escalating to `Close` — is the shape you should be able to write from memory. ### What both of them share Both mark the server as shut down permanently. A `Server` value is not reusable after either call: calling `ListenAndServe` or `Serve` on it again returns `http.ErrServerClosed` immediately rather than starting to listen. If you need to restart a service in-process, build a new `http.Server`. Both also close the listeners first, which means the serve call that was blocking in another goroutine unblocks with `http.ErrServerClosed` as soon as shutdown *begins*, not when it ends. A program that treats any return from `ListenAndServe` as fatal and exits will therefore kill the process in the middle of the drain it just asked for — the graceful shutdown becomes an abrupt one, with extra steps. And neither method reaches inside your handlers. Shutdown is expressed entirely in terms of connections. A goroutine your handler started and did not wait for is invisible to it; a handler that blocks forever keeps its connection active forever and will keep an unbounded `Shutdown` waiting forever. ### Choosing between them Use `Shutdown` whenever a request being cut off has a cost a user notices: a report download that would have to be restarted, a write that is committed but whose response never arrives, a long poll. Use `Close` when the cost of waiting exceeds the cost of the cut — in tests, in a `defer` in short-lived tooling, and as the escalation after a bounded `Shutdown` has expired. Treating `Close` as "the simple version of Shutdown" is the classic junior mistake; treating `Shutdown` as something that can never take longer than you want, without passing a deadline and following it up with `Close`, is the classic next one.