Module bao::encode

Encode some input bytes into the Bao format, or slice an existing encoding.

The Bao encoding format makes it possible to stream content bytes while verifying that they match the root hash. It also supports extracting encoded slices that can be verified apart from the rest of the encoding. This module handles the sending side of these operations. For the receiving side, see the decode module.

There are two modes of encoding, combined (the default) and outboard. The combined mode mixes subtree hashes together with the input bytes, producing a single file that can be decoded by itself. The outboard mode avoids copying any input bytes. The outboard encoding is much smaller, but it can only be used together with the original input file.

Example

use std::io::prelude::*;

let input = b"some input";
let expected_hash = bao::hash::hash(input);

let (hash, encoded_at_once) = bao::encode::encode_to_vec(b"some input");
assert_eq!(expected_hash, hash);

let mut encoded_incrementally = Vec::new();
{
    // The inner block here limits the lifetime of this mutable borrow.
    let encoded_cursor = std::io::Cursor::new(&mut encoded_incrementally);
    let mut encoder = bao::encode::Writer::new(encoded_cursor);
    encoder.write_all(b"some input")?;
    let hash = encoder.finish()?;
    assert_eq!(expected_hash, hash);
}

assert_eq!(encoded_at_once, encoded_incrementally);

Structs

SliceExtractor	An incremental slice extractor, which reads encoded bytes and produces a slice.
Writer	An incremental encoder. Note that you must call finish after you're done writing.

Functions

encode	Encode the input bytes in the combined mode. output.len() must be exactly encoded_size(input.len()).
encode_in_place	Encode the first content_len bytes from the input buffer in the combined mode, overwriting the input buffer. buf.len() must be exactly encoded_size(content_len as u64).
encode_outboard	Encode the input bytes in the outboard mode. output.len() must be exactly outboard_size(input.len()).
encode_outboard_to_vec	A convenience wrapper around encode_outboard, which allocates a new Vec to hold the encoding.
encode_to_vec	A convenience wrapper around encode, which allocates a new Vec to hold the encoding.
encoded_size	Compute the size of a combined encoding, given the size of the input. Note that for input sizes close to u64::MAX, the result can overflow a u64.
outboard_size	Compute the size of an outboard encoding, given the size of the input.