cel-dart

This project parses and evaluates Common Expression Language (CEL) programs against some inputs. For example, based on the code request.auth.claims.group=='admin' and a request object as input, the library will evaluate whether the statement is true or false. CEL (see the spec) is a language used by many security projects such as Firestore and Firebase Storage. This project is a simplified port of https://github.com/google/cel-go.

Usage

import 'package:cel/cel.dart';

void main() {
  final input = "request.auth.claims.group == 'admin'";
  final e = Environment.standard();
  final ast = e.compile(input);
  final p = e.makeProgram(ast);
  print(p.evaluate({
    'request': {
      'auth': {
        'claims': {'group': 'admin'}
      }
    }
  }));
}

Prints out true.

Differences with cel-go

The main difference is that cel-go supports checking types at compilation time, whereas we throw runtime errors at evaluation time. Also we don't support the timestamps nor durations Protobufs, type conversions and the type keyword.

Features

This table is based on https://github.com/google/cel-spec/blob/master/doc/langdef.md.

Operators

This table comes from https://firebase.google.com/docs/rules/rules-language#operators_and_operator_precedence.

Functions

From https://github.com/google/cel-spec/blob/master/doc/langdef.md#functions.

Additional information

If you are curious how it was made, or want to contribute, you may find this reading list useful:

• https://firebase.google.com/docs/rules
• https://codelabs.developers.google.com/codelabs/cel-go/
• CEL language definition
• Expr protobuf
• https://github.com/google/cel-go

Architecture

Here's the mechanism from CEL code (a String) to evaluation:

1. The user instantiates an [Environment]. In cel-go, they can pass some environment variables. We have skipped porting this so far.
2. The user calls [Environment.compile] with CEL code (a String), and gets back an Abstract Syntax Tree (AST).
   1. Under the hood, [Environment.compile] relies on [Parser], which itself uses [CELParser], an ANTLR generated Parser for CEL.
   2. [CELParser] converts the CEL code into a CEL tree (a [StartContext]).
   3. Then Parser traverses the CEL tree into an [Expr], which is the actual AST.
   4. Finally Environment wraps the [Expr] into an [Ast].
3. The user instantiates a [Program] by passing the Environment and the AST. Upon initialization, the Program calls [Planner.plan], which traverses the AST and converts it into an [Interpretable] for later use.
4. Whenever the user wants to evaluate the Program, they call [Program.evaluate] with some inputs (eg a [Map]), and get a value as a result. It evaluates the Interpretable using the inputs into a return value.

The meat of the code is in [Parser.visit] and [Planner.plan].

Implementation details

• Difference between [Value.value] and [Value.convertToNative]: While both are the same in the case of primitive wrappers such as [IntValue], [DoubleValue]... they are different for [ListValue] and [MapValue]. For example for a [ListValue], [ListValue.value] is a List<Value>, while [Value.convertToNative] will return List<non-Value type>.
• environmentOptions and standardDeclarations don't actually do anything yet. In the future, they may be used to check whether some function has indeed been declared in Interpretable.planCall when it calls resolveFunction. Doing so might help throw an Exception early if the function name is not an declared function.
• In cel-go, Parser.visit returns any. In cel-dart, we return Expr, making it more type safe.
• How does a in b get processed? in is listed in standardOverloads. It is used in StdLibrary to add them to the Dispatcher during initialization. During evaluation, the planner finds the Overload implementation by calling Dispatcher.findOverload. Eventually, the CallExpr('@in') calls the [Overload] implementation with the call to contains.
• In cel-go defines the Expr architecture with Protobuf, while this project defines Expr as native Dart. This is mostly to save time by avoiding a lot of boilerplate code. We might integrate Protobuf later if the need arises.