Expand description
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
An incremental slice extractor, which reads encoded bytes and produces a slice.
An incremental encoder. Note that you must call
finish
after you’re done writing.Functions
Encode the input bytes in the combined mode.
output.len()
must be exactly
encoded_size(input.len())
.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 the input bytes in the outboard mode.
output.len()
must be exactly
outboard_size(input.len())
.A convenience wrapper around
encode_outboard
, which allocates a new Vec
to hold the
encoding.A convenience wrapper around
encode
, which allocates a new Vec
to hold the encoding.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
.Compute the size of an outboard encoding, given the size of the input.