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}