Skip to main content

qualia_core_db/q42/volume/
opfs_source.rs

1//! WASM/OPFS caller-buffered Q42 range source.
2//!
3//! JS or native OPFS fills a caller-owned buffer; Rust never maps the whole
4//! file on the hot path. A byte slice is accepted when the host already holds
5//! the bytes (tests, verified CAR entity after cold construction). The
6//! callback adapter is the browser path: OPFS/`File` reads into `out` and
7//! returns the filled count.
8//!
9//! Local CARv1 verification is a separate cold construction. It calls
10//! [`decode_and_verify_car`] and then exposes concatenated raw (0x55) UnixFS
11//! entity bytes through the same [`Q42RangeSource`] contract. Q42 offsets
12//! address that entity, never the CAR envelope. This module does not contact
13//! a public IPFS gateway.
14
15use std::io;
16#[cfg(not(target_arch = "wasm32"))]
17use std::path::Path;
18
19use super::car::{decode_and_verify_car, VerifiedCarBlock};
20use super::cid::CidSha256;
21use super::range::{validate_exact_range_response, Q42ByteRange, Q42RangeSource};
22
23fn invalid(message: impl Into<String>) -> io::Error {
24    io::Error::new(io::ErrorKind::InvalidInput, message.into())
25}
26
27fn short_fill() -> io::Error {
28    io::Error::new(
29        io::ErrorKind::InvalidData,
30        "OPFS range fill did not return exactly the requested Q42 bytes",
31    )
32}
33
34/// Caller-buffered view of host-supplied bytes (slice or owned entity).
35pub struct OpfsSliceRangeSource<B> {
36    bytes: B,
37}
38
39impl<B> OpfsSliceRangeSource<B> {
40    /// Creates a default `OpfsSliceRangeSource`.
41    pub fn new(bytes: B) -> Self {
42        Self { bytes }
43    }
44}
45
46impl<B: AsRef<[u8]>> OpfsSliceRangeSource<B> {
47    /// Views `self` as `bytes`.
48    pub fn as_bytes(&self) -> &[u8] {
49        self.bytes.as_ref()
50    }
51}
52
53impl<B: AsRef<[u8]>> Q42RangeSource for OpfsSliceRangeSource<B> {
54    fn length(&self) -> io::Result<u64> {
55        Ok(self.bytes.as_ref().len() as u64)
56    }
57
58    fn read_range_into(&self, range: Q42ByteRange, out: &mut [u8]) -> io::Result<()> {
59        copy_exact_slice(self.bytes.as_ref(), range, out)
60    }
61}
62
63/// Host fill callback: `(offset, length, buf) -> bytes_written`.
64///
65/// The callback must write exactly `length` bytes into `buf`. A short fill is
66/// never treated as success. Rust does not open or map the backing file.
67pub struct OpfsCallbackRangeSource<F> {
68    length: u64,
69    fill: F,
70}
71
72impl<F> OpfsCallbackRangeSource<F>
73where
74    F: Fn(u64, usize, &mut [u8]) -> io::Result<usize>,
75{
76    /// Creates a default `OpfsCallbackRangeSource`.
77    pub fn new(length: u64, fill: F) -> Self {
78        Self { length, fill }
79    }
80}
81
82impl<F> Q42RangeSource for OpfsCallbackRangeSource<F>
83where
84    F: Fn(u64, usize, &mut [u8]) -> io::Result<usize>,
85{
86    fn length(&self) -> io::Result<u64> {
87        Ok(self.length)
88    }
89
90    fn read_range_into(&self, range: Q42ByteRange, out: &mut [u8]) -> io::Result<()> {
91        if out.len() != range.length {
92            return Err(invalid(
93                "Q42 range output buffer length does not match request",
94            ));
95        }
96        range.validate_for(self.length)?;
97        let filled = (self.fill)(range.offset, range.length, out)?;
98        if filled != range.length {
99            return Err(short_fill());
100        }
101        validate_exact_range_response(range, self.length, range.offset, filled)
102    }
103}
104
105/// Verified UnixFS entity reconstructed from a local CARv1 file.
106pub type VerifiedCarRangeSource = OpfsSliceRangeSource<Vec<u8>>;
107
108/// Decode and CID-verify a CARv1 buffer, then expose raw-leaf entity bytes.
109pub fn verify_car_bytes_as_q42_source(car: &[u8]) -> io::Result<VerifiedCarRangeSource> {
110    let blocks = decode_and_verify_car(car)?;
111    Ok(OpfsSliceRangeSource::new(concatenate_raw_leaves(&blocks)))
112}
113
114/// Read a local CARv1 path, CID-verify every block, expose entity bytes.
115///
116/// Cold construction: the CAR is loaded to run [`decode_and_verify_car`]. The
117/// returned source then serves exact ranges of the UnixFS entity. This is not
118/// a live public-gateway check.
119#[cfg(not(target_arch = "wasm32"))]
120pub fn verify_local_car_as_q42_source(path: &Path) -> io::Result<VerifiedCarRangeSource> {
121    let car = std::fs::read(path)?;
122    verify_car_bytes_as_q42_source(&car)
123}
124
125fn concatenate_raw_leaves(blocks: &[VerifiedCarBlock]) -> Vec<u8> {
126    let mut total = 0usize;
127    for block in blocks {
128        if block.cid.codec == CidSha256::RAW {
129            total = total.saturating_add(block.data.len());
130        }
131    }
132    let mut entity = Vec::with_capacity(total);
133    for block in blocks {
134        if block.cid.codec == CidSha256::RAW {
135            entity.extend_from_slice(&block.data);
136        }
137    }
138    entity
139}
140
141fn copy_exact_slice(bytes: &[u8], range: Q42ByteRange, out: &mut [u8]) -> io::Result<()> {
142    if out.len() != range.length {
143        return Err(invalid(
144            "Q42 range output buffer length does not match request",
145        ));
146    }
147    let source_length = bytes.len() as u64;
148    range.validate_for(source_length)?;
149    let start =
150        usize::try_from(range.offset).map_err(|_| invalid("Q42 range offset exceeds platform"))?;
151    let end = start
152        .checked_add(range.length)
153        .ok_or_else(|| invalid("Q42 range overflows platform usize"))?;
154    out.copy_from_slice(&bytes[start..end]);
155    Ok(())
156}
157
158#[cfg(all(test, not(target_arch = "wasm32")))]
159mod tests {
160    use super::*;
161    use crate::q42_volume::write_unified_volume;
162    use crate::specialized_libs::computational_geometry::allocation_counter::assert_zero_alloc;
163    use crate::NQuin;
164    use std::collections::HashMap;
165    use std::io::Write;
166
167    use super::super::car::encode_raw_car;
168    use super::super::range::LocalFileRangeSource;
169    use tempfile::NamedTempFile;
170
171    fn tiny_unified_volume() -> NamedTempFile {
172        let file = NamedTempFile::new().unwrap();
173        write_unified_volume(
174            file.path(),
175            &HashMap::new(),
176            &[(3, 3)],
177            &[vec![NQuin {
178                subject: 1,
179                predicate: 2,
180                object: 3,
181                context: 0,
182                metadata: 0,
183                parity: 0,
184            }]],
185        )
186        .unwrap();
187        file
188    }
189
190    fn read_all<S: Q42RangeSource>(source: &S) -> Vec<u8> {
191        let length = usize::try_from(source.length().unwrap()).unwrap();
192        let mut out = vec![0u8; length];
193        source
194            .read_range_into(Q42ByteRange { offset: 0, length }, &mut out)
195            .unwrap();
196        out
197    }
198
199    fn assert_same_ranges<A: Q42RangeSource, B: Q42RangeSource>(left: &A, right: &B) {
200        let left_len = left.length().unwrap();
201        let right_len = right.length().unwrap();
202        assert_eq!(left_len, right_len);
203        assert_eq!(read_all(left), read_all(right));
204
205        let mid_len = 16.min(left_len as usize);
206        if left_len >= 8 && mid_len > 0 {
207            let mut from_left = vec![0u8; mid_len];
208            let mut from_right = vec![0u8; mid_len];
209            let range = Q42ByteRange {
210                offset: 4,
211                length: mid_len,
212            };
213            left.read_range_into(range, &mut from_left).unwrap();
214            right.read_range_into(range, &mut from_right).unwrap();
215            assert_eq!(from_left, from_right);
216        }
217
218        let overflow = Q42ByteRange {
219            offset: left_len,
220            length: 1,
221        };
222        assert!(left.read_range_into(overflow, &mut [0u8; 1]).is_err());
223        assert!(right.read_range_into(overflow, &mut [0u8; 1]).is_err());
224    }
225
226    #[test]
227    fn slice_source_matches_local_file_on_tiny_unified_volume() {
228        let file = tiny_unified_volume();
229        let disk = LocalFileRangeSource::open(file.path()).unwrap();
230        let bytes = std::fs::read(file.path()).unwrap();
231        let slice = OpfsSliceRangeSource::new(bytes.as_slice());
232        assert_same_ranges(&disk, &slice);
233        assert_eq!(slice.as_bytes(), bytes.as_slice());
234    }
235
236    #[test]
237    fn callback_source_matches_local_file_on_tiny_unified_volume() {
238        let file = tiny_unified_volume();
239        let disk = LocalFileRangeSource::open(file.path()).unwrap();
240        let bytes = std::fs::read(file.path()).unwrap();
241        let callback = OpfsCallbackRangeSource::new(bytes.len() as u64, |offset, len, buf| {
242            copy_exact_slice(
243                &bytes,
244                Q42ByteRange {
245                    offset,
246                    length: len,
247                },
248                buf,
249            )?;
250            Ok(len)
251        });
252        assert_same_ranges(&disk, &callback);
253    }
254
255    #[test]
256    fn verified_local_car_exposes_the_same_entity_as_the_q42_file() {
257        let file = tiny_unified_volume();
258        let entity = std::fs::read(file.path()).unwrap();
259        let car = encode_raw_car(&[entity.as_slice()]);
260        let mut car_file = NamedTempFile::new().unwrap();
261        car_file.write_all(&car).unwrap();
262        car_file.flush().unwrap();
263
264        let source = verify_local_car_as_q42_source(car_file.path()).unwrap();
265        assert_eq!(source.as_bytes(), entity.as_slice());
266
267        let disk = LocalFileRangeSource::open(file.path()).unwrap();
268        assert_same_ranges(&disk, &source);
269    }
270
271    #[test]
272    fn tampered_local_car_is_rejected() {
273        let mut car = encode_raw_car(&[b"intact-q42-entity".as_slice()]);
274        *car.last_mut().unwrap() ^= 0xff;
275        let mut car_file = NamedTempFile::new().unwrap();
276        car_file.write_all(&car).unwrap();
277        car_file.flush().unwrap();
278        assert!(verify_local_car_as_q42_source(car_file.path()).is_err());
279        assert!(verify_car_bytes_as_q42_source(&car).is_err());
280    }
281
282    #[test]
283    fn short_callback_fill_is_rejected() {
284        let source = OpfsCallbackRangeSource::new(8, |_offset, _len, buf| {
285            buf[..2].copy_from_slice(b"ab");
286            Ok(2)
287        });
288        assert!(source
289            .read_range_into(
290                Q42ByteRange {
291                    offset: 0,
292                    length: 4
293                },
294                &mut [0u8; 4]
295            )
296            .is_err());
297    }
298
299    #[test]
300    fn slice_and_callback_hot_reads_are_zero_heap() {
301        let file = tiny_unified_volume();
302        let bytes = std::fs::read(file.path()).unwrap();
303        let slice = OpfsSliceRangeSource::new(bytes.as_slice());
304        let callback = OpfsCallbackRangeSource::new(bytes.len() as u64, |offset, len, buf| {
305            copy_exact_slice(
306                &bytes,
307                Q42ByteRange {
308                    offset,
309                    length: len,
310                },
311                buf,
312            )?;
313            Ok(len)
314        });
315        let mut slice_buf = [0u8; 8];
316        let mut callback_buf = [0u8; 8];
317        let range = Q42ByteRange {
318            offset: 0,
319            length: 8,
320        };
321        assert_zero_alloc("q42_opfs_slice_range_read", || {
322            slice.read_range_into(range, &mut slice_buf).unwrap();
323        });
324        assert_zero_alloc("q42_opfs_callback_range_read", || {
325            callback.read_range_into(range, &mut callback_buf).unwrap();
326        });
327        assert_eq!(slice_buf, callback_buf);
328    }
329}