Regorus

Regorus is a fast, lightweight, and rigorous Rego interpreter written in Rust. It is designed to be cross-platform, no_std compatible, and highly extensible.

Key features include:

• Rego Compliance: Defaults to Rego v1 and is mostly compliant with OPA release v1.2.0.
• Extensibility: Allows implementing custom stateful builtins in Rust via add_extension.
• Polyglot Support: Provides bindings for C, C++, C#, Golang, Java, Javascript (WASM), Python, and Ruby.
• Confidential Computing Ready: Supports fine-grained control over components via Cargo features to minimize binary size and attack surface.

The Rego Virtual Machine (RVM) instruction set consists of opcodes emitted by the compiler and executed by the RegoVM. Instructions are categorized by their functionality, such as arithmetic, loops, or host interaction.

Key Concepts

• Operands: Instructions use registers (rX), literals (litY), parameter indices (pZ), and immediate values.
• Parameters: Complex metadata is stored in InstructionData. Instructions reference this metadata via an index (pN).
• Outcomes: Instructions can result in different control flow states, including Continue, Return, Break, or Suspend.

The memory budget tracks additional live bytes during the RVM execution window.

Included in the budget:

• Fresh execution-state initialization.
• Rule evaluation.
• Allocations retained by the result.
• (C FFI) Native result JSON serialization and CString allocation.

Excluded from the budget:

• Program compilation.
• Program loading.
• Data, input, and context loading.
• (C#) Managed UTF-8 decoding and managed string allocation (these occur after the C FFI execution window has closed).

Secure mode is a build configuration enabled via -DMI_SECURE=ON in CMake. It provides several mitigations against memory-based exploits:

• Guard Pages: Internal mimalloc pages and heap metadata are surrounded by guard pages to prevent buffer overflow exploits from reaching metadata.
• Encoded Free Lists: Free list pointers are encoded with per-page keys to prevent overwrites and detect heap corruption.
• Double Free Detection: Automatically detects and ignores double free attempts.
• Randomization: Free lists are initialized in random order, and allocation between extension and reuse within a page is randomized. Additionally, large heap blocks from the OS are address randomized to mitigate predictable allocation order attacks.

The benchmark evaluates performance using four distinct combinations of engine and input strategies to distinguish between engine instantiation overhead and data parsing overhead:

1. Cloned Engines + Cloned Inputs: Uses pre-instantiated engines and pre-parsed input data.
2. Cloned Engines + Fresh Inputs: Uses pre-instantiated engines but performs fresh JSON parsing for each input.
3. Fresh Engines + Cloned Inputs: Uses new engine instances but uses pre-parsed input data.
4. Fresh Engines + Fresh Inputs: Uses new engine instances and performs fresh JSON parsing for each input.

The instruction dispatcher (dispatch.rs) uses the InstructionOutcome enum to control flow:

• Continue: Normal execution; the instruction pointer (pc) is incremented.
• Return(Value): Unwinds the current rule or function frame and propagates the Value upward.
• Break: Used by specific constructs (like RuleReturn or DestructuringSuccess) to exit to the owning frame without returning a specific value.
• Suspend { reason }: Used exclusively in Suspendable mode to pause execution.

The Suspendable mode allows the VM to pause execution and yield control back to the host.

Workflow:

1. Entry: Call the public API with the VM configured for Suspendable mode. The VM uses run_stackless_from to manage an execution_stack of ExecutionFrame objects.
2. Suspension: The VM can suspend due to a HostAwait, a breakpoint, or a step. The SuspendReason is recorded, and the last result snapshot is stored.
3. Resumption: The host calls resume(resume_value) to provide the value needed to continue execution.
4. Completion: Once the execution_stack is empty, the VM transitions to ExecutionState::Completed { result }.

Based on engine evaluation benchmarks, developers should be aware of the following performance characteristics:

• Engine Creation Overhead: Creating a 'fresh' engine is a major bottleneck, performing approximately 7-8x slower than using cloned engines.
• Input Processing: Generating or parsing 'fresh' inputs adds moderate overhead, typically causing a ~27% impact on throughput compared to using cloned/pre-parsed inputs.
• Thread Contention: While Regorus uses mimalloc as the default allocator to improve multi-threaded scaling and reduce contention, throughput generally degrades as thread counts increase due to inherent contention.
• Scaling Strategy: For maximum throughput, use a single thread with cloned engines and cloned inputs. For multi-threaded environments, prioritize cloning engines rather than creating them fresh to avoid the heavy creation penalty.