graceful

package
v0.0.0-...-4daffe4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 5, 2014 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package graceful implements graceful shutdown for HTTP servers by closing idle connections after receiving a signal. By default, this package listens for interrupts (i.e., SIGINT), but when it detects that it is running under Einhorn it will additionally listen for SIGUSR2 as well, giving your application automatic support for graceful upgrades.

It's worth mentioning explicitly that this package is a hack to shim graceful shutdown behavior into the net/http package provided in Go 1.2. It was written by carefully reading the sequence of function calls net/http happened to use as of this writing and finding enough surface area with which to add appropriate behavior. There's a very good chance that this package will cease to work in future versions of Go, but with any luck the standard library will add support of its own by then (https://code.google.com/p/go/issues/detail?id=4674).

If you're interested in figuring out how this package works, we suggest you read the documentation for WrapConn() and net.go.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddSignal

func AddSignal(sig ...os.Signal)

AddSignal adds the given signal to the set of signals that trigger a graceful shutdown. Note that for convenience the default interrupt (SIGINT) handler is installed at package load time, and unless you call ResetSignals() will be listened for in addition to any signals you provide by calling this function.

func ListenAndServe

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

ListenAndServe behaves exactly like the net/http function of the same name.

func ListenAndServeTLS

func ListenAndServeTLS(addr, certfile, keyfile string, handler http.Handler) error

ListenAndServeTLS behaves exactly like the net/http function of the same name.

func Middleware

func Middleware(h http.Handler) http.Handler

Middleware adds graceful shutdown capabilities to the given handler. When a graceful shutdown is in progress, this middleware intercepts responses to add a "Connection: close" header to politely inform the client that we are about to go away.

This package creates a shim http.ResponseWriter that it passes to subsequent handlers. Unfortunately, there's a great many optional interfaces that this http.ResponseWriter might implement (e.g., http.CloseNotifier, http.Flusher, and http.Hijacker), and in order to perfectly proxy all of these options we'd be left with some kind of awful powerset of ResponseWriters, and that's not even counting all the other custom interfaces you might be expecting. Instead of doing that, we have implemented two kinds of proxies: one that contains no additional methods (i.e., exactly corresponding to the http.ResponseWriter interface), and one that supports all three of http.CloseNotifier, http.Flusher, and http.Hijacker. If you find that this is not enough, the original http.ResponseWriter can be retrieved by calling Unwrap() on the proxy object.

This middleware is automatically applied to every http.Handler passed to this package, and most users will not need to call this function directly. It is exported primarily for documentation purposes and in the off chance that someone really wants more control over their http.Server than we currently provide.

func PostHook

func PostHook(f func())

PostHook registers a function to be called after all of this package's normal shutdown actions. All listeners will be called in the order they were added, from a single goroutine, and are guaranteed to be called after all listening connections have been closed, but before Wait() returns.

If you've Hijack()ed any connections that must be gracefully shut down in some other way (since this library disowns all hijacked connections), it's reasonable to use a PostHook() to signal and wait for them.

func PreHook

func PreHook(f func())

PreHook registers a function to be called before any of this package's normal shutdown actions. All listeners will be called in the order they were added, from a single goroutine.

func ResetSignals

func ResetSignals()

ResetSignals resets the list of signals that trigger a graceful shutdown. Useful if, for instance, you don't want to use the default interrupt (SIGINT) handler. Since we necessarily install the SIGINT handler before you have a chance to call ResetSignals(), there will be a brief window during which the set of signals this package listens for will not be as you intend. Therefore, if you intend on using this function, we encourage you to call it as soon as possible.

func Serve

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

Serve behaves exactly like the net/http function of the same name.

func Shutdown

func Shutdown()

Shutdown manually triggers a shutdown from your application. Like Wait(), blocks until all connections have gracefully shut down.

func Wait

func Wait()

Wait for all connections to gracefully shut down. This is commonly called at the bottom of the main() function to prevent the program from exiting prematurely.

func WrapConn

func WrapConn(c net.Conn) net.Conn

WrapConn wraps an arbitrary connection for use with graceful shutdowns. The graceful shutdown process will ensure that this connection is closed before terminating the process.

In order to use this function, you must call SetReadDeadline() before the call to Read() you might make to read a new request off the wire. The connection is eligible for abrupt closing at any point between when the call to SetReadDeadline() returns and when the call to Read returns with new data. It does not matter what deadline is given to SetReadDeadline()--the default HTTP server provided by this package sets a deadline far into the future when a deadline is not provided, for instance.

Unfortunately, this means that it's difficult to use SetReadDeadline() in a great many perfectly reasonable circumstances, such as to extend a deadline after more data has been read, without the connection being eligible for "graceful" termination at an undesirable time. Since this package was written explicitly to target net/http, which does not as of this writing do any of this, fixing the semantics here does not seem especially urgent.

As an optimization for net/http over TCP, if the input connection supports the ReadFrom() function, the returned connection will as well. This allows the net package to use sendfile(2) on certain platforms in certain circumstances.

func WrapListener

func WrapListener(l net.Listener) net.Listener

WrapListener wraps an arbitrary net.Listener for use with graceful shutdowns. All net.Conn's Accept()ed by this listener will be auto-wrapped as if WrapConn() were called on them.

Types

type Server

type Server http.Server

Type Server is exactly the same as an http.Server, but provides more graceful implementations of its methods.

func (*Server) ListenAndServe

func (srv *Server) ListenAndServe() error

func (*Server) ListenAndServeTLS

func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error

func (*Server) Serve

func (srv *Server) Serve(l net.Listener) (err error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL