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.
HTTP, HTTPS and FCGI
Manners supports three protocols: HTTP, HTTPS and FCGI. HTTP is illustrated above. For HTTPS, Manners can likewise act as a drop-in replacement for the standard library's http.ListenAndServeTLS function:
func main() {
handler := MyHTTPHandler()
certFile := MyCertificate()
keyFile := MyKeyFile()
manners.ListenAndServeTLS(":https", certFile, keyFile, handler)
}
In Manners, FCGI only operates via local a Unix socket connected to a co-hosted proxy, such as Apache or Nginx.
func main() {
handler := MyHTTPHandler()
manners.ListenAndServe("/var/run/goserver.sock", handler)
}
To use FCGI, the port string must specify the Unix socket and start with a slash or dot, as in the example above. In this case, Manners will use fcgi.Serve.
In each of the protocols, Manners drains down the connections cleanly when manners.Close() is called.
Handling signals
It's good to close down the server cleanly when OS signals are received. This is easy: just add
manners.CloseOnInterrupt()
before the ListenAndServe call. This kicks off a separate goroutine to wait for an OS signal, upon which it simply calls manners.Close() for you. Optionally, you can pass in a list of the particular signals you care about and you can find out which signal was received, if any, afterwards.
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:
manners.CloseOnInterrupt()
http.Handle("/hello", myHandler)
log.Fatal(manners.ListenAndServe(":8080", nil))
Index ¶
- func Close() bool
- func CloseOnInterrupt(signals ...os.Signal)
- 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
- func SetLogger(l *log.Logger)
- func SignalReceived() os.Signal
- type GracefulListener
- type GracefulServer
- func (s *GracefulServer) BlockingClose() bool
- func (s *GracefulServer) Close() bool
- func (s *GracefulServer) CloseOnInterrupt(signals ...os.Signal) *GracefulServer
- func (s *GracefulServer) FinishRoutine()
- func (gs *GracefulServer) GetFile() (*os.File, error)
- func (gs *GracefulServer) HijackListener(s *http.Server, config *tls.Config) (*GracefulServer, error)
- func (s *GracefulServer) ListenAndServe() error
- func (s *GracefulServer) ListenAndServeTLS(certFile, keyFile string) error
- func (s *GracefulServer) ListenAndServeTLSWithConfig(config *tls.Config) error
- func (s *GracefulServer) Serve(listener net.Listener) error
- func (s *GracefulServer) SignalReceived() os.Signal
- func (s *GracefulServer) StartRoutine()
- type Options
- type StateHandler
- type TCPKeepAliveListener
- type TLSListener
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 CloseOnInterrupt ¶
CloseOnInterrupt creates a go-routine that will call the Close() function when certain OS signals are received. If no signals are specified, the following are used: SIGINT, SIGTERM, SIGKILL, SIGQUIT, SIGHUP, SIGUSR1. This function must be called before ListenAndServe, ListenAndServeTLS, or Serve.
func ListenAndServe ¶
ListenAndServe provides a graceful version of the function provided by the net/http package. Call Close() to stop the server.
func ListenAndServeTLS ¶
ListenAndServeTLS provides a graceful version of the function provided by the net/http package. Call Close() to stop the server.
func NewTLSListener ¶
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 ¶
Serve provides a graceful version of the function provided by the net/http package. Call Close() to stop the server.
func SetLogger ¶
SetLogger changes the logger used for the startup and shutdown messages generated by Manners. By default, no log messages are emitted. To make Manners logging behave the same as per the standard log package, i.e. to stderr, use `SetLogger(log.New(os.Stderr, "", log.LstdFlags))`
func SignalReceived ¶
After a signal has cause the server to close, this method allows you to determine which signal had been received. If Close was called some other way, this method will return nil.
Note that, by convention, SIGUSR1 is often used to cause a server to close all its current connections cleanly, close its log files, and then restart. This facilitates log rotation. If you need this behaviour, you will need to provide a loop around the CloseOnInterrupt and ListenAndServe calls.
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) Close ¶
func (l *GracefulListener) Close() error
Close tells the wrapped listener to stop listening. It is idempotent.
type GracefulServer ¶
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 NewWithOptions ¶
func NewWithOptions(o Options) *GracefulServer
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 (s *GracefulServer) BlockingClose() bool
BlockingClose is similar to Close, except that it blocks until the last connection has been closed.
func (*GracefulServer) Close ¶
func (s *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) CloseOnInterrupt ¶
func (s *GracefulServer) CloseOnInterrupt(signals ...os.Signal) *GracefulServer
CloseOnInterrupt creates a go-routine that will call the Close() function when certain OS signals are received. If no signals are specified, the following are used: SIGINT, SIGTERM, SIGKILL, SIGQUIT, SIGHUP, SIGUSR1. This function must be called before ListenAndServe, ListenAndServeTLS, or Serve.
func (*GracefulServer) FinishRoutine ¶
func (s *GracefulServer) FinishRoutine()
FinishRoutine decrements the server's WaitGroup. Use this to complement StartRoutine().
func (*GracefulServer) HijackListener ¶
func (gs *GracefulServer) HijackListener(s *http.Server, config *tls.Config) (*GracefulServer, error)
func (*GracefulServer) ListenAndServe ¶
func (s *GracefulServer) ListenAndServe() error
ListenAndServe provides a graceful equivalent of net/http.Serve.ListenAndServe.
func (*GracefulServer) ListenAndServeTLS ¶
func (s *GracefulServer) ListenAndServeTLS(certFile, keyFile string) error
ListenAndServeTLS provides a graceful equivalent of net/http.Serve.ListenAndServeTLS.
func (*GracefulServer) ListenAndServeTLSWithConfig ¶
func (s *GracefulServer) ListenAndServeTLSWithConfig(config *tls.Config) error
ListenAndServeTLSWithConfig provides a graceful equivalent of net/http.Serve.ListenAndServeTLS using a bespoke TLS config.
func (*GracefulServer) Serve ¶
func (s *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) SignalReceived ¶
func (s *GracefulServer) SignalReceived() os.Signal
SignalReceived gets the signal that caused the server to close, if any. If Close() was called some other way, this method will return nil.
Note that, by convention, SIGUSR1 is often used to cause a server to close all its current connections cleanly, close its log files, and then restart. This facilitates log rotation. If you need this behaviour, you will need to provide a loop around both the CloseOnInterrupt and ListenAndServe calls.
func (*GracefulServer) StartRoutine ¶
func (s *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 Options ¶
type Options struct {
Server *http.Server
StateHandler StateHandler
Listener net.Listener
}
type StateHandler ¶
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
type TLSListener ¶
A listener implements a network listener (net.Listener) for TLS connections. direct lift from crypto/tls.go
Source Files
Directories