README
¶
gograceful
Allows you to gracefully restart applications by spawning a new process and gracefully handing off the connections.
Overview
Go is great, but not being able to gracefully shutdown an application and any current connections is a bit of a pain, especially when you want to add in graceful shutdown (for restarts etc). By using this package, you are able to restart an application gracefully, launching a new process that takes over the current file descriptors, sends a shutdown to the original process that then finishes it's clients before shutting down. Any new requests will be handled by the new process. Upon receiving the correct shutdown call it will spawn a new process handing off the current socket file descriptors to the new process.
This did use a custom implementation of an HTTP server that could manage the connection state, but since
HTTP.Shutdown has been added in 1.8, I decided to integrate this.
For an example, see the cmd/example.go implementation.
Installation
With a healthy Go Language installed, simply run go get github.com/landonia/gograceful
Out of Box Example
The example will not run with go run as it will create a different tmp file that it executes.
You need to build the file using go build $GOPATH/src/github.com/landonia/gograceful/cmd/example.go and then run ./example.
To test the graceful restart you will have to find the process ID ps a | grep example and then
issue kill -SIGUSR2 {process_id}. To test that it fully works you can find the current server uuid
by going to http://localhost:8081/uuid and then set off a long running request using http://localhost:8081/delayed. Immediately after firing the request, issue the kill command from above. If you go to http://localhost:8081/uuid you will see a new uuid but the last delayed request will show the previous uuid.
Currently, the example only shows a HTTP server in operation, but I will soon be adding examples for TCP and WebSocket connections.
About
gograceful was written by Landon Wainwright | GitHub.
Follow me on Twitter @landotube! Although I don't really tweet much tbh.
Documentation
¶
Index ¶
- Constants
- func IsErrClosing(err error) bool
- func IsErrShutdown(err error) bool
- type Graceful
- func (gf *Graceful) Listen(nett, laddr string) (net.Listener, error)
- func (gf *Graceful) ListenTCP(nett string, laddr *net.TCPAddr) (*net.TCPListener, error)
- func (gf *Graceful) ListenUnix(nett string, laddr *net.UnixAddr) (*net.UnixListener, error)
- func (gf *Graceful) NewServer(server *http.Server) *Server
- func (gf *Graceful) Ready() error
- func (gf *Graceful) ServiceReady()
- func (gf *Graceful) SetServiceCount(count int) (err error)
- func (gf *Graceful) Wait() error
- type Server
- type WithConfiguration
Constants ¶
const ( SIGINT = syscall.SIGINT SIGQUIT = syscall.SIGQUIT SIGTERM = syscall.SIGTERM SIGUSR2 = syscall.SIGUSR2 )
Don't make the caller import syscall.
Variables ¶
This section is empty.
Functions ¶
func IsErrClosing ¶
IsErrClosing will test whether an error is equivalent to net.errClosing as returned by Accept during a graceful exit.
func IsErrShutdown ¶
IsErrShutdown will return true if the error is because of a shutdown
Types ¶
type Graceful ¶
type Graceful struct {
// contains filtered or unexported fields
}
Graceful will store the listeners that have been created so that they can be inherited on a restart
func New ¶
func New(withConfs ...WithConfiguration) (gf *Graceful, err error)
New will create a new Graceful wrapper. Note only one is expected per application
func (*Graceful) Listen ¶
Listen announces on the local network address laddr. The network net must be a stream-oriented network: "tcp", "tcp4", "tcp6", "unix" or "unixpacket". It returns an inherited net.Listener for the matching network and address, or creates a new one using net.Listen.
func (*Graceful) ListenTCP ¶
ListenTCP announces on the local network address laddr. The network net must be: "tcp", "tcp4" or "tcp6". It returns an inherited net.Listener for the matching network and address, or creates a new one using net.ListenTCP.
func (*Graceful) ListenUnix ¶
ListenUnix announces on the local network address laddr. The network net must be a: "unix" or "unixpacket". It returns an inherited net.Listener for the matching network and address, or creates a new one using net.ListenUnix.
func (*Graceful) NewServer ¶
NewServer will take a standard http.Server and wrap it to make it capable of being graceful
func (*Graceful) Ready ¶
Ready to signal that the current command has started and it is in a ready state. If another process has spawned this, it will send the final shutdown to that process (that should be blocking on Wait()) to shutdown.
func (*Graceful) ServiceReady ¶
func (gf *Graceful) ServiceReady()
ServiceReady should be called when one of the services are ready. When all the services have been registered as ready the Wait method will return, in turn sending a SIGINT to the parent process
func (*Graceful) SetServiceCount ¶
SetServiceCount allows you to specify the number of services that have to start before calling ready For example, if you have 3 listeners in the application that have to be started before the service is ready, then you can set the count. You can then call ready after initialising the service but the signal will not be sent until the number of calls matches the number of services.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server encapsulates a standard HTTP server that can be gracefully shutdown by allowing the connection to be inherited by the new process
func (*Server) ListenAndServe ¶
ListenAndServe will start the server and start serving the requests it will call ServiceReady when the server is started
func (*Server) RegisterOnShutdown ¶
RegisterOnShutdown registers a function to call on Shutdown. This can be used to gracefully shutdown connections that have undergone NPN/ALPN protocol upgrade or that have been hijacked. This function should start protocol-specific graceful shutdown, but should not wait for shutdown to complete.
type WithConfiguration ¶
WithConfiguration defines a function type to configure Graceful
func WithLogger ¶
func WithLogger(log golog.Logger) WithConfiguration
WithLogger will override the logger
func WithServiceCount ¶
func WithServiceCount(services int) WithConfiguration
WithServiceCount will configure Graceful with the number of services that will initialise before it is ready (see #Ready())
Source Files
Directories