axum_gate/permissions/
validate_permissions.rs

1//! Compile-time permission validation to prevent hash collisions.
2//!
3//! This module provides the [`validate_permissions!`](crate::validate_permissions) macro for compile-time validation
4//! of permission strings to ensure they don't have hash collisions. This is essential
5//! for the deterministic permission system to work correctly across distributed nodes.
6//!
7//! # Usage
8//!
9//! Call the macro once in your application with all permission strings you use:
10//!
11//! ```rust
12//! axum_gate::validate_permissions![
13//!     "read:user",
14//!     "write:user",
15//!     "delete:user",
16//!     "read:admin",
17//!     "write:admin",
18//!     "system:health",
19//! ];
20//! ```
21//!
22//! # How It Works
23//!
24//! The macro generates a test function that:
25//! 1. Converts each permission string to a `PermissionId`
26//! 2. Checks for hash collisions between any two permissions
27//! 3. Panics during `cargo test` if collisions are found
28//!
29//! # When to Use
30//!
31//! - **Required**: When using string-based permissions in production
32//! - **Recommended**: Run during CI/CD to catch collisions early
33//! - **Best Practice**: Include all permissions used across your application
34//!
35//! # Example Integration
36//!
37//! ```rust
38//! // In your main application or tests
39//! axum_gate::validate_permissions![
40//!     "api:read",
41//!     "api:write",
42//!     "api:delete",
43//!     "user:profile:read",
44//!     "user:profile:write",
45//!     "admin:users:manage",
46//!     "admin:system:config",
47//! ];
48//! ```
49
50/// Macro for test-time permission validation.
51///
52/// This macro validates that the provided permission strings don't have hash collisions
53/// by generating a test that runs during `cargo test`. It should be called once in your
54/// application with all the permission strings you use.
55///
56/// The macro accepts both square brackets and parentheses syntax.
57///
58/// # Examples
59///
60/// ```rust
61/// # use axum_gate::validate_permissions;
62///
63/// // Using square brackets (recommended style)
64/// validate_permissions![
65///     "read:users",
66///     "write:users",
67///     "delete:users",
68///     "admin:system"
69/// ];
70///
71/// // Using parentheses (also valid)
72/// validate_permissions!(
73///     "read:posts",
74///     "write:posts",
75///     "delete:posts"
76/// );
77///
78/// // Mixed permission types
79/// validate_permissions![
80///     "api:read",
81///     "api:write",
82///     "admin:users",
83///     "admin:system",
84///     "billing:read",
85///     "billing:write"
86/// ];
87/// ```
88///
89/// # Panics
90///
91/// This macro will cause a test failure if any of the permission strings
92/// hash to the same value (extremely unlikely with SHA-256).
93#[macro_export]
94macro_rules! validate_permissions {
95    ($($permission:expr),* $(,)?) => {
96        #[cfg(test)]
97        mod __axum_gate_permission_validation {
98
99            #[test]
100            fn validate_permission_uniqueness() {
101                let permissions: Vec<String> = vec![$($permission.to_string()),*];
102                let mut checker = $crate::permissions::PermissionCollisionChecker::new(permissions);
103                let report = checker.validate()
104                    .expect("Permission validation failed: validation process error");
105
106                if !report.is_valid() {
107                    panic!("Permission validation failed: {}", report.summary());
108                }
109            }
110        }
111    };
112}
113
114#[cfg(test)]
115mod tests {
116    // Test the macro
117    validate_permissions!["test:permission1", "test:permission2", "test:permission3"];
118}
axum_gate/permissions/validate_permissions.rs

axum_gate/permissions/
validate_permissions.rs
