[host] added GuestEnvironment struct

danbugs · danbugs · commit 82b9772b3cca · 2025-06-12T17:17:34.000Z
The GuestEnvironment struct contains two blobs of data. One identifiable as a guest binary,
and one undifferentiated guest blob. This GuestEnvironment is now used to create a new
sandbox in place of just a guest binary. There are TryFrom impls to be able to convert from
a guest binary to a GuestEnvironment, so this isn't a breaking change.

Signed-off-by: danbugs &lt;danilochiarlone@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ use hyperlight_host::{UninitializedSandbox, MultiUseSandbox, func::HostFunction0
 fn main() -> hyperlight_host::Result<()> {
     // Create an uninitialized sandbox with a guest binary
     let mut uninitialized_sandbox = UninitializedSandbox::new(
-        hyperlight_host::GuestBinary::FilePath(hyperlight_testing::simple_guest_as_string().unwrap()),
+        hyperlight_host::GuestBlob::FilePath(hyperlight_testing::simple_guest_as_string().unwrap()),
         None // default configuration
     )?;
 
diff --git a/fuzz/fuzz_targets/guest_call.rs b/fuzz/fuzz_targets/guest_call.rs
@@ -19,7 +19,7 @@ limitations under the License.
 use std::sync::{Mutex, OnceLock};
 
 use hyperlight_host::func::{ParameterValue, ReturnType};
-use hyperlight_host::sandbox::uninitialized::GuestBinary;
+use hyperlight_host::sandbox::uninitialized::GuestBlob;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
 use hyperlight_host::{MultiUseSandbox, UninitializedSandbox};
@@ -33,7 +33,7 @@ fuzz_target!(
     init: {
 
         let u_sbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
+            GuestBlob::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
             None,
         )
         .unwrap();
diff --git a/fuzz/fuzz_targets/host_call.rs b/fuzz/fuzz_targets/host_call.rs
@@ -19,7 +19,7 @@ limitations under the License.
 use std::sync::{Mutex, OnceLock};
 
 use hyperlight_host::func::{ParameterValue, ReturnType};
-use hyperlight_host::sandbox::uninitialized::GuestBinary;
+use hyperlight_host::sandbox::uninitialized::GuestBlob;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
 use hyperlight_host::{HyperlightError, MultiUseSandbox, UninitializedSandbox};
@@ -32,7 +32,7 @@ static SANDBOX: OnceLock<Mutex<MultiUseSandbox>> = OnceLock::new();
 fuzz_target!(
     init: {
         let u_sbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
+            GuestBlob::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
             None
         )
         .unwrap();
diff --git a/fuzz/fuzz_targets/host_print.rs b/fuzz/fuzz_targets/host_print.rs
@@ -2,7 +2,7 @@
 
 use std::sync::{Mutex, OnceLock};
 
-use hyperlight_host::sandbox::uninitialized::GuestBinary;
+use hyperlight_host::sandbox::uninitialized::GuestBlob;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
 use hyperlight_host::{MultiUseSandbox, UninitializedSandbox};
@@ -18,7 +18,7 @@ static SANDBOX: OnceLock<Mutex<MultiUseSandbox>> = OnceLock::new();
 fuzz_target!(
     init: {
         let u_sbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
+            GuestBlob::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
             None,
         )
         .unwrap();
diff --git a/src/hyperlight_host/benches/benchmarks.rs b/src/hyperlight_host/benches/benchmarks.rs
@@ -15,7 +15,7 @@ limitations under the License.
 */
 
 use criterion::{Criterion, criterion_group, criterion_main};
-use hyperlight_host::GuestBinary;
+use hyperlight_host::GuestBlob;
 use hyperlight_host::sandbox::{
     Callable, MultiUseSandbox, SandboxConfiguration, UninitializedSandbox,
 };
@@ -25,7 +25,7 @@ use hyperlight_testing::simple_guest_as_string;
 
 fn create_uninit_sandbox() -> UninitializedSandbox {
     let path = simple_guest_as_string().unwrap();
-    UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap()
+    UninitializedSandbox::new(GuestBlob::FilePath(path), None).unwrap()
 }
 
 fn create_multiuse_sandbox() -> MultiUseSandbox {
@@ -70,7 +70,7 @@ fn guest_call_benchmark(c: &mut Criterion) {
         config.set_heap_size(SIZE as u64 * 15);
 
         let sandbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_as_string().unwrap()),
+            GuestBlob::FilePath(simple_guest_as_string().unwrap()),
             Some(config),
         )
         .unwrap();
diff --git a/src/hyperlight_host/examples/func_ctx/main.rs b/src/hyperlight_host/examples/func_ctx/main.rs
@@ -18,15 +18,15 @@ use hyperlight_host::func::call_ctx::MultiUseGuestCallContext;
 use hyperlight_host::sandbox::{Callable, MultiUseSandbox, UninitializedSandbox};
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
-use hyperlight_host::{GuestBinary, Result};
+use hyperlight_host::{GuestBlob, Result};
 use hyperlight_testing::simple_guest_as_string;
 
 fn main() {
     // create a new `MultiUseSandbox` configured to run the `simpleguest.exe`
     // test guest binary
     let sbox1: MultiUseSandbox = {
         let path = simple_guest_as_string().unwrap();
-        let u_sbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None).unwrap();
+        let u_sbox = UninitializedSandbox::new(GuestBlob::FilePath(path), None).unwrap();
         u_sbox.evolve(Noop::default())
     }
     .unwrap();
diff --git a/src/hyperlight_host/examples/guest-debugging/main.rs b/src/hyperlight_host/examples/guest-debugging/main.rs
@@ -43,9 +43,7 @@ fn main() -> hyperlight_host::Result<()> {
 
     // Create an uninitialized sandbox with a guest binary
     let mut uninitialized_sandbox = UninitializedSandbox::new(
-        hyperlight_host::GuestBinary::FilePath(
-            hyperlight_testing::simple_guest_as_string().unwrap(),
-        ),
+        hyperlight_host::GuestBlob::FilePath(hyperlight_testing::simple_guest_as_string().unwrap()),
         cfg, // sandbox configuration
     )?;
 
diff --git a/src/hyperlight_host/examples/hello-world/main.rs b/src/hyperlight_host/examples/hello-world/main.rs
@@ -23,9 +23,7 @@ use hyperlight_host::{MultiUseSandbox, UninitializedSandbox};
 fn main() -> hyperlight_host::Result<()> {
     // Create an uninitialized sandbox with a guest binary
     let mut uninitialized_sandbox = UninitializedSandbox::new(
-        hyperlight_host::GuestBinary::FilePath(
-            hyperlight_testing::simple_guest_as_string().unwrap(),
-        ),
+        hyperlight_host::GuestBlob::FilePath(hyperlight_testing::simple_guest_as_string().unwrap()),
         None, // default configuration
     )?;
 
diff --git a/src/hyperlight_host/examples/logging/main.rs b/src/hyperlight_host/examples/logging/main.rs
@@ -22,7 +22,7 @@ use hyperlight_host::sandbox::Callable;
 use hyperlight_host::sandbox::uninitialized::UninitializedSandbox;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
-use hyperlight_host::{GuestBinary, MultiUseSandbox, Result};
+use hyperlight_host::{GuestBlob, MultiUseSandbox, Result};
 use hyperlight_testing::simple_guest_as_string;
 
 fn fn_writer(_msg: String) -> Result<i32> {
@@ -44,7 +44,7 @@ fn main() -> Result<()> {
         let path = hyperlight_guest_path.clone();
         let res: Result<()> = {
             // Create a new sandbox.
-            let mut usandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)?;
+            let mut usandbox = UninitializedSandbox::new(GuestBlob::FilePath(path), None)?;
             usandbox.register_print(fn_writer)?;
 
             // Initialize the sandbox.
@@ -78,7 +78,7 @@ fn main() -> Result<()> {
 
     // Create a new sandbox.
     let usandbox =
-        UninitializedSandbox::new(GuestBinary::FilePath(hyperlight_guest_path.clone()), None)?;
+        UninitializedSandbox::new(GuestBlob::FilePath(hyperlight_guest_path.clone()), None)?;
 
     // Initialize the sandbox.
 
diff --git a/src/hyperlight_host/examples/metrics/main.rs b/src/hyperlight_host/examples/metrics/main.rs
@@ -22,7 +22,7 @@ use hyperlight_host::sandbox::Callable;
 use hyperlight_host::sandbox::uninitialized::UninitializedSandbox;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
-use hyperlight_host::{GuestBinary, MultiUseSandbox, Result};
+use hyperlight_host::{GuestBlob, MultiUseSandbox, Result};
 use hyperlight_testing::simple_guest_as_string;
 
 // Run this rust example with the flag --features "function_call_metrics" to enable more metrics to be emitted
@@ -55,7 +55,7 @@ fn do_hyperlight_stuff() {
         let path = hyperlight_guest_path.clone();
         let handle = spawn(move || -> Result<()> {
             // Create a new sandbox.
-            let mut usandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)?;
+            let mut usandbox = UninitializedSandbox::new(GuestBlob::FilePath(path), None)?;
             usandbox.register_print(fn_writer)?;
 
             // Initialize the sandbox.
@@ -89,7 +89,7 @@ fn do_hyperlight_stuff() {
 
     // Create a new sandbox.
     let usandbox =
-        UninitializedSandbox::new(GuestBinary::FilePath(hyperlight_guest_path.clone()), None)
+        UninitializedSandbox::new(GuestBlob::FilePath(hyperlight_guest_path.clone()), None)
             .expect("Failed to create UninitializedSandbox");
 
     // Initialize the sandbox.
diff --git a/src/hyperlight_host/examples/tracing-chrome/main.rs b/src/hyperlight_host/examples/tracing-chrome/main.rs
@@ -17,7 +17,7 @@ limitations under the License.
 use hyperlight_host::sandbox::uninitialized::UninitializedSandbox;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
-use hyperlight_host::{GuestBinary, MultiUseSandbox, Result};
+use hyperlight_host::{GuestBlob, MultiUseSandbox, Result};
 use hyperlight_testing::simple_guest_as_string;
 use tracing_chrome::ChromeLayerBuilder;
 use tracing_subscriber::prelude::*;
@@ -32,7 +32,7 @@ fn main() -> Result<()> {
         simple_guest_as_string().expect("Cannot find the guest binary at the expected location.");
 
     // Create a new sandbox.
-    let usandbox = UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_path), None)?;
+    let usandbox = UninitializedSandbox::new(GuestBlob::FilePath(simple_guest_path), None)?;
 
     let mut sbox = usandbox
         .evolve(Noop::<UninitializedSandbox, MultiUseSandbox>::default())
diff --git a/src/hyperlight_host/examples/tracing-otlp/main.rs b/src/hyperlight_host/examples/tracing-otlp/main.rs
@@ -30,7 +30,7 @@ use hyperlight_host::sandbox::Callable;
 use hyperlight_host::sandbox::uninitialized::UninitializedSandbox;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
-use hyperlight_host::{GuestBinary, MultiUseSandbox, Result as HyperlightResult};
+use hyperlight_host::{GuestBlob, MultiUseSandbox, Result as HyperlightResult};
 use hyperlight_testing::simple_guest_as_string;
 use opentelemetry::trace::TracerProvider;
 use opentelemetry::{KeyValue, global};
@@ -129,7 +129,7 @@ fn run_example(wait_input: bool) -> HyperlightResult<()> {
 
                 // Create a new sandbox.
                 let mut usandbox =
-                    UninitializedSandbox::new(GuestBinary::FilePath(path.clone()), None)?;
+                    UninitializedSandbox::new(GuestBlob::FilePath(path.clone()), None)?;
                 usandbox.register_print(fn_writer)?;
 
                 // Initialize the sandbox.
diff --git a/src/hyperlight_host/examples/tracing-tracy/main.rs b/src/hyperlight_host/examples/tracing-tracy/main.rs
@@ -17,7 +17,7 @@ limitations under the License.
 use hyperlight_host::sandbox::uninitialized::UninitializedSandbox;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
-use hyperlight_host::{GuestBinary, MultiUseSandbox, Result};
+use hyperlight_host::{GuestBlob, MultiUseSandbox, Result};
 use hyperlight_testing::simple_guest_as_string;
 use tracing_subscriber::EnvFilter;
 use tracing_subscriber::layer::SubscriberExt;
@@ -38,7 +38,7 @@ fn main() -> Result<()> {
         simple_guest_as_string().expect("Cannot find the guest binary at the expected location.");
 
     // Create a new sandbox.
-    let usandbox = UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_path), None)?;
+    let usandbox = UninitializedSandbox::new(GuestBlob::FilePath(simple_guest_path), None)?;
 
     let mut sbox = usandbox
         .evolve(Noop::<UninitializedSandbox, MultiUseSandbox>::default())
diff --git a/src/hyperlight_host/examples/tracing/main.rs b/src/hyperlight_host/examples/tracing/main.rs
@@ -23,7 +23,7 @@ use hyperlight_host::sandbox::Callable;
 use hyperlight_host::sandbox::uninitialized::UninitializedSandbox;
 use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
 use hyperlight_host::sandbox_state::transition::Noop;
-use hyperlight_host::{GuestBinary, MultiUseSandbox, Result};
+use hyperlight_host::{GuestBlob, MultiUseSandbox, Result};
 use hyperlight_testing::simple_guest_as_string;
 use tracing_forest::ForestLayer;
 use tracing_subscriber::layer::SubscriberExt;
@@ -72,7 +72,7 @@ fn run_example() -> Result<()> {
             let _entered = span.enter();
 
             // Create a new sandbox.
-            let mut usandbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)?;
+            let mut usandbox = UninitializedSandbox::new(GuestBlob::FilePath(path), None)?;
             usandbox.register_print(fn_writer)?;
 
             // Initialize the sandbox.
@@ -105,7 +105,7 @@ fn run_example() -> Result<()> {
 
     // Create a new sandbox.
     let usandbox =
-        UninitializedSandbox::new(GuestBinary::FilePath(hyperlight_guest_path.clone()), None)?;
+        UninitializedSandbox::new(GuestBlob::FilePath(hyperlight_guest_path.clone()), None)?;
 
     // Initialize the sandbox.
 
diff --git a/src/hyperlight_host/src/func/call_ctx.rs b/src/hyperlight_host/src/func/call_ctx.rs
@@ -114,13 +114,13 @@ mod tests {
     use crate::sandbox::Callable;
     use crate::sandbox_state::sandbox::EvolvableSandbox;
     use crate::sandbox_state::transition::Noop;
-    use crate::{GuestBinary, HyperlightError, MultiUseSandbox, Result, UninitializedSandbox};
+    use crate::{GuestBlob, HyperlightError, MultiUseSandbox, Result, UninitializedSandbox};
 
     fn new_uninit() -> Result<UninitializedSandbox> {
         let path = simple_guest_as_string().map_err(|e| {
             HyperlightError::Error(format!("failed to get simple guest path ({e:?})"))
         })?;
-        UninitializedSandbox::new(GuestBinary::FilePath(path), None)
+        UninitializedSandbox::new(GuestBlob::FilePath(path), None)
     }
 
     /// Test to create a `MultiUseSandbox`, then call several guest functions
diff --git a/src/hyperlight_host/src/hypervisor/mod.rs b/src/hyperlight_host/src/hypervisor/mod.rs
@@ -454,7 +454,7 @@ pub(crate) mod tests {
     #[cfg(gdb)]
     use crate::hypervisor::DbgMemAccessHandlerCaller;
     use crate::mem::ptr::RawPtr;
-    use crate::sandbox::uninitialized::GuestBinary;
+    use crate::sandbox::uninitialized::GuestBlob;
     #[cfg(any(crashdump, gdb))]
     use crate::sandbox::uninitialized::SandboxRuntimeConfig;
     use crate::sandbox::uninitialized_evolve::set_up_hypervisor_partition;
@@ -503,7 +503,7 @@ pub(crate) mod tests {
         #[cfg(any(crashdump, gdb))]
         let rt_cfg: SandboxRuntimeConfig = Default::default();
         let sandbox =
-            UninitializedSandbox::new(GuestBinary::FilePath(filename.clone()), Some(config))?;
+            UninitializedSandbox::new(GuestBlob::FilePath(filename.clone()), Some(config))?;
         let (_hshm, mut gshm) = sandbox.mgr.build();
         let mut vm = set_up_hypervisor_partition(
             &mut gshm,
diff --git a/src/hyperlight_host/src/lib.rs b/src/hyperlight_host/src/lib.rs
@@ -82,8 +82,8 @@ pub use sandbox::MultiUseSandbox;
 pub use sandbox::UninitializedSandbox;
 /// The re-export for the `is_hypervisor_present` type
 pub use sandbox::is_hypervisor_present;
-/// The re-export for the `GuestBinary` type
-pub use sandbox::uninitialized::GuestBinary;
+/// The re-export for the `GuestBlob` type
+pub use sandbox::uninitialized::GuestBlob;
 
 /// The re-export for the `MultiUseGuestCallContext` type`
 pub use crate::func::call_ctx::MultiUseGuestCallContext;
diff --git a/src/hyperlight_host/src/metrics/mod.rs b/src/hyperlight_host/src/metrics/mod.rs
@@ -95,15 +95,15 @@ mod tests {
     use super::*;
     use crate::sandbox_state::sandbox::EvolvableSandbox;
     use crate::sandbox_state::transition::Noop;
-    use crate::{GuestBinary, UninitializedSandbox};
+    use crate::{GuestBlob, UninitializedSandbox};
 
     #[test]
     fn test_metrics_are_emitted() {
         let recorder = metrics_util::debugging::DebuggingRecorder::new();
         let snapshotter = recorder.snapshotter();
         let snapshot = with_local_recorder(&recorder, || {
             let uninit = UninitializedSandbox::new(
-                GuestBinary::FilePath(simple_guest_as_string().unwrap()),
+                GuestBlob::FilePath(simple_guest_as_string().unwrap()),
                 None,
             )
             .unwrap();
diff --git a/src/hyperlight_host/src/sandbox/initialized_multi_use.rs b/src/hyperlight_host/src/sandbox/initialized_multi_use.rs
diff --git a/src/hyperlight_host/src/sandbox/mod.rs b/src/hyperlight_host/src/sandbox/mod.rs
diff --git a/src/hyperlight_host/src/sandbox/uninitialized.rs b/src/hyperlight_host/src/sandbox/uninitialized.rs
diff --git a/src/hyperlight_host/src/sandbox/uninitialized_evolve.rs b/src/hyperlight_host/src/sandbox/uninitialized_evolve.rs
diff --git a/src/hyperlight_host/tests/common/mod.rs b/src/hyperlight_host/tests/common/mod.rs
diff --git a/src/hyperlight_host/tests/integration_test.rs b/src/hyperlight_host/tests/integration_test.rs
diff --git a/src/hyperlight_host/tests/sandbox_host_tests.rs b/src/hyperlight_host/tests/sandbox_host_tests.rs
diff --git a/src/hyperlight_host/tests/wit_test.rs b/src/hyperlight_host/tests/wit_test.rs
