Skip to main content

xfs/
error.rs

1//! Error types for the XFS reader.
2
3use thiserror::Error;
4
5/// Errors surfaced while parsing XFS on-disk structures.
6///
7/// Every variant names the offending value so an "unknown/invalid" report hands
8/// the investigator the evidence (raw bytes / offset), never a bare "invalid".
9#[derive(Debug, Error, PartialEq, Eq)]
10#[non_exhaustive]
11pub enum XfsError {
12    /// The buffer was too small to hold the structure being parsed.
13    #[error("buffer too small for {structure}: need {need} bytes, have {have}")]
14    Truncated {
15        /// Name of the structure that could not be read.
16        structure: &'static str,
17        /// Minimum byte length required.
18        need: usize,
19        /// Byte length actually available.
20        have: usize,
21    },
22
23    /// The superblock magic number did not match `XFSB` (`0x5846_5342`).
24    ///
25    /// Carries the four bytes actually found so the caller can identify what the
26    /// image really is (fail-loud with the offending value).
27    #[error("bad superblock magic: found {found:#010x} (bytes {bytes:02x?}), expected 0x58465342 (\"XFSB\")")]
28    BadMagic {
29        /// The 32-bit big-endian value read at offset 0.
30        found: u32,
31        /// The four raw bytes at offset 0.
32        bytes: [u8; 4],
33    },
34
35    /// A directory used a format this reader does not yet handle (leaf / node /
36    /// btree), or a block directory carried an unrecognized data-block magic.
37    ///
38    /// Fail-loud rather than return an empty listing: `detail` names the format
39    /// and the offending value (magic bytes / size), so the investigator sees
40    /// *what* could not be read, never a silently-empty directory.
41    #[error("unsupported directory: {detail}")]
42    UnsupportedDir {
43        /// Human description naming the format and the offending value.
44        detail: String,
45    },
46
47    /// A path component did not resolve during [`crate::read_by_path`]: the named
48    /// component was not found in its parent directory, or a non-final component
49    /// was not itself a directory. Carries the offending path and component.
50    #[error("path not found: component {component:?} of {path:?} did not resolve")]
51    PathNotFound {
52        /// The full path being resolved.
53        path: String,
54        /// The specific component that failed to resolve.
55        component: String,
56    },
57}