Behaviour for backends that own worker claims and lease extension.
Squidie.Executor covers durable job delivery. This behaviour is the
separate worker-lifecycle boundary for queue backends that can claim work,
extend active claims, complete delivered work, and return failed work to the
backend's retry or dead-letter policy.
The journal-backed runtime does not require a lease adapter. It exists as the public contract for adapters that want to expose leasing semantics through a durable delivery backend.
Summary
Callbacks
Claims visible work from a queue for one owner.
Completes a claimed item and removes it from backend delivery.
Marks a claimed item failed and lets the backend apply retry/dead-letter policy.
Extends the lease for an active claim.
Types
@type claim_opts() :: [ limit: pos_integer(), lease_duration_ms: pos_integer(), now: non_neg_integer() ]
@type fail_opts() :: [ base_delay: pos_integer(), max_delay: pos_integer(), now: non_neg_integer() ]
@type heartbeat_opts() :: [lease_duration_ms: pos_integer(), now: non_neg_integer()]
@type lease_error() :: term()
@type owner() :: String.t()
@type queue() :: String.t()
Callbacks
@callback claim(Squidie.Config.t(), queue(), owner(), claim_opts()) :: {:ok, [Squidie.Executor.Leases.Claim.t()]} | {:error, lease_error()}
Claims visible work from a queue for one owner.
Returning {:ok, []} means no work is currently visible. Returned claims
should include the queued payload and an opaque backend reference that the same
adapter can use for heartbeat, completion, and failure.
@callback complete(Squidie.Config.t(), Squidie.Executor.Leases.Claim.t(), keyword()) :: :ok | {:error, lease_error()}
Completes a claimed item and removes it from backend delivery.
@callback fail(Squidie.Config.t(), Squidie.Executor.Leases.Claim.t(), term(), fail_opts()) :: {:ok, :requeued | :dead_lettered} | {:error, lease_error()}
Marks a claimed item failed and lets the backend apply retry/dead-letter policy.
@callback heartbeat( Squidie.Config.t(), Squidie.Executor.Leases.Claim.t(), heartbeat_opts() ) :: {:ok, Squidie.Executor.Leases.Claim.t()} | {:error, lease_error()}
Extends the lease for an active claim.