Skip to main content

scionic_merkletree/
lib.rs

1// `unsafe` code is denied everywhere but in one function, on Windows, which
2// asks the system which file an open file is (`disk.rs`). Each `unsafe` block
3// says why it is sound.
4#![deny(unsafe_code)]
5#![deny(clippy::undocumented_unsafe_blocks)]
6//! Scionic Merkle trees.
7//!
8//! A tree holds a folder of files, or one file, under one root hash. A file is
9//! a list of chunks, a folder is a list of names, and the root covers all of
10//! it. Identical chunks, files and folders have identical hashes wherever they
11//! are, so a store keeps each of them once. A sender can show a part of a tree
12//! without the rest: one name in a folder, one chunk of a file, or a stretch of
13//! a file's bytes.
14//!
15//! `spec/FORMAT.md` in this repository says exactly what each hash covers.
16
17mod build;
18mod diff;
19mod disk;
20mod encoding;
21mod fastcdc;
22mod format;
23mod hash;
24mod intake;
25mod read;
26mod store;
27mod sync;
28mod threads;
29pub mod tree;
30mod wire;
31
32pub use build::{build, build_with, BuildOptions, Builder, EntryExtra, Links};
33pub use diff::{diff, diff_within, Change, DEFAULT_MAX_CHANGES};
34pub use fastcdc::{
35    FASTCDC_GEAR_SEED_PREFIX, FASTCDC_LOOSE_MASK, FASTCDC_MAX_SIZE, FASTCDC_MIN_SIZE,
36    FASTCDC_STRICT_MASK, FASTCDC_TARGET_SIZE,
37};
38pub use format::{
39    check_name, file_hash, folder_hash, ChunkRef, Chunking, Entry, ExtraData, FileBranch, FileList,
40    FolderBranch, FolderList, Kind, OpenFile, OpenFolder, Record, Target, Totals,
41    CHUNKING_FASTCDC_V1, CHUNKING_KEY, LIST_ITEM_BYTES, MAX_CARRIED_NODES, MAX_CHUNK_BYTES,
42    MAX_ENTRY_BYTES, MAX_EXTRA_BYTES, MAX_EXTRA_NAME_BYTES, MAX_EXTRA_VALUES,
43    MAX_EXTRA_VALUE_BYTES, MAX_FOLDER_DEPTH, MAX_NAME_BYTES, MAX_RECORD_BYTES, TIMESTAMP_KEY,
44};
45pub use hash::{Hash, Root};
46pub use intake::{verify, verify_with, Accepted, Arrived, Intake, Summary, VerifyOptions};
47pub use read::{
48    file_of, folder_of, lookup, read_file, read_file_to_vec, read_open, read_range, record_of,
49    unwritable, unwritable_on_windows, write_to_disk, write_to_disk_with, WriteOptions,
50    DEFAULT_MAX_WRITTEN_ENTRIES,
51};
52pub use store::{MemoryStore, Store, Stored};
53pub use sync::{
54    export, fetch, import, serve, Entries, Peer, Remote, Responder, StreamPeer,
55    REQUESTS_AHEAD_BYTES,
56};
57pub use wire::{
58    chunk_frame, file_branch_frame, file_list_frame, folder_branch_frame, folder_list_frame,
59    have_frame, read_frame, refused_frame, write_frame, Frame, HaveMap, Refusal, Request,
60    BUNDLE_MAGIC, FRAME_CHUNK, FRAME_FILE_BRANCH, FRAME_FILE_LIST, FRAME_FOLDER_BRANCH,
61    FRAME_FOLDER_LIST, FRAME_HAVE, FRAME_RECORD, FRAME_REFUSED, MAX_REQUEST_BYTES,
62};
63
64use std::fmt;
65use std::io;
66use std::path::{Path, PathBuf};
67
68pub type Result<T> = std::result::Result<T, Error>;
69
70#[derive(Debug)]
71#[non_exhaustive]
72pub enum Error {
73    /// The file system refused something.
74    Io {
75        operation: &'static str,
76        path: PathBuf,
77        source: io::Error,
78    },
79    /// Reading from a stream or writing to one failed.
80    Stream {
81        operation: &'static str,
82        source: io::Error,
83    },
84    /// Bytes that are not a well-formed thing of the format.
85    InvalidData {
86        detail: String,
87    },
88    InvalidBase32,
89    InvalidHex,
90    /// Text that is not a root.
91    InvalidRoot {
92        value: String,
93    },
94    /// A name that the format does not allow.
95    InvalidName {
96        name: String,
97        reason: &'static str,
98    },
99    /// A thing does not hash to what it has to.
100    HashMismatch {
101        what: &'static str,
102    },
103    /// A thing does not have the size it has to.
104    SizeMismatch {
105        what: &'static str,
106        expected: u64,
107        actual: u64,
108    },
109    /// A record's totals are not those of its tree.
110    TotalsMismatch {
111        field: &'static str,
112        recorded: u64,
113        counted: u64,
114    },
115    /// An intake was used again after a part of its tree was refused.
116    IntakeFailed,
117    /// Something arrived that is not tied to the root, or was not asked for.
118    NotWanted {
119        what: &'static str,
120    },
121    /// A store holds, under a hash, bytes that are not what the hash says.
122    /// Removing them from the store and fetching the tree again mends it.
123    Corrupt {
124        what: &'static str,
125        hash: Hash,
126    },
127    /// A store does not hold something that the tree needs.
128    Missing {
129        what: &'static str,
130        hash: Hash,
131    },
132    /// Folders sit inside one another more deeply than the format allows.
133    TooDeep {
134        limit: usize,
135    },
136    /// A name that this system cannot hold as it is.
137    UnwritableName {
138        name: String,
139        reason: &'static str,
140    },
141    /// A link or a special file, where only files and folders are stored.
142    UnsupportedEntry {
143        path: PathBuf,
144        what: &'static str,
145    },
146    NonUtf8FileName {
147        path: PathBuf,
148    },
149    /// A peer could not answer, or stopped early.
150    Peer {
151        detail: String,
152    },
153    LimitExceeded {
154        what: &'static str,
155        limit: u64,
156        requested: u64,
157    },
158    AllocationFailed {
159        resource: &'static str,
160        requested: u64,
161    },
162    SystemTimeBeforeUnixEpoch,
163    SizeOverflow {
164        field: &'static str,
165    },
166    Invariant {
167        detail: &'static str,
168    },
169}
170
171impl fmt::Display for Error {
172    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
173        match self {
174            Self::Io {
175                operation,
176                path,
177                source,
178            } => write!(f, "failed to {operation} {}: {source}", path.display()),
179            Self::Stream { operation, source } => write!(f, "failed to {operation}: {source}"),
180            Self::InvalidData { detail } => write!(f, "malformed: {detail}"),
181            Self::InvalidBase32 => f.write_str("not lowercase base32"),
182            Self::InvalidHex => f.write_str("not lowercase hex of the right length"),
183            Self::InvalidRoot { value } => write!(f, "not a root: {value:?}"),
184            Self::InvalidName { name, reason } => {
185                write!(f, "the name {name:?} is not allowed: {reason}")
186            }
187            Self::HashMismatch { what } => write!(f, "{what} does not hash to what it has to"),
188            Self::SizeMismatch {
189                what,
190                expected,
191                actual,
192            } => write!(f, "{what} holds {actual} bytes where {expected} are due"),
193            Self::TotalsMismatch {
194                field,
195                recorded,
196                counted,
197            } => write!(
198                f,
199                "the record says {recorded} for {field}, and the tree has {counted}"
200            ),
201            Self::IntakeFailed => f.write_str(
202                "an intake is done once a part of its tree was refused: start a new one",
203            ),
204            Self::NotWanted { what } => {
205                write!(f, "{what} is not tied to the root, or was not asked for")
206            }
207            Self::Corrupt { what, hash } => write!(
208                f,
209                "{what} {hash} is damaged: its bytes are not what its hash says"
210            ),
211            Self::Missing { what, hash } => write!(f, "{what} {hash} is not held"),
212            Self::TooDeep { limit } => {
213                write!(f, "folders sit inside one another more than {limit} deep")
214            }
215            Self::UnwritableName { name, reason } => write!(
216                f,
217                "the name {name:?} cannot be written on this system: {reason}"
218            ),
219            Self::UnsupportedEntry { path, what } => write!(
220                f,
221                "{} is {what}, and only files and folders are stored",
222                path.display()
223            ),
224            Self::NonUtf8FileName { path } => {
225                write!(f, "path has a non-UTF-8 file name: {}", path.display())
226            }
227            Self::Peer { detail } => write!(f, "the peer {detail}"),
228            Self::LimitExceeded {
229                what,
230                limit,
231                requested,
232            } => write!(f, "{what} needs {requested}, over the limit of {limit}"),
233            Self::AllocationFailed {
234                resource,
235                requested,
236            } => write!(f, "failed to allocate {requested} bytes for {resource}"),
237            Self::SystemTimeBeforeUnixEpoch => {
238                f.write_str("the system clock is before the Unix epoch")
239            }
240            Self::SizeOverflow { field } => write!(f, "{field} exceeds the supported size"),
241            Self::Invariant { detail } => write!(f, "internal invariant failed: {detail}"),
242        }
243    }
244}
245
246impl std::error::Error for Error {
247    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
248        match self {
249            Self::Io { source, .. } | Self::Stream { source, .. } => Some(source),
250            _ => None,
251        }
252    }
253}
254
255pub(crate) fn io_error(operation: &'static str, path: &Path, source: io::Error) -> Error {
256    Error::Io {
257        operation,
258        path: path.to_path_buf(),
259        source,
260    }
261}
262
263/// The examples in the README are compiled with the tests, and the one that
264/// needs no files is run, so that the README cannot fall behind the code.
265#[cfg(doctest)]
266#[doc = include_str!("../README.md")]
267struct ReadmeExamples;