The following code snippet of Go starts a simple HTTP server that responds with “Hello World” to every request it gets.
1func main() {
2 server := &http.Server{
3 Addr: ":8080",
4 Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
5 w.Write([]byte("<html><body><h1>Hello World</h1></body></html>"))
6 }),
7 }
8 if err := server.ListenAndServe(); err != nil {
9 log.Fatal(err)
10 }
11}
But there’s a small problem: the Server.ListenAndServe method blocks until the server terminates—until, to be more specific, one of Server.Close or Server.Shutdown methods is called, or it encounters a fatal error. In this example, the server never terminates (unless there’s an error), and one would have to terminate the process manually from the outside, by for instance hitting Ctrl+C and sending an interrupt signal to the process.
But that would also terminate any HTTP requests that are being read or responses being written at that moment, mid-flight. This is not of course, especially for a production service, the optimal way this should work.
The Server.Shutdown method, in fact, exists for this particular use case, for shutting down the server gracefully, after waiting until all connections have returned to idle. In the following snippet, the program waits until it receives a SIGINT or a SIGKILL signal, and when it does, it shuts down the HTTP server gracefully before exiting the program.
(If you’re unfamiliar with Go’s channels or context.Context, you most definitely won’t understand how the following works. But if you’re familiar with those two things, the following should be easy to read and understand.)
1func main() {
2 server := &http.Server{
3 Addr: ":8080",
4 Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
5 w.Write([]byte("<html><body><h1>Hello World</h1></body></html>"))
6 }),
7 }
8
9 // From the documentation of the signal package:
10 //
11 // NotifyContext returns a copy of the parent context that is marked done
12 // (its Done channel is closed) when one of the listed signals arrives,
13 // when the returned stop function is called, or when the parent context's
14 // Done channel is closed, whichever happens first.
15 //
16 // ....
17 ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, os.Kill)
18 defer stop()
19
20 go func() {
21 // ListenAndServe always returns a non-nil error. And if it returns as a
22 // result of a call to Server.Close or Server.Shutdown, it returns
23 // http.ErrServerClosed.
24 if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
25 log.Printf("ListenAndServe (%s) error: %v\n", server.Addr, err)
26 }
27 }()
28
29 // Blocks until the process receives a SIGINT or SIGKILL signal.
30 <-ctx.Done()
31
32 // From the documentation of the http package:
33 //
34 // Shutdown gracefully shuts down the server without interrupting any
35 // active connections. Shutdown works by first closing all open
36 // listeners, then closing all idle connections, and then waiting
37 // indefinitely for connections to return to idle and then shut down.
38 // If the provided context expires before the shutdown is complete,
39 // Shutdown returns the context's error, otherwise it returns any
40 // error returned from closing the [Server]'s underlying Listener(s).
41 //
42 // When Shutdown is called, [Serve], [ListenAndServe], and
43 // [ListenAndServeTLS] immediately return [ErrServerClosed]. Make sure the
44 // program doesn't exit and waits instead for Shutdown to return.
45 //
46 // ....
47 if err := server.Shutdown(context.Background()); err != nil {
48 log.Printf("Error gracefully shutting down server: %v\n", err)
49 }
50 log.Println("Server exited gracefully")
51}
Of course, more complex behavior than this can be implemented, which in some cases might be quite useful. For example, receiving a second interrupt signal, while the program waits until server.Shutdown to return, could be made to exit the process immediately; or there could be a time limit for how long the program waits for server.Shutdown to return; etc.