Skip to content

About

💊 CEL on truffle

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

357 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

TruffleCEL — Common Expression Language on GraalVM Truffle

CI codecov CodSpeed Release OpenSSF Scorecard OpenSSF Best Practices Java 25

CEL expressions, executed by Truffle. TruffleCEL is an independent Common Expression Language parser, type checker, and evaluator for Java and Elide. Compile reusable policies, validation rules, and filters for GraalVM JVM or Native Image, with optional guest compilation for hot expressions. Production code has no cel-java dependency.

Get started · Documentation · Benchmarks · Contribute · Releases

Get started

Use Java 25 and Elide GraalVM 25.5.5-elide.28. TruffleCEL 0.13.0 uses TruffleData 0.14.0. Add the thin core JAR and the matching runtime repository:

repositories {
    mavenCentral()
    maven("https://maven.elide.dev")
    maven("https://maven.elide.dev/gvm-elide/25.5.5-elide.28")
}
dependencies {
    implementation("dev.elide:trufflecel-core:0.13.0")
}
import dev.trufflecel.Cel;
import java.util.List;
import java.util.Map;

var policy = Cel.compile("user.age >= 18 && 'admin' in user.roles");
boolean allowed = policy.test(Map.of(
    "user", Map.of("age", 30, "roles", List.of("admin"))));

Compile once and reuse across threads. Each evaluation has its own activation, scopes, and operation budget. Map inputs are borrowed: keep their contents stable until evaluation returns. Use Activation.snapshot(bindings) for reusable owned inputs. Declare an environment with Cel.newBuilder() for typed variables, custom functions, and explicit resource limits.

RE2/J is optional. For compatibility-mode regex support, add com.google.re2j:re2j:1.8. Applications can omit it by selecting TruffleRegex-only mode, subject to its explicit context and supported-pattern contract.

Choose an artifact

Maven coordinate Purpose
dev.elide:trufflecel-core Compiler, evaluator, Polyglot language and native TruffleData rows
dev.elide:trufflecel-protobuf Protobuf inputs, wire decoding and canonical CEL AST interchange
dev.elide:trufflecel-json Oracle Truffle JSON input conversion
dev.elide:trufflecel-processor Build-time generation of reflection-free POJO, JavaBean and record adapters

Use matching versions. Put the processor on the annotation processor path; generated adapters depend on core. The direct Java API does not require a Polyglot context; the registered language ID is cel. See integration for ownership, numeric and presence semantics, and publishing for Maven/Bazel consumption and runtime dependencies.

Performance and memory

Start with interpreter-to-interpreter results under the same host runtime. Guest JIT is a separate choice for hot, reused expressions; warmed evaluation excludes compilation and warmup. The comparison guide explains the evidence, comparator settings, and remaining limits in response to upstream methodology feedback.

The 0.11.0 report covers six fixtures, including protobuf policy, materialized repeated fields, maps/regex, wide activations, and optimizer opportunities. cel-java 0.15.0 runs with both default and constant-folding/CSE planners. Every non-scalar fixture retains all 69 bindings. Figures use ordinary Map inputs and three forks per cell in one guarded round on the recorded Linux host; they do not establish universal rankings.

Metric TruffleCEL interpreter: lower / tied / higher Guest JIT: lower / tied / higher
Hot evaluation time 12 / 0 / 0 12 / 0 / 0
Current-thread allocation per evaluation 11 / 1 / 0 12 / 0 / 0
Current whole-process RSS 5 / 0 / 7 3 / 0 / 9
Lifetime peak whole-process RSS 6 / 0 / 6 3 / 0 / 9

Each mode is compared with the lower cel-java planner aggregate for that metric, fixture and runtime. Counts are descriptive, not significance tests. Two of the interpreter peak-RSS comparisons have overlapping fork ranges.

Interpreter evaluation time on JVM and Native Image: the TruffleCEL interpreter is lower than both cel-java planners in all 12 fixture and runtime comparisons, from 1.31 to 35.96 times faster.
Hot evaluation with guest JIT

Guest compilation is forced before timing and its cost is excluded.

Hot evaluation time with both TruffleCEL modes: interpreter and guest JIT are each lower than the best cel-java planner in 12 of 12 comparisons.
Allocation per evaluation Current-thread allocation per evaluation: interpreter lower in 11 of 12 comparisons and tied at 96 bytes for JVM scalar; guest JIT lower in 12 of 12.
Current and peak process memory: TruffleCEL is higher in most comparisons Current process RSS: interpreter lower in 5 and higher in 7 of 12 comparisons; guest JIT lower in 3 and higher in 9. Native Image protobuf, repeated protobuf, map and regex, and optimizer fixtures use more memory with TruffleCEL. Lifetime peak process RSS: interpreter lower in 6 and higher in 6 of 12 comparisons, with two overlapping fork ranges; guest JIT lower in 3 and higher in 9.

All cards and controls · Every plotted value · All values and ranges · 0.10.0 report

Input preparation changes the comparison. cel-java copies ordinary maps but reuses Guava ImmutableMaps. In the separate prepared-input controls, JVM scalar-wide cel-java allocation falls from 2,936 to 72 B/op, below TruffleCEL interpreter's 120 B/op. Caller preparation is excluded. Only two fixtures have these controls; ordinary-map counts do not apply to every input API.

Memory and startup remain tradeoffs. Allocation is current-thread bytes/op, not retained heap. RSS covers the whole process, including setup and compilation; the shared comparison binary is not a standalone deployment footprint. Startup/payback and retained-heap measurements use earlier TruffleData 0.9.0 artifacts, and are explicitly historical. Current-release startup/payback and separate deployment-size measurements remain open evidence gaps.

CI also runs CodSpeed simulation, allocation limits and native guest-compilation gates. CodSpeed instruction counts are distinct from JVM/JIT throughput. See methodology and historical reports.

Compatibility and safety

All 2,771 cases in the pinned 32-file cel-spec corpus run without skips, through both a test fixture and the shipped protobuf adapter, and through frontend and canonical AST paths. An additional 431-case negative/edge table checks rejection phase and defined error categories; 368 cases also run against cel-java with both parsers and optimizer settings, with 22 documented divergences.

This is evidence for the tested contracts, not exhaustive CEL specification compliance. CI enforces 99.8% line and branch coverage, resource-limit and concurrency tests, and coverage-guided frontend/decoder fuzzing. Read compatibility and limitations, validation, and the threat model before exposing expressions to untrusted input.

Build and contribute

Bazelisk selects the pinned Bazel and GraalVM toolchains. Local development needs no BuildBuddy credentials:

bazel run --config=local //bazel/gazelle:update
bazel run --config=local //tools:format
bazel test --config=local //...
bazel coverage --config=local //src/test/...
bazel run --config=local //tools:coverage

The default configuration uses BuildBuddy RBE; --config=local uses the host. Native guest-JIT qualification runs on Linux. See Bazel setup, contributor guidance, agent guidance, and CI. Contributions of code, tests, documentation, and reproducible performance investigations are welcome.

Community, security and licensing

Support · Governance · Code of conduct · Security policy · OpenSSF evidence and remaining work

First-party TruffleCEL is dual-licensed under Apache-2.0 or MIT, at your option (Apache-2.0 OR MIT). Contributors offer their work under both alternatives and retain copyright; see the contributor agreement. Third-party components retain their own terms and notices. Report vulnerabilities privately using the security process.

About

💊 CEL on truffle

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages