dig_store_cache/
config.rs

1//! Public configuration + result value types: [`CacheConfig`], [`PutOptions`], [`Admission`],
2//! [`CacheStats`].
3
4use crate::policy::{EvictionPolicy, LruPolicy};
5use dig_store::CapsuleIdentity;
6use std::sync::Arc;
7
8/// The default cache capacity: 1 GiB.
9pub const DEFAULT_MAX_BYTES: u64 = 1 << 30;
10
11/// How the cache is bounded and how it decides what to evict.
12///
13/// Cloning is cheap — the `policy` is shared behind an [`Arc`]. The default is a 1 GiB [`LruPolicy`]
14/// cache.
15#[derive(Clone)]
16pub struct CacheConfig {
17    /// The maximum total bytes of admitted capsules the cache holds before evicting (pins may push it
18    /// over — see [`crate::Cache::pin`]).
19    pub max_bytes: u64,
20    /// The eviction strategy. Defaults to [`LruPolicy`].
21    pub policy: Arc<dyn EvictionPolicy>,
22}
23
24impl Default for CacheConfig {
25    fn default() -> Self {
26        Self {
27            max_bytes: DEFAULT_MAX_BYTES,
28            policy: Arc::new(LruPolicy),
29        }
30    }
31}
32
33impl std::fmt::Debug for CacheConfig {
34    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
35        // The policy is a trait object with no Debug bound; report the tunable field + its presence.
36        f.debug_struct("CacheConfig")
37            .field("max_bytes", &self.max_bytes)
38            .field("policy", &"<dyn EvictionPolicy>")
39            .finish()
40    }
41}
42
43/// Options controlling a single `put`.
44#[derive(Debug, Clone, Copy, Default)]
45pub struct PutOptions {
46    /// Pin the admitted capsule so eviction never reclaims it (until unpinned/removed).
47    pub pinned: bool,
48    /// Before admitting bytes, recover their declared identity and assert it equals the claimed id
49    /// (a cheap structural sanity check — NOT a merkle/chain verify, which the caller already did).
50    /// Ignored by [`crate::Cache::put_file`] (which never reads the source body). Defaults to `false`.
51    pub check_identity: bool,
52}
53
54/// The outcome of an admission (or a capacity-lowering reconfigure): which capsules it evicted.
55///
56/// Feeds the flywheel's retract path — every id here is one the node must stop advertising as a
57/// holding (dig-dht provider retract / opcode-222 HoldingsAnnounce retract).
58#[derive(Debug, Clone, Default, PartialEq, Eq)]
59pub struct Admission {
60    /// The capsules evicted to make room, in eviction order. Empty when nothing was evicted.
61    pub evicted: Vec<CapsuleIdentity>,
62}
63
64/// A point-in-time snapshot of cache occupancy.
65#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub struct CacheStats {
67    /// Total bytes of all admitted capsules currently on disk.
68    pub bytes_used: u64,
69    /// Number of capsules currently cached.
70    pub count: usize,
71    /// The configured capacity in bytes.
72    pub capacity: u64,
73}
dig_store_cache/config.rs

dig_store_cache/
config.rs
