1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
//! The error vocabulary shared with GN4's route.
//!
//! SCOUT section implemented: SCOUT-NATIVE §6 (the variant list and the
//! statuses GN4 maps them to). The mapping itself is GN4's
//! (`src/routes/search.rs::engine_error`) and lives there — this crate
//! only guarantees that the variants exist, carry the message text GN4
//! puts in a response body, and cannot be extended without whoever adds
//! one having to decide what status it means. `tests/error_status.rs`
//! holds that table, kept out of the crate's API on purpose: exporting a
//! status from here would be a second source of truth for a contract
//! GN4 owns (SYNTHESIS §6).
//!
//! The five variants, and what GN4 does with each (SCOUT-NATIVE §6):
//!
//! | Variant | GN4 status | code |
//! |---|---|---|
//! | [`SearchError::InvalidQuery`] | 422 | `invalid_query` |
//! | [`SearchError::Unreachable`] | 502 | `backend_unreachable` |
//! | [`SearchError::Misbehaving`] | 502 | `backend_misbehaving` |
//! | [`SearchError::Backend`] | 502 | `backend_error` |
//! | [`SearchError::Internal`] | 500 | `internal_error` |
use std::error::Error;
use std::fmt;
/// A search failure, in the vocabulary GN4's route already maps.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SearchError {
/// The backend rejected the query as malformed.
///
/// `message` is the backend's diagnostic, put in the response body
/// verbatim; `xapian_error_type` is the exception class when the
/// backend reported one (`QueryParserError`, `InvalidOperationError`),
/// carried through to `detail.xapian_error_type`. Recorded examples:
/// `"Syntax: <expression> AND <expression>"` with `QueryParserError`
/// and `"InvalidOperationError: Query is invalid (invalid Hs/Mm
/// location field)"` (SCOUT-NATIVE §6).
InvalidQuery {
message: String,
xapian_error_type: Option<String>,
},
/// The index (or, on the proxy path, the upstream) could not be
/// reached: an index path that does not exist, is not a directory, or
/// is not a glass index (SCOUT-NATIVE §2), or a transport failure.
Unreachable(String),
/// Something answered, but not with a search result: a document whose
/// stored data is not a hit, or a response body that is not a hit
/// array (SCOUT-NATIVE §4, SCOUT-PROXY §6).
Misbehaving(String),
/// The backend failed on its own side (the proxy path's prose 5xx;
/// SCOUT-PROXY §6).
Backend(String),
/// A local misconfiguration or bug: no index configured, no index
/// path set, an unparsable upstream URL, a failed blocking task
/// (SCOUT-NATIVE §2, §6).
Internal(String),
}
impl SearchError {
/// The diagnostic text GN4 puts in the response body's `detail`.
pub fn message(&self) -> &str {
match self {
Self::InvalidQuery { message, .. } => message,
Self::Unreachable(message)
| Self::Misbehaving(message)
| Self::Backend(message)
| Self::Internal(message) => message,
}
}
/// The xapian exception class, when the failure carried one.
pub fn xapian_error_type(&self) -> Option<&str> {
match self {
Self::InvalidQuery {
xapian_error_type, ..
} => xapian_error_type.as_deref(),
_ => None,
}
}
}
impl fmt::Display for SearchError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidQuery {
xapian_error_type: Some(error_type),
..
} => write!(f, "{} ({error_type})", self.message()),
_ => write!(f, "{}", self.message()),
}
}
}
impl Error for SearchError {}
|