//! Shared error response shape for all endpoints, modeled on RFC 7807 //! (Problem Details for HTTP APIs) plus a few extra fields: a machine //! readable `code`, the OpenAPI `operation_id` that failed, a `spec_url` //! pointing back at /openapi.json, the request's `request_id` (see the //! SetRequestIdLayer/PropagateRequestIdLayer in lib.rs), `took_ms` //! (server time spent before the error, the same measure as a success //! response's `meta.took_ms`), and `next`, a hint at a related endpoint //! the caller might try instead. RFC 7807 allows extension members //! like these next to the standard ones. //! //! `type`/`spec_url` are relative paths, not absolute URLs, since this //! service has no fixed public domain; RFC 7807 explicitly allows `type` //! to be a relative URI reference. use axum::Json; use axum::http::StatusCode; use axum::response::{IntoResponse, Response}; use serde::Serialize; use crate::response::RequestInfo; #[derive(Debug, Serialize, utoipa::ToSchema)] pub struct ApiError { pub r#type: String, pub title: String, pub status: u16, pub code: String, pub detail: String, /// The blessed typed error body for the 422 `invalid_query` contract /// (owner-approved 2026-10-06, AMENDMENT E): `type`, `message`, /// `param` and a `detail` object carrying the backend's own error /// classification. `None` for every other error shape, so the /// envelope's existing fields stay the whole body there. pub error: Option, pub operation_id: String, pub spec_url: String, pub request_id: Option, /// Milliseconds the server spent on the request before this error. pub took_ms: Option, pub next: Option, } /// The typed 422 `invalid_query` body (the 2026-10-06 contract, /// `{"error": {"type", "message", "param", "detail"}}`), riding inside /// the shared `ApiError` envelope under `error` so the existing fields /// (`code`, `detail`, ...) keep their meaning for every caller. #[derive(Debug, Serialize, utoipa::ToSchema)] pub struct TypedErrorDetail { /// The machine-readable error class (`invalid_query`). pub r#type: String, /// The human-readable rejection diagnostic (the backend's parser /// message). pub message: String, /// The offending request parameter. The search grammar rides on the /// `query` parameter (the contract keeps gn3's parameter name). pub param: String, /// Structured classification: the xapian exception class behind the /// rejection, when the backend reported one. pub detail: serde_json::Value, } impl ApiError { pub fn new( status: StatusCode, code: &str, title: &str, detail: String, operation_id: &str, ) -> Self { ApiError { r#type: format!("/errors/{code}"), title: title.to_string(), status: status.as_u16(), code: code.to_string(), detail, error: None, operation_id: operation_id.to_string(), spec_url: "/openapi.json".to_string(), request_id: None, took_ms: None, next: None, } } /// Attach the blessed typed 422 shape (the `error` object of the /// 2026-10-06 contract) to an `invalid_query` error. `detail` /// carries the backend's xapian error classification, when it /// reported one. pub fn with_typed_invalid_query( mut self, message: String, xapian_error_type: Option, ) -> Self { self.error = Some(TypedErrorDetail { r#type: "invalid_query".to_string(), message, param: "query".to_string(), detail: serde_json::json!({ "xapian_error_type": xapian_error_type }), }); self } /// Stamps the error with the request's id and the time taken so far. pub fn with_request_id(mut self, request: RequestInfo) -> Self { self.request_id = request.id(); self.took_ms = Some(request.took_ms()); self } pub fn with_next(mut self, next: &str) -> Self { self.next = Some(next.to_string()); self } } impl IntoResponse for ApiError { fn into_response(self) -> Response { let status = StatusCode::from_u16(self.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR); (status, Json(self)).into_response() } } /// The 401 every token-gated endpoint can return, as one shared /// `IntoResponses` type (an `ApiError` body under the hood) instead of /// writing out `(status = 401, description = "...", body = ApiError)` /// by hand on each `#[utoipa::path(...)]` -- reference it bare inside /// `responses(...)`, e.g. `responses(Unauthorized, (status = 200, ...))`. /// Which endpoints actually need it (i.e. take `AuthToken`) is still a /// per-handler decision; this only removes the repetition in /// documenting the one response shape that decision implies. #[derive(utoipa::IntoResponses)] #[response(status = 401, description = "Missing or invalid token")] #[allow(dead_code)] // only ever used for its OpenAPI schema, never constructed pub struct Unauthorized(#[to_schema] ApiError);