hyperlight_host/sandbox/

uninitialized.rs

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025 The Hyperlight Authors.

use std::fmt::Debug;
use std::option::Option;
use std::path::PathBuf;
use std::sync::{Arc, Mutex};

use tracing::{Span, instrument};
use tracing_core::LevelFilter;

use super::host_funcs::FunctionRegistry;
use super::snapshot::Snapshot;
use super::uninitialized_evolve::evolve_impl_multi_use;
use crate::func::host_functions::{HostFunction, register_host_function};
use crate::func::{ParameterTuple, SupportedReturnType};
#[cfg(feature = "build-metadata")]
use crate::log_build_details;
use crate::mem::memory_region::{DEFAULT_GUEST_BLOB_MEM_FLAGS, MemoryRegionFlags};
use crate::mem::mgr::SandboxMemoryManager;
use crate::mem::shared_mem::{ExclusiveSharedMemory, SharedMemory};
use crate::sandbox::SandboxConfiguration;
use crate::{MultiUseSandbox, Result, new_error};

#[cfg(any(crashdump, gdb))]
#[derive(Clone, Debug, Default)]
pub(crate) struct SandboxRuntimeConfig {
    #[cfg(crashdump)]
    pub(crate) binary_path: Option<PathBuf>,
    #[cfg(gdb)]
    pub(crate) debug_info: Option<super::config::DebugInfo>,
    #[cfg(crashdump)]
    pub(crate) guest_core_dump: bool,
    /// The original entry point address of the loaded guest binary
    /// (load_addr + ELF entry offset). Used for AT_ENTRY in core dumps
    /// so GDB can compute the correct load offset for PIE binaries.
    ///
    /// `None` until resolved from the snapshot's `NextAction::Initialise`
    /// in `set_up_hypervisor_partition`.
    #[cfg(crashdump)]
    pub(crate) entry_point: Option<u64>,
}

/// A preliminary sandbox that represents allocated memory and registered host functions,
/// but has not yet created the underlying virtual machine.
///
/// This struct holds the configuration and setup needed for a sandbox without actually
/// creating the VM. It allows you to:
/// - Set up memory layout and load guest binary data
/// - Register host functions that will be available to the guest
/// - Configure sandbox settings before VM creation
///
/// The virtual machine is not created until you call [`evolve`](Self::evolve) to transform
/// this into an initialized [`MultiUseSandbox`].
pub struct UninitializedSandbox {
    /// Registered host functions
    pub(crate) host_funcs: Arc<Mutex<FunctionRegistry>>,
    /// The memory manager for the sandbox.
    pub(crate) mgr: SandboxMemoryManager<ExclusiveSharedMemory>,
    pub(crate) max_guest_log_level: Option<LevelFilter>,
    pub(crate) config: SandboxConfiguration,
    #[cfg(any(crashdump, gdb))]
    pub(crate) rt_cfg: SandboxRuntimeConfig,
    pub(crate) load_info: crate::mem::exe::LoadInfo,
    // This is needed to convey the stack pointer between the snapshot
    // and the HyperlightVm creation
    pub(crate) stack_top_gva: u64,
    /// File mappings prepared by [`Self::map_file_cow`] that will be
    /// applied to the VM during [`Self::evolve`].
    pub(crate) pending_file_mappings: Vec<super::file_mapping::PreparedFileMapping>,
}

impl Debug for UninitializedSandbox {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("UninitializedSandbox")
            .field("memory_layout", &self.mgr.layout)
            .finish()
    }
}

/// A `GuestBinary` is either a buffer or the file path to some data (e.g., a guest binary).
#[derive(Debug)]
pub enum GuestBinary {
    /// A buffer containing the GuestBinary
    Buffer(Vec<u8>),
    /// A path to the GuestBinary
    FilePath(PathBuf),
}
impl GuestBinary {
    /// If the guest binary is identified by a file, canonicalise the path
    ///
    /// For [`GuestBinary::FilePath`], this resolves the path to its canonical
    /// form. For [`GuestBinary::Buffer`], this method is a no-op.
    /// TODO: Maybe we should make the GuestEnvironment or
    ///       GuestBinary constructors crate-private and turn this
    ///       into an invariant on one of those types.
    pub fn canonicalize(&mut self) -> Result<()> {
        if let GuestBinary::FilePath(p) = self {
            *p = p
                .canonicalize()
                .map_err(|e| new_error!("GuestBinary not found: '{}': {}", p.display(), e))?;
        }
        Ok(())
    }
}

/// A `GuestBlob` containing data and the permissions for its use.
#[derive(Debug)]
pub struct GuestBlob<'a> {
    /// The data contained in the blob.
    pub data: &'a [u8],
    /// The permissions for the blob in memory.
    /// By default, it's READ
    pub permissions: MemoryRegionFlags,
}

impl<'a> From<&'a [u8]> for GuestBlob<'a> {
    fn from(data: &'a [u8]) -> Self {
        GuestBlob {
            data,
            permissions: DEFAULT_GUEST_BLOB_MEM_FLAGS,
        }
    }
}

/// Container for a guest binary and optional initialization data.
///
/// This struct combines a guest binary (either from a file or memory buffer) with
/// optional data that will be available to the guest during execution.
///
/// The guest binary is owned. `'b` is the lifetime of the borrowed init data.
#[derive(Debug)]
pub struct GuestEnvironment<'b> {
    /// The guest binary, which can be a file path or a buffer.
    pub guest_binary: GuestBinary,
    /// An optional guest blob, which can be used to provide additional data to the guest.
    pub init_data: Option<GuestBlob<'b>>,
}

impl<'b> GuestEnvironment<'b> {
    /// Creates a new `GuestEnvironment` with the given guest binary and an optional guest blob.
    pub fn new(guest_binary: GuestBinary, init_data: Option<&'b [u8]>) -> Self {
        GuestEnvironment {
            guest_binary,
            init_data: init_data.map(GuestBlob::from),
        }
    }
}

impl From<GuestBinary> for GuestEnvironment<'_> {
    fn from(guest_binary: GuestBinary) -> Self {
        GuestEnvironment {
            guest_binary,
            init_data: None,
        }
    }
}

impl UninitializedSandbox {
    // Creates a new uninitialized sandbox from a pre-built snapshot.
    // Note that since memory configuration is part of the snapshot the only configuration
    // that can be changed (from the original snapshot) is the configuration defines the behaviour of
    // `InterruptHandler` on Linux.
    //
    // This is ok for now as this is not a public function
    fn from_snapshot(
        snapshot: Arc<Snapshot>,
        cfg: Option<SandboxConfiguration>,
        #[cfg(crashdump)] binary_path: Option<PathBuf>,
    ) -> Result<Self> {
        #[cfg(feature = "build-metadata")]
        log_build_details();

        // hyperlight is only supported on Windows 11 and Windows Server 2022 and later
        #[cfg(target_os = "windows")]
        check_windows_version()?;

        let sandbox_cfg = cfg.unwrap_or_default();

        #[cfg(any(crashdump, gdb))]
        let rt_cfg = {
            #[cfg(crashdump)]
            let guest_core_dump = sandbox_cfg.get_guest_core_dump();

            #[cfg(gdb)]
            let debug_info = sandbox_cfg.get_guest_debug_info();

            SandboxRuntimeConfig {
                #[cfg(crashdump)]
                binary_path,
                #[cfg(gdb)]
                debug_info,
                #[cfg(crashdump)]
                guest_core_dump,
                // entry_point is set later in set_up_hypervisor_partition
                // once the entrypoint is resolved from the snapshot
                #[cfg(crashdump)]
                entry_point: None,
            }
        };

        let mem_mgr_wrapper =
            SandboxMemoryManager::<ExclusiveSharedMemory>::from_snapshot(snapshot.as_ref())?;

        let host_funcs = Arc::new(Mutex::new(FunctionRegistry::with_default_host_print()));

        let sandbox = Self {
            host_funcs,
            mgr: mem_mgr_wrapper,
            max_guest_log_level: None,
            config: sandbox_cfg,
            #[cfg(any(crashdump, gdb))]
            rt_cfg,
            load_info: snapshot.load_info(),
            stack_top_gva: snapshot.stack_top_gva(),
            pending_file_mappings: Vec::new(),
        };

        crate::debug!("Sandbox created:  {:#?}", sandbox);

        Ok(sandbox)
    }

    /// Creates a new uninitialized sandbox for the given guest environment.
    ///
    /// The guest binary can be provided as either a file path or memory buffer.
    /// An optional configuration can customize memory sizes and sandbox settings.
    /// After creation, register host functions using [`register`](Self::register)
    /// before calling [`evolve`](Self::evolve) to complete initialization and create the VM.
    #[instrument(
        err(Debug),
        skip(env),
        parent = Span::current()
    )]
    pub fn new<'b>(
        env: impl Into<GuestEnvironment<'b>>,
        cfg: Option<SandboxConfiguration>,
    ) -> Result<Self> {
        let cfg = cfg.unwrap_or_default();
        let env = env.into();
        #[cfg(crashdump)]
        let binary_path = match &env.guest_binary {
            GuestBinary::FilePath(path) => Some(path.clone()),
            GuestBinary::Buffer(_) => None,
        };
        let snapshot = Snapshot::from_env(env, cfg)?;
        Self::from_snapshot(
            Arc::new(snapshot),
            Some(cfg),
            #[cfg(crashdump)]
            binary_path,
        )
    }

    /// Creates and initializes the virtual machine, transforming this into a ready-to-use sandbox.
    ///
    /// This method consumes the `UninitializedSandbox` and performs the final initialization
    /// steps to create the underlying virtual machine. Once evolved, the resulting
    /// [`MultiUseSandbox`] can execute guest code and handle function calls.
    #[instrument(err(Debug), skip_all, parent = Span::current(), level = "Trace")]
    pub fn evolve(self) -> Result<MultiUseSandbox> {
        evolve_impl_multi_use(self)
    }

    /// Map the contents of a file into the guest at a particular address.
    ///
    /// The file mapping is prepared immediately (host-side OS work) but
    /// the actual VM-side mapping is deferred until [`evolve()`](Self::evolve).
    ///
    /// The `guest_base` must be page-aligned and must lie **outside**
    /// the sandbox's primary shared memory region (`BASE_ADDRESS` to
    /// `BASE_ADDRESS + shared_mem_size`).
    ///
    /// Returns the length of the mapping in bytes.
    #[instrument(err(Debug), skip(self, file_path, guest_base), parent = Span::current())]
    pub fn map_file_cow(
        &mut self,
        file_path: &std::path::Path,
        guest_base: u64,
    ) -> crate::Result<u64> {
        // Validate that guest_base is outside the sandbox's primary memory slot.
        // (Full range check happens after prepare_file_cow when we know the mapped size.)
        let shared_size = self.mgr.shared_mem.mem_size() as u64;
        let base_addr = crate::mem::layout::SandboxMemoryLayout::BASE_ADDRESS as u64;

        let prepared = super::file_mapping::prepare_file_cow(file_path, guest_base)?;

        // Validate full mapped range doesn't overlap shared memory.
        let mapping_end = guest_base
            .checked_add(prepared.size as u64)
            .ok_or_else(|| {
                crate::HyperlightError::Error(format!(
                    "map_file_cow: guest address overflow: {:#x} + {:#x}",
                    guest_base, prepared.size
                ))
            })?;
        let shared_end = base_addr.checked_add(shared_size).ok_or_else(|| {
            crate::HyperlightError::Error("shared memory end overflow".to_string())
        })?;
        if guest_base < shared_end && mapping_end > base_addr {
            return Err(crate::HyperlightError::Error(format!(
                "map_file_cow: mapping [{:#x}..{:#x}) overlaps sandbox shared memory [{:#x}..{:#x})",
                guest_base, mapping_end, base_addr, shared_end,
            )));
        }

        let size = prepared.size as u64;

        // Check for overlaps with existing pending file mappings.
        let new_start = guest_base;
        let new_end = mapping_end;
        for existing in &self.pending_file_mappings {
            let ex_start = existing.guest_base;
            let ex_end = ex_start.checked_add(existing.size as u64).ok_or_else(|| {
                crate::HyperlightError::Error(format!(
                    "map_file_cow: existing mapping address overflow: {:#x} + {:#x}",
                    ex_start, existing.size
                ))
            })?;
            if new_start < ex_end && new_end > ex_start {
                return Err(crate::HyperlightError::Error(format!(
                    "map_file_cow: mapping [{:#x}..{:#x}) overlaps existing mapping [{:#x}..{:#x})",
                    new_start, new_end, ex_start, ex_end,
                )));
            }
        }

        self.pending_file_mappings.push(prepared);
        Ok(size)
    }

    /// Returns the total size of the sandbox shared memory region in bytes.
    ///
    /// This is useful for placing file mappings at guest physical addresses
    /// that don't overlap the primary shared memory slot.
    pub fn shared_mem_size(&self) -> usize {
        self.mgr.shared_mem.mem_size()
    }

    /// Sets the maximum log level for guest code execution.
    ///
    /// If not set, the log level is determined by the `RUST_LOG` environment variable,
    /// defaulting to [`LevelFilter::Error`] if unset.
    pub fn set_max_guest_log_level(&mut self, log_level: LevelFilter) {
        self.max_guest_log_level = Some(log_level);
    }

    /// Registers a host function that the guest can call.
    pub fn register<Args: ParameterTuple, Output: SupportedReturnType>(
        &mut self,
        name: impl AsRef<str>,
        host_func: impl Into<HostFunction<Output, Args>>,
    ) -> Result<()> {
        register_host_function(host_func, self, name.as_ref())
    }

    /// Registers the special "HostPrint" function for guest printing.
    ///
    /// This overrides the default behavior of writing to stdout.
    /// The function expects the signature `FnMut(String) -> i32`
    /// and will be called when the guest wants to print output.
    pub fn register_print(
        &mut self,
        print_func: impl Into<HostFunction<i32, (String,)>>,
    ) -> Result<()> {
        self.register("HostPrint", print_func)
    }
}
// Check to see if the current version of Windows is supported
// Hyperlight is only supported on Windows 11 and Windows Server 2022 and later
#[cfg(target_os = "windows")]
fn check_windows_version() -> Result<()> {
    use windows_version::{OsVersion, is_server};
    const WINDOWS_MAJOR: u32 = 10;
    const WINDOWS_MINOR: u32 = 0;
    const WINDOWS_PACK: u32 = 0;

    // Windows Server 2022 has version numbers 10.0.20348 or greater
    if is_server() {
        if OsVersion::current() < OsVersion::new(WINDOWS_MAJOR, WINDOWS_MINOR, WINDOWS_PACK, 20348)
        {
            return Err(new_error!(
                "Hyperlight Requires Windows Server 2022 or newer"
            ));
        }
    } else if OsVersion::current()
        < OsVersion::new(WINDOWS_MAJOR, WINDOWS_MINOR, WINDOWS_PACK, 22000)
    {
        return Err(new_error!("Hyperlight Requires Windows 11 or newer"));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;
    use std::sync::mpsc::channel;
    use std::{fs, thread};

    use crossbeam_queue::ArrayQueue;
    use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterValue, ReturnValue};
    use hyperlight_testing::simple_guest_as_pathbuf;

    use crate::sandbox::SandboxConfiguration;
    use crate::sandbox::uninitialized::{GuestBinary, GuestEnvironment};
    use crate::{MultiUseSandbox, Result, UninitializedSandbox, new_error};

    #[cfg(target_os = "linux")]
    #[test]
    fn guest_binary_loads_from_non_utf8_path() {
        use std::ffi::OsString;
        use std::os::unix::ffi::OsStringExt;

        let temp_dir = tempfile::tempdir().unwrap();
        let guest_path = temp_dir
            .path()
            .join(OsString::from_vec(b"guest-\xff".to_vec()));
        fs::copy(simple_guest_as_pathbuf(), &guest_path).unwrap();

        let sandbox = UninitializedSandbox::new(GuestBinary::FilePath(guest_path), None);

        assert!(sandbox.is_ok());
    }

    #[test]
    fn test_load_extra_blob() {
        let binary_path = simple_guest_as_pathbuf();
        let buffer = [0xde, 0xad, 0xbe, 0xef];
        let guest_env =
            GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), Some(&buffer));

        let uninitialized_sandbox = UninitializedSandbox::new(guest_env, None).unwrap();
        let mut sandbox = uninitialized_sandbox.evolve().unwrap();

        let res = sandbox
            .call::<Vec<u8>>("ReadFromUserMemory", (4u64, buffer.to_vec()))
            .expect("Failed to call ReadFromUserMemory");

        assert_eq!(res, buffer.to_vec());
    }

    #[test]
    fn test_new_sandbox() {
        // Guest Binary exists at path

        let binary_path = simple_guest_as_pathbuf();
        let sandbox = UninitializedSandbox::new(GuestBinary::FilePath(binary_path.clone()), None);
        assert!(sandbox.is_ok());

        // Guest Binary does not exist at path

        let mut binary_path_does_not_exist = binary_path.clone();
        binary_path_does_not_exist
            .as_mut_os_string()
            .push(".nonexistent");
        let uninitialized_sandbox =
            UninitializedSandbox::new(GuestBinary::FilePath(binary_path_does_not_exist), None);
        assert!(uninitialized_sandbox.is_err());

        // Non default memory configuration
        let cfg = {
            let mut cfg = SandboxConfiguration::default();
            cfg.set_input_data_size(0x1000);
            cfg.set_output_data_size(0x1000);
            cfg.set_heap_size(0x1000);
            Some(cfg)
        };

        let uninitialized_sandbox =
            UninitializedSandbox::new(GuestBinary::FilePath(binary_path.clone()), cfg);
        assert!(uninitialized_sandbox.is_ok());

        let uninitialized_sandbox =
            UninitializedSandbox::new(GuestBinary::FilePath(binary_path), None).unwrap();

        // Get a Sandbox from an uninitialized sandbox without a call back function

        let _sandbox = uninitialized_sandbox.evolve().unwrap();

        // Test with a valid guest binary buffer

        let binary_path = simple_guest_as_pathbuf();
        let sandbox =
            UninitializedSandbox::new(GuestBinary::Buffer(fs::read(binary_path).unwrap()), None);
        assert!(sandbox.is_ok());

        // Test with a invalid guest binary buffer

        let binary_path = simple_guest_as_pathbuf();
        let mut bytes = fs::read(binary_path).unwrap();
        let _ = bytes.split_off(100);
        let sandbox = UninitializedSandbox::new(GuestBinary::Buffer(bytes), None);
        assert!(sandbox.is_err());
    }

    #[test]
    fn test_host_functions() {
        let uninitialized_sandbox = || {
            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
                .unwrap()
        };

        // simple register + call
        {
            let mut usbox = uninitialized_sandbox();

            usbox.register("test0", |arg: i32| Ok(arg + 1)).unwrap();

            let sandbox: Result<MultiUseSandbox> = usbox.evolve();
            assert!(sandbox.is_ok());
            let sandbox = sandbox.unwrap();

            let host_funcs = sandbox
                .host_funcs
                .try_lock()
                .map_err(|_| new_error!("Error locking"));

            assert!(host_funcs.is_ok());

            let res = host_funcs
                .unwrap()
                .call_host_function("test0", vec![ParameterValue::Int(1)])
                .unwrap();

            assert_eq!(res, ReturnValue::Int(2));
        }

        // multiple parameters register + call
        {
            let mut usbox = uninitialized_sandbox();

            usbox.register("test1", |a: i32, b: i32| Ok(a + b)).unwrap();

            let sandbox: Result<MultiUseSandbox> = usbox.evolve();
            assert!(sandbox.is_ok());
            let sandbox = sandbox.unwrap();

            let host_funcs = sandbox
                .host_funcs
                .try_lock()
                .map_err(|_| new_error!("Error locking"));

            assert!(host_funcs.is_ok());

            let res = host_funcs
                .unwrap()
                .call_host_function(
                    "test1",
                    vec![ParameterValue::Int(1), ParameterValue::Int(2)],
                )
                .unwrap();

            assert_eq!(res, ReturnValue::Int(3));
        }

        // incorrect arguments register + call
        {
            let mut usbox = uninitialized_sandbox();

            usbox
                .register("test2", |msg: String| {
                    println!("test2 called: {}", msg);
                    Ok(())
                })
                .unwrap();

            let sandbox: Result<MultiUseSandbox> = usbox.evolve();
            assert!(sandbox.is_ok());
            let sandbox = sandbox.unwrap();

            let host_funcs = sandbox
                .host_funcs
                .try_lock()
                .map_err(|_| new_error!("Error locking"));

            assert!(host_funcs.is_ok());

            let res = host_funcs.unwrap().call_host_function("test2", vec![]);
            assert!(res.is_err());
        }

        // calling a function that doesn't exist
        {
            let usbox = uninitialized_sandbox();
            let sandbox: Result<MultiUseSandbox> = usbox.evolve();
            assert!(sandbox.is_ok());
            let sandbox = sandbox.unwrap();

            let host_funcs = sandbox
                .host_funcs
                .try_lock()
                .map_err(|_| new_error!("Error locking"));

            assert!(host_funcs.is_ok());

            let res = host_funcs.unwrap().call_host_function("test4", vec![]);
            assert!(res.is_err());
        }
    }

    #[test]
    fn test_host_print() {
        // writer as a FnMut closure mutating a captured variable and then trying to access the captured variable
        // after the Sandbox instance has been dropped
        // this example is fairly contrived but we should still support such an approach.

        let (tx, rx) = channel();

        let writer = move |msg| {
            let _ = tx.send(msg);
            Ok(0)
        };

        let mut sandbox =
            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
                .expect("Failed to create sandbox");

        sandbox
            .register_print(writer)
            .expect("Failed to register host print function");

        let host_funcs = sandbox
            .host_funcs
            .try_lock()
            .map_err(|_| new_error!("Error locking"));

        assert!(host_funcs.is_ok());

        host_funcs.unwrap().host_print("test".to_string()).unwrap();

        drop(sandbox);

        let received_msgs: Vec<_> = rx.into_iter().collect();
        assert_eq!(received_msgs, ["test"]);

        // There may be cases where a mutable reference to the captured variable is not required to be used outside the closure
        // e.g. if the function is writing to a file or a socket etc.

        // writer as a FnMut closure mutating a captured variable but not trying to access the captured variable

        // This seems more realistic as the client is creating a file to be written to in the closure
        // and then accessing the file a different handle.
        // The problem is that captured_file still needs static lifetime so even though we can access the data through the second file handle
        // this still does not work as the captured_file is dropped at the end of the function

        // TODO: Currently, we block any writes that are not to
        // the stdout/stderr file handles, so this code is commented
        // out until we can register writer functions like any other
        // host functions with their own set of extra allowed syscalls.
        // In particular, this code should be brought back once we have addressed the issue

        // let captured_file = Arc::new(Mutex::new(NamedTempFile::new().unwrap()));
        // let capture_file_clone = captured_file.clone();
        //
        // let capture_file_lock = captured_file
        //     .try_lock()
        //     .map_err(|_| new_error!("Error locking"))
        //     .unwrap();
        // let mut file = capture_file_lock.reopen().unwrap();
        // drop(capture_file_lock);
        //
        // let writer = move |msg: String| -> Result<i32> {
        //     let mut captured_file = capture_file_clone
        //         .try_lock()
        //         .map_err(|_| new_error!("Error locking"))
        //         .unwrap();
        //     captured_file.write_all(msg.as_bytes()).unwrap();
        //     Ok(0)
        // };
        //
        // let writer_func = Arc::new(Mutex::new(writer));
        //
        // let sandbox = UninitializedSandbox::new(
        //     GuestBinary::FilePath(simple_guest_as_pathbuf()),
        //     None,
        //     None,
        //     Some(&writer_func),
        // )
        // .expect("Failed to create sandbox");
        //
        // let host_funcs = sandbox
        //     .host_funcs
        //     .try_lock()
        //     .map_err(|_| new_error!("Error locking"));
        //
        // assert!(host_funcs.is_ok());
        //
        // host_funcs.unwrap().host_print("test2".to_string()).unwrap();
        //
        // let mut buffer = String::new();
        // file.read_to_string(&mut buffer).unwrap();
        // assert_eq!(buffer, "test2");

        // writer as a function

        fn fn_writer(msg: String) -> Result<i32> {
            assert_eq!(msg, "test2");
            Ok(0)
        }

        let mut sandbox =
            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
                .expect("Failed to create sandbox");

        sandbox
            .register_print(fn_writer)
            .expect("Failed to register host print function");

        let host_funcs = sandbox
            .host_funcs
            .try_lock()
            .map_err(|_| new_error!("Error locking"));

        assert!(host_funcs.is_ok());

        host_funcs.unwrap().host_print("test2".to_string()).unwrap();

        // writer as a method

        let mut test_host_print = TestHostPrint::new();

        // create a closure over the struct method

        let writer_closure = move |s| test_host_print.write(s);

        let mut sandbox =
            UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_as_pathbuf()), None)
                .expect("Failed to create sandbox");

        sandbox
            .register_print(writer_closure)
            .expect("Failed to register host print function");

        let host_funcs = sandbox
            .host_funcs
            .try_lock()
            .map_err(|_| new_error!("Error locking"));

        assert!(host_funcs.is_ok());

        host_funcs.unwrap().host_print("test3".to_string()).unwrap();
    }

    struct TestHostPrint {}

    impl TestHostPrint {
        fn new() -> Self {
            TestHostPrint {}
        }

        fn write(&mut self, msg: String) -> Result<i32> {
            assert_eq!(msg, "test3");
            Ok(0)
        }
    }

    #[test]
    fn check_create_and_use_sandbox_on_different_threads() {
        let unintializedsandbox_queue = Arc::new(ArrayQueue::<UninitializedSandbox>::new(10));
        let sandbox_queue = Arc::new(ArrayQueue::<MultiUseSandbox>::new(10));

        for i in 0..10 {
            let simple_guest_path = simple_guest_as_pathbuf();
            let unintializedsandbox = {
                let err_string = format!("failed to create UninitializedSandbox {i}");
                let err_str = err_string.as_str();
                UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_path), None)
                    .expect(err_str)
            };

            {
                let err_string = format!("Failed to push UninitializedSandbox {i}");
                let err_str = err_string.as_str();

                unintializedsandbox_queue
                    .push(unintializedsandbox)
                    .expect(err_str);
            }
        }

        let thread_handles = (0..10)
            .map(|i| {
                let uq = unintializedsandbox_queue.clone();
                let sq = sandbox_queue.clone();
                thread::spawn(move || {
                    let uninitialized_sandbox = uq.pop().unwrap_or_else(|| {
                        panic!("Failed to pop UninitializedSandbox thread {}", i)
                    });

                    let host_funcs = uninitialized_sandbox
                        .host_funcs
                        .try_lock()
                        .map_err(|_| new_error!("Error locking"));

                    assert!(host_funcs.is_ok());

                    host_funcs
                        .unwrap()
                        .host_print(format!("Print from UninitializedSandbox on Thread {}\n", i))
                        .unwrap();

                    let sandbox = uninitialized_sandbox.evolve().unwrap_or_else(|_| {
                        panic!("Failed to initialize UninitializedSandbox thread {}", i)
                    });

                    sq.push(sandbox).unwrap_or_else(|_| {
                        panic!("Failed to push UninitializedSandbox thread {}", i)
                    })
                })
            })
            .collect::<Vec<_>>();

        for handle in thread_handles {
            handle.join().unwrap();
        }

        let thread_handles = (0..10)
            .map(|i| {
                let sq = sandbox_queue.clone();
                thread::spawn(move || {
                    let sandbox = sq
                        .pop()
                        .unwrap_or_else(|| panic!("Failed to pop Sandbox thread {}", i));

                    let host_funcs = sandbox
                        .host_funcs
                        .try_lock()
                        .map_err(|_| new_error!("Error locking"));

                    assert!(host_funcs.is_ok());

                    host_funcs
                        .unwrap()
                        .host_print(format!("Print from Sandbox on Thread {}\n", i))
                        .unwrap();
                })
            })
            .collect::<Vec<_>>();

        for handle in thread_handles {
            handle.join().unwrap();
        }
    }

    /// Tests that tracing spans and events are properly emitted when a tracing subscriber is set.
    ///
    /// This test verifies:
    /// 1. Spans are created with correct attributes (correlation_id)
    /// 2. Nested spans from UninitializedSandbox::new are properly parented
    /// 3. Error events are emitted when sandbox creation fails
    ///
    /// NOTE: The `#[instrument]` callsite on `UninitializedSandbox::new` uses
    /// tracing's global interest cache. If another test thread registers that
    /// callsite first (with the no-op subscriber), the cached `Interest::never()`
    /// will suppress span creation on our thread. To work around this, we:
    /// 1. Make a warmup call to force-register the callsite
    /// 2. Call `rebuild_interest_cache()` to overwrite the cached interest with
    ///    our subscriber's `Interest::sometimes()`
    /// 3. Clear recorded state and run the real test
    #[test]
    #[cfg(feature = "build-metadata")]
    fn test_trace_trace() {
        use hyperlight_testing::tracing_subscriber::TracingSubscriber;
        use tracing::Level;
        use tracing_core::Subscriber;
        use tracing_core::callsite::rebuild_interest_cache;
        use uuid::Uuid;

        /// Helper to extract a string value from nested JSON: obj["span"]["attributes"][key]
        fn get_span_attr<'a>(span: &'a serde_json::Value, key: &str) -> Option<&'a str> {
            span.get("span")?.get("attributes")?.get(key)?.as_str()
        }

        /// Helper to extract event field: obj["event"][field]
        fn get_event_field<'a>(event: &'a serde_json::Value, field: &str) -> Option<&'a str> {
            event.get("event")?.get(field)?.as_str()
        }

        /// Helper to extract event metadata field: obj["event"]["metadata"][field]
        fn get_event_metadata<'a>(event: &'a serde_json::Value, field: &str) -> Option<&'a str> {
            event.get("event")?.get("metadata")?.get(field)?.as_str()
        }

        let subscriber = TracingSubscriber::new(Level::TRACE);

        tracing::subscriber::with_default(subscriber.clone(), || {
            // Warmup: force-register the #[instrument] callsite on
            // UninitializedSandbox::new by calling it once. This ensures the
            // callsite exists in the global registry regardless of whether
            // another thread already registered it.
            let mut bad_path = simple_guest_as_pathbuf();
            bad_path.as_mut_os_string().push("does_not_exist");
            let _ = UninitializedSandbox::new(GuestBinary::FilePath(bad_path.clone()), None);

            // Rebuild the interest cache. Now that the callsite is guaranteed
            // to be registered, this will overwrite any cached Interest::never()
            // (from another thread's no-op subscriber) with our subscriber's
            // Interest::sometimes(), ensuring subsequent calls create spans.
            rebuild_interest_cache();

            // Clear all state from the warmup call
            subscriber.clear();

            let correlation_id = Uuid::new_v4().to_string();
            let _span = tracing::error_span!("test_trace_logs", %correlation_id).entered();

            // Verify we're in a span with correct name
            let (test_span_id, span_meta) = subscriber
                .current_span()
                .into_inner()
                .expect("Should be inside a span");
            assert_eq!(span_meta.name(), "test_trace_logs");

            // Verify correlation_id was recorded
            let span_data = subscriber.get_span(test_span_id.into_u64());
            let recorded_id =
                get_span_attr(&span_data, "correlation_id").expect("correlation_id not found");
            assert_eq!(recorded_id, correlation_id);

            // Try to create a sandbox with a non-existent binary - this should fail
            // and emit an error event
            let result = UninitializedSandbox::new(GuestBinary::FilePath(bad_path), None);
            assert!(result.is_err(), "Sandbox creation should fail");

            // Verify we're still in our test span
            let (current_id, _) = subscriber
                .current_span()
                .into_inner()
                .expect("Should still be inside a span");
            assert_eq!(
                current_id.into_u64(),
                test_span_id.into_u64(),
                "Should still be in the test span"
            );

            // Verify a span named "new" was created by UninitializedSandbox::new
            // (look up by name rather than hardcoded ID to avoid fragility)
            let all_spans = subscriber.get_all_spans();
            let _new_span_entry = all_spans
                .iter()
                .find(|&(&id, _)| {
                    id != test_span_id.into_u64()
                        && subscriber.get_span_metadata(id).name() == "new"
                })
                .expect("Expected a span named 'new' from UninitializedSandbox::new");

            // Verify the error event was emitted
            let events = subscriber.get_events();
            assert_eq!(events.len(), 1, "Expected exactly one error event");

            let event = &events[0];
            let level = get_event_metadata(event, "level").expect("event should have level");
            let error = get_event_field(event, "error").expect("event should have error field");
            let target = get_event_metadata(event, "target").expect("event should have target");
            let module_path =
                get_event_metadata(event, "module_path").expect("event should have module_path");

            assert_eq!(level, "ERROR");
            assert!(
                error.contains("GuestBinary not found"),
                "Error should mention 'GuestBinary not found', got: {error}"
            );
            assert_eq!(target, "hyperlight_host::sandbox::uninitialized");
            assert_eq!(module_path, "hyperlight_host::sandbox::uninitialized");
        });
    }

    #[test]
    #[ignore]
    // Tests that traces are emitted as log records when there is no trace
    // subscriber configured.
    #[cfg(feature = "build-metadata")]
    fn test_log_trace() {
        use std::path::PathBuf;

        use hyperlight_testing::logger::{LOGGER as TEST_LOGGER, Logger as TestLogger};
        use log::Level;
        use tracing_core::callsite::rebuild_interest_cache;

        {
            TestLogger::initialize_test_logger();
            TEST_LOGGER.set_max_level(log::LevelFilter::Trace);

            // This makes sure that the metadata interest cache is rebuilt so that
            // the log records are emitted for the trace records

            rebuild_interest_cache();

            let mut invalid_binary_path = simple_guest_as_pathbuf();
            invalid_binary_path
                .as_mut_os_string()
                .push("does_not_exist");

            let sbox = UninitializedSandbox::new(GuestBinary::FilePath(invalid_binary_path), None);
            assert!(sbox.is_err());

            // When tracing is creating log records it will create a log
            // record for the creation of the span (from the instrument
            // attribute), and will then create a log record for the entry to
            // and exit from the span.
            //
            // It also creates a log record for the span being dropped.
            //
            // In addition there are 14 info log records created for build information
            //
            // So we expect 19 log records for this test, four for the span and
            // then one for the error as the file that we are attempting to
            // load into the sandbox does not exist, plus the 14 info log records

            let num_calls = TEST_LOGGER.num_log_calls();
            assert_eq!(13, num_calls);

            // Log record 1

            let logcall = TEST_LOGGER.get_log_call(0).unwrap();
            assert_eq!(Level::Info, logcall.level);

            assert!(logcall.args.starts_with("new; cfg"));
            assert_eq!("hyperlight_host::sandbox::uninitialized", logcall.target);

            // Log record 2

            let logcall = TEST_LOGGER.get_log_call(1).unwrap();
            assert_eq!(Level::Trace, logcall.level);
            assert_eq!(logcall.args, "-> new;");
            assert_eq!("tracing::span::active", logcall.target);

            // Log record 17

            let logcall = TEST_LOGGER.get_log_call(10).unwrap();
            assert_eq!(Level::Error, logcall.level);
            assert!(
                logcall
                    .args
                    .starts_with("error=Error(\"GuestBinary not found:")
            );
            assert_eq!("hyperlight_host::sandbox::uninitialized", logcall.target);

            // Log record 18

            let logcall = TEST_LOGGER.get_log_call(11).unwrap();
            assert_eq!(Level::Trace, logcall.level);
            assert_eq!(logcall.args, "<- new;");
            assert_eq!("tracing::span::active", logcall.target);

            // Log record 19

            let logcall = TEST_LOGGER.get_log_call(12).unwrap();
            assert_eq!(Level::Trace, logcall.level);
            assert_eq!(logcall.args, "-- new;");
            assert_eq!("tracing::span", logcall.target);
        }
        {
            // test to ensure an invalid binary logs & traces properly
            TEST_LOGGER.clear_log_calls();
            TEST_LOGGER.set_max_level(log::LevelFilter::Info);

            let mut valid_binary_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
            valid_binary_path.push("src");
            valid_binary_path.push("sandbox");
            valid_binary_path.push("initialized.rs");

            let sbox = UninitializedSandbox::new(GuestBinary::FilePath(valid_binary_path), None);
            assert!(sbox.is_err());

            // There should be 2 calls this time when we change to the log
            // LevelFilter to Info.
            let num_calls = TEST_LOGGER.num_log_calls();
            assert_eq!(2, num_calls);

            // Log record 1

            let logcall = TEST_LOGGER.get_log_call(0).unwrap();
            assert_eq!(Level::Info, logcall.level);

            assert!(logcall.args.starts_with("new; cfg"));
            assert_eq!("hyperlight_host::sandbox::uninitialized", logcall.target);

            // Log record 2

            let logcall = TEST_LOGGER.get_log_call(1).unwrap();
            assert_eq!(Level::Error, logcall.level);
            assert!(
                logcall
                    .args
                    .starts_with("error=Error(\"GuestBinary not found:")
            );
            assert_eq!("hyperlight_host::sandbox::uninitialized", logcall.target);
        }
        {
            TEST_LOGGER.clear_log_calls();
            TEST_LOGGER.set_max_level(log::LevelFilter::Error);

            let sbox = {
                let res = UninitializedSandbox::new(
                    GuestBinary::FilePath(simple_guest_as_pathbuf()),
                    None,
                );
                res.unwrap()
            };
            let _: Result<MultiUseSandbox> = sbox.evolve();

            let num_calls = TEST_LOGGER.num_log_calls();

            assert_eq!(0, num_calls);
        }
    }

    #[test]
    fn test_invalid_path() {
        let invalid_path = "some/path/that/does/not/exist";
        let sbox = UninitializedSandbox::new(GuestBinary::FilePath(invalid_path.into()), None);
        println!("{:?}", sbox);
        #[cfg(target_os = "windows")]
        assert!(
            matches!(sbox, Err(e) if e.to_string().contains("GuestBinary not found: 'some/path/that/does/not/exist': The system cannot find the path specified. (os error 3)"))
        );
        #[cfg(target_os = "linux")]
        assert!(
            matches!(sbox, Err(e) if e.to_string().contains("GuestBinary not found: 'some/path/that/does/not/exist': No such file or directory (os error 2)"))
        );
    }

    #[test]
    fn test_from_snapshot_various_configurations() {
        use crate::sandbox::snapshot::Snapshot;

        let binary_path = simple_guest_as_pathbuf();

        // Test 1: Create snapshot with default config, create multiple sandboxes from it
        {
            let env = GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), None);

            let snapshot = Arc::new(
                Snapshot::from_env(env, Default::default())
                    .expect("Failed to create snapshot with default config"),
            );

            // Create first sandbox from snapshot
            let sandbox1 = UninitializedSandbox::from_snapshot(
                snapshot.clone(),
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create first sandbox from snapshot");

            // Create second sandbox from same snapshot
            let sandbox2 = UninitializedSandbox::from_snapshot(
                snapshot.clone(),
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create second sandbox from snapshot");

            // Both should be able to evolve independently
            let _evolved1 = sandbox1.evolve().expect("Failed to evolve sandbox1");
            let _evolved2 = sandbox2.evolve().expect("Failed to evolve sandbox2");
        }

        // Test 2: Create snapshot with custom heap size
        {
            let mut cfg = SandboxConfiguration::default();
            cfg.set_heap_size(16 * 1024 * 1024); // 16MB heap

            let env = GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), None);

            let snapshot = Arc::new(
                Snapshot::from_env(env, cfg)
                    .expect("Failed to create snapshot with custom heap size"),
            );

            let sandbox = UninitializedSandbox::from_snapshot(
                snapshot,
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox from snapshot with custom heap");

            let _evolved = sandbox.evolve().expect("Failed to evolve sandbox");
        }

        // Test 3: Create snapshot with custom scratch size
        {
            let mut cfg = SandboxConfiguration::default();
            cfg.set_scratch_size(256 * 1024); // 256KB scratch

            let env = GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), None);

            let snapshot = Arc::new(
                Snapshot::from_env(env, cfg)
                    .expect("Failed to create snapshot with custom stack size"),
            );

            let sandbox = UninitializedSandbox::from_snapshot(
                snapshot,
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox from snapshot with custom stack");

            let _evolved = sandbox.evolve().expect("Failed to evolve sandbox");
        }

        // Test 4: Create snapshot with custom input/output buffer sizes
        {
            let mut cfg = SandboxConfiguration::default();
            cfg.set_input_data_size(64 * 1024); // 64KB input
            cfg.set_output_data_size(64 * 1024); // 64KB output

            let env = GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), None);

            let snapshot = Arc::new(
                Snapshot::from_env(env, cfg)
                    .expect("Failed to create snapshot with custom buffer sizes"),
            );

            let sandbox = UninitializedSandbox::from_snapshot(
                snapshot,
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox from snapshot with custom buffers");

            let _evolved = sandbox.evolve().expect("Failed to evolve sandbox");
        }

        // Test 5: Create snapshot with all custom settings
        {
            let mut cfg = SandboxConfiguration::default();
            cfg.set_heap_size(32 * 1024 * 1024); // 32MB heap
            cfg.set_scratch_size(256 * 1024 * 2); // 512KB scratch (256KB will be input/output)
            cfg.set_input_data_size(128 * 1024); // 128KB input
            cfg.set_output_data_size(128 * 1024); // 128KB output

            let env = GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), None);

            let snapshot = Arc::new(
                Snapshot::from_env(env, cfg)
                    .expect("Failed to create snapshot with all custom settings"),
            );

            // Create multiple sandboxes from the same snapshot
            let sandbox1 = UninitializedSandbox::from_snapshot(
                snapshot.clone(),
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox1 from fully customized snapshot");
            let sandbox2 = UninitializedSandbox::from_snapshot(
                snapshot.clone(),
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox2 from fully customized snapshot");
            let sandbox3 = UninitializedSandbox::from_snapshot(
                snapshot.clone(),
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox3 from fully customized snapshot");

            let _evolved1 = sandbox1.evolve().expect("Failed to evolve sandbox1");
            let _evolved2 = sandbox2.evolve().expect("Failed to evolve sandbox2");
            let _evolved3 = sandbox3.evolve().expect("Failed to evolve sandbox3");
        }

        // Test 6: Create snapshot from binary buffer instead of file path
        {
            let binary_bytes = fs::read(&binary_path).expect("Failed to read binary file");

            let snapshot = Arc::new(
                Snapshot::from_env(GuestBinary::Buffer(binary_bytes), Default::default())
                    .expect("Failed to create snapshot from buffer"),
            );

            let sandbox = UninitializedSandbox::from_snapshot(
                snapshot,
                None,
                #[cfg(crashdump)]
                None,
            )
            .expect("Failed to create sandbox from buffer-based snapshot");

            let _evolved = sandbox.evolve().expect("Failed to evolve sandbox");
        }

        // Test 7: Register host functions on sandboxes created from snapshot
        {
            let env = GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), None);

            let snapshot = Arc::new(
                Snapshot::from_env(env, Default::default()).expect("Failed to create snapshot"),
            );

            let mut sandbox = UninitializedSandbox::from_snapshot(
                snapshot,
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox from snapshot");

            // Register a custom host function
            sandbox
                .register("CustomAdd", |a: i32, b: i32| Ok(a + b))
                .expect("Failed to register custom function");

            let evolved = sandbox.evolve().expect("Failed to evolve sandbox");

            // Verify the host function was registered
            let host_funcs = evolved
                .host_funcs
                .try_lock()
                .expect("Failed to lock host funcs");

            let result = host_funcs
                .call_host_function(
                    "CustomAdd",
                    vec![ParameterValue::Int(10), ParameterValue::Int(20)],
                )
                .expect("Failed to call CustomAdd");

            assert_eq!(result, ReturnValue::Int(30));
        }

        // Test 8: Create snapshot with init data (guest blob)
        {
            let init_data = [0xCA, 0xFE, 0xBA, 0xBE];
            let guest_env =
                GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), Some(&init_data));

            let snapshot = Arc::new(
                Snapshot::from_env(guest_env, Default::default())
                    .expect("Failed to create snapshot with init data"),
            );

            let sandbox = UninitializedSandbox::from_snapshot(
                snapshot,
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create sandbox from snapshot with init data");

            let _evolved = sandbox.evolve().expect("Failed to evolve sandbox");
        }

        // Test 9: Create snapshot from existing sandbox
        {
            let env = GuestEnvironment::new(GuestBinary::FilePath(binary_path.clone()), None);
            let orig_snapshot = Arc::new(
                Snapshot::from_env(env, Default::default())
                    .expect("Failed to create snapshot with default config"),
            );
            let orig_sandbox = UninitializedSandbox::from_snapshot(
                orig_snapshot,
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create orig_sandbox");
            let mut initialized_sandbox = orig_sandbox
                .evolve()
                .expect("Failed to evolve orig_sandbox");
            let new_snapshot = initialized_sandbox
                .snapshot()
                .expect("Failed to create new_snapshot");
            let new_sandbox = UninitializedSandbox::from_snapshot(
                new_snapshot,
                None,
                #[cfg(crashdump)]
                Some(binary_path.clone()),
            )
            .expect("Failed to create new_sandbox");
            let _evolved = new_sandbox.evolve().expect("Failed to evolve new_sandbox");
        }
    }
}