Skip to content

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.

nest_rs::authz::Predicate
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:

crates/features/src/authz/ability.rs
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 methodVariantUse
p.eq(col, value)EqColumn equals value
p.ne(col, value)CmpColumn differs from value
p.lt / p.lte / p.gt / p.gte(col, value)CmpOrdered comparison
p.is_null(col) / p.is_not_null(col)IsNullNullness test
p.is_in(col, [v, ...])InColumn in list
p.all([...])AndEvery part matches
p.any([...])OrAt least one part matches
p.not(inner)NotNegation
p.related::<R, _>(rel, |r| ...)RelatedCondition 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.

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:

crates/features/src/authz/ability.rs
// `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 in Repo’s filter must, and no value it compares is an enum whose type name holds a ". Its reason field 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).