Arbiter.Core

A value's constructor name, for a payload that wraps a sum. Requires Generic.

instance HasKind Envelope where
  kindOf = Just . constructorKind . envelopePayload
  kindsFor = constructorKinds @EmailPayload

Every constructor name of a type, in declaration order.

Strict inverse of jobStatusToText. Unknown values are rejected.

The wire name for a status.

A trace context from its two stored halves. An orphan tracestate is dropped.

base's finally. The second action stays interruptible.

24h in seconds, a convenience value for setArchiveFor.

Decode a stored payload, or the reason the type rejects it.

defaultJob with a group key. Jobs sharing a group key are processed serially.

Ungrouped JobWrite with default values. For serial processing within a group, use defaultGroupedJob.

Default attempt limit stamped onto jobs whose maxAttempts is unset.

No-op hooks. Override fields to add observability:

myHooks = defaultObservabilityHooks
  { onJobSuccess = \job startTime endTime -> do
      let duration = diffUTCTime endTime startTime
      logInfo $ "Job " <> show (primaryKey job) <> " took " <> show duration
  }

Hooks written in m, run in n through the given natural transformation. It must be a monad morphism, such as lift.

A rollup finalizer is any job whose parentState snapshot is present (an empty object from its insert or spawn, the merged child results before a DLQ move).

A job's JSON fields as key-value pairs.

A job's JSON fields as an encoding series.

Transform a job's payload without changing its stored metadata.

Lowest attempt limit a job is stamped with. Every job gets at least one attempt.

Set the archive retention, in seconds.

Set the dedup key.

Set the group key.

Set the attempt limit. Nothing takes defaultMaxAttempts. Values below minMaxAttempts are raised to it.

Delay the job's first visibility.

Replace the payload.

Set the claim priority. Lower numbers claim first. In a group, a retried job goes first.

Attach a trace context.

A payload's stored form.

Completed-job archive retention in seconds.

Number of attempts made so far.

The claim token.

Holder of the outstanding claim. Nothing when no claim is outstanding.

Deduplication strategy and key.

Serial-processing group, or Nothing for an ungrouped job.

Time at which the job was inserted.

Time at which a worker last claimed the job.

Error message from the last failed attempt.

Attempt limit before the job moves to the DLQ.

Earliest time at which the job can be claimed.

Identifier of this job's parent in a job tree.

Snapshot of accumulated child results for a rollup finalizer.

User-defined payload stored as JSONB.

The labels and keys stamped from the payload at enqueue.

Database-assigned identifier for a stored job.

Claim priority. Lower numbers have higher priority. In a group, a retried job goes first.

Queue containing a stored job.

The JSON bytes of a stored payload.

Whether the job is suspended. It stays unclaimable until resumed.

W3C trace context captured at enqueue.

Time at which the job was last updated.

Deduplication strategy, checked on INSERT via ON CONFLICT on the dedup key.

A payload's per-job variant label. With no instance, the job is unlabelled. An empty instance on a Generic payload labels it with the constructor name.

Effective job status. Arbiter derives status from the stored fields. The status SQL in Arbiter.Core.Sql.Jobs is its source of truth.

A job's W3C trace context.

How long to wait before the next attempt.

The token identifying one claim of a job.

When the worker thread received the job's batch.

The worker's clock reading after the extend landed.

For a success, when the ack committed. For a failure, when the handler failed the job.

A failure message.

A job's primary key.

The full payload contract. JSON round-trip for JSONB storage plus the kind, rate-limit and concurrency declarations. All three default to none.

A job read from the database.

A job ready to enqueue. Arbiter owns claim, retry, parent, rollup, and suspension state. Use the exported setters to configure enqueue fields.

Callbacks fired at each point of a job's lifecycle, for metrics, logging or tracing. The worker catches an exception thrown inside one and logs it at Warning.

The labels and keys a stored job carries from its payload, one field each.

The constraint that lets the migration collect a registry's declared policies of both kinds.

When the worker thread received the job's batch.

A job parametrized over payload, primary key, queue name, insertion timestamp, and the columns derived from the payload. The constructor is internal.

A payload as the JSON bytes the database holds. The type it decodes to is a phantom.

Run a boolean Query. The result is true when a row is true.

Run a Query and keep its first row.

Backend-specific handler shape (for example Connection -> job -> m result). JobHandler instantiates it at one queue's job and result types.

MonadArbiter with the registry named, for signatures that mention it.

A handler for payload's queue. result is what its registry entry declares.

Database abstraction for job queue operations. Each backend (postgresql-simple, hasql, Orville) provides an instance that maps queries to its native driver.

The instance also names the monad's schema and queue registry. The high-level API resolves table names and result types from them at compile time.

This monad's registry. The default reports an instance that omits it.

The result type declared by payload's registry entry. It is not injective. A signature naming it needs another argument to determine payload.

Infix rollup for leaf-only children.

defaultJob reducer <~~ (defaultJob mapper1 :| [defaultJob mapper2])

A single job with no children.

A finalizer running once no child of it is left in the main queue. Nested rollups do not merge on their own. An intermediate finalizer returns the merged value for results to travel upward.

rollup (defaultJob root)
  ( leaf (defaultJob leaf1)
  :| [leaf (defaultJob leaf2)]
  )

A tree of jobs. Leaves are single jobs. Finalizers are parents with children that run immediately while the parent waits for completion.

A completed job in the archive.

PostgreSQL schema name, e.g. "arbiter".

Unqualified table name within a schema, e.g. "email_jobs".

The Right value, or throwInternal on the rendered Left.

The Right value, or throwParsing on the Left message.

Cancel the parent and every descendant. A job with no parent cancels only itself and its descendants.

Return the job to the queue without consuming an attempt.

Return the job to the queue without consuming an attempt, visible again after a delay in seconds.

Fail the job straight to the DLQ.

Fail the job and let it retry.

Fail the job and retry it after a delay in seconds, in place of the pool's backoff. The failure uses an attempt.

Cancel the whole job tree.

Cancel the parent and every descendant. A job with no parent cancels only itself and its descendants. A grandparent above is resumed.

Generic engine-internal failure, such as a missing connection or bad parameters.

A batch's claim hooks and handler ran past the pool's maximum job duration. Classified as a retryable failure.

Decisions a handler can signal by throwing. The worker catches it and retries, dead-letters or cancels the job.

Async exception for an operator force-cancel. Names the cancelled jobs, then the jobs the same check found reclaimed or gone.

Job was deleted or reclaimed between claim and ack. The worker recognizes this signal and skips retry/DLQ. The message is the reason reported to onJobUnavailable. The ids are the jobs that are gone. Empty when the thrower did not name them.

Reprocess the job later without recording a failure (a soft nack). The worker skips retry/DLQ, hands back the attempt the claim consumed, and leaves the job to become visible again after the delay in seconds, or when its lease lapses when there is none.

Permanent failure. The job goes straight to the DLQ.

Transient failure. The job is retried after the delay in seconds, or with the pool's backoff when there is none.

A failure that settles the jobs it names and no others.

Row decoding failure (engine-internal). Classified as a permanent failure by the worker.