grace

README

grace

Package grace provides a library that makes it easy to build socket based servers that can be gracefully terminated & restarted (that is, without dropping any connections).

It provides a convenient API for HTTP servers including support for TLS, especially if you need to listen on multiple ports (for example a secondary internal only admin server). Additionally it is implemented using the same API as systemd providing socket activation compatibility to also provide lazy activation of the server.

Usage

Demo HTTP Server with graceful termination and restart: https://github.com/facebookgo/grace/blob/master/gracedemo/demo.go

1. Install the demo application

    go get github.com/facebookgo/grace/gracedemo
   

2. Start it in the first terminal

    gracedemo
   

   This will output something like:

    2013/03/25 19:07:33 Serving [::]:48567, [::]:48568, [::]:48569 with pid 14642.
   

3. In a second terminal start a slow HTTP request

    curl 'http://localhost:48567/sleep/?duration=20s'
   

4. In a third terminal trigger a graceful server restart (using the pid from your output):

    kill -USR2 14642
   

5. Trigger another shorter request that finishes before the earlier request:

    curl 'http://localhost:48567/sleep/?duration=0s'
   

If done quickly enough, this shows the second quick request will be served by the new process (as indicated by the PID) while the slow first request will be served by the first server. It shows how the active connection was gracefully served before the server was shutdown. It is also showing that at one point both the new as well as the old server was running at the same time.

Documentation

http.Server graceful termination and restart: http://godoc.org/github.com/facebookgo/grace/gracehttp

net.Listener graceful termination and restart: http://godoc.org/github.com/facebookgo/grace

Documentation

Overview

Package grace allows for gracefully waiting for a listener to finish serving it's active requests.

Index

• Variables
• func CloseParent() error
• func Restart(listeners []Listener) (err error)
• func Wait(listeners []Listener) (err error)
• type Listener
  • func Inherit() (listeners []Listener, err error)
  • func NewListener(l Listener) Listener
• type Process
  • func (p *Process) CloseParent() error
  • func (p *Process) Inherit() (listeners []Listener, err error)
  • func (p *Process) Restart(listeners []Listener) (err error)
  • func (p *Process) Wait(listeners []Listener) error

Variables

var (
	// ErrNotInheriting is returned by Inherits() when we're not inheriting any fds.
	ErrNotInheriting = errors.New("grace: no inherited listeners")

	// ErrAlreadyClosed is returned by Listener.Accept() when Close is in progress.
	ErrAlreadyClosed = errors.New("grace: already closed")
)

Functions

func CloseParent

func CloseParent() error

CloseParent starts the close process in the parent. This does not wait for the parent to close and simply sends it the TERM signal.

func Restart

func Restart(listeners []Listener) (err error)

Restart the process passing the given listeners to the new process.

func Wait

func Wait(listeners []Listener) (err error)

Wait for signals to gracefully terminate or restart the process.

Types

type Listener

type Listener interface {
	net.Listener

	// Will return the underlying file representing this Listener.
	File() (f *os.File, err error)
}

A Listener providing a graceful Close process and can be sent across processes using the underlying File descriptor.

func Inherit

func Inherit() (listeners []Listener, err error)

Inherit listeners from the parent process.

func NewListener

func NewListener(l Listener) Listener

NewListener wraps an existing File listener to provide a graceful Close() process.

type Process

type Process struct {
	// TermTimeout if set will determine how long we'll wait for listeners when
	// we're sent the TERM signal.
	TermTimeout time.Duration
}

Process configures the restart process.

func (*Process) CloseParent

func (p *Process) CloseParent() error

CloseParent starts the close process in the parent. This does not wait for the parent to close and simply sends it the TERM signal.

func (*Process) Inherit

func (p *Process) Inherit() (listeners []Listener, err error)

Inherit listeners from the parent process.

func (*Process) Restart

func (p *Process) Restart(listeners []Listener) (err error)

Restart the process passing the given listeners to the new process.

func (*Process) Wait

func (p *Process) Wait(listeners []Listener) error

Wait for signals to gracefully terminate or restart the process.