Documentation
¶
Overview ¶
Package queue is the async job abstraction. The interface is the commitment; the backend is River (river.go, Postgres-backed), behind Client without changing enqueue sites or handlers.
Index ¶
- Constants
- type Client
- type EnqueueOption
- type Handler
- type Job
- type RiverClient
- func (c *RiverClient) CountWaiting(ctx context.Context, kind string) (int64, error)
- func (c *RiverClient) Drain(ctx context.Context, queues ...string)
- func (c *RiverClient) Enqueue(ctx context.Context, kind, queueName string, args any, opts ...EnqueueOption) (uuid.UUID, error)
- func (c *RiverClient) Register(kind string, h Handler)
- func (c *RiverClient) RegisterRescueSettling()
- func (c *RiverClient) SetMetrics(m *metrics.Metrics, sampleEvery time.Duration)
- func (c *RiverClient) SetTestOnly(on bool)
- func (c *RiverClient) SettleRescued(ctx context.Context) (int, error)
- func (c *RiverClient) Work(ctx context.Context, queues ...string) error
- type Worker
Constants ¶
const DriverRiver = "river"
DriverRiver is the driver name Open accepts (config queue.driver).
const JobSettleRescued = "queue.settle_rescued"
JobSettleRescued is the periodic job that runs SettleRescued, on the core queue.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
Enqueue(ctx context.Context, kind, queueName string, args any, opts ...EnqueueOption) (uuid.UUID, error)
Register(kind string, h Handler)
Work(ctx context.Context, queues ...string) error
// CountWaiting counts the jobs of a kind that have not started: queued,
// scheduled for later, or waiting out a retry, in this driver's own
// table. A self-rescheduling job keeps one successor waiting and asks
// this before it enqueues another, so a restart or a stacked chain never
// adds one.
CountWaiting(ctx context.Context, kind string) (int64, error)
}
Client enqueues and (as a worker) runs jobs.
type EnqueueOption ¶
type EnqueueOption func(*enqueueConfig)
EnqueueOption customizes enqueue.
func WithDelay ¶
func WithDelay(d time.Duration) EnqueueOption
WithDelay schedules the job to run after d.
func WithMaxAttempts ¶
func WithMaxAttempts(n int) EnqueueOption
WithMaxAttempts overrides the retry budget.
type Handler ¶
Handler processes one job kind. Returning an error retries (with backoff) up to the job's max attempts, then the job is marked failed. Handlers MUST be idempotent: at-least-once delivery is the contract.
type RiverClient ¶
type RiverClient struct {
// contains filtered or unexported fields
}
RiverClient is the River-backed Client. River owns the job table (river_job), fetching, retries, the rescue of jobs a dead worker held and the per-queue concurrency; this type keeps the agentry contract on top of it: kind-string handlers, at-least-once delivery, the metrics and the backlog gauges the queue-age alarm reads.
func NewRiverClient ¶
func NewRiverClient(st *store.Store, log *slog.Logger) *RiverClient
NewRiverClient builds the River queue client. Register handlers, then Work (worker role) or only Enqueue (API role).
func (*RiverClient) CountWaiting ¶
CountWaiting counts the kind's jobs in river_job not yet started. It reads only river_job.
func (*RiverClient) Drain ¶
func (c *RiverClient) Drain(ctx context.Context, queues ...string)
Drain works the queues until nothing in them is ready or running, then stops (tests and one-shot drains). A retry scheduled for later is deliberately waiting and does not hold the drain.
func (*RiverClient) Enqueue ¶
func (c *RiverClient) Enqueue(ctx context.Context, kind, queueName string, args any, opts ...EnqueueOption) (uuid.UUID, error)
Enqueue durably records a job.
func (*RiverClient) Register ¶
func (c *RiverClient) Register(kind string, h Handler)
Register wires a handler for a job kind (before Work). Registering a kind twice replaces the handler.
func (*RiverClient) RegisterRescueSettling ¶
func (c *RiverClient) RegisterRescueSettling()
RegisterRescueSettling wires JobSettleRescued onto this client.
func (*RiverClient) SetMetrics ¶
func (c *RiverClient) SetMetrics(m *metrics.Metrics, sampleEvery time.Duration)
SetMetrics wires the instrument set and the backlog sample interval.
func (*RiverClient) SetTestOnly ¶
func (c *RiverClient) SetTestOnly(on bool)
SetTestOnly turns off River's production-only staggering (jittered maintenance start-up) so a test's Drain starts and stops promptly.
func (*RiverClient) SettleRescued ¶
func (c *RiverClient) SettleRescued(ctx context.Context) (int, error)
SettleRescued gives each job River's rescuer discarded at its last attempt the last attempt it never had, and reports how many it queued. The rescuer discards a stuck job already at MaxAttempts without calling its handler again, so the settling a handler does on its last attempt (fail the knowledge pack, audit and raise an abandoned erasure, queue the next link of a chain) would never run. Each such job is queued once more, in the same transaction that marks it settled, as a single attempt whose handler sees the job's own last attempt number. A final attempt that is itself rescued is not queued again: it is logged, and the job ends there.
type Worker ¶
type Worker interface {
Client
SetMetrics(m *metrics.Metrics, sampleEvery time.Duration)
Drain(ctx context.Context, queues ...string)
}
Worker is a Client that also runs jobs: what the worker role and the tests hold. RiverClient implements it.