Struct EvaluationSession 

pub struct EvaluationSession { /* private fields */ }

Request-scoped fact loading and caching state.

A session is intended to live for one request or one authorization pass. It owns registered fact sources and caches loaded facts by key type. The cache is deliberately not process-global. Cached facts and cached errors are dropped with the session, so permission revocations or backend changes are observed by the next request’s session rather than being held process-wide.

There is intentionally no time-based (TTL) cache: freshness is governed by session lifetime — drop the session to drop its cache. If you need caching that outlives a single session (a process-wide cache with a TTL, say), layer it inside a FactSource implementation. A source can hold its own expiring cache and be shared across sessions through FactRegistry, which keeps the session a simple request-scoped layer on top.

Implementations

impl EvaluationSession

pub fn new() -> Self

Creates an empty request-scoped session.

pub fn empty() -> Self

Creates an explicitly empty request-scoped session.

This is equivalent to Self::new. It can make call sites clearer when only fact-free policies are expected and no fact sources are registered. For very hot fact-free loops, use Self::shared_empty to avoid allocating a new empty session per call.

Examples found in repository

examples/delegating_policy.rs (line 170)

async fn main() {
    let owner_id = Uuid::new_v4();
    let author_id = Uuid::new_v4();

    let comment = Comment {
        author_id,
        document: Document { owner_id },
    };

    let author = Principal {
        user_id: author_id,
        is_admin: false,
    };
    let document_owner = Principal {
        user_id: owner_id,
        is_admin: false,
    };
    let admin = Principal {
        user_id: Uuid::new_v4(),
        is_admin: true,
    };
    let stranger = Principal {
        user_id: Uuid::new_v4(),
        is_admin: false,
    };

    let checker = comment_checker();
    let session = EvaluationSession::empty();
    let action = EditComment;
    let context = ();

    let cases = [
        ("author", &author),
        ("document owner (not author)", &document_owner),
        ("admin (not author/owner)", &admin),
        ("unrelated user", &stranger),
    ];
    for (who, principal) in cases {
        let granted = checker
            .bind(&session, principal, &action, &context)
            .check(&comment)
            .await
            .is_granted();
        println!(
            "{who:<28} can edit the comment? {}",
            if granted { "yes" } else { "no" }
        );
    }

    // The document owner is not the comment author, so the direct rule denies;
    // the delegating policy then asks the document checker, which grants. The
    // trace shows the decision crossing the domain boundary.
    println!("\nTrace — document owner (not the author) editing the comment:");
    let decision = checker
        .bind(&session, &document_owner, &action, &context)
        .check(&comment)
        .await;
    println!("{}", decision.display_trace());

    assert!(checker
        .bind(&session, &author, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(checker
        .bind(&session, &document_owner, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(checker
        .bind(&session, &admin, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(!checker
        .bind(&session, &stranger, &action, &context)
        .check(&comment)
        .await
        .is_granted());
}

examples/mfa_freshness_context.rs (line 186)

async fn main() {
    let alice = User {
        id: Uuid::new_v4(),
        roles: vec!["finance".into()],
    };
    let small_refund = RefundRequest {
        id: Uuid::new_v4(),
        amount_cents: 5_000, // $50
    };
    let large_refund = RefundRequest {
        id: Uuid::new_v4(),
        amount_cents: 5_000_000, // $50,000
    };

    let now = SystemTime::now();
    let checker = build_checker();
    let session = EvaluationSession::empty();

    // Case 1: small refund, no MFA at all. Granted — the high-value
    // rule doesn't apply below the threshold, so the role grant decides.
    let small_no_mfa = ApprovalContext {
        current_time: now,
        mfa_verified_at: None,
    };
    let r = checker
        .bind(&session, &alice, &Approve, &small_no_mfa)
        .check(&small_refund)
        .await;
    report("small refund, no MFA", &r);
    r.assert_granted_by("FinanceCanApproveRefunds");

    // Case 2: large refund, no MFA. Forbidden by the freshness rule —
    // the veto overrides Alice's role grant.
    let r = checker
        .bind(&session, &alice, &Approve, &small_no_mfa)
        .check(&large_refund)
        .await;
    report("large refund, no MFA", &r);
    r.assert_forbidden_by("HighValueRequiresFreshMfa");

    // Case 3: large refund, MFA reasserted 8 minutes ago. Stale → forbidden.
    let stale = ApprovalContext {
        current_time: now,
        mfa_verified_at: Some(now - Duration::from_secs(8 * 60)),
    };
    let r = checker
        .bind(&session, &alice, &Approve, &stale)
        .check(&large_refund)
        .await;
    report("large refund, MFA 8m old", &r);
    r.assert_forbidden_by("HighValueRequiresFreshMfa");

    // Case 4: large refund, MFA reasserted 30 seconds ago. The deny rule
    // is not applicable, so the role grant decides.
    let fresh = ApprovalContext {
        current_time: now,
        mfa_verified_at: Some(now - Duration::from_secs(30)),
    };
    let r = checker
        .bind(&session, &alice, &Approve, &fresh)
        .check(&large_refund)
        .await;
    report("large refund, MFA 30s old", &r);
    r.assert_granted_by("FinanceCanApproveRefunds");

    // The point: cases 2-4 all use the same subject and resource. The
    // only thing that varies is `ApprovalContext`. That's exactly the
    // signal that the rule belongs in `Context`, not on User or
    // RefundRequest.
}

examples/rbac_policy.rs (line 100)

async fn main() {
    // The first resolver reads the requirement off the resource/action; the
    // second extracts the subject's roles. The role type (`Role`) is inferred
    // from the closures' return types.
    let rbac_policy = RbacPolicy::<DocumentDomain, _, _>::new(
        |_action: &ReadAction, doc: &Document| doc.required_roles.iter().copied().collect(),
        |user: &User| user.roles.iter().copied().collect(),
    );

    let mut checker = PermissionChecker::<DocumentDomain>::new();
    checker.add_policy(rbac_policy);

    let admin = user("admin", [Role::Admin]);
    let editor = user("editor", [Role::Editor]);
    let multi_role = user("editor+viewer", [Role::Editor, Role::Viewer]);
    let no_roles = user("no-roles", []);

    let admin_doc = document("admin handbook", [Role::Admin]);
    let editor_doc = document("style guide", [Role::Editor]);
    let shared_doc = document("team wiki", [Role::Editor, Role::Viewer]);

    // (user, document, expected outcome)
    let cases = [
        (&admin, &admin_doc, true),
        (&admin, &editor_doc, false), // admin role is not editor — no hierarchy here
        (&editor, &admin_doc, false),
        (&editor, &editor_doc, true),
        (&multi_role, &editor_doc, true),
        (&multi_role, &shared_doc, true),
        (&no_roles, &admin_doc, false),
        (&no_roles, &shared_doc, false),
    ];

    let session = EvaluationSession::empty();
    let action = ReadAction;
    let context = ();

    println!("{:<16} {:<16} verdict", "user", "document");
    println!("{}", "-".repeat(42));
    for (user, document, expected_granted) in cases {
        let decision = checker
            .bind(&session, user, &action, &context)
            .check(document)
            .await;
        println!(
            "{:<16} {:<16} {}",
            user.name,
            document.name,
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // Note the admin/style-guide denial above: `RbacPolicy` is a flat
    // role-match with no built-in hierarchy. If admins should read
    // everything, either include `Role::Admin` in each document's required
    // set or add a separate admin-override policy to the checker.

    println!("\nWhy the editor is denied the admin handbook:");
    let decision = checker
        .bind(&session, &editor, &action, &context)
        .check(&admin_doc)
        .await;
    println!("{}", decision.display_trace());
}

examples/policy_builder.rs (line 133)

async fn main() {
    let mut checker = PermissionChecker::<AdminDomain>::new();
    checker.add_policy(scoped_permission_policy());
    checker.add_policy(global_admin_policy());

    let org1 = Organization { id: "org-1".into() };
    let org2 = Organization { id: "org-2".into() };

    let org1_admin = StaffUser {
        name: "org1-admin",
        permissions: vec![GroupPermission {
            scope: "edit_user_settings",
            entity: "org-1".into(),
        }],
    };
    let org2_admin = StaffUser {
        name: "org2-admin",
        permissions: vec![GroupPermission {
            scope: "edit_user_settings",
            entity: "org-2".into(),
        }],
    };
    let no_grants = StaffUser {
        name: "no-grants",
        permissions: vec![],
    };
    let global_admin = StaffUser {
        name: "global-admin",
        permissions: vec![GroupPermission {
            scope: "global_admin",
            entity: String::new(),
        }],
    };

    // (user, action, organization, expected outcome)
    let cases = [
        // Scoped grant matches its own org…
        (&org1_admin, AdminAction::EditUserSettings, &org1, true),
        // …but not another org, and not another scope on the same org.
        (&org2_admin, AdminAction::EditUserSettings, &org1, false),
        (&org1_admin, AdminAction::EditOrgSettings, &org1, false),
        (&org2_admin, AdminAction::EditUserSettings, &org2, true),
        (&no_grants, AdminAction::EditUserSettings, &org1, false),
        // The global admin passes via the subject-axis policy on any org.
        (&global_admin, AdminAction::EditOrgSettings, &org1, true),
    ];

    for (user, action, org, expected_granted) in cases {
        let session = EvaluationSession::empty();
        let decision = checker.bind(&session, user, &action, &()).check(org).await;
        println!(
            "{:<12} {:?} on {}: {}",
            user.name,
            action,
            org.id,
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // The trace names the policy that decided; for a denial it shows every
    // policy that was consulted and why each said no.
    println!("\nWhy org2-admin cannot edit user settings on org-1:");
    let session = EvaluationSession::empty();
    let decision = checker
        .bind(&session, &org2_admin, &AdminAction::EditUserSettings, &())
        .check(&org1)
        .await;
    println!("{}", decision.display_trace());
}

examples/factsource_n_plus_one.rs (line 244)

async fn main() {
    // Same supplier, same hierarchy, same invoices for both shapes.
    let supplier_org = Uuid::new_v4();
    let customer = Uuid::new_v4();
    let supplier = Supplier {
        user_id: Uuid::new_v4(),
        org_id: supplier_org,
    };
    let routes = std::collections::HashMap::from([(supplier_org, customer)]);
    let hierarchy = Arc::new(HierarchyService::new(routes));

    let invoices: Vec<Invoice> = (0..25)
        .map(|_| Invoice {
            id: Uuid::new_v4(),
            customer_id: customer,
        })
        .collect();

    // ---- WRONG ----
    let mut wrong_checker = PermissionChecker::<SupplierInvoiceDomain>::new();
    wrong_checker.add_policy(WrongSupplierPolicy {
        hierarchy: Arc::clone(&hierarchy),
    });

    hierarchy.reset();
    let session = EvaluationSession::empty();
    let visible = wrong_checker
        .bind(&session, &supplier, &ViewAction, &())
        .filter(invoices.clone())
        .await;
    let wrong_calls = hierarchy.calls();
    println!(
        "[wrong] {} invoices -> {} hierarchy lookups (N+1, redundant)",
        visible.len(),
        wrong_calls,
    );
    // Check the lesson (call count) before the bookkeeping (item count)
    // so a regression in the dedup logic surfaces here, not in a
    // confusing length mismatch.
    assert_eq!(
        wrong_calls, 25,
        "the wrong shape pays one hierarchy call per item",
    );
    assert_eq!(visible.len(), 25);

    // ---- RIGHT ----
    let mut right_checker = PermissionChecker::<SupplierInvoiceDomain>::new();
    right_checker.add_policy(RightSupplierPolicy);

    hierarchy.reset();
    let load_many_calls = Arc::new(AtomicUsize::new(0));
    let session = FactRegistry::builder()
        .with_arc::<CustomerForOrg>(Arc::new(CustomerForOrgSource {
            hierarchy: Arc::clone(&hierarchy),
            load_many_calls: Arc::clone(&load_many_calls),
        }))
        .build()
        .session();
    let visible = right_checker
        .bind(&session, &supplier, &ViewAction, &())
        .filter(invoices)
        .await;
    let right_calls = hierarchy.calls();
    let batch_calls = load_many_calls.load(Ordering::SeqCst);
    println!(
        "[right] {} invoices ->  {} hierarchy lookup  ({} batched load_many call, deduped through the session)",
        visible.len(),
        right_calls,
        batch_calls,
    );
    assert_eq!(
        right_calls, 1,
        "the session deduplicates: one supplier_org, one backend call",
    );
    assert_eq!(
        batch_calls, 1,
        "the session batches: one load_many call covering the unique key set",
    );
    assert_eq!(visible.len(), 25);
}

examples/deny_override.rs (line 155)

async fn main() {
    let owner_id = Uuid::new_v4();
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
        suspended: false,
    };
    let suspended_owner = User {
        id: owner_id,
        is_admin: false,
        suspended: true,
    };
    let owner = User {
        id: owner_id,
        is_admin: false,
        suspended: false,
    };
    let stranger = User {
        id: Uuid::new_v4(),
        is_admin: false,
        suspended: false,
    };

    let normal_doc = Document {
        owner_id,
        legal_hold: false,
    };
    let held_doc = Document {
        owner_id,
        legal_hold: true,
    };

    let checker = document_checker();
    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // (subject, resource, label)
    let cases = [
        (&admin, &normal_doc, "admin, normal doc"),
        (&owner, &normal_doc, "owner, own normal doc"),
        (&admin, &held_doc, "admin, LEGAL-HOLD doc"),
        (&suspended_owner, &normal_doc, "SUSPENDED owner, own doc"),
        (&stranger, &normal_doc, "stranger, someone else's doc"),
    ];

    println!("{:<32} {:>10} forbidden by", "case", "decision");
    println!("{}", "-".repeat(60));
    for (subject, document, label) in cases {
        let decision = checker
            .bind(&session, subject, &action, &context)
            .check(document)
            .await;
        println!(
            "{label:<32} {:>10} {}",
            verdict(decision.is_granted()),
            decision.forbidden_by().unwrap_or("-"),
        );
    }

    // The grants still work where nothing blocks them.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("AdminOverride");
    checker
        .bind(&session, &owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("DocumentOwner");

    // The block rules override every grant — even the admin override.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await
        .assert_forbidden_by("LegalHold");
    checker
        .bind(&session, &suspended_owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_forbidden_by("AccountSuspended");

    // Default deny is untouched: no grant, no access — and no forbid
    // either, which `forbidden_by()` distinguishes for the caller.
    let stranger_decision = checker
        .bind(&session, &stranger, &action, &context)
        .check(&normal_doc)
        .await;
    stranger_decision.assert_denied();
    assert_eq!(stranger_decision.forbidden_by(), None);

    // Show the mechanism on the headline case: the forbid-effect policy is
    // evaluated first and ends the evaluation; the allow set is never
    // consulted.
    println!("\nWhy 'admin, LEGAL-HOLD doc' is blocked:");
    let decision = checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await;
    println!("{}", decision.display_trace());

    scoped_exclusion_demo().await;
}

// ---- scoped exclusion: a deny that gates only one grant path --------

/// `Effect::Forbid` is a *global* veto: it blocks every grant path in the
/// checker. When a block rule should only gate one grant path — here,
/// muted users lose collaborator access but owners and admins keep
/// theirs — scope it with combinators instead:
/// `AndPolicy[ grant_arm, NotPolicy(block) ]`. The block policy in this local
/// shape should be an ordinary grant-style predicate, not `.forbid()`;
/// `Forbidden` is active and would still veto globally.
async fn scoped_exclusion_demo() {
    #[derive(Debug, Clone)]
    struct Member {
        is_owner: bool,
        is_collaborator: bool,
        muted: bool,
    }
    #[derive(Debug, Clone)]
    struct Thread;

    struct ThreadDomain;

    impl PolicyDomain for ThreadDomain {
        type Subject = Member;
        type Action = Access;
        type Resource = Thread;
        type Context = ();
    }

    let owner_policy = PolicyBuilder::<ThreadDomain>::new("ThreadOwner")
        .subjects(|member| member.is_owner)
        .build();
    let collaborator_policy: Arc<dyn Policy<ThreadDomain>> = Arc::from(
        PolicyBuilder::<ThreadDomain>::new("Collaborator")
            .subjects(|member| member.is_collaborator)
            .build(),
    );
    // The block rule for the scoped case *grants when it matches* so that
    // `NotPolicy` can invert it into a local gate. Compare with the
    // checker-level rules above, where `Effect::Forbid` keeps natural
    // polarity — this inversion is the price of scoping, which is why a
    // global block should prefer `Effect::Forbid`.
    let muted = PolicyBuilder::<ThreadDomain>::new("Muted")
        .subjects(|member| member.muted)
        .build();

    let collaborator_unless_muted = AndPolicy::try_new(vec![
        collaborator_policy,
        Arc::new(NotPolicy::new(muted)) as Arc<dyn Policy<ThreadDomain>>,
    ])
    .expect("gate has the grant arm and the guard");

    let mut checker = PermissionChecker::<ThreadDomain>::named("ThreadChecker");
    checker.add_policy(owner_policy);
    checker.add_policy(collaborator_unless_muted);

    let muted_collaborator = Member {
        is_owner: false,
        is_collaborator: true,
        muted: true,
    };
    let muted_owner = Member {
        is_owner: true,
        is_collaborator: false,
        muted: true,
    };

    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // The mute only gates the collaborator path...
    checker
        .bind(&session, &muted_collaborator, &action, &context)
        .check(&Thread)
        .await
        .assert_denied();
    // ...the owner path is untouched, which a global Effect::Forbid mute
    // could not express.
    checker
        .bind(&session, &muted_owner, &action, &context)
        .check(&Thread)
        .await
        .assert_granted_by("ThreadOwner");

    println!("\nScoped exclusion: muted collaborator blocked, muted owner unaffected.");
}

Additional examples can be found in:

• examples/combinator_policy.rs
• examples/lookup_in_ram.rs

pub fn shared_empty() -> &'static Self

Returns a process-wide empty session for hot paths that never use fact sources.

This avoids allocating a new empty session for fact-free checks in tight loops. Only use it when no fact-backed policies are expected. Fact-backed paths should build a FactRegistry during application setup and call FactRegistry::session per request.

pub async fn get<K>(&self, key: K) -> FactLoadResult<K::Value>

where K: FactKey,

Loads one fact through the session cache.

Examples found in repository

examples/factsource_n_plus_one.rs (line 202)

    async fn evaluate(&self, ctx: &EvalCtx<'_, SupplierInvoiceDomain>) -> PolicyEvalResult {
        // Ask the session, not the backend service directly. The
        // first call inside this request triggers `load_many`; every
        // subsequent call with the same key (e.g. another invoice in
        // the same batch) hits the request-scoped cache.
        match ctx.session.get(CustomerForOrg(ctx.subject.org_id)).await {
            FactLoadResult::Found(Some(customer_id)) if customer_id == ctx.resource.customer_id => {
                ctx.grant("subject's supplier org bills under the invoice's customer")
            }
            _ => ctx.not_applicable(
                "subject's supplier org does not bill under the invoice's customer",
            ),
        }
    }

pub async fn get_many<K>(&self, keys: &[K]) -> Vec<FactLoadResult<K::Value>>

where K: FactKey,

Loads facts through the session cache.

Results preserve input order and duplicate keys. Missing cache entries are deduplicated before they are loaded, then chunked according to the source’s FactSource::max_batch_size hint.

Trait Implementations

impl Clone for EvaluationSession

fn clone(&self) -> EvaluationSession

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for EvaluationSession

fn default() -> EvaluationSession

Returns the “default value” for a type.