jobs

type Client struct {
	*river.Client[pgx.Tx]
}

type Config struct {
	OutboundWorkers    int // QueueOutbound concurrency (default 8)
	InboundWorkers     int // QueueInbound concurrency (default 8)
	WebhookWorkers     int // QueueWebhook concurrency (default 16)
	MaintenanceWorkers int // QueueMaintenance concurrency (default 2)
	NotifyWorkers      int // QueueNotify concurrency (default 4)
	DefaultWorkers     int // QueueDefault concurrency (default 5)
}

type Enqueuer interface {
	Insert(ctx context.Context, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
	InsertTx(ctx context.Context, tx pgx.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
}

type QueueStatsArgs struct{}

type QueueStatsJobs struct {
	// contains filtered or unexported fields
}

type QueueStatsMetrics interface {
	SetQueueDepth(queue, state string, n int)
	SetQueueOldestAge(queue string, seconds float64)
}

type QueueStatsWorker struct {
	river.WorkerDefaults[QueueStatsArgs]
	// contains filtered or unexported fields
}

type ReconcileResult struct {
	Enqueued int
	Rescued  int
}

type ReconcileSpec struct {
	// Table is the row table (e.g. "messages", "webhook_events").
	Table string
	// JobColumn is the nullable bigint column holding the enqueued River job id
	// (e.g. "send_job_id", "fanout_job_id"). A row is "stranded" when it matches
	// Where AND JobColumn IS NULL (plus, with RescueDeadJobs, when its stamped
	// job is dead — see below).
	JobColumn string
	// Where is the domain predicate identifying rows that SHOULD carry a job
	// (e.g. "direction='outbound' AND delivery_status='accepted'"). ANDed with
	// the strandedness condition; pass no leading/trailing "AND". Every query
	// binds the row table to the alias `t`, so unqualified column names resolve
	// to it — but with RescueDeadJobs the queries also join river_job as `r`, so
	// qualify any column whose name river_job shares (id, state, kind, queue,
	// attempt, ...) as t.<col> to avoid ambiguity.
	Where string
	// LogPrefix tags per-row enqueue-failure logs (e.g. "[outbound-reconcile]").
	LogPrefix string
	// Batch caps rows scanned per pass; 0 uses DefaultReconcileBatch.
	Batch int
	// RescueDeadJobs additionally treats a row as stranded when JobColumn IS NOT
	// NULL but the stamped river_job no longer exists (pruned by River's reaper)
	// or is in a terminal state (cancelled/discarded/completed) — a job that can
	// never run again while the row still matches Where. Same "job is dead,
	// reconcile the row" test as outboundsend's TerminalReconcileWorker, but the
	// remedy here is RE-DRIVING (fresh job, re-stamped id), so it is OPT-IN:
	// only set it when re-running the work is both idempotent and desired.
	// outboundsend, for example, must NOT re-enqueue a discarded send job (its
	// terminal reconciler settles those rows as sent/failed instead — re-driving
	// would resend email); the webhook pipeline's fan-out and delivery rows DO
	// want re-driving, because their at-least-once contract already tolerates it.
	//
	// Cost note: the dead-job scan cannot use the JobColumn-IS-NULL partial
	// indexes; it walks the rows matching Where with a stamped job (the in-flight
	// set) and probes river_job by primary key per row. Callers' Where predicates
	// keep that set small and TTL-bounded; the plain IS NULL scan still runs
	// first and stays index-backed. That ordering is also a prioritization: the
	// IS NULL strand (work that never got a job) fills the batch before dead-job
	// strands are even scanned, so under an IS-NULL backlog that saturates every
	// tick's batch, dead-job rescues wait until that backlog drains.
	RescueDeadJobs bool
	// RescueWhere optionally narrows the dead-job arm ONLY (scan + per-row
	// re-check); the IS NULL arm is unaffected. ANDed with the dead-job
	// condition; empty = no extra gate. Use it to age-gate the rescue so the
	// per-tick scan doesn't churn on rows whose jobs are plausibly still live —
	// e.g. webhookdelivery gates on quiet-for-longer-than-the-retry-envelope.
	// Same alias rules and SECURITY contract as Where.
	RescueWhere string
}

type Registrar interface {
	RegisterJobs(w *river.Workers) []*river.PeriodicJob
}