Skip to content
littleboss: supervisor construction kit
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE littleboss: ISC license Jun 8, 2018
README.md Add go syntax highlighting to readme Jun 11, 2018
littleboss.go littleboss: generalize fd extraction Mar 17, 2019
littleboss_test.go littleboss: test net.Listen is called only once Mar 17, 2019

README.md

littleboss: self-supervising Go binaries

A Go package, littleboss lets you turn your program into a a self-supervising binary. It starts itself as a child process, monitors its life cycle, reloads it if it exits, and can be instructed to replace it with a new binary.

The supervisor can open sockets for you and share them across reloads of your program, ensuring no connections are dropped.

You can install it with:

go get crawshaw.io/littleboss

Make a program use littleboss by modifying the main function:

func main() {
	lb := littleboss.New("service-name")
	lb.Run(func(ctx context.Context) {
		// main goes here, exit when <-ctx.Done()
	})
}

The service name is used to identify which program the supervisor will control.

Usage

By default the supervisor is bypassed and the program executes directly. A flag, -littleboss, is added to the binary. It can be used to start a supervised binary and manage it:

$ mybin &                     # binary runs directly, no child process
$ mybin -littleboss=start &   # supervisor is created
$ mybin2 -littleboss=reload   # child is replaced by new mybin2 process
$ mybin -littleboss=stop      # supervisor and child are shut down

Configuration

Supervisor options are baked into the binary. The littleboss struct type contains fields that can be set before calling the Run method to configure the supervisor. Options include reloading the previous binary if a reload fails, controlling how long an exiting program has to turn down its connections, and specifying exactly what flags control and are passed by littleboss.

An HTTP server example

func main() {
	lb := littleboss.New("myblog")
	flagHTTPS := lb.Listener("https", "tcp", ":443", "address")
	lb.Run(func(ctx context.Context) {
		httpMain(ctx, flagHTTPS.Listener())
	})
}

func httpMain(ctx context.Context, ln net.Listener) {
	srv := &http.Server{
		ReadTimeout:  10 * time.Second,
		WriteTimeout: 10 * time.Second,
		IdleTimeout:  60 * time.Second,
		Handler:      blogHandler,
	}
	go func() {
		if err := srv.ServeTLS(ln, "certfile", "keyfile"); err != nil {
			if err == http.ErrServerClosed {
				return
			}
			log.Fatal(err)
		}
	}()

	<-ctx.Done()
	srv.Shutdown(ctx)
}
You can’t perform that action at this time.