Documentation
¶
Overview ¶
Package queue claims due rows from a PostgreSQL job table in batches and fences the owner with a lease epoch. Client, in client.go, is a River-backed durable queue for work enqueued from application transactions.
A job table claimed by Queue has these columns:
id bigint primary key priority integer lower is claimed first next_due timestamptz the row is due when next_due <= now() state text 'pending' before a claim, 'claimed' after lease_epoch bigint bumped on every claim; the owner's fencing token
ClaimN runs one statement, so it is its own transaction: the subquery locks the rows it picks with FOR UPDATE SKIP LOCKED and the update claims exactly those rows. Settle and Fail run on the caller's *sql.DB, each on a pooled connection.
Fencing: ClaimN returns each row's new lease_epoch. Settle and Fail only update the row while state = 'claimed' AND lease_epoch = the caller's epoch, so an owner whose lease was reclaimed (or who settles twice) reports ErrStale and must stop touching the row.
Index ¶
- Constants
- Variables
- func Every(d time.Duration) river.PeriodicSchedule
- func Idempotent(base *river.InsertOpts) *river.InsertOpts
- func JobsDDL(table string) (string, error)
- func Migrate(ctx context.Context, db *sql.DB, schema string) error
- func PeriodicJob(p Periodic) *river.PeriodicJob
- type Backoff
- type Claimed
- type Client
- func (c *Client) AddPeriodic(p Periodic) error
- func (c *Client) InsertMany(ctx context.Context, jobs []river.InsertManyParams) ([]*rivertype.JobInsertResult, error)
- func (c *Client) InsertManyTx(ctx context.Context, tx *sql.Tx, jobs []river.InsertManyParams) ([]*rivertype.JobInsertResult, error)
- func (c *Client) InsertTx(ctx context.Context, tx *sql.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
- func (c *Client) Start(ctx context.Context) error
- func (c *Client) Stop(ctx context.Context) error
- type Config
- type Depth
- type Filter
- type Job
- type Jobs
- func (j *Jobs) Claim(ctx context.Context, limit int, f Filter) ([]Job, error)
- func (j *Jobs) Complete(ctx context.Context, id, epoch int64, result json.RawMessage) error
- func (j *Jobs) DeadLetters(ctx context.Context, limit int) ([]Job, error)
- func (j *Jobs) Depth(ctx context.Context) (Depth, error)
- func (j *Jobs) Enqueue(ctx context.Context, n NewJob) (job Job, created bool, err error)
- func (j *Jobs) Fail(ctx context.Context, id, epoch int64, cause error) (string, error)
- func (j *Jobs) Heartbeat(ctx context.Context, id, epoch int64) error
- func (j *Jobs) Reap(ctx context.Context) (int64, error)
- func (j *Jobs) Requeue(ctx context.Context, id int64) error
- func (j *Jobs) Stuck(ctx context.Context, grace time.Duration, limit int) ([]Job, error)
- func (j *Jobs) Throughput(ctx context.Context, window time.Duration) (Throughput, error)
- type JobsConfig
- type NewJob
- type Periodic
- type Queue
- type Schema
- type Throughput
Constants ¶
const ( // DefaultLease is how long a job may stay running before the leader // treats its worker as dead and reschedules it. DefaultLease = 5 * time.Minute // DefaultMaxAttempts is how many times a job runs before it is dead. DefaultMaxAttempts = 8 // DefaultBackoffBase is the delay after the first failed attempt. DefaultBackoffBase = 5 * time.Second // DefaultBackoffMax caps the delay between attempts. DefaultBackoffMax = 15 * time.Minute // DefaultWorkers is the concurrent jobs per client on the default queue. DefaultWorkers = 10 )
Default tuning for Client. Every value can be overridden in Config.
const ( StatePending = "pending" StateRunning = "running" StateDone = "done" StateDead = "dead" )
Job states. Dead is the dead-letter state.
const Dead = rivertype.JobStateDiscarded
Dead is the state of a job that used all its attempts. Dead jobs are kept for inspection and are never run again.
const MaxBatch = 1000
MaxBatch caps ClaimN's n. Rows claimed together share one owner, so larger batches amortize the round trip at the cost of a coarser split between claimers.
Variables ¶
var Default = Schema{ Table: "job", ID: "id", Priority: "priority", NextDue: "next_due", State: "state", Epoch: "lease_epoch", Pending: "pending", Claimed: "claimed", }
Default is the schema documented on the package, on table "job".
var ErrStale = errors.New("queue: lease is stale; the row was reclaimed or settled")
ErrStale reports that Settle or Fail no longer owns the row: it was reclaimed and claimed by another owner, settled, or already failed.
Functions ¶
func Every ¶
func Every(d time.Duration) river.PeriodicSchedule
Every is a periodic schedule that fires every d after the previous run.
func Idempotent ¶
func Idempotent(base *river.InsertOpts) *river.InsertOpts
Idempotent returns insert options under which a second insert of the same job is skipped for as long as the first one is pending, running, retrying, scheduled or completed (completed rows live until River's cleaner removes them, 24 hours by default).
A job is identified by its args: tag the field that carries the idempotency key with `river:"unique"` and only tagged fields are compared; with no tag the whole args value is. Dead and cancelled jobs do not block a new insert. base may be nil.
func JobsDDL ¶
JobsDDL returns the statements that create the job table and its indexes for the named relation, for use in a migration. The table may be schema-qualified.
func Migrate ¶
Migrate brings River's tables in schema (empty for the search path) up to date. It is idempotent and safe to run from several processes at once. Client.Start calls it unless SkipMigrate is set.
func PeriodicJob ¶
func PeriodicJob(p Periodic) *river.PeriodicJob
PeriodicJob converts p for Config.Periodic.
Types ¶
type Backoff ¶
Backoff is a bounded exponential retry policy: the delay after attempt n is Base * 2^(n-1), never more than Max. It plugs into River as the client's retry policy.
type Claimed ¶
type Claimed struct {
// ID is the row's key.
ID int64
// Epoch is the row's lease_epoch after the claim; pass it to Settle and
// Fail. It is strictly larger than any epoch a previous owner held.
Epoch int64
}
Claimed is one row handed to a claimer by ClaimN.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a River client over database/sql. Jobs are inserted with the caller's transaction, workers claim them with row locks that never block other workers, and the elected leader runs maintenance: scheduling, rescuing stuck jobs, and cleaning finished ones. It is safe for concurrent use.
func (*Client) AddPeriodic ¶
AddPeriodic registers p on a running or stopped client. Only the leader enqueues it.
func (*Client) InsertMany ¶
func (c *Client) InsertMany(ctx context.Context, jobs []river.InsertManyParams) ([]*rivertype.JobInsertResult, error)
InsertMany enqueues jobs in one transaction of its own. Use InsertManyTx when the jobs must commit with other changes.
func (*Client) InsertManyTx ¶
func (c *Client) InsertManyTx(ctx context.Context, tx *sql.Tx, jobs []river.InsertManyParams) ([]*rivertype.JobInsertResult, error)
InsertManyTx enqueues jobs in the caller's transaction. Jobs whose opts set UniqueOpts and match an existing job are skipped; the matching result has UniqueSkippedAsDuplicate set. Results are in input order. One batch must not contain the same unique key twice: PostgreSQL rejects the statement.
func (*Client) InsertTx ¶
func (c *Client) InsertTx(ctx context.Context, tx *sql.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
InsertTx enqueues a job in the caller's transaction. The job exists only if tx commits, and workers cannot see it before then.
type Config ¶
type Config struct {
// DB is the pool River works on and migrates. It must be a PostgreSQL
// database/sql pool; the caller owns it and closes it after Stop.
DB *sql.DB
// Workers registers the job kinds this client runs. Leave nil for an
// insert-only client that is never started.
Workers *river.Workers
// Workers per queue. Nil means river.QueueDefault with DefaultWorkers.
Queues map[string]river.QueueConfig
// Lease is how long a running job may go without finishing before it is
// rescued: retried with backoff, or dead when attempts are used up. Set
// it above the longest legitimate job; a job that outlives its lease can
// run twice. The per-job timeout is set to nine tenths of the lease, so a
// job is cancelled before it can be rescued. Zero means DefaultLease.
Lease time.Duration
// MaxAttempts per job, including the first run. Zero means
// DefaultMaxAttempts. A job's own InsertOpts.MaxAttempts wins.
MaxAttempts int
// BackoffBase and BackoffMax shape the retry delay, see Backoff. Zero
// means DefaultBackoffBase and DefaultBackoffMax.
BackoffBase time.Duration
BackoffMax time.Duration
// Periodic jobs are enqueued by the leader only, so a fleet of clients
// inserts each occurrence once.
Periodic []*river.PeriodicJob
// NoLeader keeps this client out of leader election: it works jobs but
// never runs maintenance, rescue or periodic enqueues. Use it for clients
// with a partial worker set. Periodic must be empty when it is set.
NoLeader bool
// SkipMigrate stops Start from applying River's schema migrations. Set it
// when the role keel runs as cannot create tables and Migrate runs
// elsewhere.
SkipMigrate bool
// Schema is the PostgreSQL schema holding River's tables. It must already
// exist. Empty means the connection's search path, normally public.
Schema string
// FetchPollInterval and FetchCooldown tune how often idle workers look
// for new jobs. Zero keeps River's defaults.
FetchPollInterval time.Duration
FetchCooldown time.Duration
// Logger receives River's logs. Nil discards them.
Logger *slog.Logger
}
Config configures a Client. Only DB is required.
type Depth ¶
type Depth struct {
// Ready are pending jobs whose run_at has passed.
Ready int64
// Delayed are pending jobs waiting for run_at, including retry backoff.
Delayed int64
Running int64
Done int64
Dead int64
}
Depth counts jobs by state.
type Filter ¶
type Filter struct {
// Kinds limits the claim to these kinds; empty means every kind.
Kinds []string
}
Filter narrows what Claim considers.
type Job ¶
type Job struct {
ID int64
Kind string
Payload json.RawMessage
IdempotencyKey string
State string
// Attempts counts claims, including the current one.
Attempts int
MaxAttempts int
// Epoch is the lease epoch; pass it to Heartbeat, Complete and Fail.
Epoch int64
RunAt time.Time
LeaseExpiresAt time.Time
Result json.RawMessage
LastError string
CreatedAt time.Time
FinishedAt time.Time
}
Job is one row of the job table.
type Jobs ¶
type Jobs struct {
// contains filtered or unexported fields
}
Jobs is a job queue over one table: enqueue with idempotency, batched claims with SKIP LOCKED, leases with heartbeats, retry with exponential backoff and a dead-letter state. Every transition after a claim is fenced on the lease epoch, so a worker that lost its lease gets ErrStale. It is safe for concurrent use.
func NewJobs ¶
func NewJobs(db *sql.DB, cfg JobsConfig) (*Jobs, error)
NewJobs returns Jobs over db. It does not reach the database.
func (*Jobs) Claim ¶
Claim leases up to max due jobs for LeaseTTL: pending jobs whose run_at has passed, and running jobs whose lease expired (a crashed or stalled worker), provided attempts remain. It first dead-letters expired jobs that have none left. Concurrent claimers get disjoint sets. max is clamped to 1..MaxBatch.
func (*Jobs) Complete ¶
Complete marks the job done and stores result, which must be valid JSON or empty. It returns ErrStale if the caller no longer holds the lease; a second Complete of the same lease is stale.
func (*Jobs) DeadLetters ¶
DeadLetters lists up to limit dead jobs, most recently dead first.
func (*Jobs) Enqueue ¶
Enqueue adds a job. With an IdempotencyKey, a job of the same Kind and key that already exists is returned unchanged and created is false; concurrent enqueues of one key add exactly one row.
func (*Jobs) Fail ¶
Fail records cause and releases the job. While attempts remain it is retried after BackoffBase * 2^(attempts-1), capped at BackoffMax; once Attempts reaches MaxAttempts it becomes dead. It returns the new state, StatePending or StateDead, or ErrStale if the caller no longer holds the lease.
func (*Jobs) Heartbeat ¶
Heartbeat extends the lease of a claimed job by LeaseTTL. It returns ErrStale if the job was reclaimed, completed or failed.
func (*Jobs) Reap ¶
Reap moves running jobs whose lease expired on their final attempt to the dead-letter state and returns how many it moved. Claim calls it; call it on a timer too if nothing claims for long stretches.
func (*Jobs) Requeue ¶
Requeue returns a dead job to pending with its attempts reset. It returns ErrStale if the job is not dead.
func (*Jobs) Stuck ¶
Stuck lists up to limit running jobs whose lease expired more than grace ago and that nothing has reclaimed: the workers are gone and no claimer is polling, or the job has no attempts left and Reap has not run.
func (*Jobs) Throughput ¶
Throughput counts jobs completed or dead-lettered in the last window.
type JobsConfig ¶
type JobsConfig struct {
// Table is the relation name; default "queue_job".
Table string
// LeaseTTL is how long a claim or heartbeat keeps a job; default 30s. A
// running job whose lease has expired is reclaimed by the next Claim.
LeaseTTL time.Duration
// DefaultMaxAttempts applies to jobs enqueued without MaxAttempts; default 5.
DefaultMaxAttempts int
// BackoffBase is the retry delay after the first failed attempt; each
// further attempt doubles it. Default 1s.
BackoffBase time.Duration
// BackoffMax caps the retry delay; default 1h.
BackoffMax time.Duration
}
JobsConfig configures Jobs. Zero fields take the documented default.
type NewJob ¶
type NewJob struct {
Kind string
Payload json.RawMessage // JSON; empty means {}
// IdempotencyKey, when set, makes Enqueue return the existing job for
// the same Kind and key instead of adding another.
IdempotencyKey string
// MaxAttempts overrides JobsConfig.DefaultMaxAttempts when positive.
MaxAttempts int
// RunAt delays the first claim; zero means now.
RunAt time.Time
}
NewJob describes a job to enqueue.
type Periodic ¶
type Periodic struct {
// ID names the schedule; it must be unique per client.
ID string
// Schedule says when to fire. Use Every, or any river.PeriodicSchedule
// such as one backed by a cron parser.
Schedule river.PeriodicSchedule
// Make builds the job for one occurrence.
Make func() (river.JobArgs, *river.InsertOpts)
// RunOnStart also enqueues one occurrence when a leader starts, so a long
// interval does not wait for the first tick after a failover.
RunOnStart bool
}
Periodic describes cron-style work: Make is called each time the schedule fires and returns the job to enqueue.
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue claims, settles and fails rows of one job table on one pool. It is safe for concurrent use.
func New ¶
New returns a Queue over db that uses Default. It does not reach the database; the table is checked by the first statement.
func NewWithSchema ¶
NewWithSchema returns a Queue over db for the named schema. Fields left zero take their Default value.
func (*Queue) ClaimN ¶
ClaimN claims up to n due rows, in one statement and therefore one transaction: highest priority first (lowest priority value, then earliest next_due, then lowest id). Each returned row has state = Claimed and an epoch one larger than before.
Rows another claimer holds at the same moment are skipped, so concurrent claimers on one table get disjoint batches without waiting on each other. ClaimN returns fewer than n rows, possibly zero, when fewer than n rows are due. n is clamped to 1..MaxBatch; the returned slice is not ordered.
func (*Queue) Fail ¶
Fail returns the row to pending so it is claimed again after backoff, and retires the lease. It succeeds only while the row is still claimed at epoch; otherwise it returns ErrStale and changes nothing. A negative backoff is treated as zero, which makes the row due immediately.
type Schema ¶
type Schema struct {
// Table is the relation name, optionally schema-qualified ("schema.job").
Table string
// ID is the bigint key column.
ID string
// Priority orders claims; lower is claimed first.
Priority string
// NextDue is the timestamptz column; a row is due once it has passed.
NextDue string
// State is the text column holding Pending or Claimed.
State string
// Epoch is the bigint lease column; every claim adds one.
Epoch string
// Pending is the state of a row waiting to be claimed. ClaimN only
// considers rows in this state.
Pending string
// Claimed is the state ClaimN sets and Settle and Fail require.
Claimed string
}
Schema names the table, columns and states Queue reads and writes. The zero value is the schema in the package documentation, on table "job".