# `Squidie.Executor.Leases`
[🔗](https://github.com/dark-trench/squidie/blob/main/lib/squidie/executor/leases.ex#L2)

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.

# `claim_opts`

```elixir
@type claim_opts() :: [
  limit: pos_integer(),
  lease_duration_ms: pos_integer(),
  now: non_neg_integer()
]
```

# `fail_opts`

```elixir
@type fail_opts() :: [
  base_delay: pos_integer(),
  max_delay: pos_integer(),
  now: non_neg_integer()
]
```

# `heartbeat_opts`

```elixir
@type heartbeat_opts() :: [lease_duration_ms: pos_integer(), now: non_neg_integer()]
```

# `lease_error`

```elixir
@type lease_error() :: term()
```

# `owner`

```elixir
@type owner() :: String.t()
```

# `queue`

```elixir
@type queue() :: String.t()
```

# `claim`

```elixir
@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.

# `complete`

```elixir
@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.

# `fail`

```elixir
@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.

# `heartbeat`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*