Documentation
¶
Overview ¶
Package engine is the orchestration core of env-starter: a foreground supervisor that starts and stops environments made of globally-shared commands, respecting the dependency graph declared in each environment's workflow.
A command is identified by its name and runs once globally. Starting an environment records that environment as a holder of the command (and waits for it to be healthy if already running). Stopping an environment removes its hold; a command is actually torn down only when no environment holds it.
Index ¶
- type CmdState
- type Engine
- func (e *Engine) ApplyConfig(cfg *config.Config) error
- func (e *Engine) CmdRetries(command string) (attempts, max int)
- func (e *Engine) CmdState(command string) CmdState
- func (e *Engine) EnvState(env string) EnvState
- func (e *Engine) Environments() []EnvInfo
- func (e *Engine) Events() <-chan Event
- func (e *Engine) IsUnmanaged(command string) bool
- func (e *Engine) LogPath(command string) string
- func (e *Engine) Logs(command string) []string
- func (e *Engine) PurgeOldLogs() ([]string, error)
- func (e *Engine) ResolveEnv(envName, command string) []ResolvedEnvVar
- func (e *Engine) RestartCommand(name string) error
- func (e *Engine) Shutdown(ctx context.Context)
- func (e *Engine) StartEnvironment(env string) error
- func (e *Engine) StopEnvironment(env string) error
- func (e *Engine) StoppingCommands() []StoppingCommand
- func (e *Engine) WorkflowCommands(env string) []string
- type EnvInfo
- type EnvLayer
- type EnvSource
- type EnvState
- type Event
- type ResolvedEnvVar
- type StoppingCommand
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// GracePeriod is how long a service is given to exit after SIGINT before
// SIGKILL. Exposed as a field so tests can shrink it.
GracePeriod time.Duration
// ProbeTimeout / ProbeInterval are the defaults used when a readiness probe
// does not specify its own. Exposed so tests can shrink them.
ProbeTimeout time.Duration
ProbeInterval time.Duration
// contains filtered or unexported fields
}
Engine supervises environments and their commands.
cfg, cmdOf, envsOf, and envEnvOf are guarded by mu but are never mutated in place: a config reload (see ApplyConfig) replaces each with a newly built value under the lock, so a reader that copies a reference while holding mu keeps a valid, immutable snapshot after releasing it.
func New ¶
New builds an Engine from cfg, validating that every environment workflow references commands that resolve to defined commands.
func (*Engine) ApplyConfig ¶ added in v1.7.0
ApplyConfig atomically swaps in a new configuration and reconciles running state selectively (see diffConfig/reloadPlan for what "selectively" means). It returns an error only when the new config is structurally invalid, in which case nothing is mutated. Once it returns nil the new config is in force for every reader; the restarts it schedules run asynchronously and report progress via Events(), so a restart failure surfaces as CmdError / EnvDegraded rather than as an error from this call.
func (*Engine) CmdRetries ¶ added in v0.2.0
CmdRetries returns the number of restart attempts consumed in the current cycle and the configured maximum. Both values are 0 for a command that has never been (or never can be) auto-restarted.
func (*Engine) CmdState ¶
CmdState returns the current state of a command. A command that has never been started (or that has been fully torn down) reports CmdPending.
func (*Engine) EnvState ¶
EnvState returns the current state of an environment (EnvStopped if unknown).
func (*Engine) Environments ¶
Environments returns the environments in config order.
func (*Engine) Events ¶
Events returns the buffered event channel. Sends are non-blocking: if no one is reading and the buffer is full, events are dropped.
func (*Engine) IsUnmanaged ¶ added in v1.6.0
IsUnmanaged reports whether command is currently healthy only because an external process already satisfied its readiness probe before env-starter spawned anything. False for a command that has never been started, that env-starter actually launched itself, or that is unknown.
func (*Engine) LogPath ¶
LogPath returns the on-disk path where the given command's logs are written.
func (*Engine) Logs ¶
Logs returns a copy of the command's ring-buffer lines, or an empty slice if the command has no logs.
func (*Engine) PurgeOldLogs ¶ added in v0.4.1
PurgeOldLogs removes log files older than logbuf.LogRetention from the logs directory. It is safe to call before any command starts. A missing directory is not an error. Returns the base names of removed files.
func (*Engine) ResolveEnv ¶ added in v1.6.0
func (e *Engine) ResolveEnv(envName, command string) []ResolvedEnvVar
ResolveEnv resolves the env variables visible to the given environment or command, with full layer provenance. Pass a non-empty command to resolve exactly what that command's process receives (OS env, overlaid by the union of its current holders' environment-level env, overlaid by the command's own env — the same layering effectiveEnv applies at launch). Otherwise pass a non-empty envName to resolve what every command in that environment's workflow inherits before its own overrides (OS env, overlaid by the environment's own env). Returns nil for an unknown name.
func (*Engine) RestartCommand ¶ added in v1.3.0
RestartCommand restarts a single running command in place, preserving its environment holders. Unlike automatic restarts it is user-initiated and ignores the restart policy — it recycles the process even when auto-restart is disabled for this command. Returns an error if the command is unknown or currently has no holders (i.e. it is not running).
func (*Engine) Shutdown ¶
Shutdown stops every currently-running command gracefully, respecting ctx as an overall deadline. All holders are cleared.
func (*Engine) StartEnvironment ¶
StartEnvironment starts the named environment asynchronously. It returns an error only if the environment is unknown; startup progress is reported via Events() and the state accessors.
If the environment is currently in a failed state (EnvError or EnvDegraded), it is first reset: its workflow commands are released so that errored commands — whose refcount was never decremented on failure — are recreated fresh. Commands still shared with other running environments are not torn down.
func (*Engine) StopEnvironment ¶
StopEnvironment decrements the reference count of every command in the named environment's workflow. A command is actually torn down only when its reference count reaches zero. Returns an error if the environment is unknown.
func (*Engine) StoppingCommands ¶
func (e *Engine) StoppingCommands() []StoppingCommand
StoppingCommands returns the commands currently being torn down, in config order. Each entry carries the time elapsed since stopping began and the per-process SIGINT→SIGKILL grace budget. Returns an empty slice when nothing is stopping.
func (*Engine) WorkflowCommands ¶
WorkflowCommands returns the command names in the given environment's workflow order. Returns nil for an unknown environment.
type EnvLayer ¶ added in v1.6.0
EnvLayer is one layer's contribution to a key: the value it set, and which source set it.
type EnvSource ¶ added in v1.6.0
type EnvSource string
EnvSource identifies which layer produced a resolved env value.
type Event ¶
type Event struct {
Kind string // "environment" | "command"
Environment string
Command string
EnvState EnvState
CmdState CmdState
Err error
}
Event is emitted on every state change. Command events carry Command and CmdState; environment events carry Environment and EnvState.
type ResolvedEnvVar ¶ added in v1.6.0
ResolvedEnvVar is one key's full provenance: the value actually applied (Winning) plus every lower-priority layer it shadows, nearest first, so a caller can show what a variable overrides without a second lookup.
Source Files