Skip to main content

qualia_core_db/net/peer/replication/
source.rs

1//! Caller-buffered scan sources (E06.1).
2//!
3//! Production scans of large volumes go through [`ScanSource::read_at`] into a
4//! caller-owned page. This module never materializes a RAM-sized dataset and
5//! does not allocate (`Vec` / `String` / `Box`) on the read path.
6//! [`MemorySource`] is an adapter over a caller-owned slice, not a synthetic
7//! XOR fill and not a volume loader.
8
9use crate::net::qdnf::errors::QdnfError;
10
11/// Exact-range reader. Implementations must not allocate.
12pub trait ScanSource {
13    /// Copy up to `out.len()` bytes from `offset`. Return bytes copied.
14    ///
15    /// Offset at or beyond [`Self::logical_len`] yields `Ok(0)`.
16    fn read_at(&self, offset: u64, out: &mut [u8]) -> Result<usize, QdnfError>;
17
18    /// Logical length in bytes. Not an allocated buffer size.
19    fn logical_len(&self) -> u64;
20}
21
22/// Adapter over a caller-owned byte slice (tests and already-resident pages).
23///
24/// Large volumes must not be fully loaded into a slice in order to scan;
25/// they must implement [`ScanSource`] with ranged `read_at`.
26#[derive(Clone, Copy, Debug, PartialEq, Eq)]
27pub struct MemorySource<'a> {
28    bytes: &'a [u8],
29}
30
31impl<'a> MemorySource<'a> {
32    /// Bind a caller-owned slice. The slice is not copied or grown.
33    #[inline]
34    pub const fn from_slice(bytes: &'a [u8]) -> Self {
35        Self { bytes }
36    }
37}
38
39impl ScanSource for MemorySource<'_> {
40    fn read_at(&self, offset: u64, out: &mut [u8]) -> Result<usize, QdnfError> {
41        let len = self.bytes.len() as u64;
42        if offset >= len {
43            return Ok(0);
44        }
45        let start = offset as usize;
46        let avail = self.bytes.len() - start;
47        let n = if avail < out.len() { avail } else { out.len() };
48        if n == 0 {
49            return Ok(0);
50        }
51        out[..n].copy_from_slice(&self.bytes[start..start + n]);
52        Ok(n)
53    }
54
55    #[inline]
56    fn logical_len(&self) -> u64 {
57        self.bytes.len() as u64
58    }
59}
60
61#[cfg(test)]
62mod tests {
63    use super::*;
64
65    #[test]
66    fn read_at_copies_slice_bytes() {
67        let src = [0x10u8, 0x20, 0x30, 0x40];
68        let mem = MemorySource::from_slice(&src);
69        let mut out = [0u8; 3];
70        assert_eq!(mem.read_at(1, &mut out).unwrap(), 3);
71        assert_eq!(&out, &[0x20, 0x30, 0x40]);
72        assert_eq!(mem.logical_len(), 4);
73    }
74
75    #[test]
76    fn offset_beyond_length_is_zero() {
77        let src = [1u8, 2, 3];
78        let mem = MemorySource::from_slice(&src);
79        let mut out = [0xffu8; 4];
80        assert_eq!(mem.read_at(3, &mut out).unwrap(), 0);
81        assert_eq!(mem.read_at(99, &mut out).unwrap(), 0);
82        assert_eq!(out, [0xffu8; 4]);
83    }
84
85    #[test]
86    fn two_equal_length_sources_yield_different_bytes() {
87        let a = [1u8; 8];
88        let b = [2u8; 8];
89        let mut pa = [0u8; 8];
90        let mut pb = [0u8; 8];
91        assert_eq!(MemorySource::from_slice(&a).read_at(0, &mut pa).unwrap(), 8);
92        assert_eq!(MemorySource::from_slice(&b).read_at(0, &mut pb).unwrap(), 8);
93        assert_ne!(pa, pb);
94        assert_eq!(pa, a);
95        assert_eq!(pb, b);
96    }
97}