//! The gn3-forwarding [`Engine`] implementation: gn4's `/search` proxy //! target. Forwards `(q, type, limit)` to GeneNetwork3's xapian-backed //! `/api/search/` and returns the hits unchanged. use super::{Engine, SearchError, SearchHit}; use std::sync::OnceLock; use std::time::Duration; /// Normalize gn3's leaked Python bytes-repr error types (the recorded /// fixtures carry `"error_type": "b'QueryParserError'"`) to the bare /// xapian exception class the typed 422 contract reports (the /// binding-report R1 / OPEN-16 formatting normalization, wrapper /// layer). fn normalize_error_type(raw: &serde_json::Value) -> Option { let text = raw.as_str()?; let stripped = text .strip_prefix("b'") .and_then(|rest| rest.strip_suffix('\'')) .unwrap_or(text); Some(stripped.to_string()) } /// Recognize gn3's escaping-xapian-exception 500s (the malformed-input /// accidents the 2026-10-06 contract folds into 422 `invalid_query`; /// parity-metric amendment: `Hs:foo:1M` -> `InvalidOperationError`, /// `position:abc` -> `ValueError`): the JSON `error` field carries the /// exception class name, bare or leading a `Class: message` form. /// A generic backend 500 whose diagnostic is prose ("gn3 exploded") /// stays a backend failure — the rule is scoped to what production /// actually emits, and the python/rust route tests pin that boundary. fn looks_like_xapian_exception_class(error: &str) -> bool { let first_word = error.split_whitespace().next().unwrap_or(""); let first_word = first_word.trim_end_matches(':'); first_word != "Error" && first_word.len() > 5 && first_word.ends_with("Error") && first_word.chars().next().is_some_and(char::is_uppercase) && first_word.chars().all(|c| c.is_ascii_alphanumeric()) } /// The typed 422 rejection for a gn3 diagnostic body: the message is /// gn3's `error` string; the classification is gn3's `error_type` /// field when present, else — for the escaping-exception shape whose /// `error` field IS the exception name — that name. /// /// `exception_class_only` gates the 5xx use: a 4xx JSON diagnostic is /// gn3's designed rejection path (any `error` string maps to 422), /// while a 5xx body only maps when the diagnostic looks like the /// escaping-exception shape (see [`looks_like_xapian_exception_class`]) /// — prose 500s stay backend failures. fn invalid_query_from_body( body: &serde_json::Value, exception_class_only: bool, ) -> Option { let error = body.get("error").and_then(|e| e.as_str())?; let exception_class = looks_like_xapian_exception_class(error); if exception_class_only && !exception_class { return None; } let xapian_error_type = body .get("error_type") .and_then(normalize_error_type) .or_else(|| exception_class.then(|| error.split(':').next().unwrap_or(error).to_string())); Some(SearchError::InvalidQuery { message: error.to_string(), xapian_error_type, }) } /// Shared HTTP client for gn3 upstream calls: one connection pool /// (keepalive across queries) instead of reqwest::get's fresh client /// per request, and a total timeout -- gn3 sets none of its own, so /// without this a stalled upstream hangs the handler past any /// front-proxy timeout. The timeout is the GN3_TIMEOUT_SECS config key. static GN3_CLIENT: OnceLock = OnceLock::new(); fn gn3_client() -> &'static reqwest::Client { GN3_CLIENT.get_or_init(|| { let timeout = Duration::from_secs(crate::config::Config::load().gn3_timeout_secs); reqwest::Client::builder() .timeout(timeout) .build() .expect("gn3 client builds") }) } /// Forwards searches to the GeneNetwork3 xapian search API. pub struct Gn3; impl Engine for Gn3 { async fn search( &self, q: &str, type_: &str, limit: u64, page: u64, ) -> Result, SearchError> { let gn3_url = crate::config::Config::load().gn3_url; let url = url::Url::parse_with_params( &format!("{}search/", gn3_url), [ ("query", q), ("type", type_), ("per_page", &limit.to_string()), ("page", &page.to_string()), ], ) .map_err(|e| { SearchError::Internal(format!("GN3_URL {gn3_url} is not a valid base URL: {e}")) })?; let response = gn3_client() .get(url) .send() .await .map_err(|e| SearchError::Unreachable(e.to_string()))?; let status = response.status(); let body = response .text() .await .map_err(|e| SearchError::Misbehaving(e.to_string()))?; if status.is_client_error() { // gn3 signals rejected queries (xapian syntax errors, unknown // type, ...) as 4xx with a JSON diagnostic; forward it as 422 // invalid_query so the caller can fix the query (assigned issue: // report-invalid-search-queries-over-api). Match on the presence // of "error" alone -- production's "error_type" leaks Python // reprs, so token-matching on it is fragile. if let Ok(v) = serde_json::from_str::(&body) { if let Some(error) = invalid_query_from_body(&v, false) { return Err(error); } } } // gn3's malformed-processor-value 500s are escaping xapian // exceptions (Q42's recorded `InvalidOperationError` body, the // parity-metric amendment's curl-verified `ValueError`), not // backend failures: under the blessed contract they surface as // 422 invalid_query too. Scoped to the exception-class shape so // prose diagnostics ("gn3 exploded") keep the 502 backend_error // class. if status.is_server_error() { if let Ok(v) = serde_json::from_str::(&body) { if let Some(error) = invalid_query_from_body(&v, true) { return Err(error); } } } if !status.is_success() { return Err(SearchError::Backend(format!( "gn3 search returned HTTP {status}: {body}" ))); } serde_json::from_str::>(&body) .map_err(|e| SearchError::Misbehaving(e.to_string())) } }