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}