Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -161,26 +161,30 @@ clean:
-rm -f src/js-host-api/index.d.ts

# TESTING
# On Windows, create surrogates on demand rather than pre-creating the pool in
# every test process. This leaves the maximum surrogate pool size unchanged.
test-env-command := if os() == "windows" { "$env:HYPERLIGHT_INITIAL_SURROGATES='0'; " } else { "" }

# Metrics tests cannot run with other tests they are marked as ignored so that cargo test works
# There may be tests that we really want to ignore so we cant just use --ignored and run then we have to
# specify the test name of the ignored tests that we want to run
# NOTE: If features is non-empty, the test will be ran with no-default-features + the given features
test target=default-target features="": (build target)
cd src/hyperlight-js && cargo test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }}
cd src/hyperlight-js && cargo test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} handle_termination --profile={{ if target == "debug" {"dev"} else { target } }} -- --ignored --nocapture
cd src/hyperlight-js && cargo test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} test_metrics --profile={{ if target == "debug" {"dev"} else { target } }} -- --ignored --nocapture
cargo test --manifest-path=./src/hyperlight-js-runtime/Cargo.toml --test=native_cli --profile={{ if target == "debug" {"dev"} else { target } }}
{{ test-env-command }}cd src/hyperlight-js && cargo test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }}
{{ test-env-command }}cd src/hyperlight-js && cargo test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} handle_termination --profile={{ if target == "debug" {"dev"} else { target } }} -- --ignored --nocapture
{{ test-env-command }}cd src/hyperlight-js && cargo test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} test_metrics --profile={{ if target == "debug" {"dev"} else { target } }} -- --ignored --nocapture
{{ test-env-command }}cargo test --manifest-path=./src/hyperlight-js-runtime/Cargo.toml --test=native_cli --profile={{ if target == "debug" {"dev"} else { target } }}
just test-native-modules {{ target }}

# Test with monitor features enabled (wall-clock and CPU time monitors)
# Note: We exclude test_metrics (requires process isolation, already run by `test`)
# and native_modules (requires custom guest runtime, run by `test-native-modules`)
test-monitors target=default-target:
cd src/hyperlight-js && cargo test --features monitor-wall-clock,monitor-cpu-time --profile={{ if target == "debug" {"dev"} else { target } }} -- --include-ignored --skip test_metrics --skip custom_native_module --skip builtin_modules_work_with_custom --skip console_log_works_with_custom --skip custom_globals_and_host_clock
{{ test-env-command }}cd src/hyperlight-js && cargo test --features monitor-wall-clock,monitor-cpu-time --profile={{ if target == "debug" {"dev"} else { target } }} -- --include-ignored --skip test_metrics --skip custom_native_module --skip builtin_modules_work_with_custom --skip console_log_works_with_custom --skip custom_globals_and_host_clock

test-js-host-api target=default-target features="": (build-js-host-api target features)
cargo test --manifest-path src/js-host-api/Cargo.toml --profile={{ if target == "debug" {"dev"} else { target } }}
cd src/js-host-api && npm test
{{ test-env-command }}cargo test --manifest-path src/js-host-api/Cargo.toml --profile={{ if target == "debug" {"dev"} else { target } }}
{{ test-env-command }}cd src/js-host-api && npm test

# Test custom native modules:
# 1. Runs the runtime crate's native_modules unit/pipeline tests (native binary)
Expand All @@ -191,11 +195,11 @@ test-native-modules target=default-target: (check-fixture-lock) (_test-native-mo

[private]
_test-native-modules-unit target=default-target:
cargo test --manifest-path=./src/hyperlight-js-runtime/Cargo.toml --test=native_modules --profile={{ if target == "debug" {"dev"} else { target } }}
{{ test-env-command }}cargo test --manifest-path=./src/hyperlight-js-runtime/Cargo.toml --test=native_modules --profile={{ if target == "debug" {"dev"} else { target } }}

[private]
_test-native-modules-manifest target=default-target:
{{ set-env-command }}HYPERLIGHT_JS_RUNTIME_MANIFEST_PATH="{{PWD}}/src/hyperlight-js-runtime/tests/fixtures/extended_runtime/Cargo.toml" {{ if os() == "windows" { ";" } else { "&&" } }} cargo test -p hyperlight-js --test native_modules --test runtime_build --profile={{ if target == "debug" {"dev"} else { target } }} -- --include-ignored --nocapture
{{ test-env-command }}{{ set-env-command }}HYPERLIGHT_JS_RUNTIME_MANIFEST_PATH="{{PWD}}/src/hyperlight-js-runtime/tests/fixtures/extended_runtime/Cargo.toml" {{ if os() == "windows" { ";" } else { "&&" } }} cargo test -p hyperlight-js --test native_modules --test runtime_build --profile={{ if target == "debug" {"dev"} else { target } }} -- --include-ignored --nocapture

[private]
_test-native-modules-restore target=default-target:
Expand Down
4 changes: 2 additions & 2 deletions docs/execution-monitors.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,7 +276,7 @@ loaded.handle_event_with_monitor("handler", "{}".into(), &monitor, None)?;
When a handler is terminated by a monitor:

1. `handle_event_with_monitor()` returns an error
2. The sandbox becomes "poisoned" (`sandbox.poisoned() == true`)
2. The sandbox becomes "poisoned" (`sandbox.status().is_poisoned()`)
3. To reuse the sandbox, call `sandbox.restore(&snapshot)`

```rust
Expand All @@ -289,7 +289,7 @@ let result = loaded_sandbox.handle_event_with_monitor(
None,
);

if result.is_err() && loaded_sandbox.poisoned() {
if result.is_err() && loaded_sandbox.status().is_poisoned() {
// Handler was killed - restore to continue using sandbox
loaded_sandbox.restore(&snapshot)?;
}
Expand Down
50 changes: 22 additions & 28 deletions src/hyperlight-js/src/sandbox/host_fn.rs
Original file line number Diff line number Diff line change
Expand Up @@ -159,9 +159,9 @@ pub(crate) fn decode_binaries(data: Vec<Bytes>) -> crate::Result<Vec<Vec<u8>>> {
.map_err(|e| crate::HyperlightError::Error(e.to_string()))
}

/// A module containing host functions that can be called from the guest JavaScript code.
/// Internal callback storage for a [`HostFunctionModule`].
#[derive(Default)]
pub struct HostModule {
pub(crate) struct HostModule {
functions: HashMap<String, HostFn>,
}

Expand All @@ -182,22 +182,8 @@ impl HostModule {
self.functions.keys().map(String::as_str)
}

/// Register a typed host function that can be called from the guest
/// JavaScript code.
///
/// Arguments are deserialized from JSON via serde and the return value
/// is serialized back to JSON automatically.
///
/// This variant does **not** support `Uint8Array`/`Buffer` arguments.
/// For binary data support, use the JS bridge API instead.
///
/// ```text
/// module.register("add", |a: i32, b: i32| a + b);
/// ```
///
/// Registering a function with the same `name` as an existing function
/// overwrites the previous registration.
pub fn register<Output: Serialize, Args: DeserializeOwned>(
/// Store a typed callback supplied through [`HostFunctionModule::register`].
pub(crate) fn register<Output: Serialize, Args: DeserializeOwned>(
&mut self,
name: impl Into<String>,
func: impl Function<Output, Args> + Send + Sync + 'static,
Expand All @@ -207,16 +193,8 @@ impl HostModule {
self
}

/// Register a host function for the JavaScript bridge (NAPI layer).
///
/// This is an internal API used by the `js-host-api` NAPI bridge.
/// Rust users should use [`register`](Self::register) instead, which
/// handles binary data transparently via serde.
///
/// The closure receives parsed `JsonValue` args and decoded binary
/// blobs directly. Return [`FnReturn::Json`] or [`FnReturn::Binary`].
#[doc(hidden)]
pub fn register_js(
/// Store a callback supplied through [`HostFunctionModule::register_js`].
pub(crate) fn register_js(
&mut self,
name: impl Into<String>,
func: impl Fn(JsonValue, Vec<Vec<u8>>) -> crate::Result<FnReturn> + Send + Sync + 'static,
Expand Down Expand Up @@ -316,6 +294,19 @@ impl HostFunctionModule {
}

/// Register a typed host function on this module.
///
/// Arguments are deserialized from JSON via serde and the return value
/// is serialized back to JSON automatically.
///
/// This variant does **not** support `Uint8Array`/`Buffer` arguments.
/// For binary data support, use the JS bridge API instead.
///
/// ```text
/// module.register("add", |a: i32, b: i32| a + b);
/// ```
///
/// Registering a function with the same `name` as an existing function
/// overwrites the previous registration.
pub fn register<Output: Serialize, Args: DeserializeOwned>(
&mut self,
name: impl Into<String>,
Expand All @@ -326,6 +317,9 @@ impl HostFunctionModule {
}

/// Register a JavaScript-bridge host function on this module.
///
/// The closure receives parsed JSON arguments and decoded binary blobs.
/// Return [`FnReturn::Json`] or [`FnReturn::Binary`].
#[doc(hidden)]
pub fn register_js(
&mut self,
Expand Down
8 changes: 1 addition & 7 deletions src/hyperlight-js/src/sandbox/js_sandbox.rs
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ pub const DEFAULT_MODULE_NAMESPACE: &str = "user";
/// Reserved namespaces that cannot be used for user modules.
///
/// The `host` namespace is reserved for host-function modules registered via
/// [`ProtoJSSandbox::host_module`].
/// [`SandboxBuilder::with_host_function_modules`](crate::SandboxBuilder::with_host_function_modules).
pub const RESERVED_NAMESPACES: &[&str] = &["host"];

/// Validates a module identifier (name or namespace).
Expand Down Expand Up @@ -375,12 +375,6 @@ impl JSSandbox {
self.modules.clear();
}

/// Returns whether the sandbox is currently poisoned.
#[deprecated(since = "0.4.0", note = "use status().is_poisoned()")]
pub fn poisoned(&self) -> bool {
self.inner.status().is_poisoned()
}

/// Returns the sandbox lifecycle status.
pub fn status(&self) -> SandboxStatus {
self.inner.status()
Expand Down
6 changes: 0 additions & 6 deletions src/hyperlight-js/src/sandbox/loaded_js_sandbox.rs
Original file line number Diff line number Diff line change
Expand Up @@ -248,12 +248,6 @@ impl LoadedJSSandbox {
self.inner.interrupt_handle()
}

/// Returns whether the sandbox is currently poisoned.
#[deprecated(since = "0.4.0", note = "use status().is_poisoned()")]
pub fn poisoned(&self) -> bool {
self.inner.status().is_poisoned()
}

/// Returns the sandbox lifecycle status.
pub fn status(&self) -> SandboxStatus {
self.inner.status()
Expand Down
87 changes: 3 additions & 84 deletions src/hyperlight-js/src/sandbox/proto_js_sandbox.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,16 @@ See the License for the specific language governing permissions and
limitations under the License.
*/
use std::collections::HashMap;
use std::fmt::Debug;
use std::time::SystemTime;

use anyhow::Context;
use hyperlight_host::sandbox::SandboxConfiguration;
use hyperlight_host::{GuestBinary, Result, UninitializedSandbox};
use serde::de::DeserializeOwned;
use serde::Serialize;
use tracing::{instrument, Level};

use super::js_sandbox::JSSandbox;
use super::sandbox_builder::SandboxBuilder;
use crate::sandbox::host_fn::{
host_function_dispatch, host_function_manifest, Function, HostModule,
};
use crate::sandbox::host_fn::{host_function_dispatch, host_function_manifest, HostModule};
use crate::sandbox::metrics::SandboxMetricsGuard;
use crate::sandbox::module_loader::ExternalModuleLoader;
use crate::HostPrintFn;
Expand All @@ -42,8 +37,8 @@ pub(super) fn current_time_micros() -> hyperlight_host::Result<u64> {

/// A fresh Hyperlight sandbox before the JavaScript runtime is loaded.
///
/// Register host resources, then call [`Self::load_runtime`] to create a
/// [`JSSandbox`]. Restore snapshots with [`crate::SandboxBuilder::from_snapshot`].
/// Configure host resources on [`SandboxBuilder`], then call [`Self::load_runtime`]
Comment thread
simongdavies marked this conversation as resolved.
Resolved
/// to create a [`JSSandbox`]. Restore snapshots with [`crate::SandboxBuilder::from_snapshot`].
pub struct ProtoJSSandbox {
inner: UninitializedSandbox,
host_modules: HashMap<String, HostModule>,
Expand Down Expand Up @@ -79,21 +74,6 @@ impl ProtoJSSandbox {
})
}

/// Install a custom file system for module resolution and loading.
///
/// Enables JavaScript module imports using the provided ~FileSystem~ implementation.
#[deprecated(
note = "Use SandboxBuilder::with_module_loader, which also works when restoring snapshots"
)]
#[instrument(err(Debug), skip_all, level=Level::INFO)]
pub fn set_module_loader<Fs: crate::resolver::FileSystem + Clone + 'static>(
mut self,
file_system: Fs,
) -> Result<Self> {
ExternalModuleLoader::new(file_system).register(&mut self.inner)?;
Ok(self)
}

/// Load the JavaScript runtime into the sandbox.
#[instrument(err(Debug), skip(self), level=Level::INFO)]
pub fn load_runtime(mut self) -> Result<JSSandbox> {
Expand All @@ -113,67 +93,6 @@ impl ProtoJSSandbox {

Comment thread
simongdavies marked this conversation as resolved.
Resolved
JSSandbox::new(multi_use_sandbox, host_functions)
}

/// Register a host module that can be called from the guest JavaScript code.
///
/// This method should be called **before** [`ProtoJSSandbox::load_runtime`], while
/// the sandbox is still in its "proto" (uninitialized) state. After
/// [`load_runtime`](Self::load_runtime) is called, the set of host modules and
/// functions is fixed for the resulting [`JSSandbox`].
///
/// Calling this method multiple times with the same `name` refers to the same
/// module; additional calls will reuse the existing module instance and allow
/// you to register more functions on it. The first call creates the module and
/// subsequent calls return the previously created module.
///
/// Module names are matched by exact string equality from the guest
/// JavaScript environment. They should be valid UTF‑8 strings and while there is
/// no explicit restriction on special characters, using simple, ASCII identifiers
/// (e.g. `"fs"`, `"net"`, `"my_module"`) is recommended for portability and clarity.
///
/// # Example
///
/// ```
/// # #![allow(deprecated)]
/// use hyperlight_js::SandboxBuilder;
///
/// // Create a proto sandbox and register a host function.
/// let mut sbox = SandboxBuilder::new().build()?;
///
/// // Register a module and a function on it before loading the runtime.
/// sbox.host_module("math").register("add", |a: i32, b: i32| a + b);
///
/// // Once all host modules/functions are registered, load the JS runtime.
/// let js_sandbox = sbox.load_runtime()?;
/// # Ok::<(), hyperlight_host::HyperlightError>(())
/// ```
#[deprecated(
note = "Use SandboxBuilder::with_host_function_modules, which also works when restoring snapshots"
)]
#[instrument(skip(self), level=Level::INFO)]
pub fn host_module(&mut self, name: impl Into<String> + Debug) -> &mut HostModule {
self.host_modules.entry(name.into()).or_default()
}

/// Register a host function that can be called from the guest JavaScript code.
/// This is equivalent to calling `sbox.host_module(module).register(name, func)`.
///
/// Registering a function with the same `module` and `name` as an existing function
/// overwrites the previous registration.
#[deprecated(
note = "Use SandboxBuilder::with_host_function_modules, which also works when restoring snapshots"
)]
#[instrument(err(Debug), skip(self, func), level=Level::INFO)]
pub fn register<Output: Serialize, Args: DeserializeOwned>(
&mut self,
module: impl Into<String> + Debug,
name: impl Into<String> + Debug,
func: impl Function<Output, Args> + Send + Sync + 'static,
) -> Result<()> {
#[allow(deprecated)]
self.host_module(module).register(name, func);
Ok(())
}
}

impl std::fmt::Debug for ProtoJSSandbox {
Expand Down
Loading
Loading