feat(bindings)!: add RVM/Program support across FFI and language bindings (#565)

- FFI: add RVM/Program APIs, execution state accessors, HostAwait handling, and buffer/result helpers in rvm.rs, common.rs, engine.rs.
- Compiler: emit HostAwait for __builtin_host_await in function_calls.rs.
- RVM tests: add HostAwait regression cases and extend harness for suspend/resume responses in host_await.yaml and mod.rs.
- C/C++: add RVM tests/examples and wrapper updates in rvm_tests.c, rvm_tests.cpp, regorus.hpp, plus CMake wiring.
- C#: add Program/Rvm bindings, SafeHandle/PInvoke, tests, and example usage in Regorus, RvmProgramTests.cs, Program.cs, and README updates.
- Go: add Program/Rvm bindings, tests, and examples in rvm.go, rvm_test.go, main.go.
- Java: add Program/Rvm bindings, JNI glue, and examples in lib.rs, regorus, Test.java.
- Python: add Program/Rvm bindings and examples in lib.rs, test.py.
- WASM: add Program/Rvm bindings and examples in lib.rs, test.js.
- Tooling: wire binding tests in xtask and ignore generated Java artifacts in .gitignore.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

bindings/python/Cargo.lock

@@ -52,6 +52,16 @@ version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
+[[package]]
+name = "bincode"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36eaf5d7b090263e8150820482d5d93cd964a81e4019913c972f4edcc6edb740"
+dependencies = [
+ "serde",
+ "unty",
+]
+
 [[package]]
 name = "bit-set"
 version = "0.8.0"
@@ -103,9 +113,9 @@ checksum = "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e"
 
 [[package]]
 name = "cc"
-version = "1.2.54"
+version = "1.2.55"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6354c81bbfd62d9cfa9cb3c773c2b7b2a3a482d569de977fd0e961f6e7c00583"
+checksum = "47b26a0954ae34af09b50f0de26458fa95369a0d478d8236d3f93082b219bd29"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -191,9 +201,9 @@ dependencies = [
 
 [[package]]
 name = "find-msvc-tools"
-version = "0.1.8"
+version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8591b0bcc8a98a64310a2fae1bb3e9b8564dd10e381e6e28010fde8e8e8568db"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
 [[package]]
 name = "fluent-uri"
@@ -263,9 +273,9 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "iana-time-zone"
-version = "0.1.64"
+version = "0.1.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "33e57f83510bb73707521ebaffa789ec8caf86f9657cad665b092b581d40e9fb"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
 dependencies = [
  "android_system_properties",
  "core-foundation-sys",
@@ -395,6 +405,8 @@ checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
 dependencies = [
  "equivalent",
  "hashbrown",
+ "serde",
+ "serde_core",
 ]
 
 [[package]]
@@ -876,10 +888,12 @@ name = "regorus"
 version = "0.9.0"
 dependencies = [
  "anyhow",
+ "bincode",
  "chrono",
  "chrono-tz",
  "data-encoding",
  "globset",
+ "indexmap",
  "ipnet",
  "jsonschema",
  "lazy_static",
@@ -1110,6 +1124,12 @@ version = "0.2.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
 
+[[package]]
+name = "unty"
+version = "0.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d49784317cd0d1ee7ec5c716dd598ec5b4483ea832a2dced265471cc0f690ae"
+
 [[package]]
 name = "url"
 version = "2.5.8"
@@ -1313,18 +1333,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.34"
+version = "0.8.36"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71ddd76bcebeed25db614f82bf31a9f4222d3fbba300e6fb6c00afa26cbd4d9d"
+checksum = "dafd85c832c1b68bbb4ec0c72c7f6f4fc5179627d2bc7c26b30e4c0cc11e76cc"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.34"
+version = "0.8.36"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d8187381b52e32220d50b255276aa16a084ec0a9017a0ca2152a1f55c539758d"
+checksum = "7cb7e4e8436d9db52fbd6625dbf2f45243ab84994a72882ec8227b99e72b439a"
 dependencies = [
  "proc-macro2",
  "quote",

bindings/python/Cargo.toml

@@ -22,6 +22,6 @@ coverage = ["regorus/coverage"]
 anyhow = "1.0"
 ordered-float = "5.0.0"
 pyo3 = { version = "0.24.1", features = ["abi3-py310", "anyhow", "extension-module"] }
-regorus = { path  = "../..", default-features = false, features = ["arc"] }
+regorus = { path  = "../..", default-features = false, features = ["arc", "rvm"] }
 serde_json = "1.0.140"
 

bindings/python/src/lib.rs

@@ -8,7 +8,14 @@ use pyo3::IntoPyObjectExt;
 
 use std::collections::{BTreeMap, BTreeSet};
 
-use ::regorus::Value;
+use ::regorus::languages::rego::compiler::Compiler;
+use ::regorus::rvm::program::{
+    generate_assembly_listing, generate_tabular_assembly_listing, AssemblyListingConfig,
+    DeserializationResult, Program as RvmProgram,
+};
+use ::regorus::rvm::vm::{ExecutionMode, RegoVM};
+use ::regorus::{compile_policy_with_entrypoint, PolicyModule, Rc, Value};
+use std::sync::Arc;
 
 /// Regorus engine.
 #[pyclass(unsendable)]
@@ -16,6 +23,18 @@ pub struct Engine {
     engine: ::regorus::Engine,
 }
 
+/// RVM program wrapper.
+#[pyclass(unsendable)]
+pub struct Program {
+    program: Arc<RvmProgram>,
+}
+
+/// RVM runtime wrapper.
+#[pyclass(unsendable)]
+pub struct Rvm {
+    vm: RegoVM,
+}
+
 impl Default for Engine {
     fn default() -> Self {
         Self::new()
@@ -384,7 +403,151 @@ impl Engine {
     }
 }
 
+#[pymethods]
+impl Program {
+    /// Compile an RVM program from modules and entry points.
+    #[staticmethod]
+    pub fn compile_from_modules(
+        data_json: String,
+        modules: Vec<(String, String)>,
+        entry_points: Vec<String>,
+    ) -> Result<Self> {
+        if entry_points.is_empty() {
+            return Err(anyhow!("entry_points must contain at least one entry"));
+        }
+
+        let data = Value::from_json_str(&data_json)?;
+        let policy_modules: Vec<PolicyModule> = modules
+            .into_iter()
+            .map(|(id, content)| PolicyModule {
+                id: Rc::from(id.as_str()),
+                content: Rc::from(content.as_str()),
+            })
+            .collect();
+
+        let entry_points_ref: Vec<&str> = entry_points.iter().map(|s| s.as_str()).collect();
+        let entry_rule = Rc::from(entry_points_ref[0]);
+        let compiled = compile_policy_with_entrypoint(data, &policy_modules, entry_rule)?;
+        let program = Compiler::compile_from_policy(&compiled, &entry_points_ref)?;
+        Ok(Self { program })
+    }
+
+    /// Deserialize an RVM program from binary data.
+    #[staticmethod]
+    pub fn deserialize_binary(data: Vec<u8>) -> Result<(Self, bool)> {
+        let (program, is_partial) =
+            match RvmProgram::deserialize_binary(&data).map_err(|e: String| anyhow!(e))? {
+                DeserializationResult::Complete(program) => (program, false),
+                DeserializationResult::Partial(program) => (program, true),
+            };
+        Ok((
+            Self {
+                program: Arc::new(program),
+            },
+            is_partial,
+        ))
+    }
+
+    /// Serialize a program to binary format.
+    pub fn serialize_binary(&self) -> Result<Vec<u8>> {
+        self.program
+            .serialize_binary()
+            .map_err(|e: String| anyhow!(e))
+    }
+
+    /// Generate a readable assembly listing.
+    pub fn generate_listing(&self) -> Result<String> {
+        Ok(generate_assembly_listing(
+            self.program.as_ref(),
+            &AssemblyListingConfig::default(),
+        ))
+    }
+
+    /// Generate a tabular assembly listing.
+    pub fn generate_tabular_listing(&self) -> Result<String> {
+        Ok(generate_tabular_assembly_listing(
+            self.program.as_ref(),
+            &AssemblyListingConfig::default(),
+        ))
+    }
+}
+
+impl Default for Rvm {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[pymethods]
+impl Rvm {
+    #[new]
+    pub fn new() -> Self {
+        Self { vm: RegoVM::new() }
+    }
+
+    /// Load an RVM program into the VM.
+    pub fn load_program(&mut self, program: &Program) -> Result<()> {
+        self.vm.load_program(program.program.clone());
+        Ok(())
+    }
+
+    /// Set data JSON for the VM.
+    pub fn set_data_json(&mut self, data_json: String) -> Result<()> {
+        let data = Value::from_json_str(&data_json)?;
+        self.vm.set_data(data)?;
+        Ok(())
+    }
+
+    /// Set input JSON for the VM.
+    pub fn set_input_json(&mut self, input_json: String) -> Result<()> {
+        let input = Value::from_json_str(&input_json)?;
+        self.vm.set_input(input);
+        Ok(())
+    }
+
+    /// Set execution mode (0 = run-to-completion, 1 = suspendable).
+    pub fn set_execution_mode(&mut self, mode: u8) -> Result<()> {
+        let mode = match mode {
+            0 => ExecutionMode::RunToCompletion,
+            1 => ExecutionMode::Suspendable,
+            _ => return Err(anyhow!("invalid execution mode")),
+        };
+        self.vm.set_execution_mode(mode);
+        Ok(())
+    }
+
+    /// Execute the program and return the JSON result.
+    pub fn execute(&mut self) -> Result<String> {
+        self.vm.execute()?.to_json_str()
+    }
+
+    /// Execute an entry point by name and return the JSON result.
+    pub fn execute_entry_point(&mut self, entry_point: String) -> Result<String> {
+        self.vm
+            .execute_entry_point_by_name(&entry_point)?
+            .to_json_str()
+    }
+
+    /// Resume execution with an optional JSON value.
+    pub fn resume(&mut self, resume_json: Option<String>) -> Result<String> {
+        let value = if let Some(json) = resume_json {
+            Some(Value::from_json_str(&json)?)
+        } else {
+            None
+        };
+        self.vm.resume(value)?.to_json_str()
+    }
+
+    /// Get the execution state as a string.
+    pub fn get_execution_state(&self) -> Result<String> {
+        Ok(format!("{:?}", self.vm.execution_state()))
+    }
+}
+
 #[pymodule]
 pub fn regorus(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
-    m.add_class::<crate::Engine>()
+    m.add_class::<crate::Engine>()?;
+    m.add_class::<crate::Program>()?;
+    m.add_class::<crate::Rvm>()?;
+    Ok(())
 }

bindings/python/test.py

@@ -2,6 +2,10 @@
 # Licensed under the MIT License.
 
 import regorus
+import sys
+
+if hasattr(sys.stdout, "reconfigure"):
+  sys.stdout.reconfigure(encoding="utf-8")
 
 # Create engine
 engine = regorus.Engine()
@@ -94,3 +98,68 @@ engine1.set_gather_prints(True)
 engine1.eval_query('print("Hello")')
 ps = engine1.take_prints()
 print(ps)
+
+# RVM regular example
+policy = """
+package demo
+import rego.v1
+
+default allow := false
+
+allow if {
+  input.user == "alice"
+  input.active == true
+}
+"""
+def run_regular_example():
+  module = ("demo.rego", policy)
+  program = regorus.Program.compile_from_modules(
+    "{}",
+    [module],
+    ["data.demo.allow"],
+  )
+
+  print(program.generate_listing())
+
+  binary = program.serialize_binary()
+  program, is_partial = regorus.Program.deserialize_binary(binary)
+  if is_partial:
+    raise RuntimeError("Deserialized program marked partial")
+
+  vm = regorus.Rvm()
+  vm.load_program(program)
+  vm.set_input_json('{"user":"alice","active":true}')
+  print(vm.execute())
+
+run_regular_example()
+
+# RVM HostAwait example
+policy = """
+package demo
+import rego.v1
+
+default allow := false
+
+allow if {
+  input.account.active == true
+  details := __builtin_host_await(input.account.id, "account")
+  details.tier == "gold"
+}
+"""
+def run_host_await_example():
+  module = ("await.rego", policy)
+  program = regorus.Program.compile_from_modules(
+    "{}",
+    [module],
+    ["data.demo.allow"],
+  )
+
+  vm = regorus.Rvm()
+  vm.set_execution_mode(1)
+  vm.load_program(program)
+  vm.set_input_json('{"account":{"id":"acct-1","active":true}}')
+  vm.execute()
+  print(vm.get_execution_state())
+  print(vm.resume('{"tier":"gold"}'))
+
+run_host_await_example()