Skip to main content

refs_core/
error.rs

1//! Error types for the ReFS reader.
2
3use thiserror::Error;
4
5/// Errors surfaced while parsing ReFS 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 / version), never a bare
9/// "invalid" (the fail-loud, show-the-unrecognized-value standard).
10#[derive(Debug, Error, PartialEq, Eq)]
11#[non_exhaustive]
12pub enum RefsError {
13    /// The buffer was too small to hold the structure being parsed.
14    #[error("buffer too small for {structure}: need {need} bytes, have {have}")]
15    Truncated {
16        /// Name of the structure that could not be read.
17        structure: &'static str,
18        /// Minimum byte length required.
19        need: usize,
20        /// Byte length actually available.
21        have: usize,
22    },
23
24    /// The ReFS file-system signature at boot offset 3 was not
25    /// `"ReFS\0\0\0\0"`. Carries the eight bytes actually found so the caller
26    /// can identify what the image really is (fail-loud with the offending
27    /// value).
28    #[error("bad ReFS signature at offset 3: found {found:02x?}, expected \"ReFS\\0\\0\\0\\0\"")]
29    BadSignature {
30        /// The eight raw bytes at boot offset 3.
31        found: [u8; 8],
32    },
33
34    /// The file-system recognition-structure identifier at boot offset 16 was
35    /// not `"FSRS"`. Carries the four bytes actually found.
36    #[error("bad FSRS identifier at offset 16: found {found:02x?} (\"{found_ascii}\"), expected \"FSRS\"")]
37    BadFsrs {
38        /// The four raw bytes at boot offset 16.
39        found: [u8; 4],
40        /// Best-effort ASCII rendering of `found` (non-printables as `.`).
41        found_ascii: String,
42    },
43
44    /// A ReFS metadata block did not carry the expected block signature
45    /// (`SUPB` superblock, `CHKP` checkpoint, `MSB+` ministore).
46    ///
47    /// Carries the offending four bytes and the byte offset where they were
48    /// found, so the investigator sees *what* was there and *where* — never a
49    /// silently-skipped block.
50    #[error("bad metadata-block signature at offset {offset:#x}: found {found:02x?} (\"{found_ascii}\"), expected \"{expected}\"")]
51    BadBlockSignature {
52        /// The four raw bytes at the block's signature position.
53        found: [u8; 4],
54        /// Best-effort ASCII rendering of `found` (non-printables as `.`).
55        found_ascii: String,
56        /// The signature that was expected (e.g. `"SUPB"`).
57        expected: &'static str,
58        /// Absolute byte offset of the signature in the image/buffer.
59        offset: u64,
60    },
61
62    /// The object table did not contain the requested object identifier.
63    ///
64    /// Surfaced (rather than an empty listing) when a directory walk asks the
65    /// object table for an id it does not carry — the fail-loud, show-the-value
66    /// standard: the missing id is named so the investigator can tell "empty
67    /// directory" from "object not found".
68    #[error("object id {object_id:#x} not found in the object table")]
69    ObjectIdNotFound {
70        /// The object identifier that was looked up and not found.
71        object_id: u64,
72    },
73
74    /// An object's tree-root block number is a **virtual address** that this
75    /// phase cannot resolve to a physical location.
76    ///
77    /// In ReFS v3.x the object table stores *virtual* block numbers; resolving
78    /// them to physical offsets requires the container table (a later phase).
79    /// When a lookup lands on a block outside the physically-resident region,
80    /// the walk fails loud with the offending virtual block number rather than
81    /// silently returning an empty result (a bootstrap/resolution failure must
82    /// never be indistinguishable from a genuinely empty directory).
83    #[error(
84        "object tree-root block {block} is a virtual address outside the resident region \
85         (needs container-table translation — not yet implemented)"
86    )]
87    UnresolvedVirtualBlock {
88        /// The unresolved virtual block number named by the object table.
89        block: u64,
90    },
91
92    /// The ReFS major format version is not one this reader supports.
93    ///
94    /// This reader targets **ReFS v3.x** (Server 2016+/Win10 1803+/Win11). A v1
95    /// volume (Server 2012 / 8.1) has a materially different on-disk layout and
96    /// is deliberately rejected rather than silently misparsed. Carries the
97    /// actual major/minor bytes so the investigator sees the real version (the
98    /// fail-loud gate RESEARCH.md mandates: "never silently misparse").
99    #[error("unsupported ReFS format version {major}.{minor}: this reader supports v3.x only (major == 3)")]
100    UnsupportedVersion {
101        /// The `Major format version` byte at boot offset 40.
102        major: u8,
103        /// The `Minor format version` byte at boot offset 41.
104        minor: u8,
105    },
106}