83891d7782
* perf!: add LRU caches for compiled regex and glob patterns
Add bounded LRU caches for compiled regex and glob patterns used by
Rego builtins, avoiding repeated recompilation of the same patterns
during policy evaluation.
New `cache` feature (included in `full-opa` and `opa-no-std`) backed by
the `lru` crate (no_std compatible) with `spin::Mutex` for thread safety.
- `src/cache.rs`: generic `LruCache<V>` wrapper, global `REGEX_CACHE`
(default capacity 256) and `GLOB_CACHE` (default capacity 128)
- `src/builtins/regex.rs`: all regex builtins route through the cache
- `src/builtins/glob.rs`: glob.match routes through the cache
- Public API: `regorus::cache::{Config, configure, clear}`
Compilation costs avoided per cache hit:
regex 10-55 µs (simple to complex patterns)
glob 10-12 µs
LRU hit ~10 ns
BREAKING CHANGE: new `cache` Cargo feature added to `full-opa` and
`opa-no-std` feature sets; adds `lru` as a dependency.
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
* perf(vm): amortize per-instruction memory and time limit checks
Deduplicate per-instruction memory_check calls by hoisting them to the
main dispatch loop, and amortize monotonic_now() syscalls in the
execution timer by checking elapsed time every N instructions instead
of on every tick.
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
* fix(vm): correct object membership to check values only, not keys
The Contains instruction for objects was checking both keys and values:
object_fields.contains_key(v) || object_fields.values().any(|v| ...)
Per the Rego specification, `x in obj` tests whether x is a VALUE of
the object, not a key. The two-argument form `k, v in obj` is needed
to access keys. The interpreter already implemented this correctly
(values-only scan), but the RVM had the extra contains_key() check
which would incorrectly return true when the search value happened to
match a key name.
Remove the contains_key() branch so the behavior matches the interpreter
and the Rego spec. Add two regression tests:
- object_membership_checks_values_not_keys: "foo" in {"foo": "bar"}
must be false (key, not a value)
- object_membership_finds_value: "bar" in {"foo": "bar"} must be true
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
* perf(compiler): hoist all-constant collection literals to the literal table
When an array, set, or object literal consists entirely of compile-time
constant expressions (numbers, strings, bools, null, and nested constant
collections), the compiler now evaluates them at compile time and emits a
single Load instruction from the literal table instead of generating
per-element instructions at runtime.
Previously, a Rego expression like `x in [1, 2, 3]` would emit
ArrayCreate + three Load + three ArrayAppend instructions, allocating a
new Vec and Rc on every evaluation. With this change, the entire array
is built once during compilation and loaded as a single constant.
This optimization applies to all three collection types:
- Array literals: avoids ArrayCreate + N x (Load + ArrayAppend)
- Set literals: avoids SetCreate + N x (Load + SetAdd)
- Object literals: avoids ObjectCreate + N x (Load + Load + ObjectInsert)
The implementation adds a try_eval_const() helper that recursively
evaluates an AST expression as a constant Value, returning None if any
sub-expression is non-constant. Each compile method for collection
literals attempts the all-constant fast path first and falls through to
the existing instruction-by-instruction codegen otherwise.
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
* perf(compiler): fuse Eq + AssertCondition into AssertEq instruction
Add a new `AssertEq { left, right }` instruction that combines equality
comparison and condition assertion into a single operation. This replaces
the previous two-instruction pattern of `Eq { dest, left, right }` followed
by `AssertCondition { condition: dest }`, saving one instruction and one
register per equality assertion.
The fused instruction checks two registers for equality and directly calls
handle_condition with the result, avoiding the intermediate boolean
register entirely. If either operand is undefined or the values differ,
the condition fails and the rule/loop backtracks.
The optimization applies to four destructuring sites:
- EqualityCheck (assignment re-binding with `x = expr; x = expr`)
- EqualityExpr (destructuring against an expression)
- EqualityValue (destructuring against a literal value)
- assert_array_length (array length validation in destructuring)
In soft_assert_mode the compiler still emits the original Eq instruction
since the boolean result register is needed by callers.
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
* perf(compiler): fuse Not + AssertCondition into AssertNot instruction
Add a new `AssertNot { operand }` instruction that combines logical
negation and condition assertion into a single operation. This replaces
the previous two-instruction pattern of `Not { dest, operand }` followed
by `AssertCondition { condition: dest }`, saving one instruction and one
register allocation.
The fused instruction checks the operand register and passes the
condition if the value is false or undefined (per Rego semantics where
`not expr` succeeds when the expression has no results or is false),
and fails the condition if the value is true or any non-boolean truthy
value.
This was the only emission site for the Not+AssertCondition pair,
occurring in the compilation of `Literal::NotExpr` statements.
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
* perf(vm): early exit for same-value multi-definition rules
When a rule has multiple definitions that all produce the same value
(e.g. implicit true, or identical literal), set early_exit_on_first_success
on RuleInfo so the VM can stop after the first successful definition.
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
* feat!: expose cache configuration API to all language bindings
Add `set_cache_config` and `clear_cache` functions to every binding
so callers can tune or reset the global regex/glob pattern caches
introduced in the cache feature.
Bindings updated:
- FFI (C): `regorus_set_cache_config`, `regorus_clear_cache`
- C++ header: free functions `regorus::set_cache_config`, `regorus::clear_cache`
- Python: module-level `set_cache_config(*, regex, glob)`, `clear_cache()`
- Java: static methods on new `CacheConfig` class
- Go: package-level `SetCacheConfig`, `ClearCache`
- Ruby: module functions `Regorus.set_cache_config`, `Regorus.clear_cache`
- WASM: free functions `setCacheConfig`, `clearCache`
- C#: static methods `Engine.SetCacheConfig`, `Engine.ClearCache`
BREAKING CHANGE: Bump SERIALIZATION_VERSION from 4 to 5 due to new
AssertEq and AssertNot instruction variants added in the instruction
fusion commits. Programs serialized with version 5 cannot be loaded
by older versions of regorus.
* fix: address PR review feedback
Cache subsystem:
- Gate REGEX_CACHE and related imports behind #[cfg(feature = "regex")]
so that building with --features cache without regex compiles correctly.
- Gate LruCache struct behind #[cfg(any(feature = "regex", feature = "glob"))].
- Add Config::MAX_CAPACITY (2^16) hard upper bound; clamp values in
configure() to prevent unbounded cache growth.
- Use parking_lot::Mutex for std builds and spin::Mutex for no_std to
avoid CPU spinning under contention in tight regex/glob eval loops.
- Narrow lock scopes in regex/glob builtins: release the mutex before
compiling a pattern, then re-acquire to insert.
Java JNI binding:
- Fix cache config overflow: negative jlong values now saturate to 0
and positive overflow saturates to usize::MAX (then clamped by
MAX_CAPACITY) instead of silently disabling the cache.
- Gate JNI cache config/clear functions behind #[cfg(feature = "cache")].
Compiler:
- Refactor static_value_of_expr to delegate to try_eval_const,
gaining support for negated numbers and constant collections.
- Make try_eval_const pub(in crate::languages::rego::compiler) and
re-export through expressions.rs.
- Handle Expr::UnaryExpr with numeric literals in try_eval_const so
collections containing negated numbers (e.g. [-1, 2]) are hoisted.
VM correctness:
- Fix Not instruction to follow Rego semantics: not expr yields
true when expr is undefined or false, false for any other defined
value (including non-booleans) -- no longer errors on non-boolean
operands.
- Add enforce_memory_check() call at execute_suspendable_entry to
ensure memory limits are checked before the first instruction.
- Update AssertNot listing comment to "exit if any defined truthy
value" to match actual VM behaviour.
- Add doc comment on Not instruction clarifying Rego negation
semantics.
Bindings:
- Fix C++ header indentation for set_cache_config / clear_cache.
- Propagate Cargo.lock parking_lot addition across ffi, java, python,
and wasm binding lockfiles.
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
---------
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
Regorus
Regorus is
- Rego-Rus(t) - A fast, light-weight Rego interpreter written in Rust.
- Rigorous - A rigorous enforcer of well-defined Rego semantics.
Regorus is also
-
cross-platform - Written in platform-agnostic Rust.
-
no_std compatible - Regorus can be used in
no_stdenvironments too. Most of the builtins are supported. -
current - We strive to keep Regorus up to date with latest OPA release. Regorus defaults to
v1of the Rego language. -
compliant - Regorus is mostly compliant with the latest OPA release v1.2.0. See OPA Conformance for details. Note that while we behaviorally produce the same results, we don't yet support all the builtins.
-
extensible - Extend the Rego language by implementing custom stateful builtins in Rust. See add_extension. Support for extensibility using other languages coming soon.
-
polyglot - In addition to Rust, Regorus can be used from C, C++, C#, Golang, Java, Javascript, Python, and Ruby. This is made possible by the excellent FFI tools available in the Rust ecosystem. See bindings for information on how to use Regorus from different languages.
To try out a Javascript(WASM) compiled version of Regorus from your browser, visit Regorus Playground.
Regorus is available as a library that can be easily integrated into your Rust projects. Here is an example of evaluating a simple Rego policy:
fn main() -> anyhow::Result<()> {
// Create an engine for evaluating Rego policies.
let mut engine = regorus::Engine::new();
let policy = String::from(
r#"
package example
allow if {
## All actions are allowed for admins.
input.principal == "admin"
} else if {
## Check if action is allowed for given user.
input.action in data.allowed_actions[input.principal]
}
"#,
);
// Add policy to the engine.
engine.add_policy(String::from("policy.rego"), policy)?;
// Add data to engine.
engine.add_data(regorus::Value::from_json_str(
r#"{
"allowed_actions": {
"user1" : ["read", "write"],
"user2" : ["read"]
}}"#,
)?)?;
// Set input and evaluate whether user1 can write.
engine.set_input(regorus::Value::from_json_str(
r#"{
"principal": "user1",
"action": "write"
}"#,
)?);
let r = engine.eval_rule(String::from("data.example.allow"))?;
assert_eq!(r, regorus::Value::from(true));
// Set input and evaluate whether user2 can write.
engine.set_input(regorus::Value::from_json_str(
r#"{
"principal": "user2",
"action": "write"
}"#,
)?);
let r = engine.eval_rule(String::from("data.example.allow"))?;
assert_eq!(r, regorus::Value::Undefined);
Ok(())
}
Regorus is designed with Confidential Computing in mind. In Confidential Computing environments, it is important to be able to control exactly what is being run. Regorus allows enabling and disabling various components using cargo features. By default all features are enabled.
The default build of regorus example program is 6.3M:
$ cargo build -r --example regorus; strip target/release/examples/regorus; ls -lh target/release/examples/regorus
-rwxr-xr-x 1 anand staff 6.3M May 11 22:03 target/release/examples/regorus*
When all default features are disabled, the binary size drops down to 1.9M.
$ cargo build -r --example regorus --no-default-features; strip target/release/examples/regorus; ls -lh target/release/examples/regorus
-rwxr-xr-x 1 anand staff 1.9M May 11 22:04 target/release/examples/regorus*
Regorus passes the OPA v1.2.0 test-suite barring a few builtins. See OPA Conformance below.
Bindings
Regorus can be used from a variety of languages:
- C: C binding is generated using cbindgen. corrosion-rs can be used to seamlessly use Regorous in your CMake based projects. See bindings/c.
- C freestanding: bindings/c_no_std shows how to use Regorus from C environments without a libc.
- C++: C++ binding is generated using cbindgen. corrosion-rs can be used to seamlessly use Regorous in your CMake based projects. See bindings/cpp.
- C#: C# binding is generated using csbindgen. See bindings/csharp for an example of how to build and use Regorus in your C# projects.
- Golang: The C bindings are exposed to Golang via CGo. See bindings/go for an example of how to build and use Regorus in your Go projects.
- Python: Python bindings are generated using pyo3. Wheels are created using maturin. See bindings/python.
- Java: Java bindings are developed using jni-rs. See bindings/java.
- Javascript: Regorus is compiled to WASM using wasmpack. See bindings/wasm for an example of using Regorus from nodejs. To try out a Javascript(WASM) compiled version of Regorus from your browser, visit Regorus Playground.
- Ruby: Ruby bindings are developed using magnus. See bindings/ruby.
To avoid operational overhead, we currently don't publish these bindings to various repositories. It is straight-forward to build these bindings yourself.
Getting Started
examples/regorus is an example program that shows how to integrate Regorus into your project and evaluate Rego policies.
To build and install it, do
$ cargo install --example regorus --path .
Check that the regorus example program is working
$ regorus
Usage: regorus <COMMAND>
Commands:
ast Parse a Rego policy and dump AST
eval Evaluate a Rego Query
lex Tokenize a Rego policy
parse Parse a Rego policy
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
First, let's evaluate a simple Rego expression 1*2+3
$ regorus eval "1*2+3"
This produces the following output
{
"result": [
{
"expressions": [
{
"value": 5,
"text": "1*2+3",
"location": {
"row": 1,
"col": 1
}
}
]
}
]
}
Next, evaluate a sample policy and input (borrowed from Rego tutorial):
$ regorus eval -d examples/server/allowed_server.rego -i examples/server/input.json data.example
Finally, evaluate real-world policies used in Azure Container Instances (ACI)
$ regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.policy.mount_overlay=x
Policy coverage
Regorus allows determining which lines of a policy have been executed using the coverage feature (enabled by default).
We can try it out using the regorus example program by passing in the --coverage flag.
$ regorus eval -d examples/server/allowed_server.rego -i examples/server/input.json data.example --coverage
It produces the following coverage report which shows that all lines are executed except the line that sets allow to true.
See Engine::get_coverage_report for details. Policy coverage information is useful for debugging your policy as well as to write tests for your policy so that all lines of the policy are exercised by the tests.
ACI Policies
Regorus successfully passes the ACI policy test-suite. It is fast and can run each of the tests in a few milliseconds.
$ cargo test -r --test aci
Finished release [optimized + debuginfo] target(s) in 0.05s
Running tests/aci/main.rs (target/release/deps/aci-2cd8d21a893a2450)
aci/mount_device passed 3.863292ms
aci/mount_overlay passed 3.6905ms
aci/scratch_mount passed 3.643041ms
aci/create_container passed 5.046333ms
aci/shutdown_container passed 3.632ms
aci/scratch_unmount passed 3.631333ms
aci/unmount_overlay passed 3.609916ms
aci/unmount_device passed 3.626875ms
aci/load_fragment passed 4.045167ms
Run the ACI policies in the tests/aci directory, using data tests/aci/data.json and input tests/aci/input.json:
$ regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.policy.mount_overlay=x
Verify that OPA produces the same output
$ diff <(regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x) \
<(opa eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x)
Performance
To check how fast Regorus runs on your system, first install a tool like hyperfine.
$ cargo install hyperfine
Then benchmark evaluation of the ACI policies,
$ hyperfine "regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x"
Benchmark 1: regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x
Time (mean ± σ): 4.6 ms ± 0.2 ms [User: 4.1 ms, System: 0.4 ms]
Range (min … max): 4.4 ms … 6.0 ms 422 runs
Compare it with OPA
$ hyperfine "opa eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x"
Benchmark 1: opa eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x
Time (mean ± σ): 45.2 ms ± 0.6 ms [User: 68.8 ms, System: 5.1 ms]
Range (min … max): 43.8 ms … 46.7 ms 62 runs
Contributor Workflow
Regorus uses a small companion CLI under the xtask package to keep CI and local development in sync.
The commands mirror our GitHub Actions jobs, making it easy to dry-run CI steps before sending a pull request.
- Run the full release pipeline with
cargo xtask ci-releaseand the debug checks withcargo xtask ci-debug. - Exercise language bindings through focused helpers such as
cargo xtask test-java --release --frozenorcargo xtask test-go. - Use
cargo xtask test-musl --release --frozenfor the cross-compilation matrix andcargo xtask test-no-stdfor embedded targets. - Formatting (
cargo xtask fmt) and linting (cargo xtask clippy --sarif) wrap the usual Cargo tooling while matching CI defaults.
The workflows in .github/workflows invoke the same commands, so keeping local runs green is usually enough to satisfy the checks enforced on main.
OPA Conformance
Regorus has been verified to be compliant with OPA v1.2.0 using a test driver that loads and runs the OPA testsuite using Regorus, and verifies that expected outputs are produced.
The test driver can be invoked by running:
$ cargo test -r --test opa --features opa-testutil,serde_json/arbitrary_precision
Currently, Regorus passes all the non-builtin specific tests. See passing tests suites.
The following test suites don't pass fully due to missing builtins:
globsmatchgraphqlinvalidkeyerrorjsonpatchjwtbuiltinsjwtdecodeverifyjwtencodesignjwtencodesignheadererrorsjwtencodesignpayloaderrorsjwtencodesignrawjwtverifyhs256jwtverifyhs384jwtverifyhs512jwtverifyrsanetcidrcontainsmatchesnetcidrintersectsnetcidrmergenetcidroverlapnetlookupipaddrproviders-awsregometadatachainregometadataruleregoparsemodulerendertemplate
They are captured in the following github issues.
Cryptographic builtins are not supported by design. Users that need cryptographic builtins are encouraged to use extensions.
Grammar
The grammar used by Regorus to parse Rego policies is described in grammar.md in both W3C EBNF and RailRoad Diagram formats.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.