Documentation
¶
Overview ¶
Package supervisor implements the Supervisor Pattern for managing process and worker lifecycles.
A Supervisor is a special type of Worker that manages a collection of child Workers. It is responsible for starting (spawning), monitoring (watching), and restarting (healing) its children based on defined strategies.
Strategies ¶
The supervisor supports the following restart strategies:
- StrategyOneForOne: If a child process terminates, only that process is restarted.
- StrategyOneForAll: If a child process terminates, all other child processes are terminated, and then all child processes are restarted.
Backoff Strategy ¶
To prevent rapid restart loops, the supervisor implements an exponential backoff strategy with jitter. This is configurable per-worker via `Backoff` struct in `Spec`.
Dynamic Topology ¶
Workers can be added or removed dynamically at runtime using `Add(Spec)` and `Remove(name)`.
Handover Protocol ¶
The supervisor implements a Handover Protocol to provide continuity across restarts. Each worker spec is assigned a persistent `ResumeID`. When a worker is restarted, the supervisor injects this ID and the previous exit status (via `EnvInjector`) to allow the new instance to resume work or report status accurately.
Usage
sup := supervisor.New("my-sup", supervisor.StrategyOneForOne,
supervisor.Spec{
Name: "worker-1",
Factory: func() (worker.Worker, error) {
return worker.NewProcess("worker-1", "sleep", "10"), nil
},
},
)
sup.Start(ctx)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backoff ¶
type Backoff struct {
InitialInterval time.Duration
MaxInterval time.Duration
Multiplier float64
// ResetDuration is the time the child must run successfully to reset the backoff.
ResetDuration time.Duration
// MaxRestarts is the maximum number of restarts allowed within MaxDuration.
// If 0, no limit is enforced.
MaxRestarts int
// MaxDuration is the time window for MaxRestarts.
MaxDuration time.Duration
}
Backoff defines the retry policy for failed children.
type RestartPolicy ¶
type RestartPolicy string
RestartPolicy defines when a child worker should be restarted.
const ( // RestartAlways: Always restart the worker, regardless of exit reason (default). RestartAlways RestartPolicy = "Always" // RestartOnFailure: Restart only if the worker exits with an error. RestartOnFailure RestartPolicy = "OnFailure" // RestartNever: Never restart the worker. RestartNever RestartPolicy = "Never" )
type Spec ¶
type Spec struct {
Name string
Type string // "process", "container", "func" (optional, for diagrams)
Factory Factory
Backoff Backoff
RestartPolicy RestartPolicy
}
Spec defines the configuration for a supervised child worker.
type Strategy ¶
type Strategy string
Strategy defines how the supervisor handles child failures.
const ( // StrategyOneForOne: If a child process terminates, only that process is restarted. StrategyOneForOne Strategy = "OneForOne" // StrategyOneForAll: If a child process terminates, all other child processes are terminated, // and then all child processes are restarted. StrategyOneForAll Strategy = "OneForAll" )
type Supervisor ¶
type Supervisor interface {
worker.Worker
// Add executes a new worker under the supervisor.
Add(Spec) error
// Remove terminates and removes a worker from the supervisor.
Remove(name string) error
// Suspend pauses all suspendable children.
Suspend(context.Context) error
// Resume resumes all suspendable children.
Resume(context.Context) error
// Workers returns the state of all children.
Workers() []worker.State
// Watch returns a channel that emits state changes.
Watch(context.Context) <-chan introspection.StateChange[worker.State]
}
Supervisor defines the interface for a managed cluster of workers. It implements the worker.Worker interface, allowing it to be nested.
Source Files