Documentation
¶
Overview ¶
Package worker defines interfaces and implementations for managed units of work.
It provides a uniform `Worker` interface to manage the lifecycle (Start, Stop, Wait) of various execution units such as OS processes, Goroutines, or Containers.
key features:
- **Worker Interface**: A standard contract for starting, stopping, and waiting for work.
- **Functional Worker**: Simple adapter `FromFunc` to turn any function into a Worker.
- **Process Worker**: A wrapper around `os/exec` that ensures process hygiene (Fail-Closed) using `pkg/proc` logic (Job Objects on Windows, PDeathSig on Linux).
- **Container Worker**: A bridge to manage containerized workloads via `pkg/container`.
- **Handover Protocol**: Standard environment variables (`LIFECYCLE_RESUME_ID`, `LIFECYCLE_PREV_EXIT`) to pass context across worker restarts.
This package is foundational for the Supervisor pattern (v1.3+).
Index ¶
Constants ¶
const ( // EnvResumeID is the unique session identifier for a worker. // It remains constant across restarts within the same supervisor lifecycle. EnvResumeID = "LIFECYCLE_RESUME_ID" // EnvPrevExit is the exit code of the previous execution of this worker. // It is injected by the supervisor upon restart. EnvPrevExit = "LIFECYCLE_PREV_EXIT" // EnvResumeToken is the opaque token used to resume a worker session. // It is injected by the supervisor upon restart/handover. EnvResumeToken = "LIFECYCLE_RESUME_TOKEN" )
Standard environment variables for the Handover Protocol.
Variables ¶
This section is empty.
Functions ¶
func MermaidState ¶
MermaidState returns a simple Mermaid state diagram (FSM) for a single worker. It visualizes the lifecycle transitions: Pending -> Running -> Stopped/Failed. This is useful for understanding the internal behavior of a worker type.
func MermaidTree ¶
MermaidTree returns a Mermaid diagram string representing the worker structure (Tree). It renders a hierarchical tree (graph TD) showing parent-child relationships.
Types ¶
type ContainerWorker ¶
type ContainerWorker struct {
// contains filtered or unexported fields
}
ContainerWorker is a Worker that manages a container via the container.Container interface.
func NewContainerWorker ¶
func NewContainerWorker(name string, c container.Container) *ContainerWorker
NewContainerWorker creates a new Worker for a given container.
func (*ContainerWorker) State ¶
func (cw *ContainerWorker) State() State
func (*ContainerWorker) String ¶
func (cw *ContainerWorker) String() string
func (*ContainerWorker) Wait ¶
func (cw *ContainerWorker) Wait() <-chan error
type EnvInjector ¶
type EnvInjector interface {
SetEnv(key, value string)
}
EnvInjector is an optional interface for workers that support environment variable injection.
type ProcessWorker ¶
type ProcessWorker struct {
// contains filtered or unexported fields
}
ProcessWorker is a Worker that manages an OS process.
func NewProcessWorker ¶
func NewProcessWorker(name string, nameCmd string, args ...string) *ProcessWorker
NewProcessWorker creates a new ProcessWorker for the given command.
func (*ProcessWorker) SetEnv ¶
func (p *ProcessWorker) SetEnv(key, value string)
SetEnv adds an environment variable to the process.
func (*ProcessWorker) Start ¶
func (p *ProcessWorker) Start(ctx context.Context) error
Start starts the OS process.
func (*ProcessWorker) State ¶
func (p *ProcessWorker) State() State
State returns a snapshot of the worker's status.
func (*ProcessWorker) Stop ¶
func (p *ProcessWorker) Stop(ctx context.Context) error
Stop sends a signal to the process to terminate.
func (*ProcessWorker) String ¶
func (p *ProcessWorker) String() string
String returns the worker name.
func (*ProcessWorker) Wait ¶
func (p *ProcessWorker) Wait() <-chan error
Wait returns the channel to wait for process exit.
type Resumable ¶ added in v1.4.0
type Resumable interface {
Worker
// Pause requests the worker to stop and return a resume token.
// This token can be passed to a new worker instance via LIFECYCLE_RESUME_TOKEN.
Pause(context.Context) (string, error)
}
Resumable is an optional interface for workers that support pausing and resuming.
type State ¶
type State struct {
Name string
Status Status
PID int
ExitCode int
Error error
ResumeToken string
Metadata map[string]string
Children []State
}
State represents a snapshot of the worker's status.
type Worker ¶
type Worker interface {
// Start initiates the worker. It must be non-blocking.
// The context can be used to control the startup phase.
Start(context.Context) error
// Stop requests the worker to stop.
// It should respect the provided context for timeout/cancellation of the stop request.
Stop(context.Context) error
// Wait returns a channel that is closed when the worker has exited.
// The error associated with the exit (if any) is sent on the channel.
Wait() <-chan error
// String returns a human-readable description/ID of the worker.
String() string
// State returns the current state of the worker for introspection.
// Note: This returns a snapshot; some fields might be empty if not applicable.
State() State
}
Worker defines the interface for a managed unit of work (process, goroutine, container).
The lifecycle is:
- Start(ctx) -> Non-blocking.
- Wait() -> Returns channel that closes when work finishes.
- Stop(ctx) -> Graceful termination request.
Source Files