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 validated 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::*;
use std::io::Cursor;

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

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

let mut encoded_incrementally = Vec::new();
let mut encoder = bao::encode::Encoder::new(Cursor::new(&mut encoded_incrementally));
encoder.write_all(b"some input")?;
let hash = encoder.finalize()?;
assert_eq!(expected_hash, hash);

assert_eq!(encoded_at_once, encoded_incrementally);

Structs

Encoder

An incremental encoder. Note that you must call finalize after you’re done writing.

SliceExtractor

An incremental slice extractor, which reads encoded bytes and produces a slice.

Functions

encode

Encode an entire slice into a bytes vector in the default combined mode. This is a convenience wrapper around Encoder::write_all.

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

Encode an entire slice into a bytes vector in the outboard mode. This is a convenience wrapper around Encoder::new_outboard and Encoder::write_all.

outboard_size

Compute the size of an outboard encoding, given the size of the input.