heddle-object-model 0.15.0

Heddle's content-addressed object model and stable codecs.
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

// SPDX-License-Identifier: Apache-2.0

use super::{
    Result,
    io::{Reader, Writer},
    limits::{MAX_COMPACT_COUNT, MIN_BLOB_ITEM_BYTES},
};
use crate::object::ContentHash;

const BLOB_MAGIC: &[u8; 4] = b"HCB2";

/// One verified blob slice within a lineage-solid frame.
pub type DecodedBlob<'a> = (ContentHash, &'a [u8]);

/// Whether `bytes` begin with the lineage-solid blob-frame discriminator.
pub fn is_blob_frame(bytes: &[u8]) -> bool {
    bytes.starts_with(BLOB_MAGIC)
}

/// Encode blob bodies newest-to-oldest in one checksummed solid frame.
///
/// Lengths precede the concatenated bodies, giving the frame reader an exact
/// `(offset, len)` for every object while zstd sees one continuous lineage.
pub fn encode_blob_frame(blobs: &[&[u8]]) -> Result<Vec<u8>> {
    if blobs.len() > MAX_COMPACT_COUNT {
        return Err(super::invalid(format!(
            "blob frame count {} exceeds maximum {MAX_COMPACT_COUNT}",
            blobs.len()
        )));
    }
    let mut output = Writer::new(BLOB_MAGIC);
    output.put_u64(blobs.len() as u64);
    if let Some((first, rest)) = blobs.split_first() {
        output.put_u64(first.len() as u64);
        let mut previous = i64::try_from(first.len())
            .map_err(|_| super::invalid("blob length exceeds signed delta range"))?;
        for blob in rest {
            let current = i64::try_from(blob.len())
                .map_err(|_| super::invalid("blob length exceeds signed delta range"))?;
            output.put_i64(current - previous);
            previous = current;
        }
    }
    for blob in blobs {
        output.put_fixed(blob);
    }
    Ok(output.finish())
}

/// Decode and whole-frame-verify every indexed blob slice.
pub fn decode_blob_frame(bytes: &[u8]) -> Result<Vec<DecodedBlob<'_>>> {
    let mut input = Reader::verified(bytes, BLOB_MAGIC)?;
    let count = input.get_count("blob frame", MIN_BLOB_ITEM_BYTES)?;
    let mut lengths = Vec::with_capacity(count);
    if count > 0 {
        let first = input.get_u64()?;
        lengths.push(checked_length(first)?);
        let mut previous = i64::try_from(first)
            .map_err(|_| super::invalid("blob length exceeds signed delta range"))?;
        for _ in 1..count {
            let current = previous
                .checked_add(input.get_i64()?)
                .ok_or_else(|| super::invalid("blob length delta overflow"))?;
            if current < 0 {
                return Err(super::invalid("blob length delta became negative"));
            }
            lengths.push(checked_length(current as u64)?);
            previous = current;
        }
    }
    let minimum_remaining = lengths
        .iter()
        .try_fold(0usize, |total, len| total.checked_add(*len))
        .ok_or_else(|| super::invalid("blob frame length overflow"))?;
    if input.remaining() != minimum_remaining {
        return Err(super::invalid(format!(
            "blob lengths total {minimum_remaining}, frame has {} body bytes",
            input.remaining()
        )));
    }
    let mut blobs = Vec::with_capacity(count);
    for len in lengths {
        let body = input.take(len)?;
        blobs.push((ContentHash::compute_typed("blob", body), body));
    }
    input.finish()?;
    Ok(blobs)
}

fn checked_length(value: u64) -> Result<usize> {
    usize::try_from(value).map_err(|_| super::invalid("blob length exceeds platform limits"))
}