Files
regorus/bindings/ruby/test/test_regorus.rb
Anand Krishnamoorthi 83891d7782 RVM compiler & runtime optimizations: caching, instruction fusion, constant hoisting, and correctness fixes (#626)
* 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>
2026-03-23 21:00:51 -05:00

243 lines
6.4 KiB
Ruby

# frozen_string_literal: true
require "test_helper"
require "json"
class TestRegorus < Minitest::Test
ALICE = "Alice"
BOB = "Bob"
CARLOS = "Carlos"
def setup
@engine = ::Regorus::Engine.new
@engine.add_policy("regorus_test.rego", example_policy)
@engine.add_data(example_data)
end
def example_policy
<<~REGO
package regorus_test
is_manager if {
input.name == data.managers[_]
}
is_employee if {
input.name == data.employees[_]
}
# Set a default value for to return false instead of nil
default is_manager_bool = false
default is_employee_bool = false
is_manager_bool if {
is_manager
}
is_employee_bool if {
is_employee
}
REGO
end
def example_data
{
"managers" => [ALICE],
"employees" => [ALICE, BOB]
}
end
def input_for(name)
{ "name" => name }
end
def test_version_number_presence
refute_nil ::Regorus::VERSION
end
def test_engine_creation
assert_instance_of ::Regorus::Engine, ::Regorus::Engine.new
end
def test_policy_addition
# returns the package name from the REGO, not the filename
assert_equal "data.regorus_test", @engine.add_policy("example.rego", example_policy)
end
def test_object_creation_with_new
refute_same ::Regorus::Engine.new, ::Regorus::Engine.new
end
def test_data_addition
assert_silent { @engine.add_data(example_data) }
end
def test_data_addition_as_json
assert_silent { @engine.add_data_json(example_data.to_json) }
end
def test_query_evaluation_for_alice
@engine.set_input(input_for(ALICE))
assert_equal alice_results, @engine.eval_query("data.regorus_test")
end
def test_query_evaluation_for_bob
@engine.set_input(input_for(BOB))
assert_equal bob_results, @engine.eval_query("data.regorus_test")
end
def test_query_evaluation_as_json
@engine.set_input(input_for(ALICE))
assert_equal alice_results.to_json, @engine.eval_query_as_json("data.regorus_test")
end
def test_rule_evaluation_for_alice
@engine.set_input(input_for(ALICE))
assert @engine.eval_rule("data.regorus_test.is_employee")
assert @engine.eval_rule("data.regorus_test.is_employee_bool")
assert @engine.eval_rule("data.regorus_test.is_manager")
assert @engine.eval_rule("data.regorus_test.is_manager_bool")
end
def test_rule_evaluation_for_bob
@engine.set_input(input_for(BOB))
assert @engine.eval_rule("data.regorus_test.is_employee")
assert @engine.eval_rule("data.regorus_test.is_employee_bool")
assert_nil @engine.eval_rule("data.regorus_test.is_manager")
refute @engine.eval_rule("data.regorus_test.is_manager_bool")
end
def test_rule_evaluation_for_carlos
@engine.set_input(input_for(CARLOS))
assert_nil @engine.eval_rule("data.regorus_test.is_employee")
refute @engine.eval_rule("data.regorus_test.is_employee_bool")
assert_nil @engine.eval_rule("data.regorus_test.is_manager")
refute @engine.eval_rule("data.regorus_test.is_manager_bool")
end
def test_eval_bool_query
assert @engine.eval_bool_query("1 < 2")
refute @engine.eval_bool_query("1 > 2")
assert_raises(RuntimeError) { @engine.eval_bool_query("1 + 1") }
assert_raises(RuntimeError) { @engine.eval_bool_query("true; true") }
assert_raises(RuntimeError) { @engine.eval_bool_query("true; false; true") }
end
def test_eval_allow_query
assert @engine.eval_allow_query("1 < 2")
refute @engine.eval_allow_query("1 > 2")
refute @engine.eval_allow_query("1 + 1")
refute @engine.eval_allow_query("true; true")
refute @engine.eval_allow_query("true; false; true")
end
def test_eval_deny_query
assert @engine.eval_deny_query("1 < 2")
refute @engine.eval_deny_query("1 > 2")
assert @engine.eval_deny_query("1 + 1")
assert @engine.eval_deny_query("true; true")
assert @engine.eval_deny_query("true; false; true")
end
def test_missing_rules_handling
@engine.set_input(input_for(ALICE))
assert_raises(RuntimeError) { @engine.eval_rule("data.regorus_test.not_a_rule") }
end
def test_engine_cloning
cloned_engine = @engine.clone
assert_instance_of ::Regorus::Engine, cloned_engine
refute_same @engine, cloned_engine
end
def test_coverage_printing_json
@engine.set_input(input_for(ALICE))
@engine.set_enable_coverage(true)
@engine.eval_rule("data.regorus_test.is_employee")
assert_match(/covered":\[7\],"not_covered":\[3,11,12,15,19\]/, @engine.get_coverage_report_as_json)
end
def test_coverage_printing_pretty
@engine.set_input(input_for(ALICE))
@engine.set_enable_coverage(true)
@engine.eval_rule("data.regorus_test.is_employee")
# to see the colors in the ruby terminal, use `puts @engine.get_coverage_report``
pretty_coverage_report = @engine.get_coverage_report_pretty
assert_match(/\e\[31m 3 input.name == data.managers\[_\]/, pretty_coverage_report)
assert_match(/\e\[32m 7 input.name == data.employees\[_\]/, pretty_coverage_report)
end
def test_gather_print_statements
@engine.set_gather_prints(true)
@engine.eval_query('print("Hello")')
assert_equal ["<query.rego>:1: Hello"], @engine.take_prints
end
def test_set_policy_length_config
@engine.set_policy_length_config({ max_col: 2000, max_file_bytes: 1048576, max_lines: 20000 })
@engine.clear_policy_length_config
end
def test_set_cache_config
::Regorus.set_cache_config({ regex: 256, glob: 128 })
::Regorus.clear_cache
end
def alice_results
{
result: [
{
expressions: [
{
value: {
"is_employee" => true,
"is_employee_bool" => true,
"is_manager" => true,
"is_manager_bool" => true
},
text: "data.regorus_test",
location: {
row: 1,
col: 1
}
}
]
}
]
}
end
def bob_results
{
result: [
{
expressions: [
{
value: {
"is_employee" => true,
"is_employee_bool" => true,
"is_manager_bool" => false
},
text: "data.regorus_test",
location: {
row: 1,
col: 1
}
}
]
}
]
}
end
end