graceful

README

graceful

This is a fork of Stretchr, Inc.'s graceful, a Go 1.3+ package enabling graceful shutdown of http.Handler servers. This fork allows more fine-grained control over when the server is shutdown.

Usage

Usage of Graceful is simple. Create your http.Handler and pass it to the Run function:

import (
	"fmt"
	"net/http"

	"github.com/andrew-d/graceful"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome to the home page!")
	})

	// This will return when the server has shut down.
	graceful.Run(":3001", mux)
}

Or, create an instance of graceful.GracefulServer, configure the timeout, and have more control over when your server shuts down:

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

	"github.com/andrew-d/graceful"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		fmt.Fprintf(w, "Welcome to the home page!")
	})

	srv := graceful.NewServer()
	srv.Timeout = 60 * time.Second

	go func() {
		// ... catch signals, or otherwise wait to signal shutdown
		srv.Shutdown <- struct{}{}
	}()

	// This will return when the server has shut down.
	srv.Run(":3001", mux)
}

In addition to Run there are the http.Server counterparts ListenAndServe, ListenAndServeTLS and Serve, which allow additional configuration. See the examples for some fully-working demonstrations, or the documentation for the full API.

How It Works

When Graceful is asked to shutdown, it:

1. Disables Keep-Alive connections.
2. Closes the listening socket, allowing another process to listen on that port immediately.
3. Starts a timer of timeout duration to give active requests a chance to finish.
4. If the timeout expires, forcefully closes all active connections.
5. Returns from the function, allowing the server to terminate.

Notes

• If the timeout value is 0, the server never times out, allowing all active requests to complete.
• Sending to the 'Shutdown' channel a second time will forcefully close all open connections.

Documentation

Index

• func ListenAndServe(h *http.Server) error
• func ListenAndServeTLS(h *http.Server, certFile, keyFile string) error
• func Run(addr string, handler http.Handler) error
• type GracefulServer
  • func NewServer() *GracefulServer
  • func (s *GracefulServer) ListenAndServe(srv *http.Server) error
  • func (s *GracefulServer) ListenAndServeTLS(srv *http.Server, certFile, keyFile string) error
  • func (s *GracefulServer) Run(addr string, handler http.Handler) error
  • func (s *GracefulServer) Serve(srv *http.Server, listener net.Listener) error

Functions

func ListenAndServe

func ListenAndServe(h *http.Server) error

Helper function that does the same as GracefulServer.ListenAndServe, automatically shutting down whenever a SIGINT or SIGTERM is sent to the process.

func ListenAndServeTLS

func ListenAndServeTLS(h *http.Server, certFile, keyFile string) error

Helper function that does the same as GracefulServer.ListenAndServeTLS, automatically shutting down whenever a SIGINT or SIGTERM is sent to the process.

func Run

func Run(addr string, handler http.Handler) error

Helper function that does the same as GracefulServer.Run, automatically shutting down whenever a SIGINT or SIGTERM is sent to the process.

Types

type GracefulServer

type GracefulServer struct {
	// The shutdown channel.  Send on this channel to shut down the server.
	// Note that when the send finishes, the server may not yet be shut down - the
	// call to Serve() will return when the shutdown is complete.
	Shutdown chan struct{}

	// Time between when the shutdown has been signalled and all remaining open
	// connections are forcefully closed.  A value of 0 represents no timeout, and
	// that the server should wait until all open connections are closed before
	// returning.
	Timeout time.Duration
}

func NewServer

func NewServer() *GracefulServer

Create a new instance of GracefulServer with a default timeout of 10 seconds.

func (*GracefulServer) ListenAndServe

func (s *GracefulServer) ListenAndServe(srv *http.Server) error

ListenAndServe is equivalent to http.Server.ListenAndServe with graceful shutdown enabled.

func (*GracefulServer) ListenAndServeTLS

func (s *GracefulServer) ListenAndServeTLS(srv *http.Server, certFile, keyFile string) error

ListenAndServeTLS is equivalent to http.Server.ListenAndServeTLS with graceful shutdown enabled.

func (*GracefulServer) Run

func (s *GracefulServer) Run(addr string, handler http.Handler) error

Run serves the given http.Handler with graceful shutdown enabled.

func (*GracefulServer) Serve

func (s *GracefulServer) Serve(srv *http.Server, listener net.Listener) error

Serve is equivalent to http.Server.Serve with graceful shutdown enabled.

This function will return when the server has been properly shut down and all open connections have been closed, or, if the timeout expires, when all remaining open connections have been forcefully closed.