mnem_http/

error.rs

//! HTTP error type. Maps mnem-core errors to status codes and emits a
//! stable JSON envelope: `{"error": "<message>", "schema": "mnem.v1.err"}`.
//!
//! The `/remote/v1/*` surface uses a separate [`RemoteError`] type that
//! renders as RFC 7807 `application/problem+json` instead of the
//! `mnem.v1.err` envelope, so remote clients (including non-mnem
//! toolchains) see a standard problem document.

use axum::Json;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use serde_json::json;

/// HTTP error type for `mnem http` handlers. Renders as JSON
/// `{"schema": "mnem.v1.err", "error": "<message>"}` with an HTTP
/// status code attached via `IntoResponse`.
pub struct Error {
    status: StatusCode,
    message: String,
}

impl Error {
    pub(crate) fn bad_request(msg: impl Into<String>) -> Self {
        Self {
            status: StatusCode::BAD_REQUEST,
            message: msg.into(),
        }
    }

    pub(crate) fn not_found(msg: impl Into<String>) -> Self {
        Self {
            status: StatusCode::NOT_FOUND,
            message: msg.into(),
        }
    }

    pub(crate) fn conflict(msg: impl Into<String>) -> Self {
        Self {
            status: StatusCode::CONFLICT,
            message: msg.into(),
        }
    }

    pub(crate) fn internal(msg: impl Into<String>) -> Self {
        Self {
            status: StatusCode::INTERNAL_SERVER_ERROR,
            message: msg.into(),
        }
    }

    pub(crate) fn locked() -> Self {
        Self::internal("server state lock poisoned")
    }

    /// Build an error with an arbitrary HTTP status code.
    pub(crate) fn status(status: StatusCode, msg: impl Into<String>) -> Self {
        Self {
            status,
            message: msg.into(),
        }
    }
}

impl IntoResponse for Error {
    fn into_response(self) -> Response {
        (
            self.status,
            Json(json!({
                "schema": "mnem.v1.err",
                "error": self.message,
            })),
        )
            .into_response()
    }
}

impl From<anyhow::Error> for Error {
    fn from(e: anyhow::Error) -> Self {
        Self::internal(format!("{e:#}"))
    }
}

/// audit-2026-04-25 P2-6 / R3 (Stage E re-fix): middleware that
/// rewrites axum's default JSON-extraction failure responses
/// (plain-text bodies at 400 / 415 / 422) into the canonical
/// `mnem.v1.err` envelope. Without this, malformed JSON on
/// `/v1/nodes`, `/v1/ingest`, etc. leaks the raw axum error string
/// with no schema tag, breaking JSON-only clients that branch on
/// the envelope.
///
/// V2 verification observed only the 422 path was rewritten: axum
/// 0.8 emits 400 for malformed-JSON and 415 for missing
/// `Content-Type`. The Stage E re-fix expands the trigger set to
/// include both, so EVERY body-deserialize failure ends up in the
/// envelope. Most of the `/remote/v1/*` surface is exempt because it
/// renders RFC 7807 problem documents -- we leave
/// `application/problem+json` responses alone.
///
/// audit-2026-04-25 C3-3 (Cycle-3): extend the envelope to
/// `/remote/v1/fetch-blocks` only. The two write-side endpoints
/// (`/remote/v1/push-blocks` and `/remote/v1/advance-head`)
/// intentionally use RFC 7807 for `503` auth-unconfigured
/// responses and remain exempt; `fetch-blocks` was the only
/// `/remote/v1/*` route still leaking plain-text body-deserialize
/// errors instead of the canonical `mnem.v1.err` envelope.
pub(crate) async fn json_rejection_envelope(
    req: axum::http::Request<axum::body::Body>,
    next: axum::middleware::Next,
) -> Response {
    use axum::body::to_bytes;
    use axum::http::header::CONTENT_TYPE;

    // Skip the rewrite for the write-side `/remote/v1/*` surface
    // (`push-blocks`, `advance-head`), which uses RFC 7807
    // problem+json instead of the mnem.v1.err envelope. The
    // read-side `fetch-blocks` IS rewritten so JSON-only clients
    // see the canonical envelope on body-deserialize failures.
    let path = req.uri().path();
    let is_remote_problem_json =
        path == "/remote/v1/push-blocks" || path == "/remote/v1/advance-head";
    let response = next.run(req).await;

    // Trigger statuses: axum 0.8 emits 400 (bad JSON), 415 (missing
    // Content-Type), 422 (type mismatch / missing field). All are
    // rewritten when paired with a text/plain body.
    let trigger = matches!(
        response.status(),
        StatusCode::BAD_REQUEST
            | StatusCode::UNSUPPORTED_MEDIA_TYPE
            | StatusCode::UNPROCESSABLE_ENTITY
    );
    if !trigger || is_remote_problem_json {
        return response;
    }
    // Only rewrite text/plain bodies -- the JSON envelope already used
    // by every handler-side error path is content-type application/json
    // and must pass through untouched.
    let is_text = response
        .headers()
        .get(CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .is_some_and(|s| s.starts_with("text/"));
    if !is_text {
        return response;
    }
    let (parts, body) = response.into_parts();
    let bytes = match to_bytes(body, 64 * 1024).await {
        Ok(b) => b,
        Err(_) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(json!({
                    "schema": "mnem.v1.err",
                    "error": "request body could not be parsed",
                })),
            )
                .into_response();
        }
    };
    let msg = String::from_utf8_lossy(&bytes).into_owned();
    let _ = parts; // headers / version intentionally dropped: we are
    // re-emitting a fresh response with the canonical schema.
    (
        StatusCode::BAD_REQUEST,
        Json(json!({
            "schema": "mnem.v1.err",
            "error": format!("invalid request body: {msg}"),
        })),
    )
        .into_response()
}

/// Error type for the `/remote/v1/*` surface. Each variant maps to a
/// single HTTP status code and renders as RFC 7807
/// `application/problem+json` with fields `type`, `title`, `status`,
/// and `detail`. The `type` URI is stable per variant so clients can
/// programmatically branch on it without string-matching `detail`.
#[derive(Debug)]
pub enum RemoteError {
    /// Request body was malformed (bad JSON, unknown field, bad CID
    /// string, or inner codec/transport error).
    BadRequest(String),
    /// Requested resource (e.g. a ref name) does not exist.
    NotFound(String),
    /// Compare-and-swap on `advance-head` saw a different current CID
    /// than the caller expected. Body carries the current CID in the
    /// problem document's `current` extension field so the client can
    /// rebase without a second round trip.
    CasMismatch {
        /// Current server-side head CID at the time of mismatch.
        current: mnem_core::id::Cid,
    },
    /// Internal server-side failure (blockstore I/O, lock poison,
    /// codec bug). Body carries a sanitised message.
    Internal(String),
}

impl RemoteError {
    fn status(&self) -> StatusCode {
        match self {
            Self::BadRequest(_) => StatusCode::BAD_REQUEST,
            Self::NotFound(_) => StatusCode::NOT_FOUND,
            Self::CasMismatch { .. } => StatusCode::CONFLICT,
            Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
        }
    }

    fn title(&self) -> &'static str {
        match self {
            Self::BadRequest(_) => "Bad Request",
            Self::NotFound(_) => "Not Found",
            Self::CasMismatch { .. } => "Conflict",
            Self::Internal(_) => "Internal Server Error",
        }
    }

    fn type_uri(&self) -> &'static str {
        match self {
            Self::BadRequest(_) => "https://mnem.dev/errors/remote/bad-request",
            Self::NotFound(_) => "https://mnem.dev/errors/remote/not-found",
            Self::CasMismatch { .. } => "https://mnem.dev/errors/remote/cas-mismatch",
            Self::Internal(_) => "https://mnem.dev/errors/remote/internal",
        }
    }

    fn detail(&self) -> String {
        match self {
            Self::BadRequest(m) | Self::NotFound(m) | Self::Internal(m) => m.clone(),
            Self::CasMismatch { current } => {
                format!("remote tip has advanced; pull first (current head is {current})")
            }
        }
    }
}

impl IntoResponse for RemoteError {
    fn into_response(self) -> Response {
        let status = self.status();
        let mut body = json!({
            "type": self.type_uri(),
            "title": self.title(),
            "status": status.as_u16(),
            "detail": self.detail(),
        });
        // CAS mismatch carries two extension members: `error` is a
        // machine-readable code (`"cas_mismatch"`) for programmatic
        // branching, and `current` is the current head CID so the
        // client can rebase without a second `GET /refs` round trip.
        if let Self::CasMismatch { current } = &self {
            body["error"] = json!("cas_mismatch");
            body["current"] = json!(current.to_string());
        }
        (
            status,
            [(axum::http::header::CONTENT_TYPE, "application/problem+json")],
            body.to_string(),
        )
            .into_response()
    }
}

impl From<mnem_core::Error> for Error {
    fn from(e: mnem_core::Error) -> Self {
        // Route mnem-core errors to RFC-correct HTTP status codes.
        // `NotFound` -> 404. `AmbiguousMatch` -> 409 Conflict (caller
        // asked for exactly-one and got many). `Uninitialized` -> 503
        // Service Unavailable (the server is up but the repo is not
        // usable yet; a liveness-vs-readiness distinction). Vector
        // dim mismatch + retrieval empty -> 400 Bad Request. Stale
        // (CAS-style precondition failure) -> 409 Conflict. Anything
        // else falls through to 500.
        use mnem_core::Error as CoreError;
        use mnem_core::RepoError;
        let msg = format!("{e}");
        let status = match &e {
            CoreError::Repo(RepoError::NotFound) => StatusCode::NOT_FOUND,
            CoreError::Repo(RepoError::AmbiguousMatch | RepoError::Stale) => StatusCode::CONFLICT,
            CoreError::Repo(RepoError::Uninitialized) => StatusCode::SERVICE_UNAVAILABLE,
            CoreError::Repo(RepoError::VectorDimMismatch { .. } | RepoError::RetrievalEmpty) => {
                StatusCode::BAD_REQUEST
            }
            // C8: edge references a node that does not exist in the current
            // view. This is a client error (bad input), not a server fault.
            CoreError::Repo(RepoError::DanglingEdge { .. }) => StatusCode::UNPROCESSABLE_ENTITY,
            _ => StatusCode::INTERNAL_SERVER_ERROR,
        };
        Self {
            status,
            message: msg,
        }
    }
}

#[cfg(test)]
mod remote_error_tests {
    use super::*;
    use mnem_core::id::Cid;

    fn raw_cid(byte: u8) -> Cid {
        // SHA-256 multihash over a single byte; stable + deterministic
        // per-byte identity for tests.
        let mh = mnem_core::id::Multihash::sha2_256(&[byte]);
        Cid::new(mnem_core::id::CODEC_RAW, mh)
    }

    fn status_of(e: RemoteError) -> u16 {
        e.into_response().status().as_u16()
    }

    #[test]
    fn bad_request_maps_to_400() {
        assert_eq!(status_of(RemoteError::BadRequest("bad".into())), 400);
    }

    #[test]
    fn not_found_maps_to_404() {
        assert_eq!(status_of(RemoteError::NotFound("nope".into())), 404);
    }

    #[test]
    fn cas_mismatch_maps_to_409() {
        let e = RemoteError::CasMismatch {
            current: raw_cid(7),
        };
        assert_eq!(status_of(e), 409);
    }

    #[test]
    fn internal_maps_to_500() {
        assert_eq!(status_of(RemoteError::Internal("boom".into())), 500);
    }

    #[test]
    fn cas_mismatch_body_carries_current_cid() {
        let cid = raw_cid(42);
        let e = RemoteError::CasMismatch {
            current: cid.clone(),
        };
        let resp = e.into_response();
        assert_eq!(resp.status().as_u16(), 409);
        // The body is a byte stream; we can't trivially inspect it in
        // a unit test without awaiting. Instead, we re-render to
        // confirm the serialiser path emits `current`.
        let e2 = RemoteError::CasMismatch {
            current: cid.clone(),
        };
        let json = serde_json::json!({
            "type": e2.type_uri(),
            "title": e2.title(),
            "status": 409,
            "detail": e2.detail(),
            "current": cid.to_string(),
        });
        assert_eq!(json["current"], cid.to_string());
        assert_eq!(json["status"], 409);
    }
}