# `Rheo.Lease`
[🔗](https://github.com/thanos/rheo/blob/v1.0.0/lib/rheo/lease.ex#L1)

A temporary claim on an event for one consumer group.

Fetching work creates a lease with a unique `lease_id` (fencing token). Only
the holder of the **current** lease may `Rheo.ack/2`, `Rheo.nack/3`, or
`Rheo.reject/3`. After expiry, another consumer may obtain a new lease
(at-least-once redelivery).

## Fields

| Field | Type | Meaning |
|---|---|---|
| `lease_id` | `String.t()` | Opaque fencing token for this claim |
| `stream` | `String.t()` | Stream name |
| `group` | `String.t()` | Consumer group name |
| `event_id` | `String.t()` | Id of the leased event |
| `event` | `Rheo.Event.t()` | Full immutable event payload |
| `consumer_id` | `String.t()` | Worker that holds the lease |
| `attempt` | `pos_integer()` | Delivery attempt count (starts at 1) |
| `leased_at` | `DateTime.t()` | When the lease was granted |
| `expires_at` | `DateTime.t()` | When the lease becomes reclaimable |
| `receipt` | `term() \| nil` | Opaque backend-native settle identity (ADR 021) |

## Example

    iex> event = %Rheo.Event{
    ...>   id: "evt_01",
    ...>   stream: "market-events",
    ...>   partition: 0,
    ...>   sequence: 1,
    ...>   timestamp: ~U[2026-01-15 12:00:00.000Z],
    ...>   type: "curve_update",
    ...>   payload: %{"currency" => "EUR"}
    ...> }
    iex> lease = %Rheo.Lease{
    ...>   lease_id: "lease_abc",
    ...>   stream: "market-events",
    ...>   group: "risk",
    ...>   event_id: event.id,
    ...>   event: event,
    ...>   consumer_id: "risk-worker-1",
    ...>   attempt: 1,
    ...>   leased_at: ~U[2026-01-15 12:00:00.000Z],
    ...>   expires_at: ~U[2026-01-15 12:00:30.000Z],
    ...>   receipt: "lease_abc"
    ...> }
    iex> {lease.group, lease.event.type, lease.attempt, lease.receipt}
    {"risk", "curve_update", 1, "lease_abc"}

# `t`

```elixir
@type t() :: %Rheo.Lease{
  attempt: pos_integer(),
  consumer_id: String.t(),
  event: Rheo.Event.t(),
  event_id: String.t(),
  expires_at: DateTime.t(),
  group: String.t(),
  lease_id: String.t(),
  leased_at: DateTime.t(),
  receipt: term() | nil,
  stream: String.t()
}
```

A fenced lease on a single event for a consumer group.

Pass this struct to `Rheo.ack/2`, `Rheo.nack/3`, or `Rheo.reject/3`.

`receipt` is an opaque backend-native settle token (ADR 021). Database
backends typically mirror `lease_id`; native-stream backends may store a
Redis ID / PEL claim identity. Do not pattern-match on receipt contents in
application code.

---

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