#![deny(unsafe_code)]
#![deny(clippy::undocumented_unsafe_blocks)]
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 {
Io {
operation: &'static str,
path: PathBuf,
source: io::Error,
},
Stream {
operation: &'static str,
source: io::Error,
},
InvalidData {
detail: String,
},
InvalidBase32,
InvalidHex,
InvalidRoot {
value: String,
},
InvalidName {
name: String,
reason: &'static str,
},
HashMismatch {
what: &'static str,
},
SizeMismatch {
what: &'static str,
expected: u64,
actual: u64,
},
TotalsMismatch {
field: &'static str,
recorded: u64,
counted: u64,
},
IntakeFailed,
NotWanted {
what: &'static str,
},
Corrupt {
what: &'static str,
hash: Hash,
},
Missing {
what: &'static str,
hash: Hash,
},
TooDeep {
limit: usize,
},
UnwritableName {
name: String,
reason: &'static str,
},
UnsupportedEntry {
path: PathBuf,
what: &'static str,
},
NonUtf8FileName {
path: PathBuf,
},
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,
}
}
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeExamples;