패키지, 저장소 및 앱 카테고리 검색

패키지 상세v0.6.1

cel

이 프로젝트는 입력값에 대해 공통 표현 언어(CEL) 프로그램을 분석하고 평가합니다.

30일 다운로드
23.2만
좋아요
6
Pub 점수
140

패키지 설치

flutter pub add cel

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

cel 패키지는 Dart 애플리케이션 내에서 일반 표현식 언어(CEL) 식을 파싱하고 평가할 수 있도록 합니다. 구조화된 입력 데이터를 사용하여 런타임에 논리적, 산술적, 조건부 식을 동적으로 평가할 수 있습니다. 이는 앱에서 유연한 규칙 엔진, 구성 검증 또는 정책 확인을 구현하는 데 특히 유용합니다. 패키지는 변수, 함수, 타입 체크와 같은 광범위한 CEL 기능을 지원하며, 식의 안전한 실행을 보장합니다. pub add를 통해 Flutter 프로젝트에 원활하게 통합됩니다. 소스 코드는 오픈소스이며 투명성과 기여를 위해 GitHub에 호스팅되어 있습니다.

사용 사례

  • 동적 규칙 평가
  • 구성 검증
  • 정책 시행
  • 런타임 표현식 평가
  • 입력 필터링

주요 기능

  • 완전한 CEL 구문을 지원합니다
  • 안전한 표현식 실행
  • 변수 및 함수 지원
  • 타입 안전한 평가
  • 오픈소스이며 잘 문서화되어 있습니다

적합한 대상

  • 동적 논리를 필요로 하는 애플리케이션
  • 백엔드 규칙 엔진
  • 식 검사를 요구하는 테스트 프레임워크
  • 사용자 정의 가능한 비즈니스 규칙

고려 사항

  • CEL 구문 이해 필요
  • 제한된 플랫폼 지원이 목록에 나와 있습니다
  • 반복 평가를 위한 내장 캐시 없음
  • 최적화 없이 고빈도 사용을 위한 설계가 아님

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

cel-dart

pub package Unit Tests

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.

CEL Literal Description Supported
null Null Literal ✅
true and false Bool Literal ✅
"abc" String Literal ✅
-13, 0xff Int Literal ✅
12u Uint Literal ✅
12.6 Double Literal ✅
b"abc" Bytes Literals ✅
user.id == "abc" Operators See table below
Structures Description Supported
[a, b] List ✅
{'name': 'cel', 35 : true} Map ✅
timestamp google.protobuf.Timestamp ❌
duration google.protobuf.Duration ❌
Operators

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

Operator Description Supported
a.f field access ✅
a() call ✅
a[i] Index ✅
!a, -a Unary negation ✅
a/b, a%b, a*b Multiplicative operators ✅
a+b, a-b Additive operators ✅
a>b, a>=b Relational operators ✅
a in b Existence in list or map ✅
a is type Type comparison, where type can be bool, int, float, number, string, list, map, timestamp, duration, path or latlng ❌
a==b, a!=b Comparison operators ✅
a && b Conditional AND ✅
a || b Conditional OR ✅
a ? true_value : false_value Ternary expression ✅
Functions

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

Symbol Type Description
!_ (bool) -> bool logical not ✅
-_ (int) -> int negation ✅
(double) -> double negation ✅
_!=_ (A, A) -> bool inequality ✅
_%_ (int, int) -> int arithmetic ✅
(uint, uint) -> uint arithmetic untested
_&&_ (bool, bool) -> bool logical and ✅
(bool, ...) -> bool logical and (variadic) ✅
_*_ (int, int) -> int arithmetic ✅
(uint, uint) -> uint arithmetic ✅
(double, double) -> double arithmetic ✅
_+_ (int, int) -> int arithmetic ✅
(uint, uint) -> uint arithmetic ✅
(double, double) -> double arithmetic ✅
(string, string) -> string String concatenation. ✅
(bytes, bytes) -> bytes bytes concatenation ❌
(list(A), list(A)) -> list(A) List concatenation. ✅
(google.protobuf.Timestamp, google.protobuf.Duration) -> google.protobuf.Timestamp arithmetic ❌
(google.protobuf.Duration, google.protobuf.Timestamp) -> google.protobuf.Timestamp arithmetic ❌
(google.protobuf.Duration, google.protobuf.Duration) -> google.protobuf.Duration arithmetic ❌
_-_ (int, int) -> int arithmetic ✅
(uint, uint) -> uint arithmetic ✅
(double, double) -> double arithmetic ✅
(google.protobuf.Timestamp, google.protobuf.Timestamp) -> google.protobuf.Duration arithmetic ❌
(google.protobuf.Timestamp, google.protobuf.Duration) -> google.protobuf.Timestamp arithmetic ❌
(google.protobuf.Duration, google.protobuf.Duration) -> google.protobuf.Duration arithmetic ❌
_/_ (int, int) -> int arithmetic ✅
(uint, uint) -> uint arithmetic ✅
(double, double) -> double arithmetic ✅
_<=_ (bool, bool) -> bool ordering ✅
(int, int) -> bool ordering ✅
(uint, uint) -> bool ordering ✅
(double, double) -> bool ordering ✅
(string, string) -> bool ordering ✅
(bytes, bytes) -> bool ordering ❌
(google.protobuf.Timestamp, google.protobuf.Timestamp) -> bool ordering ❌
(google.protobuf.Duration, google.protobuf.Duration) -> bool ordering ❌
_<_ (bool, bool) -> bool ordering ✅
(int, int) -> bool ordering ✅
(uint, uint) -> bool ordering ✅
(double, double) -> bool ordering ✅
(string, string) -> bool ordering ✅
(bytes, bytes) -> bool ordering ❌
(google.protobuf.Timestamp, google.protobuf.Timestamp) -> bool ordering ❌
(google.protobuf.Duration, google.protobuf.Duration) -> bool ordering ❌
_==_ (A, A) -> bool equality ✅
_>=_ (bool, bool) -> bool ordering ✅
(int, int) -> bool ordering ✅
(uint, uint) -> bool ordering ✅
(double, double) -> bool ordering ✅
(string, string) -> bool ordering ✅
(bytes, bytes) -> bool ordering ❌
(google.protobuf.Timestamp, google.protobuf.Timestamp) -> bool ordering ❌
(google.protobuf.Duration, google.protobuf.Duration) -> bool ordering ❌
_>_ (bool, bool) -> bool ordering ✅
(int, int) -> bool ordering ✅
(uint, uint) -> bool ordering ✅
(double, double) -> bool ordering ✅
(string, string) -> bool ordering ✅
(bytes, bytes) -> bool ordering ❌
(google.protobuf.Timestamp, google.protobuf.Timestamp) -> bool ordering ❌
(google.protobuf.Duration, google.protobuf.Duration) -> bool ordering ❌
_?_:_ (bool, A, A) -> A The conditional operator. See above for evaluation semantics. Will evaluate the test and only one of the remaining sub-expressions. ✅
_[_] (list(A), int) -> A list indexing. ✅
(map(A, B), A) -> B map indexing. ✅
in (A, list(A)) -> bool list membership. ✅
(A, map(A, B)) -> bool map key membership. ✅
|| (bool, bool) -> bool logical or ✅
(bool, ...) -> bool logical or (variadic) ✅
bool type(bool) type denotation ❌
bytes type(bytes) type denotation ❌
(string) -> bytes type conversion ❌
contains string.(string) -> bool Tests whether the string operand contains the substring. ✅
double type(double) type denotation ❌
(int) -> double type conversion ❌
(uint) -> double type conversion ❌
(string) -> double type conversion ❌
duration (string) -> google.protobuf.Duration Type conversion. Duration strings should support the following suffixes: "h" (hour), "m" (minute), "s" (second), "ms" (millisecond), "us" (microsecond), and "ns" (nanosecond). Duration strings may be zero, negative, fractional, and/or compound. Examples: "0", "-1.5h", "1m6s" ❌
dyn type(dyn) type denotation ❌
(A) -> dyn type conversion ❌
endsWith string.(string) -> bool Tests whether the string operand ends with the suffix argument. ✅
getDate google.protobuf.Timestamp.() -> int get day of month from the date in UTC, one-based indexing ❌
google.protobuf.Timestamp.(string) -> int get day of month from the date with timezone, one-based indexing ❌
getDayOfMonth google.protobuf.Timestamp.() -> int get day of month from the date in UTC, zero-based indexing ❌
google.protobuf.Timestamp.(string) -> int get day of month from the date with timezone, zero-based indexing ❌
getDayOfWeek google.protobuf.Timestamp.() -> int get day of week from the date in UTC, zero-based, zero for Sunday ❌
google.protobuf.Timestamp.(string) -> int get day of week from the date with timezone, zero-based, zero for Sunday ❌
getDayOfYear google.protobuf.Timestamp.() -> int get day of year from the date in UTC, zero-based indexing ❌
google.protobuf.Timestamp.(string) -> int get day of year from the date with timezone, zero-based indexing ❌
getFullYear google.protobuf.Timestamp.() -> int get year from the date in UTC ❌
google.protobuf.Timestamp.(string) -> int get year from the date with timezone ❌
getHours google.protobuf.Timestamp.() -> int get hours from the date in UTC, 0-23 ❌
google.protobuf.Timestamp.(string) -> int get hours from the date with timezone, 0-23 ❌
google.protobuf.Duration.() -> int get hours from duration ❌
getMilliseconds google.protobuf.Timestamp.() -> int get milliseconds from the date in UTC, 0-999 ❌
google.protobuf.Timestamp.(string) -> int get milliseconds from the date with timezone, 0-999 ❌
google.protobuf.Duration.() -> int milliseconds from duration, 0-999 ❌
getMinutes google.protobuf.Timestamp.() -> int get minutes from the date in UTC, 0-59 ❌
google.protobuf.Timestamp.(string) -> int get minutes from the date with timezone, 0-59 ❌
google.protobuf.Duration.() -> int get minutes from duration ❌
getMonth google.protobuf.Timestamp.() -> int get month from the date in UTC, 0-11 ❌
google.protobuf.Timestamp.(string) -> int get month from the date with timezone, 0-11 ❌
getSeconds google.protobuf.Timestamp.() -> int get seconds from the date in UTC, 0-59 ❌
google.protobuf.Timestamp.(string) -> int get seconds from the date with timezone, 0-59 ❌
google.protobuf.Duration.() -> int get seconds from duration ❌
int type(int) type denotation ❌
(uint) -> int type conversion ❌
(double) -> int Type conversion. Rounds toward zero, then errors if result is out of range. ❌
(string) -> int type conversion ❌
(enum E) -> int type conversion ❌
(google.protobuf.Timestamp) -> int Convert timestamp to int64 in seconds since Unix epoch. ❌
list type(list(dyn)) type denotation ❌
map type(map(dyn, dyn)) type denotation ❌
matches (string, string) -> bool Matches first argument against regular expression in second argument. ✅
string.(string) -> bool Matches the self argument against regular expression in first argument. ✅
null_type type(null) type denotation ❌
size (string) -> int string length ✅
(bytes) -> int bytes length ❌
(list(A)) -> int list size. ✅
(map(A, B)) -> int map size. ✅
startsWith string.(string) -> bool Tests whether the string operand starts with the prefix argument. ✅
string type(string) type denotation ❌
(int) -> string type conversion ❌
(uint) -> string type conversion ❌
(double) -> string type conversion ❌
(bytes) -> string type conversion ❌
(timestamp) -> string type conversion, using the same format as timestamp string parsing ❌
(duration) -> string type conversion, using the same format as duration string parsing ❌
timestamp (string) -> google.protobuf.Timestamp Type conversion of strings to timestamps according to RFC3339. Example: "1972-01-01T10:00:20.021-05:00" ❌
type type(dyn) type denotation ❌
(A) -> type(dyn) returns type of value ❌
uint type(uint) type denotation ❌
(int) -> uint type conversion ❌
(double) -> uint Type conversion. Rounds toward zero, then errors if result is out of range. ❌
(string) -> uint type conversion ❌
E (for fully-qualified enumeration E) (int) -> enum E type conversion when in int32 range, otherwise error ❌
(string) -> enum E type conversion for unqualified symbolic name, otherwise error ❌

Additional information

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

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.
Re-generating CELParser
  1. Run ./lib/src/parser/gen/generate.sh.
  2. Using Visual Studio Code, in CELParser.dart replace the regex \(\(1 << _la\) & (\d+)\) by bitwiseAnd(pow(2, _la), $1).

카테고리

의존성

의존성 목록 3 개

소스 저장소

이 패키지를 사용하는 프로젝트

순위