Skip to main content

store_io_engine/
report.rs

1//! How a [`StoreReport`] prints, and the unavailable-region report (D-090).
2
3use store_io_core::RegionId;
4use store_io_core::error::CorruptionKind;
5use store_io_format::meta::RegionKind;
6
7use crate::store::StoreReport;
8
9impl core::fmt::Display for StoreReport {
10    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
11        let d = &self.decision;
12        writeln!(f, "volume           {}", self.volume)?;
13        writeln!(
14            f,
15            "io               {} ({})",
16            self.io.interface, self.io.reason
17        )?;
18        writeln!(f, "class            {}", d.class)?;
19        writeln!(f, "label            {}", d.label)?;
20        writeln!(f, "durable open     {:?}", d.durable_open)?;
21        if d.power_safe_candidate {
22            writeln!(
23                f,
24                "note             device reports no volatile cache; health unreadable (power-safe candidate)"
25            )?;
26        }
27        for r in d.reasons.iter() {
28            writeln!(f, "reason           {r}")?;
29        }
30        for m in d.missing.iter() {
31            writeln!(f, "missing          {m}")?;
32        }
33        writeln!(f, "flush execution  inline (leader)")?;
34        writeln!(f, "block size       {}", self.block_size)?;
35        writeln!(f, "table capacity   {} regions", self.table_capacity)?;
36        writeln!(f, "filesystem       {:?}", self.evidence.fs.kind)?;
37        writeln!(f, "bus              {:?}", self.evidence.device.bus)?;
38        writeln!(f, "internal         {:?}", self.evidence.device.internal)?;
39        if let Some(m) = &self.evidence.device.model {
40            writeln!(f, "model            {m}")?;
41        }
42        for u in &self.unavailable {
43            writeln!(
44                f,
45                "unavailable      region {:?} (id {}, {:?}): {}",
46                u.name,
47                u.id.get(),
48                u.kind,
49                u.reason
50            )?;
51        }
52        writeln!(f, "format           {}", self.format)?;
53        if self.format == store_io_format::slot::FORMAT_2 {
54            write!(f, "{}", self.metadata)?;
55        }
56        write!(
57            f,
58            "mode             {}",
59            if self.read_only {
60                "read-only"
61            } else {
62                "read-write"
63            }
64        )
65    }
66}
67
68/// Why a region the region table names could not be opened (D-090).
69///
70/// Such a region is never used as ready and its name stays reserved; a lookup
71/// returns [`Error::Corruption`](store_io_core::error::Error::Corruption) naming the region, never `NotFound`.
72#[derive(Debug, Clone, Copy, PartialEq, Eq)]
73#[non_exhaustive]
74pub enum Unavailable {
75    /// The container is shorter than the region's extent.
76    ContainerShort {
77        /// Bytes the container must hold for this region.
78        needed: u64,
79        /// Bytes it holds.
80        actual: u64,
81    },
82    /// Neither copy of the region's header is valid.
83    HeaderUnreadable,
84    /// The header passes its checksum but holds impossible values.
85    HeaderInvalid,
86    /// The header belongs to another region or another kind of region.
87    HeaderMismatch,
88    /// The header says the region was released while the table says ready.
89    HeaderReleased,
90    /// Format 2: the table entry itself holds impossible values (its span
91    /// stays reserved).
92    EntryInvalid,
93    /// Format 2: the header's extents do not match the entry (their sum,
94    /// the span, the table area, or an overlap within the region).
95    ExtentsInvalid,
96    /// Format 2: a region with a newer (or equal) footprint overlaps it.
97    Overlaps,
98    /// Format 2: a region with a newer (or equal) footprint has its name.
99    NameTaken,
100}
101
102impl Unavailable {
103    /// The corruption kind a lookup of such a region reports.
104    #[must_use]
105    pub fn corruption_kind(&self) -> CorruptionKind {
106        match self {
107            Self::ContainerShort { .. } => CorruptionKind::Truncated,
108            Self::HeaderUnreadable => CorruptionKind::HeaderCrc,
109            Self::HeaderInvalid
110            | Self::HeaderMismatch
111            | Self::HeaderReleased
112            | Self::EntryInvalid
113            | Self::ExtentsInvalid
114            | Self::Overlaps
115            | Self::NameTaken => CorruptionKind::Metadata,
116        }
117    }
118}
119
120impl core::fmt::Display for Unavailable {
121    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
122        match self {
123            Self::ContainerShort { needed, actual } => write!(
124                f,
125                "the container holds {actual} bytes but the region needs {needed}"
126            ),
127            Self::HeaderUnreadable => f.write_str("neither copy of its header is valid"),
128            Self::HeaderInvalid => f.write_str("its header holds impossible values"),
129            Self::HeaderMismatch => f.write_str("its header belongs to another region or kind"),
130            Self::HeaderReleased => {
131                f.write_str("its header says released while the table says ready")
132            }
133            Self::EntryInvalid => f.write_str("its table entry holds impossible values"),
134            Self::ExtentsInvalid => f.write_str("its extents do not match its table entry"),
135            Self::Overlaps => f.write_str("a newer region overlaps it"),
136            Self::NameTaken => f.write_str("a newer region has its name"),
137        }
138    }
139}
140
141/// What one repair of a store did (v0.5 E6), as [`Store::repairs`](crate::Store::repairs)
142/// returns it: for the caller's own log (the library prints nothing).
143#[derive(Debug, Clone, PartialEq, Eq)]
144#[non_exhaustive]
145pub enum Repair {
146    /// `repair_unavailable`: an unavailable region's table entry released
147    /// (its bytes untouched; its space free again where no other region's
148    /// footprint lies).
149    EntryReleased {
150        /// The region, as `unavailable_regions` listed it.
151        region: UnavailableRegion,
152    },
153    /// `repair_unavailable`: a table entry of a kind this version does not
154    /// know (`metadata.invalid_entries`) released.
155    InvalidEntryReleased {
156        /// Its table page.
157        page: u32,
158        /// Its sequence on the page.
159        seq: u32,
160    },
161    /// `accept_page_rollback`: a stale page's winner made the page's
162    /// content (whatever its lost commits held is given up).
163    PageAccepted {
164        /// The page.
165        page: u32,
166    },
167}
168
169/// A region the region table names that could not be opened (D-090).
170#[derive(Debug, Clone, PartialEq, Eq)]
171pub struct UnavailableRegion {
172    /// The region's name.
173    pub name: String,
174    /// The region's id.
175    pub id: RegionId,
176    /// The region's kind.
177    pub kind: RegionKind,
178    /// Why it could not be opened.
179    pub reason: Unavailable,
180}