footing 0.3.1

Feature-gated foundations for Rust backend services
Documentation
use axum::{http::StatusCode, response::IntoResponse};
use serde_json::json;

use super::{
    ApiProblem, ApiProblemStatusError, PROBLEM_JSON_MEDIA_TYPE, ProblemCode,
    ProblemIdentifierError, ProblemType,
};
use crate::http::{RequestContext, RequestId};
use crate::result::{ClassifyError, ErrorBoundaryPolicy, ErrorCode, ErrorDescriptor, ErrorKind};

fn code(value: &'static str) -> ProblemCode {
    ProblemCode::try_new(value).expect("test problem code should be valid")
}

#[test]
fn validates_problem_code() {
    let code = ProblemCode::try_new(" invalid_query ").expect("problem code should be valid");

    assert_eq!(code.as_str(), "invalid_query");
    assert!(matches!(
        ProblemCode::try_new("invalid query"),
        Err(ProblemIdentifierError::InvalidCharacters)
    ));
    assert!(matches!(
        ProblemCode::try_new("invalid query"),
        Err(ProblemIdentifierError::InvalidCharacters)
    ));
}

#[test]
fn validates_problem_type() {
    let problem_type = ProblemType::try_new(" https://example.com/problems/invalid-query ")
        .expect("problem type should be valid");

    assert_eq!(
        problem_type.as_str(),
        "https://example.com/problems/invalid-query"
    );
    assert!(matches!(
        ProblemType::try_new("bad type"),
        Err(ProblemIdentifierError::InvalidCharacters)
    ));
    assert!(matches!(
        ProblemType::try_new("bad type"),
        Err(ProblemIdentifierError::InvalidCharacters)
    ));
}

#[test]
fn problem_types_reject_invalid_uri_characters_and_percent_encoding() {
    for value in [
        "https://example.com/problems/%",
        "https://example.com/problems/%2",
        "https://example.com/problems/%zz",
        "https://example.com/problems/\\invalid",
        "https://example.com/problems/\"invalid\"",
        "https://example.com/problems/{invalid}",
        "https://example.com/problems/失敗",
        "https://example.com/problems/a\u{0085}b",
    ] {
        assert!(
            matches!(
                ProblemType::try_new(value),
                Err(ProblemIdentifierError::InvalidCharacters)
            ),
            "invalid URI reference {value:?} should be rejected"
        );
        assert!(
            serde_json::from_value::<ProblemType>(json!(value)).is_err(),
            "invalid URI reference {value:?} should not deserialize"
        );
    }
}

#[test]
fn problem_types_reject_invalid_uri_structure() {
    for value in [
        "1bad:problem",
        "https://[broken",
        "https://example.com/#first#second",
        "https://user@@example.com/problem",
        "https://example.com:port/problem",
    ] {
        assert!(
            matches!(
                ProblemType::try_new(value),
                Err(ProblemIdentifierError::InvalidCharacters)
            ),
            "invalid URI reference {value:?} should be rejected"
        );
        assert!(
            serde_json::from_value::<ProblemType>(json!(value)).is_err(),
            "invalid URI reference {value:?} should not deserialize"
        );
    }
}

#[test]
fn problem_types_preserve_nonempty_and_length_limits() {
    for value in ["", " \t\n "] {
        assert_eq!(
            ProblemType::try_new(value),
            Err(ProblemIdentifierError::Empty)
        );
        assert!(serde_json::from_value::<ProblemType>(json!(value)).is_err());
    }

    let max = super::MAX_PROBLEM_TYPE_LENGTH;
    let value = format!("/{}", "a".repeat(max - 1));
    let problem_type = ProblemType::try_new(format!(" {value} "))
        .expect("trimmed URI reference at the length limit should be valid");
    assert_eq!(problem_type.as_str(), value);
    let oversized = format!("{value}a");
    assert_eq!(
        ProblemType::try_new(&oversized),
        Err(ProblemIdentifierError::TooLong { max })
    );
    assert!(serde_json::from_value::<ProblemType>(json!(oversized)).is_err());
}

#[test]
fn problem_types_preserve_valid_uri_references() {
    for value in [
        "about:blank",
        "urn:example:problem:invalid-input",
        "tag:example@example.org,2021-09-17:OutOfLuck",
        "/problems/invalid-input",
        "../problems/invalid-input?field=name#details",
        "#invalid-input",
        "?problem=invalid-input",
        "//example.com/problems/invalid-input",
        "https://[2001:db8::1]/problems/%E5%A4%B1%E6%95%97",
        "custom://[v1.a:b]/problems/invalid-input",
        "https://example.com/problems/a%2fb!$&'()*+,;=:@_~-.",
    ] {
        let problem_type = ProblemType::try_new(value).expect("URI reference should be valid");
        assert_eq!(problem_type.as_str(), value);
        let deserialized: ProblemType =
            serde_json::from_value(json!(value)).expect("URI reference should deserialize");
        assert_eq!(deserialized, problem_type);
    }
}

#[test]
fn problem_identifiers_deserialize_with_constructor_validation() {
    let code: ProblemCode =
        serde_json::from_value(json!(" invalid_query ")).expect("code should deserialize");
    assert_eq!(code.as_str(), "invalid_query");
    assert!(serde_json::from_value::<ProblemCode>(json!("invalid query")).is_err());

    let problem_type: ProblemType =
        serde_json::from_value(json!(" https://example.com/problems/invalid-query "))
            .expect("type should deserialize");
    assert_eq!(
        problem_type.as_str(),
        "https://example.com/problems/invalid-query"
    );
    assert!(serde_json::from_value::<ProblemType>(json!("bad type")).is_err());
}

#[test]
fn problem_identifier_errors_are_classified_as_validation_failures() {
    let error = ProblemCode::try_new("bad code").expect_err("problem code should be invalid");
    let descriptor = error.error_descriptor();

    assert_eq!(descriptor.kind(), ErrorKind::Validation);
    assert_eq!(
        descriptor.code().as_str(),
        "problem_identifier_invalid_characters"
    );
}

#[test]
fn problem_body_carries_status_and_request_id() {
    let problem = ApiProblem::bad_request(code("invalid_query"), "invalid query")
        .with_request_id(&RequestId::new("req_test").expect("request id should be valid"));

    assert_eq!(problem.status(), StatusCode::BAD_REQUEST);
    assert_eq!(problem.body().status(), 400);
    assert_eq!(problem.body().title(), "Bad Request");
    assert_eq!(problem.body().detail(), "invalid query");
    assert_eq!(problem.body().request_id(), Some("req_test"));
}

#[test]
fn problem_details_deserialization_preserves_private_invariants() {
    let valid = serde_json::json!({
        "type": "about:blank",
        "title": "Bad Request",
        "status": 400,
        "code": "invalid_query",
        "detail": "invalid query"
    });
    for status in [400, 599] {
        let mut value = valid.clone();
        value["status"] = json!(status);
        let problem = serde_json::from_value::<super::ProblemDetails>(value)
            .expect("error status should deserialize");
        assert_eq!(problem.status(), status);
        assert_eq!(problem.instance(), None);
        assert_eq!(problem.request_id(), None);
        assert_eq!(problem.trace_id(), None);
        assert_eq!(problem.details(), None);
        assert_eq!(serde_json::to_value(&problem).unwrap()["status"], status);
    }

    for status in [0, 200, 399, 600, 1000] {
        let mut value = valid.clone();
        value["status"] = json!(status);
        assert!(
            serde_json::from_value::<super::ProblemDetails>(value).is_err(),
            "status {status} should be rejected"
        );
    }

    for (field, value) in [
        ("type", "bad type"),
        ("code", "invalid code"),
        ("request_id", "bad request id"),
    ] {
        let mut problem = valid.clone();
        problem[field] = json!(value);
        assert!(
            serde_json::from_value::<super::ProblemDetails>(problem).is_err(),
            "invalid {field} should be rejected"
        );
    }
}

#[test]
fn problem_debug_redacts_arbitrary_payloads_without_changing_wire_data() {
    let detail = "private-public-detail";
    let instance = "https://example.com/problem?token=private-instance";
    let details = "private-details";
    let problem = ApiProblem::bad_request(code("invalid_query"), detail)
        .with_instance(instance)
        .with_details(json!({ "credential": details }));

    let debug = format!("{problem:?}");
    let display = problem.to_string();
    assert!(debug.contains("invalid_query"));
    assert!(debug.contains("[REDACTED]"));
    for sensitive in [detail, instance, details] {
        assert!(!debug.contains(sensitive));
        assert!(!display.contains(sensitive));
    }
    assert_eq!(display, "HTTP problem invalid_query (400)");

    let wire = serde_json::to_value(problem.body()).expect("problem should serialize");
    assert_eq!(wire["detail"], detail);
    assert_eq!(wire["instance"], instance);
    assert_eq!(wire["details"]["credential"], details);
    assert!(wire.get("context").is_none());
}

#[test]
fn request_context_exposes_only_safe_correlation_identifiers() {
    let context = RequestContext::new(
        RequestId::new("req_test").expect("request id should be valid"),
        Some("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01".to_owned()),
    )
    .with_client_ip("198.51.100.10")
    .with_locale("en-US")
    .with_time_zone("UTC")
    .with_utc_offset_minutes(0)
    .with_client_id("opsline")
    .with_session_id("sess_private");

    let problem = ApiProblem::bad_request(code("invalid_query"), "invalid query")
        .with_request_context(&context)
        .into_body();

    assert_eq!(problem.request_id(), Some("req_test"));
    assert_eq!(problem.trace_id(), Some("4bf92f3577b34da6a3ce929d0e0e4736"));
    let serialized = serde_json::to_value(problem).expect("problem should serialize");
    assert!(serialized.get("context").is_none());
    assert!(!serialized.to_string().contains("sess_private"));
}

#[test]
fn classified_errors_apply_disclosure_policy_before_http_conversion() {
    let descriptor = ErrorDescriptor::new(
        ErrorKind::Dependency,
        ErrorCode::try_new("database_unavailable").expect("error code should be valid"),
        "database connection failed",
    );
    let context = RequestContext::new(
        RequestId::new("req_test").expect("request id should be valid"),
        None,
    )
    .with_client_id("private-client")
    .with_session_id("private-session");

    for (policy, detail) in [
        (ErrorBoundaryPolicy::new(), "service is unavailable"),
        (
            ErrorBoundaryPolicy::trusted_internal(),
            "database connection failed",
        ),
    ] {
        let problem = ApiProblem::from_error(&descriptor, policy)
            .with_request_context(&context)
            .into_body();

        assert_eq!(problem.status(), 503);
        assert_eq!(problem.code(), "database_unavailable");
        assert_eq!(problem.detail(), detail);
        assert_eq!(problem.request_id(), Some("req_test"));
        assert!(
            !serde_json::to_string(&problem)
                .unwrap()
                .contains("private-")
        );
    }

    let private_client_error = ErrorDescriptor::new(
        ErrorKind::Validation,
        ErrorCode::internal("invalid_input"),
        "private input detail",
    )
    .with_private_message();
    let problem = ApiProblem::from_error(
        &private_client_error,
        ErrorBoundaryPolicy::trusted_internal(),
    );
    assert_eq!(problem.status(), StatusCode::BAD_REQUEST);
    assert_eq!(problem.body().detail(), "request validation failed");
}

#[test]
fn problem_status_must_be_error_status() {
    let error =
        ApiProblem::try_new(StatusCode::OK, code("ok"), "ok").expect_err("status is not an error");
    assert!(matches!(
        error,
        ApiProblemStatusError::InvalidStatus { status: 200 }
    ));
    assert_eq!(
        error.error_descriptor().code().as_str(),
        "api_problem_invalid_status"
    );
}

#[tokio::test]
async fn response_uses_problem_json_content_type_and_matching_status() {
    for status in [400, 422, 500, 599] {
        let status = StatusCode::from_u16(status).unwrap();
        let response = ApiProblem::try_new(status, code("test_problem"), "test problem")
            .unwrap()
            .into_response();
        assert_eq!(response.status(), status);
        assert_eq!(
            response.headers()[axum::http::header::CONTENT_TYPE],
            PROBLEM_JSON_MEDIA_TYPE
        );
        let body = axum::body::to_bytes(response.into_body(), usize::MAX)
            .await
            .unwrap();
        let body: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(body["status"], status.as_u16());
    }
}