Struct AllowlistAspect 

pub struct AllowlistAspect { /* private fields */ }

Identity-based allowlist aspect.

Admits a call when the supplied identity string is present in a configured allowlist, optionally honoring a wildcard entry ("*") and an optional normalization hook for identity comparison.

This shape recurs across messaging-channel integrations in real codebases: each channel maintains its own list of who is permitted to talk to the bot. The classical role-based AuthorizationAspect does not fit because there are no roles — there is a set of literal identity strings and a yes/no decision.

Example

use aspect_std::AllowlistAspect;

let policy = AllowlistAspect::new(["user_a".to_string(), "user_b".to_string()]);
assert!(policy.is_allowed("user_a"));
assert!(!policy.is_allowed("intruder"));

// Wildcard.
let open = AllowlistAspect::new(["*".to_string()]);
assert!(open.is_allowed("anyone"));

// Empty list = deny everyone.
let closed = AllowlistAspect::new(Vec::<String>::new());
assert!(!closed.is_allowed("user_a"));

Normalization

Some identity spaces require canonicalization before comparison: phone numbers (E.164), emails (case-insensitive), Telegram usernames (@-stripped), Matrix MXIDs (case-insensitive). Pass a normalization function via AllowlistAspect::with_normalizer.

Mutability

The allowlist is stored behind an RwLock and can be amended at runtime via AllowlistAspect::add / AllowlistAspect::set. This matches runtime-pairing flows where new identities are added without restart.

Implementations

impl AllowlistAspect

pub fn new<I, S>(entries: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Build an allowlist aspect from an initial set of entries.

The wildcard entry "*" admits everyone. An empty list denies everyone (fail-closed). Identity comparison is byte-equal by default; see AllowlistAspect::with_normalizer for case- insensitive or canonicalized comparison.

pub fn with_normalizer<F>(self, normalizer: F) -> Self

where F: Fn(&str) -> String + Send + Sync + 'static,

Attach a normalization function applied to both the allowlist entries and the queried identity before comparison.

Consumes and returns self. The normalizer must be deterministic and referentially transparent: calling it twice on the same input must produce identical output.

Mutually exclusive with AllowlistAspect::with_matcher: if a matcher is installed, the normalizer is bypassed because the matcher owns the entry-vs-identity comparison end-to-end.

pub fn with_matcher<F>(self, matcher: F) -> Self

where F: Fn(&str, &str) -> bool + Send + Sync + 'static,

Attach a custom match predicate (entry, identity) -> bool that replaces the default byte-equal (or normalized-equal) comparison.

Consumes and returns self. The wildcard "*" and empty-list short-circuits still apply before the matcher runs — the matcher is only consulted for non-"*" entries against a non-empty list. The matcher must be referentially transparent.

Use this when entries and identities are not directly comparable — e.g. allowlist entries that describe a class of identity ("@example.com" matches any user at that domain) rather than a single literal one. When a matcher is set the normalizer is bypassed; the matcher owns the comparison.

pub fn is_allowed(&self, identity: &str) -> bool

Returns true if identity is admitted by the allowlist.

Semantics: empty list ⇒ deny; "*" present ⇒ admit; otherwise admit iff the (possibly normalized) identity equals some (possibly normalized) entry.

pub fn add(&self, identity: impl Into<String>)

Append identity to the allowlist if absent. No-op when identity is already present (byte-equal, not normalized).

pub fn set<I, S>(&self, entries: I)

where I: IntoIterator<Item = S>, S: Into<String>,

Replace the entire allowlist atomically.

pub fn snapshot(&self) -> Vec<String>

Snapshot the current allowlist as an owned Vec. Order-preserving relative to insertion / construction.

pub fn len(&self) -> usize

Number of entries currently in the list (including the wildcard entry if present).

pub fn is_empty(&self) -> bool

Returns true when the allowlist is empty (i.e. denies everyone).

Trait Implementations

impl Aspect for AllowlistAspect

fn before(&self, _ctx: &JoinPoint)

Advice executed before the target function runs.

fn around( &self, pjp: ProceedingJoinPoint<'_>, ) -> Result<Box<dyn Any>, AspectError>

Advice that wraps the entire target function execution.

fn after(&self, _ctx: &JoinPoint, _result: &(dyn Any + 'static))

Advice executed after the target function completes successfully.

fn after_error(&self, _ctx: &JoinPoint, _error: &AspectError)

Advice executed when the target function encounters an error.

impl Clone for AllowlistAspect

fn clone(&self) -> AllowlistAspect

Returns a duplicate of the value.

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

Performs copy-assignment from source.