1use std::fmt;
25
26pub const CANONICAL: [&str; 25] = [
31 "INVALID_TOOL_INPUT",
32 "MUTATION_REQUIRED",
33 "QUERY_REQUIRED",
34 "INVALID_VARIABLES",
35 "MISSING_GRAPHQL_VARIABLES",
36 "UNDECLARED_GRAPHQL_VARIABLES",
37 "UNSUPPORTED_GRAPHQL_VARIABLE_TYPE",
38 "UNSUPPORTED_GRAPHQL_VARIABLE_DEFAULT",
39 "INVALID_GRAPHQL_VARIABLE_VALUE",
40 "INVALID_GRAPHQL_QUERY",
41 "INVALID_GRAPHQL_MUTATION",
42 "QUERY_NOT_ALLOWED",
43 "NOT_A_MUTATION",
44 "RESERVED_MUTATION_ALIAS",
45 "INVALID_DATE_FILTER",
46 "QUERY_FORBIDDEN",
47 "QUERY_TIMEOUT",
48 "DATABASE_UNAVAILABLE",
49 "QUERY_EXECUTION_FAILED",
50 "MUTATION_EXECUTION_FAILED",
51 "MUTATION_RESULT_UNREADABLE",
52 "INVALID_QUERY_RESPONSE",
53 "INVALID_MUTATION_RESPONSE",
54 "PAGINATION_FAILED",
55 "QUERY_DATA_FAILED",
56];
57
58pub const UNSPECIFIED: &str = "ACTION_FAILED";
63
64const MAX_CODE_BYTES: usize = 64;
66
67const MIN_CODE_BYTES: usize = 2;
69
70#[non_exhaustive]
72#[derive(Clone, Debug, PartialEq, Eq)]
73pub enum Code {
74 InvalidToolInput,
76 MutationRequired,
78 QueryRequired,
80 InvalidVariables,
82 MissingGraphqlVariables,
84 UndeclaredGraphqlVariables,
86 UnsupportedGraphqlVariableType,
88 UnsupportedGraphqlVariableDefault,
90 InvalidGraphqlVariableValue,
92 InvalidGraphqlQuery,
94 InvalidGraphqlMutation,
96 QueryNotAllowed,
98 NotAMutation,
100 ReservedMutationAlias,
102 InvalidDateFilter,
104 QueryForbidden,
106 QueryTimeout,
108 DatabaseUnavailable,
110 QueryExecutionFailed,
112 MutationExecutionFailed,
114 MutationResultUnreadable,
116 InvalidQueryResponse,
118 InvalidMutationResponse,
120 PaginationFailed,
122 QueryDataFailed,
124 Custom(String),
126}
127
128impl Code {
129 pub fn as_str(&self) -> &str {
134 match self {
135 Code::InvalidToolInput => "INVALID_TOOL_INPUT",
136 Code::MutationRequired => "MUTATION_REQUIRED",
137 Code::QueryRequired => "QUERY_REQUIRED",
138 Code::InvalidVariables => "INVALID_VARIABLES",
139 Code::MissingGraphqlVariables => "MISSING_GRAPHQL_VARIABLES",
140 Code::UndeclaredGraphqlVariables => "UNDECLARED_GRAPHQL_VARIABLES",
141 Code::UnsupportedGraphqlVariableType => "UNSUPPORTED_GRAPHQL_VARIABLE_TYPE",
142 Code::UnsupportedGraphqlVariableDefault => "UNSUPPORTED_GRAPHQL_VARIABLE_DEFAULT",
143 Code::InvalidGraphqlVariableValue => "INVALID_GRAPHQL_VARIABLE_VALUE",
144 Code::InvalidGraphqlQuery => "INVALID_GRAPHQL_QUERY",
145 Code::InvalidGraphqlMutation => "INVALID_GRAPHQL_MUTATION",
146 Code::QueryNotAllowed => "QUERY_NOT_ALLOWED",
147 Code::NotAMutation => "NOT_A_MUTATION",
148 Code::ReservedMutationAlias => "RESERVED_MUTATION_ALIAS",
149 Code::InvalidDateFilter => "INVALID_DATE_FILTER",
150 Code::QueryForbidden => "QUERY_FORBIDDEN",
151 Code::QueryTimeout => "QUERY_TIMEOUT",
152 Code::DatabaseUnavailable => "DATABASE_UNAVAILABLE",
153 Code::QueryExecutionFailed => "QUERY_EXECUTION_FAILED",
154 Code::MutationExecutionFailed => "MUTATION_EXECUTION_FAILED",
155 Code::MutationResultUnreadable => "MUTATION_RESULT_UNREADABLE",
156 Code::InvalidQueryResponse => "INVALID_QUERY_RESPONSE",
157 Code::InvalidMutationResponse => "INVALID_MUTATION_RESPONSE",
158 Code::PaginationFailed => "PAGINATION_FAILED",
159 Code::QueryDataFailed => "QUERY_DATA_FAILED",
160 Code::Custom(code) => code.as_str(),
161 }
162 }
163
164 pub fn wire(&self) -> &str {
171 match self {
172 Code::Custom(code) if !wire_safe(code) => UNSPECIFIED,
173 other => other.as_str(),
174 }
175 }
176
177 pub fn unspecified() -> Code {
184 Code::Custom(UNSPECIFIED.to_string())
185 }
186
187 pub fn category(&self) -> Category {
189 match self {
190 Code::InvalidToolInput
191 | Code::MutationRequired
192 | Code::QueryRequired
193 | Code::InvalidVariables
194 | Code::MissingGraphqlVariables
195 | Code::UndeclaredGraphqlVariables
196 | Code::UnsupportedGraphqlVariableType
197 | Code::UnsupportedGraphqlVariableDefault
198 | Code::InvalidGraphqlVariableValue
199 | Code::InvalidGraphqlQuery
200 | Code::InvalidGraphqlMutation
201 | Code::QueryNotAllowed
202 | Code::NotAMutation
203 | Code::ReservedMutationAlias
204 | Code::InvalidDateFilter => Category::Validation,
205 Code::QueryForbidden => Category::Authorization,
206 Code::QueryTimeout => Category::Timeout,
207 Code::DatabaseUnavailable => Category::Availability,
208 Code::QueryExecutionFailed
209 | Code::MutationExecutionFailed
210 | Code::MutationResultUnreadable => Category::Execution,
211 Code::InvalidQueryResponse | Code::InvalidMutationResponse => Category::Response,
212 Code::PaginationFailed => Category::Pagination,
213 Code::QueryDataFailed => Category::Internal,
214 Code::Custom(_) => Category::Execution,
215 }
216 }
217
218 pub fn retryable(&self) -> bool {
225 matches!(self, Code::QueryTimeout | Code::DatabaseUnavailable)
226 }
227}
228
229impl fmt::Display for Code {
230 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
231 formatter.write_str(self.wire())
232 }
233}
234
235#[non_exhaustive]
241#[derive(Clone, Copy, Debug, PartialEq, Eq)]
242pub enum Category {
243 Validation,
245 Authorization,
247 Timeout,
249 Availability,
251 Execution,
253 Response,
255 Pagination,
257 Internal,
259}
260
261impl Category {
262 pub fn as_str(&self) -> &str {
264 match self {
265 Category::Validation => "validation",
266 Category::Authorization => "authorization",
267 Category::Timeout => "timeout",
268 Category::Availability => "availability",
269 Category::Execution => "execution",
270 Category::Response => "response",
271 Category::Pagination => "pagination",
272 Category::Internal => "internal",
273 }
274 }
275}
276
277impl fmt::Display for Category {
278 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
279 formatter.write_str(self.as_str())
280 }
281}
282
283fn wire_safe(code: &str) -> bool {
285 (MIN_CODE_BYTES..=MAX_CODE_BYTES).contains(&code.len())
286 && code
287 .bytes()
288 .all(|byte| byte.is_ascii_uppercase() || byte.is_ascii_digit() || byte == b'_')
289 && code.as_bytes()[0].is_ascii_uppercase()
290}
291
292#[cfg(test)]
293mod tests {
294 use super::*;
295
296 const EVERY: [Code; 25] = [
300 Code::InvalidToolInput,
301 Code::MutationRequired,
302 Code::QueryRequired,
303 Code::InvalidVariables,
304 Code::MissingGraphqlVariables,
305 Code::UndeclaredGraphqlVariables,
306 Code::UnsupportedGraphqlVariableType,
307 Code::UnsupportedGraphqlVariableDefault,
308 Code::InvalidGraphqlVariableValue,
309 Code::InvalidGraphqlQuery,
310 Code::InvalidGraphqlMutation,
311 Code::QueryNotAllowed,
312 Code::NotAMutation,
313 Code::ReservedMutationAlias,
314 Code::InvalidDateFilter,
315 Code::QueryForbidden,
316 Code::QueryTimeout,
317 Code::DatabaseUnavailable,
318 Code::QueryExecutionFailed,
319 Code::MutationExecutionFailed,
320 Code::MutationResultUnreadable,
321 Code::InvalidQueryResponse,
322 Code::InvalidMutationResponse,
323 Code::PaginationFailed,
324 Code::QueryDataFailed,
325 ];
326
327 #[test]
328 fn every_variant_is_canonical() {
329 for code in EVERY.iter() {
332 let known = match code {
333 Code::Custom(_) => false,
334 _ => CANONICAL.contains(&code.as_str()),
335 };
336
337 assert!(known, "{} is not in CANONICAL", code.as_str());
338 }
339
340 assert_eq!(EVERY.len(), CANONICAL.len());
341 }
342
343 #[test]
344 fn canonical_order_matches_the_enum() {
345 let listed: Vec<&str> = EVERY.iter().map(Code::as_str).collect();
346
347 assert_eq!(listed, CANONICAL.to_vec());
348 }
349
350 #[test]
351 fn only_confirmed_timeouts_and_outages_are_retryable() {
352 let retryable: Vec<&str> = EVERY
353 .iter()
354 .filter(|code| code.retryable())
355 .map(Code::as_str)
356 .collect();
357
358 assert_eq!(retryable, vec!["QUERY_TIMEOUT", "DATABASE_UNAVAILABLE"]);
359 }
360
361 #[test]
362 fn a_custom_code_the_wire_cannot_carry_is_replaced() {
363 assert_eq!(Code::Custom("INVOICE_PAID".into()).wire(), "INVOICE_PAID");
364 assert_eq!(Code::Custom("invoice paid".into()).wire(), UNSPECIFIED);
365 assert_eq!(Code::Custom(String::new()).wire(), UNSPECIFIED);
366 assert_eq!(Code::Custom("_LEADING".into()).wire(), UNSPECIFIED);
367 assert_eq!(Code::Custom("X".repeat(65)).wire(), UNSPECIFIED);
368 }
369}