Skip to main content

qualia_core_db/q42/volume/
range.rs

1//! Transport-neutral, caller-buffered byte-range access.
2//!
3//! HTTP gateways and IPFS partial-CAR retrieval must obey this same exact-range
4//! contract. The local file adapter is both useful itself and the reference
5//! implementation for response-length and boundary validation.
6
7#[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
22/// Build an `InvalidData` io::Error for malformed range-source
23/// content.
24fn invalid(message: impl Into<String>) -> io::Error {
25    io::Error::new(io::ErrorKind::InvalidInput, message.into())
26}
27
28/// A half-open byte interval, represented without an end-offset overflow.
29#[derive(Clone, Copy, Debug, Eq, PartialEq)]
30pub struct Q42ByteRange {
31    pub offset: u64,
32    pub length: usize,
33}
34
35impl Q42ByteRange {
36    /// Exclusive end offset; errors on u64 overflow.
37    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    /// Bounds-check the range against `source_length`.
44    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
52/// Exact, caller-buffered random access. Implementations must fail if the
53/// source returns a short response; partial data is never treated as success.
54pub trait Q42RangeSource {
55    /// Total byte length of the source.
56    fn length(&self) -> io::Result<u64>;
57    /// Fill `out` with exactly `range.length` bytes at `range.offset` —
58    /// exact-fit contract, short responses must error.
59    fn read_range_into(&self, range: Q42ByteRange, out: &mut [u8]) -> io::Result<()>;
60}
61
62/// Native local-file implementation. The mutex serialises seek/read pairs;
63/// high-concurrency remote adapters should instead use independent requests.
64#[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    /// Open `path` and capture its length once (immutable-source
73    /// contract — the length is not re-polled).
74    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    /// The length captured at `open`.
87    fn length(&self) -> io::Result<u64> {
88        Ok(self.length)
89    }
90
91    /// Exact-fit `pread` under the seek mutex — bounds-checked against
92    /// the captured length.
93    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
109/// Validate an HTTP/IPFS adapter response before it is accepted by a reader.
110/// `content_range_start` is the start declared by `Content-Range` or the
111/// verified CAR block offset; `returned_len` is its actual payload size.
112pub 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
128/// Stream the complete immutable source through a caller-provided scratch
129/// buffer and compare it to the SHA-256 committed by the root descriptor.
130/// This is the bounded verification path for a trusted HTTP/IPFS gateway;
131/// partial-CAR block proofs can later authenticate individual ranges sooner.
132pub 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/// Native HTTP byte-range source for trusted gateways. It never accepts a
169/// `200 OK` full-body fallback: large Q42 access must stay range-bounded.
170#[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    /// Source with a caller-attested byte length (e.g. from a manifest)
180    /// — http/https only, 10s connect / 30s request timeouts.
181    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    /// Discover an immutable source length without downloading its body. This
203    /// is a cold construction operation used for a root URL (including IPNS).
204    /// Gateways that omit `Content-Length` on HEAD must still prove a one-byte
205    /// `206` range response before they are accepted.
206    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    /// The attested source length.
262    fn length(&self) -> io::Result<u64> {
263        Ok(self.length)
264    }
265
266    /// HTTP GET with `Range: bytes=…`; requires a 206 whose
267    /// `Content-Range` exactly matches the request and the catalog
268    /// length — anything else fails closed.
269    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"))]
338/// `HttpRangeSource` for `{gateway}/ipfs/{cid}` — CID must be a
339/// non-empty alphanumeric token; `length` stays caller-attested.
340pub 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/// Construct a range source for an IPNS-published root. Resolution is bounded
353/// by the HTTP adapter's 10-second connect and 30-second request timeouts;
354/// after the root manifest is read, child segments must use immutable CIDs.
355#[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/// Opens manifest `ipfs://CID` child locators through one configured gateway.
369/// The CID and byte length remain manifest-committed; the gateway is merely a
370/// transport route and cannot substitute a different-length object.
371#[cfg(not(target_arch = "wasm32"))]
372pub struct IpfsGatewaySegmentFactory {
373    gateway: String,
374}
375
376#[cfg(not(target_arch = "wasm32"))]
377impl IpfsGatewaySegmentFactory {
378    /// Bind the factory to an http/https gateway URL.
379    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    /// Open an `ipfs://CID` locator through the gateway; the manifest-
397    /// committed byte length travels with the segment.
398    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    /// Open an `ipfs://CID` lexicon-shard locator through the gateway.
411    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"))]
423/// Parse `Content-Range: bytes start-end/total` — rejects malformed
424/// units, intervals, and out-of-bounds ends.
425fn 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}