qualia_core_db/q42/volume/
range.rs1#[cfg(not(target_arch = "wasm32"))]
8use std::fs::File;
9use std::io;
10#[cfg(not(target_arch = "wasm32"))]
11use std::io::{Read, Seek, SeekFrom};
12#[cfg(not(target_arch = "wasm32"))]
13use std::path::Path;
14#[cfg(not(target_arch = "wasm32"))]
15use std::sync::Mutex;
16
17use sha2::{Digest, Sha256};
18
19#[cfg(not(target_arch = "wasm32"))]
20use super::manifest::{Q42SegmentRangeFactory, Q42VolumeSegment};
21
22fn invalid(message: impl Into<String>) -> io::Error {
25 io::Error::new(io::ErrorKind::InvalidInput, message.into())
26}
27
28#[derive(Clone, Copy, Debug, Eq, PartialEq)]
30pub struct Q42ByteRange {
31 pub offset: u64,
32 pub length: usize,
33}
34
35impl Q42ByteRange {
36 pub fn end(self) -> io::Result<u64> {
38 self.offset
39 .checked_add(self.length as u64)
40 .ok_or_else(|| invalid("Q42 byte range overflows u64"))
41 }
42
43 pub fn validate_for(self, source_length: u64) -> io::Result<()> {
45 if self.end()? > source_length {
46 return Err(invalid("Q42 byte range exceeds source length"));
47 }
48 Ok(())
49 }
50}
51
52pub trait Q42RangeSource {
55 fn length(&self) -> io::Result<u64>;
57 fn read_range_into(&self, range: Q42ByteRange, out: &mut [u8]) -> io::Result<()>;
60}
61
62#[cfg(not(target_arch = "wasm32"))]
65pub struct LocalFileRangeSource {
66 length: u64,
67 file: Mutex<File>,
68}
69
70#[cfg(not(target_arch = "wasm32"))]
71impl LocalFileRangeSource {
72 pub fn open(path: &Path) -> io::Result<Self> {
75 let file = File::open(path)?;
76 let length = file.metadata()?.len();
77 Ok(Self {
78 length,
79 file: Mutex::new(file),
80 })
81 }
82}
83
84#[cfg(not(target_arch = "wasm32"))]
85impl Q42RangeSource for LocalFileRangeSource {
86 fn length(&self) -> io::Result<u64> {
88 Ok(self.length)
89 }
90
91 fn read_range_into(&self, range: Q42ByteRange, out: &mut [u8]) -> io::Result<()> {
94 if out.len() != range.length {
95 return Err(invalid(
96 "Q42 range output buffer length does not match request",
97 ));
98 }
99 range.validate_for(self.length)?;
100 let mut file = self
101 .file
102 .lock()
103 .map_err(|_| io::Error::other("Q42 range source lock poisoned"))?;
104 file.seek(SeekFrom::Start(range.offset))?;
105 file.read_exact(out)
106 }
107}
108
109pub fn validate_exact_range_response(
113 requested: Q42ByteRange,
114 source_length: u64,
115 content_range_start: u64,
116 returned_len: usize,
117) -> io::Result<()> {
118 requested.validate_for(source_length)?;
119 if content_range_start != requested.offset || returned_len != requested.length {
120 return Err(io::Error::new(
121 io::ErrorKind::InvalidData,
122 "range response does not exactly match the requested Q42 bytes",
123 ));
124 }
125 Ok(())
126}
127
128pub fn verify_source_sha256<S: Q42RangeSource>(
133 source: &S,
134 expected: &[u8; 32],
135 scratch: &mut [u8],
136) -> io::Result<()> {
137 if scratch.is_empty() {
138 return Err(invalid(
139 "Q42 verification requires a non-empty scratch buffer",
140 ));
141 }
142 let length = source.length()?;
143 let mut hasher = Sha256::new();
144 let mut offset = 0u64;
145 while offset < length {
146 let count = usize::try_from((length - offset).min(scratch.len() as u64))
147 .map_err(|_| invalid("Q42 verification chunk does not fit platform"))?;
148 source.read_range_into(
149 Q42ByteRange {
150 offset,
151 length: count,
152 },
153 &mut scratch[..count],
154 )?;
155 hasher.update(&scratch[..count]);
156 offset += count as u64;
157 }
158 let actual: [u8; 32] = hasher.finalize().into();
159 if &actual != expected {
160 return Err(io::Error::new(
161 io::ErrorKind::InvalidData,
162 "Q42 source SHA-256 differs from root manifest",
163 ));
164 }
165 Ok(())
166}
167
168#[cfg(not(target_arch = "wasm32"))]
171pub struct HttpRangeSource {
172 client: reqwest::blocking::Client,
173 url: reqwest::Url,
174 length: u64,
175}
176
177#[cfg(not(target_arch = "wasm32"))]
178impl HttpRangeSource {
179 pub fn new(url: &str, length: u64) -> io::Result<Self> {
182 if length == 0 {
183 return Err(invalid("Q42 HTTP source length must be non-zero"));
184 }
185 let url = reqwest::Url::parse(url)
186 .map_err(|error| invalid(format!("invalid Q42 HTTP URL: {error}")))?;
187 if url.scheme() != "https" && url.scheme() != "http" {
188 return Err(invalid("Q42 HTTP source must use http or https"));
189 }
190 let client = reqwest::blocking::Client::builder()
191 .connect_timeout(std::time::Duration::from_secs(10))
192 .timeout(std::time::Duration::from_secs(30))
193 .build()
194 .map_err(|error| io::Error::other(format!("build Q42 HTTP client: {error}")))?;
195 Ok(Self {
196 client,
197 url,
198 length,
199 })
200 }
201
202 pub fn discover(url: &str) -> io::Result<Self> {
207 let url = reqwest::Url::parse(url)
208 .map_err(|error| invalid(format!("invalid Q42 HTTP URL: {error}")))?;
209 if url.scheme() != "https" && url.scheme() != "http" {
210 return Err(invalid("Q42 HTTP source must use http or https"));
211 }
212 let client = reqwest::blocking::Client::builder()
213 .connect_timeout(std::time::Duration::from_secs(10))
214 .timeout(std::time::Duration::from_secs(30))
215 .build()
216 .map_err(|error| io::Error::other(format!("build Q42 HTTP client: {error}")))?;
217 if let Ok(response) = client.head(url.clone()).send() {
218 if response.status().is_success() {
219 if let Some(length) = response.content_length().filter(|length| *length != 0) {
220 return Ok(Self {
221 client,
222 url,
223 length,
224 });
225 }
226 }
227 }
228 let mut response = client
229 .get(url.clone())
230 .header(reqwest::header::RANGE, "bytes=0-0")
231 .send()
232 .map_err(|error| io::Error::other(format!("discover Q42 range length: {error}")))?;
233 if response.status() != reqwest::StatusCode::PARTIAL_CONTENT {
234 return Err(invalid("Q42 gateway cannot prove byte-range source length"));
235 }
236 let header = response
237 .headers()
238 .get(reqwest::header::CONTENT_RANGE)
239 .and_then(|value| value.to_str().ok())
240 .ok_or_else(|| invalid("Q42 discovery response has no valid Content-Range"))?;
241 let (start, end, length) = parse_content_range(header)?;
242 if start != 0 || end != 0 {
243 return Err(invalid("Q42 discovery range was not exactly bytes 0-0"));
244 }
245 let mut first = [0u8; 1];
246 response.read_exact(&mut first)?;
247 let mut extra = [0u8; 1];
248 if response.read(&mut extra)? != 0 {
249 return Err(invalid("Q42 discovery response contains extra bytes"));
250 }
251 Ok(Self {
252 client,
253 url,
254 length,
255 })
256 }
257}
258
259#[cfg(not(target_arch = "wasm32"))]
260impl Q42RangeSource for HttpRangeSource {
261 fn length(&self) -> io::Result<u64> {
263 Ok(self.length)
264 }
265
266 fn read_range_into(&self, range: Q42ByteRange, out: &mut [u8]) -> io::Result<()> {
270 if out.len() != range.length {
271 return Err(invalid(
272 "Q42 range output buffer length does not match request",
273 ));
274 }
275 range.validate_for(self.length)?;
276 let end = range
277 .end()?
278 .checked_sub(1)
279 .ok_or_else(|| invalid("Q42 HTTP range may not be empty"))?;
280 let response = self
281 .client
282 .get(self.url.clone())
283 .header(
284 reqwest::header::RANGE,
285 format!("bytes={}-{}", range.offset, end),
286 )
287 .send()
288 .map_err(|error| io::Error::other(format!("fetch Q42 range: {error}")))?;
289 if response.status() != reqwest::StatusCode::PARTIAL_CONTENT {
290 return Err(io::Error::new(
291 io::ErrorKind::InvalidData,
292 "Q42 gateway did not return HTTP 206 Partial Content",
293 ));
294 }
295 let header = response
296 .headers()
297 .get(reqwest::header::CONTENT_RANGE)
298 .and_then(|value| value.to_str().ok())
299 .ok_or_else(|| {
300 io::Error::new(
301 io::ErrorKind::InvalidData,
302 "Q42 range response has no valid Content-Range",
303 )
304 })?;
305 let (start, returned_end, total) = parse_content_range(header)?;
306 if total != self.length
307 || returned_end
308 .checked_add(1)
309 .and_then(|value| value.checked_sub(start))
310 .and_then(|value| usize::try_from(value).ok())
311 != Some(range.length)
312 {
313 return Err(io::Error::new(
314 io::ErrorKind::InvalidData,
315 "Q42 Content-Range does not match catalog length",
316 ));
317 }
318 let mut response = response;
319 response
320 .read_exact(out)
321 .map_err(|error| io::Error::other(format!("read Q42 range body: {error}")))?;
322 let mut extra = [0u8; 1];
323 if response
324 .read(&mut extra)
325 .map_err(|error| io::Error::other(format!("read Q42 range tail: {error}")))?
326 != 0
327 {
328 return Err(io::Error::new(
329 io::ErrorKind::InvalidData,
330 "Q42 range response contains extra bytes",
331 ));
332 }
333 validate_exact_range_response(range, self.length, start, out.len())
334 }
335}
336
337#[cfg(not(target_arch = "wasm32"))]
338pub fn ipfs_gateway_range_source(
341 gateway: &str,
342 cid: &str,
343 length: u64,
344) -> io::Result<HttpRangeSource> {
345 if cid.is_empty() || !cid.bytes().all(|byte| byte.is_ascii_alphanumeric()) {
346 return Err(invalid("IPFS CID must be a non-empty base32/base58 token"));
347 }
348 let gateway = gateway.trim_end_matches('/');
349 HttpRangeSource::new(&format!("{gateway}/ipfs/{cid}"), length)
350}
351
352#[cfg(not(target_arch = "wasm32"))]
356pub fn ipns_gateway_range_source(gateway: &str, name: &str) -> io::Result<HttpRangeSource> {
357 if name.is_empty()
358 || !name
359 .bytes()
360 .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b'_'))
361 {
362 return Err(invalid("IPNS name must be an ASCII name without a path"));
363 }
364 let gateway = gateway.trim_end_matches('/');
365 HttpRangeSource::discover(&format!("{gateway}/ipns/{name}"))
366}
367
368#[cfg(not(target_arch = "wasm32"))]
372pub struct IpfsGatewaySegmentFactory {
373 gateway: String,
374}
375
376#[cfg(not(target_arch = "wasm32"))]
377impl IpfsGatewaySegmentFactory {
378 pub fn new(gateway: &str) -> io::Result<Self> {
380 let gateway = gateway.trim_end_matches('/');
381 let url = reqwest::Url::parse(gateway)
382 .map_err(|error| invalid(format!("invalid IPFS gateway URL: {error}")))?;
383 if url.scheme() != "https" && url.scheme() != "http" {
384 return Err(invalid("IPFS gateway must use http or https"));
385 }
386 Ok(Self {
387 gateway: gateway.to_owned(),
388 })
389 }
390}
391
392#[cfg(not(target_arch = "wasm32"))]
393impl Q42SegmentRangeFactory for IpfsGatewaySegmentFactory {
394 type Source = HttpRangeSource;
395
396 fn open_segment(&self, segment: &Q42VolumeSegment) -> io::Result<Self::Source> {
399 let cid = segment
400 .ipfs_cid()
401 .ok_or_else(|| invalid("IPFS gateway factory requires an ipfs://CID locator"))?;
402 ipfs_gateway_range_source(&self.gateway, cid, segment.byte_length)
403 }
404}
405
406#[cfg(not(target_arch = "wasm32"))]
407impl super::manifest::Q42LexiconRangeFactory for IpfsGatewaySegmentFactory {
408 type Source = HttpRangeSource;
409
410 fn open_lexicon_segment(
412 &self,
413 segment: &super::manifest::Q42LexiconSegment,
414 ) -> io::Result<Self::Source> {
415 let cid = segment.locator.strip_prefix("ipfs://").ok_or_else(|| {
416 invalid("IPFS gateway factory requires an ipfs://CID lexicon locator")
417 })?;
418 ipfs_gateway_range_source(&self.gateway, cid, segment.byte_length)
419 }
420}
421
422#[cfg(not(target_arch = "wasm32"))]
423fn parse_content_range(value: &str) -> io::Result<(u64, u64, u64)> {
426 let body = value
427 .strip_prefix("bytes ")
428 .ok_or_else(|| invalid("unsupported Content-Range unit"))?;
429 let (range, total) = body
430 .split_once('/')
431 .ok_or_else(|| invalid("malformed Content-Range"))?;
432 let (start, end) = range
433 .split_once('-')
434 .ok_or_else(|| invalid("malformed Content-Range interval"))?;
435 let start = start
436 .parse()
437 .map_err(|_| invalid("invalid Content-Range start"))?;
438 let end = end
439 .parse()
440 .map_err(|_| invalid("invalid Content-Range end"))?;
441 let total = total
442 .parse()
443 .map_err(|_| invalid("invalid Content-Range total"))?;
444 if start > end || end >= total {
445 return Err(invalid("Content-Range lies outside source"));
446 }
447 Ok((start, end, total))
448}
449
450#[cfg(all(test, not(target_arch = "wasm32")))]
451mod tests {
452 use super::*;
453 use crate::specialized_libs::computational_geometry::allocation_counter::assert_zero_alloc;
454 use std::io::Write;
455 use tempfile::NamedTempFile;
456
457 #[test]
458 fn local_source_requires_exact_bounded_ranges() {
459 let mut file = NamedTempFile::new().unwrap();
460 file.write_all(b"0123456789").unwrap();
461 let source = LocalFileRangeSource::open(file.path()).unwrap();
462 let mut out = [0u8; 4];
463 source
464 .read_range_into(
465 Q42ByteRange {
466 offset: 3,
467 length: 4,
468 },
469 &mut out,
470 )
471 .unwrap();
472 assert_eq!(&out, b"3456");
473 assert!(source
474 .read_range_into(
475 Q42ByteRange {
476 offset: 9,
477 length: 2
478 },
479 &mut [0; 2]
480 )
481 .is_err());
482 assert!(validate_exact_range_response(
483 Q42ByteRange {
484 offset: 3,
485 length: 4
486 },
487 10,
488 4,
489 4
490 )
491 .is_err());
492 }
493
494 #[test]
495 fn source_hash_verification_is_bounded_and_fail_closed() {
496 let mut file = NamedTempFile::new().unwrap();
497 file.write_all(b"0123456789").unwrap();
498 let source = LocalFileRangeSource::open(file.path()).unwrap();
499 let expected: [u8; 32] = Sha256::digest(b"0123456789").into();
500 let mut scratch = [0u8; 3];
501 verify_source_sha256(&source, &expected, &mut scratch).unwrap();
502 assert!(verify_source_sha256(&source, &[0; 32], &mut scratch).is_err());
503 }
504
505 #[test]
506 fn local_range_and_digest_hot_loops_are_zero_heap() {
507 let mut file = NamedTempFile::new().unwrap();
508 file.write_all(b"0123456789").unwrap();
509 let source = LocalFileRangeSource::open(file.path()).unwrap();
510 let expected: [u8; 32] = Sha256::digest(b"0123456789").into();
511 let mut read_buffer = [0u8; 4];
512 let mut digest_buffer = [0u8; 3];
513 assert_zero_alloc("q42_local_range_read", || {
514 source
515 .read_range_into(
516 Q42ByteRange {
517 offset: 3,
518 length: 4,
519 },
520 &mut read_buffer,
521 )
522 .unwrap();
523 });
524 assert_zero_alloc("q42_source_sha256", || {
525 verify_source_sha256(&source, &expected, &mut digest_buffer).unwrap();
526 });
527 }
528
529 #[cfg(not(target_arch = "wasm32"))]
530 #[test]
531 fn content_range_parser_rejects_mismatched_or_invalid_bounds() {
532 assert_eq!(parse_content_range("bytes 5-8/10").unwrap(), (5, 8, 10));
533 assert!(parse_content_range("bytes 8-5/10").is_err());
534 assert!(parse_content_range("bytes 5-10/10").is_err());
535 assert!(parse_content_range("items 5-8/10").is_err());
536 }
537
538 #[cfg(not(target_arch = "wasm32"))]
539 #[test]
540 fn ipfs_factory_requires_cid_locators_without_contacting_the_gateway() {
541 let factory = IpfsGatewaySegmentFactory::new("https://gateway.example").unwrap();
542 let local = Q42VolumeSegment {
543 locator: "segment.q42".into(),
544 byte_length: 1,
545 first_object_hash: 1,
546 last_object_hash: 1,
547 quin_count: 1,
548 sha256: [0; 32],
549 };
550 assert!(factory.open_segment(&local).is_err());
551 assert!(ipns_gateway_range_source("https://gateway.example", "bad/name").is_err());
552 }
553}