footing 0.1.3

Feature-gated foundations for Rust backend services
Documentation
use axum::http::Method;

use super::{
    EndpointAudit, EndpointAuth, EndpointContract, EndpointContractRegistry,
    EndpointContractSnapshot, EndpointMethod, EndpointPathPattern, EndpointPermissions,
    EndpointRateLimit, EndpointRisk,
};
use crate::result::{ClassifyError, ErrorKind};

#[test]
fn endpoint_contract_matches_exact_and_template_paths() {
    let exact: EndpointContract = EndpointContract::new(
        EndpointMethod::Get,
        EndpointPathPattern::Exact("/api/users"),
    );
    let template: EndpointContract = EndpointContract::new(
        EndpointMethod::Delete,
        EndpointPathPattern::Template("/api/users/{id}"),
    );

    assert!(exact.matches(&Method::GET, "/api/users"));
    assert!(!exact.matches(&Method::GET, "/api/users/123"));
    assert!(template.matches(&Method::DELETE, "/api/users/123"));
    assert!(!template.matches(&Method::DELETE, "/api/users/123/sessions"));
}

#[test]
fn unsupported_endpoint_method_is_classified_as_validation() {
    let error = EndpointMethod::try_from(&Method::TRACE)
        .expect_err("TRACE should not be contractable")
        .error_descriptor();

    assert_eq!(error.kind(), ErrorKind::Validation);
    assert_eq!(error.code().as_str(), "endpoint_method_unsupported");
}

#[test]
fn endpoint_method_converts_every_supported_http_method() {
    for (method, expected) in [
        (Method::DELETE, EndpointMethod::Delete),
        (Method::GET, EndpointMethod::Get),
        (Method::HEAD, EndpointMethod::Head),
        (Method::OPTIONS, EndpointMethod::Options),
        (Method::PATCH, EndpointMethod::Patch),
        (Method::POST, EndpointMethod::Post),
        (Method::PUT, EndpointMethod::Put),
    ] {
        assert_eq!(EndpointMethod::try_from(&method), Ok(expected));
    }
}

#[test]
fn endpoint_permissions_support_common_policy_modes() {
    let one = EndpointPermissions::one("users:read");
    let any = EndpointPermissions::any(&["users:read", "users:write"]);
    let all = EndpointPermissions::all(&["users:read", "users:write"]);

    assert!(one.is_granted_by(|permission| permission == "users:read"));
    assert!(any.is_granted_by(|permission| permission == "users:write"));
    assert!(!all.is_granted_by(|permission| permission == "users:write"));
    assert!(all.contains("users:read"));
    assert!(!EndpointPermissions::<&str>::all(&[]).is_granted_by(|_| true));
}

#[test]
fn registry_validates_duplicate_routes_and_private_permissions() {
    let endpoints = [
        EndpointContract::new(
            EndpointMethod::Get,
            EndpointPathPattern::Exact("/api/users"),
        )
        .with_auth(EndpointAuth::Admin)
        .with_permissions(EndpointPermissions::one("users:read"))
        .with_risk(EndpointRisk::Low),
        EndpointContract::new(
            EndpointMethod::Post,
            EndpointPathPattern::Exact("/api/users"),
        )
        .with_auth(EndpointAuth::Admin)
        .with_permissions(EndpointPermissions::one("users:write"))
        .with_risk(EndpointRisk::Medium),
    ];

    let registry = EndpointContractRegistry::new(&endpoints);
    registry.validate().expect("contracts should be valid");
    assert!(registry.find(&Method::POST, "/api/users").is_some());
}

#[test]
fn registry_rejects_empty_permission_sets() {
    let endpoints = [EndpointContract::new(
        EndpointMethod::Get,
        EndpointPathPattern::Exact("/api/users"),
    )
    .with_auth(EndpointAuth::Admin)
    .with_permissions(EndpointPermissions::<&str>::all(&[]))];
    let registry = EndpointContractRegistry::new(&endpoints);
    let error = registry
        .validate()
        .expect_err("empty all permissions should be invalid");

    assert!(matches!(
        error,
        super::EndpointContractValidationError::EmptyPermissions { mode: "all", .. }
    ));
}

#[test]
fn registry_rejects_invalid_path_patterns() {
    let endpoints = [EndpointContract::new(
        EndpointMethod::Get,
        EndpointPathPattern::Exact("/api/users?active=true"),
    )];
    let registry = EndpointContractRegistry::<&str>::new(&endpoints);

    let error = registry
        .validate()
        .expect_err("query strings do not belong in route contracts");

    assert!(matches!(
        error,
        super::EndpointContractValidationError::InvalidPath { .. }
    ));
}

#[test]
fn registry_rejects_template_syntax_in_exact_paths() {
    let endpoints = [EndpointContract::new(
        EndpointMethod::Get,
        EndpointPathPattern::Exact("/api/users/{id}"),
    )];
    let registry = EndpointContractRegistry::<&str>::new(&endpoints);

    let error = registry
        .validate()
        .expect_err("template segments must use EndpointPathPattern::Template");

    assert!(matches!(
        error,
        super::EndpointContractValidationError::InvalidPath { .. }
    ));
}

#[test]
fn registry_rejects_invalid_custom_rate_limit_labels() {
    let endpoints = [EndpointContract::new(
        EndpointMethod::Get,
        EndpointPathPattern::Exact("/api/users"),
    )
    .with_rate_limit(EndpointRateLimit::Custom("User Reads"))];
    let registry = EndpointContractRegistry::<&str>::new(&endpoints);

    let error = registry
        .validate()
        .expect_err("custom rate limit labels must be stable metric labels");

    assert!(matches!(
        error,
        super::EndpointContractValidationError::InvalidRateLimitLabel { .. }
    ));
}

#[test]
fn registry_exports_stable_contract_documents() {
    let endpoints = [EndpointContract::new(
        EndpointMethod::Get,
        EndpointPathPattern::Exact("/api/users"),
    )
    .with_auth(EndpointAuth::Admin)
    .with_permissions(EndpointPermissions::one("users:read"))
    .with_risk(EndpointRisk::Low)];
    let registry = EndpointContractRegistry::new(&endpoints);

    let documents = registry.documents(str::to_owned);

    assert_eq!(documents.len(), 1);
    assert_eq!(documents[0].method, "GET");
    assert_eq!(documents[0].path, "/api/users");
    assert_eq!(documents[0].auth, "admin");
    assert_eq!(documents[0].permissions.mode, "one");
    assert_eq!(documents[0].permissions.values, ["users:read"]);
}

#[test]
fn registry_exports_stable_contract_snapshot() {
    let endpoints = [
        EndpointContract::new(
            EndpointMethod::Get,
            EndpointPathPattern::Exact("/api/users"),
        )
        .with_auth(EndpointAuth::Admin)
        .with_permissions(EndpointPermissions::one("users:read"))
        .with_risk(EndpointRisk::Low)
        .with_rate_limit(EndpointRateLimit::Read)
        .with_audit(EndpointAudit::Optional),
        EndpointContract::new(
            EndpointMethod::Delete,
            EndpointPathPattern::Template("/api/users/{id}"),
        )
        .with_auth(EndpointAuth::Admin)
        .with_permissions(EndpointPermissions::one("users:delete"))
        .with_risk(EndpointRisk::High)
        .with_rate_limit(EndpointRateLimit::Write)
        .with_audit(EndpointAudit::Required),
    ];
    let registry = EndpointContractRegistry::new(&endpoints);

    let snapshot = registry.snapshot(str::to_owned);

    assert_eq!(
        snapshot.schema_version,
        EndpointContractSnapshot::SCHEMA_VERSION
    );
    assert_eq!(snapshot.summary.total, 2);
    assert_eq!(snapshot.summary.permissioned, 2);
    assert_eq!(snapshot.summary.by_auth["admin"], 2);
    assert_eq!(snapshot.summary.by_risk["high"], 1);
    assert_eq!(snapshot.summary.by_audit["required"], 1);
    assert!(
        snapshot
            .to_pretty_json()
            .expect("json")
            .contains("\"endpoints\"")
    );
}