Struct BoundEvaluator 

pub struct BoundEvaluator<'a, D: PolicyDomain> { /* private fields */ }

A request-bound evaluator for one checker, subject, action, context, and evaluation session.

Implementations

impl<'a, D: PolicyDomain> BoundEvaluator<'a, D>

pub async fn check(&self, resource: &D::Resource) -> AccessEvaluation

Evaluates one resource.

Examples found in repository

examples/actix_web.rs (line 470)

pub async fn view_post(
    path: web::Path<Uuid>,
    req: HttpRequest,
    AuthenticatedUser(user): AuthenticatedUser,
    state: web::Data<AppState>,
) -> impl Responder {
    let post = load_post(&state, *path, &PostOverrides::from_request(&req));
    let session = state.request_session();
    let context = RequestContext::now();

    match state
        .checker
        .bind(&session, &user, &Action::View, &context)
        .check(&post)
        .await
    {
        AccessEvaluation::Granted { .. } => {
            HttpResponse::Ok().body(format!("Viewing '{}'", post.title))
        }
        AccessEvaluation::Denied { reason, trace } => forbidden(&reason, &trace),
        _ => HttpResponse::Forbidden().body("Access denied"),
    }
}

pub async fn edit_post(
    path: web::Path<Uuid>,
    req: HttpRequest,
    AuthenticatedUser(user): AuthenticatedUser,
    state: web::Data<AppState>,
) -> impl Responder {
    let post = load_post(&state, *path, &PostOverrides::from_request(&req));
    let session = state.request_session();
    let context = RequestContext::now();

    match state
        .checker
        .bind(&session, &user, &Action::Edit, &context)
        .check(&post)
        .await
    {
        AccessEvaluation::Granted { .. } => HttpResponse::Ok().body("Post updated"),
        AccessEvaluation::Denied { reason, trace } => forbidden(&reason, &trace),
        _ => HttpResponse::Forbidden().body("Access denied"),
    }
}

pub async fn publish_post(
    path: web::Path<Uuid>,
    req: HttpRequest,
    AuthenticatedUser(user): AuthenticatedUser,
    state: web::Data<AppState>,
) -> impl Responder {
    let post = load_post(&state, *path, &PostOverrides::from_request(&req));
    let session = state.request_session();
    let context = RequestContext::now();

    match state
        .checker
        .bind(&session, &user, &Action::Publish, &context)
        .check(&post)
        .await
    {
        AccessEvaluation::Granted { .. } => HttpResponse::Ok().body("Post published"),
        AccessEvaluation::Denied { reason, trace } => forbidden(&reason, &trace),
        _ => HttpResponse::Forbidden().body("Access denied"),
    }
}

examples/axum.rs (line 399)

pub async fn view_invoice_handler(
    Path(invoice_id): Path<Uuid>,
    State(state): State<AppState>,
    AuthenticatedUser(user): AuthenticatedUser,
    overrides: InvoiceOverrides,
) -> impl IntoResponse {
    // Simulate a DB fetch.
    let invoice = overrides.build_invoice(invoice_id);
    let session = state.request_session();
    let context = RequestContext::now();

    if state
        .checker
        .bind(&session, &user, &Action::View, &context)
        .check(&invoice)
        .await
        .is_granted()
    {
        (StatusCode::OK, format!("{invoice:?}")).into_response()
    } else {
        (
            StatusCode::FORBIDDEN,
            "You are not authorized to view this invoice",
        )
            .into_response()
    }
}

pub async fn list_invoices_handler(
    State(state): State<AppState>,
    AuthenticatedUser(user): AuthenticatedUser,
) -> impl IntoResponse {
    let session = state.request_session();
    let candidates = state.invoices.as_ref().clone();
    let context = RequestContext::now();

    // The session is request-scoped: app state owns the source, this request
    // registers it, and the batch authorization call uses it for every invoice
    // — relationship loads are batched and deduplicated.
    let visible = state
        .checker
        .bind(&session, &user, &Action::View, &context)
        .filter(candidates)
        .await
        .into_iter()
        .map(InvoiceSummary::from)
        .collect::<Vec<_>>();

    Json(visible).into_response()
}

pub async fn edit_invoice_handler(
    Path(invoice_id): Path<Uuid>,
    State(state): State<AppState>,
    AuthenticatedUser(user): AuthenticatedUser,
    overrides: InvoiceOverrides,
) -> impl IntoResponse {
    let invoice = overrides.build_invoice(invoice_id);
    let session = state.request_session();
    let context = RequestContext::now();

    if state
        .checker
        .bind(&session, &user, &Action::Edit, &context)
        .check(&invoice)
        .await
        .is_granted()
    {
        (StatusCode::OK, "Invoice edited successfully").into_response()
    } else {
        (
            StatusCode::FORBIDDEN,
            "You are not authorized to edit this invoice",
        )
            .into_response()
    }
}

examples/delegating_policy.rs (line 183)

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

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

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

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());
}

Additional examples can be found in:

• examples/in_ram_rebac.rs
• examples/deny_override.rs
• examples/rebac_policy.rs
• examples/combinator_policy.rs
• examples/lookup_in_ram.rs
• examples/postgres_bulk_rebac.rs

pub async fn evaluate<I>( &self, resources: I, ) -> Vec<(I::Item, AccessEvaluation)>

where I: IntoIterator, I::Item: Borrow<D::Resource>,

Evaluates a batch of already-loaded resources, preserving input order.

pub async fn evaluate_by<I, F>( &self, items: I, resource_of: F, ) -> Vec<(I::Item, AccessEvaluation)>

where I: IntoIterator, F: for<'item> Fn(&'item I::Item) -> &'item D::Resource,

Evaluates a batch of caller-owned items by projecting each item to the resource used for authorization.

Use this for list endpoints that carry wide database rows but authorize a narrower resource projection:

let decisions = bound.evaluate_by(rows, |row| &row.authz_resource).await;

pub async fn filter<I>(&self, resources: I) -> Vec<I::Item>

where I: IntoIterator, I::Item: Borrow<D::Resource>,

Returns only the resources granted by Self::evaluate.

Examples found in repository

examples/actix_web.rs (line 450)

pub async fn list_posts(
    AuthenticatedUser(user): AuthenticatedUser,
    state: web::Data<AppState>,
) -> impl Responder {
    let session = state.request_session();
    let context = RequestContext::now();
    let candidates = state.posts.as_ref().clone();

    let visible = state
        .checker
        .bind(&session, &user, &Action::View, &context)
        .filter(candidates)
        .await;

    let summaries = visible.iter().map(PostSummary::from).collect::<Vec<_>>();
    HttpResponse::Ok().json(summaries)
}

examples/axum.rs (line 427)

pub async fn list_invoices_handler(
    State(state): State<AppState>,
    AuthenticatedUser(user): AuthenticatedUser,
) -> impl IntoResponse {
    let session = state.request_session();
    let candidates = state.invoices.as_ref().clone();
    let context = RequestContext::now();

    // The session is request-scoped: app state owns the source, this request
    // registers it, and the batch authorization call uses it for every invoice
    // — relationship loads are batched and deduplicated.
    let visible = state
        .checker
        .bind(&session, &user, &Action::View, &context)
        .filter(candidates)
        .await
        .into_iter()
        .map(InvoiceSummary::from)
        .collect::<Vec<_>>();

    Json(visible).into_response()
}

examples/factsource_n_plus_one.rs (line 247)

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/in_ram_rebac.rs (line 132)

async fn main() {
    let user = User { id: Uuid::new_v4() };
    let documents = vec![
        Document {
            id: Uuid::new_v4(),
            title: "roadmap",
        },
        Document {
            id: Uuid::new_v4(),
            title: "incident report",
        },
        Document {
            id: Uuid::new_v4(),
            title: "finance plan",
        },
    ];

    let store = Arc::new(InRamRelationships::default());
    store.grant(user.id, documents[0].id, Relation::Viewer);
    store.grant(user.id, documents[1].id, Relation::Viewer);
    // The store can hold more relation types than any one policy consumes. This
    // editor grant is never matched below (the checker only asks about Viewer),
    // and is here to show the source and the policy stack are decoupled.
    store.grant(user.id, documents[1].id, Relation::Editor);
    let relationships: Arc<dyn FactSource<RelationshipKey>> = store;
    let registry = FactRegistry::builder()
        .with_arc::<RelationshipKey>(Arc::clone(&relationships))
        .build();

    let checker = build_checker();
    let context = ();

    let first_request = request_session(&registry);
    let visible = checker
        .bind(&first_request, &user, &View, &context)
        .filter(documents.clone())
        .await;
    println!(
        "batch list — visible documents: {:?}",
        visible
            .iter()
            .map(|document| document.title)
            .collect::<Vec<_>>()
    );

    // A fresh session for a single-resource check. The user has no viewer
    // relationship on the finance plan, so this denies.
    let second_request = request_session(&registry);
    let can_view_finance = checker
        .bind(&second_request, &user, &View, &context)
        .check(&documents[2])
        .await;
    println!(
        "single check — can view '{}'? {}",
        documents[2].title,
        if can_view_finance.is_granted() {
            "yes"
        } else {
            "no"
        }
    );
    assert!(!can_view_finance.is_granted());

    let shared = registry.clone();
    let concurrent_requests = (0..4)
        .map(|_| {
            let checker = checker.clone();
            let user = user.clone();
            let documents = documents.clone();
            let registry = shared.clone();
            tokio::spawn(async move {
                let session = request_session(&registry);
                let context = ();
                checker
                    .bind(&session, &user, &View, &context)
                    .filter(documents)
                    .await
                    .len()
            })
        })
        .collect::<Vec<_>>();

    println!("\n4 concurrent requests sharing one FactSource (each builds its own session):");
    for (index, request) in concurrent_requests.into_iter().enumerate() {
        let visible_count = request.await.unwrap();
        println!("  request {index}: {visible_count} visible document(s)");
        assert_eq!(visible_count, 2);
    }
}

examples/postgres_bulk_rebac.rs (line 337)

async fn main() {
    let database_url = std::env::var("DATABASE_URL").unwrap_or_else(|_| {
        "host=localhost port=15432 user=postgres password=test dbname=awa_test".to_string()
    });

    let (client, connection) = tokio_postgres::connect(&database_url, NoTls)
        .await
        .expect("connect to PostgreSQL");
    tokio::spawn(async move {
        if let Err(error) = connection.await {
            eprintln!("postgres connection error: {error}");
        }
    });
    let client = Arc::new(client);

    let version: String = client
        .query_one("SELECT version()", &[])
        .await
        .expect("version query should succeed")
        .get(0);
    println!("{version}");

    client
        .batch_execute(
            "
            DROP TABLE IF EXISTS gatehouse_example_post_relationships;
            CREATE UNLOGGED TABLE gatehouse_example_post_relationships (
                subject_id uuid NOT NULL,
                post_id uuid NOT NULL,
                relationship text NOT NULL,
                PRIMARY KEY (subject_id, post_id, relationship)
            );
            ",
        )
        .await
        .expect("setup schema");

    let subject = User { id: Uuid::new_v4() };
    let posts = (0..10_000)
        .map(|index| Post {
            id: Uuid::new_v4(),
            public: index % 5 == 0,
        })
        .collect::<Vec<_>>();
    let granted_ids = posts
        .iter()
        .enumerate()
        .filter_map(|(index, post)| (!post.public && index % 2 == 0).then_some(post.id))
        .collect::<Vec<_>>();
    let relationships = vec![Relation::Viewer.as_str(); granted_ids.len()];
    let subject_ids = vec![subject.id; granted_ids.len()];

    client
        .execute(
            "
            INSERT INTO gatehouse_example_post_relationships (subject_id, post_id, relationship)
            SELECT *
            FROM unnest($1::uuid[], $2::uuid[], $3::text[])
            ",
            &[&subject_ids, &granted_ids, &relationships],
        )
        .await
        .expect("seed grants");

    let point_stmt = Arc::new(
        client
            .prepare(
                "
                SELECT EXISTS (
                    SELECT 1
                    FROM gatehouse_example_post_relationships
                    WHERE subject_id = $1
                      AND relationship = $2
                      AND post_id = $3
                ) AS allowed
                ",
            )
            .await
            .expect("prepare point query"),
    );
    let bulk_stmt = Arc::new(
        client
            .prepare(
                "
                WITH candidate_relationships AS (
                    SELECT subject_id, post_id, relationship, ord
                    FROM unnest($1::uuid[], $2::uuid[], $3::text[])
                        WITH ORDINALITY AS input(subject_id, post_id, relationship, ord)
                )
                SELECT
                    COALESCE(bool_or(g.post_id IS NOT NULL), false) AS allowed
                FROM candidate_relationships c
                LEFT JOIN gatehouse_example_post_relationships g
                  ON g.subject_id = c.subject_id
                 AND g.relationship = c.relationship
                 AND g.post_id = c.post_id
                GROUP BY c.ord, c.subject_id, c.post_id, c.relationship
                ORDER BY c.ord
                ",
            )
            .await
            .expect("prepare bulk query"),
    );

    let source = Arc::new(PgRelationshipSource {
        client,
        point_stmt,
        bulk_stmt,
    });
    assert_point_and_bulk_agree(
        &source,
        &[
            RelationshipQuery {
                subject_id: subject.id,
                resource_id: posts
                    .iter()
                    .find(|post| granted_ids.contains(&post.id))
                    .expect("fixture should include a granted private post")
                    .id,
                relation: Relation::Viewer,
            },
            RelationshipQuery {
                subject_id: subject.id,
                resource_id: posts
                    .iter()
                    .enumerate()
                    .find(|(index, post)| !post.public && index % 2 == 1)
                    .expect("fixture should include a denied private post")
                    .1
                    .id,
                relation: Relation::Viewer,
            },
        ],
    )
    .await;
    let source: Arc<dyn FactSource<RelationshipKey>> = source;
    let checker = build_checker();

    println!("size,relationship_checks,naive_ms,bulk_ms,allowed,improvement");
    for &size in &[10usize, 100, 1_000, 5_000, 10_000] {
        let sample = posts.iter().take(size).cloned().collect::<Vec<_>>();
        let relationship_checks = sample.iter().filter(|post| !post.public).count();
        let naive = measure(|| async {
            let mut allowed = 0usize;
            for post in &sample {
                let session = session_with(&source);
                if checker
                    .bind(&session, &subject, &View, &())
                    .check(post)
                    .await
                    .is_granted()
                {
                    allowed += 1;
                }
            }
            allowed
        })
        .await;

        let bulk = measure(|| async {
            let session = session_with(&source);
            checker
                .bind(&session, &subject, &View, &())
                .filter(sample.clone())
                .await
                .len()
        })
        .await;

        assert_eq!(naive.output, bulk.output);
        println!(
            "{size},{relationship_checks},{:.3},{:.3},{},x{:.1}",
            naive.elapsed.as_secs_f64() * 1_000.0,
            bulk.elapsed.as_secs_f64() * 1_000.0,
            bulk.output,
            naive.elapsed.as_secs_f64() / bulk.elapsed.as_secs_f64()
        );
    }
}

pub async fn filter_by<I, F>(&self, items: I, resource_of: F) -> Vec<I::Item>

where I: IntoIterator, F: for<'item> Fn(&'item I::Item) -> &'item D::Resource,

Returns only the caller-owned items granted by Self::evaluate_by.

The returned values are the original input items, not cloned projected resources.

pub async fn lookup_page<L, H>( &self, lookup: &L, hydrator: &H, cursor: Option<&[u8]>, limit: NonZeroUsize, ) -> Result<LookupAuthorizedPage<D::Resource>, LookupAuthorizedError<L::Error, H::Error>>

where L: LookupSource<D>, H: Hydrator<L::Id, Resource = D::Resource>,

Looks up one candidate page, hydrates it, and returns authorized resources from that page.

Examples found in repository

examples/lookup_in_ram.rs (line 178)

async fn collect_authorized<H>(
    checker: &PermissionChecker<DocumentDomain>,
    session: &EvaluationSession,
    subject: &User,
    lookup: &InMemoryViewerLookup,
    page_size: NonZeroUsize,
    hydrator: &H,
) -> Result<Vec<Document>, gatehouse::LookupAuthorizedError<ViewerLookupError, H::Error>>
where
    H: gatehouse::Hydrator<Uuid, Resource = Document>,
{
    let mut cursor: Option<Vec<u8>> = None;
    let mut authorized = Vec::new();
    let bound = checker.bind(session, subject, &View, &());
    loop {
        let page = bound
            .lookup_page(lookup, hydrator, cursor.as_deref(), page_size)
            .await?;
        authorized.extend(page.resources);
        match page.next_cursor {
            Some(next) => cursor = Some(next),
            None => return Ok(authorized),
        }
    }
}

// --- Wiring + main -----------------------------------------------------

#[tokio::main]
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::<DocumentDomain>::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 by collecting lookup pages.
    let alice_visible =
        collect_authorized(&checker, &session, &alice, &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 =
        collect_authorized(&checker, &session, &admin, &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
        .bind(&session, &admin, &View, &())
        .check(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;
    let alice_bound = checker.bind(&session, &alice, &View, &());
    loop {
        let page = alice_bound
            .lookup_page(&lookup, &hydrator, cursor.as_deref(), page_size)
            .await
            .expect("lookup_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 helper loop above.
    assert_eq!(page_index, 2);
    assert_eq!(streamed_total, viewer_doc_ids.len());
}