1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
//! 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<String> {
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<SearchError> {
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<reqwest::Client> = 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<Vec<SearchHit>, 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::<serde_json::Value>(&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::<serde_json::Value>(&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::<Vec<SearchHit>>(&body)
.map_err(|e| SearchError::Misbehaving(e.to_string()))
}
}
|