about summary refs log tree commit diff
path: root/crates/schema/src/error.rs
blob: 8a6afe15f9cc4882430ef5ccca6857a426073d4d (plain)
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 {}