use axum::http::Method;
use super::{
EndpointAudit, EndpointAuth, EndpointContract, EndpointContractRegistry,
EndpointContractSnapshot, EndpointMethod, EndpointPathPattern, EndpointPermissions,
EndpointPolicy, EndpointRisk, EndpointRouter,
};
use crate::http::{IdempotencyRequestPolicy, RateLimitRequestPolicy};
use crate::result::{ClassifyError, ErrorKind};
#[tokio::test]
async fn registered_contract_lookup_uses_axum_route_precedence_and_head_fallback() {
use crate::http::{HttpMiddlewareConfig, HttpMiddlewareStack};
use axum::{
body::{Body, to_bytes},
extract::{MatchedPath, State},
http::Request,
};
use tower::ServiceExt;
let contracts: [EndpointContract; 2] = [
EndpointContract::new(
EndpointMethod::Get,
EndpointPathPattern::template("/users/{id}"),
),
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::exact("/users/me")),
]
.map(|contract| contract.with_rate_limit(RateLimitRequestPolicy::Disabled));
async fn selected(
State(contracts): State<[EndpointContract; 2]>,
method: Method,
path: MatchedPath,
) -> String {
let registry = EndpointContractRegistry::new(&contracts);
let contract = registry.find(&method, &path).unwrap();
assert_eq!(
registry.find(&Method::HEAD, &path).unwrap().path(),
contract.path()
);
contract.path().as_str().to_owned()
}
let routes = EndpointRouter::new()
.route(contracts[0].clone(), selected)
.unwrap()
.route(contracts[1].clone(), selected)
.unwrap();
assert_eq!(routes.contracts().endpoints(), &contracts);
let app = routes
.into_router(
HttpMiddlewareStack::builder(HttpMiddlewareConfig::minimal())
.build()
.unwrap(),
)
.unwrap()
.with_state(contracts);
for (path, expected) in [("/users/me", "/users/me"), ("/users/42", "/users/{id}")] {
let response = app
.clone()
.oneshot(Request::get(path).body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(to_bytes(response.into_body(), 100).await.unwrap(), expected);
}
}
#[test]
fn route_registration_rejects_duplicates_including_different_pattern_variants() {
let first: EndpointContract =
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::exact("/users"));
let duplicate =
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::template("/users"));
assert!(matches!(
EndpointRouter::<()>::new()
.route(first, || async {})
.unwrap()
.route(duplicate, || async {}),
Err(super::EndpointContractValidationError::DuplicateRoute { .. })
));
}
#[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 none = EndpointPermissions::<&str>::None;
let one = EndpointPermissions::One("users:read");
let any = EndpointPermissions::Any(&["users:read", "users:write"]);
let all = EndpointPermissions::All(&["users:read", "users:write"]);
assert!(none.is_none());
assert!(none.is_granted_by(|_| panic!("no permissions should be checked")));
assert!(!none.contains("users:read"));
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 authentication_and_permission_requirements_are_independent() {
for auth in [
EndpointAuth::Public,
EndpointAuth::Authenticated,
EndpointAuth::User,
EndpointAuth::Client,
EndpointAuth::Admin,
EndpointAuth::Service,
] {
let contract =
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::exact("/profile"))
.with_auth(auth);
EndpointContractRegistry::new(std::slice::from_ref(&contract))
.validate()
.unwrap();
let document = contract.document(str::to_owned);
assert_eq!(document.auth, auth.as_str());
assert_eq!(document.permissions.mode, "none");
assert!(document.permissions.values.is_empty());
let guarded = contract.with_permissions(EndpointPermissions::One("profile:read"));
let endpoints = [guarded];
let result = EndpointContractRegistry::new(&endpoints).validate();
if auth == EndpointAuth::Public {
assert!(matches!(
result,
Err(
super::EndpointContractValidationError::PublicEndpointRequiresPermissions { .. }
)
));
} else {
result.unwrap();
}
}
}
#[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");
}
#[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_legacy_axum_path_prefixes_before_registration() {
for path in ["/:user", "/users/:id/", "/*path", "/files/*path"] {
for pattern in [
EndpointPathPattern::exact(path),
EndpointPathPattern::template(path),
] {
let contract: EndpointContract = EndpointContract::new(EndpointMethod::Get, pattern);
assert!(matches!(
EndpointRouter::<()>::new().route(contract, || async {}),
Err(super::EndpointContractValidationError::InvalidPath { .. })
));
}
}
}
#[tokio::test]
async fn template_routes_preserve_root_empty_segments_and_trailing_slashes() {
use axum::{body::Body, extract::MatchedPath, http::Request};
use tower::ServiceExt;
use crate::http::{HttpMiddlewareConfig, HttpMiddlewareStack};
for (path, request_path) in [
("/", "/"),
("/users/", "/users/"),
("/users/{id}/", "/users/42/"),
("/users//{id}/", "/users//42/"),
] {
let contract: EndpointContract =
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::template(path))
.with_rate_limit(RateLimitRequestPolicy::Disabled);
let app = EndpointRouter::<()>::new()
.route(contract.clone(), move |selected: MatchedPath| {
let contract = contract.clone();
async move {
assert_eq!(selected.as_str(), path);
assert_eq!(
EndpointContractRegistry::new(std::slice::from_ref(&contract))
.find(&Method::GET, &selected)
.unwrap(),
&contract
);
}
})
.unwrap()
.into_router(
HttpMiddlewareStack::builder(HttpMiddlewareConfig::minimal())
.build()
.unwrap(),
)
.unwrap();
assert_eq!(
app.oneshot(Request::get(request_path).body(Body::empty()).unwrap())
.await
.unwrap()
.status(),
axum::http::StatusCode::OK
);
}
}
#[test]
fn registry_rejects_unsupported_or_malformed_capture_segments() {
for path in [
"/users/{}",
"/users/{id",
"/users/id}",
"/users/{id}{name}",
"/users/user-{id}",
"/files/{*path}",
] {
let contract: EndpointContract =
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::template(path));
assert!(matches!(
EndpointRouter::<()>::new().route(contract, || async {}),
Err(super::EndpointContractValidationError::InvalidTemplate { .. })
));
}
}
#[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"]);
assert_eq!(documents[0].idempotency, "disabled");
assert_eq!(documents[0].rate_limit, "disabled");
}
#[test]
fn registry_exports_stable_contract_snapshot() {
const ADMIN: EndpointPolicy = EndpointPolicy::new().with_auth(EndpointAuth::Admin);
let endpoints = [
EndpointContract::new(
EndpointMethod::Get,
EndpointPathPattern::exact("/api/users"),
)
.with_policy(
ADMIN
.with_permissions(EndpointPermissions::One("users:read"))
.with_risk(EndpointRisk::Low)
.with_rate_limit(RateLimitRequestPolicy::Disabled)
.with_audit(EndpointAudit::Optional),
),
EndpointContract::new(
EndpointMethod::Delete,
EndpointPathPattern::template("/api/users/{id}"),
)
.with_policy(
ADMIN
.with_permissions(EndpointPermissions::One("users:delete"))
.with_risk(EndpointRisk::High)
.with_rate_limit(RateLimitRequestPolicy::Enabled)
.with_idempotency(IdempotencyRequestPolicy::Required)
.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_eq!(snapshot.summary().by_rate_limit["enabled"], 1);
assert_eq!(snapshot.summary().by_rate_limit["disabled"], 1);
assert_eq!(snapshot.summary().idempotency_required, 1);
assert!(
snapshot
.to_pretty_json()
.expect("json")
.contains("\"endpoints\"")
);
}
#[test]
fn snapshots_normalize_order_and_validate_derived_data_on_deserialization() {
let mut endpoints = [
EndpointContract::new(EndpointMethod::Post, EndpointPathPattern::exact("/users")),
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::exact("/health")),
EndpointContract::new(EndpointMethod::Get, EndpointPathPattern::exact("/users"))
.with_auth(EndpointAuth::Authenticated),
];
let snapshot = EndpointContractSnapshot::from_contracts(&endpoints, str::to_owned);
endpoints.reverse();
let reordered = EndpointContractSnapshot::from_contracts(&endpoints, str::to_owned);
assert_eq!(snapshot, reordered);
assert_eq!(
snapshot.to_pretty_json().unwrap(),
reordered.to_pretty_json().unwrap()
);
assert_eq!(snapshot.summary().total, 3);
assert_eq!(snapshot.summary().permissioned, 0);
assert_eq!(snapshot.summary().by_auth["authenticated"], 1);
assert_eq!(
snapshot
.endpoints()
.iter()
.map(|endpoint| (endpoint.path.as_str(), endpoint.method.as_str()))
.collect::<Vec<_>>(),
[("/health", "GET"), ("/users", "GET"), ("/users", "POST")],
);
let mut wire = serde_json::to_value(&snapshot).unwrap();
wire["endpoints"].as_array_mut().unwrap().reverse();
assert_eq!(
serde_json::from_value::<EndpointContractSnapshot>(wire.clone()).unwrap(),
snapshot
);
let bytes = postcard::to_allocvec(&snapshot).unwrap();
assert_eq!(
postcard::from_bytes::<EndpointContractSnapshot>(&bytes).unwrap(),
snapshot
);
let mut wrong_version = wire.clone();
wrong_version["schema_version"] = 2.into();
assert!(serde_json::from_value::<EndpointContractSnapshot>(wrong_version).is_err());
let mut stale_counts = wire.clone();
stale_counts["summary"]["permissioned"] = 1.into();
assert!(serde_json::from_value::<EndpointContractSnapshot>(stale_counts).is_err());
wire["endpoints"].as_array_mut().unwrap().pop();
assert!(serde_json::from_value::<EndpointContractSnapshot>(wire).is_err());
}