Module eval 

Evaluating a ruleset for one request: what the evaluator takes and what it decides.

authorize finds the allow statements that apply to the request and evaluates their conditions. What the official emulator does, as measured with tools/oracle/rules_conditions.py (results/rules-conditions-official-v1.22.0.json) and tools/oracle/rules_eval.py (tests/fixtures/rules_eval.json):

• Types are checked when a condition runs. Each operator, function and method takes the types its error lists (Unsupported operation error. Received: list + list. Expected: int + int, …); a method a type does not have is a Function not found error.
• Errors are absorbed the CEL way: error || true and true || error are true, error && false and false && error are false, anything else with an error is the error. An error that reaches the top of a condition denies, like false.
• == between values of different types is false; an int equals a float of the same value, but not inside lists and maps. Sets and map diffs compare numbers by value at any depth.
• Strings are Java strings: sizes, indexes and slices count UTF-16 code units, lower() and upper() change ASCII letters only, and regular expressions are RE2.
• The operands of an operator, a call or a list or map literal are all evaluated, the last first (as debug() shows), and the first error in order wins (for x in y, y‘s; for a method, a null receiver or a method it does not have comes before its arguments’ errors).
• The arguments of a function (the last first), then its lets in order, are evaluated before its result, but an error in one only matters if the function uses it.

Each condition is evaluated once, so a denial lists each statement once; the official emulator evaluates again after an error and lists everything twice (docs/parity-exceptions.md).

authorize_traced also reports what the official emulator logs and counts for its coverage report (tools/oracle/rules_coverage.py, Trace): each debug() value, and what each expression evaluated to. Which statements it evaluates shows there: those of every match covering the path, each match’s until one allows.

Structs

Auth

request.auth for a caller with a token.

Budget

The lookups a request may still make (tools/oracle/rules_lookups.py): a single read or write may look up 10 distinct documents, a query 20, and a batch 10 per write and 20 in all. A document looked up again costs nothing, across the writes of a batch too, and so does the document a request reads or writes and every document its batch writes (tools/oracle/rules_eval.py).

Document

A document as resource, request.resource and get() give it.

Query

request.query for a list, and the filter that decides it.

Request

One request, as rules see it.

Timestamp

Trace

What one decision reports besides the decision: the value of each debug() call, in order, and, when values are traced (Trace::with_values), what each expression of the coverage report evaluated to, for crate::coverage::Coverage::record.

Enums

Comparator

How a filter of a constraint compares.

Decision

What the rules decided.

Filter

A query’s filter.

FilterOp

KeyStatus

What a.diff(b) says of a key.

Method

The method a request is checked against. read covers get and list, write covers create, update and delete.

Observed

A value as debug() logs it and the coverage report counts it: the official emulator’s value message, which also holds what only rules compute (sets, map diffs, constraints) and the path segments a list does not know.

Outcome

What an expression of the coverage report evaluated to once.

Segment

A segment of a path: a name, or what a list does not know, one document ID (capture) or any number of segments (glob_capture).

Value

A value as rules see it. Firestore values convert to these (timestamp, bytes, latlng, a reference as a path, maps and lists); the others only come from rules.

Traits

Documents

The documents get() / exists() read (as they were before the request’s writes) and getAfter() / existsAfter() read (as they would be after all of them).

Functions

authorize

Decides one request against ruleset (the cloud.firestore service). resource is the stored document (None if it does not exist, or for a list). The rules’ version decides how recursive wildcards match.

authorize_traced

authorize, reporting into trace what the conditions evaluated.

java_double

A float as Java’s Double.toString writes it: 1.0, 0.001, 1.0E7, 1.0E-4, Infinity, NaN, with the shortest digits that read back the same.

Type Aliases

Map

A map’s entries, in the order the document or the literal holds them. Equality ignores the order; where rules list keys in another order, the evaluator sorts.