Move Sandbox into a private initialized module

The initialized module holds the initialized sandbox type. Sandbox,
SandboxStatus and PtRootFinder are reached through
hyperlight_host::Sandbox or hyperlight_host::sandbox.

The module is private because every public item in it is already
re-exported one level up. sandbox::initialized_multi_use stays as a
deprecated facade so existing callers keep compiling.

Keeping the type in a deprecated module is not an option. Module
deprecation is inherited by the items defined inside it and follows them
through re-exports, which would warn on every use of the canonical
hyperlight_host::Sandbox path.

The log tracing test pointed at sandbox/initialized.rs, a file that did
not exist, so it took the "not found" path instead of testing an invalid
binary as intended. It now reads the crate manifest, which always exists
and is never a valid guest binary.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

Author: jprendes

CHANGELOG.md

@@ -16,6 +16,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 * `Sandbox` is the primary initialized sandbox type. `MultiUseSandbox` remains
   as a deprecated alias.
+* `Sandbox` lives in the private `sandbox::initialized` module and is reached
+  through `hyperlight_host::Sandbox` or `hyperlight_host::sandbox::Sandbox`.
+  `sandbox::initialized_multi_use` remains as a deprecated public path.
 * Support overriding the guest log level when building or restoring initialized
   snapshots.
 * `Snapshot::save` now writes the guest memory blob sparsely, skipping all-zero

Justfile

@@ -263,18 +263,18 @@ test-loom:
 test-isolated target=default-target features="" :
     {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::uninitialized::tests::test_log_trace --exact --ignored
     {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::outb::tests::test_log_emit_guest_log --exact --ignored
-    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_is_honored_from_snapshot --exact --ignored
-    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_overrides_initialized_snapshot --exact --ignored
-    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_setter_survives_restore --exact --ignored
-    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_can_be_disabled_and_reenabled --exact --ignored
-    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_can_be_enabled_after_off_init --exact --ignored
+    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_is_honored_from_snapshot --exact --ignored
+    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_overrides_initialized_snapshot --exact --ignored
+    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_setter_survives_restore --exact --ignored
+    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_disabled_and_reenabled --exact --ignored
+    {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_enabled_after_off_init --exact --ignored
     {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --test integration_test -- log_message --exact --ignored
     @# CPU vendor check, gated to known CI runner hardware
     {{ cargo-cmd }} 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 } }} {{ target-triple-flag }} -p hyperlight-host --lib -- sandbox::snapshot::file::config::tests::cpu_vendor_current_is_recognized --exact --ignored
     @# Slow host-dependent MSR audit. Run once per x86_64 CI profile.
-    {{ if features == "" { if hyperlight-target-arch == "x86_64" { cargo-cmd + " test --profile=" + (if target == "debug" { "dev" } else { target }) + " " + target-triple-flag + " -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::msr_tests::test_no_msr_leaks_across_restore_full_window_sweep --exact --ignored --nocapture" } else { "" } } else { "" } }}
+    {{ if features == "" { if hyperlight-target-arch == "x86_64" { cargo-cmd + " test --profile=" + (if target == "debug" { "dev" } else { target }) + " " + target-triple-flag + " -p hyperlight-host --lib -- sandbox::initialized::tests::msr_tests::test_no_msr_leaks_across_restore_full_window_sweep --exact --ignored --nocapture" } else { "" } } else { "" } }}
     @# LAPIC-enabled MSHV can expose additional MSRs. Audit it once in debug.
-    {{ if features == "mshv3,hw-interrupts" { if target == "debug" { if hyperlight-target-arch == "x86_64" { cargo-cmd + " test --no-default-features -F mshv3,hw-interrupts --profile=dev " + target-triple-flag + " -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::msr_tests::test_no_msr_leaks_across_restore_full_window_sweep --exact --ignored --nocapture" } else { "" } } else { "" } } else { "" } }}
+    {{ if features == "mshv3,hw-interrupts" { if target == "debug" { if hyperlight-target-arch == "x86_64" { cargo-cmd + " test --no-default-features -F mshv3,hw-interrupts --profile=dev " + target-triple-flag + " -p hyperlight-host --lib -- sandbox::initialized::tests::msr_tests::test_no_msr_leaks_across_restore_full_window_sweep --exact --ignored --nocapture" } else { "" } } else { "" } } else { "" } }}
     @# metrics tests
     {{ cargo-cmd }} test {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F function_call_metrics," + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} -p hyperlight-host --lib -- metrics::tests::test_metrics_are_emitted --exact
 
@@ -551,11 +551,11 @@ coverage-run hypervisor="kvm": ensure-cargo-llvm-cov
     # isolated tests (require running separately due to global state)
     cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::uninitialized::tests::test_log_trace --exact --ignored
     cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::outb::tests::test_log_emit_guest_log --exact --ignored
-    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_is_honored_from_snapshot --exact --ignored
-    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_overrides_initialized_snapshot --exact --ignored
-    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_setter_survives_restore --exact --ignored
-    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_can_be_disabled_and_reenabled --exact --ignored
-    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized_multi_use::tests::from_snapshot::max_guest_log_level_can_be_enabled_after_off_init --exact --ignored
+    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_is_honored_from_snapshot --exact --ignored
+    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_overrides_initialized_snapshot --exact --ignored
+    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_setter_survives_restore --exact --ignored
+    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_disabled_and_reenabled --exact --ignored
+    cargo +{{nightly-toolchain}} test -p hyperlight-host --lib -- sandbox::initialized::tests::from_snapshot::max_guest_log_level_can_be_enabled_after_off_init --exact --ignored
     cargo +{{nightly-toolchain}} test -p hyperlight-host --test integration_test -- log_message --exact --ignored
     cargo +{{nightly-toolchain}} test -p hyperlight-host --no-default-features -F function_call_metrics,{{ if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }} --lib -- metrics::tests::test_metrics_are_emitted --exact
 

src/hyperlight_component_util/src/host.rs

@@ -408,7 +408,7 @@ fn emit_component<'a, 'b, 'c>(s: &'c mut State<'a, 'b>, wn: WitName, ct: &'c Com
             #(#exports)*
         }
         impl #ns::#r#trait<::hyperlight_common::component::Positive> for ::hyperlight_host::sandbox::UninitializedSandbox {
-            type Exports<I: #ns::#import_trait<::hyperlight_common::component::Negative> + ::std::marker::Send> = #wrapper_name<I, ::hyperlight_host::sandbox::initialized_multi_use::Sandbox>;
+            type Exports<I: #ns::#import_trait<::hyperlight_common::component::Negative> + ::std::marker::Send> = #wrapper_name<I, ::hyperlight_host::sandbox::Sandbox>;
             fn instantiate<I: #ns::#import_trait<::hyperlight_common::component::Negative> + ::std::marker::Send + 'static>(mut self, i: I) -> <::hyperlight_common::component::Positive as ::hyperlight_common::component::Positivity>::CallResult<Self::Exports<I>> {
                 let rts = register_host_functions(&mut self, i)?;
                 let sb = self.evolve()?;

…ost/src/sandbox/initialized_multi_use.rs …perlight_host/src/sandbox/initialized.rssrc/hyperlight_host/src/sandbox/initialized_multi_use.rs renamed to src/hyperlight_host/src/sandbox/initialized.rs src/hyperlight_host/src/sandbox/initialized_multi_use.rs renamed to src/hyperlight_host/src/sandbox/initialized.rs

@@ -11,7 +11,14 @@ pub(crate) mod file_mapping;
 pub(crate) mod host_funcs;
 /// Functionality for dealing with initialized sandboxes that can
 /// call 0 or more guest functions
-pub mod initialized_multi_use;
+mod initialized;
+/// Deprecated path for the items in the `initialized` module.
+#[deprecated(since = "0.17.0", note = "use hyperlight_host::sandbox")]
+pub mod initialized_multi_use {
+    #[allow(deprecated)]
+    pub use super::initialized::MultiUseSandbox;
+    pub use super::initialized::{PtRootFinder, Sandbox, SandboxStatus};
+}
 pub(crate) mod outb;
 /// Functionality for creating uninitialized sandboxes, manipulating them,
 /// and converting them to initialized sandboxes.
@@ -36,9 +43,9 @@ pub use callable::Callable;
 pub use config::SandboxConfiguration;
 /// Re-export for the deprecated `MultiUseSandbox` name
 #[allow(deprecated)]
-pub use initialized_multi_use::MultiUseSandbox;
+pub use initialized::MultiUseSandbox;
 /// Re-export for the `Sandbox` type
-pub use initialized_multi_use::{PtRootFinder, Sandbox, SandboxStatus};
+pub use initialized::{PtRootFinder, Sandbox, SandboxStatus};
 /// Re-export for `GuestBinary` type
 pub use uninitialized::GuestBinary;
 /// Re-export for `UninitializedSandbox` type

src/hyperlight_host/src/sandbox/mod.rs

@@ -1051,12 +1051,11 @@ mod tests {
             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");
+            // An existing file that is never a valid guest binary.
+            let mut invalid_binary_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+            invalid_binary_path.push("Cargo.toml");
 
-            let sbox = UninitializedSandbox::new(GuestBinary::FilePath(valid_binary_path), None);
+            let sbox = UninitializedSandbox::new(GuestBinary::FilePath(invalid_binary_path), None);
             assert!(sbox.is_err());
 
             // There should be 2 calls this time when we change to the log
@@ -1076,11 +1075,7 @@ mod tests {
 
             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!(logcall.args.starts_with("error=PEFileProcessingFailure"));
             assert_eq!("hyperlight_host::sandbox::uninitialized", logcall.target);
         }
         {