Skip to main content

qualia_core_db/bundle/stream/http/
provider.rs

1//! Serve descriptor / pages / encode_proof / representation bytes.
2//! HTTP status is not a grant. Charge the existing ReservationLedger.
3
4use super::range::{
5    write_content_range, write_hex_lower, write_u64_ascii, write_unsatisfiable_content_range,
6    InclusiveRange, RangeError, LEGACY_FULL_OBJECT_FALLBACK_BYTES,
7};
8use super::status::{
9    strong_etag, write_strong_etag, FallbackPolicy, StatusError, Validator,
10};
11use crate::bundle::stream::policy::LocalEffectControl;
12use crate::bundle::stream::proof::{
13    decode_proof, verify_leaf, ProofError, LEAF_BYTES, MAX_SIBLINGS,
14};
15use crate::bundle::stream::selection::SelectedPlainEntry;
16use crate::net::peer::replication::qbdl::provider::{OutboardCatalog, OutboardError};
17use crate::net::peer::runtime::{ReservationHandle, ReservationLedger, ResourceBudget};
18use crate::net::qdnf::errors::QdnfError;
19use crate::net::qdnf::types::StrongDigest;
20
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub enum ProviderError {
23    Identity,
24    Policy,
25    Unsupported,
26    Unsatisfiable,
27    ChangedValidator,
28    Encoding,
29    Capacity,
30    Bounds,
31    Proof,
32    Budget,
33    Ledger(QdnfError),
34    Status(StatusError),
35    Range(RangeError),
36}
37
38impl From<RangeError> for ProviderError {
39    fn from(e: RangeError) -> Self {
40        match e {
41            RangeError::Unsatisfiable => Self::Unsatisfiable,
42            RangeError::Capacity => Self::Capacity,
43            other => Self::Range(other),
44        }
45    }
46}
47
48impl From<ProofError> for ProviderError {
49    fn from(_: ProofError) -> Self {
50        Self::Proof
51    }
52}
53
54impl From<OutboardError> for ProviderError {
55    fn from(e: OutboardError) -> Self {
56        match e {
57            OutboardError::Identity => Self::Identity,
58            OutboardError::Capacity => Self::Capacity,
59            OutboardError::Proof(_) => Self::Proof,
60            _ => Self::Bounds,
61        }
62    }
63}
64
65#[derive(Clone, Copy, Debug, PartialEq, Eq)]
66pub enum HttpObject {
67    Descriptor,
68    Page,
69    Proof { leaf: u64 },
70    Representation,
71}
72
73#[derive(Clone, Copy, Debug, PartialEq, Eq)]
74pub struct ServeOptions {
75    pub fallback: FallbackPolicy,
76    pub verified_peer: bool,
77}
78
79pub struct HttpProvider<'src, 'sel, 'nodes, 'meta> {
80    source: &'src [u8],
81    catalog: OutboardCatalog<'sel, 'nodes>,
82    descriptor: &'meta [u8],
83    entry_page: &'meta [u8],
84}
85
86pub struct ServedHeaders {
87    pub status: u16,
88    pub content_range: [u8; 80],
89    pub content_range_len: usize,
90    pub content_length: u64,
91    pub etag: [u8; 98],
92    pub etag_len: usize,
93}
94
95pub struct Served {
96    pub status: u16,
97    pub total: u64,
98    pub body_len: usize,
99    pub headers: ServedHeaders,
100    pub charge: Option<ReservationHandle>,
101}
102
103impl<'src, 'sel, 'nodes, 'meta> HttpProvider<'src, 'sel, 'nodes, 'meta> {
104    pub fn bind(
105        source: &'src [u8],
106        catalog: OutboardCatalog<'sel, 'nodes>,
107        descriptor: &'meta [u8],
108        entry_page: &'meta [u8],
109    ) -> Result<Self, ProviderError> {
110        let selected = catalog.selected();
111        let start = usize::try_from(selected.offset()).map_err(|_| ProviderError::Bounds)?;
112        let len = usize::try_from(selected.logical_length()).map_err(|_| ProviderError::Bounds)?;
113        let end = start.checked_add(len).ok_or(ProviderError::Bounds)?;
114        if end > source.len() {
115            return Err(ProviderError::Identity);
116        }
117        if descriptor.is_empty() || entry_page.is_empty() {
118            return Err(ProviderError::Identity);
119        }
120        Ok(Self {
121            source,
122            catalog,
123            descriptor,
124            entry_page,
125        })
126    }
127
128    pub fn selected(&self) -> SelectedPlainEntry<'sel> {
129        self.catalog.selected()
130    }
131
132    pub fn representation_etag(&self, out: &mut [u8]) -> Result<usize, ProviderError> {
133        Ok(write_strong_etag(self.catalog.selected().root(), out)?)
134    }
135
136    /// Deployment convention, not a registry allocation.
137    pub fn write_path(&self, object: HttpObject, out: &mut [u8]) -> Result<usize, ProviderError> {
138        let id = self.catalog.selected().candidate_identity().descriptor_id();
139        write_object_path(object, id, self.catalog.selected().entry_id(), out)
140    }
141
142    pub fn serve(
143        &self,
144        object: HttpObject,
145        range: Option<InclusiveRange>,
146        if_range: Option<&[u8]>,
147        expected: Validator<'_>,
148        options: ServeOptions,
149        authority: &mut LocalEffectControl<'_, '_>,
150        ledger: &mut ReservationLedger,
151        out: &mut [u8],
152    ) -> Result<Served, ProviderError> {
153        if let HttpObject::Proof { leaf } = object {
154            return serve_proof_into(
155                self, leaf, if_range, expected, options, authority, ledger, out,
156            );
157        }
158        if authority.closure().identity() != self.catalog.selected().candidate_identity() {
159            return Err(ProviderError::Identity);
160        }
161        authority.recheck().map_err(|_| ProviderError::Policy)?;
162
163        let (bytes, etag_digest) = self.object_bytes(object)?;
164        let total = bytes.len() as u64;
165        let mut etag = [0u8; 98];
166        let etag_len = write_strong_etag(etag_digest, &mut etag)?;
167        check_validators(&etag[..etag_len], if_range, expected)?;
168
169        let decided = decide_range(range, total, options.fallback)?;
170        match decided {
171            Decision::Unsatisfiable => {
172                let mut headers = empty_headers(416);
173                headers.etag = etag;
174                headers.etag_len = etag_len;
175                headers.content_range_len =
176                    write_unsatisfiable_content_range(total, &mut headers.content_range)?;
177                Ok(Served {
178                    status: 416,
179                    total,
180                    body_len: 0,
181                    headers,
182                    charge: None,
183                })
184            }
185            Decision::Partial(incl) | Decision::Full(incl) => {
186                let start = usize::try_from(incl.start()).map_err(|_| ProviderError::Bounds)?;
187                let n = usize::try_from(incl.length()).map_err(|_| ProviderError::Bounds)?;
188                let end = start.checked_add(n).ok_or(ProviderError::Bounds)?;
189                if end > bytes.len() || n > out.len() {
190                    return Err(ProviderError::Capacity);
191                }
192                let status = if matches!(decided, Decision::Full(_)) {
193                    200
194                } else {
195                    206
196                };
197                let charge = ledger
198                    .reserve(
199                        ResourceBudget {
200                            bytes: n as u64,
201                            work: 1,
202                            io: 1,
203                        },
204                        options.verified_peer,
205                    )
206                    .map_err(|e| {
207                        if e == QdnfError::BudgetExhausted {
208                            ProviderError::Budget
209                        } else {
210                            ProviderError::Ledger(e)
211                        }
212                    })?;
213                out[..n].copy_from_slice(&bytes[start..end]);
214                let mut headers = empty_headers(status);
215                headers.etag = etag;
216                headers.etag_len = etag_len;
217                headers.content_length = n as u64;
218                headers.content_range_len = write_content_range(incl, total, &mut headers.content_range)?;
219                Ok(Served {
220                    status,
221                    total,
222                    body_len: n,
223                    headers,
224                    charge: Some(charge),
225                })
226            }
227        }
228    }
229
230    fn object_bytes(&self, object: HttpObject) -> Result<(&[u8], StrongDigest), ProviderError> {
231        let selected = self.catalog.selected();
232        match object {
233            HttpObject::Descriptor => Ok((
234                self.descriptor,
235                selected.candidate_identity().descriptor_id(),
236            )),
237            HttpObject::Page => Ok((self.entry_page, selected.root())),
238            HttpObject::Representation => {
239                let start = usize::try_from(selected.offset()).map_err(|_| ProviderError::Bounds)?;
240                let len =
241                    usize::try_from(selected.logical_length()).map_err(|_| ProviderError::Bounds)?;
242                Ok((&self.source[start..start + len], selected.root()))
243            }
244            HttpObject::Proof { .. } => Err(ProviderError::Unsupported),
245        }
246    }
247}
248
249/// Proof bytes cannot borrow a stack buffer. Encode into `out` directly.
250pub fn serve_proof_into(
251    provider: &HttpProvider<'_, '_, '_, '_>,
252    leaf: u64,
253    if_range: Option<&[u8]>,
254    expected: Validator<'_>,
255    options: ServeOptions,
256    authority: &mut LocalEffectControl<'_, '_>,
257    ledger: &mut ReservationLedger,
258    out: &mut [u8],
259) -> Result<Served, ProviderError> {
260    if authority.closure().identity() != provider.catalog.selected().candidate_identity() {
261        return Err(ProviderError::Identity);
262    }
263    authority.recheck().map_err(|_| ProviderError::Policy)?;
264    let selected = provider.catalog.selected();
265    let spec = *provider.catalog.tree_spec();
266    let payload_len = spec.logical_leaf_length(leaf)?;
267    let leaf_off = leaf.checked_mul(LEAF_BYTES).ok_or(ProviderError::Bounds)?;
268    let start = selected
269        .offset()
270        .checked_add(leaf_off)
271        .ok_or(ProviderError::Bounds)?;
272    let start = usize::try_from(start).map_err(|_| ProviderError::Bounds)?;
273    let end = start
274        .checked_add(payload_len)
275        .ok_or(ProviderError::Bounds)?;
276    if end > provider.source.len() {
277        return Err(ProviderError::Identity);
278    }
279    let payload = &provider.source[start..end];
280    let mut encoded = [0u8; 1 + MAX_SIBLINGS * 48];
281    let mut siblings = [StrongDigest::ZERO; MAX_SIBLINGS];
282    // `proof_into` encodes via canonical `encode_proof`; this module has no second codec.
283    let n = provider
284        .catalog
285        .proof_into(leaf, &mut encoded, &mut siblings)?;
286    let mut decoded = [StrongDigest::ZERO; MAX_SIBLINGS];
287    let path = decode_proof(&encoded[..n], &mut decoded)?;
288    verify_leaf(&spec, selected.root(), leaf, payload, path)?;
289
290    let mut etag = [0u8; 98];
291    let etag_len = write_strong_etag(selected.root(), &mut etag)?;
292    check_validators(&etag[..etag_len], if_range, expected)?;
293
294    let total = n as u64;
295    let incl = InclusiveRange::from_start_length(0, total)?;
296    if n > out.len() {
297        return Err(ProviderError::Capacity);
298    }
299    let ServeOptions {
300        fallback: _,
301        verified_peer,
302    } = options;
303    let charge = ledger
304        .reserve(
305            ResourceBudget {
306                bytes: total,
307                work: 1,
308                io: 1,
309            },
310            verified_peer,
311        )
312        .map_err(|e| {
313            if e == QdnfError::BudgetExhausted {
314                ProviderError::Budget
315            } else {
316                ProviderError::Ledger(e)
317            }
318        })?;
319    out[..n].copy_from_slice(&encoded[..n]);
320    let mut headers = empty_headers(206);
321    headers.etag = etag;
322    headers.etag_len = etag_len;
323    headers.content_length = total;
324    headers.content_range_len = write_content_range(incl, total, &mut headers.content_range)?;
325    Ok(Served {
326        status: 206,
327        total,
328        body_len: n,
329        headers,
330        charge: Some(charge),
331    })
332}
333
334enum Decision {
335    Partial(InclusiveRange),
336    Full(InclusiveRange),
337    Unsatisfiable,
338}
339
340fn decide_range(
341    range: Option<InclusiveRange>,
342    total: u64,
343    fallback: FallbackPolicy,
344) -> Result<Decision, ProviderError> {
345    match range {
346        Some(r) if r.fits(total) => Ok(Decision::Partial(r)),
347        Some(_) => Ok(Decision::Unsatisfiable),
348        None => {
349            if !fallback.allow_full_object
350                || total == 0
351                || total > fallback.max_full_object_bytes
352                || total > LEGACY_FULL_OBJECT_FALLBACK_BYTES
353            {
354                return Err(ProviderError::Budget);
355            }
356            Ok(Decision::Full(InclusiveRange::from_start_length(0, total)?))
357        }
358    }
359}
360
361fn check_validators(
362    etag: &[u8],
363    if_range: Option<&[u8]>,
364    expected: Validator<'_>,
365) -> Result<(), ProviderError> {
366    if let Some(tag) = if_range {
367        let got = strong_etag(tag).ok_or(ProviderError::ChangedValidator)?;
368        if got != etag {
369            return Err(ProviderError::ChangedValidator);
370        }
371    }
372    if let Some(want) = expected.etag {
373        if want != etag {
374            return Err(ProviderError::ChangedValidator);
375        }
376    }
377    Ok(())
378}
379
380fn empty_headers(status: u16) -> ServedHeaders {
381    ServedHeaders {
382        status,
383        content_range: [0; 80],
384        content_range_len: 0,
385        content_length: 0,
386        etag: [0; 98],
387        etag_len: 0,
388    }
389}
390
391pub fn write_object_path(
392    object: HttpObject,
393    descriptor: StrongDigest,
394    entry: u32,
395    out: &mut [u8],
396) -> Result<usize, ProviderError> {
397    let mut n = 0;
398    fn put(out: &mut [u8], n: &mut usize, b: &[u8]) -> Result<(), ProviderError> {
399        let end = n.checked_add(b.len()).ok_or(ProviderError::Capacity)?;
400        if end > out.len() {
401            return Err(ProviderError::Capacity);
402        }
403        out[*n..end].copy_from_slice(b);
404        *n = end;
405        Ok(())
406    }
407    put(out, &mut n, b"/objects/")?;
408    if n + 96 > out.len() {
409        return Err(ProviderError::Capacity);
410    }
411    n += write_hex_lower(&descriptor.0, &mut out[n..])?;
412    match object {
413        HttpObject::Descriptor => put(out, &mut n, b"/descriptor")?,
414        HttpObject::Page => put(out, &mut n, b"/pages/0")?,
415        HttpObject::Representation => {
416            put(out, &mut n, b"/representations/")?;
417            n += write_u64_ascii(entry as u64, &mut out[n..])?;
418        }
419        HttpObject::Proof { leaf } => {
420            put(out, &mut n, b"/entries/")?;
421            n += write_u64_ascii(entry as u64, &mut out[n..])?;
422            put(out, &mut n, b"/proof/")?;
423            n += write_u64_ascii(leaf, &mut out[n..])?;
424        }
425    }
426    Ok(n)
427}
428
429pub fn write_http_head(headers: &ServedHeaders, out: &mut [u8]) -> Result<usize, ProviderError> {
430    let mut n = 0;
431    fn put(out: &mut [u8], n: &mut usize, b: &[u8]) -> Result<(), ProviderError> {
432        let end = n.checked_add(b.len()).ok_or(ProviderError::Capacity)?;
433        if end > out.len() {
434            return Err(ProviderError::Capacity);
435        }
436        out[*n..end].copy_from_slice(b);
437        *n = end;
438        Ok(())
439    }
440    put(out, &mut n, b"HTTP/1.1 ")?;
441    n += write_u64_ascii(headers.status as u64, &mut out[n..])?;
442    let reason: &[u8] = match headers.status {
443        200 => b" OK\r\n",
444        206 => b" Partial Content\r\n",
445        416 => b" Range Not Satisfiable\r\n",
446        _ => b"\r\n",
447    };
448    put(out, &mut n, reason)?;
449    put(out, &mut n, b"Content-Encoding: identity\r\nAccept-Ranges: bytes\r\n")?;
450    if headers.content_range_len > 0 {
451        put(out, &mut n, b"Content-Range: ")?;
452        put(out, &mut n, &headers.content_range[..headers.content_range_len])?;
453        put(out, &mut n, b"\r\n")?;
454    }
455    put(out, &mut n, b"Content-Length: ")?;
456    n += write_u64_ascii(headers.content_length, &mut out[n..])?;
457    put(out, &mut n, b"\r\n")?;
458    if headers.etag_len > 0 {
459        put(out, &mut n, b"ETag: ")?;
460        put(out, &mut n, &headers.etag[..headers.etag_len])?;
461        put(out, &mut n, b"\r\n")?;
462    }
463    put(out, &mut n, b"Connection: close\r\n\r\n")?;
464    Ok(n)
465}