Skip to main content

qualia_core_db/bundle/stream/http/
range.rs

1//! Single nonempty inclusive byte range. Headers are the adapter surface.
2//! `end = start + length - 1`. Multipart and `bytes */` are not 206 data.
3
4/// Architecture ยง6: legacy whole-object HTTP fallback, explicit policy only.
5pub const LEGACY_FULL_OBJECT_FALLBACK_BYTES: u64 = 1 << 20;
6
7#[derive(Clone, Copy, Debug, PartialEq, Eq)]
8pub enum RangeError {
9    Empty,
10    Overflow,
11    Syntax,
12    Multipart,
13    Unit,
14    Unsatisfiable,
15    Mismatch,
16    Encoding,
17    Capacity,
18}
19
20/// Inclusive nonempty range stored as start+length so `end` cannot wrap.
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub struct InclusiveRange {
23    start: u64,
24    length: u64,
25}
26
27impl InclusiveRange {
28    pub fn from_start_length(start: u64, length: u64) -> Result<Self, RangeError> {
29        if length == 0 {
30            return Err(RangeError::Empty);
31        }
32        let _end = start
33            .checked_add(length - 1)
34            .ok_or(RangeError::Overflow)?;
35        Ok(Self { start, length })
36    }
37
38    pub const fn start(self) -> u64 {
39        self.start
40    }
41
42    pub const fn length(self) -> u64 {
43        self.length
44    }
45
46    /// Inclusive end. Safe: constructor checked `start + length - 1`.
47    pub const fn end(self) -> u64 {
48        self.start + self.length - 1
49    }
50
51    pub const fn fits(self, total: u64) -> bool {
52        self.length != 0 && self.end() < total
53    }
54}
55
56pub(super) fn trim_ows(s: &[u8]) -> &[u8] {
57    let mut a = 0;
58    let mut b = s.len();
59    while a < b && (s[a] == b' ' || s[a] == b'\t') {
60        a += 1;
61    }
62    while b > a && (s[b - 1] == b' ' || s[b - 1] == b'\t') {
63        b -= 1;
64    }
65    &s[a..b]
66}
67
68pub(super) fn eq_ignore_ascii_case(a: &[u8], b: &[u8]) -> bool {
69    a.len() == b.len()
70        && a.iter()
71            .zip(b)
72            .all(|(x, y)| x.to_ascii_lowercase() == y.to_ascii_lowercase())
73}
74
75pub(super) fn starts_ignore_ascii_case(s: &[u8], prefix: &[u8]) -> bool {
76    s.len() >= prefix.len() && eq_ignore_ascii_case(&s[..prefix.len()], prefix)
77}
78
79pub(super) fn parse_u64_ascii(s: &[u8]) -> Result<u64, RangeError> {
80    if s.is_empty() {
81        return Err(RangeError::Syntax);
82    }
83    let mut n = 0u64;
84    for &c in s {
85        if !c.is_ascii_digit() {
86            return Err(RangeError::Syntax);
87        }
88        n = n.checked_mul(10).ok_or(RangeError::Overflow)?;
89        n = n
90            .checked_add(u64::from(c - b'0'))
91            .ok_or(RangeError::Overflow)?;
92    }
93    Ok(n)
94}
95
96pub(super) fn write_u64_ascii(n: u64, out: &mut [u8]) -> Result<usize, RangeError> {
97    let mut tmp = [0u8; 20];
98    let mut i = tmp.len();
99    let mut v = n;
100    loop {
101        i -= 1;
102        tmp[i] = b'0' + (v % 10) as u8;
103        v /= 10;
104        if v == 0 {
105            break;
106        }
107    }
108    let len = tmp.len() - i;
109    if out.len() < len {
110        return Err(RangeError::Capacity);
111    }
112    out[..len].copy_from_slice(&tmp[i..]);
113    Ok(len)
114}
115
116pub(super) fn write_hex_lower(bytes: &[u8], out: &mut [u8]) -> Result<usize, RangeError> {
117    const HEX: &[u8; 16] = b"0123456789abcdef";
118    let n = bytes.len().checked_mul(2).ok_or(RangeError::Overflow)?;
119    if out.len() < n {
120        return Err(RangeError::Capacity);
121    }
122    for (i, &b) in bytes.iter().enumerate() {
123        out[i * 2] = HEX[(b >> 4) as usize];
124        out[i * 2 + 1] = HEX[(b & 0x0f) as usize];
125    }
126    Ok(n)
127}
128
129fn skip_bytes_unit(value: &[u8], sep: u8) -> Result<&[u8], RangeError> {
130    let v = trim_ows(value);
131    if v.iter().any(|&c| c == b',') {
132        return Err(RangeError::Multipart);
133    }
134    if !starts_ignore_ascii_case(v, b"bytes") {
135        return Err(RangeError::Unit);
136    }
137    let rest = &v[b"bytes".len()..];
138    if rest.first().copied() != Some(sep) {
139        return Err(RangeError::Unit);
140    }
141    Ok(&rest[1..])
142}
143
144/// Parse `bytes=start-end` only. Open-end, suffix, star, and lists are R1 refusals.
145pub fn parse_range_spec(value: &[u8]) -> Result<InclusiveRange, RangeError> {
146    let spec = skip_bytes_unit(value, b'=')?;
147    let spec = trim_ows(spec);
148    if spec == b"*" || spec.first() == Some(&b'-') {
149        return Err(RangeError::Unsatisfiable);
150    }
151    let dash = spec.iter().position(|&c| c == b'-').ok_or(RangeError::Syntax)?;
152    let start = parse_u64_ascii(trim_ows(&spec[..dash]))?;
153    let end_bytes = trim_ows(&spec[dash + 1..]);
154    if end_bytes.is_empty() {
155        return Err(RangeError::Syntax);
156    }
157    let end = parse_u64_ascii(end_bytes)?;
158    if end < start {
159        return Err(RangeError::Syntax);
160    }
161    let length = end
162        .checked_sub(start)
163        .and_then(|d| d.checked_add(1))
164        .ok_or(RangeError::Overflow)?;
165    InclusiveRange::from_start_length(start, length)
166}
167
168#[derive(Clone, Copy, Debug, PartialEq, Eq)]
169pub enum ContentRange {
170    Satisfied { range: InclusiveRange, total: u64 },
171    /// 416 metadata only. Never a 206 body.
172    Unsatisfiable { total: u64 },
173}
174
175/// Parse `bytes start-end/total` or 416 `bytes */total`. No extra interior spaces.
176pub fn parse_content_range_value(value: &[u8]) -> Result<ContentRange, RangeError> {
177    let spec = skip_bytes_unit(value, b' ')?;
178    let slash = spec.iter().position(|&c| c == b'/').ok_or(RangeError::Syntax)?;
179    let range = &spec[..slash];
180    let total = parse_u64_ascii(&spec[slash + 1..])?;
181    if range == b"*" {
182        return Ok(ContentRange::Unsatisfiable { total });
183    }
184    let dash = range.iter().position(|&c| c == b'-').ok_or(RangeError::Syntax)?;
185    let start = parse_u64_ascii(&range[..dash])?;
186    let end = parse_u64_ascii(&range[dash + 1..])?;
187    if end < start {
188        return Err(RangeError::Syntax);
189    }
190    let length = end
191        .checked_sub(start)
192        .and_then(|d| d.checked_add(1))
193        .ok_or(RangeError::Overflow)?;
194    let incl = InclusiveRange::from_start_length(start, length)?;
195    if !incl.fits(total) {
196        return Err(RangeError::Unsatisfiable);
197    }
198    Ok(ContentRange::Satisfied { range: incl, total })
199}
200
201pub fn require_exact_partial(
202    value: &[u8],
203    requested: InclusiveRange,
204    pinned_total: u64,
205) -> Result<(), RangeError> {
206    match parse_content_range_value(value)? {
207        ContentRange::Satisfied { range, total } => {
208            if range != requested || total != pinned_total {
209                Err(RangeError::Mismatch)
210            } else {
211                Ok(())
212            }
213        }
214        ContentRange::Unsatisfiable { .. } => Err(RangeError::Unsatisfiable),
215    }
216}
217
218pub fn parse_unsatisfiable_total(value: &[u8]) -> Result<u64, RangeError> {
219    match parse_content_range_value(value)? {
220        ContentRange::Unsatisfiable { total } => Ok(total),
221        ContentRange::Satisfied { .. } => Err(RangeError::Mismatch),
222    }
223}
224
225pub fn write_range_header(range: InclusiveRange, out: &mut [u8]) -> Result<usize, RangeError> {
226    // bytes=start-end
227    if out.len() < 6 {
228        return Err(RangeError::Capacity);
229    }
230    out[..6].copy_from_slice(b"bytes=");
231    let mut n = 6;
232    n += write_u64_ascii(range.start(), &mut out[n..])?;
233    if n >= out.len() {
234        return Err(RangeError::Capacity);
235    }
236    out[n] = b'-';
237    n += 1;
238    n += write_u64_ascii(range.end(), &mut out[n..])?;
239    Ok(n)
240}
241
242pub fn write_content_range(
243    range: InclusiveRange,
244    total: u64,
245    out: &mut [u8],
246) -> Result<usize, RangeError> {
247    if !range.fits(total) {
248        return Err(RangeError::Unsatisfiable);
249    }
250    if out.len() < 6 {
251        return Err(RangeError::Capacity);
252    }
253    out[..6].copy_from_slice(b"bytes ");
254    let mut n = 6;
255    n += write_u64_ascii(range.start(), &mut out[n..])?;
256    if n >= out.len() {
257        return Err(RangeError::Capacity);
258    }
259    out[n] = b'-';
260    n += 1;
261    n += write_u64_ascii(range.end(), &mut out[n..])?;
262    if n >= out.len() {
263        return Err(RangeError::Capacity);
264    }
265    out[n] = b'/';
266    n += 1;
267    n += write_u64_ascii(total, &mut out[n..])?;
268    Ok(n)
269}
270
271pub fn write_unsatisfiable_content_range(total: u64, out: &mut [u8]) -> Result<usize, RangeError> {
272    if out.len() < 8 {
273        return Err(RangeError::Capacity);
274    }
275    out[..8].copy_from_slice(b"bytes */");
276    let n = 8 + write_u64_ascii(total, &mut out[8..])?;
277    Ok(n)
278}
279
280/// Absent or exact `identity`. Any transform (gzip, lists) is a refusal.
281pub fn encoding_is_identity(value: Option<&[u8]>) -> bool {
282    match value {
283        None => true,
284        Some(v) => eq_ignore_ascii_case(trim_ows(v), b"identity"),
285    }
286}
287
288pub fn content_type_is_multipart(value: Option<&[u8]>) -> bool {
289    match value {
290        None => false,
291        Some(v) => starts_ignore_ascii_case(trim_ows(v), b"multipart/"),
292    }
293}