Skip to main content

harness_websearch/engines/
fallback.rs

1//! Ordered fallback engine — mirrors `ddgs backend="auto"` / SearXNG's
2//! cross-engine merge and the TS `engines/fallback.ts`. Engines are tried in
3//! chain order (general-first); their results are ACCUMULATED, de-duplicated
4//! by normalized URL, until the requested `count` is met (sufficiency) or
5//! engines/budget run out.
6//!
7//! Fast path: if the FIRST engine alone meets count, return it directly (no
8//! mixing, no re-rank). When more than one engine contributes, results are
9//! fused with Reciprocal Rank Fusion + engine weights (see rank.rs) — a page
10//! two engines agree on floats up (consensus) and a niche/encyclopedic backstop
11//! can't outrank broad web just because the leader was short.
12//!
13//! Timeout fairness: `input.timeout_ms` is the OVERALL budget; each engine
14//! gets a slice (≈ overall / engine_count, clamped) via a per-engine timeout.
15//!
16//! Empty/degraded (engine-class aware): a general engine's empty is
17//! authoritative; a niche/vertical-only empty while a general engine errored
18//! is degraded → error; all-error → chain-summary error.
19
20use async_trait::async_trait;
21use std::collections::HashMap;
22use std::sync::Arc;
23use std::time::{Duration, Instant};
24
25use super::dedupe::normalize_url_for_dedup;
26use super::rank::{fuse_rrf, FusionCandidate, RankOccurrence};
27use crate::engine::{
28    EngineClass, SearchError, SearchErrorCode, WebSearchEngine, WebSearchEngineInput,
29    WebSearchEngineResult,
30};
31use crate::types::WebSearchResultItem;
32
33const PER_ENGINE_FLOOR_MS: u64 = 3_000;
34const PER_ENGINE_CAP_MS: u64 = 8_000;
35
36pub struct FallbackEngine {
37    engines: Vec<Arc<dyn WebSearchEngine>>,
38    names: Vec<String>,
39}
40
41impl FallbackEngine {
42    pub fn new(engines: Vec<Arc<dyn WebSearchEngine>>) -> Self {
43        let names = engines.iter().map(|e| e.name().to_string()).collect();
44        Self { engines, names }
45    }
46
47    pub fn chain(&self) -> &[String] {
48        &self.names
49    }
50}
51
52#[async_trait]
53impl WebSearchEngine for FallbackEngine {
54    fn name(&self) -> &str {
55        "fallback"
56    }
57
58    async fn search(
59        &self,
60        input: WebSearchEngineInput,
61    ) -> Result<WebSearchEngineResult, SearchError> {
62        let overall_ms = input.timeout_ms;
63        let deadline = Instant::now() + Duration::from_millis(overall_ms);
64        let n_engines = self.engines.len().max(1) as u64;
65        let per_engine_ms =
66            (overall_ms / n_engines).clamp(PER_ENGINE_FLOOR_MS.min(overall_ms), PER_ENGINE_CAP_MS);
67
68        let mut errors: Vec<SearchError> = Vec::new();
69        let mut summary: Vec<String> = Vec::new();
70
71        // Deduped candidate pool keyed on normalized URL; each candidate
72        // records every (engine, rank) that surfaced it, for RRF fusion.
73        let mut candidates: HashMap<String, FusionCandidate> = HashMap::new();
74        let mut contributors: Vec<String> = Vec::new();
75        let mut backend_host = String::new();
76        let mut first_engine: Option<String> = None;
77        let mut first_class: Option<EngineClass> = None;
78        let mut total_elapsed: u64 = 0;
79        let mut any_time_applied = false;
80        let mut any_time_ignored = false;
81
82        let mut general_empty = false;
83        let mut fallback_empty = false;
84        let mut general_errored = false;
85
86        for (idx, engine) in self.engines.iter().enumerate() {
87            if candidates.len() >= input.count {
88                break; // sufficiency reached
89            }
90            let remaining = deadline
91                .checked_duration_since(Instant::now())
92                .map(|d| d.as_millis() as u64)
93                .unwrap_or(0);
94            if remaining == 0 {
95                break;
96            }
97            let budget = per_engine_ms.min(remaining).max(1);
98
99            let mut per_input = input.clone();
100            per_input.timeout_ms = budget;
101
102            let name = engine.name().to_string();
103            let class = engine.engine_class();
104            let fut = engine.search(per_input);
105            match tokio::time::timeout(Duration::from_millis(budget), fut).await {
106                Ok(Ok(r)) => {
107                    total_elapsed += r.elapsed_ms;
108                    if r.results.is_empty() {
109                        summary.push(format!("{}: empty", name));
110                        if class == EngineClass::General {
111                            general_empty = true;
112                        } else {
113                            fallback_empty = true;
114                        }
115                        continue;
116                    }
117                    // Fast path: first engine alone meets count → return it.
118                    if idx == 0 && r.results.len() >= input.count {
119                        summary.push(format!("{}: results", name));
120                        let mut out = r;
121                        if out.engine.is_none() {
122                            out.engine = Some(name);
123                        }
124                        out.engine_class = Some(class);
125                        return Ok(out);
126                    }
127                    // Accumulate into the candidate pool. A URL already seen
128                    // from an earlier engine records an additional (engine,
129                    // rank) occurrence (consensus) instead of being dropped.
130                    let r_time = r.time_range_applied;
131                    let r_host = r.backend_host.clone();
132                    for (rank, item) in r.results.into_iter().enumerate() {
133                        let key = normalize_url_for_dedup(&item.url);
134                        if let Some(existing) = candidates.get_mut(&key) {
135                            existing.occurrences.push(RankOccurrence {
136                                engine: name.clone(),
137                                class,
138                                rank,
139                            });
140                        } else {
141                            let order = candidates.len();
142                            candidates.insert(
143                                key,
144                                FusionCandidate {
145                                    item,
146                                    occurrences: vec![RankOccurrence {
147                                        engine: name.clone(),
148                                        class,
149                                        rank,
150                                    }],
151                                    order,
152                                },
153                            );
154                        }
155                    }
156                    summary.push(format!("{}: results", name));
157                    if !contributors.contains(&name) {
158                        contributors.push(name.clone());
159                    }
160                    if first_engine.is_none() {
161                        first_engine = Some(name);
162                        first_class = Some(class);
163                        backend_host = r_host;
164                    }
165                    match r_time {
166                        Some(true) => any_time_applied = true,
167                        Some(false) => any_time_ignored = true,
168                        None => {}
169                    }
170                }
171                Ok(Err(e)) => {
172                    summary.push(format!("{}: {:?}", name, e.code));
173                    if class == EngineClass::General {
174                        general_errored = true;
175                    }
176                    errors.push(e);
177                }
178                Err(_) => {
179                    summary.push(format!("{}: Timeout", name));
180                    if class == EngineClass::General {
181                        general_errored = true;
182                    }
183                    errors.push(SearchError::new(
184                        SearchErrorCode::Timeout,
185                        format!("{} exceeded its per-engine time slice", name),
186                    ));
187                }
188            }
189        }
190
191        if !candidates.is_empty() {
192            let mixed = contributors.len() > 1;
193            // Fuse the candidate pool with RRF + engine weights, then truncate.
194            // For a single contributor RRF preserves that engine's order, so
195            // it's a stable no-op reorder — we just clear the source tag.
196            let pool: Vec<FusionCandidate> = candidates.into_values().collect();
197            let fused = fuse_rrf(pool);
198            let results: Vec<WebSearchResultItem> = fused
199                .into_iter()
200                .take(input.count)
201                .map(|f| {
202                    let mut item = f.item;
203                    item.source = if mixed {
204                        // Multi-engine: surface the contributing engine(s) for
205                        // this row (consensus shows all agreeing engines).
206                        Some(f.sources.join("+"))
207                    } else {
208                        None
209                    };
210                    item
211                })
212                .collect();
213            let time_range_applied = if any_time_applied || any_time_ignored {
214                Some(!any_time_ignored)
215            } else {
216                None
217            };
218            return Ok(WebSearchEngineResult {
219                results,
220                backend_host,
221                elapsed_ms: total_elapsed,
222                engine: first_engine.or_else(|| contributors.first().cloned()),
223                engine_class: first_class,
224                engines: if mixed { Some(contributors) } else { None },
225                time_range_applied,
226            });
227        }
228
229        // No results gathered. A general engine's empty is authoritative.
230        if general_empty {
231            return Ok(empty_result(backend_host, total_elapsed));
232        }
233        // Niche/vertical-only empty: trustworthy only if no general engine broke.
234        if fallback_empty && !general_errored {
235            return Ok(empty_result(backend_host, total_elapsed));
236        }
237        Err(synthesize_chain_error(&errors, &summary))
238    }
239}
240
241fn empty_result(backend_host: String, elapsed_ms: u64) -> WebSearchEngineResult {
242    WebSearchEngineResult {
243        results: Vec::new(),
244        backend_host,
245        elapsed_ms,
246        engine: None,
247        engine_class: None,
248        engines: None,
249        time_range_applied: None,
250    }
251}
252
253fn synthesize_chain_error(errors: &[SearchError], summary: &[String]) -> SearchError {
254    if errors.is_empty() {
255        return SearchError::new(
256            SearchErrorCode::ServerNotAvailable,
257            "no search engines were available to try",
258        );
259    }
260    let first_code = errors[0].code;
261    let all_same = errors.iter().all(|e| e.code == first_code);
262    let rep = if all_same {
263        first_code
264    } else {
265        SearchErrorCode::ServerNotAvailable
266    };
267    SearchError::new(
268        rep,
269        format!("all search engines failed ({})", summary.join(", ")),
270    )
271}