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}