Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

7.6 KB
Raw Blame
//! Custom axum extractors that close pitfalls in axum's defaults.
//!
//! ## Why
//!
//! axum's stock `Option<Json<T>>` extractor has a behaviour that is
//! easy to overlook: if the request body is present but malformed
//! (invalid JSON, hits the deserializer's recursion limit, exceeds
//! the body limit, etc.) the extractor **silently returns `None`**
//! instead of producing a `JsonRejection`. The handler then sees
//! `body.is_none()` and typically falls back to defaults.
//!
//! The 2026-04-25 OSS code review verified this empirically: a
//! 70-level deep nested-bool POST against `/idx/_search` arrived at
//! `parse_request` as `{"query": {"match_all": {}}}` — the deep query
//! had been silently replaced with the default. The user got back
//! 200 OK with empty hits, never knowing the query they sent had
//! been thrown away.
//!
//! `OptionalJson<T>` distinguishes the three real cases:
//!
//! | Case               | Behaviour                            |
//! |--------------------|--------------------------------------|
//! | Body absent/empty  | `Ok(OptionalJson(None))`             |
//! | Body parses to `T` | `Ok(OptionalJson(Some(T)))`          |
//! | Body is malformed  | `Err(JsonRejection)` → 400 response  |
//!
//! Use this on every POST/PUT handler that accepts a body but
//! tolerates an absent one (e.g. `/_search` works with no body —
//! defaults to match-all). For mandatory-body endpoints, use
//! `Json<T>` directly.
//!
//! ## Migration
//!
//! ```ignore
//! // Before:
//! pub async fn handler(body: Option<Json<EsSearchBody>>) {
//!     let body = body.map(|j| j.0).unwrap_or_default();
//! }
//!
//! // After:
//! use crate::extract::OptionalJson;
//! pub async fn handler(body: OptionalJson<EsSearchBody>) {
//!     let body = body.0.unwrap_or_default();
//! }
//! ```

use axum::{
    async_trait,
    body::Bytes,
    extract::{rejection::BytesRejection, FromRequest, Request},
    http::{header, StatusCode},
    response::{IntoResponse, Response},
    Json,
};
use serde::de::DeserializeOwned;

/// JSON-body extractor that returns `None` when the body is absent
/// but rejects (rather than silently defaulting) when the body is
/// present and invalid. See module docs for rationale.
pub struct OptionalJson<T>(pub Option<T>);

/// Why an `OptionalJson<T>` extraction failed. Always converts to a
/// 400 with an ES-shaped error body so clients see the real reason
/// instead of getting a misleading 200 with default behaviour.
#[derive(Debug)]
pub enum OptionalJsonRejection {
    /// Reading the body bytes failed (Content-Length oversize,
    /// connection reset, etc.). Forwarded from axum's `Bytes`
    /// extractor.
    BodyRead(BytesRejection),
    /// The body bytes did not parse as JSON for `T`.
    JsonParse(serde_json::Error),
    /// `Content-Type` header was set to something other than a JSON
    /// flavour. Most clients send `application/json`; we also accept
    /// `application/x-ndjson` for the bulk endpoints (those use
    /// their own extractor anyway, so this only fires for misuse).
    UnsupportedMediaType(String),
}

impl IntoResponse for OptionalJsonRejection {
    fn into_response(self) -> Response {
        let (status, reason) = match self {
            OptionalJsonRejection::BodyRead(r) => {
                (r.status(), format!("failed to read request body: {r}"))
            }
            OptionalJsonRejection::JsonParse(e) => (
                StatusCode::BAD_REQUEST,
                format!("malformed JSON in request body: {e}"),
            ),
            OptionalJsonRejection::UnsupportedMediaType(ct) => (
                StatusCode::UNSUPPORTED_MEDIA_TYPE,
                // Name the fix (#2575): `curl -d` sends form encoding by
                // default, and the bare media type does not say what to change.
                format!(
                    "unsupported Content-Type: {ct}. Send the body as JSON with the header \
                     `Content-Type: application/json` (curl: -H 'Content-Type: application/json')"
                ),
            ),
        };
        let body = serde_json::json!({
            "error": {
                "type": "parse_exception",
                "reason": reason,
            },
            "status": status.as_u16(),
        });
        (status, Json(body)).into_response()
    }
}

#[async_trait]
impl<S, T> FromRequest<S> for OptionalJson<T>
where
    S: Send + Sync,
    T: DeserializeOwned,
{
    type Rejection = OptionalJsonRejection;

    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
        // Tolerate a missing or generic Content-Type for empty bodies;
        // only reject if the caller explicitly sets a non-JSON one
        // alongside a payload. This matches what `Json` does internally
        // but is more permissive about absent headers (which is the
        // common case for GET-with-body and empty POST bodies).
        let ct = req
            .headers()
            .get(header::CONTENT_TYPE)
            .and_then(|v| v.to_str().ok())
            .map(str::to_owned);

        let bytes = Bytes::from_request(req, state)
            .await
            .map_err(OptionalJsonRejection::BodyRead)?;

        if bytes.is_empty() {
            return Ok(OptionalJson(None));
        }

        if let Some(ct_str) = ct {
            // application/json, application/json; charset=utf-8,
            // application/vnd.elasticsearch+json, application/x-ndjson, …
            // are all acceptable. Fall back to leniency on missing CT.
            let lower = ct_str.to_ascii_lowercase();
            let is_json = lower.contains("json") || lower.starts_with("text/plain");
            if !is_json {
                return Err(OptionalJsonRejection::UnsupportedMediaType(ct_str));
            }
        }

        let value: T = serde_json::from_slice(&bytes).map_err(OptionalJsonRejection::JsonParse)?;
        Ok(OptionalJson(Some(value)))
    }
}

impl<T: Default> OptionalJson<T> {
    /// Convenience for the very common pattern
    /// `body.0.unwrap_or_default()`.
    #[inline]
    pub fn into_or_default(self) -> T {
        self.0.unwrap_or_default()
    }
}

// Deref into the inner `Option<T>` so handlers that previously called
// `body.as_ref()`, `body.iter()`, `body.is_some()`, `body.as_mut()` etc.
// against the stock `Option<Json<T>>` keep working with one mechanical
// change to the type signature only.
impl<T> std::ops::Deref for OptionalJson<T> {
    type Target = Option<T>;
    #[inline]
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl<T> std::ops::DerefMut for OptionalJson<T> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.0
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// #2575: the 415 names the header to send, not just the media type.
    #[tokio::test]
    async fn unsupported_media_type_names_the_json_header_fix() {
        let response =
            OptionalJsonRejection::UnsupportedMediaType("application/x-www-form-urlencoded".into())
                .into_response();
        assert_eq!(response.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
        let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
            .await
            .unwrap();
        let body: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
        let reason = body["error"]["reason"].as_str().unwrap();
        assert!(
            reason.starts_with("unsupported Content-Type: application/x-www-form-urlencoded"),
            "{reason}"
        );
        assert!(
            reason.contains("Content-Type: application/json"),
            "{reason}"
        );
        assert_eq!(body["error"]["type"], "parse_exception");
        assert_eq!(body["status"], 415);
    }
}