mirror of
https://github.com/microsoft/regorus.git
synced 2026-08-05 02:16:11 +00:00
49bd3c22f3
* feat!: add Rego Virtual Machine (RVM) implementation This commit introduces a register-based virtual machine for executing Rego policies with bytecode-style instructions. Unlike the existing tree-walking interpreter, the RVM compiles policies into instruction sequences that operate on virtual registers, offering better performance and optimization potential. Core Components: Instruction Set Architecture: - Define instruction types for data operations, control flow, and builtins - Implement instruction parameter encoding and display formatting - Add instruction parser with comprehensive test coverage Virtual Machine Engine: - Register-based execution model with program counter management - Loop execution supporting iterators, comprehensions, and quantifiers - Function call handling with argument evaluation and context management - Rule evaluation with default value resolution and virtual data support - Arithmetic and comparison operation implementations Program Representation: - Program listing builder with instruction sequencing - Rule tree construction for organizing policy rules - Binary and JSON serialization for compiled programs - Recompilation support for program modification Testing Infrastructure: - Extensive YAML test suites covering all VM features - Rust unit tests for VM execution and instruction parsing - Test suites for loops, comprehensions, builtins, and control flow BREAKING CHANGE: Introduces new VM execution path alongside interpreter Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com> * docs: add detailed RVM architecture references Introduce architecture.md explaining program artifacts, serialization, and runtime subsystems. Document the full opcode catalog in instruction-set.md, including operands, parameter tables, and outcomes. Walk through execution flow, stacks, and operational guidance in vm-runtime.md, tying the runtime to the new architecture docs. Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com> --------- Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
79 lines
5.9 KiB
Markdown
79 lines
5.9 KiB
Markdown
# Regorus VM Test Suites
|
|
|
|
This directory hosts YAML-driven regression suites for the Regorus virtual machine. Each YAML file is converted into parameterised Rust tests by `src/rvm/tests/vm.rs`, so the contents here define the end-to-end VM coverage.
|
|
|
|
## Prerequisites
|
|
|
|
- Enable the `rvm` feature (it pulls in `std` and the VM runtime) whenever you run these tests:
|
|
- `cargo test --features rvm run_vm_test_file`
|
|
- `cargo test --features rvm run_loop_test_file`
|
|
- Append `-- --nocapture` to surface per-test diagnostics when a failure occurs.
|
|
- Individual generated tests follow the pattern `run_vm_test_file_tests_rvm_vm_suites_<suite>_yaml`, so you can use that fragment with `cargo test` to run a single suite.
|
|
|
|
## Layout
|
|
|
|
- `suites/*.yaml` — primary instruction, control-flow, and integration suites.
|
|
- `suites/loops/*.yaml` — dedicated loop/comprehension suites.
|
|
- Mirror the comment headers inside each suite when adding new files; the descriptions are surfaced in this README for quick reference.
|
|
|
|
## Main Suites (`suites/*.yaml`)
|
|
|
|
| Suite | Focus |
|
|
| --- | --- |
|
|
| `arithmetic_operations.yaml` | Arithmetic opcodes (`Add`, `Sub`, `Mul`, `Div`, `Mod`) and simple expressions. |
|
|
| `assertions.yaml` | `AssertCondition` semantics, including success/failure and loop control interactions. |
|
|
| `basic_instructions.yaml` | Core load/move/return instructions that underpin every program. |
|
|
| `boolean_literals.yaml` | `LoadBool`, `LoadTrue`, `LoadFalse`, and their interaction with logical operators. |
|
|
| `builtin_functions.yaml` | Builtin dispatch covering argument marshalling, return handling, and error cases. |
|
|
| `call_rule.yaml` | `CallRule` execution, rule caches, defaults, and fallbacks. |
|
|
| `comparison_operations.yaml` | Relational operators plus logical combining (`Eq`, `Ne`, `Lt`, `Le`, `Gt`, `Ge`, `And`, `Or`, `Not`). |
|
|
| `complex.yaml` | Deeply nested hybrid loops, comprehensions, and rule calls that stress the scheduler. |
|
|
| `constructed_collections.yaml` | `ArrayCreate`/`SetCreate` success paths, undefined propagation, and deduplication. |
|
|
| `control_flow.yaml` | Conditional branching patterns, nested assertions, and selection logic. |
|
|
| `core_semantics.yaml` | Broad regression coverage for arithmetic, comparisons, loops, assertions, and collection helpers. |
|
|
| `data_structures.yaml` | Array/object/set creation, access, and mutation instructions. |
|
|
| `deep_nesting.yaml` | Three-plus levels of mixed loop modes validating register pressure and control flow correctness. |
|
|
| `default_rules.yaml` | Complete rule execution with default literals and failure fallbacks. |
|
|
| `destructuring_rules.yaml` | Destructuring metadata handling, success/early-exit semantics. |
|
|
| `function_calls.yaml` | User function invocation plumbing, argument passing, and returns. |
|
|
| `halt.yaml` | `Halt` instruction returning register `0` and stopping execution. |
|
|
| `host_await.yaml` | Successful `HostAwait` responses across execution modes and run-to-completion flows. |
|
|
| `host_await_failures.yaml` | Error signalling and ignore-flag behaviour for `HostAwait`. |
|
|
| `indexed_access.yaml` | Literal/register indexing, chained accesses, and undefined propagation. |
|
|
| `integration_scenarios.yaml` | Real-world policy shapes (RBAC, filtering, transforms, workflows). |
|
|
| `interpreter_operator_compatibility.yaml` | Ensures VM operators match interpreter behaviour on edge cases. |
|
|
| `invalid_collection_ops.yaml` | Error paths for object/set/array mutations with incorrect types. |
|
|
| `load_data_input.yaml` | `LoadData` and `LoadInput` instructions across nested/empty/undefined sources. |
|
|
| `loop_invalid_iteration.yaml` | Loop errors for non-iterables plus instruction-limit enforcement. |
|
|
| `null_undefined_handling.yaml` | Null/undefined behaviour across arithmetic, comparisons, indexing, loops, and comprehensions. |
|
|
| `object_operations.yaml` | Advanced object templates, dynamic keys, collisions, and validation. |
|
|
| `predefined.yaml` | Global `data` and `input` bindings, including nested access patterns. |
|
|
| `resource_limits.yaml` | Instruction counts, recursion depth, and other resource exhaustion scenarios. |
|
|
| `serialization.yaml` | Round-trip binary serialization for compiled programs covering all instruction families. |
|
|
| `set_operations.yaml` | Set creation, deduplication, membership checks, and nested values. |
|
|
| `type_errors.yaml` | Graceful error reporting for cross-family type mismatches. |
|
|
| `virtual_data_lookup.yaml` | `VirtualDataDocumentLookup` with base data, rule overrides, and invalid indices. |
|
|
|
|
## Loop Suites (`suites/loops/*.yaml`)
|
|
|
|
| Suite | Focus |
|
|
| --- | --- |
|
|
| `array_comprehensions.yaml` | Mapping, filtering, and edge cases for array comprehensions. |
|
|
| `empty.yaml` | Behaviour of every loop mode over empty collections (vacuous truth/falsehood). |
|
|
| `existential.yaml` | `some`-style (`Any`) quantification including early exits and complex predicates. |
|
|
| `loop_comprehension_interactions.yaml` | Interplay between nested loops and comprehensions emitting structured data. |
|
|
| `nested.yaml` | Mixed nesting patterns for loops and comprehensions with varying depth. |
|
|
| `nested_fixed.yaml` | Placeholder for future fixed-nesting scenarios (no cases yet). |
|
|
| `object_comprehensions.yaml` | Key/value emission, collision handling, and filtering in object comprehensions. |
|
|
| `set_comprehensions.yaml` | Deduplication and uniqueness guarantees in set comprehensions. |
|
|
| `universal.yaml` | `every`-style (`Every`) quantification, early failure, and vacuous truth cases. |
|
|
|
|
## Adding or Updating Suites
|
|
|
|
1. Place the new YAML file under `suites/` (or the relevant `suites/loops/` subdirectory).
|
|
2. Add a concise comment block at the top describing the intent and scenarios.
|
|
3. Update the tables above so the catalog stays accurate.
|
|
4. Run `cargo test --features rvm run_vm_test_file` to ensure the suite loads and all cases pass.
|
|
|
|
Keeping this README current makes it easier to discover coverage gaps and reason about the generated tests.
|