# `AshVault.KeyCaches.ETS`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/key_caches/ets.ex#L1)

The default `AshVault.KeyCache` backend: a bounded, TTL'd, LRU ETS table.

Pure Elixir, no native code, and the fallback `cache: true` resolves to when no other
backend is named.

> #### This backend cannot zero key material {: .warning}
>
> `zeroes_on_evict?/0` returns `false`, and that is not a detail to gloss over.
> Deleting an ETS object drops a *reference*. A 32-byte key is small enough to be
> copied onto the caller's heap rather than refcounted, so after an eviction the bytes
> survive in however many process heaps read them, for however long the garbage
> collector takes. The BEAM offers no way to overwrite them.
>
> What this backend does guarantee is the **observable** contract: after
> `evict_scope/2` returns, no `fetch/3` on this node can see that scope again, and the
> generation fence means an in-flight read cannot put it back. That is what bounds the
> erasure window. `AshVaultRustler.KeyCache` additionally zeroes the authoritative
> copy.

## Storage

Two public ETS tables, owned by a `GenServer` named after the cache:

  * entries — `{{scope, slot}, entry, expires_at, generation, last_used, bytes}`
  * generations — `{scope, generation}`

`fetch/3` reads ETS directly, so the hot path takes no lock and no message. `put/6`
and `evict_scope/2` go through the owning process, which is what keeps the entry and
byte bounds and the LRU order exact rather than eventually consistent. Puts only
happen on a provider miss, so the serialisation point is off the hot path.

## Bounds

`:max_entries` and `:max_bytes` are both enforced on every write; when either is
exceeded the least-recently-used entries are dropped until both hold. `:tombstone`
entries are never evicted for space — they carry no key material, they are the
fail-closed answer, and dropping one to make room for a key would be precisely
backwards.

Because they cannot be evicted, they are also **excluded from the `:max_entries`
count**. Counting an inevictable entry towards an evictable bound is how a cache stops
honouring it: enough destroyed scopes and `trim/1` runs out of candidates with the
count still over the limit, and from then on every write is over budget and the bound
means nothing. They carry no bytes (`AshVault.KeyCache.entry_bytes/1` returns `0` for
`:destroyed`), so `:max_bytes` never had the same problem.

## Not started?

If the owning process is not running, `fetch/3` answers `{:miss, 0}` and `put/6` is a
no-op. Every read then goes to the real provider: slower, and correct. A cache is
allowed to fail to cache; it is never allowed to fail to serve.

# `evict_all`

```elixir
@spec evict_all(AshVault.KeyCache.name()) :: :ok | {:error, term()}
```

Drop everything, bumping the generation of every scope currently known.

# `evict_scope`

```elixir
@spec evict_scope(AshVault.KeyCache.name(), AshVault.KeyCache.scope()) ::
  :ok | {:error, term()}
```

Drop every entry for a scope and bump its generation. Synchronous.

# `fetch`

```elixir
@spec fetch(
  AshVault.KeyCache.name(),
  AshVault.KeyCache.scope(),
  AshVault.KeyCache.slot()
) ::
  {:ok, AshVault.KeyCache.entry(), AshVault.KeyCache.generation()}
  | {:miss, AshVault.KeyCache.generation()}
```

Read a slot, returning the generation observed so a later `put/6` can be fenced.

# `generation`

```elixir
@spec generation(AshVault.KeyCache.name(), AshVault.KeyCache.scope()) ::
  non_neg_integer()
```

The current eviction counter for diagnostics, `0` if never evicted.

This counter is not a write token. Pass the opaque token from `fetch/3` to `put/6`.

# `put`

```elixir
@spec put(
  AshVault.KeyCache.name(),
  AshVault.KeyCache.scope(),
  AshVault.KeyCache.slot(),
  AshVault.KeyCache.entry(),
  AshVault.KeyCache.ttl(),
  AshVault.KeyCache.generation()
) :: :ok | :stale
```

Write a slot unless the scope's generation has advanced since `fetch/3` read it.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start the cache.

Options: `:name` (required), `:max_entries`, `:max_bytes`.

# `stats`

```elixir
@spec stats(AshVault.KeyCache.name()) :: %{
  entries: non_neg_integer(),
  bytes: non_neg_integer()
}
```

Entry count and total cached key bytes.

`:entries` counts *every* slot, inevictable `:tombstone` entries included, so it can
legitimately exceed `:max_entries` — that bound applies only to the evictable ones. See
the "Bounds" section of the moduledoc.

# `zeroes_on_evict?`

```elixir
@spec zeroes_on_evict?() :: boolean()
```

This backend drops references; it does not zero. Always `false`.

---

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