Documentation
¶
Overview ¶
Package workertasks is the shared mechanism for work a worker claims, holds under a lease, may run in several slices with server-held state in between, and reports back (spec 2026-10-22-02). Every kind (crawl, discovery chunks) rides the same table, lease, fencing rules and agent protocol.
The worker pulls, the server never pushes. Cloud workers call the Service in-process; agents call it over signed HTTP (handlers/agenttasks). The server owns the state: a worker receives it in the claim and sends the next one back with the step, and nothing but this service writes it.
Index ¶
- Constants
- Variables
- type CancelFilter
- type Claim
- type ClaimRequest
- type FailRequest
- type HeartbeatResponse
- type Prepared
- type Service
- func (s *Service) Cancel(ctx context.Context, filter CancelFilter) (int, error)
- func (s *Service) Claim(ctx context.Context, identity *WorkerIdentity) (*Claim, error)
- func (s *Service) Create(ctx context.Context, task *models.WorkerTask) error
- func (s *Service) CreateIfNone(ctx context.Context, idb bun.IDB, task *models.WorkerTask) (bool, error)
- func (s *Service) FailSlice(ctx context.Context, uid, worker, errorCode string) error
- func (s *Service) Finish(ctx context.Context, uid, worker string, body json.RawMessage) error
- func (s *Service) Get(ctx context.Context, uid string) (*models.WorkerTask, error)
- func (s *Service) Heartbeat(ctx context.Context, uid, worker string) (time.Time, error)
- func (s *Service) KnownKinds(requested []string) []string
- func (s *Service) RegisterKind(kind TaskKind)
- func (s *Service) SetStateStore(store StateStore)
- func (s *Service) Step(ctx context.Context, uid, worker string, req StepRequest) error
- type StateStore
- type StepRequest
- type TaskKind
- type WorkerIdentity
Constants ¶
const ( // LeaseDuration is how long a claim or a heartbeat holds a task. LeaseDuration = 2 * time.Minute // MaxAttempts is how many claims a slice gets: the claim that would be // the next one fails the task with ErrorMaxAttempts instead. MaxAttempts = 3 // MaxSliceFailures is how many failed slices in a row fail the task. MaxSliceFailures = 3 // SliceRetryDelay is how long a failed slice waits before its next claim. SliceRetryDelay = time.Minute // MaxProgressBytes caps the progress summary a worker sends with a slice. MaxProgressBytes = 16 * 1024 )
Timings and limits of the mechanism.
const ( // ErrorMaxAttempts is a task whose slice was claimed MaxAttempts times // without a report. ErrorMaxAttempts = "max_attempts" // ErrorStateMissing is a task whose state file cannot be read back. ErrorStateMissing = "state_missing" // ErrorSliceFailed is the code used when a worker reports a failure // without a valid code of its own. ErrorSliceFailed = "slice_failed" )
Error codes the mechanism writes on a failed task.
Variables ¶
var ( // ErrTaskGone means the task is not (or no longer) held by this worker: // another worker holds it, its lease expired, or it was canceled or // ended. The worker must stop: nothing was written. ErrTaskGone = errors.New("worker task gone") // ErrTooLarge means the state or the progress exceeds its cap. Nothing // was written. ErrTooLarge = errors.New("worker task state or progress too large") // ErrInvalidIdentity means the worker identity cannot claim anything. ErrInvalidIdentity = errors.New("invalid worker identity") // ErrInvalidTask means a task to create is malformed. ErrInvalidTask = errors.New("invalid worker task") // ErrInvalidState means the state sent with a step is not JSON. ErrInvalidState = errors.New("worker task state must be JSON") // ErrNoStateStore means the service was built without a state store. ErrNoStateStore = errors.New("worker task state store not configured") // ErrUnknownKind means no kind is registered under the task's name. ErrUnknownKind = errors.New("unknown worker task kind") // ErrCancelTask is what a kind's PrepareClaim returns (wrapped or not) // when the task has no reason to run any more (its check was paused or // deleted): the claim cancels it instead of handing it out. ErrCancelTask = errors.New("worker task no longer needed") )
Errors of the service.
Functions ¶
This section is empty.
Types ¶
type CancelFilter ¶
CancelFilter selects the tasks to cancel: those of one check or one job.
type Claim ¶
type Claim struct {
UID string `json:"uid"`
Kind string `json:"kind"`
OrganizationUID string `json:"organizationUid"`
Region string `json:"region"`
CheckUID string `json:"checkUid,omitempty"`
JobUID string `json:"jobUid,omitempty"`
Slice int `json:"slice"`
Attempt int `json:"attempt"`
LeaseUntil time.Time `json:"leaseUntil"`
Input json.RawMessage `json:"input,omitempty"`
State json.RawMessage `json:"state,omitempty"`
SliceBudgetMs int64 `json:"sliceBudgetMs,omitempty"`
Units int `json:"units,omitempty"`
Final bool `json:"final,omitempty"`
}
Claim is what a worker receives for one slice. It is also the wire body of POST /api/v1/agent/tasks/claim.
type ClaimRequest ¶
type ClaimRequest struct {
Kinds []string `json:"kinds"`
}
ClaimRequest is the body of POST /api/v1/agent/tasks/claim.
type FailRequest ¶
type FailRequest struct {
ErrorCode string `json:"errorCode"`
}
FailRequest is a failed slice's report.
type HeartbeatResponse ¶
HeartbeatResponse is the body of a successful heartbeat.
type Prepared ¶
type Prepared struct {
// Input is the kind's input for the worker. Nil sends the task payload.
Input json.RawMessage
// SliceBudget is how long the slice may run.
SliceBudget time.Duration
// Units is how much work the slice may do (pages, hosts...).
Units int
// Final asks the worker to finish in this slice.
Final bool
// DeferUntil, when set, releases the claim without counting an attempt
// and moves the task's not_before to this time.
DeferUntil *time.Time
}
Prepared is what a kind adds to a claim.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the server side of worker tasks.
func NewService ¶
NewService builds the service over the database.
func (*Service) Cancel ¶
Cancel moves the pending and claimed tasks of a check or a job to WorkerTaskStatusCancelled, runs their kind's End hook and returns how many it changed. A worker still running one gets ErrTaskGone on its next call.
func (*Service) Claim ¶
Claim takes one task for the worker, or returns nil when there is none.
One atomic statement takes the oldest eligible row: a kind in Kinds, the worker's exact region, the agent's org (agents only), not_before reached, pending or claimed under an expired lease, and the worker holding fewer live leases than Slots. Postgres locks the candidate FOR UPDATE SKIP LOCKED; SQLite runs the same UPDATE … WHERE uid = (SELECT … LIMIT 1) RETURNING.
func (*Service) Create ¶
Create inserts a pending task. A check's stale active task (untouched for models.WorkerTaskStaleAfter) is failed first, so lazy expiry never blocks a new run; a live one makes the insert fail on the one-active-run index.
func (*Service) CreateIfNone ¶
func (s *Service) CreateIfNone(ctx context.Context, idb bun.IDB, task *models.WorkerTask) (bool, error)
CreateIfNone is Create on idb (a claim's transaction) that reports false, without an error, when the check already has a live active task.
func (*Service) FailSlice ¶
FailSlice records a failed slice. MaxSliceFailures in a row fail the task (and run the kind's Fail hook); otherwise it goes back to pending and waits SliceRetryDelay.
func (*Service) Finish ¶
Finish hands a finished task's body to its kind's Complete hook, then marks it done, or failed with the code the hook returns.
func (*Service) Get ¶
Get returns a task as readers see it: a stale active task reads as failed with models.WorkerTaskErrorExpired (lazy expiry, there is no sweeper).
func (*Service) KnownKinds ¶
KnownKinds intersects requested kinds with the registry, without duplicates. A kind the server does not know is ignored, never an error: an agent newer than its server may run kinds this server has not heard of.
func (*Service) RegisterKind ¶
RegisterKind registers (or replaces) a kind's server hooks.
func (*Service) SetStateStore ¶
func (s *Service) SetStateStore(store StateStore)
SetStateStore installs the state store. Set once at startup.
type StateStore ¶
type StateStore interface {
PutTaskState(ctx context.Context, orgUID, taskUID string, envelope []byte, details models.JSONMap) (string, error)
ReadTaskState(ctx context.Context, orgUID, taskUID, fileUID string) ([]byte, error)
PurgeTaskState(ctx context.Context, orgUID, taskUID string) error
}
StateStore keeps the state a task carries between slices. The attachment rail implements it (tasks/<uid>/step-state, keep 2).
type StepRequest ¶
type StepRequest struct {
State json.RawMessage `json:"state"`
Progress models.JSONMap `json:"progress,omitempty"`
Units int `json:"units,omitempty"`
}
StepRequest is a non-final slice's report.
type TaskKind ¶
type TaskKind struct {
// Name is the kind, as stored in worker_tasks.kind.
Name string
// Materialize creates the kind's due tasks for the claiming worker, in
// the claim's transaction and before a row is selected, so a worker
// asking for the kind may get a task created by its own claim. Optional.
Materialize func(ctx context.Context, tx bun.IDB, identity *WorkerIdentity) error
// PrepareClaim builds what the claiming worker (identity) needs from the
// task and its decoded state (nil on the first slice). Optional.
PrepareClaim func(
ctx context.Context, task *models.WorkerTask, identity *WorkerIdentity, state json.RawMessage,
) (*Prepared, error)
// Complete validates and persists a finished task's result. A non-empty
// error code marks the task failed with it (the kind already recorded the
// failure, Fail is not called). Optional: nil marks the task done.
Complete func(ctx context.Context, task *models.WorkerTask, body json.RawMessage) (errorCode string, err error)
// Fail records a terminal failure decided by the mechanism (attempts,
// slice failures, missing state). Optional.
Fail func(ctx context.Context, task *models.WorkerTask, errorCode string) error
// Step runs after a non-final slice was recorded, with the task as it
// was claimed (UnitsGranted is the slice's grant). Optional, best-effort:
// its error is logged.
Step func(ctx context.Context, task *models.WorkerTask, req StepRequest) error
// End runs once the task reached a terminal status (done, failed or
// canceled), after Complete or Fail. Optional, best-effort.
End func(ctx context.Context, task *models.WorkerTask)
}
TaskKind is the server side of a kind.