nordisk/skade

The read path — design

Class: design · Function: read-path · Uses: store. Only the shape that runs; the why (why three layers, why no TTL, why foldhash) is in read-path-reasoning.md.

f0 — the layered resolve

A read resolves left to right, falling through only on a miss. The invariant that makes it coherence-free: every in-memory layer is keyed by an immutable, content-addressed identifier (a metadata_location or a snapshot id), so an entry can only be evicted, never stale.

table_exists / resolve_metadata / load_table
        │
   L1 pointer mirror ──miss──▶ L2 redb `tables`   (source of truth)
        │ (metadata_location)
   L1.5 Table handle cache ──miss──▶ L0 metadata cache ──miss──▶ FileIO read+parse

The warm-read entry points on RedbCatalog:

f1 — L1: the pointer mirror (pointer_cache.rs)

PointerCache (pointer_cache.rs:60) is an ArcSwap<PointerSnapshot> wrapping an imbl::HashMap<String, Arc<str>, foldhash::fast::RandomState> (pointer_cache.rs:42). It maps table_key → metadata_location for every live table.

• Built once from a full scan of the tables keyspace at open (store.rs:187).
• Maintained write-through: each commit path calls insert/remove (pointer_cache.rs:94) after its redb commit, still under the redb write lock.
• Reads (get, pointer_cache.rs:80) load the snapshot lock-free.
• Every published PointerSnapshot carries a monotonic generation (pointer_cache.rs:46); mutate clones the map (imbl structural sharing, O(1)) and stores a new snapshot, so readers observe a whole snapshot atomically.

A key absent from the mirror means the table does not exist; the redb fallback in resolve_location / table_exists is a safety net that only runs on a genuine miss.

f2 — L0: the parsed-metadata cache (meta_cache.rs)

MetadataCache (meta_cache.rs:34) is a byte-bounded moka::future::Cache<String, Arc<TableMetadata>> keyed by metadata_location. get_or_load (meta_cache.rs:62) returns a cached Arc on a hit, else reads + parses the metadata JSON via FileIO, coalescing concurrent misses on the same location into one read_from (moka single-flight). Entry weight is a structural estimate (weight_of, meta_cache.rs:117); budget defaults to DEFAULT_METADATA_CACHE_BYTES = 128 MiB (meta_cache.rs:27). A budget of 0 disables it.

f3 — L1.5: the built-Table handle cache (table_cache.rs)

TableHandleCache (table_cache.rs:42) is a capacity-bounded moka::future::Cache<String, Table> keyed by metadata_location. get (table_cache.rs:67) returns a clone of a built Table (which shares the underlying Arc<ObjectCache>), short-circuiting before L0 — but only if the cached handle's identifier() matches, so two entries aliasing the same metadata file (via register_table) don't cross. build_and_insert (table_cache.rs:79) builds on a miss and caches. Default capacity DEFAULT_TABLE_HANDLE_CACHE_BYTES = 256 MiB (table_cache.rs); 0 disables. It is a BYTE budget, not a handle count: one handle pins its parsed TableMetadata plus iceberg's per-Table ObjectCache, so a count bounded nothing (512 handles x iceberg's 32 MiB default was ~16 GiB). Each handle's object cache is now pinned to TABLE_OBJECT_CACHE_BYTES (4 MiB) and charged at that ceiling.

Correctness

All three caches share one property: the key is the immutable metadata location (or an immutable snapshot id). A new commit writes a new file at a new location and flips the pointer, so a stale value is unrepresentable — no TTL, no invalidation, no coherence protocol. The full argument is in read-path-reasoning.md.