nodedb_wal/
error.rs

1/// Errors produced by the WAL subsystem.
2#[derive(Debug, thiserror::Error)]
3pub enum WalError {
4    /// I/O error from the underlying file operations.
5    #[error("WAL I/O error: {0}")]
6    Io(#[from] std::io::Error),
7
8    /// CRC32C checksum mismatch during read/replay.
9    #[error("WAL checksum mismatch at LSN {lsn}: expected {expected:#010x}, got {actual:#010x}")]
10    ChecksumMismatch {
11        lsn: u64,
12        expected: u32,
13        actual: u32,
14    },
15
16    /// Record header has an invalid magic number — file is corrupted or not a WAL.
17    #[error("invalid WAL magic at offset {offset}: expected {expected:#010x}, got {actual:#010x}")]
18    InvalidMagic {
19        offset: u64,
20        expected: u32,
21        actual: u32,
22    },
23
24    /// WAL format version is not supported by this binary.
25    #[error("unsupported WAL format version {version} (supported: {supported})")]
26    UnsupportedVersion { version: u16, supported: u16 },
27
28    /// Unknown required record type encountered during replay.
29    /// Optional unknown record types are safely skipped.
30    #[error("unknown required record type {record_type} at LSN {lsn}")]
31    UnknownRequiredRecordType { record_type: u16, lsn: u64 },
32
33    /// Write payload exceeds maximum record size.
34    #[error("payload too large: {size} bytes (max: {max})")]
35    PayloadTooLarge { size: usize, max: usize },
36
37    /// Attempted to write to a WAL that has been closed or is in error state.
38    #[error("WAL is sealed and no longer accepting writes")]
39    Sealed,
40
41    /// Alignment violation — O_DIRECT requires aligned buffers and offsets.
42    #[error("alignment violation: {context} (required: {required}, actual: {actual})")]
43    AlignmentViolation {
44        context: &'static str,
45        required: usize,
46        actual: usize,
47    },
48
49    /// A mutex was poisoned (another thread panicked while holding the lock).
50    #[error("WAL lock poisoned: {context}")]
51    LockPoisoned { context: &'static str },
52
53    /// Encryption or decryption failed.
54    #[error("WAL encryption error: {detail}")]
55    EncryptionError { detail: String },
56
57    /// `DoubleWriteBuffer::open` was called with `DwbMode::Off`. Callers
58    /// that want the DWB disabled must not call `open` at all.
59    #[error("DoubleWriteBuffer::open called with DwbMode::Off")]
60    DwbOffNotOpenable,
61
62    /// Record payload failed structural validation (truncation, bad length
63    /// prefix, invalid UTF-8, etc.). Distinct from [`WalError::ChecksumMismatch`]
64    /// — the bytes passed CRC but the payload's own framing is wrong.
65    #[error("corrupt WAL record at LSN {lsn}: {detail}")]
66    CorruptRecord { lsn: u64, detail: String },
67}
68
69pub type Result<T> = std::result::Result<T, WalError>;
nodedb_wal/error.rs

nodedb_wal/
error.rs
