Documentation
¶
Overview ¶
Package controls provides a lifecycle controller for managing concurrent, long-running services such as HTTP servers, background workers, and schedulers.
The Controller orchestrates startup, health monitoring, and graceful shutdown with proper cleanup ordering. Shared communication channels carry errors, OS signals, and control messages between registered services.
The Controllable interface abstracts the controller for testing, exposing Start, Stop, IsRunning, IsStopped, IsStopping, Register, and configuration methods. Concrete transports are provided by the grpc and http sub-packages.
Index ¶
- Constants
- Variables
- type ChannelProvider
- type Configurable
- type Controllable
- type Controller
- func (c *Controller) Errors() chan error
- func (c *Controller) GetContext() context.Context
- func (c *Controller) GetLogger() logger.Logger
- func (c *Controller) GetServiceInfo(name string) (ServiceInfo, bool)
- func (c *Controller) GetState() State
- func (c *Controller) Health() chan HealthMessage
- func (c *Controller) IsRunning() bool
- func (c *Controller) IsStopped() bool
- func (c *Controller) IsStopping() bool
- func (c *Controller) Liveness() HealthReport
- func (c *Controller) Messages() chan Message
- func (c *Controller) Readiness() HealthReport
- func (c *Controller) Register(id string, opts ...ServiceOption)
- func (c *Controller) SetErrorsChannel(errs chan error)
- func (c *Controller) SetHealthChannel(health chan HealthMessage)
- func (c *Controller) SetLogger(l logger.Logger)
- func (c *Controller) SetMessageChannel(messages chan Message)
- func (c *Controller) SetShutdownTimeout(d time.Duration)
- func (c *Controller) SetSignalsChannel(signals chan os.Signal)
- func (c *Controller) SetState(state State)
- func (c *Controller) SetWaitGroup(wg *sync.WaitGroup)
- func (c *Controller) Signals() chan os.Signal
- func (c *Controller) Start()
- func (c *Controller) Status() HealthReport
- func (c *Controller) Stop()
- func (c *Controller) Wait()
- func (c *Controller) WaitGroup() *sync.WaitGroup
- type ControllerOpt
- type HealthMessage
- type HealthReport
- type HealthReporter
- type Message
- type ProbeFunc
- type RestartPolicy
- type Runner
- type Service
- type ServiceInfo
- type ServiceOption
- type ServiceStatus
- type Services
- type StartFunc
- type State
- type StateAccessor
- type StatusFunc
- type StopFunc
- type ValidErrorFunc
Constants ¶
const DefaultShutdownTimeout = 5 * time.Second
Variables ¶
var ErrShutdown = errors.New("controller shutdown")
ErrShutdown is the cause attached to the controller context when a graceful shutdown is initiated. Callers can distinguish a controlled stop from an upstream cancellation via context.Cause(ctx) == controls.ErrShutdown.
Functions ¶
This section is empty.
Types ¶
type ChannelProvider ¶
type ChannelProvider interface {
Messages() chan Message
Health() chan HealthMessage
Errors() chan error
Signals() chan os.Signal
}
ChannelProvider provides access to controller channels.
type Configurable ¶
type Configurable interface {
SetErrorsChannel(errs chan error)
SetMessageChannel(control chan Message)
SetSignalsChannel(sigs chan os.Signal)
SetHealthChannel(health chan HealthMessage)
SetWaitGroup(wg *sync.WaitGroup)
SetShutdownTimeout(d time.Duration)
SetLogger(l logger.Logger)
}
Configurable provides controller configuration setters.
type Controllable ¶
type Controllable interface {
Runner
HealthReporter
StateAccessor
Configurable
ChannelProvider
}
Controllable is the full controller interface, composed of all role-based interfaces. Prefer using the narrower interfaces (Runner, HealthReporter, Configurable, etc.) where possible.
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
func NewController ¶
func NewController(ctx context.Context, opts ...ControllerOpt) *Controller
func (*Controller) Errors ¶
func (c *Controller) Errors() chan error
func (*Controller) GetContext ¶
func (c *Controller) GetContext() context.Context
func (*Controller) GetLogger ¶
func (c *Controller) GetLogger() logger.Logger
func (*Controller) GetServiceInfo ¶ added in v1.6.0
func (c *Controller) GetServiceInfo(name string) (ServiceInfo, bool)
GetServiceInfo returns the runtime information and statistics for a specific service.
func (*Controller) GetState ¶
func (c *Controller) GetState() State
func (*Controller) Health ¶
func (c *Controller) Health() chan HealthMessage
func (*Controller) IsRunning ¶
func (c *Controller) IsRunning() bool
func (*Controller) IsStopped ¶
func (c *Controller) IsStopped() bool
func (*Controller) IsStopping ¶
func (c *Controller) IsStopping() bool
func (*Controller) Liveness ¶ added in v1.6.0
func (c *Controller) Liveness() HealthReport
Liveness returns an aggregate liveness report for all registered services.
func (*Controller) Messages ¶
func (c *Controller) Messages() chan Message
func (*Controller) Readiness ¶ added in v1.6.0
func (c *Controller) Readiness() HealthReport
Readiness returns an aggregate readiness report for all registered services.
func (*Controller) Register ¶
func (c *Controller) Register(id string, opts ...ServiceOption)
func (*Controller) SetErrorsChannel ¶
func (c *Controller) SetErrorsChannel(errs chan error)
func (*Controller) SetHealthChannel ¶
func (c *Controller) SetHealthChannel(health chan HealthMessage)
func (*Controller) SetLogger ¶
func (c *Controller) SetLogger(l logger.Logger)
func (*Controller) SetMessageChannel ¶
func (c *Controller) SetMessageChannel(messages chan Message)
func (*Controller) SetShutdownTimeout ¶
func (c *Controller) SetShutdownTimeout(d time.Duration)
func (*Controller) SetSignalsChannel ¶
func (c *Controller) SetSignalsChannel(signals chan os.Signal)
func (*Controller) SetState ¶
func (c *Controller) SetState(state State)
func (*Controller) SetWaitGroup ¶
func (c *Controller) SetWaitGroup(wg *sync.WaitGroup)
func (*Controller) Signals ¶
func (c *Controller) Signals() chan os.Signal
func (*Controller) Start ¶
func (c *Controller) Start()
Start launches all registered services. Duplicate calls while already running are no-ops.
func (*Controller) Status ¶ added in v1.6.0
func (c *Controller) Status() HealthReport
Status returns an aggregate health report for all registered services.
func (*Controller) Stop ¶
func (c *Controller) Stop()
Stop initiates a graceful shutdown. Duplicate calls while already stopping or stopped are safely ignored.
func (*Controller) Wait ¶
func (c *Controller) Wait()
func (*Controller) WaitGroup ¶
func (c *Controller) WaitGroup() *sync.WaitGroup
type ControllerOpt ¶
type ControllerOpt func(Configurable)
ControllerOpt is a functional option for configuring a Controller.
func WithLogger ¶
func WithLogger(l logger.Logger) ControllerOpt
WithLogger sets the controller logger.
func WithShutdownTimeout ¶
func WithShutdownTimeout(d time.Duration) ControllerOpt
WithShutdownTimeout sets the graceful shutdown timeout.
func WithoutSignals ¶
func WithoutSignals() ControllerOpt
WithoutSignals disables OS signal handling.
type HealthMessage ¶
type HealthReport ¶ added in v1.6.0
type HealthReport struct {
OverallHealthy bool `json:"overall_healthy"`
Services []ServiceStatus `json:"services"`
}
type HealthReporter ¶ added in v1.6.2
type HealthReporter interface {
Status() HealthReport
Liveness() HealthReport
Readiness() HealthReport
GetServiceInfo(name string) (ServiceInfo, bool)
}
HealthReporter provides read access to service health, liveness, and readiness reports, and to per-service runtime information. Handlers and transports that only need to query health should depend on this interface rather than the full Controllable.
type RestartPolicy ¶ added in v1.6.0
type RestartPolicy struct {
MaxRestarts int
InitialBackoff time.Duration
MaxBackoff time.Duration
HealthFailureThreshold int
HealthCheckInterval time.Duration
}
RestartPolicy defines how a service should be restarted on failure.
type Runner ¶
type Runner interface {
Start()
Stop()
IsRunning() bool
IsStopped() bool
IsStopping() bool
Register(id string, opts ...ServiceOption)
}
Runner provides service lifecycle operations.
type Service ¶
type Service struct {
Name string
Start StartFunc
Stop StopFunc
Status StatusFunc
Liveness ProbeFunc
Readiness ProbeFunc
RestartPolicy *RestartPolicy
}
type ServiceInfo ¶ added in v1.6.0
type ServiceOption ¶
type ServiceOption func(*Service)
func WithLiveness ¶ added in v1.6.0
func WithLiveness(fn ProbeFunc) ServiceOption
func WithReadiness ¶ added in v1.6.0
func WithReadiness(fn ProbeFunc) ServiceOption
func WithRestartPolicy ¶ added in v1.6.0
func WithRestartPolicy(policy RestartPolicy) ServiceOption
func WithStart ¶
func WithStart(fn StartFunc) ServiceOption
func WithStatus ¶
func WithStatus(fn StatusFunc) ServiceOption
func WithStop ¶
func WithStop(fn StopFunc) ServiceOption
type ServiceStatus ¶ added in v1.6.0
type StateAccessor ¶
type StateAccessor interface {
GetState() State
SetState(state State)
GetContext() context.Context
GetLogger() logger.Logger
}
StateAccessor provides read access to controller state and context.
type StatusFunc ¶
type StatusFunc func() error