Fields

• workerCount :: Int

  Number of concurrent worker threads.

• handlerMode :: HandlerMode m payload

  Job handler and claiming strategy. Set by this module's config constructors.

• pollInterval :: NominalDiffTime

  Cadence floor in seconds for the dispatcher poll. Default: 5.

• visibilityTimeout :: NominalDiffTime

  How long a claimed job stays invisible to other workers. Must be greater than jobHeartbeatInterval. Default: 60.

• jobHeartbeatInterval :: NominalDiffTime

  Interval for extending a job's visibility timeout during processing. Must be less than visibilityTimeout. Default: 30.

• maxJobDuration :: Maybe NominalDiffTime

  Interrupt a handler that runs longer than this. Default: Nothing, no bound.

• workerHeartbeatInterval :: NominalDiffTime

  Cadence for bumping arbiter_workers.last_heartbeat, the optional liveness file, and reconciling pause state from the DB. Must be well below workerStaleThreshold. Default: 10.

• backoffStrategy :: BackoffStrategy

  Retry backoff strategy. Default: exponential with base 2, max 1048576 seconds.

• jitter :: Jitter

  Jitter strategy for retry delays. Default: EqualJitter.

• observabilityHooks :: ObservabilityHooks m payload

  Callbacks for metrics or tracing. Default: no-op hooks.

• onMaintenance :: MaintenanceOp -> Int64 -> m ()

  Called after a reaper op this pool won the gate for, with the rows it touched. Reaper work is schema-wide and carries no queue. Default: no-op.

• workerRuntime :: WorkerRuntime

  Mutable lifecycle state allocated for this pool.

• livenessFile :: Maybe FilePath

  When set, the heartbeat loop touches this file at the workerHeartbeatInterval cadence, for a file-based liveness probe. Default: arbiter-worker-<workerId> in the system temporary directory.

• gracefulShutdownTimeout :: Maybe NominalDiffTime

  Seconds a graceful shutdown waits on in-flight jobs before force-exiting. Nothing waits indefinitely. Default: Just 30.

• logConfig :: LogConfig

  Where the pool's structured JSON logs go, at what level, and what context they carry beyond the job's own. Default: Info to stdout.

• cronJobs :: [CronJob payload]

  Cron schedules. A non-empty list gives the pool a scheduler thread, which reads the cron_schedules table each tick for runtime overrides. Default: [].

• reaperInterval :: NominalDiffTime

  How often the reaper runs. Default: 300 (5 minutes).

• reaperSparseInterval :: NominalDiffTime

  How often the reaper runs an operation that scans the whole schema. Default: 3600 (1 hour).

• reaperBucketIdle :: NominalDiffTime

  Idle age at which the reaper prunes a rate-limit bucket. Default: 300 (5 minutes).

• reaperTimeout :: NominalDiffTime

  Abort any single reaper statement that runs longer than this. Default: 300 (5 minutes).

• workerId :: UUID

  Identity for this pool. A fresh one is generated by default.

• workerHost :: Maybe Text

  Hostname recorded in the worker registry. Default: auto-generated.

• workerMetadata :: Maybe Value

  Arbitrary JSONB metadata for the worker registry row (image tag, git SHA, deploy id, etc.). Default: Nothing.

• workerStaleThreshold :: NominalDiffTime

  Workers whose last_heartbeat is older than this are swept from the runtime registry by reaperInterval. Must be well above the heartbeat cadence (workerHeartbeatInterval, or jobHeartbeatInterval while busy). Default: 300 (5 minutes).

Fields

• ack :: JobRead payload -> m ()

  Ack and fire onJobSuccess, storing no result. Available on any queue. A job acked this way is absent from its parent rollup's child results and leaves its archive entry's result NULL. Aborts the handler if another worker holds the job. The abort nacks the siblings still unfinalized.

• ackWith :: JobRead payload -> result -> m ()

  Ack, store the result for the parent rollup or the job's archive entry, fire onJobSuccess.

• ackAll :: [JobRead payload] -> m ()

  Bulk-ack in one parent-aware transaction, storing no results. Fires onJobSuccess per acked job. A job another worker holds is reported and skipped. The handler continues.

• ackAllWith :: [(JobRead payload, result)] -> m ()

  ackAll storing each job's result for its parent rollup or archive entry.

• failRetry :: JobRead payload -> Text -> m ()

  Retry with backoff, then DLQ at the job's maxAttempts.

• failPermanent :: JobRead payload -> Text -> m ()

  Straight to the DLQ.

• cancelBranch :: JobRead payload -> Text -> m ()

  Cancel this job's branch (its parent and all siblings).

• cancelTree :: JobRead payload -> Text -> m ()

  Cancel the whole tree from the root down.

• nack :: JobRead payload -> m ()

  Reprocess after the visibility timeout. Records no failure and consumes no attempt.