AshVault.KeyCaches.ETS (AshVault v0.2.0)

Copy Markdown View Source

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

evict_all(name)

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

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

evict_scope(name, scope)

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

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

fetch(name, scope, slot)

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

generation(name, scope)

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(name, scope, slot, entry, ttl, generation)

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

start_link(opts)

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

Start the cache.

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

stats(name)

@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?()

@spec zeroes_on_evict?() :: boolean()

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