1#![deny(unsafe_code)]
5#![deny(clippy::undocumented_unsafe_blocks)]
6mod 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 Io {
75 operation: &'static str,
76 path: PathBuf,
77 source: io::Error,
78 },
79 Stream {
81 operation: &'static str,
82 source: io::Error,
83 },
84 InvalidData {
86 detail: String,
87 },
88 InvalidBase32,
89 InvalidHex,
90 InvalidRoot {
92 value: String,
93 },
94 InvalidName {
96 name: String,
97 reason: &'static str,
98 },
99 HashMismatch {
101 what: &'static str,
102 },
103 SizeMismatch {
105 what: &'static str,
106 expected: u64,
107 actual: u64,
108 },
109 TotalsMismatch {
111 field: &'static str,
112 recorded: u64,
113 counted: u64,
114 },
115 IntakeFailed,
117 NotWanted {
119 what: &'static str,
120 },
121 Corrupt {
124 what: &'static str,
125 hash: Hash,
126 },
127 Missing {
129 what: &'static str,
130 hash: Hash,
131 },
132 TooDeep {
134 limit: usize,
135 },
136 UnwritableName {
138 name: String,
139 reason: &'static str,
140 },
141 UnsupportedEntry {
143 path: PathBuf,
144 what: &'static str,
145 },
146 NonUtf8FileName {
147 path: PathBuf,
148 },
149 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#[cfg(doctest)]
266#[doc = include_str!("../README.md")]
267struct ReadmeExamples;