README
¶
Documentation
¶
Index ¶
- Variables
- func ContextWithHealth(ctx context.Context, health *Health) context.Context
- type Container
- type ContainerBuilder
- type Finalizer
- type FinalizerFunc
- type Health
- func (h *Health) Get(key interface{}) (*HealthComponentStatus, bool)
- func (h *Health) GetAll(keys ...interface{}) ([]*HealthComponentStatus, error)
- func (h *Health) Healthy() bool
- func (h *Health) Register(key interface{}) (*HealthComponentStatus, error)
- func (h *Health) Subscribe() (<-chan struct{}, func())
- type HealthComponentStatus
- type Initializer
- type InitializerFunc
- type Injecter
- type InjecterFunc
- type LogFields
- type Logger
- type MachineConfigFunc
- type Meta
- func (m *Meta) Finalize(ctx context.Context) error
- func (m *Meta) Init(ctx context.Context) (err error)
- func (m *Meta) Metadata() map[string]interface{}
- func (m *Meta) Name() string
- func (m *Meta) Run(ctx context.Context) error
- func (m *Meta) Stop(ctx context.Context) error
- func (m *Meta) Wrapped() interface{}
- type MetaConfigFunc
- func WithEarlyExit(allowed bool) MetaConfigFunc
- func WithMetaContext(f func(ctx context.Context) context.Context) MetaConfigFunc
- func WithMetaFinalizeTimeout(timeout time.Duration) MetaConfigFunc
- func WithMetaHealth(health *Health) MetaConfigFunc
- func WithMetaHealthKey(healthKeys ...interface{}) MetaConfigFunc
- func WithMetaInitTimeout(timeout time.Duration) MetaConfigFunc
- func WithMetaLogger(logger Logger) MetaConfigFunc
- func WithMetaName(name string) MetaConfigFunc
- func WithMetaPriority(priority int) MetaConfigFunc
- func WithMetaShutdownTimeout(timeout time.Duration) MetaConfigFunc
- func WithMetaStartupTimeout(timeout time.Duration) MetaConfigFunc
- func WithMetaStopTimeout(timeout time.Duration) MetaConfigFunc
- func WithMetadata(metadata map[string]interface{}) MetaConfigFunc
- type Runner
- type RunnerFunc
- type State
- type Stopper
Constants ¶
This section is empty.
Variables ¶
var ErrHealthCheckCanceled = errors.New("health check canceled")
ErrHealthCheckCanceled occurs when a process's initial health check is cancelled due to another process exiting in a non-healthy way.
var ErrHealthComponentAlreadyRegistered = errors.New("health component already registered")
ErrHealthComponentAlreadyRegistered occurs when a health component is registered with the name of previously registered health component.
var ErrShutdownTimeout = errors.New("process refusing to shut down; abandoning goroutine")
ErrShutdownTimeout occurs when a process does not return from Run after a call to Stop and a context cancellation within the configured timeout.
var ErrStartupTimeout = errors.New("process did not become healthy within timeout")
ErrStartupTimeout occurs when the health items associated with a process do not report healthy within the configured timeout.
var ErrUnexpectedReturn = errors.New("unexpected return from process")
ErrUnexpectedReturn occurs when a process returns from Run before the process runner enters shutdown. This error does not occur if the process is marked with early exit.
Functions ¶
Types ¶
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container is an immutable container used to hold registered processes. A container instance is constructed from a mutable container builder.
func (*Container) MetaForPriority ¶
MetaForPriority returns a new slice of meta values registered to the given priority.
func (*Container) Priorities ¶
Priorities returns a new slice of unique priorities to which a meta value is registered.
type ContainerBuilder ¶
type ContainerBuilder struct {
// contains filtered or unexported fields
}
ContainerBuilder is a mutable container used to register processes at application boot. The container builder can be frozen into an immutable container.
func NewContainerBuilder ¶
func NewContainerBuilder() *ContainerBuilder
NewContainerBuilder creates an empty container builder.
func (*ContainerBuilder) Build ¶
func (b *ContainerBuilder) Build(configs ...MetaConfigFunc) *Container
Build creates a frozen and immutable version of the container containing all of the processes registered to the container builder thus far.
func (*ContainerBuilder) RegisterInitializer ¶
func (b *ContainerBuilder) RegisterInitializer(wrapped interface{}, configs ...MetaConfigFunc)
RegisterInitializer registers an initializer with the given configs.
func (*ContainerBuilder) RegisterProcess ¶
func (b *ContainerBuilder) RegisterProcess(wrapped interface{}, configs ...MetaConfigFunc)
RegisterProcess registers a process with the given configs.
type Finalizer ¶
type Finalizer interface {
// Finalize is the hook invoked directly before application exit.
Finalize(ctx context.Context) error
}
Finalizer wraps behavior that happens directly before application exit.
type FinalizerFunc ¶
FinalizerFunc is a function conforming to the Finalizer interface.
type Health ¶
type Health struct {
// contains filtered or unexported fields
}
Health is an aggregate container reporting the current health status of individual application components.
func HealthFromContext ¶ added in v2.0.1
func (*Health) Get ¶
func (h *Health) Get(key interface{}) (*HealthComponentStatus, bool)
Get returns the component status value registered to the given key.
func (*Health) GetAll ¶
func (h *Health) GetAll(keys ...interface{}) ([]*HealthComponentStatus, error)
GetAll returns the component status values registered to the given keys.
func (*Health) Register ¶
func (h *Health) Register(key interface{}) (*HealthComponentStatus, error)
Register creates and returns a new component status value for the given key. It an error to register the same key twice.
func (*Health) Subscribe ¶
func (h *Health) Subscribe() (<-chan struct{}, func())
Subscribe returns a notification channel that receives a value whenever the set of components change, or the status of a component changes. This method also returns a cancellation function that should be called once the user wishes to unsubscribe.
type HealthComponentStatus ¶
type HealthComponentStatus struct {
// contains filtered or unexported fields
}
HealthComponentStatus manages the current status of an application component.
func (*HealthComponentStatus) Healthy ¶
func (s *HealthComponentStatus) Healthy() bool
Healthy returns true if the component is currently healthy.
func (*HealthComponentStatus) Update ¶
func (s *HealthComponentStatus) Update(healthy bool)
Update sets the current health status of the application component.
type Initializer ¶
type Initializer interface {
// Init is the hook invoked on application startup.
Init(ctx context.Context) error
}
Initializer wraps behavior that happens on application startup.
type InitializerFunc ¶
InitializerFunc is a function conforming to the Initializer interface.
type Injecter ¶
type Injecter interface {
// Inject populates the fields of the wrapped value in the given meta value.
Inject(ctx context.Context, meta *Meta) error
}
Injecter tags a struct as being an expected target of dependency injection.
type InjecterFunc ¶
InjecterFunc is a function conforming to the Injecter interface.
type Logger ¶
type Logger interface {
WithFields(LogFields) Logger
Info(string, ...interface{})
Warning(string, ...interface{})
Error(string, ...interface{})
}
var NilLogger Logger = nilLogger{}
type MachineConfigFunc ¶
type MachineConfigFunc func(*machineBuilder)
func WithHealth ¶
func WithHealth(health *Health) MachineConfigFunc
WithHealth configures a machine builder instance to use the given health instance.
func WithInjecter ¶
func WithInjecter(injectHook Injecter) MachineConfigFunc
WithInjecter configures a machine builder instance to use the given inject hook.
type Meta ¶
type Meta struct {
// contains filtered or unexported fields
}
Meta is a wrapper around a process value. This wrapper ensures that the configured receiver's methods are only called once and not called from an invalid state (e.g. Run called before Init or after a failed Init).
func (*Meta) Finalize ¶
Finalize invokes the wrapped value's Finalize method.
A timeout error will be returned if the invocation does not unblock within the configured finalize timeout.
This method will no-op if the meta instance was not initialized.
func (*Meta) Init ¶
Init invokes the wrapped value's Init method.
A timeout error will be returned if the invocation does not unblock within the configured init timeout.
func (*Meta) Name ¶
Name returns the process's configured name or `<unnamed {type}>` if one was not supplied.
func (*Meta) Run ¶
Run invokes the wrapped value's Run method.
A timeout error will be returned if the associated health instance does not report healthy within the configured startup timeout, or if Run method does not unblock after the meta instance's Stop method is called within the configured shutdown timeout.
A canned error will also be returned if the underlying Run method unblocks with a nil value without Stop being called and the meta was not configured with the silent exit flag.
This method will no-op if the meta instance was not initialized.
type MetaConfigFunc ¶
type MetaConfigFunc func(meta *metaOptions)
func WithEarlyExit ¶
func WithEarlyExit(allowed bool) MetaConfigFunc
WithEarlyExit sets the flag that determines if the process is allowed to return from the Run method (with a nil error value) before the Stop method is called. The default behavior is to treat exiting processes as erroneous.
func WithMetaContext ¶
func WithMetaContext(f func(ctx context.Context) context.Context) MetaConfigFunc
WithMetaContext configures a Meta instance to use the context returned by the given function when invoking the wrapped value's underlying Init, Run, Stop, or Finalize methods.
func WithMetaFinalizeTimeout ¶
func WithMetaFinalizeTimeout(timeout time.Duration) MetaConfigFunc
WithMetaFinalizeTimeout configures a Meta instance with the given timeout for the invocation of the wrapped value's Finalize method.
func WithMetaHealth ¶
func WithMetaHealth(health *Health) MetaConfigFunc
WithMetaHealth configures a Meta instance to use the given health instance.
func WithMetaHealthKey ¶
func WithMetaHealthKey(healthKeys ...interface{}) MetaConfigFunc
WithMetaHealthKey configures a Meta instance to use the given keys to search for registered health component belonging to this process.
func WithMetaInitTimeout ¶
func WithMetaInitTimeout(timeout time.Duration) MetaConfigFunc
WithMetaInitTimeout configures a Meta instance with the given timeout for the invocation of the wrapped value's Init method.
func WithMetaLogger ¶
func WithMetaLogger(logger Logger) MetaConfigFunc
WithMetaLogger configures a Meta instance with the given logger instance.
func WithMetaName ¶
func WithMetaName(name string) MetaConfigFunc
WithMetaName tags a Meta instance with the given name.
func WithMetaPriority ¶
func WithMetaPriority(priority int) MetaConfigFunc
WithMetaPriority tags a Meta instance with the given priority.
func WithMetaShutdownTimeout ¶
func WithMetaShutdownTimeout(timeout time.Duration) MetaConfigFunc
WithMetaShutdownTimeout configures a Meta instance with the given timeout for the time between the wrapped value's Stop method being invoked and the process's Run method unblocking.
func WithMetaStartupTimeout ¶
func WithMetaStartupTimeout(timeout time.Duration) MetaConfigFunc
WithMetaStartupTimeout configures a Meta instance with the given timeout for the time between the wrapped value's Run method being invoked and the process becoming healthy.
func WithMetaStopTimeout ¶
func WithMetaStopTimeout(timeout time.Duration) MetaConfigFunc
WithMetaStopTimeout configures a Meta instance with the given timeout for the invocation of the wrapped value's Stop method.
func WithMetadata ¶
func WithMetadata(metadata map[string]interface{}) MetaConfigFunc
WithMetadata tags a Meta instance with the given metadata.
type Runner ¶
type Runner interface {
// Run is the hook invoked on application startup. The run hook is expected
// to be long-running. Returning early, prior to the given context being
// canceled, is generally an unexpected event.
Run(ctx context.Context) error
}
Runner wraps behavior that happens continually through the application lifecycle.
type RunnerFunc ¶
RunnerFunc is a function conforming to the Runner interface.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State tracks the current state of application execution.
func Run ¶
func Run(ctx context.Context, container *Container, configs ...MachineConfigFunc) *State
Run builds a machine to invoke the processes registered to the given container. This method returns a state value that can be used to signal the application to begin shutdown, and to block until the active processes have exited.
func (*State) Errors ¶ added in v2.1.0
Errors returns a slice of errors encountered while running the processes. The Errors method can be used once the Wait method returns to find the errors returned by the processes.
func (*State) Wait ¶
Wait blocks until all processes exit cleanly or until an error occurs during execution of the machine built via Run. If an error occurs, all other running processes are signalled to exit. This method unblocks once all processes have exited. This method returns a boolean flag indicating a clean exit.
type Stopper ¶
type Stopper interface {
// Stop is the hook invoked on a running process immediately prior to the
// root context being canceled. This method may exit immediately and is
// not expected to synchronize on Run returning.
Stop(ctx context.Context) error
}
Stopper wraps a process with way to signal graceful exit.
Source Files