alkblobs 0.1.0

Content-addressed blob storage: multi-hash put/get/verify store with pluggable backends, transport- and protocol-agnostic
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

//! Size-threshold dispatch between the kv and large tiers (ADR-003):
//! routing as a pure function of content length.
//!
//! **The routing seam the facade programs through.** `route` is the
//! pure function — `route(len, threshold) → Tier`, **at-or-below the
//! threshold stays on the kv tier** (the boundary's pinned reading:
//! store-put-paths' "≤ threshold → kv; > threshold → large") — and
//! [`DEFAULT_DISPATCH_THRESHOLD`] is the shipped default, 128 KiB, the
//! conservative edge of the measured ~128-256 KiB crossover zone (POC #3
//! A4). Purity is the ADR-003 invariant: same content ⇒ same length ⇒
//! same tier, re-puts are deterministic, no content ever migrates.
//!
//! The threshold is **constructor-tunable** (a per-deployment media
//! re-tuning, never an API change): the facade's mode constructors take
//! it explicitly and default their docs to this constant. Read-side
//! consult order — kv first, then large — is the facade's fall-through
//! general rule (ADR-012 §6.1), carried on the `Store` facade type
//! ([`crate::store`]); mode-specific behavior (kv-only's put-time
//! rejection, mem-only's no-threshold posture) lives on the facade's
//! mode machinery, not here: this module routes lengths, it does not
//! own modes.
//!
//! Read-side ops do not consult `route` — the
//! fall-through consult order is the facade's (kv first, then large;
//! ADR-012 §6.1).

/// The default dispatch threshold in bytes: 128 KiB — the conservative
/// edge of the measured ~128-256 KiB crossover zone (ADR-003; POC #3
/// finding A4's first-party benchmark). Constructor-tunable per
/// deployment media; retuning is a constructor parameter, never an API
/// change.
pub const DEFAULT_DISPATCH_THRESHOLD: u64 = 128 * 1024;

/// The two tiers a content length routes between. `pub(crate)`: the
/// enum is the routing *answer*, not the engine — tier names the
/// routing class (ADR-011 §1), and which engine backs the tier is the
/// constructor's choice, never this type's business.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Tier {
    /// The kv tier — at-or-below-threshold content.
    Kv,
    /// The large tier — over-threshold content.
    Large,
}

/// The pure routing function: over the threshold goes to the large
/// tier; **at or below** (exactly-at-threshold included) stays on the
/// kv tier. The boundary reading is pinned here and boundary-tested
/// below — `store-put-paths` and the read paths consume this exact
/// reading through the facade's seam.
///
/// Total purity discipline (ADR-003): a pure function of `len` — no
/// engine input, no namespace, no state. Same length is the same tier
/// forever, across mixed put paths, re-puts, and restarts.
pub(crate) fn route(len: u64, threshold: u64) -> Tier {
    if len > threshold {
        Tier::Large
    } else {
        Tier::Kv
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The shipped default is 128 KiB — pinned numerically (131072).
    #[test]
    fn default_threshold_is_128_kib() {
        assert_eq!(DEFAULT_DISPATCH_THRESHOLD, 131_072);
        assert_eq!(DEFAULT_DISPATCH_THRESHOLD, 128 * 1024);
    }

    /// The pinned boundary reading: exactly-at-threshold routes to the
    /// kv tier (≤ threshold → kv); one over routes large.
    #[test]
    fn exactly_at_threshold_routes_kv_one_over_routes_large() {
        assert_eq!(route(4096, 4096), Tier::Kv);
        assert_eq!(route(4095, 4096), Tier::Kv);
        assert_eq!(route(4097, 4096), Tier::Large);
    }

    /// Boundary values across the domain: zero length, the default
    /// threshold, and the degenerate tunings a constructor may pass —
    /// all route deterministically.
    #[test]
    fn boundary_values_route_deterministically() {
        assert_eq!(route(0, DEFAULT_DISPATCH_THRESHOLD), Tier::Kv);
        assert_eq!(route(131_071, DEFAULT_DISPATCH_THRESHOLD), Tier::Kv);
        assert_eq!(route(131_072, DEFAULT_DISPATCH_THRESHOLD), Tier::Kv);
        assert_eq!(route(131_073, DEFAULT_DISPATCH_THRESHOLD), Tier::Large);

        assert_eq!(route(0, 0), Tier::Kv, "zero-length content always kv");
        assert_eq!(
            route(1, 0),
            Tier::Large,
            "threshold 0: everything else large"
        );

        assert_eq!(route(0, u64::MAX), Tier::Kv, "max threshold: nothing large");
        assert_eq!(
            route(u64::MAX, u64::MAX),
            Tier::Kv,
            "at-threshold is kv even at MAX"
        );
    }

    /// Purity (the ADR-003 invariant): the same length is the same tier
    /// on every call — routing derives from inputs alone.
    #[test]
    fn routing_is_a_pure_function_of_length() {
        let len = 103_487;
        let first = route(len, DEFAULT_DISPATCH_THRESHOLD);
        for _ in 0..32 {
            assert_eq!(route(len, DEFAULT_DISPATCH_THRESHOLD), first);
        }
    }
}