• CEL-CXX
  • Documentation
  • Quick Start
    • Installation
    • Basic Expression Evaluation
    • Custom Types with Derive Macros
  • Platform Support
    • Cross-Compilation Support
    • Android Build Instructions
  • CEL Feature Support
    • Core Language Features
    • Standard Library
    • Optional Value Support
    • Extension Libraries
    • Runtime Features
  • Protobuf Integration
    • Typed API with Derive Macros
  • License
  • Acknowledgements

CEL-CXX

A type-safe Rust library for Common Expression Language (CEL), built on top of cel-cpp with zero-cost FFI bindings via cxx.

Documentation

• English Documentation - Complete documentation and guides
• 中文文档 - 中文文档和指南

For detailed guides on architecture, function registration, type system, and advanced features, see the documentation directory.

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
cel-cxx = "0.2.4"

# Optional features
cel-cxx = { version = "0.2.4", features = ["tokio"] }

# Protobuf derive macros (choose your backend)
cel-cxx = { version = "0.2.4", features = ["prost"] }
cel-cxx = { version = "0.2.4", features = ["protobuf-legacy"] }

Basic Expression Evaluation

use cel_cxx::*;

// 1. Build environment with variables and functions
let env = Env::builder()
    .declare_variable::<String>("name")?
    .declare_variable::<i64>("age")?
    .register_global_function("adult", |age: i64| age >= 18)?
    .build()?;

// 2. Compile expression
let program = env.compile("'Hello ' + name + '! You are ' + (adult(age) ? 'an adult' : 'a minor')")?;

// 3. Create activation with variable bindings
let activation = Activation::new()
    .bind_variable("name", "Alice")?
    .bind_variable("age", 25i64)?;

// 4. Evaluate
let result = program.evaluate(&activation)?;
println!("{}", result); // "Hello Alice! You are an adult"
# Ok::<(), cel_cxx::Error>(())

Custom Types with Derive Macros

use cel_cxx::*;

#[derive(Opaque, Debug, Clone, PartialEq)]
// Specify type name in CEL type system.
#[cel_cxx(type = "myapp.User")]
// Generates `std::fmt::Display` impl for User` with `Debug` trait.
#[cel_cxx(display)]
// or you can specify a custom format.
// Generates `std::fmt::Display` impl with custom format.
#[cel_cxx(display = write!(fmt, "User(name={name})", name = &self.name))]
struct User {
    name: String,
    age: i32,
    roles: Vec<String>,
}

impl User {
    // Struct methods can be registered directly as CEL member functions
    fn has_role(&self, role: &str) -> bool {
        self.roles.contains(&role.to_string())
    }
    
    fn is_adult(&self) -> bool {
        self.age >= 18
    }
    
    fn get_role_count(&self) -> i64 {
        self.roles.len() as i64
    }
}

let env = Env::builder()
    .declare_variable::<User>("user")?
    // ✨ Register struct methods directly - &self becomes CEL receiver
    .register_member_function("has_role", User::has_role)?
    .register_member_function("is_adult", User::is_adult)?
    .register_member_function("get_role_count", User::get_role_count)?
    .build()?;

let program = env.compile("user.has_role('admin') && user.is_adult()")?;
# Ok::<(), cel_cxx::Error>(())

Platform Support

Legend:

• ✅ Tested: Confirmed working with automated tests
• 🟡 Should work: Build configuration exists but not tested in CI

Cross-Compilation Support

cel-cxx includes built-in support for cross-compilation via cross-rs. The build system automatically detects cross-compilation environments and configures the appropriate toolchains.

Usage with cross-rs:

# Install cross-rs
cargo install cross --git https://github.com/cross-rs/cross

# Build for aarch64
cross build --target aarch64-unknown-linux-gnu

Note: Not all cross-rs targets are supported due to CEL-CPP's build requirements. musl targets and some embedded targets may not work due to missing C++ standard library support or incompatible toolchains.

Android Build Instructions

Android builds require additional setup beyond the standard Rust toolchain:

Prerequisites:

1. Install Android NDK and set ANDROID_NDK_HOME
2. Install cargo-ndk for simplified Android builds

# Install cargo-ndk
cargo install cargo-ndk

# Add Android targets
rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi
rustup target add x86_64-linux-android
rustup target add i686-linux-android

Building for Android:

# Build for ARM64 (recommended)
cargo ndk --target aarch64-linux-android build

# Build for ARMv7
cargo ndk --target armv7-linux-androideabi build

# Build for x86_64 (emulator)
cargo ndk --target x86_64-linux-android build

# Build for i686 (emulator)
cargo ndk --target i686-linux-android build

Why cargo-ndk is required:

• ANDROID_NDK_HOME configures Bazel for CEL-CPP compilation
• cargo-ndk automatically sets up CC_{target} and AR_{target} environment variables needed for the Rust FFI layer
• This ensures both the C++ (CEL-CPP) and Rust (cel-cxx-ffi) components use compatible toolchains

CEL Feature Support

Core Language Features

Standard Library

Optional Value Support

Extension Libraries

Runtime Features

Protobuf Integration

cel-cxx supports native Protocol Buffer messages as first-class CEL types. You can bind serialized protobuf messages as variables, access their fields in CEL expressions, construct new messages, and extract results back to Rust.

Compiling Proto Descriptors

CEL needs a FileDescriptorSet (a binary descriptor file) to understand your .proto types. The recommended approach is protox, a pure-Rust protobuf compiler that requires no external binary:

use prost::Message;

let fds = protox::compile(["proto/my_service.proto"], ["proto/"]).unwrap();
let descriptor_bytes = fds.encode_to_vec();

Alternatively, you can use protoc directly:

protoc --descriptor_set_out=descriptors.bin \
       --include_imports \
       --proto_path=proto \
       proto/my_service.proto

Setting Up the Environment

use cel_cxx::*;

# let descriptor_bytes: Vec<u8> = vec![];
let env = Env::builder()
    .with_file_descriptor_set(&descriptor_bytes)
    .declare_variable_with_type("msg", ValueType::Struct(StructType::new("my.package.MyMessage")))?
    .build()?;
# Ok::<(), cel_cxx::Error>(())

Binding Protobuf Input

Serialize your message to bytes (e.g., via prost) and bind it:

# use cel_cxx::*;
# let serialized_bytes: Vec<u8> = vec![];
let activation = Activation::new()
    .bind_variable_dynamic("msg", StructValue::from_bytes("my.package.MyMessage", serialized_bytes))?;
# Ok::<(), cel_cxx::Error>(())

Accessing Fields in CEL

CEL expressions can access all protobuf field types:

msg.name                              // scalar fields
msg.address.city                      // nested message fields
msg.tags[0]                           // repeated fields
msg.labels["env"]                     // map fields
msg.status == my.package.Status.ACTIVE // enum constants
has(msg.optional_field)               // field presence

Message Construction

Construct new protobuf messages directly in CEL:

my.package.MyMessage{name: "Alice", id: 42}

Extracting Results

# use cel_cxx::*;
# fn example(result: Value, env: Env) -> Result<(), Error> {
// Borrow via as_struct()
let sv = result.as_struct().unwrap();
let type_name = sv.type_name();
let bytes = sv.to_bytes();

// Or extract an owned StructValue
let sv = StructValue::from_value(&result)?;

// Read individual fields from Rust
let name = env.get_struct_field(&sv, "name")?;
let has_name = env.has_struct_field(&sv, "name")?;
# Ok(())
# }

Typed API with Derive Macros

If you have compile-time protobuf types (via prost-build or protobuf-codegen), derive macros let you skip the manual StructValue::from_bytes plumbing and use the standard typed API instead:

// With the `prost` or `protobuf-legacy` feature enabled:
let env = Env::builder()
    .with_file_descriptor_set(&descriptors)
    .declare_variable::<MyMessage>("msg")?  // instead of declare_variable_with_type(...)
    .build()?;

let activation = Activation::new()
    .bind_variable("msg", my_message)?;  // instead of bind_variable_dynamic(...)

let result = program.evaluate(&activation)?;
let recovered = MyMessage::from_value(&result)?;  // instead of StructValue::from_value(...)

The derives are injected during code generation in your build.rs -- one line per type for prost, or a small CustomizeCallback for protobuf-codegen.

See the Protobuf Derive Macros Guide for full setup instructions, feature flags, and examples.

Well-Known Type Handling

cel-cpp automatically converts well-known types to their CEL equivalents:

Performance Note

Protobuf messages cross the Rust/C++ FFI boundary via serialization: messages are serialized to bytes on the Rust side and deserialized into arena-allocated C++ messages for evaluation, then serialized back when extracting results. This adds overhead proportional to message size.

Zero-copy is not currently implemented for two reasons. First, the architectural change to keep C++ arena-allocated messages alive across the FFI boundary would be significant. Second, true zero-copy would require both cel-cxx and the Rust protobuf library to link against the exact same C++ protobuf library instance so that message pointers can be passed directly across the boundary. The official Google Rust protobuf crate (protobuf) supports a C++ kernel backend that would make this possible in theory, but it currently requires Bazel (not cargo), and there is no shared protobuf-cpp-sys crate that both libraries could depend on. cel-cxx also compiles its own copy of C++ protobuf as part of cel-cpp via cmake, so integrating a shared dependency would require reworking the build. Until the ecosystem converges, serialization/deserialization is the only correct approach.

License

Licensed under the Apache License 2.0. See LICENSE for details.

Acknowledgements

• google/cel-cpp - The foundational C++ CEL implementation
• dtolnay/cxx - Safe and efficient Rust-C++ interop
• rmanoka/async-scoped - Scoped async execution for safe lifetime management
• The CEL community and other Rust CEL implementations for inspiration and ecosystem growth