worker

package
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 22, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package worker models Fort's deterministic cloud worker protocol. It owns no database, network, clock, or runtime integration.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalid               = errors.New("worker protocol command is invalid")
	ErrAlreadyLeased         = errors.New("target already has a lease")
	ErrStaleAttempt          = errors.New("worker attempt is stale")
	ErrNeedsAttention        = errors.New("target recovery needs human attention")
	ErrIdempotencyConflict   = errors.New("worker protocol idempotency key conflicts with an earlier command")
	ErrTerminalReceiptExists = errors.New("attempt already has a terminal receipt")
)

Functions

This section is empty.

Types

type AuthoritySnapshot 

type AuthoritySnapshot struct {
	ID               string   `json:"id"`
	Revision         string   `json:"revision"`
	Permissions      []string `json:"permissions"`
	ContextRecordIDs []string `json:"context_record_ids"`
}

AuthoritySnapshot is the exact effective grant accepted for one Target. It contains values, rather than only a mutable authority identifier.

type CancelCommand 

type CancelCommand struct {
	TargetID       string    `json:"target_id"`
	AttemptID      string    `json:"attempt_id"`
	MachineID      string    `json:"machine_id"`
	IdempotencyKey string    `json:"idempotency_key"`
	RequestedAt    time.Time `json:"requested_at"`
	Reason         string    `json:"reason"`
}

type Cancellation 

type Cancellation struct {
	TargetID       string    `json:"target_id"`
	AttemptID      string    `json:"attempt_id"`
	MachineID      string    `json:"machine_id"`
	IdempotencyKey string    `json:"idempotency_key"`
	RequestedAt    time.Time `json:"requested_at"`
	Reason         string    `json:"reason"`
}

type ClaimCommand 

type ClaimCommand struct {
	TargetID       string    `json:"target_id"`
	AttemptID      string    `json:"attempt_id"`
	MachineID      string    `json:"machine_id"`
	IdempotencyKey string    `json:"idempotency_key"`
	ClaimedAt      time.Time `json:"claimed_at"`
	ExpiresAt      time.Time `json:"expires_at"`
}

type EnrolledMachine 

type EnrolledMachine struct {
	ID         string       `json:"id"`
	AccountID  string       `json:"account_id"`
	State      MachineState `json:"state"`
	EnrolledAt time.Time    `json:"enrolled_at"`
}

EnrolledMachine is the account-scoped worker identity allowed to claim work.

func (EnrolledMachine) Validate 

func (m EnrolledMachine) Validate(at time.Time) error

type ExecutionPins 

type ExecutionPins struct {
	AgentID                    string            `json:"agent_id"`
	BehaviorRevisionID         string            `json:"behavior_revision_id"`
	BindingRevisionID          string            `json:"binding_revision_id"`
	SeatID                     string            `json:"seat_id"`
	EffectiveAuthoritySnapshot AuthoritySnapshot `json:"effective_authority_snapshot"`
}

ExecutionPins are immutable execution identity and authority evidence.

type HeartbeatCommand 

type HeartbeatCommand struct {
	TargetID    string    `json:"target_id"`
	AttemptID   string    `json:"attempt_id"`
	MachineID   string    `json:"machine_id"`
	ObservedAt  time.Time `json:"observed_at"`
	ExtendUntil time.Time `json:"extend_until"`
}

type HeartbeatResult 

type HeartbeatResult struct {
	Lease     Lease           `json:"lease"`
	Directive WorkerDirective `json:"directive"`
}

type Lease 

type Lease struct {
	TargetID  string        `json:"target_id"`
	AttemptID string        `json:"attempt_id"`
	MachineID string        `json:"machine_id"`
	Pins      ExecutionPins `json:"pins"`
	State     LeaseState    `json:"state"`
	ClaimedAt time.Time     `json:"claimed_at"`
	ExpiresAt time.Time     `json:"expires_at"`
}

type LeaseState 

type LeaseState string
const (
	LeaseClaimed         LeaseState = "claimed"
	LeaseWorking         LeaseState = "working"
	LeaseCancelRequested LeaseState = "cancel_requested"
	LeaseExpired         LeaseState = "expired"
	LeaseCompleted       LeaseState = "completed"
	LeaseFailed          LeaseState = "failed"
	LeaseCanceled        LeaseState = "canceled"
)

type MachineState 

type MachineState string
const (
	MachineEnrolled MachineState = "enrolled"
	MachineRevoked  MachineState = "revoked"
)

type Recovery 

type Recovery struct {
	TargetID   string         `json:"target_id"`
	AttemptID  string         `json:"attempt_id"`
	MachineID  string         `json:"machine_id"`
	Reason     RecoveryReason `json:"reason"`
	ExpiresAt  time.Time      `json:"expires_at"`
	ObservedAt time.Time      `json:"observed_at"`
}

Recovery preserves the exact lease that requires an explicit human decision. It is not a new queue entry and cannot be claimed automatically.

type RecoveryReason 

type RecoveryReason string
const (
	RecoveryLeaseExpired RecoveryReason = "lease_expired"
)

type Target 

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

Target is one queued request and at most one worker attempt lease.

func NewTarget 

func NewTarget(spec TargetSpec) (*Target, error)

func (*Target) Claim 

func (t *Target) Claim(machine EnrolledMachine, command ClaimCommand) (Lease, error)

func (*Target) CommitTerminal 

func (t *Target) CommitTerminal(receipt TerminalReceipt) (TerminalReceipt, bool, error)

CommitTerminal records exactly one terminal receipt. An exact replay is a successful no-op; every competing receipt conflicts.

func (*Target) Heartbeat 

func (t *Target) Heartbeat(command HeartbeatCommand) (HeartbeatResult, error)

func (*Target) ObserveExpiry 

func (t *Target) ObserveExpiry(observedAt time.Time) (bool, error)

ObserveExpiry records an elapsed active lease as actionable recovery. A false result means either the deadline has not elapsed or recovery was already recorded.

func (*Target) RequestCancel 

func (t *Target) RequestCancel(command CancelCommand) (Cancellation, error)

func (*Target) Snapshot 

func (t *Target) Snapshot() TargetSnapshot

type TargetSnapshot 

type TargetSnapshot struct {
	ID              string           `json:"id"`
	AccountID       string           `json:"account_id"`
	State           TargetState      `json:"state"`
	Pins            ExecutionPins    `json:"pins"`
	Lease           *Lease           `json:"lease,omitempty"`
	Cancellation    *Cancellation    `json:"cancellation,omitempty"`
	Recovery        *Recovery        `json:"recovery,omitempty"`
	TerminalReceipt *TerminalReceipt `json:"terminal_receipt,omitempty"`
}

type TargetSpec 

type TargetSpec struct {
	ID        string        `json:"id"`
	AccountID string        `json:"account_id"`
	Pins      ExecutionPins `json:"pins"`
}

type TargetState 

type TargetState string
const (
	TargetQueued                    TargetState = "queued"
	TargetLeased                    TargetState = "leased"
	TargetWorking                   TargetState = "working"
	TargetCancelRequested           TargetState = "cancel_requested"
	TargetRecoverableNeedsAttention TargetState = "recoverable_needs_attention"
	TargetCompleted                 TargetState = "completed"
	TargetFailed                    TargetState = "failed"
	TargetCanceled                  TargetState = "canceled"
)

type TerminalReceipt 

type TerminalReceipt struct {
	TargetID       string         `json:"target_id"`
	AttemptID      string         `json:"attempt_id"`
	MachineID      string         `json:"machine_id"`
	IdempotencyKey string         `json:"idempotency_key"`
	Status         TerminalStatus `json:"status"`
	ResultDigest   string         `json:"result_digest"`
	CommittedAt    time.Time      `json:"committed_at"`
}

TerminalReceipt is the single normalized outcome accepted for an attempt. ResultDigest identifies the bounded persisted terminal payload/output.

type TerminalStatus 

type TerminalStatus string
const (
	TerminalCompleted TerminalStatus = "completed"
	TerminalFailed    TerminalStatus = "failed"
	TerminalCanceled  TerminalStatus = "canceled"
)

type WorkerDirective 

type WorkerDirective string
const (
	DirectiveContinue WorkerDirective = "continue"
	DirectiveCancel   WorkerDirective = "cancel"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.