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}