Skip to main content

simbad_resolver/
resolver.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//! The network-resolution seam: [`Resolver`], [`PositionResolver`],
6//! [`OfflineResolver`], and (test-only) [`FakeResolver`].
7//!
8//! Object-safe via `async-trait` so a boxed `dyn Resolver` can be shared
9//! across an async runtime.
10
11use crate::error::ResolveError;
12use crate::types::{PositionMatch, ResolvedIdentity};
13
14/// Resolve a designation or common name to one canonical identity.
15///
16/// Zero rows resolve to [`ResolveError::NotFound`], more than one distinct
17/// physical object to [`ResolveError::Ambiguous`], a transport/timeout failure
18/// to [`ResolveError::Network`]/[`ResolveError::Timeout`], a disabled backend
19/// to [`ResolveError::Disabled`], and a malformed response to
20/// [`ResolveError::Parse`] — implementations MUST return one of these variants
21/// rather than a synthesized identity.
22///
23/// Implementations MUST be `Send + Sync` so a resolver can be shared across a
24/// background queue.
25#[async_trait::async_trait]
26pub trait Resolver: Send + Sync {
27    /// Resolve a complete designation or common name to a canonical identity.
28    ///
29    /// Any [`crate::TapResolver`]/[`crate::SesameResolver`] call needs network
30    /// access (see their own docs for `no_run` examples); this one uses the
31    /// offline [`crate::FakeResolver`] test double instead:
32    ///
33    /// ```
34    /// use simbad_resolver::{FakeResolver, ResolveError, Resolver};
35    ///
36    /// # async fn run() {
37    /// let resolver = FakeResolver::new(); // no canned responses registered
38    /// let err = resolver.resolve("does-not-exist").await.unwrap_err();
39    /// assert!(matches!(err, ResolveError::NotFound(_)));
40    /// # }
41    /// ```
42    async fn resolve(&self, query: &str) -> Result<ResolvedIdentity, ResolveError>;
43
44    /// Resolve a verbatim FITS `OBJECT` header value to a canonical identity.
45    ///
46    /// Matching is exact-normalized only (no fuzzy/probabilistic match); a
47    /// non-matching or ambiguous value stays unresolved rather than being
48    /// guessed. The default delegates to [`Resolver::resolve`];
49    /// implementations only override this when they need FITS-specific
50    /// pre-normalization.
51    ///
52    /// ```
53    /// use simbad_resolver::{
54    ///     AliasKind, FakeResolver, ObjectType, ResolvedAlias, ResolvedIdentity, Resolver,
55    ///     TargetSource,
56    /// };
57    ///
58    /// # async fn run() {
59    /// let m31 = ResolvedIdentity {
60    ///     simbad_oid: Some(1_575_544),
61    ///     primary_designation: "M 31".to_owned(),
62    ///     common_name: None,
63    ///     object_type: ObjectType::Galaxy,
64    ///     otype_raw: "G".to_owned(),
65    ///     ra_deg: 10.684_708,
66    ///     dec_deg: 41.268_75,
67    ///     v_mag: Some(3.44),
68    ///     aliases: vec![ResolvedAlias::new("M 31", AliasKind::Designation)],
69    ///     source: TargetSource::Seed,
70    /// };
71    /// let resolver = FakeResolver::new().with_response("M31", m31);
72    /// // The default impl just forwards to `resolve`.
73    /// let got = resolver.resolve_object("M 31").await.unwrap();
74    /// assert_eq!(got.primary_designation, "M 31");
75    /// # }
76    /// ```
77    async fn resolve_object(&self, object_raw: &str) -> Result<ResolvedIdentity, ResolveError> {
78        self.resolve(object_raw).await
79    }
80}
81
82/// Position resolution (cone search) is a separate capability some resolver
83/// backends provide; not every [`Resolver`] supports it.
84///
85/// [`crate::TapResolver`] is the built-in implementation; it queries the real
86/// SIMBAD TAP endpoint, so this example is `no_run`:
87///
88/// ```no_run
89/// use simbad_resolver::{PositionResolver, TapResolver};
90///
91/// # async fn run() -> Result<(), simbad_resolver::ResolveError> {
92/// let resolver = TapResolver::with_defaults()?;
93/// // Objects within 0.05° of M 31's ICRS position, nearest first (max 5).
94/// let matches = resolver.resolve_position(10.684_708, 41.268_75, 0.05, 5).await?;
95/// for m in &matches {
96///     println!("{} at {:.4}°", m.identity.primary_designation, m.separation_deg);
97/// }
98/// # Ok(())
99/// # }
100/// ```
101#[async_trait::async_trait]
102pub trait PositionResolver: Send + Sync {
103    /// Nearest object(s) within `radius_deg` of `(ra_deg, dec_deg)`, nearest first.
104    async fn resolve_position(
105        &self,
106        ra_deg: f64,
107        dec_deg: f64,
108        radius_deg: f64,
109        limit: usize,
110    ) -> Result<Vec<PositionMatch>, ResolveError>;
111}
112
113/// A zero-cost [`Resolver`] that never reaches the network.
114///
115/// Used when online resolution is disabled by configuration, so callers can
116/// run a cache-first use case without constructing a network client. Every
117/// call reports [`ResolveError::Disabled`].
118///
119/// ```
120/// use simbad_resolver::{OfflineResolver, ResolveError, Resolver};
121///
122/// # async fn run() {
123/// let err = OfflineResolver.resolve("M 31").await.unwrap_err();
124/// assert_eq!(err, ResolveError::Disabled);
125/// # }
126/// ```
127#[derive(Clone, Copy, Debug, Default)]
128pub struct OfflineResolver;
129
130#[async_trait::async_trait]
131impl Resolver for OfflineResolver {
132    async fn resolve(&self, _query: &str) -> Result<ResolvedIdentity, ResolveError> {
133        Err(ResolveError::Disabled)
134    }
135}
136
137// ── FakeResolver (test double) ────────────────────────────────────────────────
138
139/// In-memory test double for [`Resolver`].
140///
141/// Returns canned results without any network access. Gated behind
142/// `cfg(test)` and the `test-util` feature so it is available to downstream
143/// tests but never compiled into production builds.
144///
145/// Lookups are keyed by the *normalized* query ([`crate::normalize::normalize`])
146/// so callers can register a canned identity under any of its aliases.
147///
148/// The `call_count` atomic counter increments on every call to
149/// [`Resolver::resolve`]; read it with [`FakeResolver::call_count`] to assert
150/// the resolver was invoked an exact number of times (useful for verifying
151/// cache-first behaviour).
152#[cfg(any(test, feature = "test-util"))]
153#[derive(Debug, Default)]
154pub struct FakeResolver {
155    /// Normalized query → canned successful identity.
156    responses: std::collections::HashMap<String, ResolvedIdentity>,
157    /// Normalized query → canned error (takes precedence over `responses`).
158    errors: std::collections::HashMap<String, ResolveError>,
159    /// Error returned for any query with no registered response/error.
160    default_error: Option<ResolveError>,
161    /// Number of times [`Resolver::resolve`] has been called.
162    call_count: std::sync::atomic::AtomicUsize,
163}
164
165#[cfg(any(test, feature = "test-util"))]
166impl FakeResolver {
167    /// Construct an empty fake; unknown queries return [`ResolveError::NotFound`].
168    ///
169    /// ```
170    /// use simbad_resolver::{FakeResolver, ResolveError, Resolver};
171    ///
172    /// # async fn run() {
173    /// let err = FakeResolver::new().resolve("anything").await.unwrap_err();
174    /// assert!(matches!(err, ResolveError::NotFound(_)));
175    /// # }
176    /// ```
177    #[must_use]
178    pub fn new() -> Self {
179        Self::default()
180    }
181
182    /// Register a canned successful identity, keyed by the normalized `query`.
183    ///
184    /// ```
185    /// use simbad_resolver::{
186    ///     AliasKind, FakeResolver, ObjectType, ResolvedAlias, ResolvedIdentity, Resolver,
187    ///     TargetSource,
188    /// };
189    ///
190    /// # async fn run() {
191    /// let m31 = ResolvedIdentity {
192    ///     simbad_oid: Some(1_575_544),
193    ///     primary_designation: "M 31".to_owned(),
194    ///     common_name: None,
195    ///     object_type: ObjectType::Galaxy,
196    ///     otype_raw: "G".to_owned(),
197    ///     ra_deg: 10.684_708,
198    ///     dec_deg: 41.268_75,
199    ///     v_mag: Some(3.44),
200    ///     aliases: vec![ResolvedAlias::new("M 31", AliasKind::Designation)],
201    ///     source: TargetSource::Seed,
202    /// };
203    /// let resolver = FakeResolver::new().with_response("M31", m31);
204    /// // Registered under normalized "M31"; any equivalent form matches.
205    /// let got = resolver.resolve("M 31").await.unwrap();
206    /// assert_eq!(got.primary_designation, "M 31");
207    /// # }
208    /// ```
209    #[must_use]
210    pub fn with_response(mut self, query: &str, identity: ResolvedIdentity) -> Self {
211        self.responses.insert(crate::normalize::normalize(query), identity);
212        self
213    }
214
215    /// Register a canned error for `query`, keyed by its normalized form.
216    ///
217    /// ```
218    /// use simbad_resolver::{FakeResolver, ResolveError, Resolver};
219    ///
220    /// # async fn run() {
221    /// let resolver = FakeResolver::new()
222    ///     .with_error("M31", ResolveError::Ambiguous { query: "M31".to_owned(), count: 2 });
223    /// let err = resolver.resolve("M 31").await.unwrap_err();
224    /// assert!(matches!(err, ResolveError::Ambiguous { count: 2, .. }));
225    /// # }
226    /// ```
227    #[must_use]
228    pub fn with_error(mut self, query: &str, error: ResolveError) -> Self {
229        self.errors.insert(crate::normalize::normalize(query), error);
230        self
231    }
232
233    /// Set the error returned for any unregistered query (default:
234    /// [`ResolveError::NotFound`]). Use [`ResolveError::Network`] to simulate
235    /// an offline resolver for degrade-to-cache tests.
236    ///
237    /// ```
238    /// use simbad_resolver::{FakeResolver, ResolveError, Resolver};
239    ///
240    /// # async fn run() {
241    /// let resolver =
242    ///     FakeResolver::new().with_default_error(ResolveError::Network("down".to_owned()));
243    /// let err = resolver.resolve("anything").await.unwrap_err();
244    /// assert!(matches!(err, ResolveError::Network(_)));
245    /// # }
246    /// ```
247    #[must_use]
248    pub fn with_default_error(mut self, error: ResolveError) -> Self {
249        self.default_error = Some(error);
250        self
251    }
252
253    /// Return the number of times [`Resolver::resolve`] has been called.
254    ///
255    /// Uses `Relaxed` ordering; suitable for single-threaded test assertions
256    /// after all async work has completed.
257    ///
258    /// ```
259    /// use simbad_resolver::{FakeResolver, Resolver};
260    ///
261    /// # async fn run() {
262    /// let resolver = FakeResolver::new();
263    /// assert_eq!(resolver.call_count(), 0);
264    /// let _ = resolver.resolve("M 31").await;
265    /// assert_eq!(resolver.call_count(), 1);
266    /// # }
267    /// ```
268    #[must_use]
269    pub fn call_count(&self) -> usize {
270        self.call_count.load(std::sync::atomic::Ordering::Relaxed)
271    }
272}
273
274// `FakeResolver` cannot derive `Clone` because `AtomicUsize` does not
275// implement `Clone`. Provide a manual impl that resets the counter in the
276// clone so each clone starts from zero.
277#[cfg(any(test, feature = "test-util"))]
278impl Clone for FakeResolver {
279    fn clone(&self) -> Self {
280        Self {
281            responses: self.responses.clone(),
282            errors: self.errors.clone(),
283            default_error: self.default_error.clone(),
284            call_count: std::sync::atomic::AtomicUsize::new(0),
285        }
286    }
287}
288
289#[cfg(any(test, feature = "test-util"))]
290#[async_trait::async_trait]
291impl Resolver for FakeResolver {
292    async fn resolve(&self, query: &str) -> Result<ResolvedIdentity, ResolveError> {
293        self.call_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
294        let key = crate::normalize::normalize(query);
295        if let Some(err) = self.errors.get(&key) {
296            return Err(err.clone());
297        }
298        if let Some(identity) = self.responses.get(&key) {
299            return Ok(identity.clone());
300        }
301        Err(self.default_error.clone().unwrap_or_else(|| ResolveError::NotFound(query.to_owned())))
302    }
303}
304
305#[cfg(test)]
306mod tests {
307    use super::*;
308    use crate::types::{AliasKind, ObjectType, ResolvedAlias, TargetSource};
309
310    fn sample_identity() -> ResolvedIdentity {
311        ResolvedIdentity {
312            simbad_oid: Some(1_575_544),
313            primary_designation: "M 31".to_owned(),
314            common_name: Some("Andromeda Galaxy".to_owned()),
315            object_type: ObjectType::Galaxy,
316            otype_raw: "G".to_owned(),
317            ra_deg: 10.684_708,
318            dec_deg: 41.268_75,
319            v_mag: Some(3.44),
320            aliases: vec![
321                ResolvedAlias::new("M 31", AliasKind::Designation),
322                ResolvedAlias::new("NGC 224", AliasKind::Designation),
323                ResolvedAlias::new("Andromeda Galaxy", AliasKind::CommonName),
324            ],
325            source: TargetSource::Resolved,
326        }
327    }
328
329    #[tokio::test]
330    async fn fake_resolver_returns_canned_response() {
331        let resolver = FakeResolver::new().with_response("M31", sample_identity());
332        // Registered under normalized "M31"; querying any alias form hits it.
333        let got = resolver.resolve("M 31").await.unwrap();
334        assert_eq!(got.primary_designation, "M 31");
335        assert_eq!(got.object_type, ObjectType::Galaxy);
336        assert_eq!(got.otype_raw, "G");
337        assert_eq!(got.simbad_oid, Some(1_575_544));
338    }
339
340    #[tokio::test]
341    async fn fake_resolver_unknown_is_not_found() {
342        let resolver = FakeResolver::new();
343        let err = resolver.resolve("does-not-exist").await.unwrap_err();
344        assert!(matches!(err, ResolveError::NotFound(_)));
345    }
346
347    #[tokio::test]
348    async fn fake_resolver_canned_error() {
349        let resolver = FakeResolver::new()
350            .with_error("M31", ResolveError::Ambiguous { query: "M31".to_owned(), count: 2 });
351        let err = resolver.resolve("M 31").await.unwrap_err();
352        assert!(matches!(err, ResolveError::Ambiguous { count: 2, .. }));
353    }
354
355    #[tokio::test]
356    async fn fake_resolver_default_error_simulates_offline() {
357        let resolver =
358            FakeResolver::new().with_default_error(ResolveError::Network("down".to_owned()));
359        let err = resolver.resolve("anything").await.unwrap_err();
360        assert!(matches!(err, ResolveError::Network(_)));
361    }
362
363    #[tokio::test]
364    async fn resolve_object_defaults_to_resolve() {
365        let resolver = FakeResolver::new().with_response("M31", sample_identity());
366        let got = resolver.resolve_object("M 31").await.unwrap();
367        assert_eq!(got.primary_designation, "M 31");
368    }
369
370    #[tokio::test]
371    async fn fake_resolver_call_count_increments() {
372        let resolver = FakeResolver::new().with_response("M31", sample_identity());
373        assert_eq!(resolver.call_count(), 0);
374        let _ = resolver.resolve("M 31").await;
375        let _ = resolver.resolve("m31").await;
376        assert_eq!(resolver.call_count(), 2);
377    }
378
379    #[tokio::test]
380    async fn fake_resolver_clone_resets_call_counter() {
381        let resolver = FakeResolver::new().with_response("M31", sample_identity());
382        let _ = resolver.resolve("M 31").await;
383        assert_eq!(resolver.call_count(), 1);
384
385        // A clone copies the canned responses but starts its own counter at 0.
386        let cloned = resolver.clone();
387        assert_eq!(cloned.call_count(), 0);
388        let got = cloned.resolve("M 31").await.unwrap();
389        assert_eq!(got.primary_designation, "M 31");
390        assert_eq!(cloned.call_count(), 1);
391        assert_eq!(resolver.call_count(), 1, "clone's calls do not affect the original");
392    }
393
394    #[tokio::test]
395    async fn offline_resolver_always_disabled() {
396        let resolver = OfflineResolver;
397        let err = resolver.resolve("M 31").await.unwrap_err();
398        assert_eq!(err, ResolveError::Disabled);
399    }
400
401    /// A minimal [`PositionResolver`] impl, used only to prove the trait is
402    /// object-safe (`Box<dyn PositionResolver>`) and callable.
403    struct FakePositionResolver;
404
405    #[async_trait::async_trait]
406    impl PositionResolver for FakePositionResolver {
407        async fn resolve_position(
408            &self,
409            _ra_deg: f64,
410            _dec_deg: f64,
411            _radius_deg: f64,
412            limit: usize,
413        ) -> Result<Vec<PositionMatch>, ResolveError> {
414            let identity = sample_identity();
415            let matches: Vec<PositionMatch> =
416                std::iter::once(PositionMatch { identity, separation_deg: 0.01 })
417                    .take(limit)
418                    .collect();
419            Ok(matches)
420        }
421    }
422
423    #[tokio::test]
424    async fn position_resolver_is_object_safe_and_callable() {
425        let resolver: Box<dyn PositionResolver> = Box::new(FakePositionResolver);
426        let matches = resolver.resolve_position(10.68, 41.27, 0.5, 5).await.unwrap();
427        assert_eq!(matches.len(), 1);
428        assert!((matches[0].separation_deg - 0.01).abs() < 1e-9);
429    }
430}