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()
  server := manners.NewServer()
  server.ListenAndServe(":7000", handler)
}

Then, when you want to shut the server down:

server.Shutdown <- true

(Note that this does not block until all the requests are finished. Rather, the call to server.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.

Compatability

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

Installation

go get github.com/braintree/manners

Documentation

Index

• type GracefulListener
  • func NewListener(l net.Listener, s *GracefulServer) *GracefulListener
  • func (l *GracefulListener) Accept() (net.Conn, error)
  • func (l *GracefulListener) Close() error
• type GracefulServer
  • func NewServer() *GracefulServer
  • func (s *GracefulServer) FinishRoutine()
  • func (s *GracefulServer) ListenAndServe(addr string, handler http.Handler) error
  • func (s *GracefulServer) Serve(listener net.Listener, handler http.Handler) error
  • func (s *GracefulServer) StartRoutine()

Types

type GracefulListener

type GracefulListener struct {
	net.Listener
	// 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, s *GracefulServer) *GracefulListener

func (*GracefulListener) Accept

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

func (*GracefulListener) Close

func (l *GracefulListener) Close() error

type GracefulServer

type GracefulServer struct {
	Shutdown chan bool

	InnerServer 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.

func NewServer

func NewServer() *GracefulServer

Creates a new GracefulServer. The server will begin shutting down when a value is passed to the Shutdown channel.

func (*GracefulServer) FinishRoutine

func (s *GracefulServer) FinishRoutine()

Decrement the server's WaitGroup. Used this to complement StartRoutine().

func (*GracefulServer) ListenAndServe

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

A helper function that emulates the functionality of http.ListenAndServe.

func (*GracefulServer) Serve

func (s *GracefulServer) Serve(listener net.Listener, handler http.Handler) error

Similar to http.Serve. The listener passed must wrap a GracefulListener.

func (*GracefulServer) StartRoutine

func (s *GracefulServer) 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.