Skip to main content

qualia_core_db/net/peer/replication/
manifest.rs

1//! Immutable content manifests: exact ranges, SHA-384 digests, codec and
2//! decoded-size bounds (SVC-01.12 partial).
3//!
4//! The digest is caller-supplied SHA-384 of the exact artifact bytes; this
5//! module does not hash a body. A container generation root is not a QSync
6//! root. Raw Q42/QNF artifacts are disclosed only when every byte and
7//! metadata is authorized. Packages remain open. This wave's decoded bound
8//! is 4 MiB, not RAM-sized datasets.
9
10use crate::net::qdnf::errors::QdnfError;
11use crate::net::qdnf::types::StrongDigest;
12
13/// Maximum exact ranges stored on one manifest.
14pub const MAX_RANGES: usize = 8;
15/// Decoded-size bound this wave (not a RAM-sized dataset ceiling).
16pub const MAX_DECODED_BYTES: u32 = 4 * 1024 * 1024;
17
18/// Half-open byte range `[offset, offset + len)` into the exact artifact.
19#[repr(C)]
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub struct ByteRange {
22    pub offset: u64,
23    pub len: u32,
24}
25
26/// Immutable content identity: digest, codec, decoded bound, exact ranges.
27#[repr(C)]
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub struct ContentManifest {
30    pub digest: StrongDigest,
31    pub codec: u16,
32    pub decoded_len: u32,
33    pub range_count: u8,
34    ranges: [ByteRange; MAX_RANGES],
35}
36
37impl ContentManifest {
38    /// Bind a manifest. Digest is not computed from a body here.
39    ///
40    /// [`QdnfError::Malformed`] if `digest` is [`StrongDigest::ZERO`] or `ranges` is empty.
41    /// [`QdnfError::Range`] if `decoded_len` is 0 or greater than [`MAX_DECODED_BYTES`],
42    /// or if `offset + len` overflows.
43    /// [`QdnfError::Capacity`] if `ranges.len() > MAX_RANGES`.
44    /// [`QdnfError::Overlap`] if any pair overlaps when ordered by `offset`
45    /// (`end > next.offset`). Adjacent ranges (`end == next.offset`) are allowed.
46    /// Unsorted input is compared pairwise without allocation.
47    pub fn bind(
48        digest: StrongDigest,
49        codec: u16,
50        decoded_len: u32,
51        ranges: &[ByteRange],
52    ) -> Result<Self, QdnfError> {
53        if digest == StrongDigest::ZERO {
54            return Err(QdnfError::Malformed);
55        }
56        if decoded_len == 0 || decoded_len > MAX_DECODED_BYTES {
57            return Err(QdnfError::Range);
58        }
59        if ranges.is_empty() {
60            return Err(QdnfError::Malformed);
61        }
62        if ranges.len() > MAX_RANGES {
63            return Err(QdnfError::Capacity);
64        }
65        reject_overlaps(ranges)?;
66        let mut stored = [ByteRange { offset: 0, len: 0 }; MAX_RANGES];
67        let mut i = 0usize;
68        while i < ranges.len() {
69            stored[i] = ranges[i];
70            i += 1;
71        }
72        Ok(Self {
73            digest,
74            codec,
75            decoded_len,
76            range_count: ranges.len() as u8,
77            ranges: stored,
78        })
79    }
80
81    #[inline]
82    /// `ContentManifest::range_count`.
83    pub fn range_count(&self) -> usize {
84        self.range_count as usize
85    }
86
87    /// Range at index `i`. Out of bounds → [`QdnfError::Range`].
88    pub fn range_at(&self, i: usize) -> Result<ByteRange, QdnfError> {
89        if i >= self.range_count as usize {
90            return Err(QdnfError::Range);
91        }
92        Ok(self.ranges[i])
93    }
94}
95
96/// A container generation root is not an authorized QSync root (SVC-01.14).
97#[inline]
98pub fn container_generation_is_qsync_root() -> bool {
99    false
100}
101
102/// Raw Q42/QNF artifacts require every byte and metadata disclosure authorized.
103#[inline]
104pub fn raw_artifact_requires_full_authorization() -> bool {
105    true
106}
107
108/// Disclose raw Q42/QNF artifact bytes. Incomplete authorization fails closed.
109#[inline]
110pub fn disclose_raw_artifact(fully_authorized: bool) -> Result<(), QdnfError> {
111    if raw_artifact_requires_full_authorization() && !fully_authorized {
112        return Err(QdnfError::Unauthorized);
113    }
114    Ok(())
115}
116
117fn checked_end(r: ByteRange) -> Result<u64, QdnfError> {
118    r.offset
119        .checked_add(u64::from(r.len))
120        .ok_or(QdnfError::Range)
121}
122
123/// Pairwise overlap: after ordering a pair by `offset`, `end > next.offset`.
124fn reject_overlaps(ranges: &[ByteRange]) -> Result<(), QdnfError> {
125    let n = ranges.len();
126    let mut i = 0usize;
127    while i < n {
128        let a = ranges[i];
129        let a_end = checked_end(a)?;
130        let mut j = i + 1;
131        while j < n {
132            let b = ranges[j];
133            let b_end = checked_end(b)?;
134            let overlap = if a.offset <= b.offset {
135                a_end > b.offset
136            } else {
137                b_end > a.offset
138            };
139            if overlap {
140                return Err(QdnfError::Overlap);
141            }
142            j += 1;
143        }
144        i += 1;
145    }
146    Ok(())
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152
153    fn digest(tag: u8) -> StrongDigest {
154        let mut d = StrongDigest::ZERO;
155        d.0[0] = tag;
156        d
157    }
158
159    fn bind_ok(ranges: &[ByteRange]) -> ContentManifest {
160        ContentManifest::bind(digest(1), 0, 64, ranges).unwrap()
161    }
162
163    #[test]
164    fn zero_digest_is_malformed() {
165        let ranges = [ByteRange { offset: 0, len: 8 }];
166        assert_eq!(
167            ContentManifest::bind(StrongDigest::ZERO, 0, 64, &ranges),
168            Err(QdnfError::Malformed)
169        );
170    }
171
172    #[test]
173    fn decoded_len_zero_and_over_max_are_range() {
174        let ranges = [ByteRange { offset: 0, len: 8 }];
175        assert_eq!(
176            ContentManifest::bind(digest(1), 0, 0, &ranges),
177            Err(QdnfError::Range)
178        );
179        assert_eq!(
180            ContentManifest::bind(digest(1), 0, MAX_DECODED_BYTES + 1, &ranges),
181            Err(QdnfError::Range)
182        );
183        ContentManifest::bind(digest(1), 0, MAX_DECODED_BYTES, &ranges).unwrap();
184    }
185
186    #[test]
187    fn empty_ranges_malformed_ninth_is_capacity() {
188        assert_eq!(
189            ContentManifest::bind(digest(1), 0, 64, &[]),
190            Err(QdnfError::Malformed)
191        );
192        let nine = [
193            ByteRange { offset: 0, len: 1 },
194            ByteRange { offset: 1, len: 1 },
195            ByteRange { offset: 2, len: 1 },
196            ByteRange { offset: 3, len: 1 },
197            ByteRange { offset: 4, len: 1 },
198            ByteRange { offset: 5, len: 1 },
199            ByteRange { offset: 6, len: 1 },
200            ByteRange { offset: 7, len: 1 },
201            ByteRange { offset: 8, len: 1 },
202        ];
203        assert_eq!(
204            ContentManifest::bind(digest(1), 0, 64, &nine),
205            Err(QdnfError::Capacity)
206        );
207    }
208
209    #[test]
210    fn overlapping_ranges_are_overlap() {
211        let sorted = [
212            ByteRange { offset: 0, len: 10 },
213            ByteRange { offset: 8, len: 4 },
214        ];
215        assert_eq!(
216            ContentManifest::bind(digest(1), 0, 64, &sorted),
217            Err(QdnfError::Overlap)
218        );
219        let unsorted = [
220            ByteRange { offset: 8, len: 4 },
221            ByteRange { offset: 0, len: 10 },
222        ];
223        assert_eq!(
224            ContentManifest::bind(digest(1), 0, 64, &unsorted),
225            Err(QdnfError::Overlap)
226        );
227    }
228
229    #[test]
230    fn two_disjoint_ranges_bind_ok() {
231        let ranges = [
232            ByteRange {
233                offset: 100,
234                len: 16,
235            },
236            ByteRange { offset: 0, len: 8 },
237        ];
238        let m = bind_ok(&ranges);
239        assert_eq!(m.digest, digest(1));
240        assert_eq!(m.codec, 0);
241        assert_eq!(m.decoded_len, 64);
242        assert_eq!(m.range_count(), 2);
243        assert_eq!(m.range_at(0).unwrap(), ranges[0]);
244        assert_eq!(m.range_at(1).unwrap(), ranges[1]);
245        assert_eq!(m.range_at(2), Err(QdnfError::Range));
246        let adjacent = [
247            ByteRange { offset: 0, len: 8 },
248            ByteRange { offset: 8, len: 4 },
249        ];
250        bind_ok(&adjacent);
251    }
252
253    #[test]
254    fn container_generation_is_not_qsync_root() {
255        assert!(!container_generation_is_qsync_root());
256    }
257
258    #[test]
259    fn raw_artifact_requires_full_authorization_is_true() {
260        assert!(raw_artifact_requires_full_authorization());
261        assert_eq!(disclose_raw_artifact(false), Err(QdnfError::Unauthorized));
262        disclose_raw_artifact(true).unwrap();
263    }
264}