Graceful HTTP Server Restart in Go: Source Code Analysis and Implementation Details

Classic smooth upgrade uses a /status endpoint and a load balancer to add or remove servers, but it suffers from traffic spikes, downtime during upgrades, and incomplete request handling.

Graceful restart in Go can be achieved with Facebook’s archived grace library, which performs zero‑downtime deployments by forking a new process that inherits listening sockets and signals the old process to shut down after completing in‑flight requests.

The library provides grace.Serve(srv, srvMonitor) which creates an app struct managing listeners, servers, and signal handling. The run method starts listening, serves, and launches goroutines for wait and signalHandler . On SIGINT / SIGTERM it calls a.term() to stop all httpdown.Server instances, while SIGUSR2 triggers a.net.StartProcess() to launch the new process.

Process inheritance is handled via the LISTEN_FDS environment variable. The child extracts file descriptors, creates listeners with net.FileListener , and passes them to the server. The parent sets LISTEN_FDS to the number of listeners and starts the child using os.StartProcess (or syscall.ForkExec ).

Key functions include app.listen() , app.serve() , app.wait() , app.term() , app.signalHandler() , and the Net.StartProcess() method that assembles the file descriptor list, updates the environment, and launches the new binary.

By integrating these components, a Go HTTP service can achieve seamless upgrades without dropping connections.