Documentation ¶
Overview ¶
Package littleboss creates self-supervising Go binaries.
A self-supervising binary starts itself as a child process. The parent process becomes a supervisor that is responsible for monitoring, managing I/O, restarting, and reloading the child.
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() }) }
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.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ListenerFlag ¶
type ListenerFlag struct {
// contains filtered or unexported fields
}
A ListenerFlag is a flag whose value is used as a net.Listener or net.PacketConn.
An empty flag value ("") means no listener is created. For a listener on a random port, use ":0".
func (*ListenerFlag) Listener ¶
func (lnf *ListenerFlag) Listener() net.Listener
func (*ListenerFlag) Network ¶
func (lnf *ListenerFlag) Network() string
func (*ListenerFlag) PacketConn ¶
func (lnf *ListenerFlag) PacketConn() net.PacketConn
func (*ListenerFlag) Set ¶
func (lnf *ListenerFlag) Set(value string) error
func (*ListenerFlag) String ¶
func (lnf *ListenerFlag) String() string
type Littleboss ¶
type Littleboss struct { FlagSet *flag.FlagSet // used for passing flags to child, default flag.CommandLine Logf func(format string, args ...interface{}) // defaults to stderr SupervisorInit func() // executed by supervisor on Run Persist bool // if program exits, restart it FallbackOnFailure bool // if program exits badly, use previous version LameduckTimeout time.Duration // time to wait before forcing exit // contains filtered or unexported fields }
func New ¶
func New(serviceName string) *Littleboss
func (*Littleboss) Command ¶
func (lb *Littleboss) Command(modeFlagName string, mode *string)
Command gives littleboss a custom command mode flag name and value.
By default littleboss creates a flag named -littleboss when Run is called, and sets its default value to "bypass". If the FlagSet is going to be processed by a non-standard flag package or the littleboss command mode is not passed as a flag at all, then this Command method can be used instead to avoid the flag creation.
This makes it possible for a program to invoke flag parsing itself, after calling New, Command, any calls to Listener, but before the call to Run.
For example:
lb := littleboss.New("myservice") lb.Command("-mylb", pflag.String("mylb", "start", "lb command mode")) pflag.CommandLine.AddGoFlagSet(flag.CommandLine) pflag.Parse() lb.Run(...)
NOTE: All the flags passed to the child process are extracted from Littleboss.FlagSet. Make sure any flags defined by external flag packages have their value in the FlagSet.
func (*Littleboss) Listener ¶
func (lb *Littleboss) Listener(flagName, network, value, usage string) *ListenerFlag
func (*Littleboss) Run ¶
func (lb *Littleboss) Run(mainFn func(ctx context.Context))
Run starts the little boss, with mainFn as the entry point to the service. Run does not return.