Skip to main content

mariadb_cli/error/
category.rs

1//! Failure categories and the exit numbers they map to.
2//!
3//! The product publishes a closed list of thirteen failure categories and a
4//! closed table of fourteen exit numbers. Both lists are normative: a category
5//! outside [`Category`] does not exist, and an exit number outside
6//! [`ExitNumber`] must never be observed.
7//!
8//! The two lists differ by exactly one, and that is deliberate: thirteen of the
9//! numbers are the categories, and [`ExitNumber::Success`] is not a failure, so
10//! it has no category. Every number a failure can end with has a category of
11//! its own.
12//!
13//! [`Category::ChannelClosed`] is the thirteenth and was the last to arrive. A
14//! closed channel used to be reported as `Limit`, distinguished only by the
15//! stable code `output.broken_pipe`, so a caller branching on the category
16//! could not tell "the reader went away" from "a ceiling was reached" — two
17//! conditions with nothing in common but a number. Branching on the category is
18//! now enough.
19
20use serde::{Deserialize, Serialize};
21
22/// The closed set of failure categories the product can report.
23///
24/// Every failure carries exactly one category. The category is stable across
25/// releases and is the field callers branch on, never the message text.
26#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
27#[serde(rename_all = "snake_case")]
28pub enum Category {
29    /// The caller's input to this tool is wrong.
30    Usage,
31    /// The statement was refused by analysis before it was sent.
32    Validation,
33    /// A profile or a setting is missing or invalid.
34    Config,
35    /// The server could not be reached.
36    Network,
37    /// The credential was refused.
38    Authentication,
39    /// The credential may not do what was asked.
40    Permission,
41    /// The requested object does not exist.
42    Absence,
43    /// The change hit a lock, a deadlock or a constraint.
44    Conflict,
45    /// Some phase exceeded its time budget.
46    Timeout,
47    /// The server returned an error of its own.
48    Server,
49    /// A size, row or packet ceiling was reached.
50    Limit,
51    /// The work was cancelled from outside.
52    Interrupted,
53    /// The reader closed the channel the answer was being written to.
54    ///
55    /// Not a failure of the work: a caller that read as much as it wanted and
56    /// walked away is behaving correctly, which is why this is the one category
57    /// whose number is a signal number rather than one of the product's own.
58    ChannelClosed,
59}
60
61impl Category {
62    /// Every category this product carries, in the order the annex tabulates.
63    ///
64    /// Public because the annex is transcribed by hand in an acceptance proof,
65    /// and a transcription needs something that notices when it stops being the
66    /// whole of what it transcribes. That proof carried twelve of these thirteen
67    /// for as long as it existed, so the pair `ChannelClosed` to 141 was
68    /// asserted nowhere and could have been swapped for any other number.
69    pub const ALL: [Self; 13] = [
70        Self::Usage,
71        Self::Validation,
72        Self::Config,
73        Self::Network,
74        Self::Authentication,
75        Self::Permission,
76        Self::Absence,
77        Self::Conflict,
78        Self::Timeout,
79        Self::Server,
80        Self::Limit,
81        Self::Interrupted,
82        Self::ChannelClosed,
83    ];
84
85    /// The exit number this category maps to.
86    ///
87    /// The mapping is total and fixed: every category has exactly one number,
88    /// and the number always comes from the published table.
89    #[must_use]
90    pub const fn exit_number(self) -> ExitNumber {
91        match self {
92            Self::Usage => ExitNumber::Usage,
93            Self::Validation => ExitNumber::Validation,
94            Self::Config => ExitNumber::Config,
95            Self::Network => ExitNumber::Network,
96            Self::Authentication => ExitNumber::Authentication,
97            Self::Permission => ExitNumber::Permission,
98            Self::Absence => ExitNumber::Absence,
99            Self::Conflict => ExitNumber::Conflict,
100            Self::Limit => ExitNumber::Limit,
101            Self::Server => ExitNumber::Server,
102            Self::Timeout => ExitNumber::Timeout,
103            Self::Interrupted => ExitNumber::Interrupted,
104            Self::ChannelClosed => ExitNumber::BrokenPipe,
105        }
106    }
107
108    /// Whether repeating the same call may succeed without changing the input.
109    ///
110    /// `Server` is deliberately absent from the retryable set here: whether a
111    /// server condition is worth repeating depends on the condition itself, so
112    /// that decision is made where the condition code is known.
113    #[must_use]
114    pub const fn is_retryable(self) -> bool {
115        matches!(self, Self::Network | Self::Conflict | Self::Timeout)
116    }
117
118    /// The stable snake_case identifier emitted on the wire.
119    #[must_use]
120    pub const fn as_str(self) -> &'static str {
121        match self {
122            Self::Usage => "usage",
123            Self::Validation => "validation",
124            Self::Config => "config",
125            Self::Network => "network",
126            Self::Authentication => "authentication",
127            Self::Permission => "permission",
128            Self::Absence => "absence",
129            Self::Conflict => "conflict",
130            Self::Timeout => "timeout",
131            Self::Server => "server",
132            Self::Limit => "limit",
133            Self::Interrupted => "interrupted",
134            Self::ChannelClosed => "channel_closed",
135        }
136    }
137}
138
139/// The closed table of process exit numbers.
140///
141/// A number outside this list does not exist in the product. Adding one is a
142/// change to the published contract, never an implementation detail.
143#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
144#[repr(u8)]
145pub enum ExitNumber {
146    /// Success.
147    Success = 0,
148    /// Incorrect use of this tool.
149    Usage = 2,
150    /// Analysis refused the statement.
151    Validation = 3,
152    /// Configuration missing or invalid.
153    Config = 4,
154    /// Network unreachable.
155    Network = 5,
156    /// Authentication refused.
157    Authentication = 6,
158    /// Insufficient permission.
159    Permission = 7,
160    /// Object not found.
161    Absence = 8,
162    /// Lock conflict, deadlock or constraint.
163    Conflict = 9,
164    /// Size, row or packet ceiling reached.
165    Limit = 10,
166    /// Error returned by the server.
167    Server = 11,
168    /// Time limit reached.
169    Timeout = 124,
170    /// Interrupted by a signal from the caller.
171    Interrupted = 130,
172    /// The output channel was closed by the reader.
173    BrokenPipe = 141,
174}
175
176impl ExitNumber {
177    /// The raw process exit code.
178    #[must_use]
179    pub const fn code(self) -> u8 {
180        self as u8
181    }
182}
183
184impl From<ExitNumber> for std::process::ExitCode {
185    fn from(value: ExitNumber) -> Self {
186        Self::from(value.code())
187    }
188}
189
190#[cfg(test)]
191mod tests {
192    use super::*;
193
194    /// `ALL` holds every variant of `Category`, each exactly once and in its
195    /// declared place.
196    ///
197    /// # Why counting is not enough
198    ///
199    /// `ALL` is written as `[Self; 13]`, so the compiler counts what is inside
200    /// it — but nothing connects that count to the enum. Adding a variant and
201    /// leaving `ALL` alone compiles: thirteen elements are still thirteen
202    /// elements, and every test that walks `ALL` keeps passing over a set that
203    /// is no longer the whole of it. `std::mem::variant_count` would close this
204    /// directly and is not stable, so the bridge is built here instead.
205    ///
206    /// The bridge is the `match`, and it has to yield a position rather than a
207    /// yes or no. Exhaustiveness means a variant added to the enum stops this
208    /// file from building until it is named here, which puts whoever adds one
209    /// inside the block where `ALL` is written rather than somewhere that never
210    /// mentions it. Naming it then forces a position, and a position that
211    /// belongs to another variant fails the comparison below.
212    ///
213    /// # What this still does not catch
214    ///
215    /// A variant named here with a position past the end of `ALL` and left out
216    /// of `ALL` itself. The loop walks `ALL`, so it never reaches that variant
217    /// to check it, and thirteen elements are still thirteen. Closing it needs
218    /// the variant count the language does not hand out on stable. What is left
219    /// is deliberate rather than accidental: it takes writing a number nothing
220    /// in the array answers to, in the same block as the array.
221    #[test]
222    fn all_holds_every_category_in_its_declared_place() {
223        /// Where each variant sits in `ALL`. Exhaustive on purpose.
224        const fn place(category: Category) -> usize {
225            match category {
226                Category::Usage => 0,
227                Category::Validation => 1,
228                Category::Config => 2,
229                Category::Network => 3,
230                Category::Authentication => 4,
231                Category::Permission => 5,
232                Category::Absence => 6,
233                Category::Conflict => 7,
234                Category::Timeout => 8,
235                Category::Server => 9,
236                Category::Limit => 10,
237                Category::Interrupted => 11,
238                Category::ChannelClosed => 12,
239            }
240        }
241
242        for (index, category) in Category::ALL.into_iter().enumerate() {
243            assert_eq!(
244                place(category),
245                index,
246                "{category:?} is declared at {} and sits at {index} in `ALL`",
247                place(category)
248            );
249        }
250    }
251
252    /// Every category maps to a distinct number, so a caller can tell them
253    /// apart by exit code alone.
254    #[test]
255    fn categories_map_to_distinct_numbers() {
256        let mut seen = std::collections::BTreeSet::new();
257        for category in Category::ALL {
258            assert!(
259                seen.insert(category.exit_number().code()),
260                "duplicate exit number for {category:?}",
261            );
262        }
263        assert_eq!(seen.len(), Category::ALL.len());
264    }
265
266    /// The numbers are exactly the ones the contract publishes.
267    #[test]
268    fn exit_numbers_match_the_published_table() {
269        assert_eq!(ExitNumber::Success.code(), 0);
270        assert_eq!(ExitNumber::Usage.code(), 2);
271        assert_eq!(ExitNumber::Validation.code(), 3);
272        assert_eq!(ExitNumber::Config.code(), 4);
273        assert_eq!(ExitNumber::Network.code(), 5);
274        assert_eq!(ExitNumber::Authentication.code(), 6);
275        assert_eq!(ExitNumber::Permission.code(), 7);
276        assert_eq!(ExitNumber::Absence.code(), 8);
277        assert_eq!(ExitNumber::Conflict.code(), 9);
278        assert_eq!(ExitNumber::Limit.code(), 10);
279        assert_eq!(ExitNumber::Server.code(), 11);
280        assert_eq!(ExitNumber::Timeout.code(), 124);
281        assert_eq!(ExitNumber::Interrupted.code(), 130);
282        assert_eq!(ExitNumber::BrokenPipe.code(), 141);
283    }
284
285    /// Only the three transient categories are retryable without changing input.
286    #[test]
287    fn only_transient_categories_are_retryable() {
288        assert!(Category::Network.is_retryable());
289        assert!(Category::Conflict.is_retryable());
290        assert!(Category::Timeout.is_retryable());
291        assert!(!Category::Usage.is_retryable());
292        assert!(!Category::Validation.is_retryable());
293        assert!(!Category::Permission.is_retryable());
294        assert!(!Category::Absence.is_retryable());
295    }
296}