starter

README

server-starter

Yet Another Go port of start_server utility (a.k.a. Server::Starter), based on lestrrat-go/server-starter.

DESCRIPTION

note: this description is almost entirely taken from the original Server::Starter module

The start_server utility is a superdaemon for hot-deploying server programs.

It is often a pain to write a server program that supports graceful restarts, with no resource leaks. Server::Starter solves the problem by splitting the task into two: start_server works as a superdaemon that binds to zero or more TCP ports or unix sockets, and repeatedly spawns the server program that actually handles the necessary tasks (for example, responding to incoming connections). The spawned server programs under start_server call accept(2) and handle the requests.

To gracefully restart the server program, send SIGHUP to the superdaemon. The superdaemon spawns a new server program, and if (and only if) it starts up successfully, sends SIGTERM to the old server program.

By using start_server it is much easier to write a hot-deployable server. Following are the only requirements a server program to be run under start_server should conform to:

• receive file descriptors to listen to through an environment variable - perform a graceful shutdown when receiving SIGTERM

Many PSGI servers support this. If you want your Go program to support it, you can look under the listener directory for an implementation that also fills the net.Listener interface.

INSTALLATION

go install github.com/shogo82148/server-starter/cmd/start_server@latest

Documentation

Index

• Constants
• type Starter
  • func ParseArgs(args []string) (*Starter, error)
  • func (s *Starter) Close() error
  • func (s *Starter) Listeners() []net.Listener
  • func (s *Starter) PacketConns() []net.PacketConn
  • func (s *Starter) Reload() error
  • func (s *Starter) Run() error
  • func (s *Starter) Shutdown(ctx context.Context) error

Constants

const GenerationEnvName = "SERVER_STARTER_GENERATION"

GenerationEnvName is the environment name for the generation number.

const PortEnvName = "SERVER_STARTER_PORT"

PortEnvName is the environment name for server_starter configures.

Types

type Starter

type Starter struct {
	Command string
	Args    []string

	// Ports to bind to (addr:port or port, so it's a string)
	Ports []string

	// Paths at where to listen using unix socket.
	Paths []string

	Interval time.Duration

	// Signal to send when HUP is received
	SignalOnHUP os.Signal

	// Signal to send when TERM is received
	SignalOnTERM os.Signal

	// KillOlddeplay is time to suspend to send a signal to the old worker.
	KillOldDelay time.Duration

	// if set, writes the status of the server process(es) to the file
	StatusFile string

	// if set, writes the process id of the start_server process to the file
	PidFile string

	// working directory, start_server do chdir to before exec (optional)
	Dir string

	// enables automatic restart by time.
	EnableAutoRestart bool

	// automatic restart interval (default 360). It is used with EnableAutoRestart option.
	AutoRestartInterval time.Duration

	// directory that contains environment variables to the server processes.
	EnvDir string

	// prints the version number
	Version bool

	// prints the help message.
	Help bool

	// daemonize the server. (UNIMPLEMENTED)
	Daemonize bool

	// if set, redirects STDOUT and STDERR to given file or command
	LogFile string

	// this is a wrapper command that reads the pid of the start_server process from --pid-file,
	// sends SIGHUP to the process and waits until the server(s) of the older generation(s) die by monitoring the contents of the --status-file
	Restart bool

	// this is a wrapper command that reads the pid of the start_server process from --pid-file, sends SIGTERM to the process.
	Stop bool
	// contains filtered or unexported fields
}

Starter is an implement of Server::Starter.

func ParseArgs

func ParseArgs(args []string) (*Starter, error)

ParseArgs parses command line arguments, and return configured Starter.

func (*Starter) Close

func (s *Starter) Close() error

Close terminates all workers immediately.

func (*Starter) Listeners

func (s *Starter) Listeners() []net.Listener

Listeners returns the listeners.

func (*Starter) PacketConns

func (s *Starter) PacketConns() []net.PacketConn

PacketConns returns the PacketConns.

func (*Starter) Reload

func (s *Starter) Reload() error

Reload starts a new worker and stop the current worker.

func (*Starter) Run

func (s *Starter) Run() error

Run starts the specified command.

func (*Starter) Shutdown

func (s *Starter) Shutdown(ctx context.Context) error

Shutdown terminates all workers.