queue

package
v0.7.12 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
const DriverRiver = "river"

DriverRiver is the driver name Open accepts (config queue.driver).

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

type Handler func(ctx context.Context, job Job) error

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 Job

type Job struct {
	ID      uuid.UUID
	Kind    string
	Queue   string
	Args    json.RawMessage
	Attempt int
}

Job is a claimed unit of work handed to a Handler.

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

func (c *RiverClient) CountWaiting(ctx context.Context, kind string) (int64, error)

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.

func (*RiverClient) Work

func (c *RiverClient) Work(ctx context.Context, queues ...string) error

Work runs jobs from the queues until ctx is cancelled, then stops gracefully: no new fetches, running jobs finish within stopGrace, after which they are cancelled.

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.

func Open

func Open(driver string, maxWorkers int, st *store.Store, log *slog.Logger) (Worker, error)

Open returns the driver named by the configuration: River, the only one. The former "pg" driver name is refused with a pointer to river. maxWorkers is how many jobs one process runs at once per queue.

Jump to

Keyboard shortcuts

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