goagain

README

goagain

Zero-downtime restarts in Go

The goagain package provides primitives for bringing zero-downtime restarts to Go applications that accept connections from a net.TCPListener or net.UnixListener.

Have a look at the examples because it isn't just a matter of importing the library and everything working. Your main function will have to accomodate the goagain protocols and your process will have to have some definition (however contrived you like) of a graceful shutdown process.

Installation

go get github.com/rcrowley/goagain

Usage

Send SIGUSR2 to a process using goagain and it will restart without downtime.

example/single/main.go: The Single strategy (named because it calls execve(2) once) operates similarly to Nginx and Unicorn. The parent forks a child, the child execs, and then the child kills the parent. This is easy to understand but doesn't play nicely with Upstart and similar direct-supervision init(8) daemons. It should play nicely with systemd.

example/double/main.go: The Double strategy (named because it calls execve(2) twice) is experimental so proceed with caution. The parent forks a child, the child execs, the child signals the parent, the parent execs, and finally the parent kills the child. This is regrettably much more complicated but plays nicely with Upstart and similar direct-supervision init(8) daemons.

Documentation

Overview

Zero-downtime restarts in Go.

Index

• Constants
• Variables
• func AwaitSignals(l net.Listener) (err error)
• func Exec(l net.Listener) error
• func ForkExec(l net.Listener) error
• func GetEnvs() (l net.Listener, ppid int, err error)
• func IsErrClosing(err error) bool
• func Kill() error
• func KillParent(ppid int) error
• func Listener() (l net.Listener, err error)
• func Wait(l net.Listener) (syscall.Signal, error)

Constants

const (
	// The Single-exec strategy: parent forks child to exec with an inherited
	// net.Listener; child kills parent and becomes a child of init(8).
	Single strategy = iota

	// The Double-exec strategy: parent forks child to exec (first) with an
	// inherited net.Listener; child signals parent to exec (second); parent
	// kills child.
	Double
)

const (
	SIGINT  = syscall.SIGINT
	SIGQUIT = syscall.SIGQUIT
	SIGTERM = syscall.SIGTERM
	SIGUSR2 = syscall.SIGUSR2
)

Don't make the caller import syscall.

Variables

var (
	// OnSIGHUP is the function called when the server receives a SIGHUP
	// signal. The normal use case for SIGHUP is to reload the
	// configuration.
	OnSIGHUP func(l net.Listener) error

	// OnSIGUSR1 is the function called when the server receives a
	// SIGUSR1 signal. The normal use case for SIGUSR1 is to repon the
	// log files.
	OnSIGUSR1 func(l net.Listener) error

	// The strategy to use; Single by default.
	Strategy strategy = Single
)

Functions

func AwaitSignals

func AwaitSignals(l net.Listener) (err error)

Block this goroutine awaiting signals. Signals are handled as they are by Nginx and Unicorn: <http://unicorn.bogomips.org/SIGNALS.html>.

func Exec

func Exec(l net.Listener) error

Re-exec this same image without dropping the net.Listener.

func ForkExec

func ForkExec(l net.Listener) error

Fork and exec this same image without dropping the net.Listener.

func GetEnvs

func GetEnvs() (l net.Listener, ppid int, err error)

Convert and validate the GOAGAIN_FD, GOAGAIN_NAME, and GOAGAIN_PPID environment variables. If all three are present and in order, this is a child process that may pick up where the parent left off.

func IsErrClosing

func IsErrClosing(err error) bool

Test whether an error is equivalent to net.errClosing as returned by Accept during a graceful exit.

func Kill

func Kill() error

Kill process specified in the environment with the signal specified in the environment; default to SIGQUIT.

func KillParent

func KillParent(ppid int) error

Send SIGQUIT to the given ppid in order to complete the handoff to the child process.

func Listener

func Listener() (l net.Listener, err error)

Reconstruct a net.Listener from a file descriptior and name specified in the environment. Deal with Go's insistence on dup(2)ing file descriptors.

func Wait

func Wait(l net.Listener) (syscall.Signal, error)

Block this goroutine awaiting signals. Signals are handled as they are by Nginx and Unicorn: <http://unicorn.bogomips.org/SIGNALS.html>.