Predicates
A rule's when builds one Predicate AST — lowered to SQL for the query and matched in memory for the row — and scopes through a relation.
A rule’s when builds a Predicate: one AST the query pre-filter lowers to
SQL and the by-id check and each wire row match in memory, so the rows a query
returns and the rows a reply may answer never disagree.
Predicates — the shared AST
Section titled “Predicates — the shared AST”pub enum Predicate<E: EntityTrait> { Always, Deny, // a rejected relation: fails the build Eq(E::Column, Value), In(E::Column, Vec<Value>), Cmp(E::Column, CmpOp, Value), // Ne / Lt / Lte / Gt / Gte IsNull(E::Column, bool), // IS NULL / IS NOT NULL And(Vec<Predicate<E>>), Or(Vec<Predicate<E>>), Not(Box<Predicate<E>>), Related(RelatedPredicate), // condition on a related entity}PredicateBuilder exposes the constructors:
if let Some(user_id) = actor.sub.user_id() { ab.can(Action::Read, user::Entity).when(|p| { p.all([ p.eq(user::Column::OrgId, actor.org_id), p.any([ p.eq(user::Column::Role, "admin"), p.eq(user::Column::Id, user_id), ]), ]) });}| Builder method | Variant | Use |
|---|---|---|
p.eq(col, value) | Eq | Column equals value |
p.ne(col, value) | Cmp | Column differs from value |
p.lt / p.lte / p.gt / p.gte(col, value) | Cmp | Ordered comparison |
p.is_null(col) / p.is_not_null(col) | IsNull | Nullness test |
p.is_in(col, [v, ...]) | In | Column in list |
p.all([...]) | And | Every part matches |
p.any([...]) | Or | At least one part matches |
p.not(inner) | Not | Negation |
p.related::<R, _>(rel, |r| ...) | Related | Condition on a related entity — see below |
Predicate::Always is the default — a rule with no .when admits
every row. An empty p.any([]) matches nothing (SQL FALSE); an
empty p.all([]) matches every row (SQL TRUE). The same identities
hold for the SQL lowering and the in-memory check.
Relational scoping
Section titled “Relational scoping”Some entities carry no tenant column of their own — a message
belongs to a conversation, and the conversation carries the org_id.
p.related scopes E by a condition on a related entity R, reached
through a variant of E’s SeaORM Relation enum; the closure builds
the sub-condition with R’s own typed columns:
// `message` has no `org_id`; its tenant is the parent conversation's.ab.can(Action::Read, message::Entity).when(|p| { p.related::<conversation::Entity, _>( message::Relation::Conversation, |c| c.eq(conversation::Column::OrgId, org_id), )});The SQL lowering is a semi-join: belongs_to / has_one becomes an
uncorrelated IN (subquery), has_many a correlated EXISTS. A
relation’s custom on_condition is folded into the subquery, in parentheses
of its own, so the scope is never widened past the join, nor past what the
on_condition says.
Three checks close the gaps a rule’s text could open. A rule failing one files
one error on nest_rs::authz and fails AbilityBuilder::build, so the guard
answers 500 rather than install a silently-wrong filter:
- the relation must point at
R(its target table is checked); - the relation must be single-column — a tenant key is one column by design; denormalize it onto the child rather than scoping through a composite key;
- what the rule writes as text must stay where the scope writes it: the
relation’s
on_condition, read alone, closes every parenthesis, string and identifier it opens and holds no comment, as a raw fragment inRepo’sfiltermust, and no value it compares is an enum whose type name holds a". Itsreasonfield says which.
One consequence for the read-back path: the in-memory check cannot
traverse the relation without loading the parent, so row visibility
for a relational rule is decided in SQL everywhere — including
the by-id binding and create paths, which re-check against the same
lowered condition (see
By-id binding). Ability::can
grants nothing on a relation, and Repo::can decides it in SQL. A pushed
value went through no SQL read, so a relational grant admits none of it
(Each row is judged on its whole row).
Going further
Section titled “Going further”- Policies — the rules a predicate conditions.
- Row-level filtering — the SQL a predicate lowers to.
- Route model binding — the by-id check a relational rule decides in SQL.