footing 0.4.1

Feature-gated foundations for Rust backend services
Documentation
use super::{
    ClassifyError, Diagnostic, DiagnosticKind, ErrorBoundaryPolicy, ErrorCode, ErrorCodeError,
    ErrorDescriptor, ErrorKind, ErrorVisibility, MAX_DIAGNOSTIC_FIELD_LENGTH,
    MAX_ERROR_CODE_LENGTH,
};

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

#[test]
fn diagnostic_truncation_preserves_unicode_boundaries() {
    for (input, expected) in [
        ("中".repeat(200), "中".repeat(170)),
        ("🙂".repeat(200), "🙂".repeat(128)),
        (format!("{}🙂", "a".repeat(511)), "a".repeat(511)),
        ("a".repeat(512), "a".repeat(512)),
    ] {
        let diagnostic = Diagnostic::new("test", "test", DiagnosticKind::Unknown, input.clone())
            .with_remediation(input);
        assert_eq!(diagnostic.message(), expected);
        assert_eq!(diagnostic.remediation(), Some(expected.as_str()));
    }
}

#[test]
fn error_codes_are_stable_snake_case_identifiers() {
    assert_eq!(
        ErrorCode::try_new(" invalid_request ")
            .expect("code should be valid")
            .as_str(),
        "invalid_request"
    );
    assert_eq!(
        ErrorCode::from_parts(["mfa_factor", "not_found"])
            .expect("parts should build")
            .as_str(),
        "mfa_factor_not_found"
    );
    assert!(matches!(
        ErrorCode::from_parts(["mfa factor", "not_found"]),
        Err(ErrorCodeError::InvalidCharacters)
    ));
    assert!(matches!(
        ErrorCode::try_new("InvalidRequest"),
        Err(ErrorCodeError::InvalidCharacters)
    ));
    assert!(matches!(
        ErrorCode::try_new("a".repeat(MAX_ERROR_CODE_LENGTH + 1)),
        Err(ErrorCodeError::TooLong { .. })
    ));
}

#[test]
fn error_code_errors_are_classified_as_validation_failures() {
    let error = ErrorCode::try_new("InvalidRequest").expect_err("code should be invalid");
    let descriptor = error.error_descriptor();

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

#[test]
fn descriptor_inherits_retryability_from_kind() {
    let dependency = ErrorDescriptor::new(ErrorKind::Dependency, code("database_down"), "db down");
    let validation =
        ErrorDescriptor::new(ErrorKind::Validation, code("invalid_input"), "bad input");

    assert!(dependency.retryable());
    assert!(!validation.retryable());
}

#[test]
fn descriptor_try_new_rejects_dynamic_invalid_codes() {
    assert!(matches!(
        ErrorDescriptor::try_new(ErrorKind::Validation, "mfa factor_not_found", "missing"),
        Err(ErrorCodeError::InvalidCharacters)
    ));
}

#[test]
fn descriptor_hides_server_fault_messages_by_default() {
    let internal = ErrorDescriptor::new(
        ErrorKind::Internal,
        code("internal_error"),
        "database failed",
    );
    let validation =
        ErrorDescriptor::new(ErrorKind::Validation, code("invalid_input"), "bad input");

    assert_eq!(internal.visibility(), ErrorVisibility::Private);
    assert_eq!(internal.public_message(), "internal server error");
    assert_eq!(internal.to_string(), "internal server error");
    assert!(!format!("{internal:?}").contains("database failed"));
    assert_eq!(validation.visibility(), ErrorVisibility::Public);
    assert_eq!(validation.public_message(), "bad input");
    assert_eq!(validation.to_string(), "bad input");
}

#[test]
fn descriptor_uses_generic_message_when_message_is_empty() {
    let descriptor = ErrorDescriptor::new(ErrorKind::Validation, code("invalid_input"), " ");

    assert_eq!(descriptor.message(), "request validation failed");
    assert_eq!(descriptor.public_message(), "request validation failed");
}

#[test]
fn boundary_policy_can_expose_server_messages_for_trusted_boundaries() {
    for kind in [
        ErrorKind::Timeout,
        ErrorKind::Dependency,
        ErrorKind::Unavailable,
        ErrorKind::Internal,
    ] {
        let descriptor = ErrorDescriptor::new(kind, code("server_failure"), "internal details");
        let hidden = ErrorBoundaryPolicy::new().decide_descriptor(descriptor.clone());
        let exposed = ErrorBoundaryPolicy::trusted_internal().decide_descriptor(descriptor);

        assert_eq!(hidden.descriptor().visibility(), ErrorVisibility::Private);
        assert_ne!(hidden.public_message(), "internal details");
        assert_eq!(exposed.descriptor().visibility(), ErrorVisibility::Public);
        assert_eq!(exposed.public_message(), "internal details");
    }
}

#[test]
fn server_message_policy_preserves_client_error_visibility() {
    for kind in [
        ErrorKind::Validation,
        ErrorKind::Authentication,
        ErrorKind::Authorization,
        ErrorKind::NotFound,
        ErrorKind::Conflict,
        ErrorKind::RateLimit,
    ] {
        for policy in [
            ErrorBoundaryPolicy::new(),
            ErrorBoundaryPolicy::new().with_server_error_messages(true),
            ErrorBoundaryPolicy::cli(),
            ErrorBoundaryPolicy::trusted_internal(),
        ] {
            let descriptor = ErrorDescriptor::new(kind, code("client_failure"), "client details");
            let exposed = policy.decide_descriptor(descriptor.clone());
            let hidden = policy.decide_descriptor(descriptor.with_private_message());

            assert_eq!(exposed.descriptor().visibility(), ErrorVisibility::Public);
            assert_eq!(exposed.public_message(), "client details");
            assert_eq!(hidden.descriptor().visibility(), ErrorVisibility::Private);
            assert_ne!(hidden.public_message(), "client details");
        }
    }
}

#[test]
fn boundary_presets_match_their_external_contract() {
    assert_eq!(ErrorBoundaryPolicy::new(), ErrorBoundaryPolicy::default());
    assert!(!ErrorBoundaryPolicy::new().exposes_server_error_messages());
    assert!(ErrorBoundaryPolicy::new().alerts_internal_errors());

    assert!(ErrorBoundaryPolicy::cli().exposes_server_error_messages());
    assert!(!ErrorBoundaryPolicy::cli().alerts_internal_errors());

    assert!(ErrorBoundaryPolicy::trusted_internal().exposes_server_error_messages());
    assert!(ErrorBoundaryPolicy::trusted_internal().alerts_internal_errors());
}

#[test]
fn diagnostic_normalizes_operational_context() {
    let diagnostic = Diagnostic::new(
        "PostgreSQL",
        "ensure-database",
        DiagnosticKind::ResourceMissing,
        "database example_resource is missing",
    )
    .with_resource("example_resource")
    .with_remediation("enable create_on_startup or create the database")
    .with_retryable(false);

    assert_eq!(diagnostic.component(), "postgresql");
    assert_eq!(diagnostic.operation(), "ensure_database");
    assert_eq!(diagnostic.kind(), DiagnosticKind::ResourceMissing);
    assert_eq!(diagnostic.resource(), Some("example_resource"));
    assert_eq!(
        diagnostic.remediation(),
        Some("enable create_on_startup or create the database")
    );
    assert!(!diagnostic.retryable());
    let debug = format!("{diagnostic:?}");
    assert!(!debug.contains("database example_resource is missing"));
    assert!(!debug.contains("enable create_on_startup"));

    let filtered = Diagnostic::new(
        "\u{2003}API-数据库🙂 READ_2!\u{2003}",
        " \t数据库🙂 ",
        DiagnosticKind::Unknown,
        "",
    );
    assert_eq!(filtered.component(), "api_read_2");
    assert_eq!(filtered.operation(), "operation");

    let bounded = Diagnostic::new(
        format!(
            "{}{}-tail",
            "界".repeat(MAX_DIAGNOSTIC_FIELD_LENGTH + 1),
            "A".repeat(MAX_DIAGNOSTIC_FIELD_LENGTH)
        ),
        "",
        DiagnosticKind::Unknown,
        "",
    );
    assert_eq!(bounded.component(), "a".repeat(MAX_DIAGNOSTIC_FIELD_LENGTH));
    assert_eq!(bounded.operation(), "operation");

    let empty = Diagnostic::new("", "", DiagnosticKind::Unknown, "");
    assert_eq!(empty.component(), "component");
    assert_eq!(empty.operation(), "operation");
}

#[cfg(feature = "settings")]
#[test]
fn diagnostic_can_be_created_from_settings_validation_error() {
    let error = crate::settings::SettingsValidationError::single(
        "http.timeout",
        "must be greater than zero",
    );
    let diagnostic = Diagnostic::from(error);

    assert_eq!(diagnostic.component(), "settings");
    assert_eq!(diagnostic.operation(), "validate_configuration");
    assert_eq!(diagnostic.kind(), DiagnosticKind::InvalidConfiguration);
    assert!(diagnostic.message().contains("http.timeout"));
}