Struct Role 

pub struct Role { /* private fields */ }

A role represents a collection of permissions that can be assigned to subjects.

Implementations

impl Role

pub fn new(name: impl Into<String>) -> Role

Create a new role with the given name.

pub fn with_id(id: impl Into<String>, name: impl Into<String>) -> Role

Create a new role with a specific ID.

pub fn id(&self) -> &str

Get the role’s unique identifier.

pub fn name(&self) -> &str

Get the role’s name.

pub fn with_description(self, description: impl Into<String>) -> Role

Set the role’s description.

pub fn description(&self) -> Option<&str>

Get the role’s description.

pub fn add_permission(self, permission: Permission) -> Role

Add a permission to this role.

pub fn add_permissions( self, permissions: impl IntoIterator<Item = Permission>, ) -> Role

Add multiple permissions to this role.

pub fn remove_permission(&mut self, permission: &Permission)

Remove a permission from this role.

pub fn has_permission_exact(&self, permission: &Permission) -> bool

Check if this role has a specific permission.

pub fn has_permission( &self, action: &str, resource_type: &str, context: &HashMap<String, String>, ) -> bool

Check if this role grants permission for an action on a resource type.

pub fn permissions(&self) -> &PermissionSet

Get all permissions granted by this role.

pub fn with_metadata( self, key: impl Into<String>, value: impl Into<String>, ) -> Role

Set metadata for this role.

pub fn metadata(&self, key: &str) -> Option<&str>

Get metadata value for a key.

pub fn all_metadata(&self) -> &HashMap<String, String>

Get all metadata.

pub fn set_active(&mut self, active: bool)

Set whether this role is active.

pub fn is_active(&self) -> bool

Check if this role is active.

pub fn deactivate(self) -> Role

Deactivate this role.

pub fn merge_permissions(&mut self, other: &Role)

Merge permissions from another role into this one.

pub fn parent_role_id(&self) -> Option<&str>

Get the parent role ID if this role has a parent in the hierarchy.

This method provides access to the direct parent relationship, enabling use cases like API responses, admin interfaces, and JWT token generation.

Returns None if:

• This role has no parent (it’s a root role)
• Hierarchy access is disabled in configuration

Example

use role_system::Role;

let role = Role::new("junior_dev");
if let Some(parent_id) = role.parent_role_id() {
    println!("Parent role: {}", parent_id);
}

Note

This method returns None by default to maintain backward compatibility. The actual parent relationship is managed by the RoleHierarchy system. To use this feature, the role must be created through a system that tracks hierarchy relationships and enables hierarchy access.

pub fn child_role_ids(&self) -> Vec<&str>

Get the child role IDs if this role has children in the hierarchy.

This method provides access to direct child relationships, useful for building admin interfaces, API responses, and permission visualization.

Returns empty vector if:

• This role has no children
• Hierarchy access is disabled in configuration

Example

use role_system::Role;

let role = Role::new("team_lead");
let children = role.child_role_ids();
for child_id in children {
    println!("Child role: {}", child_id);
}

Note

This method returns an empty vector by default to maintain backward compatibility. The actual child relationships are managed by the RoleHierarchy system. To use this feature, the role must be created through a system that tracks hierarchy relationships and enables hierarchy access.

pub fn is_root_role(&self) -> bool

Check if this role is a root role (has no parent).

A root role is one that sits at the top of a hierarchy branch and doesn’t inherit from any other role.

Example

use role_system::Role;

let admin_role = Role::new("admin");
if admin_role.is_root_role() {
    println!("This is a top-level role");
}

Note

Returns true by default since individual Role instances don’t track hierarchy relationships. Use RoleHierarchy or AsyncRoleSystem for actual hierarchy-aware operations.

pub fn is_leaf_role(&self) -> bool

Check if this role is a leaf role (has no children).

A leaf role is one that doesn’t have any roles inheriting from it.

Example

use role_system::Role;

let intern_role = Role::new("intern");
if intern_role.is_leaf_role() {
    println!("This role has no children");
}

Note

Returns true by default since individual Role instances don’t track hierarchy relationships. Use RoleHierarchy or AsyncRoleSystem for actual hierarchy-aware operations.

pub fn hierarchy_depth(&self) -> usize

Get the depth of this role in the hierarchy.

Root roles have depth 0, their children have depth 1, etc. This is useful for visualization and API responses.

Example

use role_system::Role;

let role = Role::new("senior_dev");
let depth = role.hierarchy_depth();
println!("Role depth: {}", depth);

Note

Returns 0 by default since individual Role instances don’t track hierarchy relationships. Use RoleHierarchy or AsyncRoleSystem for actual hierarchy-aware depth calculation.

pub fn hierarchy_metadata(&self) -> HashMap<String, String>

Get metadata about this role’s position in the hierarchy.

Returns a HashMap containing hierarchy-related metadata such as:

• “parent_count”: Number of ancestors
• “child_count”: Number of direct children
• “descendant_count”: Total number of descendants
• “depth”: Depth in hierarchy

Example

use role_system::Role;

let role = Role::new("manager");
let hierarchy_meta = role.hierarchy_metadata();
if let Some(depth) = hierarchy_meta.get("depth") {
    println!("Hierarchy depth: {}", depth);
}

Note

Returns minimal metadata by default. Use RoleHierarchy or AsyncRoleSystem for complete hierarchy metadata.

Trait Implementations

impl Clone for Role

fn clone(&self) -> Role

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Role

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Role

fn deserialize<__D>( __deserializer: __D, ) -> Result<Role, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Role

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.