Application-side read cache for kura projects.

Sending one chat message, serving one authenticated request, executing one webhook — hot paths read the same few rows over and over, and none of them change often. This module keeps those values in an ETS table owned by a supervised process and invalidates them on write.

The shape:

• one public ETS table (read_concurrency), owned by the kura_cache gen_server so it outlives the request processes that fill it;
• fetch/3 is the only read API: a hit returns the cached value, a miss runs the loader and caches whatever it returns — except undefined and {error, _}, which pass through uncached (caching a transient failure turns a blip into a bug);
• entries carry a per-kind TTL as a backstop: an eviction the application forgot to write costs staleness for seconds, not forever. A kind with no configured TTL is not cached at all — adding a kind is a deliberate act, so a stale read can always be traced to the configuration;
• evict/2 after every write to the underlying data. In a cluster the eviction must also reach the other nodes: kura_cache does not pick a transport, it calls the configured broadcast fun and exports local_evict/2 / local_flush/1 for the receiving side. Wire it to syn, pg, or nothing (single node).

The cache is not a source of truth and never serves writes — anything that must be correct under concurrency goes straight to the database.

Row-cache sugar

fetch_row/3 / evict_row/2 cache rows of a kura schema keyed by primary key: the kind is the schema module, the key is normalized from the schema's key fields (a bare value for single-column keys, a #{field => value} map for composite ones — the same spec convention as kura_repo_worker:get/3). The discipline is cache-aside, see docs/cache-aside-guide.md: only read the cache by primary key, write the database first, evict (never re-put) after writes.

Configuration

kura_cache:start_link(#{
    kinds => #{
        my_schema => 60_000,   %% TTL in ms; kind = schema module or any atom
        fanout    => 30_000
    },
    broadcast => fun my_app:broadcast_eviction/1,  %% optional
    sweep_interval => 60_000                       %% optional, default 60s
}).

Telemetry

[kura_cache, hit], [kura_cache, miss] and [kura_cache, evict] are executed with #{count => 1} and #{kind => Kind} metadata.