driftdb/error.rs
1//! Error type and shared `Result` alias for the public API.
2//!
3//! The crate uses `thiserror` for the library surface so callers can pattern-match on
4//! variants. The boundary contract: only `std::io::Error` is wrapped through `#[from]` — no
5//! third-party error type appears in the public API (in particular, bincode's `Error` type is
6//! never exposed; a bincode failure is always mapped to `ManifestCorrupt` or `SstCorrupt` at
7//! the call site, since bincode is only ever used to decode the manifest log or an SST's
8//! index/bloom region). WAL corruption is *not* one of those variants: a bad CRC, an invalid
9//! kind byte, or a header/body that runs off the end of the file is always treated as a torn
10//! tail from a mid-write crash (see `wal.rs`'s module docs) and silently truncated away on
11//! replay rather than surfaced as an error. Manifest corruption gets the stricter treatment —
12//! a `ManifestCorrupt` variant — because only a torn *tail* frame is dropped that way; the same
13//! corruption in the middle of the log is a real error (see `manifest.rs`'s module docs).
14
15use thiserror::Error;
16
17/// Crate-wide error type. See module docs for the full taxonomy.
18///
19/// `#[non_exhaustive]`: new variants may be added in a minor (0.x) release; match with a
20/// wildcard arm (`_ => ...`) rather than exhaustively.
21#[derive(Debug, Error)]
22#[non_exhaustive]
23pub enum Error {
24 /// Underlying filesystem error from `std::io`.
25 #[error("io: {0}")]
26 Io(#[from] std::io::Error),
27
28 /// Manifest log replay encountered an unknown record kind or a truncated/corrupt record.
29 /// A format-version mismatch is reported as [`Error::UnsupportedFormat`] instead.
30 #[error("manifest corrupt: {0}")]
31 ManifestCorrupt(String),
32
33 /// SSTable file failed validation on open or during a block read: truncated file, bad
34 /// magic/footer offsets, a block that failed its CRC check, or a malformed index/bloom. A
35 /// format-version mismatch is reported as [`Error::UnsupportedFormat`] instead.
36 #[error("sst corrupt: {0}")]
37 SstCorrupt(String),
38
39 /// A caller-supplied argument violates a documented limit — e.g. a key longer than
40 /// [`crate::wal::MAX_KEY_LEN`] or a value longer than [`crate::wal::MAX_VALUE_LEN`]. Checked
41 /// before the op ever reaches the writer thread, so the engine and any other pending writes
42 /// are unaffected.
43 #[error("invalid argument: {0}")]
44 InvalidArgument(String),
45
46 /// `Db::open`/`open_with` found `<dir>/LOCK` already held by another live `Db` (in this
47 /// process or another). Only one open `Db` per directory is supported: two writers sharing
48 /// a WAL/manifest would corrupt each other's state, and mmap-based WAL replay racing a live
49 /// writer could SIGBUS. Close/drop the other `Db` first.
50 #[error("driftdb: {0} is already open by another Db instance (directory lock held)")]
51 Locked(std::path::PathBuf),
52
53 /// `Db::open`/`open_with` found a manifest (or SST) written by an on-disk format version
54 /// this build doesn't support. Checked before recovery touches any WAL or SST file, so the
55 /// directory is left exactly as found — nothing is deleted or rewritten. Open it with a
56 /// driftdb version that supports `found` instead.
57 #[error("driftdb: on-disk format version {found} is not supported (this build supports {supported})")]
58 UnsupportedFormat {
59 /// The format version recorded on disk.
60 found: u32,
61 /// The format version this build supports.
62 supported: u32,
63 },
64}
65
66/// Crate-wide `Result` alias.
67pub type Result<T> = std::result::Result<T, Error>;