webgates_core/permissions/
validate_permissions.rs

1//! Compile-time permission validation to prevent hash collisions.
2//!
3//! This module exposes the [`validate_permissions!`](crate::validate_permissions)
4//! macro for test-time validation of permission strings.
5//!
6//! Use it once in your application or test crate to verify that the permission
7//! names you rely on do not normalize to colliding
8//! [`crate::permissions::PermissionId`] values.
9//!
10//! # Usage
11//!
12//! ```rust
13//! use webgates_core::validate_permissions;
14//!
15//! validate_permissions![
16//!     "read:user",
17//!     "write:user",
18//!     "delete:user",
19//!     "read:admin",
20//!     "write:admin",
21//!     "system:health",
22//! ];
23//! ```
24//!
25//! # How it works
26//!
27//! The macro generates a test that:
28//! 1. Converts each permission string into a
29//!    [`crate::permissions::permission_id::PermissionId`]
30//! 2. Validates the full set with
31//!    [`crate::permissions::collision_checker::PermissionCollisionChecker`]
32//! 3. Fails the test when duplicates or hash collisions are detected
33//!
34//! # When to use
35//!
36//! - Required when your application depends on string-based permissions
37//! - Recommended in CI so permission changes are validated automatically
38//! - Best used with the complete set of permissions your application defines
39//!
40//! # Example integration
41//!
42//! ```rust
43//! use webgates_core::validate_permissions;
44//!
45//! validate_permissions![
46//!     "api:read",
47//!     "api:write",
48//!     "api:delete",
49//!     "user:profile:read",
50//!     "user:profile:write",
51//!     "admin:users:manage",
52//!     "admin:system:config",
53//! ];
54//! ```
55
56/// Macro for test-time permission validation.
57///
58/// Use this macro to validate a complete set of permission names during tests.
59/// It generates a test that checks the provided strings with
60/// [`crate::permissions::collision_checker::PermissionCollisionChecker`].
61///
62/// The macro accepts both square bracket and parenthesis invocation forms.
63///
64/// # Examples
65///
66/// ```rust
67/// use webgates_core::validate_permissions;
68///
69/// validate_permissions![
70///     "read:users",
71///     "write:users",
72///     "delete:users",
73///     "admin:system",
74/// ];
75///
76/// validate_permissions!(
77///     "read:posts",
78///     "write:posts",
79///     "delete:posts"
80/// );
81///
82/// validate_permissions![
83///     "api:read",
84///     "api:write",
85///     "admin:users",
86///     "admin:system",
87///     "billing:read",
88///     "billing:write",
89/// ];
90/// ```
91///
92/// # Panics
93///
94/// The generated test fails when the provided permission strings contain
95/// duplicates or hash collisions.
96#[macro_export]
97macro_rules! validate_permissions {
98    ($($permission:expr),* $(,)?) => {
99        #[cfg(test)]
100        mod __webgates_permission_validation {
101
102            #[test]
103            fn validate_permission_uniqueness() {
104                let permissions: Vec<String> = vec![$($permission.to_string()),*];
105                let mut checker =
106                    $crate::permissions::collision_checker::PermissionCollisionChecker::new(permissions);
107                let report = match checker.validate() {
108                    Ok(report) => report,
109                    Err(error) => {
110                        panic!("Permission validation failed: validation process error: {}", error);
111                    }
112                };
113
114                if !report.is_valid() {
115                    panic!("Permission validation failed: {}", report.summary());
116                }
117            }
118        }
119    };
120}
121
122#[cfg(test)]
123mod tests {
124    // Test the macro
125    validate_permissions!["test:permission1", "test:permission2", "test:permission3"];
126}
webgates_core/permissions/validate_permissions.rs

webgates_core/permissions/
validate_permissions.rs
