qualia_core_db/q42/volume/
opfs_source.rs1use 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
34pub struct OpfsSliceRangeSource<B> {
36 bytes: B,
37}
38
39impl<B> OpfsSliceRangeSource<B> {
40 pub fn new(bytes: B) -> Self {
42 Self { bytes }
43 }
44}
45
46impl<B: AsRef<[u8]>> OpfsSliceRangeSource<B> {
47 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
63pub 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 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
105pub type VerifiedCarRangeSource = OpfsSliceRangeSource<Vec<u8>>;
107
108pub 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#[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}