AshVault.KeyCache behaviour (AshVault v0.2.0)

Copy Markdown View Source

Behaviour for the storage behind AshVault.KeyProviders.Cached.

A key cache is a bounded, TTL'd, scope-partitioned map from {scope, slot} to a cached provider answer. AshVault.KeyProviders.Cached holds all of the policy — what may be cached, for how long, and the tombstone asymmetry — and a backend holds only the mechanism. That split is what lets the Rust backend (AshVaultRustler.KeyCache) drop in without restating any of the security rules.

AshVault ships AshVault.KeyCaches.ETS, which is pure Elixir and is the default.

What a backend must guarantee

  • evict_scope/2 is synchronous on the local node. When it returns :ok, no subsequent fetch/3 on that node can observe any entry for that scope that was written before the call. Cluster fan-out is the caller's job, not the backend's.
  • evict_scope/2 bumps the scope's generation. Every fetch/3 returns the generation it observed, and put/6 is given that generation back and must drop the write if the generation has since advanced. Without this fence, a read that started before a destroy can re-populate the cache after the eviction and resurrect an erased scope for a full TTL.
  • Generations are opaque tokens bound to the cache lifetime. A token from before a restart, or from a stopped cache, must never authorize a write to a new instance, even if its per-scope eviction counter is the same. Callers must pass the token from fetch/3 unchanged; they must not construct or order it.
  • fetch/3 never invents an entry. A backend that cannot answer returns :miss, which sends the caller to the real provider. A cache is allowed to fail to cache; it is never allowed to fail to serve, and it is never allowed to answer "not destroyed" on its own initiative.
  • Entries expire. An expired entry is a :miss.

Slots

A scope's cache is partitioned by slot:

  • :current — the answer to current_key/1, a key_info map. Rotation-sensitive, so it takes the short TTL.
  • a positive integer — the answer to get_key/2 for that version, a raw key binary.
  • :tombstone — a cached {:error, :destroyed}. Monotonic and fail-closed, so it may be cached without expiry. Only :destroyed is ever stored here; the absence of a tombstone is never cached, because caching "this scope is not destroyed" is exactly how a cache resurrects an erased tenant.

Zeroing

zeroes_on_evict?/0 tells the truth about whether eviction actually clears the bytes. AshVault.KeyCaches.ETS returns false — the BEAM cannot securely zero memory, and an ETS delete drops a reference on a refcounted binary whose lifetime is then the garbage collector's business. AshVaultRustler.KeyCache returns true. AshVault.KeyProviders.Cached logs this once at start so the difference is never a surprise.

Summary

Types

A cached provider answer.

Opaque fence bound to the cache instance and changed by each scope eviction.

The backend instance name. The generated Cached provider module is used.

A scope, already normalised to a binary.

Which answer for a scope is being cached.

Milliseconds, or :infinity for a tombstone.

Callbacks

A child spec, so a cache can be placed in a supervision tree.

Drop everything. Used by tests and by an operator panic button.

Synchronously drop every entry for a scope on this node and bump its generation.

Read a slot, along with the generation observed.

Write a slot, unless generation is stale.

Start the backend.

Current entry count and byte total, for tests and telemetry.

Whether eviction actually zeroes the key bytes, or merely drops a reference.

Functions

The number of bytes an entry's key material occupies, used for the byte bound.

Types

entry()

@type entry() :: {:key_info, map()} | {:key, binary()} | :destroyed

A cached provider answer.

{:key_info, map} for :current, {:key, binary} for a version slot, and :destroyed for :tombstone.

generation()

@type generation() :: term()

Opaque fence bound to the cache instance and changed by each scope eviction.

name()

@type name() :: atom()

The backend instance name. The generated Cached provider module is used.

scope()

@type scope() :: binary()

A scope, already normalised to a binary.

slot()

@type slot() :: :current | :tombstone | pos_integer()

Which answer for a scope is being cached.

ttl()

@type ttl() :: non_neg_integer() | :infinity

Milliseconds, or :infinity for a tombstone.

Callbacks

child_spec(keyword)

@callback child_spec(keyword()) :: Supervisor.child_spec()

A child spec, so a cache can be placed in a supervision tree.

evict_all(name)

@callback evict_all(name()) :: :ok | {:error, term()}

Drop everything. Used by tests and by an operator panic button.

evict_scope(name, scope)

@callback evict_scope(name(), scope()) :: :ok | {:error, term()}

Synchronously drop every entry for a scope on this node and bump its generation.

fetch(name, scope, slot)

@callback fetch(name(), scope(), slot()) ::
  {:ok, entry(), generation()} | {:miss, generation()}

Read a slot, along with the generation observed.

Returns {:miss, generation} for an absent, expired or evicted entry, and {:miss, 0} when the backend is not running at all.

put(name, scope, slot, entry, ttl, generation)

@callback put(name(), scope(), slot(), entry(), ttl(), generation()) :: :ok | :stale

Write a slot, unless generation is stale.

Returns :stale when the scope's generation has advanced since fetch/3 observed it, or the cache instance has changed — the write is dropped, making eviction durable against a concurrent read.

start_link(keyword)

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

Start the backend.

Options always include :name (the atom the other callbacks are addressed by), :max_entries and :max_bytes.

stats(name)

@callback stats(name()) :: %{entries: non_neg_integer(), bytes: non_neg_integer()}

Current entry count and byte total, for tests and telemetry.

zeroes_on_evict?()

@callback zeroes_on_evict?() :: boolean()

Whether eviction actually zeroes the key bytes, or merely drops a reference.

Functions

entry_bytes(arg1)

@spec entry_bytes(entry()) :: non_neg_integer()

The number of bytes an entry's key material occupies, used for the byte bound.