workertasks

package
v0.0.0-...-1cad98a Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

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

View Source
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.

View Source
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

View Source
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

type CancelFilter struct {
	CheckUID string
	JobUID   string
}

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

type HeartbeatResponse struct {
	LeaseUntil time.Time `json:"leaseUntil"`
}

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

func NewService(db bun.IDB) *Service

NewService builds the service over the database.

func (*Service) Cancel

func (s *Service) Cancel(ctx context.Context, filter CancelFilter) (int, error)

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

func (s *Service) Claim(ctx context.Context, identity *WorkerIdentity) (*Claim, error)

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

func (s *Service) Create(ctx context.Context, task *models.WorkerTask) error

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

func (s *Service) FailSlice(ctx context.Context, uid, worker, errorCode string) error

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

func (s *Service) Finish(ctx context.Context, uid, worker string, body json.RawMessage) error

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

func (s *Service) Get(ctx context.Context, uid string) (*models.WorkerTask, error)

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) Heartbeat

func (s *Service) Heartbeat(ctx context.Context, uid, worker string) (time.Time, error)

Heartbeat extends the worker's lease and returns its new end.

func (*Service) KnownKinds

func (s *Service) KnownKinds(requested []string) []string

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

func (s *Service) RegisterKind(kind TaskKind)

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.

func (*Service) Step

func (s *Service) Step(ctx context.Context, uid, worker string, req StepRequest) error

Step records a non-final slice: the next state (stored as an attachment, 1 MiB cap), the progress, and puts the task back to pending for its next slice, with the lease cleared.

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.

type WorkerIdentity

type WorkerIdentity struct {
	UID     string
	Region  string
	OrgUID  string
	IsAgent bool
	Kinds   []string
	Slots   int
}

WorkerIdentity is who claims. A cloud worker serves every org of its region; an agent only its own org (OrgUID) in its exact region.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址