Updates for the latest hypleright version (#24)

simongdavies · web-flow · commit 5cd2ab98aed1 · 2026-03-02T10:34:25.000Z
Signed-off-by: Simon Davies &lt;simongdavies@users.noreply.github.com&gt;
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -11,10 +11,10 @@ repository = "https://github.com/hyperlight-dev/hyperlight-js"
 readme = "README.md"
 
 [workspace.dependencies]
-hyperlight-common = { version = "0.12",  default-features = false }
-hyperlight-guest-bin = { version = "0.12" }
-hyperlight-guest = { version = "0.12" }
-hyperlight-host = { version = "0.12", default-features = false, features = ["executable_heap", "init-paging"] }
+hyperlight-common = { git = "https://github.com/hyperlight-dev/hyperlight", rev = "620339aa95d508e8cbd1d38b4374f09090aade7b", default-features = false }
+hyperlight-guest-bin = { git = "https://github.com/hyperlight-dev/hyperlight", rev = "620339aa95d508e8cbd1d38b4374f09090aade7b" }
+hyperlight-guest = { git = "https://github.com/hyperlight-dev/hyperlight", rev = "620339aa95d508e8cbd1d38b4374f09090aade7b" }
+hyperlight-host = { git = "https://github.com/hyperlight-dev/hyperlight", rev = "620339aa95d508e8cbd1d38b4374f09090aade7b", default-features = false, features = ["executable_heap", "init-paging"] }
 hyperlight-js = { version = "0.1.1", path = "src/hyperlight-js" }
 hyperlight-js-runtime = { version = "0.1.1", path = "src/hyperlight-js-runtime" }
 
diff --git a/src/hyperlight-js/benches/benchmarks.rs b/src/hyperlight-js/benches/benchmarks.rs
@@ -197,7 +197,7 @@ fn handle_events_benchmark(c: &mut Criterion) {
                     let start = Instant::now();
                     let _ =
                         loaded_js_sandbox.handle_event("function1", event.to_string(), Some(gc));
-                    loaded_js_sandbox.restore(&snapshot).unwrap();
+                    loaded_js_sandbox.restore(snapshot.clone()).unwrap();
                     elapsed += start.elapsed();
                 }
             }
diff --git a/src/hyperlight-js/examples/interrupt/main.rs b/src/hyperlight-js/examples/interrupt/main.rs
@@ -114,7 +114,7 @@ fn main() -> Result<()> {
 
     // Demonstrate recovery from poisoned state
     println!("\n📸 Restoring sandbox from snapshot...");
-    loaded_sandbox.restore(&snapshot)?;
+    loaded_sandbox.restore(snapshot)?;
 
     println!("🔒 Poisoned after restore: {}", loaded_sandbox.poisoned());
     assert!(
diff --git a/src/hyperlight-js/src/sandbox/js_sandbox.rs b/src/hyperlight-js/src/sandbox/js_sandbox.rs
@@ -15,6 +15,7 @@ limitations under the License.
 */
 use std::collections::HashMap;
 use std::fmt::Debug;
+use std::sync::Arc;
 
 use hyperlight_host::sandbox::snapshot::Snapshot;
 use hyperlight_host::{new_error, MultiUseSandbox, Result};
@@ -30,7 +31,7 @@ pub struct JSSandbox {
     handlers: HashMap<String, Script>,
     // Snapshot of state before any handlers are added.
     // This is used to restore state back to a neutral JSSandbox.
-    snapshot: Snapshot,
+    snapshot: Arc<Snapshot>,
     // metric drop guard to manage sandbox metric
     _metric_guard: SandboxMetricsGuard<JSSandbox>,
 }
@@ -48,8 +49,11 @@ impl JSSandbox {
     }
 
     /// Creates a new `JSSandbox` from a `MultiUseSandbox` and a `Snapshot` of state before any handlers were added.
-    pub(crate) fn from_loaded(mut loaded: MultiUseSandbox, snapshot: Snapshot) -> Result<Self> {
-        loaded.restore(&snapshot)?;
+    pub(crate) fn from_loaded(
+        mut loaded: MultiUseSandbox,
+        snapshot: Arc<Snapshot>,
+    ) -> Result<Self> {
+        loaded.restore(snapshot.clone())?;
         Ok(Self {
             inner: loaded,
             handlers: HashMap::new(),
diff --git a/src/hyperlight-js/src/sandbox/loaded_js_sandbox.rs b/src/hyperlight-js/src/sandbox/loaded_js_sandbox.rs
@@ -36,7 +36,7 @@ pub struct LoadedJSSandbox {
     inner: MultiUseSandbox,
     // Snapshot of state before the sandbox was loaded and before any handlers were added.
     // This is used to restore state back to a JSSandbox.
-    snapshot: Snapshot,
+    snapshot: Arc<Snapshot>,
     // metric drop guard to manage sandbox metric
     _metric_guard: SandboxMetricsGuard<LoadedJSSandbox>,
 }
@@ -57,7 +57,7 @@ impl Drop for MonitorTask {
 
 impl LoadedJSSandbox {
     #[instrument(err(Debug), skip_all, level=Level::INFO)]
-    pub(super) fn new(inner: MultiUseSandbox, snapshot: Snapshot) -> Result<LoadedJSSandbox> {
+    pub(super) fn new(inner: MultiUseSandbox, snapshot: Arc<Snapshot>) -> Result<LoadedJSSandbox> {
         metrics::counter!(METRIC_SANDBOX_LOADS).increment(1);
         Ok(LoadedJSSandbox {
             inner,
@@ -107,13 +107,13 @@ impl LoadedJSSandbox {
     /// Take a snapshot of the the current state of the sandbox.
     /// This can be used to restore the state of the sandbox later.
     #[instrument(err(Debug), skip_all, level=Level::DEBUG)]
-    pub fn snapshot(&mut self) -> Result<Snapshot> {
+    pub fn snapshot(&mut self) -> Result<Arc<Snapshot>> {
         self.inner.snapshot()
     }
 
     /// Restore the state of the sandbox to a previous snapshot.
     #[instrument(err(Debug), skip_all, level=Level::DEBUG)]
-    pub fn restore(&mut self, snapshot: &Snapshot) -> Result<()> {
+    pub fn restore(&mut self, snapshot: Arc<Snapshot>) -> Result<()> {
         self.inner.restore(snapshot)?;
         Ok(())
     }
@@ -417,7 +417,7 @@ mod tests {
         assert_eq!(response_json["count"], 3);
 
         // Restore the snapshot
-        loaded_js_sandbox.restore(&snapshot).unwrap();
+        loaded_js_sandbox.restore(snapshot.clone()).unwrap();
 
         // Handle the event again, should reset to initial state
         let result = loaded_js_sandbox
@@ -447,7 +447,7 @@ mod tests {
             .unwrap_err();
 
         // restore to snapshot before unload/reload
-        reloaded_js_sandbox.restore(&snapshot).unwrap();
+        reloaded_js_sandbox.restore(snapshot.clone()).unwrap();
         // handler should be available again
         let result = reloaded_js_sandbox
             .handle_event("handler", get_static_counter_event(), gc)
diff --git a/src/hyperlight-js/src/sandbox/sandbox_builder.rs b/src/hyperlight-js/src/sandbox/sandbox_builder.rs
@@ -16,8 +16,8 @@ limitations under the License.
 #[cfg(target_os = "linux")]
 use std::time::Duration;
 
-use hyperlight_host::sandbox::{is_hypervisor_present, SandboxConfiguration};
-use hyperlight_host::{GuestBinary, HyperlightError, Result};
+use hyperlight_host::sandbox::SandboxConfiguration;
+use hyperlight_host::{is_hypervisor_present, GuestBinary, HyperlightError, Result};
 
 use super::proto_js_sandbox::ProtoJSSandbox;
 use crate::HostPrintFn;
@@ -28,16 +28,35 @@ pub struct SandboxBuilder {
     host_print_fn: Option<HostPrintFn>,
 }
 
-const MIN_STACK_SIZE: u64 = 256 * 1024;
-// The minimum heap size is 4096KB.
+/// The minimum scratch size for the JS runtime sandbox.
+///
+/// The scratch region provides writable physical memory for:
+///   - I/O buffers (input + output data)
+///   - Page table copies (proportional to snapshot size — our ~13 MB guest
+///     binary + heap produce ~72 KiB of page tables)
+///   - Dynamically allocated pages (GDT/IDT, stack growth, Copy-on-Write
+///     resolution during QuickJS initialisation)
+///   - Exception stack and metadata (2 pages at the top)
+///
+/// Hyperlight's default scratch (288 KiB) is far too small for the JS
+/// runtime guest: after fixed overheads there are only ~44 free pages,
+/// which are exhausted during init.  1 MiB (0x10_0000) matches
+/// hyperlight's own "large guest" test configuration and gives
+/// comfortable headroom.
+const MIN_SCRATCH_SIZE: usize = 0x10_0000; // 1 MiB
+
+/// The minimum heap size is 4 MiB.  The QuickJS engine needs a
+/// reasonable amount of heap during initialisation for builtins,
+/// global objects, and the bytecode compiler.  This lives in the
+/// identity-mapped snapshot region (NOT scratch).
 const MIN_HEAP_SIZE: u64 = 4096 * 1024;
 
 impl SandboxBuilder {
     /// Create a new SandboxBuilder
     pub fn new() -> Self {
         let mut config = SandboxConfiguration::default();
-        config.set_stack_size(MIN_STACK_SIZE);
         config.set_heap_size(MIN_HEAP_SIZE);
+        config.set_scratch_size(MIN_SCRATCH_SIZE);
 
         Self {
             config,
@@ -67,13 +86,14 @@ impl SandboxBuilder {
         self
     }
 
-    /// Set the guest stack size
-    /// This is the size of the stack that code executing in the guest can use.
-    /// If this value is too small then the guest will fail with a stack overflow error
-    /// The default value (and minimum) is set to the value of the MIN_STACK_SIZE const.
-    pub fn with_guest_stack_size(mut self, guest_stack_size: u64) -> Self {
-        if guest_stack_size > MIN_STACK_SIZE {
-            self.config.set_stack_size(guest_stack_size);
+    /// Set the guest scratch size in bytes.
+    /// The scratch region provides writable memory for the guest, including the
+    /// dynamically-sized stack. Increase this if your guest code needs deep
+    /// recursion or large local variables.
+    /// Values smaller than the default (288KiB) are ignored.
+    pub fn with_guest_scratch_size(mut self, guest_scratch_size: usize) -> Self {
+        if guest_scratch_size > MIN_SCRATCH_SIZE {
+            self.config.set_scratch_size(guest_scratch_size);
         }
         self
     }
diff --git a/src/hyperlight-js/tests/monitors.rs b/src/hyperlight-js/tests/monitors.rs
@@ -112,7 +112,7 @@ fn wall_clock_monitor_sandbox_recovers_with_restore() {
     assert!(loaded.poisoned(), "Should be poisoned after kill");
 
     // Restore from snapshot
-    loaded.restore(&snapshot).unwrap();
+    loaded.restore(snapshot.clone()).unwrap();
     assert!(!loaded.poisoned(), "Should not be poisoned after restore");
 
     // Should be able to run again
@@ -177,7 +177,7 @@ fn cpu_time_monitor_sandbox_recovers_with_restore() {
     assert!(loaded.poisoned(), "Should be poisoned after kill");
 
     // Restore from snapshot
-    loaded.restore(&snapshot).unwrap();
+    loaded.restore(snapshot.clone()).unwrap();
     assert!(!loaded.poisoned(), "Should not be poisoned after restore");
 
     // Should be able to run again
@@ -252,7 +252,7 @@ fn tuple_monitor_sandbox_recovers_with_restore() {
     assert!(loaded.poisoned(), "Should be poisoned after kill");
 
     // Restore and verify recovery
-    loaded.restore(&snapshot).unwrap();
+    loaded.restore(snapshot.clone()).unwrap();
     assert!(!loaded.poisoned(), "Should not be poisoned after restore");
 
     let monitor2 = (
diff --git a/src/hyperlight-js/tests/termination.rs b/src/hyperlight-js/tests/termination.rs
@@ -107,7 +107,7 @@ fn handle_termination() -> Result<()> {
     );
 
     // Restore the sandbox from snapshot
-    loaded_sandbox.restore(&snapshot)?;
+    loaded_sandbox.restore(snapshot)?;
 
     // Verify sandbox is no longer poisoned after restore
     assert!(
diff --git a/src/js-host-api/README.md b/src/js-host-api/README.md
@@ -50,15 +50,15 @@ Creates and configures a new sandbox.
 
 **Methods:**
 - `setHeapSize(bytes: number)` → `this` — Set guest heap size (must be > 0, chainable)
-- `setStackSize(bytes: number)` → `this` — Set guest stack size (must be > 0, chainable)
+- `setScratchSize(bytes: number)` → `this` — Set guest scratch size, includes stack (must be > 0, chainable)
 - `setInputBufferSize(bytes: number)` → `this` — Set guest input buffer size (must be > 0, chainable)
 - `setOutputBufferSize(bytes: number)` → `this` — Set guest output buffer size (must be > 0, chainable)
 - `build()` → `Promise<ProtoJSSandbox>` — Builds a proto sandbox ready to load the JavaScript runtime
 
 ```javascript
 const builder = new SandboxBuilder()
     .setHeapSize(8 * 1024 * 1024)
-    .setStackSize(512 * 1024);
+    .setScratchSize(1024 * 1024);
 const protoSandbox = await builder.build();
 ```
 
@@ -237,9 +237,8 @@ All errors thrown by the API include a `code` property for programmatic handling
 |------|---------|
 | `ERR_INVALID_ARG` | Bad argument (empty handler name, zero timeout, etc.) |
 | `ERR_CONSUMED` | Object already consumed (e.g., calling `loadRuntime()` twice) |
-| `ERR_POISONED` | Sandbox is in an inconsistent state (after timeout kill, guest abort, etc.) — restore from snapshot or unload |
+| `ERR_POISONED` | Sandbox is in an inconsistent state (after timeout kill, guest abort, stack overflow, etc.) — restore from snapshot or unload |
 | `ERR_CANCELLED` | Execution was cancelled (by monitor timeout or manual `kill()`) |
-| `ERR_STACK_OVERFLOW` | Guest code caused a stack overflow |
 | `ERR_GUEST_ABORT` | Guest code aborted |
 | `ERR_INTERNAL` | Unexpected internal error |
 
@@ -251,8 +250,8 @@ try {
         case 'ERR_CANCELLED':
             console.log('Execution was cancelled');
             break;
-        case 'ERR_STACK_OVERFLOW':
-            console.log('Stack overflow in guest code');
+        case 'ERR_POISONED':
+            console.log('Sandbox is poisoned (e.g. stack overflow, timeout)');
             break;
         default:
             console.log(`Unexpected error [${error.code}]: ${error.message}`);
diff --git a/src/js-host-api/examples/README.md b/src/js-host-api/examples/README.md
@@ -126,7 +126,7 @@ const { SandboxBuilder } = require('../lib.js');
 async function main() {
     const builder = new SandboxBuilder();
     builder.setHeapSize(8 * 1024 * 1024);   // Set heap size
-    builder.setStackSize(512 * 1024);        // Set stack size
+    builder.setScratchSize(1024 * 1024);        // Set scratch size (includes stack)
     const protoSandbox = await builder.build(); // Build sandbox
 }
 main();
diff --git a/src/js-host-api/examples/simple.js b/src/js-host-api/examples/simple.js
@@ -9,7 +9,7 @@ async function main() {
     console.log('1. Creating sandbox builder...');
     const builder = new SandboxBuilder();
     builder.setHeapSize(8 * 1024 * 1024); // 8MB heap
-    builder.setStackSize(512 * 1024); // 512KB stack
+    builder.setScratchSize(1024 * 1024); // 1MB scratch (includes stack)
     console.log('   ✓ Builder configured\n');
 
     // Step 2: Build the proto sandbox (async — returns a Promise)
diff --git a/src/js-host-api/lib.js b/src/js-host-api/lib.js
@@ -168,7 +168,12 @@ ProtoJSSandbox.prototype.loadRuntime = wrapAsync(ProtoJSSandbox.prototype.loadRu
 // SandboxBuilder — async build + sync setters
 SandboxBuilder.prototype.build = wrapAsync(SandboxBuilder.prototype.build);
 
-for (const method of ['setHeapSize', 'setStackSize', 'setInputBufferSize', 'setOutputBufferSize']) {
+for (const method of [
+    'setHeapSize',
+    'setScratchSize',
+    'setInputBufferSize',
+    'setOutputBufferSize',
+]) {
     const orig = SandboxBuilder.prototype[method];
     if (!orig) throw new Error(`Cannot wrap missing method: SandboxBuilder.${method}`);
     SandboxBuilder.prototype[method] = wrapSync(orig);
diff --git a/src/js-host-api/src/lib.rs b/src/js-host-api/src/lib.rs
@@ -95,8 +95,6 @@ enum ErrorCode {
     Poisoned,
     /// Execution was cancelled by the host (monitor timeout or manual `kill()`).
     Cancelled,
-    /// Guest stack overflow — increase stack size or reduce recursion depth.
-    StackOverflow,
     /// Guest abort (trap, panic, or fatal error in guest code).
     GuestAbort,
     /// Invalid arguments (bad types, empty names, zero sizes).
@@ -113,7 +111,6 @@ impl ErrorCode {
         match self {
             Self::Poisoned => "ERR_POISONED",
             Self::Cancelled => "ERR_CANCELLED",
-            Self::StackOverflow => "ERR_STACK_OVERFLOW",
             Self::GuestAbort => "ERR_GUEST_ABORT",
             Self::InvalidArg => "ERR_INVALID_ARG",
             Self::Consumed => "ERR_CONSUMED",
@@ -159,7 +156,6 @@ fn to_napi_error(err: HyperlightError) -> napi::Error {
         HyperlightError::PoisonedSandbox => ErrorCode::Poisoned,
         HyperlightError::ExecutionCanceledByHost() => ErrorCode::Cancelled,
         HyperlightError::JsonConversionFailure(_) => ErrorCode::InvalidArg,
-        HyperlightError::StackOverflow() => ErrorCode::StackOverflow,
         HyperlightError::GuestAborted(_, _) => ErrorCode::GuestAbort,
         _ => ErrorCode::Internal,
     };
@@ -226,7 +222,7 @@ pub struct SnapshotWrapper {
 /// ```js
 /// const proto = await new SandboxBuilder()
 ///     .setHeapSize(8 * 1024 * 1024)
-///     .setStackSize(512 * 1024)
+///     .setScratchSize(1024 * 1024)
 ///     .build();
 /// ```
 #[napi(js_name = "SandboxBuilder")]
@@ -311,20 +307,21 @@ impl SandboxBuilderWrapper {
         self.with_inner(|b| b.with_guest_input_buffer_size(size as usize))
     }
 
-    /// Set the guest stack size in bytes.
+    /// Set the guest scratch size in bytes.
     ///
-    /// Controls how much stack space is available for guest code execution.
-    /// Deep recursion or large local variables need a bigger stack.
+    /// Controls how much scratch space (which includes the stack) is available
+    /// for guest code execution. Deep recursion or large local variables need
+    /// a bigger scratch region.
     ///
-    /// @param size - Stack size in bytes (must be > 0)
+    /// @param size - Scratch size in bytes (must be > 0)
     /// @returns this (for chaining)
     /// @throws If size is 0
     #[napi]
-    pub fn set_stack_size(&self, size: u32) -> napi::Result<&Self> {
+    pub fn set_scratch_size(&self, size: u32) -> napi::Result<&Self> {
         if size == 0 {
-            return Err(invalid_arg_error("Stack size must be greater than 0"));
+            return Err(invalid_arg_error("Scratch size must be greater than 0"));
         }
-        self.with_inner(|b| b.with_guest_stack_size(size as u64))
+        self.with_inner(|b| b.with_guest_scratch_size(size as usize))
     }
 
     /// Set the guest heap size in bytes.
@@ -834,9 +831,7 @@ impl LoadedJSSandboxWrapper {
         })
         .await
         .map_err(join_error)??;
-        Ok(SnapshotWrapper {
-            inner: Arc::new(snapshot),
-        })
+        Ok(SnapshotWrapper { inner: snapshot })
     }
 
     /// Restore the sandbox to a previously captured snapshot state.
@@ -858,7 +853,7 @@ impl LoadedJSSandboxWrapper {
             let sandbox = guard
                 .as_mut()
                 .ok_or_else(|| consumed_error("LoadedJSSandbox"))?;
-            let result = sandbox.restore(&snap).map_err(to_napi_error);
+            let result = sandbox.restore(snap).map_err(to_napi_error);
             poisoned_flag.store(sandbox.poisoned(), Ordering::Release);
             result
         })
diff --git a/src/js-host-api/tests/sandbox.test.js b/src/js-host-api/tests/sandbox.test.js
@@ -22,7 +22,7 @@ describe('SandboxBuilder', () => {
         const builder = new SandboxBuilder();
         const result = builder
             .setHeapSize(8 * 1024 * 1024)
-            .setStackSize(512 * 1024)
+            .setScratchSize(1024 * 1024)
             .setInputBufferSize(4096)
             .setOutputBufferSize(4096);
         expect(result).toBe(builder);
@@ -53,9 +53,9 @@ describe('SandboxBuilder', () => {
         expectThrowsWithCode(() => builder.setHeapSize(0), 'ERR_INVALID_ARG');
     });
 
-    it('should reject zero stack size', () => {
+    it('should reject zero scratch size', () => {
         const builder = new SandboxBuilder();
-        expectThrowsWithCode(() => builder.setStackSize(0), 'ERR_INVALID_ARG');
+        expectThrowsWithCode(() => builder.setScratchSize(0), 'ERR_INVALID_ARG');
     });
 
     it('should reject zero input buffer size', () => {

Original file line number	Diff line number	Diff line change
`@@ -197,7 +197,7 @@ fn handle_events_benchmark(c: &mut Criterion) {`
`197`	`197`	`let start = Instant::now();`
`198`	`198`	`let _ =`
`199`	`199`	`loaded_js_sandbox.handle_event("function1", event.to_string(), Some(gc));`
`200`		`- loaded_js_sandbox.restore(&snapshot).unwrap();`
	`200`	`+ loaded_js_sandbox.restore(snapshot.clone()).unwrap();`
`201`	`201`	`elapsed += start.elapsed();`
`202`	`202`	`}`
`203`	`203`	`}`