Documentation
¶
Overview ¶
Package hostup is the reconcile engine behind `hadron team host up` (hadron-cli#1389, epic hadron-server#4229): compare what a host SHOULD run with what it DOES run, plan the missing steps, and, on apply, carry them out through an Actuator.
The engine is pure over three seams, so it can be driven by fakes:
Source what should run: one Snapshot per host (the server's
hostDesiredState once hadron-server#4222/#4224 land; a file or
an in-memory fake until then)
Observer what does run: registration, worktree, agent terminals
Actuator how a planned step is carried out (the typed host-operation
queue, cor:agt:070:05; a host-local relaunch later, cli#2060)
What it never does, whatever the seams say: act on a worker the platform marked leave-alone, halted, paused, team-paused, resetting or retired; act when the App's sweep mode is not APPLY; cast, bind, rebind or end anything; act on a worker it could not observe.
Index ¶
Constants ¶
const ( Running = "RUNNING" Stopped = "STOPPED" )
Desired values of Worker.Desired.
const ( ActionWorktreeCreate = "worktree.create" ActionWorkerStart = "worker.start" // ActionWorkerRelaunch labels skipped work in reconciliation output. The // CLI never plans or applies it; the periodic poller is the launch owner. ActionWorkerRelaunch = "worker.relaunch" )
The actions a plan can hold. The first two are the typed host operations `worker onboard` issues; the third is host-local (cli#2060) and is planned only when the Actuator supports it.
const ( // Why a step is planned (and, once done, applied). ReasonWorktreeMissing = "WORKTREE_MISSING" ReasonNoSession = "NO_SESSION" ReasonTerminalMissing = "TERMINAL_MISSING" // Why a worker was left alone. The platform's own stop reasons // (LEAVE_ALONE, HALTED, PAUSED, TEAM_PAUSED, RESETTING, RETIRED, // SWEEP_OFF) pass through unchanged. ReasonInSync = "IN_SYNC" ReasonSweepNotApply = "SWEEP_NOT_APPLY" ReasonNotOnHost = "NOT_ON_HOST" ReasonNotRegistered = "NOT_REGISTERED" // ReasonNotAssigned: the App's setup source is SERVER and the platform // does not assign this worker to this host (cli#2085). ReasonNotAssigned = "NOT_ASSIGNED" ReasonUnknownDesired = "UNKNOWN_DESIRED" ReasonUnknownReason = "UNKNOWN_REASON" ReasonSessionWithoutWorktree = "SESSION_WITHOUT_WORKTREE" ReasonTerminalWithoutSession = "TERMINAL_WITHOUT_SESSION" ReasonDuplicateAgents = "DUPLICATE_AGENTS" ReasonNoWorktreeSource = "NO_WORKTREE_SOURCE" ReasonSetupInvalid = "SETUP_INVALID" ReasonRelaunchUnproven = "RELAUNCH_UNPROVEN" ReasonRelaunchPendingPoller = "RELAUNCH_PENDING_POLLER" ReasonStopPending = "STOP_PENDING" // Why a step failed. ReasonObserveFailed = "OBSERVE_FAILED" ReasonActionFailed = "ACTION_FAILED" ReasonRefused = "REFUSED" ReasonNotAttempted = "NOT_ATTEMPTED" )
Reason codes. They are part of the `--json` contract: add, never repurpose.
const SweepApply = "APPLY"
SweepApply is the only sweep mode under which the engine acts.
Variables ¶
var ErrLocked = errors.New("another host up run holds this host's lock")
ErrLocked is another run holding the host's lock.
Functions ¶
func Lock ¶
Lock takes the per-host run lock in dir, without waiting: two applying runs on one host never overlap (a timer's sweep and a hand run, or two sweeps when one runs long), and the second leaves at once with ErrLocked rather than queueing behind the first. It is an OS file lock, so a run that dies leaves nothing stale behind. The returned func releases it.
Types ¶
type AbortError ¶
type AbortError struct{ Err error }
AbortError is how an Actuator says the whole run must stop: nothing further is attempted (a refused credential must not be retried per worker).
func (*AbortError) Error ¶
func (e *AbortError) Error() string
func (*AbortError) Unwrap ¶
func (e *AbortError) Unwrap() error
type Actuator ¶
type Actuator interface {
Supports(action string) bool
Apply(ctx context.Context, w Worker, s Step) (ref string, err error)
}
Actuator carries out a step. Supports says whether it can, so a plan never holds a step that apply could not attempt. Apply returns a reference to what it did (a host-operation id), which may be set even when it fails.
type Item ¶
type Item struct {
WorkerID string
Worker string
// Action is the step, or for a skipped worker the step the engine did
// not take ("" when there was none to take).
Action string
Reason string
Args map[string]string
// Ref is the Actuator's reference for an applied or failed step.
Ref string
// Detail is free text for a human: the failure, or what was seen.
Detail string
}
Item is one line of a run's result: a step planned, applied or failed, or a worker skipped.
type Observation ¶
type Observation struct {
// PollerConnected is an engine extension point for an in-process adapter
// with a proven live association. The current CLI observer never sets it:
// host up reports RELAUNCH_UNPROVEN. Metadata or a state file is not proof.
PollerConnected bool
// Registered: the host's registration lists this worker.
Registered bool
// WorktreeExists: the worker's worktree (or plain directory) is there.
WorktreeExists bool
// AgentTerminals: live agent terminals in that worktree.
AgentTerminals int
}
Observation is what the host shows for one worker.
type Observer ¶
type Observer interface {
Observe(ctx context.Context, w Worker) (Observation, error)
}
Observer reads the host. An error means "could not tell", and the engine then plans nothing for that worker; an *AbortError stops the whole run before anything is applied.
type Options ¶
type Options struct {
HostID string
// Apply carries the plan out. False is a dry run: the Actuator's Apply is
// never called.
Apply bool
// Only narrows the run to one worker, matched against a worker's id or
// name (case-insensitively). A worker the snapshot does not hold is
// reported as NOT_ON_HOST and nothing is created for it.
Only string
}
Options select the run.
type Result ¶
type Result struct {
HostID string
SweepMode string
// SetupSource echoes Snapshot.SetupSource.
SetupSource string
DryRun bool
Planned []Item
Applied []Item
Skipped []Item
Failed []Item
}
Result is one run.
type Setup ¶
type Setup struct {
// Worktree is the worker's worktree name token, relative to the host's
// worktrees root: "<repo's last segment>/<label>" for a git worktree, or
// the name of a plain directory for a worker without Git.
Worktree string
// Repo, BaseBranch and Branch are what worktree.create needs. A worker
// with no Repo is never given a worktree: its directory must exist.
Repo string
BaseBranch string
Branch string
// Family is the model family worker.start launches.
Family string
// RepoSource, when set, names the repos the worker's role has, read only
// when the worktree is missing and Repo is empty. Exactly one entry is the
// repo a worktree.create is planned from; zero, several or a failed read is
// NO_WORKTREE_SOURCE: a repo is never guessed (cli#2085).
RepoSource func(ctx context.Context) ([]string, error)
// Problem, when set, is why the source could not give a usable setup
// (no worktree, several, or a malformed value). The worker is then
// reported SETUP_INVALID before the host is read for it.
Problem string
}
Setup is what the host needs to start a worker.
type Snapshot ¶
type Snapshot struct {
HostID string
SweepMode string
// SetupSource is the App's hostSetupSource ("HOST" or "SERVER") when the
// source read it, else "" (a file, or a server that predates it).
SetupSource string
Workers []Worker
}
Snapshot is a host's desired state.
type Worker ¶
type Worker struct {
WorkerID string
Name string
Desired string
Reason string
// WouldBe is what Desired would read without the marker in Reason (the
// server reports it for LEAVE_ALONE). Echoed, never acted on.
WouldBe string
// SessionID is the worker's open session, or "".
SessionID string
Setup Setup
// Unassigned: the App's setup source is SERVER and the platform does not
// assign this worker to this host. Reported, never acted on (cli#2085).
Unassigned bool
// Absent: assigned to this host by the platform, but the desired state
// does not list it (the host's registration does not). It has no desired
// state to act on: reported NOT_REGISTERED, never acted on (cli#2085).
Absent bool
}
Worker is one worker's desired state on a host.