# `Hyper.Img.Db.Lease`
[🔗](https://github.com/harmont-dev/hyper/blob/main/lib/hyper/img/db/lease.ex#L1)

A single running VM's claim on an image (and transitively, every blob in that
image's chain).

  * take a lease  -> insert a row        (your "increment, before starting the VM")
  * release       -> delete the row      (your "decrement, when done")
  * heartbeat     -> bump expires_at      (keeps a live VM's claim fresh)

Because the claim is owned and expiring, a node that dies mid-VM does not leak a
reference - its lease simply lapses, and the blob becomes deletable again without
anyone running the missing decrement.

# `bump`

```elixir
@spec bump(Hyper.Img.id(), Hyper.Vm.Id.t(), Unit.Time.t()) ::
  {:ok,
   %Hyper.Img.Db.Lease{
     __meta__: term(),
     expires_at: term(),
     id: term(),
     image: term(),
     image_id: term(),
     inserted_at: term(),
     node_id: term(),
     vm_id: term()
   }}
  | {:error, Ecto.Changeset.t()}
```

Take a lease on the given image, bumping its expiry if one already exists.

Upserts on `(node_id, vm_id)` - the same call both takes a fresh lease and
heartbeats a live one.

# `changeset`

# `default_ttl`

# `reap_expired`

Reap the expired leases. This is mostly implemented to clean up the database, but does nothing
outside of that. Returns the number of leases removed.

# `release`

```elixir
@spec release(Hyper.Vm.Id.t()) :: :ok
```

Release the lease issued to the given node_id and the given vm_id. Since each VM only ever uses
one image, it is not necessary to specify the image id.

---

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