Skip to main content

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>;