Documentation
¶
Overview ¶
Package task defines the core Task record and its lifecycle.
Index ¶
Constants ¶
const DefaultMaxAttempts = 3
DefaultMaxAttempts is used when New.MaxAttempts is zero.
Variables ¶
var ( // ErrNotFound is returned when a task ID does not exist. ErrNotFound = errors.New("task: not found") // ErrLeaseNotHeld is returned when completing/failing/heartbeating a task // whose lease is owned by someone else or already expired. ErrLeaseNotHeld = errors.New("task: lease not held") // ErrDuplicateID is returned when enqueueing a task whose ID already exists. ErrDuplicateID = errors.New("task: duplicate id") // ErrInvalidTransition is returned by stores that validate transitions. ErrInvalidTransition = errors.New("task: invalid status transition") )
Functions ¶
func CanTransitionTo ¶
CanTransitionTo reports whether from → to is a legal lifecycle transition.
func StatusCountsMap ¶ added in v0.3.1
StatusCountsMap lifts per-status counts keyed by any string-based status type into the typed enum: the inverse of StatusCountsView's key direction. Store and read-model surfaces report counts as map[string]int; upstream-engine adapters hold a foreign ~string Status of their own — map invariance forbids assigning either map to map[string]int, so the key type is generic and both shapes convert through this helper instead of hand-rolling the same loop.
func StatusCountsView ¶ added in v0.3.1
StatusCountsView flattens per-status counts into the stats wire shape: a string-keyed map holding every known status (zeros included) plus the total. The HTTP stats surfaces (httpapi, webui) share one contract pinned by TestStatsSurfacesAgree; this is that contract's single source.
Types ¶
type ID ¶
type ID string
ID identifies a task. Opaque, unique, time-sortable: lexicographic ID order is creation order, including tasks minted within the same millisecond (the suffix carries a process-local monotonic sequence).
func NewID ¶
func NewID() ID
NewID returns a new unique task ID (timestamp prefix + monotonic suffix). IDs minted by this process are strictly increasing in lexicographic order, so sorting by ID is sorting by creation time — sweep windows and other ID-ordered views stay deterministic even when tasks share a millisecond.
type New ¶
type New struct {
Project string
Type string
Payload jsontext.Value
Deps []ID
Priority int
MaxAttempts int
NotBefore time.Time
// DedupKey, when set, makes Enqueue idempotent: if a task with the same
// key already exists, that task is returned unchanged and no duplicate is
// created. Use a stable derivation (e.g. hash of project + source + title)
// so repeated harvest runs converge instead of re-enqueueing.
DedupKey string
}
New is a task template for enqueueing. ID, Attempts, Status and timestamps are assigned by the store; everything else is caller-supplied.
type Status ¶
type Status string
Status is the task lifecycle state. Transitions are validated by CanTransitionTo.
const ( // Pending means the task is waiting to be claimed (possibly delayed via NotBefore). Pending Status = "pending" // Running means a worker holds the lease. Running Status = "running" // Completed means the task succeeded (terminal). Completed Status = "completed" // Dead means attempts were exhausted and the task is parked in the dead-letter queue (terminal). Dead Status = "dead" // Cancelled means the task was withdrawn before completion (terminal). Cancelled Status = "cancelled" )
func AllStatuses ¶ added in v0.3.0
func AllStatuses() []Status
AllStatuses returns every Status in lifecycle order (the single list other packages range over for enum-complete iteration). A function, not an exported slice var, so no caller can mutate the enum list for the whole process.
type Task ¶
type Task struct {
ID ID `json:"id"`
Project string `json:"project,omitempty"`
Type string `json:"type"`
Payload jsontext.Value `json:"payload,omitempty"`
Deps []ID `json:"deps,omitempty"`
Priority int `json:"priority,omitempty"`
Attempts int `json:"attempts"`
MaxAttempts int `json:"maxAttempts"`
NotBefore time.Time `json:"notBefore"`
Status Status `json:"status"`
LeaseOwner string `json:"leaseOwner,omitempty"`
LeaseExpires *time.Time `json:"leaseExpires,omitempty"`
LastError string `json:"lastError,omitempty"`
// DedupKey mirrors the tasks table column (empty when the task does
// not opt into idempotent enqueue). The journal-drift audit diffs it,
// so the row projection carries it like every other diffed field.
DedupKey string `json:"dedupKey,omitempty"`
CreatedAt time.Time `json:"createdAt"`
UpdatedAt time.Time `json:"updatedAt"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
}
Task is the unit of work: what to run, for which project, under which constraints.
Source Files