1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
/// Marker trait for role types that have a privilege hierarchy.
///
/// Implement this trait when your application uses roles ordered from least
/// privileged to most privileged. `webgates-core` uses that ordering to answer
/// questions like: "does an admin satisfy a moderator requirement?"
///
/// Implementors must satisfy these invariants:
/// - the type has a total order via `Ord` and `PartialOrd`
/// - higher privilege compares greater than lower privilege
/// - `Default::default()` returns the least privileged role
///
/// These constraints let authorization code express hierarchy checks with
/// straightforward comparisons instead of custom lookup tables.
///
/// # Supervisor checks
///
/// A role `user_role` satisfies a required role `required_role` when:
/// - `user_role == required_role` for an exact match
/// - `user_role >= required_role` when supervisor access is allowed
///
/// # Example
///
/// ```
/// #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
/// enum Role {
/// #[default]
/// User,
/// Reporter,
/// Moderator,
/// Admin,
/// }
///
/// assert!(Role::Admin > Role::Moderator);
/// assert!(Role::Moderator > Role::User);
/// assert_eq!(Role::default(), Role::User);
/// assert!(Role::Admin >= Role::User);
/// ```
///
/// Reordering variants changes authorization semantics and should be treated as
/// a deliberate API change.