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 via Self::register_arc, 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 RBAC/ABAC policies are expected and no fact sources are registered. For very hot RBAC/ABAC-only loops, use Self::shared_empty to avoid allocating a new empty session per call.

Examples found in repository

examples/factsource_n_plus_one.rs (line 237)

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::<Supplier, Invoice, ViewAction, ()>::new();
    wrong_checker.add_policy(WrongSupplierPolicy {
        hierarchy: Arc::clone(&hierarchy),
    });

    hierarchy.reset();
    let session = EvaluationSession::empty();
    let visible = wrong_checker
        .filter_authorized_in_session_by_resource(
            &session,
            &supplier,
            &ViewAction,
            invoices.clone(),
            &(),
            |i| i,
        )
        .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::<Supplier, Invoice, ViewAction, ()>::new();
    right_checker.add_policy(RightSupplierPolicy);

    hierarchy.reset();
    let load_many_calls = Arc::new(AtomicUsize::new(0));
    let session = EvaluationSession::builder()
        .with_arc::<CustomerForOrg>(Arc::new(CustomerForOrgSource {
            hierarchy: Arc::clone(&hierarchy),
            load_many_calls: Arc::clone(&load_many_calls),
        }))
        .build();
    let visible = right_checker
        .filter_authorized_in_session_by_resource(
            &session,
            &supplier,
            &ViewAction,
            invoices,
            &(),
            |i| i,
        )
        .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/lookup_in_ram.rs (line 218)

async fn main() {
    // Build a small population.
    let alice = User {
        id: Uuid::new_v4(),
        is_admin: false,
    };
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
    };
    let docs: Vec<Document> = (0..7)
        .map(|i| Document {
            id: Uuid::new_v4(),
            title: format!("doc-{i}"),
        })
        .collect();

    // Alice is a viewer of docs[1], docs[3], docs[5].
    let viewer_doc_ids: Vec<Uuid> = [&docs[1], &docs[3], &docs[5]]
        .into_iter()
        .map(|d| d.id)
        .collect();

    let viewers: HashMap<Uuid, Vec<Uuid>> = viewer_doc_ids
        .iter()
        .map(|doc_id| (*doc_id, vec![alice.id]))
        .collect();

    let viewer_lookup_index: HashMap<Uuid, Vec<Uuid>> =
        HashMap::from([(alice.id, viewer_doc_ids.clone())]);

    // Document catalog used by the hydrator. In production this is a
    // database call: `SELECT * FROM docs WHERE id = ANY($1)`.
    let catalog: Arc<HashMap<Uuid, Document>> =
        Arc::new(docs.iter().map(|d| (d.id, d.clone())).collect());

    let lookup = InMemoryViewerLookup {
        per_user: viewer_lookup_index,
    };

    // Hydrator closure: maps a slice of ids to `Vec<Option<Document>>`.
    // `None` would represent an id deleted between enumeration and the
    // catalog fetch; the in-memory catalog here always resolves.
    let hydrator = {
        let catalog = Arc::clone(&catalog);
        move |ids: &[Uuid]| {
            let catalog = Arc::clone(&catalog);
            let ids = ids.to_vec();
            async move {
                Ok::<_, std::convert::Infallible>(
                    ids.iter().map(|id| catalog.get(id).cloned()).collect(),
                )
            }
        }
    };

    // Compose policies: admin override OR viewer relation. The lookup
    // source only enumerates the viewer axis — admin overrides apply only
    // to point checks.
    let mut checker = PermissionChecker::<User, Document, View, ()>::new();
    checker.add_policy(AdminPolicy);
    checker.add_policy(ViewerPolicy { viewers });

    let session = EvaluationSession::empty();
    let page_size = NonZeroUsize::new(2).unwrap();

    // (1) Alice lists her visible documents via lookup_authorized.
    let alice_visible = checker
        .lookup_authorized(&session, &alice, &View, &(), &lookup, page_size, &hydrator)
        .await
        .expect("lookup ok");
    println!("Alice sees {} document(s):", alice_visible.len());
    for doc in &alice_visible {
        println!("  - {} ({})", doc.title, doc.id);
    }
    let alice_visible_ids: Vec<Uuid> = alice_visible.iter().map(|doc| doc.id).collect();
    assert_eq!(
        alice_visible_ids, viewer_doc_ids,
        "the lookup + policy stack should authorize exactly the viewer-granted documents, in source order"
    );

    // (2) Admin lists "their visible documents" via the same lookup.
    // The viewer lookup does not enumerate documents for the admin (no
    // viewer relation), so this listing returns empty — correctly,
    // because lookup is bounded by what it enumerates. To enumerate
    // "everything an admin can see", the production code would either
    // route admin requests to a different source or simply skip the
    // lookup path and list directly.
    let admin_via_lookup = checker
        .lookup_authorized(&session, &admin, &View, &(), &lookup, page_size, &hydrator)
        .await
        .expect("lookup ok");
    println!(
        "\nAdmin via the viewer-lookup sees {} document(s) — this is bounded \
         by what the source enumerates; admin grants still apply at point checks.",
        admin_via_lookup.len()
    );
    assert!(
        admin_via_lookup.is_empty(),
        "the viewer lookup enumerates nothing for the admin, so the listing is empty"
    );

    // (3) Point check confirms the admin policy is alive: pick a document
    // the admin has no viewer relation on.
    let any_doc = &docs[0];
    let admin_point = checker
        .evaluate_in_session(&session, &admin, &View, any_doc, &())
        .await;
    println!(
        "\nAdmin point check on '{}': {}",
        any_doc.title,
        if admin_point.is_granted() {
            "Granted"
        } else {
            "Denied"
        }
    );
    admin_point.assert_granted_by("AdminPolicy");

    // (4) Page-oriented streaming. Drive the lookup one candidate page at
    // a time — useful when you want to flush results to a response writer
    // as they are confirmed.
    println!("\nStreaming Alice's visible documents page-by-page:");
    let mut cursor: Option<Vec<u8>> = None;
    let mut page_index = 0;
    let mut streamed_total = 0;
    loop {
        let page = checker
            .lookup_authorized_page(
                &session,
                &alice,
                &View,
                &(),
                &lookup,
                cursor.as_deref(),
                page_size,
                &hydrator,
            )
            .await
            .expect("lookup_authorized_page ok");
        println!("  page {page_index}: {} authorized", page.resources.len());
        page_index += 1;
        streamed_total += page.resources.len();
        match page.next_cursor {
            None => break,
            Some(next) => cursor = Some(next),
        }
    }
    // 3 candidate ids paged 2-at-a-time: two candidate pages, same total as
    // the collecting `lookup_authorized` call above.
    assert_eq!(page_index, 2);
    assert_eq!(streamed_total, viewer_doc_ids.len());
}

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 RBAC/ABAC-only checks in tight loops. It is only safe when no fact-backed policies are expected: calling Self::register, Self::register_arc, Self::replace, or Self::replace_arc on this session panics.

The panic is deliberate. Registering on the shared handle is a programming error, not a runtime condition — code that registers sources should own a Self::new session, and this handle exists only for fact-free hot paths. The non-panicking Self::try_register / Self::try_replace family still returns FactSourceRegistrationError::SharedEmptySession here rather than panicking, for callers that want to handle it. A type-state split (a separate “registrable” type) was considered but would push that distinction into every signature that accepts a &EvaluationSession, defeating the drop-in substitutability that makes this handle useful.

pub fn builder() -> EvaluationSessionBuilder

Starts building a request-scoped session with all fact sources declared in one place.

Examples found in repository

examples/actix_web.rs (line 241)

    fn request_session(&self) -> EvaluationSession {
        EvaluationSession::builder()
            .with_arc::<PostRelationship>(Arc::clone(&self.relationships))
            .build()
    }

examples/postgres_bulk_rebac.rs (line 158)

fn session_with(source: &Arc<dyn FactSource<RelationshipKey>>) -> EvaluationSession {
    EvaluationSession::builder()
        .with_arc::<RelationshipKey>(Arc::clone(source))
        .build()
}

examples/axum.rs (line 252)

    fn request_session(&self) -> EvaluationSession {
        EvaluationSession::builder()
            .with_arc::<InvoiceRelationship>(Arc::clone(&self.invoice_relationships))
            .build()
    }

examples/in_ram_rebac.rs (line 74)

fn request_session(relationships: &Arc<dyn FactSource<RelationshipKey>>) -> EvaluationSession {
    EvaluationSession::builder()
        .with_arc::<RelationshipKey>(Arc::clone(relationships))
        .build()
}

examples/factsource_n_plus_one.rs (line 269)

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::<Supplier, Invoice, ViewAction, ()>::new();
    wrong_checker.add_policy(WrongSupplierPolicy {
        hierarchy: Arc::clone(&hierarchy),
    });

    hierarchy.reset();
    let session = EvaluationSession::empty();
    let visible = wrong_checker
        .filter_authorized_in_session_by_resource(
            &session,
            &supplier,
            &ViewAction,
            invoices.clone(),
            &(),
            |i| i,
        )
        .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::<Supplier, Invoice, ViewAction, ()>::new();
    right_checker.add_policy(RightSupplierPolicy);

    hierarchy.reset();
    let load_many_calls = Arc::new(AtomicUsize::new(0));
    let session = EvaluationSession::builder()
        .with_arc::<CustomerForOrg>(Arc::new(CustomerForOrgSource {
            hierarchy: Arc::clone(&hierarchy),
            load_many_calls: Arc::clone(&load_many_calls),
        }))
        .build();
    let visible = right_checker
        .filter_authorized_in_session_by_resource(
            &session,
            &supplier,
            &ViewAction,
            invoices,
            &(),
            |i| i,
        )
        .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/rebac_policy.rs (line 148)

async fn main() {
    println!("=== ReBAC Policy Example ===\n");

    let owner = User {
        id: Uuid::new_v4(),
        name: "Alice",
    };
    let contributor = User {
        id: Uuid::new_v4(),
        name: "Bob",
    };
    let viewer = User {
        id: Uuid::new_v4(),
        name: "Charlie",
    };
    let outsider = User {
        id: Uuid::new_v4(),
        name: "Dave",
    };
    let project = Project {
        id: Uuid::new_v4(),
        name: "Sample Project",
    };

    let relationships = HashSet::from([
        ProjectRelationship {
            subject_id: owner.id,
            resource_id: project.id,
            relation: Relation::Owner,
        },
        ProjectRelationship {
            subject_id: contributor.id,
            resource_id: project.id,
            relation: Relation::Contributor,
        },
        ProjectRelationship {
            subject_id: viewer.id,
            resource_id: project.id,
            relation: Relation::Viewer,
        },
    ]);

    let session = EvaluationSession::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships.clone()))
        .build();

    // Editing requires an owner OR contributor relationship; a viewer
    // relationship exists in the store but grants nothing here.
    let mut checker = PermissionChecker::<User, Project, EditAction, ()>::new();
    checker.add_policy(RebacPolicy::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Owner,
    ));
    checker.add_policy(RebacPolicy::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Contributor,
    ));

    // (user, relationship held, expected outcome)
    let cases = [
        (&owner, "owner", true),
        (&contributor, "contributor", true),
        (&viewer, "viewer", false),
        (&outsider, "none", false),
    ];
    for (user, held, expected_granted) in cases {
        println!("Can {} ({held}) edit {}?", user.name, project.name);
        let decision = checker
            .evaluate_in_session(&session, user, &EditAction, &project, &())
            .await;
        println!(
            "  -> {}\n",
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // The trace records the facts each policy consulted (the `↳ fact` lines)
    // alongside its decision — here the viewer's denial shows both
    // relationship lookups coming back false. Note that no new "loading fact"
    // lines appear: this re-check runs in the same session, so the facts come
    // from the session cache.
    println!("Why {} is denied:", viewer.name);
    let decision = checker
        .evaluate_in_session(&session, &viewer, &EditAction, &project, &())
        .await;
    println!("{}\n", decision.display_trace());

    println!("=== Error During Relationship Loading ===\n");

    // A failing store must never grant: the load error is carried into the
    // trace and the decision fails closed to denial — even for the owner.
    let error_session = EvaluationSession::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships).with_error())
        .build();
    let decision = checker
        .evaluate_in_session(&error_session, &owner, &EditAction, &project, &())
        .await;
    println!("{}", decision.display_trace());
    decision.assert_denied();
    decision.assert_trace_contains("simulated relationship store error");
}

pub fn register<K, S>(&self, source: S)

where K: FactKey, S: FactSource<K> + 'static,

Registers a fact source for one key type.

Panics if a source for K is already registered. Use Self::replace when replacing a source is intentional. Register sources during session setup; registering while loads for the same key type are in flight is not a supported operation and will panic.

This panicking form is meant for session setup, where a failed registration (a duplicate source, or a load already in flight) is a configuration bug that should fail loudly and immediately. Use Self::try_register when registration is driven by runtime input and you want to handle FactSourceRegistrationError rather than panic.

pub fn register_arc<K>(&self, source: Arc<dyn FactSource<K>>)

where K: FactKey,

Registers a shared fact source for one key type.

Panics if a source for K is already registered. Register sources during session setup; use Self::replace_arc only when overwriting is deliberate. Registering while loads for the same key type are in flight is not a supported operation and will panic.

Use this form to share one source instance across many sessions: build the Arc once and Arc::clone it into each request’s session (see EvaluationSessionBuilder::with_arc). Self::register takes the source by value and wraps it in a fresh Arc per call, so it cannot share a single instance; reach for register_arc when the source holds expensive shared state such as a connection pool or its own cache. Like Self::register, it panics on invalid registration; use Self::try_register_arc to handle the error instead.

The registry is keyed by the exact Rust fact key type. If two production backends serve the same logical shape, such as the same RelationshipQuery<UserId, ConversationId, ParticipantRelation>, they cannot both be registered under that exact type in one session. Wrap one ID/relation type or define distinct fact keys so each backend has a separate registry entry.

pub fn try_register<K, S>( &self, source: S, ) -> Result<(), FactSourceRegistrationError>

where K: FactKey, S: FactSource<K> + 'static,

Registers a fact source for one key type, returning an error instead of panicking if registration is invalid.

pub fn try_register_arc<K>( &self, source: Arc<dyn FactSource<K>>, ) -> Result<(), FactSourceRegistrationError>

where K: FactKey,

Registers a shared fact source for one key type, returning an error instead of panicking if registration is invalid.

pub fn replace<K, S>(&self, source: S)

where K: FactKey, S: FactSource<K> + 'static,

Explicitly replaces a fact source for one key type.

Replacing a source clears any cached facts for that key type in this session. Replacing while loads for the same key type are in flight is not a supported operation and will panic.

pub fn replace_arc<K>(&self, source: Arc<dyn FactSource<K>>)

where K: FactKey,

Explicitly replaces a shared fact source for one key type.

Replacing a source clears any cached facts for that key type in this session. Replacing while loads for the same key type are in flight is not a supported operation and will panic.

pub fn try_replace<K, S>( &self, source: S, ) -> Result<(), FactSourceRegistrationError>

where K: FactKey, S: FactSource<K> + 'static,

Explicitly replaces a fact source for one key type, returning an error instead of panicking if replacement is invalid.

pub fn try_replace_arc<K>( &self, source: Arc<dyn FactSource<K>>, ) -> Result<(), FactSourceRegistrationError>

where K: FactKey,

Explicitly replaces a shared fact source for one key type, returning an error instead of panicking if replacement is invalid.

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 197)

    async fn evaluate(
        &self,
        ctx: &EvalCtx<'_, Supplier, Invoice, ViewAction, ()>,
    ) -> 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.deny("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.