controls

package
v1.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 25, 2026 License: MIT Imports: 8 Imported by: 0

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

View Source
const DefaultShutdownTimeout = 5 * time.Second

Variables

View Source
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

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 HealthMessage struct {
	Host    string `json:"host"`
	Port    int    `json:"port"`
	Status  int    `json:"status"`
	Message string `json:"message"`
}

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 Message

type Message string
const (
	Stop   Message = "stop"
	Status Message = "status"
)

type ProbeFunc added in v1.6.0

type ProbeFunc func() error

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 ServiceInfo struct {
	Name         string
	RestartCount int
	LastStarted  time.Time
	LastStopped  time.Time
	Error        error
}

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 ServiceStatus struct {
	Name   string `json:"name"`
	Status string `json:"status"` // "OK", "ERROR"
	Error  string `json:"error,omitempty"`
}

type Services

type Services struct {
	// contains filtered or unexported fields
}

type StartFunc

type StartFunc func(context.Context) error

type State

type State string
const (
	Unknown  State = "unknown"
	Running  State = "running"
	Stopping State = "stopping"
	Stopped  State = "stopped"
)

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

type StopFunc

type StopFunc func(context.Context)

type ValidErrorFunc

type ValidErrorFunc func(error) bool

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL