Struct RootToLeavesValidator 

pub struct RootToLeavesValidator {
    root_digest: B3Digest,
    referenced_directories: HashMap<B3Digest, u64>,
    pending_directories: HashSet<B3Digest>,
    poison: bool,
}

A struct holding state while consuming a sequence of Directories in Root-To-Leaves order.

It allows querying whether a certain digest could be acceptable (to be able to skip parsing entirely if present in serialized form)

Validates that newly received directories are already referenced from the root via existing directories. It also ensures the actual directory sizes are the same as the sizes communicated previously alongside the pointers. Commonly used when receiving a directory closure from a store.

Internally keeps a list of digests introduced (pointers in previously received directories), to recognize getting sent unrelated directories, as well as a list of introduced, but not yet received digest (to detect still-missing directories).

Fields

root_digest: B3Digest

the expected root digest

referenced_directories: HashMap<B3Digest, u64>

references of (directory digest, size) we have seen so far.

pending_directories: HashSet<B3Digest>

Directories we still wait to receive, because we heard about them but didn’t accept them yet. These consist of the root digest and any subset of referenced_directories.

poison: bool

tracks whether Self::finalize has been called, or an error has occured while trying to accept.

Implementations

impl RootToLeavesValidator

pub fn new_with_root_digest(root_digest: B3Digest) -> Self

Initialize with an expected root directory That directory should be sent next.

pub fn would_accept(&self, digest: &B3Digest) -> bool

Checks a directory digest on whether it’s introduced. Particularly useful when receiving directories in canonical protobuf encoding, so that directories not connected to the root can be rejected without parsing.

After parsing, the directory can be passed to Self::try_accept to add its children to the list of expected digests.

pub fn try_accept(&mut self, directory: &Directory) -> Result<(), OrderingError>

Accepts a directory if previously introduced, or returns an error if it’s unknown.

pub fn finalize(self) -> Result<(), OrderingError>

Should be called after accepting the last Directory Ensures there’s no more pending directories.

fn introduce_children_of(&mut self, directory: &Directory)

pub fn validate_stream<'s, S>( root_digest: B3Digest, directories: S, ) -> BoxStream<'s, Result<Directory, OrderingError>>

where S: Stream<Item = Directory> + Send + 's,

This receives a stream of Directories, validating them to be in Root-To-Leaves order. The expected root digest needs to be passed in. If the order is correct, they are yielded wrapped in an Ok(). If not, we yield an error.