Documentation
¶
Overview ¶
Package task defines Modary's bounded durable background-work contract.
The official PostgreSQL adapter implements this contract with River, but consumers do not depend on River or PostgreSQL types. Delivery is at least once: handlers must use stable job identity and idempotent external effects.
Index ¶
Constants ¶
const ( // MaxPayloadBytes bounds one serialized task payload. MaxPayloadBytes = 1 << 20 // DefaultQueue is used when Request.Queue is empty. DefaultQueue = "default" // DefaultMaxAttempts is used when Request.MaxAttempts is zero. DefaultMaxAttempts = 3 // DefaultMaxWorkers is used when Queue.MaxWorkers is zero. DefaultMaxWorkers = 10 // MinimumRetryDelay keeps a custom retry scheduled strictly in the future. MinimumRetryDelay = time.Millisecond // MaximumRetryDelay bounds declarative per-runner retry configuration. MaximumRetryDelay = 30 * 24 * time.Hour // DefaultListLimit bounds one operational inspection page by default. DefaultListLimit = 50 // MaxListLimit is the largest operational inspection page. MaxListLimit = 100 )
Variables ¶
var ( ErrUnavailable = errors.New("task service is unavailable") // ErrTransactionRequired reports enqueue outside a governed Action transaction. ErrTransactionRequired = errors.New("task enqueue requires a governed transaction") )
Functions ¶
This section is empty.
Types ¶
type HandlerFunc ¶
HandlerFunc adapts a function to Handler.
type Inspector ¶
type Inspector interface {
List(context.Context, ListOptions) (Page, error)
}
Inspector reads bounded task metadata without exposing a queue backend or mutation authority.
type Job ¶
type Job struct {
ID int64
Kind string
Payload json.RawMessage
Queue string
Attempt int
MaxAttempts int
}
Job is the framework-neutral task value supplied to a Handler.
func (Job) TerminalAttempt ¶
TerminalAttempt reports whether the current attempt is the last configured attempt. It is useful when a product must persist its own terminal status.
type ListOptions ¶
ListOptions selects one descending task page. BeforeID is the exclusive cursor returned by the previous Page.
func NormalizeListOptions ¶
func NormalizeListOptions(options ListOptions) (ListOptions, error)
NormalizeListOptions validates one provider-neutral inspection query.
type Page ¶
type Page struct {
Tasks []Summary `json:"tasks"`
NextBeforeID int64 `json:"next_before_id,omitempty,string"`
}
Page is one bounded operational task result.
type Request ¶
type Request struct {
Kind string
Payload json.RawMessage
Queue string
MaxAttempts int
ScheduledAt time.Time
UniqueKey string
}
Request describes one durable task insertion. UniqueKey is optional. When present, an equivalent logical kind and key are inserted at most once while River's active uniqueness states apply.
func NormalizeRequest ¶
NormalizeRequest validates and defensively copies one enqueue request. It is public so adapter and consumer contract tests use the same rules.
type Runner ¶
type Runner interface {
Start(context.Context) error
Stop(context.Context) error
Stopped() <-chan struct{}
}
Runner owns one immutable worker process lifecycle.
type RunnerOptions ¶
type RunnerOptions struct {
Queues []Queue
JobTimeout time.Duration
SoftStopTimeout time.Duration
// RetryDelays optionally replaces River's default retry schedule. Entry zero
// follows the first failed attempt; attempts beyond the list reuse its last
// value. An empty list selects the adapter default.
RetryDelays []time.Duration
}
RunnerOptions freezes runner behavior before it starts.
func NormalizeRunnerOptions ¶
func NormalizeRunnerOptions(options RunnerOptions) (RunnerOptions, error)
NormalizeRunnerOptions validates and defensively copies runner options.
type Service ¶
type Service interface {
Enqueue(context.Context, Request) (Receipt, error)
NewRunner(Handler, RunnerOptions) (Runner, error)
}
Service inserts tasks and constructs immutable runners.
type State ¶
type State string
State is the provider-neutral lifecycle state exposed by task inspection. Queue implementations map their internal states into this closed contract.
const ( // StateQueued is ready for a worker to claim. StateQueued State = "queued" // StatePending is accepted but not yet eligible to run. StatePending State = "pending" // StateScheduled is waiting for its scheduled time. StateScheduled State = "scheduled" // StateRunning is currently executing. StateRunning State = "running" // StateRetrying is waiting for another attempt after failure. StateRetrying State = "retrying" // StateSucceeded completed successfully. StateSucceeded State = "succeeded" // StateFailed reached a terminal failure. StateFailed State = "failed" // StateCancelled was cancelled before successful completion. StateCancelled State = "cancelled" )
type Summary ¶
type Summary struct {
ID int64 `json:"id,string"`
Kind string `json:"kind"`
Queue string `json:"queue"`
State State `json:"state"`
Attempt int `json:"attempt"`
MaxAttempts int `json:"max_attempts"`
ScheduledAt time.Time `json:"scheduled_at"`
CreatedAt time.Time `json:"created_at"`
FinalizedAt *time.Time `json:"finalized_at,omitempty"`
}
Summary is provider-neutral operational task metadata. Payloads and backend error details are deliberately excluded from the Admin inspection surface.
Source Files