footing 0.1.18

Feature-gated foundations for Rust backend services
Documentation
use super::{
    ClassifyError, Diagnostic, DiagnosticKind, ErrorBoundaryPolicy, ErrorCode, ErrorCodeError,
    ErrorDescriptor, ErrorKind, ErrorVisibility, 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);
        assert_eq!(diagnostic.message(), expected);
    }
}

#[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() {
    let descriptor = ErrorDescriptor::new(
        ErrorKind::Dependency,
        code("storage_unavailable"),
        "storage down",
    );
    let decision = ErrorBoundaryPolicy::trusted_internal().decide_descriptor(descriptor);

    assert_eq!(decision.public_message(), "storage down");
}

#[test]
fn boundary_presets_match_their_external_contract() {
    assert!(!ErrorBoundaryPolicy::http_api().exposes_server_error_messages());
    assert!(ErrorBoundaryPolicy::http_api().alerts_internal_errors());

    assert!(!ErrorBoundaryPolicy::worker().exposes_server_error_messages());
    assert!(ErrorBoundaryPolicy::worker().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::dependency(
        "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!(diagnostic.remediation().is_some());
    assert!(!diagnostic.retryable());
    let debug = format!("{diagnostic:?}");
    assert!(!debug.contains("database example_resource is missing"));
    assert!(!debug.contains("enable create_on_startup"));
}

#[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"));
}