scionic-merkletree 2.5.6

Scionic Merkle trees: a folder of files under one root, with identical chunks, files and folders stored once, and any part of it shown and checked without the rest
Documentation
// `unsafe` code is denied everywhere but in one function, on Windows, which
// asks the system which file an open file is (`disk.rs`). Each `unsafe` block
// says why it is sound.
#![deny(unsafe_code)]
#![deny(clippy::undocumented_unsafe_blocks)]
//! Scionic Merkle trees.
//!
//! A tree holds a folder of files, or one file, under one root hash. A file is
//! a list of chunks, a folder is a list of names, and the root covers all of
//! it. Identical chunks, files and folders have identical hashes wherever they
//! are, so a store keeps each of them once. A sender can show a part of a tree
//! without the rest: one name in a folder, one chunk of a file, or a stretch of
//! a file's bytes.
//!
//! `spec/FORMAT.md` in this repository says exactly what each hash covers.

mod build;
mod diff;
mod disk;
mod encoding;
mod fastcdc;
mod format;
mod hash;
mod intake;
mod read;
mod store;
mod sync;
mod threads;
pub mod tree;
mod wire;

pub use build::{build, build_with, BuildOptions, Builder, EntryExtra, Links};
pub use diff::{diff, diff_within, Change, DEFAULT_MAX_CHANGES};
pub use fastcdc::{
    FASTCDC_GEAR_SEED_PREFIX, FASTCDC_LOOSE_MASK, FASTCDC_MAX_SIZE, FASTCDC_MIN_SIZE,
    FASTCDC_STRICT_MASK, FASTCDC_TARGET_SIZE,
};
pub use format::{
    check_name, file_hash, folder_hash, ChunkRef, Chunking, Entry, ExtraData, FileBranch, FileList,
    FolderBranch, FolderList, Kind, OpenFile, OpenFolder, Record, Target, Totals,
    CHUNKING_FASTCDC_V1, CHUNKING_KEY, LIST_ITEM_BYTES, MAX_CARRIED_NODES, MAX_CHUNK_BYTES,
    MAX_ENTRY_BYTES, MAX_EXTRA_BYTES, MAX_EXTRA_NAME_BYTES, MAX_EXTRA_VALUES,
    MAX_EXTRA_VALUE_BYTES, MAX_FOLDER_DEPTH, MAX_NAME_BYTES, MAX_RECORD_BYTES, TIMESTAMP_KEY,
};
pub use hash::{Hash, Root};
pub use intake::{verify, verify_with, Accepted, Arrived, Intake, Summary, VerifyOptions};
pub use read::{
    file_of, folder_of, lookup, read_file, read_file_to_vec, read_open, read_range, record_of,
    unwritable, unwritable_on_windows, write_to_disk, write_to_disk_with, WriteOptions,
    DEFAULT_MAX_WRITTEN_ENTRIES,
};
pub use store::{MemoryStore, Store, Stored};
pub use sync::{
    export, fetch, import, serve, Entries, Peer, Remote, Responder, StreamPeer,
    REQUESTS_AHEAD_BYTES,
};
pub use wire::{
    chunk_frame, file_branch_frame, file_list_frame, folder_branch_frame, folder_list_frame,
    have_frame, read_frame, refused_frame, write_frame, Frame, HaveMap, Refusal, Request,
    BUNDLE_MAGIC, FRAME_CHUNK, FRAME_FILE_BRANCH, FRAME_FILE_LIST, FRAME_FOLDER_BRANCH,
    FRAME_FOLDER_LIST, FRAME_HAVE, FRAME_RECORD, FRAME_REFUSED, MAX_REQUEST_BYTES,
};

use std::fmt;
use std::io;
use std::path::{Path, PathBuf};

pub type Result<T> = std::result::Result<T, Error>;

#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
    /// The file system refused something.
    Io {
        operation: &'static str,
        path: PathBuf,
        source: io::Error,
    },
    /// Reading from a stream or writing to one failed.
    Stream {
        operation: &'static str,
        source: io::Error,
    },
    /// Bytes that are not a well-formed thing of the format.
    InvalidData {
        detail: String,
    },
    InvalidBase32,
    InvalidHex,
    /// Text that is not a root.
    InvalidRoot {
        value: String,
    },
    /// A name that the format does not allow.
    InvalidName {
        name: String,
        reason: &'static str,
    },
    /// A thing does not hash to what it has to.
    HashMismatch {
        what: &'static str,
    },
    /// A thing does not have the size it has to.
    SizeMismatch {
        what: &'static str,
        expected: u64,
        actual: u64,
    },
    /// A record's totals are not those of its tree.
    TotalsMismatch {
        field: &'static str,
        recorded: u64,
        counted: u64,
    },
    /// An intake was used again after a part of its tree was refused.
    IntakeFailed,
    /// Something arrived that is not tied to the root, or was not asked for.
    NotWanted {
        what: &'static str,
    },
    /// A store holds, under a hash, bytes that are not what the hash says.
    /// Removing them from the store and fetching the tree again mends it.
    Corrupt {
        what: &'static str,
        hash: Hash,
    },
    /// A store does not hold something that the tree needs.
    Missing {
        what: &'static str,
        hash: Hash,
    },
    /// Folders sit inside one another more deeply than the format allows.
    TooDeep {
        limit: usize,
    },
    /// A name that this system cannot hold as it is.
    UnwritableName {
        name: String,
        reason: &'static str,
    },
    /// A link or a special file, where only files and folders are stored.
    UnsupportedEntry {
        path: PathBuf,
        what: &'static str,
    },
    NonUtf8FileName {
        path: PathBuf,
    },
    /// A peer could not answer, or stopped early.
    Peer {
        detail: String,
    },
    LimitExceeded {
        what: &'static str,
        limit: u64,
        requested: u64,
    },
    AllocationFailed {
        resource: &'static str,
        requested: u64,
    },
    SystemTimeBeforeUnixEpoch,
    SizeOverflow {
        field: &'static str,
    },
    Invariant {
        detail: &'static str,
    },
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Io {
                operation,
                path,
                source,
            } => write!(f, "failed to {operation} {}: {source}", path.display()),
            Self::Stream { operation, source } => write!(f, "failed to {operation}: {source}"),
            Self::InvalidData { detail } => write!(f, "malformed: {detail}"),
            Self::InvalidBase32 => f.write_str("not lowercase base32"),
            Self::InvalidHex => f.write_str("not lowercase hex of the right length"),
            Self::InvalidRoot { value } => write!(f, "not a root: {value:?}"),
            Self::InvalidName { name, reason } => {
                write!(f, "the name {name:?} is not allowed: {reason}")
            }
            Self::HashMismatch { what } => write!(f, "{what} does not hash to what it has to"),
            Self::SizeMismatch {
                what,
                expected,
                actual,
            } => write!(f, "{what} holds {actual} bytes where {expected} are due"),
            Self::TotalsMismatch {
                field,
                recorded,
                counted,
            } => write!(
                f,
                "the record says {recorded} for {field}, and the tree has {counted}"
            ),
            Self::IntakeFailed => f.write_str(
                "an intake is done once a part of its tree was refused: start a new one",
            ),
            Self::NotWanted { what } => {
                write!(f, "{what} is not tied to the root, or was not asked for")
            }
            Self::Corrupt { what, hash } => write!(
                f,
                "{what} {hash} is damaged: its bytes are not what its hash says"
            ),
            Self::Missing { what, hash } => write!(f, "{what} {hash} is not held"),
            Self::TooDeep { limit } => {
                write!(f, "folders sit inside one another more than {limit} deep")
            }
            Self::UnwritableName { name, reason } => write!(
                f,
                "the name {name:?} cannot be written on this system: {reason}"
            ),
            Self::UnsupportedEntry { path, what } => write!(
                f,
                "{} is {what}, and only files and folders are stored",
                path.display()
            ),
            Self::NonUtf8FileName { path } => {
                write!(f, "path has a non-UTF-8 file name: {}", path.display())
            }
            Self::Peer { detail } => write!(f, "the peer {detail}"),
            Self::LimitExceeded {
                what,
                limit,
                requested,
            } => write!(f, "{what} needs {requested}, over the limit of {limit}"),
            Self::AllocationFailed {
                resource,
                requested,
            } => write!(f, "failed to allocate {requested} bytes for {resource}"),
            Self::SystemTimeBeforeUnixEpoch => {
                f.write_str("the system clock is before the Unix epoch")
            }
            Self::SizeOverflow { field } => write!(f, "{field} exceeds the supported size"),
            Self::Invariant { detail } => write!(f, "internal invariant failed: {detail}"),
        }
    }
}

impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io { source, .. } | Self::Stream { source, .. } => Some(source),
            _ => None,
        }
    }
}

pub(crate) fn io_error(operation: &'static str, path: &Path, source: io::Error) -> Error {
    Error::Io {
        operation,
        path: path.to_path_buf(),
        source,
    }
}

/// The examples in the README are compiled with the tests, and the one that
/// needs no files is run, so that the README cannot fall behind the code.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeExamples;