Fields

• connStr :: ByteString

  PostgreSQL connection string (used for LISTEN/NOTIFY).

• workerCount :: Int

  Number of concurrent worker threads.

• handlerMode :: HandlerMode m payload result

  Job handler and claiming strategy (single or batched). Default: SingleJobMode.

• pollInterval :: NominalDiffTime

  Polling interval in seconds (fallback when no NOTIFY received). Also serves as the liveness heartbeat — the dispatcher signals the liveness probe after each poll cycle. Default: 5 seconds.

• visibilityTimeout :: NominalDiffTime

  Duration in seconds a claimed job stays invisible to other workers. Must be greater than heartbeatInterval. Sub-second values are rounded up to the nearest second. Default: 60.

• heartbeatInterval :: Int

  Interval in seconds for extending visibility timeout during processing. Must be less than visibilityTimeout to prevent job reclaim. Default: 30.

• maxAttempts :: Int32

  Max retries before moving to DLQ (used when job's maxAttempts is Nothing). Default: 10.

• backoffStrategy :: BackoffStrategy

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

• jitter :: Jitter

  Jitter strategy for retry delays. Default: EqualJitter.

• useWorkerTransaction :: Bool

  Transaction Mode:

  • True (Automatic): Handler runs in a transaction with automatic acking and rollback. Heartbeat prevents job reclaim during processing. Cannot control commit timing. If the ack fails then all database work is rolled back — this means BatchedJobsMode can have a large blast radius because the batch is acked atomically. Default: True.
  • False (Manual): Full transaction control. Handler must explicitly ack jobs. Child results are not automatically stored in the results table — the handler must call insertResult to make results visible to the rollup finalizer.
• transactionTimeout :: Maybe NominalDiffTime

  Transaction statement timeout in seconds. Only applies when useWorkerTransaction is True. Default: Nothing (no timeout).

• observabilityHooks :: ObservabilityHooks m payload

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

• workerStateVar :: TVar WorkerState

  Worker state (Running, Paused, ShuttingDown). Managed internally.

• livenessConfig :: Maybe LivenessConfig

  File-based liveness probe configuration. Default: writes to /tmp/arbiter-worker-<uuid> every 60 seconds.

• gracefulShutdownTimeout :: Maybe NominalDiffTime

  Maximum time in seconds to wait for in-flight jobs during graceful shutdown. If Nothing, waits indefinitely. If Just n, force-exits after n seconds. Default: Just 30.

• logConfig :: LogConfig

  Logging configuration. Arbiter outputs structured JSON logs with job context automatically included. Use this to control log level, destination, and inject additional context (e.g., trace IDs). Default: Info level to stdout.

• claimThrottle :: Maybe (IO (Int, NominalDiffTime))

  Optional claim rate limiter. The IO action returns (maxClaims, window): at most maxClaims jobs will be claimed per window duration. The action is called each claim cycle, so limits can be adjusted dynamically. Default: Nothing (no throttling).

• cronJobs :: [CronJob payload]

  Cron schedules. When non-empty, the worker pool spawns a scheduler thread that opens a dedicated connection from connStr and inserts jobs based on cron expressions. The cron_schedules table is consulted for runtime overrides (expression, overlap, enabled). Default: [].

• groupReaperInterval :: NominalDiffTime

  How often to recompute the groups table (correct drift in job_count, min_priority, min_id, in_flight_until). Default: 300 (5 minutes).

Fields

• livenessPath :: FilePath

  Path to the health check file

• livenessSignal :: MVar ()

  MVar pulsed by the dispatcher after each claim cycle and by the heartbeat after each successful visibility extension

• livenessInterval :: Int

  Seconds between health file writes