README
¶
Controls
Service orchestration and lifecycle management for long-running processes.
Provides:
- Controller for managing background services
- Lifecycle hooks for startup and shutdown
- Standard interfaces for cancellable tasks
For detailed documentation and implementation patterns, see the Controls Component Documentation.
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) 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) Messages() chan Message
- 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) Stop()
- func (c *Controller) Wait()
- func (c *Controller) WaitGroup() *sync.WaitGroup
- type ControllerOpt
- type HealthMessage
- type Message
- type Runner
- type Service
- type ServiceOption
- 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
StateAccessor
Configurable
ChannelProvider
}
Controllable is the full controller interface, composed of all role-based interfaces. Prefer using the narrower interfaces (Runner, 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) 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) Messages ¶
func (c *Controller) Messages() chan Message
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) 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 Runner ¶
type Runner interface {
Start()
Stop()
IsRunning() bool
IsStopped() bool
IsStopping() bool
Register(id string, opts ...ServiceOption)
}
Runner provides service lifecycle operations.
type ServiceOption ¶
type ServiceOption func(*Service)
func WithStart ¶
func WithStart(fn StartFunc) ServiceOption
func WithStatus ¶
func WithStatus(fn StatusFunc) ServiceOption
func WithStop ¶
func WithStop(fn StopFunc) ServiceOption
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()
type ValidErrorFunc ¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package grpc provides a gRPC transport for the controls lifecycle controller, enabling remote service management and health checking over gRPC.
|
Package grpc provides a gRPC transport for the controls lifecycle controller, enabling remote service management and health checking over gRPC. |
|
Package http provides an HTTP transport for the controls lifecycle controller, exposing health, readiness, and management endpoints for use with container orchestrators and load balancers.
|
Package http provides an HTTP transport for the controls lifecycle controller, exposing health, readiness, and management endpoints for use with container orchestrators and load balancers. |