lifecycle

type Action ¶

type Action string

const (
	ActionInitialize Action = "initialize"
	ActionStart      Action = "start"
	ActionStop       Action = "stop"
	ActionRestart    Action = "restart"
	ActionReload     Action = "reload"
)

type Checkpointer ¶

type Checkpointer interface {
	// Checkpoint writes a checkpoint of the runner's process into dir,
	// which must already exist.
	//
	// On success the process is STOPPED. That is deliberate: the image
	// is the rollback artifact for a migration, and a source that keeps
	// executing past the point its image captured has already diverged
	// from it.
	Checkpoint(ctx context.Context, dir string) error

	// Restore recreates the process from the checkpoint in dir and
	// adopts it, so the runner's Pid reports the restored process and
	// Stop can terminate it.
	//
	// The restored process is not a child of this program - CRIU spawns
	// it - so it is tracked by pid and reparents to the supervisor's
	// subreaper, which is how its eventual exit is observed.
	Restore(ctx context.Context, dir string) error
}

Checkpointer is an optional capability for runners whose process can be checkpointed and restored with CRIU (GOBLIN-DIV-018). Runners that cannot be dumped - anything running in-process rather than as a separate program - simply do not implement it, and an orchestrator asserts the capability once at admission rather than discovering at migration time that a workload was never movable.

Both methods take a context on the same terms as Start: it bounds the call, not the lifetime of the process the call produces.

type Controller ¶

type Controller struct {
	GraceStop time.Duration
	WaitStart time.Duration
	WaitStop  time.Duration
	// contains filtered or unexported fields
}

func NewController(id, host string, r Runner, bus *TypedBus, deps DependencyResolver) *Controller

func (c *Controller) Apply(a Action) error

func (c *Controller) ApplyWithContext(ctx context.Context, a Action) error

func (c *Controller) State() string

type DependencyResolver ¶

type DependencyResolver interface {
	DepsOf(id string) []string
	IsRunning(id string) bool
	EnsureStarted(ctx context.Context, id string) error
}

type LifecycleStateMachine ¶

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

func NewLifecycleStateMachine(agentID, hostname string, bus *eventbus.EventBus[*anypb.Any]) *LifecycleStateMachine

func (lsm *LifecycleStateMachine) CurrentProtoState() protopkg.AgentState

func (lsm *LifecycleStateMachine) GetState() string

func (lsm *LifecycleStateMachine) TransitionTo(newState string) error

type RunIDSetter ¶

type RunIDSetter interface {
	SetRunID(string)
}

Optional capability for runners to support per-start correlation.

type Runner ¶

type Runner interface {
	// Start spawns the runner's process. The context bounds the start
	// operation only - it is cancelled as soon as Start returns, so an
	// implementation must NOT tie the spawned process's lifetime to it.
	// exec.CommandContext here means the process is SIGKILLed the moment
	// the start call completes (GAPI-DIV-028); use exec.Command and let
	// Stop own the process.
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Reload(ctx context.Context) error
	Reset()
}

type SpeechReporter ¶

type SpeechReporter interface {
	// HasSpoken reports whether any valid control frame has arrived
	// since the current run was started. It is reset by Start, so it
	// answers about this run and not the agent's history.
	HasSpoken() bool
}

SpeechReporter answers whether the current run's child has written any control frame at all (GAPI-DIV-104).

A START DEADLINE THAT EXPIRES HAS TWO CAUSES AND THEY NEED DIFFERENT ANSWERS. A child that spoke and has not yet reached RUNNING is slow; a child that has said nothing is either hung before its first report or built against an ADK that never opened the descriptor. Since GAPI-DIV-099 the supervisor learns state only from frames the agent writes, so silence is the sole evidence for the second case - and without this the timeout names neither, reporting only that the wait ended.

Optional, on the same terms as RunIDSetter: an in-process runner has no control channel and simply does not implement it, which is distinct from implementing it and answering false.

type StartTimeout ¶

type StartTimeout struct {
	AgentID      string
	RunID        string
	Waited       time.Duration
	Silent       bool
	SilenceKnown bool
}

StartTimeout is the start deadline expiring, as data rather than as a sentence (GAPI-DIV-104).

Silent is the discriminator the old bare timeout could not express: a child that has written nothing is hung before its first report or was built against an ADK that never opened the control descriptor, while one that has spoken and not reached RUNNING is merely slow. Those want different operator responses, and a caller must be able to branch on the difference without matching on a message.

SilenceKnown is separate from Silent because "the runner cannot answer this question" is a third state, not a quiet false. An in-process runner has no control channel at all.

func (e *StartTimeout) Error() string

type TypedBus ¶

type TypedBus = eventbus.EventBus[*anypb.Any]