Crate dig_store_cache 

dig-store-cache

The DIG Node’s on-disk cache of already-verified .dig capsules — the cache + reshare leg of the content-replication flywheel (install → connect → discover → read → CACHE → reshare). When the node fetches and verifies a capsule, it admits the finished bytes here; the cache holds them under a bounded, evicted (pluggable policy, LRU by default), pin-aware, crash-safe store and reports the resulting holdings so the node can announce itself as a provider. Every read therefore makes content MORE available.

Boundary — a pure filesystem primitive

This crate has NO chain, NO network, and NO key dependencies. It trusts the caller to have verified content before put_file/put_bytes (dig-node runs the NC-9 merkle/chain verify), and it does not choose where it lives — the caller passes the root. It re-exports dig_store::CapsuleIdentity as THE content id so the whole ecosystem speaks one identity type. The optional PutOptions::check_identity adds a cheap structural sanity check (the bytes’ declared identity equals the claim) — not a substitute for the caller’s real verify.

Durability contract

Disk is authoritative; the index.json manifest is an advisory overlay. Admission is atomic (stage to tmp/, fsync, rename into capsules/), so a crash never leaves a half file among the capsules. On open the index is rebuilt by SCANNING capsules/ and overlaying the manifest for recency + pin state; a lost manifest costs only recency ordering (recovered from mtimes) and pins, never a capsule. See SPEC.md.

Example

use dig_store_cache::{Cache, CacheConfig, PutOptions, CapsuleIdentity};
use std::path::Path;

let cache = Cache::open(Path::new("/var/lib/dig/cache"), CacheConfig::default())?;
let admission = cache.put_file(id, verified, PutOptions::default())?;
// `admission.evicted` lists capsules the node must stop advertising.
if let Some(hit) = cache.get(&id) {
    // stream from `hit.path()` — capsules can be ~1 GiB, never assume they fit in RAM
    let _path = hit.path();
}

Structs

Admission

The outcome of an admission (or a capacity-lowering reconfigure): which capsules it evicted.

Cache

A thread-safe handle to an on-disk capsule cache. Cloning shares the same underlying cache.

CacheConfig

How the cache is bounded and how it decides what to evict.

CacheStats

A point-in-time snapshot of cache occupancy.

CachedCapsule

A cached capsule located on disk. Byte access is PATH-BASED — capsules can be ~1 GiB, so a consumer streams from CachedCapsule::path rather than reading the whole file into memory.

CapsuleIdentity

The content id a capsule is addressed by, re-exported from dig-store so the ecosystem speaks ONE identity type ({ store_id, root_hash }). The identity a capsule declares: one immutable store generation, the pair (store_id, root_hash).

EvictionContext

The read-only view a policy reasons over when choosing what to evict.

EvictionEntry

A single cache entry as the policy sees it — enough to rank it for eviction, nothing more.

LruPolicy

Least-recently-used eviction: evict the coldest unpinned entries first until enough room is freed.

PutOptions

Options controlling a single put.

Enums

CacheError

A failure of a cache operation.

Constants

DEFAULT_MAX_BYTES

The default cache capacity: 1 GiB.

Traits

EvictionPolicy

Chooses which capsules to evict to make room. See the module docs for the pinned invariant.