Skip to main content

fetchium_core/search/
fallback.rs

1//! Fallback chain logic — ordered backend fallback with result quality thresholds.
2//!
3//! When the primary backend returns fewer than `min_results` results (or fails),
4//! the chain automatically tries the next backend. This handles API outages,
5//! rate limits, and degraded service gracefully.
6//!
7//! # Design
8//! - Each entry has a `min_results` threshold; falling short triggers fallback.
9//! - Per-backend timeout prevents slow backends from blocking the chain.
10//! - The best partial result set is returned if all backends fail to meet thresholds.
11
12use crate::error::FetchiumResult;
13use crate::search::SearchBackend;
14use crate::types::{BackendId, ResultItem};
15use std::collections::HashMap;
16use std::sync::Arc;
17use std::time::{Duration, Instant};
18use tokio::time::timeout;
19use tracing::{info, warn};
20
21// ── Chain entry ────────────────────────────────────────────────────────────────
22
23/// One entry in the fallback chain, pairing a backend with its quality threshold.
24struct ChainEntry {
25    backend: Arc<dyn SearchBackend>,
26    /// If the backend returns fewer than this many results, fall through to the next.
27    min_results: usize,
28}
29
30// ── FallbackChain ──────────────────────────────────────────────────────────────
31
32/// Ordered fallback chain: try backends in sequence until quality bar is met.
33///
34/// # Example
35/// ```no_run
36/// # use std::sync::Arc;
37/// # use fetchium_core::search::fallback::FallbackChain;
38/// let mut chain = FallbackChain::new();
39/// // chain.add(google_backend, 5).add(ddg_backend, 1);
40/// ```
41pub struct FallbackChain {
42    entries: Vec<ChainEntry>,
43    /// Maximum time to wait for any single backend.
44    timeout: Duration,
45}
46
47impl FallbackChain {
48    /// Create an empty fallback chain with a 15-second per-backend timeout.
49    pub fn new() -> Self {
50        Self::with_timeout(Duration::from_secs(15))
51    }
52
53    /// Create an empty fallback chain with a custom per-backend timeout.
54    pub fn with_timeout(timeout: Duration) -> Self {
55        Self {
56            entries: Vec::new(),
57            timeout,
58        }
59    }
60
61    /// Append a backend to the chain.
62    ///
63    /// `min_results` triggers fallback to the next entry if the backend returns
64    /// fewer results. Set to `0` to always accept results from this backend.
65    pub fn add(&mut self, backend: Arc<dyn SearchBackend>, min_results: usize) -> &mut Self {
66        self.entries.push(ChainEntry {
67            backend,
68            min_results,
69        });
70        self
71    }
72
73    /// Execute the chain: try each backend in order, falling back when needed.
74    ///
75    /// Returns:
76    /// - Results from the first backend that meets `min_results`, **or**
77    /// - The largest partial result set collected across all backends if none meet the threshold.
78    /// - An empty `Vec` if all backends fail entirely.
79    pub async fn execute(&self, query: &str, max_results: u32) -> FetchiumResult<Vec<ResultItem>> {
80        let mut best_results: Vec<ResultItem> = Vec::new();
81
82        for entry in &self.entries {
83            let backend_id = entry.backend.id();
84            let start = Instant::now();
85
86            match timeout(self.timeout, entry.backend.search(query, max_results)).await {
87                Ok(Ok(results)) => {
88                    let elapsed_ms = start.elapsed().as_millis();
89                    let n = results.len();
90                    info!(
91                        "FallbackChain: {:?} returned {} results in {}ms",
92                        backend_id, n, elapsed_ms
93                    );
94
95                    if n >= entry.min_results {
96                        // Quality bar met — return immediately
97                        return Ok(results);
98                    }
99
100                    // Below threshold — keep as best partial if it improves on what we have
101                    if n > best_results.len() {
102                        best_results = results;
103                    }
104                    warn!(
105                        "FallbackChain: {:?} returned {} results (min={}), falling back",
106                        backend_id, n, entry.min_results
107                    );
108                }
109                Ok(Err(e)) => {
110                    warn!("FallbackChain: {:?} error: {e}", backend_id);
111                }
112                Err(_elapsed) => {
113                    warn!(
114                        "FallbackChain: {:?} timed out after {:?}",
115                        backend_id, self.timeout
116                    );
117                }
118            }
119        }
120
121        if best_results.is_empty() {
122            warn!(
123                "FallbackChain: all {} backend(s) exhausted for {:?}",
124                self.entries.len(),
125                query
126            );
127        }
128
129        Ok(best_results)
130    }
131
132    /// Number of backends registered in this chain.
133    pub fn len(&self) -> usize {
134        self.entries.len()
135    }
136
137    /// Returns `true` if no backends have been added.
138    pub fn is_empty(&self) -> bool {
139        self.entries.is_empty()
140    }
141}
142
143impl Default for FallbackChain {
144    fn default() -> Self {
145        Self::new()
146    }
147}
148
149// ── Chain factory ──────────────────────────────────────────────────────────────
150
151/// Build the standard web-search fallback chain from a map of available backends.
152///
153/// Priority order (highest quality first):
154/// `Google → Bing → SearXNG → Brave → DuckDuckGo`
155///
156/// Only backends present in `backends` are added to the chain.
157pub fn build_web_search_chain(
158    backends: &HashMap<BackendId, Arc<dyn SearchBackend>>,
159) -> FallbackChain {
160    let mut chain = FallbackChain::new();
161
162    // (BackendId, min_results_threshold)
163    let priority_order: &[(BackendId, usize)] = &[
164        (BackendId::Google, 5),
165        (BackendId::Bing, 3),
166        (BackendId::Searxng, 3),
167        (BackendId::Brave, 3),
168        (BackendId::DuckDuckGo, 1),
169    ];
170
171    for (id, min_results) in priority_order {
172        if let Some(backend) = backends.get(id) {
173            chain.add(Arc::clone(backend), *min_results);
174        }
175    }
176
177    chain
178}
179
180// ── Tests ──────────────────────────────────────────────────────────────────────
181
182#[cfg(test)]
183mod tests {
184    use super::*;
185    use crate::types::BackendId;
186    use async_trait::async_trait;
187    use std::sync::atomic::{AtomicUsize, Ordering};
188
189    // ── Mock backend ──────────────────────────────────────────────────────────
190
191    /// A mock backend that always returns a fixed number of results.
192    struct MockBackend {
193        id: BackendId,
194        results: Vec<ResultItem>,
195        call_count: Arc<AtomicUsize>,
196    }
197
198    impl MockBackend {
199        /// Construct a mock backend and return its call counter and `Arc<dyn SearchBackend>`.
200        fn make(id: BackendId, n_results: usize) -> (Arc<AtomicUsize>, Arc<dyn SearchBackend>) {
201            let counter = Arc::new(AtomicUsize::new(0));
202            let results = (0..n_results)
203                .map(|i| ResultItem {
204                    title: format!("Result {i}"),
205                    url: format!("https://example.com/{i}"),
206                    snippet: format!("Snippet for result {i}"),
207                    rank: (i + 1) as u32,
208                    backend: id.clone(),
209                    score: None,
210                    published_date: None,
211                })
212                .collect();
213            let backend = Arc::new(MockBackend {
214                id,
215                results,
216                call_count: Arc::clone(&counter),
217            });
218            (counter, backend as Arc<dyn SearchBackend>)
219        }
220    }
221
222    #[async_trait]
223    impl SearchBackend for MockBackend {
224        fn id(&self) -> BackendId {
225            self.id.clone()
226        }
227
228        async fn search(&self, _query: &str, _max: u32) -> FetchiumResult<Vec<ResultItem>> {
229            self.call_count.fetch_add(1, Ordering::SeqCst);
230            Ok(self.results.clone())
231        }
232    }
233
234    /// A mock backend that always returns an error.
235    struct ErrorBackend {
236        id: BackendId,
237        call_count: Arc<AtomicUsize>,
238    }
239
240    impl ErrorBackend {
241        fn make(id: BackendId) -> (Arc<AtomicUsize>, Arc<dyn SearchBackend>) {
242            let counter = Arc::new(AtomicUsize::new(0));
243            let backend = Arc::new(ErrorBackend {
244                id,
245                call_count: Arc::clone(&counter),
246            });
247            (counter, backend as Arc<dyn SearchBackend>)
248        }
249    }
250
251    #[async_trait]
252    impl SearchBackend for ErrorBackend {
253        fn id(&self) -> BackendId {
254            self.id.clone()
255        }
256
257        async fn search(&self, _query: &str, _max: u32) -> FetchiumResult<Vec<ResultItem>> {
258            self.call_count.fetch_add(1, Ordering::SeqCst);
259            Err(crate::error::FetchiumError::Search(
260                "mock error".to_string(),
261            ))
262        }
263    }
264
265    // ── Tests ─────────────────────────────────────────────────────────────────
266
267    #[tokio::test]
268    async fn chain_uses_first_backend_when_sufficient_results() {
269        let (counter1, b1) = MockBackend::make(BackendId::Google, 10);
270        let (counter2, b2) = MockBackend::make(BackendId::Bing, 10);
271
272        let mut chain = FallbackChain::new();
273        chain.add(b1, 5).add(b2, 5);
274
275        let results = chain.execute("test query", 10).await.unwrap();
276        assert_eq!(
277            results.len(),
278            10,
279            "Should get 10 results from first backend"
280        );
281        assert_eq!(
282            counter1.load(Ordering::SeqCst),
283            1,
284            "First backend called once"
285        );
286        assert_eq!(
287            counter2.load(Ordering::SeqCst),
288            0,
289            "Second backend NOT called"
290        );
291    }
292
293    #[tokio::test]
294    async fn chain_falls_back_when_too_few_results() {
295        let (_c1, b1) = MockBackend::make(BackendId::Google, 2); // Only 2 results
296        let (counter2, b2) = MockBackend::make(BackendId::Bing, 10);
297
298        let mut chain = FallbackChain::new();
299        chain.add(b1, 5).add(b2, 5); // min_results=5
300
301        let results = chain.execute("test query", 10).await.unwrap();
302        assert_eq!(results.len(), 10, "Should get 10 results from fallback");
303        assert_eq!(
304            counter2.load(Ordering::SeqCst),
305            1,
306            "Should have fallen back to second backend"
307        );
308    }
309
310    #[tokio::test]
311    async fn chain_returns_best_partial_when_all_fail_threshold() {
312        let (_c1, b1) = MockBackend::make(BackendId::Google, 0); // 0 results
313        let (_c2, b2) = MockBackend::make(BackendId::Bing, 2); // 2 results (< min 5)
314
315        let mut chain = FallbackChain::new();
316        chain.add(b1, 5).add(b2, 5); // Neither meets min_results=5
317
318        let results = chain.execute("test query", 10).await.unwrap();
319        // Best partial was 2 results from Bing
320        assert_eq!(results.len(), 2, "Should return best partial (2 from Bing)");
321    }
322
323    #[tokio::test]
324    async fn chain_skips_error_backends_and_falls_back() {
325        let (err_counter, b_err) = ErrorBackend::make(BackendId::Google);
326        let (ok_counter, b_ok) = MockBackend::make(BackendId::Bing, 7);
327
328        let mut chain = FallbackChain::new();
329        chain.add(b_err, 5).add(b_ok, 5);
330
331        let results = chain.execute("test", 10).await.unwrap();
332        assert_eq!(results.len(), 7);
333        assert_eq!(
334            err_counter.load(Ordering::SeqCst),
335            1,
336            "Error backend was tried"
337        );
338        assert_eq!(ok_counter.load(Ordering::SeqCst), 1, "OK backend was used");
339    }
340
341    #[tokio::test]
342    async fn chain_returns_empty_when_all_error() {
343        let (_c1, b1) = ErrorBackend::make(BackendId::Google);
344        let (_c2, b2) = ErrorBackend::make(BackendId::Bing);
345
346        let mut chain = FallbackChain::new();
347        chain.add(b1, 5).add(b2, 5);
348
349        let results = chain.execute("test", 10).await.unwrap();
350        assert!(results.is_empty(), "All errors → empty results");
351    }
352
353    #[tokio::test]
354    async fn empty_chain_returns_empty_results() {
355        let chain = FallbackChain::new();
356        let results = chain.execute("test", 10).await.unwrap();
357        assert!(results.is_empty());
358    }
359
360    #[tokio::test]
361    async fn chain_with_zero_min_results_always_accepts() {
362        let (_counter, b) = MockBackend::make(BackendId::DuckDuckGo, 1); // Only 1 result
363        let mut chain = FallbackChain::new();
364        chain.add(b, 0); // min_results=0 means always accept
365
366        let results = chain.execute("test", 10).await.unwrap();
367        assert_eq!(results.len(), 1, "Zero min_results should always accept");
368    }
369
370    #[test]
371    fn chain_len_and_is_empty() {
372        let mut chain = FallbackChain::new();
373        assert!(chain.is_empty());
374        assert_eq!(chain.len(), 0);
375
376        let (_c, b) = MockBackend::make(BackendId::DuckDuckGo, 0);
377        chain.add(b, 1);
378        assert!(!chain.is_empty());
379        assert_eq!(chain.len(), 1);
380    }
381
382    #[test]
383    fn build_web_search_chain_respects_priority() {
384        let mut backends: HashMap<BackendId, Arc<dyn SearchBackend>> = HashMap::new();
385        let (_c1, b1) = MockBackend::make(BackendId::DuckDuckGo, 5);
386        let (_c2, b2) = MockBackend::make(BackendId::Brave, 5);
387        backends.insert(BackendId::DuckDuckGo, b1);
388        backends.insert(BackendId::Brave, b2);
389
390        let chain = build_web_search_chain(&backends);
391        // Should have both backends in the chain
392        assert_eq!(chain.len(), 2, "Chain should have 2 entries");
393    }
394
395    #[test]
396    fn build_web_search_chain_empty_backends() {
397        let backends: HashMap<BackendId, Arc<dyn SearchBackend>> = HashMap::new();
398        let chain = build_web_search_chain(&backends);
399        assert!(chain.is_empty(), "Empty backends map → empty chain");
400    }
401}