Struct PermissionMapping

Source

pub struct PermissionMapping { /* private fields */ }

Expand description

Mapping between a permission name and its deterministic permission ID.

This type stores the relationship between:

the normalized permission string (trimmed and lowercased)
the computed 64-bit permission ID used in bitmap storage

§Purpose

This mapping enables reverse lookup from permission IDs back to their normalized string representations, which is useful for:

Debugging and logging
Administrative interfaces
Audit trails
Permission reporting

§Design Principles

Immutable once created; construct via From<&str>/From<String> or PermissionMapping::new(original, id)
Contains only the normalized string and computed ID (the original input form is not retained)
Validates consistency between string and ID during construction with new; validate() can be used to re-check invariants

§Examples

use webgates_core::permissions::permission_id::PermissionId;
use webgates_core::permissions::mapping::PermissionMapping;

// Create from a permission string
let mapping = PermissionMapping::from("Read:API");
assert_eq!(mapping.normalized_string(), "read:api");
assert_eq!(mapping.permission_id(), PermissionId::from("Read:API"));

// Create from components (useful for deserialization)
let id = PermissionId::from("write:file");
let mapping = PermissionMapping::new("Write:File", id).unwrap();

§Validation

The mapping validates that the provided permission ID actually corresponds to the normalized string to prevent inconsistent state.

§Construction

Prefer PermissionMapping::from(<&str|String>) when you have the permission in string form. Use PermissionMapping::new(original, id) when deserializing or when both pieces are provided and must be validated.

§Serialization

This type derives Serialize/Deserialize. The serialized shape contains normalized_string and permission_id.

Implementations§

Source §

impl PermissionMapping

Source

pub fn new( original: impl Into<String>, id: PermissionId, ) -> Result<Self, PermissionMappingError>

Creates a new mapping from a permission string and an existing ID.

This constructor validates that the provided ID actually corresponds to the normalized string so inconsistent state cannot be created by mistake.

§Arguments

original - The original permission string as provided
id - The permission ID that must correspond to the normalized form of original

Normalization is handled internally from original (trim + lowercase)

§Returns

Returns Ok(PermissionMapping) if the ID matches the normalized string, or Err(PermissionMappingError) if there’s a mismatch.

§Examples

use webgates_core::permissions::permission_id::PermissionId;
use webgates_core::permissions::mapping::PermissionMapping;

let id = PermissionId::from("read:api");
let mapping = PermissionMapping::new("Read:API", id).unwrap();

Source

pub fn normalized_string(&self) -> &str

Returns the normalized permission string.

The normalized form is trimmed and lowercased. This is the exact value used to compute the permission ID.

Source

pub fn permission_id(&self) -> PermissionId

Returns the computed permission ID.

This is the 64-bit identifier that would be stored in the permissions bitmap.

Source

pub fn id_as_u64(&self) -> u64

Returns the permission ID as a raw u64 value.

This is a convenience method for storage, diagnostics, or comparisons.

Source

pub fn matches_string(&self, permission: &str) -> bool

Checks whether this mapping corresponds to the given permission string.

The comparison uses the normalized form of the input, so it ignores case and surrounding whitespace differences.

§Examples

use webgates_core::permissions::mapping::PermissionMapping;

let mapping = PermissionMapping::from("read:api");
assert!(mapping.matches_string("READ:API"));
assert!(mapping.matches_string("  read:api  "));
assert!(!mapping.matches_string("write:api"));

Source

pub fn matches_id(&self, id: PermissionId) -> bool

Checks whether this mapping corresponds to the given permission ID.

§Examples

use webgates_core::permissions::permission_id::PermissionId;
use webgates_core::permissions::mapping::PermissionMapping;

let mapping = PermissionMapping::from("read:api");
let id = PermissionId::from("read:api");
assert!(mapping.matches_id(id));

Source

pub fn validate(&self) -> Result<(), PermissionMappingError>

Validates that this mapping is internally consistent.

This checks that the permission ID actually corresponds to the normalized string, which should always be true for properly constructed mappings.

Note: Calling this is typically only necessary when a mapping is created via serde deserialization. Constructors from strings (From<&str>/From<String>) and PermissionMapping::new(original, id) enforce the invariant at creation time.

Returns Ok(()) if consistent, or Err(PermissionMappingError) if not.