controls

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

Index

• Constants
• Variables
• type Controllable
• type Controller
  • func NewController(ctx context.Context, opts ...ControllerOpt) *Controller
  • func (c *Controller) Errors() chan error
  • func (c *Controller) GetContext() context.Context
  • func (c *Controller) GetLogger() *slog.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(logger *slog.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
  • func WithLogger(logger *slog.Logger) ControllerOpt
  • func WithShutdownTimeout(d time.Duration) ControllerOpt
  • func WithoutSignals() ControllerOpt
• type HealthMessage
• type Message
• type Service
• type ServiceOption
  • func WithStart(fn StartFunc) ServiceOption
  • func WithStatus(fn StatusFunc) ServiceOption
  • func WithStop(fn StopFunc) ServiceOption
• type Services
• type StartFunc
• type State
• 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.

Types

type Controllable

type Controllable interface {
	Messages() chan Message
	Health() chan HealthMessage
	Errors() chan error
	Signals() chan os.Signal
	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)
	Start()
	Stop()
	GetContext() context.Context
	SetState(state State)
	GetState() State
	SetLogger(logger *slog.Logger)
	GetLogger() *slog.Logger
	IsRunning() bool
	IsStopped() bool
	IsStopping() bool
	Register(id string, opts ...ServiceOption)
}

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() *slog.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(logger *slog.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()

func (*Controller) Stop

func (c *Controller) Stop()

Stop configured server.

func (*Controller) Wait

func (c *Controller) Wait()

func (*Controller) WaitGroup

func (c *Controller) WaitGroup() *sync.WaitGroup

type ControllerOpt

type ControllerOpt func(Controllable)

func WithLogger

func WithLogger(logger *slog.Logger) ControllerOpt

Global Options.

func WithShutdownTimeout

func WithShutdownTimeout(d time.Duration) ControllerOpt

func WithoutSignals

func WithoutSignals() ControllerOpt

type HealthMessage

type HealthMessage struct {
	Host    string `json:"host"`
	Port    int    `json:"port"`
	Status  int    `json:"status"`
	Message string `json:"message"`
}

type Message

type Message string

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

type Service

type Service struct {
	Name   string
	Start  StartFunc
	Stop   StopFunc
	Status StatusFunc
}

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 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 StatusFunc

type StatusFunc func()

type StopFunc

type StopFunc func(context.Context)

type ValidErrorFunc

type ValidErrorFunc func(error) bool