//! Client-simulation self-correction: proves the typed-422 contract //! (the 2026-10-06 body) is mechanically SUFFICIENT for a client with //! no other API knowledge to diagnose and repair a malformed query. //! //! The client here is deliberately dumb: all it can do is send a //! query, read the error body, and re-send. Every decision in its //! repair step is derived from the body's own fields — `error.param` //! (which parameter is at fault), `error.message` (what the backend's //! parser said), `error.detail.xapian_error_type` (the backend's own //! classification) — never from hardcoded knowledge of this API's //! grammar or of the specific query being tested. If the body were //! missing any of those fields, the repair step would fail loudly //! instead of guessing. //! //! Hermetic, CI-safe (no index, no live server, no dev index): the //! tests/search.rs pattern — a stub axum app stands in for gn3, //! serving the RECORDED production responses (the alcohol/phenotype //! fixture for accepted queries, the recorded Q52 and parser //! diagnostics for the malformed shapes), and a second stub stands in //! for gn-auth's JWKS, with tokens minted locally against the //! committed test key. The forwarder engine is forced with //! SEARCH_ENGINE="" so this suite never needs a xapian index. //! //! One sequential test function per binary: `GN3_URL`, //! `AUTH_SERVER_URL` and `SEARCH_ENGINE` are process-global. use axum::Router; use axum::body::Body; use axum::extract::Query; use axum::http::{Request, StatusCode}; use axum::routing::get; use http_body_util::BodyExt; use jsonwebtoken::{Algorithm, EncodingKey, Header, encode}; use serde::Serialize; use serde_json::{Value, json}; use std::collections::HashMap; use tower::ServiceExt; /// Recorded from production on 2026-10-03: /// https://genenetwork.org/api3/search/?query=alcohol&type=phenotype&per_page=5 const FIXTURE: &str = include_str!("../test/data/search_alcohol_phenotype.json"); /// Committed test-only key material: the JWKS the gn-auth stub serves, /// and the matching RSA private key used to sign tokens locally. See /// test/data/test_jwks.json. const TEST_JWKS: &str = include_str!("../test/data/test_jwks.json"); const TEST_PRIVATE_KEY: &str = include_str!("../test/data/test_rsa_private.pem"); /// True when every `field:a..b` range token in the query has numeric /// endpoints. gn3's parser rejects a range token with non-numeric /// endpoints on the token's SHAPE (the recorded production Q52), not /// on whole-query identity, so the stub mirrors that. fn range_endpoints_numeric(query: &str) -> bool { query.split_whitespace().all(|token| { let Some((_, value)) = token.split_once(':') else { return true; }; match value.split_once("..") { Some((begin, end)) => begin.parse::().is_ok() && end.parse::().is_ok(), None => true, } }) } /// Stands in for gn3's /api/search during tests, serving recorded /// production shapes: the Q52 rejection for non-numeric range /// endpoints, the parser's dangling-operator rejection, and the /// alcohol/phenotype fixture for everything the parser accepts. async fn serve_gn3(Query(params): Query>) -> (StatusCode, String) { let query = params.get("query").map(String::as_str).unwrap_or(""); if !range_endpoints_numeric(query) { // Recorded production Q52 body (test/data/parity-fixtures/ // Q52.json): the diagnostic under "error", the Python repr // under "error_type". return ( StatusCode::BAD_REQUEST, json!({ "error": "Unknown range operation", "error_type": "b'QueryParserError'" }) .to_string(), ); } if query.split_whitespace().next_back() == Some("AND") { // The parser's own diagnostic for a trailing operator with no // expression after it (the shape tests/search.rs's stub // mirrors for `&&`): same 400 diagnostic shape. return ( StatusCode::BAD_REQUEST, json!({ "error": "Syntax: AND ", "error_type": "b'QueryParserError'" }) .to_string(), ); } (StatusCode::OK, FIXTURE.to_string()) } async fn gn3_stub_url() -> String { let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); let port = listener.local_addr().unwrap().port(); let app = Router::new().route("/api/search/", get(serve_gn3)); tokio::spawn(async move { axum::serve(listener, app).await.unwrap(); }); format!("http://127.0.0.1:{port}/api/") } /// Stands in for gn-auth's GET /auth/public-jwks, so token verification /// never needs a live gn-auth (same pattern as tests/search.rs). async fn serve_jwks() -> (StatusCode, &'static str) { (StatusCode::OK, TEST_JWKS) } async fn gn_auth_stub_url() -> String { let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); let port = listener.local_addr().unwrap().port(); let app = Router::new().route("/auth/public-jwks", get(serve_jwks)); tokio::spawn(async move { axum::serve(listener, app).await.unwrap(); }); format!("http://127.0.0.1:{port}") } /// Signs a token locally with the committed test private key, so the /// stub's JWKS verifies it. `issuer` must equal the AUTH_SERVER_URL the /// app is configured with (src/auth.rs validates the `iss` claim). fn sign_test_token(issuer: &str) -> String { #[derive(Serialize)] struct Claims { sub: String, scope: String, iss: String, iat: u64, exp: u64, } let now = std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .unwrap() .as_secs(); let claims = Claims { sub: "selfcorrection-test-user".to_string(), scope: "profile".to_string(), iss: issuer.to_string(), iat: now, exp: now + 3600, }; let key = EncodingKey::from_rsa_pem(TEST_PRIVATE_KEY.as_bytes()).unwrap(); encode(&Header::new(Algorithm::RS256), &claims, &key).unwrap() } fn set(key: &str, value: &str) { // SAFETY: this test file is the only place that touches these keys, // in one single-threaded sequence (see the module doc comment). unsafe { std::env::set_var(key, value) }; } /// The client's whole vocabulary: send a query, get status + body. async fn client_query(query: &str, token: &str) -> (StatusCode, Value) { let uri = format!("/search?q={}&type=phenotype", urlencoding(query)); let request = Request::builder() .uri(uri) .header("Authorization", format!("Bearer {token}")) .body(Body::empty()) .unwrap(); let response = genenetwork4::app().oneshot(request).await.unwrap(); let status = response.status(); let body = response.into_body().collect().await.unwrap().to_bytes(); (status, serde_json::from_slice(&body).unwrap()) } /// Percent-encode just what the test's queries need (space and the /// range token's `:`), without pulling in a urlencoding dependency. fn urlencoding(query: &str) -> String { let mut out = String::new(); for byte in query.bytes() { match byte { b' ' => out.push_str("%20"), b':' => out.push_str("%3A"), b'&' => out.push_str("%26"), b'?' => out.push_str("%3F"), _ => out.push(byte as char), } } out } /// The machine correction, derived ONLY from the typed error body. /// `error.param` says which parameter is at fault; `error.message` is /// the backend's own diagnostic; `error.detail.xapian_error_type` is /// the backend's classification. No fixed query, no grammar knowledge /// beyond what the body itself states. Returns `Err` naming the field /// whose absence blocked the repair — so a corrupted body fails the /// test instead of a lucky guess passing it. fn correct_from_error(query: &str, body: &Value) -> Result { let error = body .get("error") .ok_or_else(|| "body carries no typed error object".to_string())?; let param = error .get("param") .and_then(Value::as_str) .ok_or_else(|| "error.param missing".to_string())?; if param != "query" { return Err(format!("error.param is {param:?}, not the query parameter")); } let message = error .get("message") .and_then(Value::as_str) .filter(|m| !m.is_empty()) .ok_or_else(|| "error.message missing or empty".to_string())?; if error .get("detail") .and_then(|d| d.get("xapian_error_type")) .and_then(Value::as_str) .filter(|t| !t.is_empty()) .is_none() { return Err("error.detail.xapian_error_type missing".to_string()); } let tokens: Vec<&str> = query.split_whitespace().collect(); if tokens.is_empty() { return Err("nothing to correct: the query is empty".to_string()); } // Rule 1: a message naming boolean operators ("Syntax: // AND ") says every named operator needs // an expression on both sides — drop the named operators that // dangle at the end with nothing after them. let named_operators: Vec<&str> = message .split_whitespace() .filter(|word| word.len() >= 2 && word.chars().all(|c| c.is_ascii_uppercase())) .collect(); if !named_operators.is_empty() { let mut kept = tokens.clone(); while kept .last() .is_some_and(|token| named_operators.contains(token)) { kept.pop(); } if kept.is_empty() { return Err("dropping the dangling operators left no query".to_string()); } if kept.len() < tokens.len() { return Ok(kept.join(" ")); } return Err("the message names operators but none dangle".to_string()); } // Rule 2: a message about an unknown "range operation" indicts the // range-construct tokens (the `field:a..b` shapes) — excise them, // keeping what the message did not complain about. if message.to_ascii_lowercase().contains("range") { let kept: Vec<&str> = tokens .iter() .copied() .filter(|token| !token.contains("..")) .collect(); if kept.is_empty() { return Err("dropping the range constructs left no query".to_string()); } if kept.len() < tokens.len() { return Ok(kept.join(" ")); } return Err("the message indicts ranges but the query has none".to_string()); } Err(format!( "the message names nothing the query can correct: {message:?}" )) } /// One full self-correction loop: send `query`, expect the blessed /// typed 422, machine-correct from the body alone, re-send the /// corrected query, expect 200 with the recorded hits. async fn assert_self_corrects(query: &str, token: &str) { // 1. The malformed query is rejected with the blessed typed body. let (status, body) = client_query(query, token).await; assert_eq!(status, StatusCode::UNPROCESSABLE_ENTITY, "{query:?}"); assert_eq!(body["code"], "invalid_query", "{query:?}"); let typed = &body["error"]; assert_eq!(typed["type"], "invalid_query", "{query:?}"); assert_eq!(typed["param"], "query", "{query:?}"); assert!( typed["message"].as_str().is_some_and(|m| !m.is_empty()), "{query:?}" ); assert_eq!( typed["detail"]["xapian_error_type"], "QueryParserError", "{query:?}" ); // 2. The client repairs using ONLY what the body says. let corrected = correct_from_error(query, &body) .unwrap_or_else(|e| panic!("{query:?}: the body did not suffice: {e}")); assert_ne!(corrected, query, "the correction changed nothing"); // 3. The corrected query serves: 200 with the recorded hits. let (status, body) = client_query(&corrected, token).await; assert_eq!(status, StatusCode::OK, "{query:?} -> {corrected:?}"); let hits = body["data"].as_array().cloned().unwrap_or_default(); assert_eq!(hits.len(), 5, "the recorded alcohol/phenotype fixture"); assert_eq!(hits[0]["name"], "10199"); } #[tokio::test(flavor = "multi_thread", worker_threads = 2)] async fn client_self_corrects_from_the_typed_422_body() { let gn3_stub = gn3_stub_url().await; let gn_auth_stub = gn_auth_stub_url().await; set("GN3_URL", &gn3_stub); set("AUTH_SERVER_URL", &gn_auth_stub); // Force the forwarder engine so this suite needs no xapian index // even when the surrounding environment configures one. set("SEARCH_ENGINE", ""); let token = sign_test_token(&gn_auth_stub); // Loop 1: a trailing boolean operator. The recorded production // diagnostic ("Syntax: AND ") must be // enough for a machine to drop the dangling operator. assert_self_corrects("alcohol AND", &token).await; // Loop 2: the recorded Q52 shape, a non-numeric range endpoint // ("mean:abc..def"). A standalone malformed-only token would // leave the client nothing to re-send once excised (an empty query // is a 400, not a recovery), so the shape rides in a compound // query — the diagnostic must let a machine excise the indicted // range construct and keep the rest. assert_self_corrects("alcohol mean:abc..def", &token).await; }