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
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.
Summary
Functions
Drop everything, bumping the generation of every scope currently known.
Drop every entry for a scope and bump its generation. Synchronous.
Read a slot, returning the generation observed so a later put/6 can be fenced.
The current eviction counter for diagnostics, 0 if never evicted.
Write a slot unless the scope's generation has advanced since fetch/3 read it.
Start the cache.
Entry count and total cached key bytes.
This backend drops references; it does not zero. Always false.
Functions
@spec evict_all(AshVault.KeyCache.name()) :: :ok | {:error, term()}
Drop everything, bumping the generation of every scope currently known.
@spec evict_scope(AshVault.KeyCache.name(), AshVault.KeyCache.scope()) :: :ok | {:error, term()}
Drop every entry for a scope and bump its generation. Synchronous.
@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.
@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.
@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.
@spec start_link(keyword()) :: GenServer.on_start()
Start the cache.
Options: :name (required), :max_entries, :max_bytes.
@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.
@spec zeroes_on_evict?() :: boolean()
This backend drops references; it does not zero. Always false.