//! Search domain endpoint. //! //! Phase A (gn4-api-foundation.gmi "Pilot: search"): proxies gn3's //! /api/search (xapian-backed) and wraps the hits in the //! descriptive envelope. gn3's hit objects pass through untouched; //! gn4 contributes boundary validation and the contract, plus what //! gn3's hits lack: `lod` (derived from `lrs`), `locus` and //! `abbreviation` (looked up in PublishXRef/Phenotype), and //! `sort`/`order`/`page`. //! //! The backend itself lives behind the search engine seam (see //! `crate::search`); this handler validates parameters, delegates to //! the configured [`Engine`], and maps the engine's [`SearchError`] //! onto the existing [`ApiError`] shapes. use axum::Json; use axum::extract::Query; use axum::http::StatusCode; use serde::Deserialize; use std::collections::HashMap; use gnauth_macros::gnauth; use crate::auth::AuthToken; use crate::db; use crate::error::{ApiError, Unauthorized}; use crate::response::{Ctx, Envelope, RequestInfo, path_segment}; use crate::search::{self, SearchError, SearchHit}; /// Query parameters for `GET /search`. /// /// Named for LLM callers (`q`, `type`, `limit`) rather than gn3's /// (`query`, `target`, `per_page`); the handler translates. #[derive(Deserialize, utoipa::IntoParams)] pub struct SearchParams { /// Free-text query, e.g. "alcohol". Xapian query syntax is accepted. pub q: String, /// What to search: "phenotype" (default) or "gene". #[param(value_type = Option)] pub r#type: Option, /// Maximum hits to return (default 20, capped at 100). pub limit: Option, /// Rank hits by "lrs" or "lod" (the same order) instead of /// relevance; hits without a value come last. The ranking covers /// the first 1000 relevance-ranked matches, then `limit` applies. pub sort: Option, /// "desc" (default) or "asc"; only meaningful with `sort`. pub order: Option, /// Which page of `limit` hits to return (default 1). With `sort`, /// pages are taken from the ranked list, so they reach past the /// first `limit` best hits (up to the first 1000 matches). pub page: Option, } /// Map a [`SearchError`] onto the `/search` error contract: one /// `ApiError` per engine failure class, carrying the engine's own /// diagnostic as `detail`. See `crate::search` for the mapping table. fn engine_error(error: SearchError, rid: RequestInfo) -> ApiError { // Every gn3-side failure maps to one 502 shape; the caller can tell // connectivity, protocol, and backend errors apart by `code`. let backend_error = |code: &str, detail: String| { ApiError::new( StatusCode::BAD_GATEWAY, code, "Search backend failure", detail, "search", ) .with_request_id(rid.clone()) }; match error { SearchError::InvalidQuery { message, xapian_error_type, } => { // The blessed typed-422 contract (owner-approved 2026-10-06, // AMENDMENT E): the rejection carries `param` ("query") and // a `detail` object with the backend's xapian error class, // inside the shared ApiError envelope under `error` — the // envelope's existing fields (code, detail, ...) keep their // meaning, so every current 422 (Q51/Q52 parser rejects, // Q42's invalid-location class, mean:abc..def) emits it. ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "invalid_query", "Query rejected by the search backend", message.clone(), "search", ) .with_typed_invalid_query(message, xapian_error_type) .with_request_id(rid) } SearchError::Unreachable(detail) => backend_error("backend_unreachable", detail), SearchError::Misbehaving(detail) => backend_error("backend_misbehaving", detail), SearchError::Backend(detail) => backend_error("backend_error", detail), SearchError::Internal(detail) => ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", detail, "search", ) .with_request_id(rid), } } /// With `sort`, the engine is asked for this many hits (not just /// `limit`) so the ranking spans more than one page of relevance- /// ordered results. const SORT_FETCH_LIMIT: u64 = 1000; /// Orders hits by `lrs` (which orders LOD identically), descending /// unless `ascending`; hits with no `lrs` always come last. fn sort_by_lrs(hits: &mut [SearchHit], ascending: bool) { hits.sort_by(|a, b| match (a.lrs, b.lrs) { (Some(x), Some(y)) if ascending => x.total_cmp(&y), (Some(x), Some(y)) => y.total_cmp(&x), (Some(_), None) => std::cmp::Ordering::Less, (None, Some(_)) => std::cmp::Ordering::Greater, (None, None) => std::cmp::Ordering::Equal, }); } /// Fills in `locus` and `abbreviation` for phenotype hits from one /// PublishXRef lookup, and says whether that worked. A database failure /// leaves them null rather than failing the search (the hits are still /// correct, and both are also on GET /traits/{dataset}/{trait}); the /// handler reports it as a `partial` response. async fn add_publish_annotations(hits: &mut [SearchHit]) -> bool { let key = |hit: &SearchHit| -> Option<(String, u32)> { let dataset = hit.dataset.as_deref().filter(|d| d.ends_with("Publish"))?; Some((dataset.to_string(), hit.name.as_deref()?.parse().ok()?)) }; let keys: Vec<(String, u32)> = hits.iter().filter_map(key).collect(); if keys.is_empty() { return true; } let annotations: HashMap<(String, u32), db::PublishAnnotation> = match tokio::task::spawn_blocking(move || db::get_publish_annotations(&keys)).await { Ok(Ok(annotations)) => annotations, _ => return false, }; for hit in hits { let annotation = key(hit) .and_then(|key| annotations.get(&key).cloned()) .unwrap_or_default(); hit.locus = annotation.locus; hit.abbreviation = annotation.abbreviation; } true } #[utoipa::path(get, path = "/search", summary = "Search traits across GN datasets", description = "Search traits across GN datasets. Runs through the \ configured engine: GeneNetwork3's xapian search by default, or the \ native xapian engine when SEARCH_ENGINE=native (phase A; see \ topics/gn4/gn4-api-foundation.gmi). Hits are gn3's trait objects passed \ through unchanged, wrapped in the descriptive envelope. Malformed \ queries carry the backend's parser diagnostic as a 422.", params(SearchParams), responses( (status = 200, description = "Matching traits, gn3 shape", body = Envelope>), Unauthorized, (status = 400, description = "Missing or invalid parameter", body = ApiError), (status = 422, description = "Query unparsable by the search backend; carries gn3's diagnostic", body = ApiError), (status = 502, description = "Search backend unreachable or misbehaving", body = ApiError) ))] #[gnauth(token_only)] pub async fn search( ctx: Ctx, _token: AuthToken, Query(params): Query, ) -> Result>>, ApiError> { let rid = ctx.request_info(); let bad_request = |detail: &str| { ApiError::new( StatusCode::BAD_REQUEST, "invalid_parameter", "Invalid parameter", detail.to_string(), "search", ) .with_request_id(rid.clone()) }; let q = params.q.trim(); if q.is_empty() { return Err(bad_request("q must not be empty")); } let search_type = params.r#type.as_deref().unwrap_or("phenotype"); if !matches!(search_type, "phenotype" | "gene") { return Err(bad_request( "type must be \"phenotype\" or \"gene\"; see /openapi.json", )); } let limit = params.limit.unwrap_or(20).min(100); if !matches!(params.sort.as_deref(), None | Some("lrs") | Some("lod")) { return Err(bad_request("sort must be \"lrs\" or \"lod\"")); } let ascending = match params.order.as_deref() { None | Some("desc") => false, Some("asc") => true, Some(_) => return Err(bad_request("order must be \"asc\" or \"desc\"")), }; let page = params.page.unwrap_or(1); if page < 1 { return Err(bad_request("page must be at least 1")); } // Unsorted: gn3 pages for us. Sorted: gn3 is asked for one wide // first page and the pages are taken from the ranked list. let (fetch_limit, gn3_page) = if params.sort.is_some() { (SORT_FETCH_LIMIT, 1) } else { (limit, page) }; let mut hits = search::search(q, search_type, fetch_limit, gn3_page) .await .map_err(|e| engine_error(e, rid))?; let fetched = hits.len() as u64; for hit in &mut hits { hit.lod = hit.lrs.map(db::lod); } if params.sort.is_some() { sort_by_lrs(&mut hits, ascending); hits = hits .into_iter() .skip((page - 1).saturating_mul(limit) as usize) .collect(); } hits.truncate(limit as usize); let annotated = add_publish_annotations(&mut hits).await; let top = hits .first() .and_then(|hit| Some((hit.dataset.clone()?, hit.name.clone()?))); let more = if params.sort.is_some() { fetched > page.saturating_mul(limit) } else { hits.len() as u64 == limit }; let mut envelope = ctx.envelope(hits).with_note(db::LOD_NOTE); if params.sort.is_some() && fetched >= SORT_FETCH_LIMIT { envelope = envelope.partial(&format!( "Ranked over the first {SORT_FETCH_LIMIT} matches by relevance; \ further matches exist and were not ranked." )); } if !annotated { envelope = envelope.partial( "locus and abbreviation could not be looked up (database unavailable); \ they are null.", ); } if more { let mut query = url::form_urlencoded::Serializer::new(String::new()); query .append_pair("q", q) .append_pair("limit", &limit.to_string()); if let Some(search_type) = params.r#type.as_deref() { query.append_pair("type", search_type); } if let Some(sort) = params.sort.as_deref() { query.append_pair("sort", sort); } if let Some(order) = params.order.as_deref() { query.append_pair("order", order); } query.append_pair("page", &(page + 1).to_string()); envelope = envelope.with_next( &format!("/search?{}", query.finish()), "The next page of hits", ); } if let Some((dataset, name)) = top { envelope = envelope.with_next( &format!("/traits/{}/{}", path_segment(&dataset), path_segment(&name)), "Metadata of the top hit", ); } Ok(Json(envelope.with_links(crate::suggest::root_links()))) } #[cfg(test)] mod tests { use super::*; /// Each `SearchError` class keeps its existing status/code/title, /// carrying the engine's diagnostic as `detail`, with the request /// id threaded through. #[test] fn engine_error_preserves_the_existing_contract() { let rid = RequestInfo::new(Some("req-1".to_string())); let cases = [ ( SearchError::InvalidQuery { message: "detail".to_string(), xapian_error_type: Some("QueryParserError".to_string()), }, StatusCode::UNPROCESSABLE_ENTITY, "invalid_query", "Query rejected by the search backend", ), ( SearchError::Unreachable("detail".to_string()), StatusCode::BAD_GATEWAY, "backend_unreachable", "Search backend failure", ), ( SearchError::Misbehaving("detail".to_string()), StatusCode::BAD_GATEWAY, "backend_misbehaving", "Search backend failure", ), ( SearchError::Backend("detail".to_string()), StatusCode::BAD_GATEWAY, "backend_error", "Search backend failure", ), ( SearchError::Internal("detail".to_string()), StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", ), ]; for (error, status, code, title) in cases { let api_error = engine_error(error, rid.clone()); assert_eq!(api_error.status, status.as_u16()); assert_eq!(api_error.code, code); assert_eq!(api_error.title, title); assert_eq!(api_error.detail, "detail"); assert_eq!(api_error.operation_id, "search"); assert_eq!(api_error.r#type, format!("/errors/{code}")); assert_eq!(api_error.request_id.as_deref(), Some("req-1")); } // The blessed typed 422 shape rides under `error`: the class, the // message, param "query", and the xapian classification in // detail. Present for invalid_query, absent for every other // class. let invalid = engine_error( SearchError::InvalidQuery { message: "Syntax: AND ".to_string(), xapian_error_type: Some("QueryParserError".to_string()), }, RequestInfo::new(None), ); let typed = invalid.error.expect("invalid_query carries the typed body"); assert_eq!(typed.r#type, "invalid_query"); assert_eq!(typed.message, "Syntax: AND "); assert_eq!(typed.param, "query"); assert_eq!( serde_json::json!({"xapian_error_type": "QueryParserError"}), typed.detail ); let backend = engine_error( SearchError::Backend("detail".to_string()), RequestInfo::new(None), ); assert!(backend.error.is_none()); } use serde_json::json; fn hit(lrs: Option) -> SearchHit { serde_json::from_value(json!({ "lrs": lrs })).unwrap() } fn lrs_of(hits: &[SearchHit]) -> Vec> { hits.iter().map(|h| h.lrs).collect() } #[test] fn sort_by_lrs_descending_puts_missing_values_last() { let mut hits = vec![hit(Some(2.0)), hit(None), hit(Some(9.0)), hit(Some(5.0))]; sort_by_lrs(&mut hits, false); assert_eq!(lrs_of(&hits), [Some(9.0), Some(5.0), Some(2.0), None]); } #[test] fn sort_by_lrs_ascending_still_puts_missing_values_last() { let mut hits = vec![hit(Some(2.0)), hit(None), hit(Some(9.0)), hit(Some(5.0))]; sort_by_lrs(&mut hits, true); assert_eq!(lrs_of(&hits), [Some(2.0), Some(5.0), Some(9.0), None]); } }