Struct Sandbox 

pub struct Sandbox { /* private fields */ }

A JavaScript runtime that rule code executes in.

Not Sync: the underlying engine runtime is single-threaded, so each rayon worker owns one. They share a RunClock so the global budget is measured once for the run rather than once per worker.

Implementations

impl Sandbox

pub fn new(limits: Limits, clock: Arc<RunClock>) -> Result<Self, SandboxError>

Build a sandbox sharing a run clock.

Errors

Returns SandboxError::Engine if the runtime cannot be created or the bootstrap fails, both of which indicate a broken build rather than anything about a rule.

pub fn with_modules( limits: Limits, clock: Arc<RunClock>, root: RuleRoot, typescript: Arc<dyn Language>, javascript: Arc<dyn Language>, ) -> Result<Self, SandboxError>

Build a sandbox that can load rule modules from a rules root.

Errors

As Sandbox::new.

pub fn loaded_modules(&self) -> Option<&LoadedModules>

Every module loaded so far, when this sandbox was built with a module root.

The hash of the rule graph is derived from this, so it has to reflect what was actually read rather than what the config named.

pub fn import_default<T>(&self, path: &Path) -> Result<T, SandboxError>

where T: for<'js> FromJs<'js>,

Import a rule module and return its default export.

Errors

Returns SandboxError on a breached budget, a module that fails to resolve or load, or a module that throws while evaluating.

pub fn with_limits(limits: Limits) -> Result<Self, SandboxError>

Build a sandbox with its own run clock, starting now.

For a single-threaded run or a test. A real run shares one clock across workers.

Errors

As Sandbox::new.

pub const fn limits(&self) -> &Limits

The budgets in force.

pub fn eval<T>(&self, source: &str) -> Result<T, SandboxError>

where T: for<'js> FromJs<'js>,

Evaluate source, enforcing the per-invocation budget.

Errors

Returns SandboxError on a breached budget or a thrown value. Every variant cancels the run.

pub fn eval_with_timeout<T>( &self, source: &str, timeout: Duration, ) -> Result<T, SandboxError>

where T: for<'js> FromJs<'js>,

Evaluate source under an explicit per-invocation budget, for a rule that declared its own.

Errors

As Sandbox::eval.

pub fn eval_module(&self, name: &str, source: &str) -> Result<(), SandboxError>

Evaluate a synthetic module under a chosen name.

The name matters: the resolver treats it as the importing module’s path, so a synthetic entry has to sit inside the rules root for relative specifiers in its source to resolve. Naming it outside would make every import look like an escape.

Errors

As Sandbox::eval.

pub fn eval_with_host<T>( &self, host: &HostContext, source: &str, ) -> Result<T, SandboxError>

where T: for<'js> FromJs<'js>,

Evaluate source with a ctx object in scope, the way a rule handler runs.

Errors

As Sandbox::eval.

pub fn eval_with_host_timeout<T>( &self, host: &HostContext, source: &str, timeout: Duration, ) -> Result<T, SandboxError>

where T: for<'js> FromJs<'js>,

Evaluate with ctx in scope under an explicit budget, for a rule that declared one.

Errors

As Sandbox::eval.

pub fn eval_with_reduce_host<T>( &self, host: &ReduceContext, source: &str, timeout: Duration, ) -> Result<T, SandboxError>

where T: for<'js> FromJs<'js>,

Evaluate with a reduce-phase ctx in scope, under an explicit budget.

A separate entry point rather than a flag on the one above, because the two contexts expose different surfaces on purpose — facts and files here, emitFact and the tree there. A single builder that switched on a boolean would make it possible to get the wrong one, which is precisely what must not happen.

Errors

As Sandbox::eval.

Trait Implementations

impl Debug for Sandbox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.