Skip to main content

simbad_resolver/
config.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//! Configuration types: [`SimbadConfig`] (network-backed resolvers) and
6//! [`ResolverConfig`] (the cache-first facade).
7
8use std::time::Duration;
9
10use uuid::Uuid;
11
12/// Default SIMBAD TAP sync endpoint (CDS).
13pub const DEFAULT_TAP_ENDPOINT: &str = "https://simbad.cds.unistra.fr/simbad/sim-tap/sync";
14
15/// Polite identifying `User-Agent` (CDS norm): includes this crate's version
16/// and a contact URL.
17pub const DEFAULT_USER_AGENT: &str = concat!(
18    "simbad-resolver/",
19    env!("CARGO_PKG_VERSION"),
20    " (+https://github.com/nightwatch-astro/simbad-resolver)"
21);
22
23/// Configuration for a network-backed [`crate::Resolver`] (e.g. the SIMBAD TAP
24/// or Sesame resolver).
25#[derive(Clone, Debug)]
26pub struct SimbadConfig {
27    /// Backend endpoint URL (validated by the resolver via `url`; https, or
28    /// http loopback for local testing).
29    pub endpoint: String,
30    /// Per-request timeout; on expiry the resolver returns
31    /// [`crate::ResolveError::Timeout`] so callers degrade to seed+cache.
32    pub timeout: Duration,
33    /// Identifying `User-Agent` header value.
34    pub user_agent: String,
35}
36
37impl Default for SimbadConfig {
38    fn default() -> Self {
39        Self {
40            endpoint: DEFAULT_TAP_ENDPOINT.to_owned(),
41            timeout: Duration::from_secs(10),
42            user_agent: DEFAULT_USER_AGENT.to_owned(),
43        }
44    }
45}
46
47impl SimbadConfig {
48    /// Build a config from caller-persisted settings, clamping `timeout_secs`
49    /// to a minimum of 1 second (a 0s timeout would fail every request).
50    ///
51    /// ```
52    /// use std::time::Duration;
53    ///
54    /// use simbad_resolver::SimbadConfig;
55    ///
56    /// let config = SimbadConfig::from_settings("https://example.test/tap", 0);
57    /// assert_eq!(config.timeout, Duration::from_secs(1), "0s is clamped to 1s");
58    /// ```
59    #[must_use]
60    pub fn from_settings(endpoint: impl Into<String>, timeout_secs: u64) -> Self {
61        Self {
62            endpoint: endpoint.into(),
63            timeout: Duration::from_secs(timeout_secs.max(1)),
64            user_agent: DEFAULT_USER_AGENT.to_owned(),
65        }
66    }
67}
68
69/// Configuration for the [`crate::SimbadResolver`] facade.
70///
71/// Settings are supplied by the caller at construction; the library persists
72/// none of them.
73///
74/// ```
75/// use simbad_resolver::ResolverConfig;
76///
77/// // Namespaced by a fixed, application-specific seed so derived target ids
78/// // stay stable across runs. See `SimbadResolver::new` for its full role.
79/// let config = ResolverConfig::new("my-app.targets").with_fuzzy(0.6);
80/// assert!(config.online_enabled);
81/// assert_eq!(config.fuzzy_min_score, Some(0.6));
82/// ```
83///
84/// [`SimbadResolver::new`]: crate::SimbadResolver::new
85#[derive(Clone, Debug)]
86pub struct ResolverConfig {
87    /// Whether online resolution is attempted on a cache miss. When `false`,
88    /// only the cache is consulted (offline mode).
89    pub online_enabled: bool,
90    /// The id namespace used to derive stable target ids from designations.
91    /// Supply your own seed via [`ResolverConfig::new`] for id continuity.
92    pub namespace: Uuid,
93    /// Minimum token-set similarity (`0.0..=1.0`) for a fuzzy typeahead hit in
94    /// [`crate::SimbadResolver::search`]. `None` (the default) disables fuzzy
95    /// matching; exact/prefix/substring ranking is unaffected either way.
96    pub fuzzy_min_score: Option<f32>,
97}
98
99impl ResolverConfig {
100    /// Build a config from an id-namespace seed (e.g. your app's reverse-DNS
101    /// name). Online resolution defaults to enabled.
102    ///
103    /// ```
104    /// use simbad_resolver::ResolverConfig;
105    ///
106    /// let a = ResolverConfig::new("my-app.targets");
107    /// let b = ResolverConfig::new("my-app.targets");
108    /// assert!(a.online_enabled);
109    /// assert_eq!(a.namespace, b.namespace, "same seed derives the same namespace");
110    /// ```
111    #[must_use]
112    pub fn new(namespace_seed: &str) -> Self {
113        Self {
114            online_enabled: true,
115            namespace: crate::identity::namespace(namespace_seed),
116            fuzzy_min_score: None,
117        }
118    }
119
120    /// Set whether online resolution is enabled.
121    ///
122    /// ```
123    /// use simbad_resolver::ResolverConfig;
124    ///
125    /// let offline = ResolverConfig::new("x").with_online(false);
126    /// assert!(!offline.online_enabled);
127    /// ```
128    #[must_use]
129    pub fn with_online(mut self, online_enabled: bool) -> Self {
130        self.online_enabled = online_enabled;
131        self
132    }
133
134    /// Use an explicit namespace UUID (rather than deriving it from a seed).
135    ///
136    /// ```
137    /// use simbad_resolver::ResolverConfig;
138    /// use uuid::Uuid;
139    ///
140    /// let explicit = Uuid::from_u128(0x1234_5678_90ab_cdef_1234_5678_90ab_cdef);
141    /// let config = ResolverConfig::new("x").with_namespace(explicit);
142    /// assert_eq!(config.namespace, explicit);
143    /// ```
144    #[must_use]
145    pub fn with_namespace(mut self, namespace: Uuid) -> Self {
146        self.namespace = namespace;
147        self
148    }
149
150    /// Enable fuzzy typeahead in [`crate::SimbadResolver::search`]: after
151    /// exact/prefix/substring matches, remaining result slots are filled with
152    /// hits whose token-set similarity to the query is at least `min_score`
153    /// (clamped to `0.0..=1.0`), in a [`crate::RANK_FUZZY`] tier. Off by default.
154    /// Does not affect [`crate::SimbadResolver::resolve`], which stays exact.
155    ///
156    /// ```
157    /// use simbad_resolver::ResolverConfig;
158    ///
159    /// let config = ResolverConfig::new("x").with_fuzzy(2.0); // clamped to 1.0
160    /// assert_eq!(config.fuzzy_min_score, Some(1.0));
161    /// ```
162    #[must_use]
163    pub fn with_fuzzy(mut self, min_score: f32) -> Self {
164        self.fuzzy_min_score = Some(min_score.clamp(0.0, 1.0));
165        self
166    }
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172
173    #[test]
174    fn default_uses_cds_tap_endpoint() {
175        let c = SimbadConfig::default();
176        assert_eq!(c.endpoint, DEFAULT_TAP_ENDPOINT);
177        assert_eq!(c.timeout, Duration::from_secs(10));
178        assert!(c.user_agent.starts_with("simbad-resolver/"));
179    }
180
181    #[test]
182    fn from_settings_clamps_zero_timeout_to_one_second() {
183        let c = SimbadConfig::from_settings("https://example/tap", 0);
184        assert_eq!(c.timeout, Duration::from_secs(1));
185        assert_eq!(c.endpoint, "https://example/tap");
186    }
187
188    #[test]
189    fn from_settings_preserves_larger_timeout() {
190        let c = SimbadConfig::from_settings("https://example/tap", 30);
191        assert_eq!(c.timeout, Duration::from_secs(30));
192    }
193
194    #[test]
195    fn new_enables_online_and_derives_a_stable_namespace() {
196        let a = ResolverConfig::new("example.targets");
197        let b = ResolverConfig::new("example.targets");
198        let c = ResolverConfig::new("other.targets");
199        assert!(a.online_enabled);
200        assert_eq!(a.namespace, b.namespace, "same seed derives the same namespace");
201        assert_ne!(a.namespace, c.namespace, "a different seed derives a different namespace");
202    }
203
204    #[test]
205    fn with_online_toggles_the_flag() {
206        assert!(!ResolverConfig::new("x").with_online(false).online_enabled);
207        assert!(ResolverConfig::new("x").with_online(false).with_online(true).online_enabled);
208    }
209
210    #[test]
211    fn with_namespace_overrides_the_derived_namespace() {
212        let explicit = Uuid::from_u128(0x1234_5678_90ab_cdef_1234_5678_90ab_cdef);
213        assert_eq!(ResolverConfig::new("x").with_namespace(explicit).namespace, explicit);
214    }
215
216    #[test]
217    fn fuzzy_is_disabled_by_default() {
218        assert_eq!(ResolverConfig::new("x").fuzzy_min_score, None);
219    }
220
221    #[test]
222    fn with_fuzzy_sets_and_clamps_the_threshold() {
223        assert_eq!(ResolverConfig::new("x").with_fuzzy(0.5).fuzzy_min_score, Some(0.5));
224        assert_eq!(ResolverConfig::new("x").with_fuzzy(2.0).fuzzy_min_score, Some(1.0));
225        assert_eq!(ResolverConfig::new("x").with_fuzzy(-1.0).fuzzy_min_score, Some(0.0));
226    }
227}