decdn-bao-range 0.0.1

Leaf crate: iroh-blobs-free bao verified-range helpers (chunk-group alignment, encoded-size, range encode/verify) shared by decdn-cache (serve/import) and decdn-client (receive). Depends only on bao-tree so the CLI's iroh-blobs-free invariant (#578) holds.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

//! The `(hash, total_bytes)` blob view every range-aware backend implements.
//!
//! [`RangedStore`] is what keeps this crate iroh-blobs-free: it speaks byte
//! offsets and `ChunkRanges` only, so the node's iroh-blobs cache and the
//! CLI's `.partial` sidecar can both satisfy it (#578).

/// A boxed future returned by a [`RangedStore`] method, borrowing the store
/// for `'a`.
pub type RangedFuture<'a, T> =
    core::pin::Pin<Box<dyn core::future::Future<Output = Result<T, RangedStoreError>> + Send + 'a>>;

/// What a [`RangedStore`] operation can fail with.
///
/// A variant that wraps a cause names only itself in `Display` and returns the
/// cause from `source()`, so a chain renderer (`{:#}` or `{:?}` on an
/// `anyhow::Error`, or a `source()` walk) prints each cause once. Render it
/// through one, not plain `Display`.
#[derive(Debug, thiserror::Error)]
pub enum RangedStoreError {
    /// The requested range is not chunk-group aligned, or does not verify
    /// against the outboard.
    #[error("range alignment")]
    Alignment(#[from] crate::RangeVerifyError),
    /// Finalization was asked for while ranges are still missing.
    #[error("blob is incomplete: cannot finalize")]
    Incomplete,
    /// The underlying store (file, blob store) failed.
    #[error("backend")]
    Backend(#[source] Box<dyn std::error::Error + Send + Sync>),
}

/// A source-agnostic, range-aware view of ONE blob `(hash, total_bytes)`.
/// Speaks `ChunkRanges` + byte offsets only — no hash type — so `bao-range`
/// stays iroh-blobs-free (#578). Both the node (iroh-blobs cache) and the
/// client (`.partial` sidecar) backends implement it and pass one shared
/// conformance suite.
pub trait RangedStore: Send + Sync {
    /// The blob length in bytes the store currently works to. A backend keyed
    /// by size fixes it at construction. A backend keyed by offset reports its
    /// current bound, which becomes the proven size once a verified final
    /// chunk proves one.
    fn total_bytes(&self) -> u64;
    /// Chunk ranges that verify right now.
    fn present_ranges(&self) -> RangedFuture<'_, bao_tree::ChunkRanges>;
    /// `[byte_offset, byte_offset+byte_len)` (`byte_len == 0` ⇒ to end) minus what is present.
    fn missing_ranges(
        &self,
        byte_offset: u64,
        byte_len: u64,
    ) -> RangedFuture<'_, bao_tree::ChunkRanges>;
    /// Verify the interleaved `bao_bytes` for `range` against the root in
    /// transit, write data + proof, record the range. Idempotent per range.
    fn admit(&self, range: crate::AlignedRange, bao_bytes: bytes::Bytes) -> RangedFuture<'_, ()>;
    /// Plaintext bytes for the held `[byte_offset, byte_offset+byte_len)` span.
    /// The returned span is collected into `Bytes`, so callers (e.g. a
    /// future gap-driven driver) should request gap-sized spans rather than
    /// whole blobs to stay O(gap) in memory.
    fn read(&self, byte_offset: u64, byte_len: u64) -> RangedFuture<'_, bytes::Bytes>;
    /// The whole blob is present.
    fn is_complete(&self) -> RangedFuture<'_, bool>;
    /// Whole-blob wrap-up: verify complete (+ promote/materialize on backends
    /// that need it). Errors `Incomplete` if any range is still missing.
    fn finalize(&self) -> RangedFuture<'_, ()>;
}

#[cfg(test)]
mod tests;