app

Documentation

Overview

Package app provides a process bootstrapping framework.

Index

• Variables
• type App
  • func (a *App) Run(services ...Service) (int, error)
• type Config
• type ConfigLoader
• type FlagSetter
• type Service

Variables

var ErrFlagNameConflict = errors.New("a flag with the given name was already registered")

ErrFlagNameConflict is returned by a FlagSetter when the App itself or another service has registered the given name value.

Types

type App

type App struct{}

An App encapsulates a binary's entire process.

func (*App) Run

func (a *App) Run(services ...Service) (int, error)

Run runs the supplied services until one errors or shutdown signal is provided.

type Config

type Config interface {
	// Validate returning an error signifies the service cannot start with the
	// configuration in the present state
	Validate() error
}

Config describes startup-configuration values of a service.

type ConfigLoader

type ConfigLoader interface {
	// Default is expected to return a Config. It may or may not validate as-is.
	Default() Config

	// EnvLoad mutates config based on the provided map representing the
	// current process environment. Any returned error will be logged with the
	// App logger and the process will be terminated with a non-zero exit code.
	EnvLoad(config Config, env map[string]string) error

	// FlagSet registers command-line flags to be mutated when arguments are
	// parsed.
	FlagSetup(config Config, flagSetter FlagSetter) error
}

ConfigLoader provides a structure way a Config pointer can be dispensed and have values loaded in layers - first from a default, then a JSON file, then from the environment, and finally from the process's command-line arguments.

type FlagSetter

type FlagSetter interface {
	BoolVar(p *bool, name string, value bool, usage string) error
	DurationVar(p *time.Duration, name string, value time.Duration, usage string) error
	Float64Var(p *float64, name string, value float64, usage string) error
	Int64Var(p *int64, name string, value int64, usage string) error
	IntVar(p *int, name string, value int, usage string) error
	StringVar(p *string, name string, value string, usage string) error
	Uint64Var(p *uint64, name string, value uint64, usage string) error
	UintVar(p *uint, name string, value uint, usage string) error
	Var(value flag.Value, name string, usage string) error
}

A FlagSetter allows callers to specify command line flags and set pointers to values that should be mutated when the App parses command line arguments.

type Service

type Service interface {
	// ConfigLoader provides the App with the means to load a Config for the
	// service.
	ConfigLoader() ConfigLoader

	// Run starts the service with the config calculated by ConfigLoader.
	//
	// ctx is the App-level runtime context. The service is expected to stop in
	// a timely fashion when ctx is canceled.
	//
	// logger is a guaranteed-initialized Logger instance.
	//
	// instanceID corresponds to a 0-based incrementing count of instances
	// based on the result of the service's Instances method. This provides
	// a reference point a worker can use to identify itself and react to (e.g.
	// incrementing port numbers).
	//
	// Returning without an error will cause the App process to exit with
	// a zero exit code; returning with an error will cause a non-zero exit.
	Run(ctx context.Context, config Config, logger *logging.Logger, instanceID int) error

	// Instances returns the number of times Run should be invoked in separate
	// goroutines by the App. Returning a value < 0 is a terminal error for
	// the App.
	Instances(config Config) int
}

A Service encapsulates one long-lived Routine