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}