Struct LoadedJSSandbox

Source

pub struct LoadedJSSandbox { /* private fields */ }

Expand description

A Hyperlight Sandbox with a JavaScript run time loaded and guest code loaded. A Hyperlight Sandbox with a JavaScript run time loaded and guest JavaScript handlers loaded.

Implementations§

Source §

impl LoadedJSSandbox

Source

pub fn handle_event<F>( &mut self, func_name: F, event: String, gc: Option<bool>, ) -> Result<String>
where F: Into<String> + Debug,

Handles an event by calling the specified function with the event data.

Source

pub fn unload(self) -> Result<JSSandbox>

Unloads the Handlers from the sandbox and returns a JSSandbox with the JavaScript runtime loaded.

Source

pub fn snapshot(&mut self) -> Result<Snapshot>

Take a snapshot of the the current state of the sandbox. This can be used to restore the state of the sandbox later.

Source

pub fn restore(&mut self, snapshot: &Snapshot) -> Result<()>

Restore the state of the sandbox to a previous snapshot.

Source

pub fn interrupt_handle(&self) -> Arc<dyn InterruptHandle>

Get a handle to the interrupt handler for this sandbox, capable of interrupting guest execution.

Source

pub fn poisoned(&self) -> bool

Returns whether the sandbox is currently poisoned.

A poisoned sandbox is in an inconsistent state due to the guest not running to completion. This can happen when guest execution is interrupted (e.g., via InterruptHandle::kill()), when the guest panics, or when memory violations occur.

When poisoned, most operations will fail with PoisonedSandbox error. Use restore() with a snapshot or unload() to recover from a poisoned state.

Source

pub fn handle_event_with_monitor<F, M>( &mut self, func_name: F, event: String, monitor: &M, gc: Option<bool>, ) -> Result<String>
where F: Into<String> + Debug, M: MonitorSet,

Handles an event with execution monitoring.

The monitor enforces execution limits (time, CPU usage, etc.) and will terminate execution if limits are exceeded. If terminated, the sandbox will be poisoned and an error is returned.

§Fail-Closed Semantics

If the monitor fails to initialize, the handler is never executed. Execution cannot proceed unmonitored.

§Tuple Monitors (OR semantics)

Pass a tuple of monitors to enforce multiple limits. The first monitor to fire terminates execution, and the winning monitor’s name is logged:

let monitor = (
    WallClockMonitor::new(Duration::from_secs(5))?,
    CpuTimeMonitor::new(Duration::from_millis(500))?,
);
loaded.handle_event_with_monitor("handler", "{}".into(), &monitor, None)?;

§Arguments

func_name - The name of the handler function to call.
event - JSON string payload to pass to the handler.
monitor - The execution monitor (or tuple of monitors) to enforce limits. Tuples race all sub-monitors; the first to fire wins and its name is logged.
gc - Whether to run garbage collection after the call (defaults to true if None).

§Returns

The handler result string on success, or an error if execution failed or was terminated by the monitor. If terminated, the sandbox will be poisoned and subsequent calls will fail until restored or unloaded.

§Example

use hyperlight_js::WallClockMonitor;
use std::time::Duration;

let monitor = WallClockMonitor::new(Duration::from_secs(5))?;
let result = loaded.handle_event_with_monitor(
    "handler",
    "{}".to_string(),
    &monitor,
    None,
)?;
println!("Handler returned: {}", result);