Struct PolicyEngine 

pub struct PolicyEngine<M: ValidationMode = SchemaFree> { /* private fields */ }

Implementations

impl PolicyEngine<SchemaFree>

pub fn new_from_str(policy_text: &str) -> Result<Self, PolicyError>

pub fn new_from_str_with_policy_stores( policy_text: &str, layout: PolicyStoreLayout, ) -> Result<Self, PolicyError>

Create an engine that partitions policies into namespace-owned stores.

Existing monolithic constructors remain unchanged. Store assignment is validated before the engine is returned, and each request must resolve to exactly one declared store or evaluation fails closed.

pub fn new_from_str_with_schema( policy_text: &str, schema: Schema, ) -> Result<PolicyEngine<SchemaEnforcing>, PolicyError>

Create a new policy engine with schema-based policy and request validation.

pub fn new_from_str_with_schema_and_policy_stores( policy_text: &str, schema: Schema, layout: PolicyStoreLayout, ) -> Result<PolicyEngine<SchemaEnforcing>, PolicyError>

Create a namespace-partitioned engine with schema validation.

pub fn new_from_str_with_cedarschema( policy_text: &str, schema_text: &str, ) -> Result<PolicyEngine<SchemaEnforcing>, PolicyError>

Create a new policy engine from policy text and Cedar schema text.

pub fn new_from_str_with_cedarschema_and_policy_stores( policy_text: &str, schema_text: &str, layout: PolicyStoreLayout, ) -> Result<PolicyEngine<SchemaEnforcing>, PolicyError>

Create a namespace-partitioned engine from policy and Cedar schema text.

impl<M: ValidationMode> PolicyEngine<M>

pub fn with_label_registry(self, registry: LabelRegistry) -> Self

Create a new policy engine with a label registry.

This is a convenience method that combines new_from_str and with_label_registry.

pub fn set_label_registry(&self, registry: LabelRegistry)

Set or replace the label registry for this engine.

This allows updating the labelers after the engine has been created.

pub fn label_registry(&self) -> Option<LabelRegistry>

Clone the current immutable label registry, if one is configured.

pub fn reload_from_str(&self, policy_text: &str) -> Result<(), PolicyError>

pub fn current_version(&self) -> PolicyVersion

Get the complete current authorization-state version.

The policy hash, policy load time, label-set version, and engine generation all come from the same atomic state load.

pub fn session(&self) -> EvaluationSession<M>

Capture one coherent authorization-state generation for batch work.

pub fn policy_store_ids(&self) -> Option<Vec<PolicyStoreId>>

Return configured policy-store IDs, or None for a monolithic engine.

pub fn evaluate(&self, request: &Request) -> Result<Decision, PolicyError>

Evaluate a policy request against the currently loaded policy set.

This method performs a complete Cedar policy evaluation:

1. Applies any registered labelers to augment resource attributes
2. Constructs Cedar entities for the principal (including groups), action, and resource
3. Executes the Cedar authorization decision
4. Returns either Allow (with the matching policy) or Deny, both including version metadata

Arguments

• request - The authorization request containing the principal, action, and resource

Returns

• Ok(decision) with Decision::is_allowed returning true if at least one permit policy matches and no forbid policies match, or false otherwise
• Err(PolicyError) - If there’s an error constructing entities, parsing the request, or during evaluation

Examples

use treetop_core::{PolicyEngine, Request, Principal, User, Action, Resource};

let policies = r#"
    permit (
        principal == User::"alice",
        action == Action::"read",
        resource == Document::"doc1"
    );
"#;

let engine = PolicyEngine::new_from_str(policies).unwrap();

let request = Request {
    principal: Principal::User(User::new("alice", None, None).unwrap()),
    action: Action::new("read", None).unwrap(),
    resource: Resource::new("Document", "doc1").unwrap(),
};

let decision = engine.evaluate(&request).unwrap();
assert!(decision.is_allowed());

// Access version information
println!("Allowed by policy version: {}", decision.version().hash);

Thread Safety

This method is thread-safe and lock-free. Multiple threads can evaluate requests concurrently without blocking each other.

pub fn evaluate_with_context( &self, request: &Request, request_context: &RequestContext, ) -> Result<Decision, PolicyError>

Evaluate a request with explicit Cedar request context.

pub fn evaluate_with_diagnostics( &self, request: &Request, ) -> Result<DecisionDiagnostics, PolicyError>

Evaluate a request and include deny-side forbid diagnostics.

pub fn evaluate_with_context_and_diagnostics( &self, request: &Request, request_context: &RequestContext, ) -> Result<DecisionDiagnostics, PolicyError>

Evaluate a request with explicit context and include deny diagnostics.

pub fn list_policies_for_user( &self, user: &str, groups: &[&str], namespace: &[&str], ) -> Result<PolicyCandidates, PolicyError>

List permit-policy candidates whose scope matches a user.

This mirrors PolicyEngine::evaluate input shape for principal identity: user id + groups + shared namespace.

Matching includes all Cedar principal-constraint forms:

• principal == User::"..."
• principal in Group::"..."
• principal
• principal is User
• principal is User in Group::"..."

Cedar when and unless clauses are not evaluated. The result is not an authorization decision; use PolicyEngine::evaluate to authorize. Resource constraints are not applied in this method. To additionally filter by policy resource constraints, use PolicyEngine::list_policies_for_user_with_resource.

Output is deterministic: policies are sorted by Cedar policy ID. Each returned policy includes match reasons via PolicyCandidates::matches().

Arguments

• user - User ID
• groups - Group IDs the user belongs to
• namespace - Optional shared namespace path for both user and groups

Returns

• Ok(PolicyCandidates) - Matching policies and match metadata
• Err(PolicyError) - If entity UID construction fails

Examples

use treetop_core::PolicyEngine;

let policies = r#"
    permit (principal == User::"alice", action, resource);
    permit (principal in Group::"admins", action, resource);
"#;

let engine = PolicyEngine::new_from_str(policies).unwrap();
let candidates = engine.list_policies_for_user("alice", &["admins"], &[]).unwrap();

assert_eq!(candidates.policies().len(), 2);
assert!(!candidates.matches().is_empty());

pub fn list_policies( &self, request: &Request, ) -> Result<PolicyCandidates, PolicyError>

List permit-policy candidates whose scope matches a concrete request.

This mirrors PolicyEngine::evaluate by accepting &Request and uses:

• the request principal (including user group membership, if any)
• the request action
• the request resource

Cedar when and unless clauses are not evaluated. The result is not an authorization decision. This method defaults to permit policies; use PolicyEngine::list_policies_with_effect for an explicit effect.

pub fn list_policies_with_effect( &self, request: &Request, effect_filter: PolicyEffectFilter, ) -> Result<PolicyCandidates, PolicyError>

List policy candidates for a request, with explicit effect filtering.

Cedar when and unless clauses are not evaluated.

pub fn list_policies_for_user_with_resource( &self, user: &str, groups: &[&str], namespace: &[&str], resource: Option<&Resource>, ) -> Result<PolicyCandidates, PolicyError>

List all policies applicable to a user, optionally filtering by resource constraints.

This variant applies both principal and resource constraints:

• principal constraints as described in PolicyEngine::list_policies_for_user
• resource constraints (==, in, is, is in, any) when resource is provided

When resource is None, behavior is equivalent to PolicyEngine::list_policies_for_user.

Returned PolicyCandidates includes match reasons for principal and, when applicable, resource matches.

pub fn list_policies_for_user_with_resource_and_effect( &self, user: &str, groups: &[&str], namespace: &[&str], resource: Option<&Resource>, effect_filter: PolicyEffectFilter, ) -> Result<PolicyCandidates, PolicyError>

List all policies applicable to a user with optional resource and effect filtering.

pub fn list_policies_for_group( &self, group: &str, namespace: &[&str], ) -> Result<PolicyCandidates, PolicyError>

List all policies applicable to a group principal.

Useful when callers model group identities directly as principals (mirroring Principal::Group in PolicyEngine::evaluate).

Resource constraints are not applied in this method. To also filter by resource constraints, use PolicyEngine::list_policies_for_group_with_resource.

pub fn list_policies_for_group_with_resource( &self, group: &str, namespace: &[&str], resource: Option<&Resource>, ) -> Result<PolicyCandidates, PolicyError>

List all policies applicable to a group principal, optionally filtering by resource constraints.

This applies principal constraints for a group principal and, when resource is provided, resource constraints as well.

pub fn list_policies_for_group_with_resource_and_effect( &self, group: &str, namespace: &[&str], resource: Option<&Resource>, effect_filter: PolicyEffectFilter, ) -> Result<PolicyCandidates, PolicyError>

List all policies applicable to a group principal with optional resource and effect filtering.

pub fn policies(&self) -> Vec<Policy>

Return all policies in the current coherent engine state.

impl PolicyEngine<SchemaEnforcing>

pub fn reload_from_str_with_schema( &self, policy_text: &str, schema: Schema, ) -> Result<(), PolicyError>

Reload policies and replace the enforced schema in one atomic update.

pub fn reload_from_str_with_cedarschema( &self, policy_text: &str, schema_text: &str, ) -> Result<(), PolicyError>

Reload policies and replace the enforced schema from Cedar schema text.

Trait Implementations

impl<M: Clone + ValidationMode> Clone for PolicyEngine<M>

fn clone(&self) -> PolicyEngine<M>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<M: ValidationMode> From<&PolicyEngine<M>> for PolicyVersion

fn from(engine: &PolicyEngine<M>) -> Self

Converts to this type from the input type.

impl<M: ValidationMode> From<PolicyEngine<M>> for PolicyVersion

fn from(engine: PolicyEngine<M>) -> Self

Converts to this type from the input type.