Testable Go HTTP Services With Graceful Shutdown

Go, http

Inspired by How I write Go HTTP services after seven years, I thought it worth while to share how I’ve been writing Go HTTP services since the approach is very similar albeit with a couple of minor but useful additions.

In my use case, there’s multiple asynchronous things happening in the HTTP server using channels. As requests come in, data is being created and sent onto a channel, which is then processed in the background via go routines. The goal was 1) to create an HTTP server object that is fully testable in an end-to-end scenario. And 2) Supports graceful shutdown, such that any queues can be cleared and connections closed when the program exits.

Below is how I achieved it (minus the application specific channel logic mentioned above).

The HTTP Server Struct

First, let’s look at the HTTP server and it’s methods to start:

  • NewServer(port int) simply returns a new instance. This is where you could initialize database connections before starting the HTTP server for example.
  • Start() just starts the HTTP server. This method is blocking.
  • Shutdown() closes the HTTP server - this is where you could also close database connections or other cleanup tasks before the program exits.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
package xserver

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/gorilla/mux"
)

type Server struct {
	Router     *mux.Router
	HttpServer *http.Server
	Port       int
}

// NewServer returns an initialized instance of a new server
func NewServer(port int) *Server {
	s := &Server{}
	s.Port = port

	s.Router = mux.NewRouter()

	// setup routes
	s.Router.HandleFunc("/", s.handleHome())
	s.Router.HandleFunc("/ping", s.handlePing())

	s.HttpServer = &http.Server{
		Handler:      s.Router,
		Addr:         fmt.Sprintf("127.0.0.1:%d", s.Port),
		WriteTimeout: 15 * time.Second,
		ReadTimeout:  15 * time.Second,
	}
	return s
}

// Start http server. This method is blocking.
func (s *Server) Start() {
	s.HttpServer.ListenAndServe()
}

// Shutdown stops the HTTP Server
func (s *Server) Shutdown() {

	// clean up for shutdown here!

	//shutdown http server
	ctx, _ := context.WithTimeout(context.Background(), 5*time.Second)
	s.HttpServer.Shutdown(ctx)
	log.Println("Server shutdown gracefully")

}

// handlers
func (s *Server) handleHome() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprint(w, "Welcome!")
	}
}

func (s *Server) handlePing() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprint(w, "pong")
	}
}

Graceful Shutdown

The idea is to start the HTTP server, then gurantee somehow that Shutdown() is called before the program exits. There’s multiple ways to achieve this with Go. Here is the most elegant way I’ve found. I stumbled on this one while Googleing the topic one day and have used it since.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package main

import (
	"os"
	"os/signal"

	"github.com/ezeev/go-examples/xserver"
)

func main() {

	stop := make(chan os.Signal, 1)
	signal.Notify(stop, os.Interrupt)

	server := xserver.NewServer(8081)
	go server.Start()

	<-stop
	server.Shutdown()

}

The first 2 lines inside of main() initialize a channel and signal.Notify() to trigger a message being sent to the channel once an os.Interrupt is received. On line 16, the server is started in a new Go routine. Line 18 will block until it recieves the os.Interrupt signal. At that point, server.Shutdown() is called, which will gracefully close down our HTTP server. That’s all there is to it. Below is the output.

1
2
go run exec/main.go 
^C2017/05/14 22:14:47 Server shutdown gracefully

Safe End to End Testing

The goal is the be able to start the server, use an HTTP client to send real live requests and receive responses from an instance of the HTTP server. All in a simple go test. As a first step, let’s try this (hint: this isn’t safe!)

1
2
3
4
5
6
7
8
9
10
func TestServer(t *testing.T) {

    server := xserver.NewServer(8081)
    go server.Start()

    // run tests against the server here!

    // graceful shutdown
    server.Shutdown()
}

The problem with this code is that we are starting the server in the background (via go routine) which means any code immediately afterwards could be executed before or during the go routine’s execution. If you’re writing to or changing any data that depends on the server instance’s HTTP server, you can get a nil pointer error. In fact, if you take the code that initializes the router and HTTP server and move it into the Start() method, you’re guranteed to get a nil pointer error.

In order to make this safe, we need to add a method to gurantee the HTTP server is fully functional before executing tests.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ServerReady Blocks until the server returns a 200 status code from the /ping endpoint
func (s *Server) ServerReady() bool {
    var client = &http.Client{
        Timeout: time.Second * 5,
    }
    tries := 0
    for {
        tries++
        url := fmt.Sprintf("http://localhost:%d/ping", s.Port)
        resp, _ := client.Get(url)
        if resp.StatusCode == http.StatusOK {
            return true
        } else {
            time.Sleep(time.Second * 1)
        }

        if tries >= 5 {
            panic("Unable to connect to test HTTP server at " + url)
        }
    }
}

And then, update our tests to use it:

1
2
3
4
5
6
7
8
func TestServer(t *testing.T) {
    server := xserver.NewServer(8081)
    go server.Start()
    // wait until the server is ready
    server.ServerReady()
    // run tests against the server here!
    server.Shutdown()
}

Now our test is safe. ServerReady() simply blocks until the /ping endpoint returns a successful response back (200 status code).