Documentation
¶
Overview ¶
Package worker is factory-agent's worker loop (supervise.md §The worker loop): it registers with the dispatcher (its refresh token, else the one-time enrollment token), long-polls for leases, runs each leased task through a runner.Runner while heartbeating, reports the Outcome (complete, abandon, throttle), and drains on SIGTERM.
The agent token lives in memory only: a restart registers again with the refresh token, which rotates on each registration. Tokens are never logged.
Index ¶
Constants ¶
const ( BasePath = "/api/v1" HeaderEnrollmentToken = "X-Factory-Enrollment-Token" HeaderAgentRefreshToken = "X-Factory-Agent-Refresh-Token" )
The dispatcher's API base path and the registration credential headers (contracts.md §HTTP API).
const ( // DefaultLeaseWait is the long poll's wait (the dispatcher caps it at 60 s). DefaultLeaseWait = 30 * time.Second // DefaultHeartbeat is used when a lease doesn't say (pool.lease.heartbeat is 30 s). DefaultHeartbeat = 30 * time.Second // DefaultWallClock bounds a drain for a task whose TaskSpec sets no maxWallClock. DefaultWallClock = time.Hour // DefaultThrottle is how long a throttled harness rests when it gave no reset time // (harness-adapters.md: else +15 min). DefaultThrottle = 15 * time.Minute // DefaultMinBackoff and DefaultMaxBackoff bound the exponential backoff on failed calls. DefaultMinBackoff = time.Second DefaultMaxBackoff = time.Minute // DefaultReportAttempts is how often complete and abandon are tried on transient errors. DefaultReportAttempts = 5 )
Defaults.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type APIError ¶
APIError is a dispatcher answer other than the operation's success. It carries the problem's code and text, never a request's credentials.
type Enrollment ¶
type Enrollment interface {
// Token is the refresh token when one is saved (refresh true), else the one-time
// enrollment token.
Token() (tok string, refresh bool, err error)
// Save keeps the next refresh token durably; it is called before the registration that
// returned it is used.
Save(refresh string) error
// Forget drops a refresh token the dispatcher refused.
Forget() error
}
Enrollment is an enrolled agent's registration credential (P1 §6; enroll.Files).
type Options ¶
type Options struct {
// Dispatcher is the dispatcher's base URL (the API is under BasePath).
Dispatcher string
Pool string
Host string
AgentVersion string
Capabilities v1alpha1.AgentCapabilities
Lending v1alpha1.Lending
// Enrollment registers with the refresh token (else the enrollment token) and saves each
// rotated one.
Enrollment Enrollment
// Runner executes leased tasks.
Runner runner.Runner
// HTTPClient calls the dispatcher. Default: http.DefaultClient's transport, no timeout
// (each call carries its own deadline).
HTTPClient apiclient.HttpRequestDoer
Clock clock.Clock
Logger *slog.Logger
// LeaseWait is the long poll's wait, whole seconds in [1s, 60s]. Default 30 s.
LeaseWait time.Duration
// DefaultWallClock bounds a drain for tasks without limits.maxWallClock. Default 1 h.
DefaultWallClock time.Duration
// MinBackoff and MaxBackoff bound retries. Defaults 1 s and 1 min.
MinBackoff, MaxBackoff time.Duration
// ReportAttempts bounds complete/abandon retries. Default 5.
ReportAttempts int
}
Options configure a Worker. Pool, Host, AgentVersion, Capabilities, Enrollment and Runner are required.
type Worker ¶
type Worker struct {
// contains filtered or unexported fields
}
Worker is one registered agent's lease loop.
func (*Worker) Drain ¶
func (w *Worker) Drain()
Drain stops leasing: running tasks finish (or are abandoned with shutdown once their wall-clock budget is spent), then the agent deregisters and Run returns. Safe to call more than once and from any goroutine.
func (*Worker) Run ¶
Run registers, then leases and runs tasks until Drain (or a fatal error), waits for the running tasks and deregisters. Cancelling ctx aborts: running tasks are cancelled and abandoned with shutdown. It returns nil after a drain or an abort, and the error when registration is refused.
func (*Worker) SetLending ¶
SetLending changes the owner's consent (SIGHUP): the local concurrency now, and the dispatcher's copy through PATCH /agents/{id} once registered.