Skip to main content

simbad_resolver/
error.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5//! Error types: [`ResolveError`] (the resolver seam) and [`Error`] (the facade).
6
7use crate::cache::{CacheError, QueueError};
8
9/// Errors produced by a [`crate::Resolver`].
10///
11/// `Network`/`Timeout`/`Disabled` are transient — degrade to seed+cache and
12/// retry later ([`ResolveError::is_transient`]). `NotFound`/`Ambiguous`/`Parse`
13/// are content misses: the query itself did not resolve, so an identical retry
14/// produces the same result. A resolver reports a content miss as one of these
15/// variants rather than returning a best-guess result in their place.
16///
17/// `Clone`/`Eq` let callers (e.g. a durable retry queue) retain the error
18/// across attempts without re-running the request.
19///
20/// ```
21/// use simbad_resolver::ResolveError;
22///
23/// // Transport failures are worth retrying; content misses are not.
24/// assert!(ResolveError::Network("connection reset".to_owned()).is_transient());
25/// assert!(ResolveError::Timeout(10).is_transient());
26/// assert!(!ResolveError::NotFound("not-an-object".to_owned()).is_transient());
27/// assert!(!ResolveError::Ambiguous { query: "M".to_owned(), count: 3 }.is_transient());
28/// ```
29#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
30pub enum ResolveError {
31    /// Network/transport failure reaching the resolver backend; degrade to
32    /// seed+cache.
33    #[error("resolver backend unreachable: {0}")]
34    Network(String),
35    /// The request exceeded the configured timeout (seconds); degrade to
36    /// seed+cache.
37    #[error("resolver request timed out after {0}s")]
38    Timeout(u64),
39    /// Online resolution is disabled by configuration; seed+cache only.
40    #[error("online resolution is disabled")]
41    Disabled,
42    /// The query did not resolve to any known object (unknown/garbled).
43    #[error("no object resolved for query: {0}")]
44    NotFound(String),
45    /// The query resolved to multiple distinct physical objects; callers
46    /// leave the item unresolved rather than guessing.
47    #[error("query '{query}' is ambiguous ({count} distinct objects)")]
48    Ambiguous {
49        /// The verbatim query.
50        query: String,
51        /// Number of distinct physical objects matched.
52        count: usize,
53    },
54    /// The backend response could not be parsed into a canonical identity.
55    #[error("failed to parse resolver response: {0}")]
56    Parse(String),
57}
58
59impl ResolveError {
60    /// Whether this error is transient (worth retrying later) as opposed to a
61    /// content miss (the query itself does not resolve).
62    #[must_use]
63    pub fn is_transient(&self) -> bool {
64        matches!(self, Self::Network(_) | Self::Timeout(_) | Self::Disabled)
65    }
66}
67
68/// Errors surfaced by the [`crate::SimbadResolver`] facade and
69/// [`crate::BatchResolver`].
70#[derive(Debug, thiserror::Error)]
71pub enum Error {
72    /// A cache backend operation failed.
73    #[error(transparent)]
74    Cache(#[from] CacheError),
75    /// A queue backend operation failed.
76    #[error(transparent)]
77    Queue(#[from] QueueError),
78    /// A resolver produced an unexpected error not modelled as an unresolved
79    /// outcome (the normal not-found/ambiguous/offline cases are represented by
80    /// [`crate::Resolution::Unresolved`], not this variant).
81    #[error(transparent)]
82    Resolve(#[from] ResolveError),
83}
84
85#[cfg(test)]
86mod tests {
87    use super::ResolveError;
88
89    #[test]
90    fn transient_variants() {
91        assert!(ResolveError::Network("down".to_owned()).is_transient());
92        assert!(ResolveError::Timeout(10).is_transient());
93        assert!(ResolveError::Disabled.is_transient());
94    }
95
96    #[test]
97    fn content_miss_variants_are_not_transient() {
98        assert!(!ResolveError::NotFound("x".to_owned()).is_transient());
99        assert!(!ResolveError::Ambiguous { query: "x".to_owned(), count: 2 }.is_transient());
100        assert!(!ResolveError::Parse("bad".to_owned()).is_transient());
101    }
102}