manners

README

Manners

A polite webserver for Go.

Manners allows you to shut your Go webserver down gracefully, without dropping any requests. It can act as a drop-in replacement for the standard library's http.ListenAndServe function:

func main() {
  handler := MyHTTPHandler()
  manners.ListenAndServe(":7000", handler)
}

Then, when you want to shut the server down:

manners.Close()

(Note that this does not block until all the requests are finished. Rather, the call to manners.ListenAndServe will stop blocking when all the requests are finished.)

Manners ensures that all requests are served by incrementing a WaitGroup when a request comes in and decrementing it when the request finishes.

If your request handler spawns Goroutines that are not guaranteed to finish with the request, you can ensure they are also completed with the StartRoutine and FinishRoutine functions on the server.

Known Issues

Manners does not correctly shut down long-lived keepalive connections when issued a shutdown command. Clients on an idle keepalive connection may see a connection reset error rather than a close. See https://github.com/braintree/manners/issues/13 for details.

Compatability

Manners 0.3.0 and above uses standard library functionality introduced in Go 1.3.

Installation

go get github.com/braintree/manners

Documentation

Overview

Package manners provides a wrapper for a standard net/http server that ensures all active HTTP client have completed their current request before the server shuts down.

It can be used a drop-in replacement for the standard http package, or can wrap a pre-configured Server.

eg.

http.Handle("/hello", func(w http.ResponseWriter, r *http.Request) {
  w.Write([]byte("Hello\n"))
})

log.Fatal(manners.ListenAndServe(":8080", nil))

or for a customized server:

s := manners.NewWithServer(&http.Server{
	Addr:           ":8080",
	Handler:        myHandler,
	ReadTimeout:    10 * time.Second,
	WriteTimeout:   10 * time.Second,
	MaxHeaderBytes: 1 << 20,
})
log.Fatal(s.ListenAndServe())

The server will shut down cleanly when the Close() method is called:

go func() {
	sigchan := make(chan os.Signal, 1)
	signal.Notify(sigchan, os.Interrupt, os.Kill)
	<-sigchan
	log.Info("Shutting down...")
	manners.Close()
}()

http.Handle("/hello", myHandler)
log.Fatal(manners.ListenAndServe(":8080", nil))

Index

• func Close() bool
• func ListenAndServe(addr string, handler http.Handler) error
• func ListenAndServeTLS(addr string, certFile string, keyFile string, handler http.Handler) error
• func NewTLSListener(inner net.Listener, config *tls.Config) net.Listener
• func Serve(l net.Listener, handler http.Handler) error
• type GracefulListener
  • func NewListener(l net.Listener) *GracefulListener
  • func (l *GracefulListener) Accept() (net.Conn, error)
  • func (l *GracefulListener) Addr() net.Addr
  • func (l *GracefulListener) Clone() (net.Listener, error)
  • func (l *GracefulListener) Close() error
  • func (l *GracefulListener) GetFile() (*os.File, error)
• type GracefulServer
  • func NewServer() *GracefulServer
  • func NewWithOptions(o Options) *GracefulServer
  • func NewWithServer(s *http.Server) *GracefulServer
  • func (gs *GracefulServer) BlockingClose() bool
  • func (gs *GracefulServer) Close() bool
  • func (gs *GracefulServer) FinishRoutine()
  • func (gs *GracefulServer) GetFile() (*os.File, error)
  • func (gs *GracefulServer) HijackListener(s *http.Server, fn ListenerMutateFunc) (*GracefulServer, error)
  • func (gs *GracefulServer) ListenAndServe() error
  • func (gs *GracefulServer) ListenAndServeTLS(certFile, keyFile string) error
  • func (gs *GracefulServer) ListenAndServeTLSWithConfig(config *tls.Config) error
  • func (gs *GracefulServer) RoutinesCount() int
  • func (gs *GracefulServer) Serve(listener net.Listener) error
  • func (gs *GracefulServer) StartRoutine()
• type ListenerMutateFunc
• type Options
• type StateHandler
• type TCPKeepAliveListener
  • func (ln TCPKeepAliveListener) Accept() (c net.Conn, err error)
• type TLSListener
  • func (l *TLSListener) Accept() (c net.Conn, err error)

Functions

func Close

func Close() bool

Shuts down the default server used by ListenAndServe, ListenAndServeTLS and Serve. It returns true if it's the first time Close is called.

func ListenAndServe

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

ListenAndServe provides a graceful version of the function provided by the net/http package. Call Close() to stop the server.

func ListenAndServeTLS

func ListenAndServeTLS(addr string, certFile string, keyFile string, handler http.Handler) error

ListenAndServeTLS provides a graceful version of the function provided by the net/http package. Call Close() to stop the server.

func NewTLSListener

func NewTLSListener(inner net.Listener, config *tls.Config) net.Listener

NewListener creates a Listener which accepts connections from an inner Listener and wraps each connection with Server. The configuration config must be non-nil and must have at least one certificate.

func Serve

func Serve(l net.Listener, handler http.Handler) error

Serve provides a graceful version of the function provided by the net/http package. Call Close() to stop the server.

Types

type GracefulListener

type GracefulListener struct {
	// contains filtered or unexported fields
}

A GracefulListener differs from a standard net.Listener in one way: if Accept() is called after it is gracefully closed, it returns a listenerAlreadyClosed error. The GracefulServer will ignore this error.

func NewListener

func NewListener(l net.Listener) *GracefulListener

NewListener wraps an existing listener for use with GracefulServer.

Note that you generally don't need to use this directly as GracefulServer will automatically wrap any non-graceful listeners supplied to it.

func (*GracefulListener) Accept

func (l *GracefulListener) Accept() (net.Conn, error)

Accept implements the Accept method in the Listener interface.

func (*GracefulListener) Addr

func (l *GracefulListener) Addr() net.Addr

func (*GracefulListener) Clone

func (l *GracefulListener) Clone() (net.Listener, error)

func (*GracefulListener) Close

func (l *GracefulListener) Close() error

Close tells the wrapped listener to stop listening. It is idempotent.

func (*GracefulListener) GetFile

func (l *GracefulListener) GetFile() (*os.File, error)

type GracefulServer

type GracefulServer struct {
	*http.Server
	// contains filtered or unexported fields
}

A GracefulServer maintains a WaitGroup that counts how many in-flight requests the server is handling. When it receives a shutdown signal, it stops accepting new requests but does not actually shut down until all in-flight requests terminate.

GracefulServer embeds the underlying net/http.Server making its non-override methods and properties avaiable.

It must be initialized by calling NewServer or NewWithServer

func NewServer

func NewServer() *GracefulServer

NewServer creates a new GracefulServer.

func NewWithOptions

func NewWithOptions(o Options) *GracefulServer

NewWithOptions creates a GracefulServer instance with the specified options.

func NewWithServer

func NewWithServer(s *http.Server) *GracefulServer

NewWithServer wraps an existing http.Server object and returns a GracefulServer that supports all of the original Server operations.

func (*GracefulServer) BlockingClose

func (gs *GracefulServer) BlockingClose() bool

BlockingClose is similar to Close, except that it blocks until the last connection has been closed.

func (*GracefulServer) Close

func (gs *GracefulServer) Close() bool

Close stops the server from accepting new requets and begins shutting down. It returns true if it's the first time Close is called.

func (*GracefulServer) FinishRoutine

func (gs *GracefulServer) FinishRoutine()

FinishRoutine decrements the server's WaitGroup. Use this to complement StartRoutine().

func (*GracefulServer) GetFile

func (gs *GracefulServer) GetFile() (*os.File, error)

func (*GracefulServer) HijackListener

func (gs *GracefulServer) HijackListener(s *http.Server, fn ListenerMutateFunc) (*GracefulServer, error)

func (*GracefulServer) ListenAndServe

func (gs *GracefulServer) ListenAndServe() error

ListenAndServe provides a graceful equivalent of net/http.Serve.ListenAndServe.

func (*GracefulServer) ListenAndServeTLS

func (gs *GracefulServer) ListenAndServeTLS(certFile, keyFile string) error

ListenAndServeTLS provides a graceful equivalent of net/http.Serve.ListenAndServeTLS.

func (*GracefulServer) ListenAndServeTLSWithConfig

func (gs *GracefulServer) ListenAndServeTLSWithConfig(config *tls.Config) error

ListenAndServeTLS provides a graceful equivalent of net/http.Serve.ListenAndServeTLS.

func (*GracefulServer) RoutinesCount

func (gs *GracefulServer) RoutinesCount() int

RoutinesCount returns the number of currently running routines

func (*GracefulServer) Serve

func (gs *GracefulServer) Serve(listener net.Listener) error

Serve provides a graceful equivalent net/http.Server.Serve.

If listener is not an instance of *GracefulListener it will be wrapped to become one.

func (*GracefulServer) StartRoutine

func (gs *GracefulServer) StartRoutine()

StartRoutine increments the server's WaitGroup. Use this if a web request starts more goroutines and these goroutines are not guaranteed to finish before the request.

type ListenerMutateFunc

type ListenerMutateFunc func(net.Listener) (net.Listener, error)

type Options

type Options struct {
	Server       *http.Server
	StateHandler StateHandler
	Listener     net.Listener
}

Options used by NewWithOptions to provide parameters for a GracefulServer instance to be created.

type StateHandler

type StateHandler func(net.Conn, http.ConnState, http.ConnState)

StateHandler can be called by the server if the state of the connection changes. Notice that it passed previous state and the new state as parameters.

type TCPKeepAliveListener

type TCPKeepAliveListener struct {
	*net.TCPListener
}

TCPKeepAliveListener sets TCP keep-alive timeouts on accepted connections. It's used by ListenAndServe and ListenAndServeTLS so dead TCP connections (e.g. closing laptop mid-download) eventually go away.

direct lift from net/http/server.go

func (TCPKeepAliveListener) Accept

func (ln TCPKeepAliveListener) Accept() (c net.Conn, err error)

type TLSListener

type TLSListener struct {
	net.Listener
	// contains filtered or unexported fields
}

A listener implements a network listener (net.Listener) for TLS connections. direct lift from crypto/tls.go

func (*TLSListener) Accept

func (l *TLSListener) Accept() (c net.Conn, err error)

Accept waits for and returns the next incoming TLS connection. The returned connection c is a *tls.Conn.