fix: use PathBuf instead of String for guest binary and crash dump paths

CHANGELOG.md

@@ -12,6 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   declared MSRs are captured in a snapshot and restored, while every other MSR
   resets to a clean default. On KVM the guest may only read or write declared
   MSRs, on MSHV and WHP this is not enforced. by @ludfjig in https://github.com/hyperlight-dev/hyperlight/pull/991
+* **Breaking:** Filesystem paths are now represented using `PathBuf`. `GuestBinary::FilePath` now stores a `PathBuf` instead of a `String`, and `MultiUseSandbox::generate_crashdump_to_dir` accepts `Into<PathBuf>` instead of `Into<String>`. Callers passing a `String` to `GuestBinary::FilePath` must convert it using `.into()`.
 
 ### Removed
 

fuzz/fuzz_targets/guest_call.rs

@@ -21,7 +21,7 @@ use std::sync::{Mutex, OnceLock};
 use hyperlight_host::func::{ParameterValue, ReturnType};
 use hyperlight_host::sandbox::uninitialized::GuestBinary;
 use hyperlight_host::{MultiUseSandbox, UninitializedSandbox};
-use hyperlight_testing::simple_guest_for_fuzzing_as_string;
+use hyperlight_testing::simple_guest_for_fuzzing_as_pathbuf;
 use libfuzzer_sys::fuzz_target;
 static SANDBOX: OnceLock<Mutex<MultiUseSandbox>> = OnceLock::new();
 
@@ -31,7 +31,7 @@ fuzz_target!(
     init: {
 
         let u_sbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
+            GuestBinary::FilePath(simple_guest_for_fuzzing_as_pathbuf()),
             None,
         )
         .unwrap();

fuzz/fuzz_targets/guest_trace.rs

@@ -25,7 +25,7 @@ use hyperlight_host::func::{ParameterValue, ReturnType, ReturnValue};
 use hyperlight_host::sandbox::SandboxConfiguration;
 use hyperlight_host::sandbox::uninitialized::GuestBinary;
 use hyperlight_host::{MultiUseSandbox, UninitializedSandbox};
-use hyperlight_testing::simple_guest_for_fuzzing_as_string;
+use hyperlight_testing::simple_guest_for_fuzzing_as_pathbuf;
 use libfuzzer_sys::arbitrary::Arbitrary;
 use libfuzzer_sys::{Corpus, fuzz_target};
 
@@ -71,12 +71,9 @@ fuzz_target!(
         let mut cfg = SandboxConfiguration::default();
         // In local tests, 256 KiB seemed sufficient for deep recursion
         cfg.set_scratch_size(256 * 1024);
-        let path = simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing");
-        let u_sbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(path),
-            Some(cfg),
-        )
-        .unwrap();
+        let path = simple_guest_for_fuzzing_as_pathbuf();
+        let u_sbox =
+            UninitializedSandbox::new(GuestBinary::FilePath(path), Some(cfg)).unwrap();
 
         let mu_sbox: MultiUseSandbox = u_sbox.evolve().unwrap();
 

fuzz/fuzz_targets/host_call.rs

@@ -23,7 +23,7 @@ use hyperlight_host::func::{ParameterValue, ReturnType};
 use hyperlight_host::sandbox::SandboxConfiguration;
 use hyperlight_host::sandbox::uninitialized::GuestBinary;
 use hyperlight_host::{HyperlightError, MultiUseSandbox, UninitializedSandbox};
-use hyperlight_testing::simple_guest_for_fuzzing_as_string;
+use hyperlight_testing::simple_guest_for_fuzzing_as_pathbuf;
 use libfuzzer_sys::fuzz_target;
 
 static SANDBOX: OnceLock<Mutex<MultiUseSandbox>> = OnceLock::new();
@@ -37,7 +37,7 @@ fuzz_target!(
         cfg.set_input_data_size(64 * 1024); // 64 KB input buffer
         cfg.set_scratch_size(512 * 1024); // large scratch region to contain those buffers, any data copies, etc.
         let u_sbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
+            GuestBinary::FilePath(simple_guest_for_fuzzing_as_pathbuf()),
             Some(cfg)
         )
         .unwrap();

fuzz/fuzz_targets/host_print.rs

@@ -4,7 +4,7 @@ use std::sync::{Mutex, OnceLock};
 
 use hyperlight_host::sandbox::uninitialized::GuestBinary;
 use hyperlight_host::{MultiUseSandbox, UninitializedSandbox};
-use hyperlight_testing::simple_guest_for_fuzzing_as_string;
+use hyperlight_testing::simple_guest_for_fuzzing_as_pathbuf;
 use libfuzzer_sys::{Corpus, fuzz_target};
 
 static SANDBOX: OnceLock<Mutex<MultiUseSandbox>> = OnceLock::new();
@@ -16,7 +16,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")),
+            GuestBinary::FilePath(simple_guest_for_fuzzing_as_pathbuf()),
             None,
         )
         .unwrap();

src/hyperlight_host/benches/benchmarks.rs

@@ -27,7 +27,7 @@ use hyperlight_host::GuestBinary;
 use hyperlight_host::mem::shared_mem::ExclusiveSharedMemory;
 use hyperlight_host::sandbox::{MultiUseSandbox, SandboxConfiguration, UninitializedSandbox};
 use hyperlight_testing::sandbox_sizes::{LARGE_HEAP_SIZE, MEDIUM_HEAP_SIZE, SMALL_HEAP_SIZE};
-use hyperlight_testing::{c_simple_guest_as_string, simple_guest_as_string};
+use hyperlight_testing::{c_simple_guest_as_pathbuf, simple_guest_as_pathbuf};
 
 /// Sandbox heap size configurations for benchmarking.
 /// Only affects heap size - all other configuration remains at defaults.
@@ -86,7 +86,7 @@ impl SandboxSize {
 }
 
 fn create_uninit_sandbox_with_size(size: SandboxSize) -> UninitializedSandbox {
-    let path = simple_guest_as_string().unwrap();
+    let path = simple_guest_as_pathbuf();
     UninitializedSandbox::new(GuestBinary::FilePath(path), size.config()).unwrap()
 }
 
@@ -416,7 +416,7 @@ fn guest_call_benchmark_large_param(c: &mut Criterion) {
         config.set_scratch_size(6 * SIZE + 4 * (1024 * 1024)); // Big enough for the IO data regions and enough of the heap to be used
 
         let sandbox = UninitializedSandbox::new(
-            GuestBinary::FilePath(simple_guest_as_string().unwrap()),
+            GuestBinary::FilePath(simple_guest_as_pathbuf()),
             Some(config),
         )
         .unwrap();
@@ -494,7 +494,7 @@ fn function_call_serialization_benchmark(c: &mut Criterion) {
 fn sample_workloads_benchmark(c: &mut Criterion) {
     let mut group = c.benchmark_group("sample_workloads");
 
-    fn bench_24k_in_8k_out(b: &mut criterion::Bencher, guest_path: String) {
+    fn bench_24k_in_8k_out(b: &mut criterion::Bencher, guest_path: std::path::PathBuf) {
         let mut cfg = SandboxConfiguration::default();
         cfg.set_input_data_size(25 * 1024);
 
@@ -514,11 +514,11 @@ fn sample_workloads_benchmark(c: &mut Criterion) {
     }
 
     group.bench_function("24K_in_8K_out_c", |b| {
-        bench_24k_in_8k_out(b, c_simple_guest_as_string().unwrap());
+        bench_24k_in_8k_out(b, c_simple_guest_as_pathbuf());
     });
 
     group.bench_function("24K_in_8K_out_rust", |b| {
-        bench_24k_in_8k_out(b, simple_guest_as_string().unwrap());
+        bench_24k_in_8k_out(b, simple_guest_as_pathbuf());
     });
 
     group.finish();

src/hyperlight_host/examples/crashdump/main.rs

@@ -73,6 +73,7 @@ limitations under the License.
 
 #[cfg(all(crashdump, target_os = "linux"))]
 use std::io::Write;
+use std::path::Path;
 
 #[cfg(all(crashdump, target_os = "linux"))]
 use hyperlight_host::HyperlightError;
@@ -86,8 +87,7 @@ fn main() -> hyperlight_host::Result<()> {
         env_logger::init();
     }
 
-    let guest_path =
-        hyperlight_testing::simple_guest_as_string().expect("Cannot find simpleguest binary");
+    let guest_path = hyperlight_testing::simple_guest_as_pathbuf();
 
     println!("=== Hyperlight Crash Dump Example ===\n");
 
@@ -139,11 +139,11 @@ fn main() -> hyperlight_host::Result<()> {
 /// 3. The hypervisor rejects the write → `MemoryAccessViolation`
 /// 4. The crash dump is written automatically (no explicit call needed)
 #[cfg(all(crashdump, target_os = "linux"))]
-fn guest_crash_auto_dump(guest_path: &str) -> hyperlight_host::Result<()> {
+fn guest_crash_auto_dump(guest_path: &Path) -> hyperlight_host::Result<()> {
     let cfg = SandboxConfiguration::default();
 
     let uninitialized_sandbox =
-        UninitializedSandbox::new(GuestBinary::FilePath(guest_path.to_string()), Some(cfg))?;
+        UninitializedSandbox::new(GuestBinary::FilePath(guest_path.to_path_buf()), Some(cfg))?;
 
     let mut sandbox: MultiUseSandbox = uninitialized_sandbox.evolve()?;
 
@@ -173,7 +173,7 @@ fn guest_crash_auto_dump(guest_path: &str) -> hyperlight_host::Result<()> {
 
 /// Fallback when crashdump feature or Linux is not available.
 #[cfg(not(all(crashdump, target_os = "linux")))]
-fn guest_crash_auto_dump(_guest_path: &str) -> hyperlight_host::Result<()> {
+fn guest_crash_auto_dump(_guest_path: &Path) -> hyperlight_host::Result<()> {
     println!(
         "This part requires the `crashdump` feature and Linux.\n\
          Re-run with: cargo run --example crashdump --features crashdump"
@@ -204,11 +204,11 @@ fn create_mapping_file() -> std::path::PathBuf {
 /// Because the error is reported through the I/O path (not a VM-level
 /// fault), the automatic crash dump code in the VM run loop is not reached.
 /// To get a crash dump in this case, call `generate_crashdump()` explicitly.
-fn guest_crash_with_on_demand_dump(guest_path: &str) -> hyperlight_host::Result<()> {
+fn guest_crash_with_on_demand_dump(guest_path: &Path) -> hyperlight_host::Result<()> {
     let cfg = SandboxConfiguration::default();
 
     let uninitialized_sandbox =
-        UninitializedSandbox::new(GuestBinary::FilePath(guest_path.to_string()), Some(cfg))?;
+        UninitializedSandbox::new(GuestBinary::FilePath(guest_path.to_path_buf()), Some(cfg))?;
 
     let mut sandbox: MultiUseSandbox = uninitialized_sandbox.evolve()?;
 
@@ -245,13 +245,13 @@ fn guest_crash_with_on_demand_dump(guest_path: &str) -> hyperlight_host::Result<
 /// (e.g., during fuzzing or testing) and you don't want the overhead of
 /// writing core dump files.
 #[cfg(all(crashdump, target_os = "linux"))]
-fn guest_crash_with_dump_disabled(guest_path: &str) -> hyperlight_host::Result<()> {
+fn guest_crash_with_dump_disabled(guest_path: &Path) -> hyperlight_host::Result<()> {
     let mut cfg = SandboxConfiguration::default();
     cfg.set_guest_core_dump(false);
     println!("Core dump disabled for this sandbox.");
 
     let uninitialized_sandbox =
-        UninitializedSandbox::new(GuestBinary::FilePath(guest_path.to_string()), Some(cfg))?;
+        UninitializedSandbox::new(GuestBinary::FilePath(guest_path.to_path_buf()), Some(cfg))?;
 
     let mut sandbox: MultiUseSandbox = uninitialized_sandbox.evolve()?;
 
@@ -277,7 +277,7 @@ fn guest_crash_with_dump_disabled(guest_path: &str) -> hyperlight_host::Result<(
 
 /// Fallback when crashdump feature or Linux is not available.
 #[cfg(not(all(crashdump, target_os = "linux")))]
-fn guest_crash_with_dump_disabled(_guest_path: &str) -> hyperlight_host::Result<()> {
+fn guest_crash_with_dump_disabled(_guest_path: &Path) -> hyperlight_host::Result<()> {
     println!(
         "This part requires the `crashdump` feature and Linux.\n\
          Re-run with: cargo run --example crashdump --features crashdump"
@@ -387,8 +387,7 @@ mod tests {
         let data_file = create_test_data_file(dump_dir);
 
         // Create sandbox with default config (crashdump enabled)
-        let guest_path =
-            hyperlight_testing::simple_guest_as_string().expect("Cannot find simpleguest binary");
+        let guest_path = hyperlight_testing::simple_guest_as_pathbuf();
         let cfg = SandboxConfiguration::default();
         let u_sbox =
             UninitializedSandbox::new(GuestBinary::FilePath(guest_path), Some(cfg)).unwrap();
@@ -428,7 +427,7 @@ mod tests {
         // IO-based errors (GuestAborted), so we call generate_crashdump()
         // explicitly — this is the recommended workflow for post-mortem
         // debugging anyway.
-        sbox.generate_crashdump_to_dir(dump_dir.to_string_lossy())
+        sbox.generate_crashdump_to_dir(dump_dir)
             .expect("generate_crashdump should succeed");
 
         // Find the generated hl_core_*.elf file. The dump dir is a fresh
@@ -460,8 +459,7 @@ mod tests {
     /// ELF core dump. Used to check that crash dumps from snapshot-created
     /// sandboxes resolve symbols the same way as directly-evolved ones.
     fn generate_crashdump_from_snapshot(dump_dir: &Path) -> PathBuf {
-        let guest_path =
-            hyperlight_testing::simple_guest_as_string().expect("Cannot find simpleguest binary");
+        let guest_path = hyperlight_testing::simple_guest_as_pathbuf();
         let mut cfg = SandboxConfiguration::default();
         cfg.set_guest_core_dump(true);
         let u_sbox =
@@ -479,7 +477,7 @@ mod tests {
         assert!(result.is_err(), "TriggerException should return an error");
 
         sbox2
-            .generate_crashdump_to_dir(dump_dir.to_string_lossy())
+            .generate_crashdump_to_dir(dump_dir)
             .expect("generate_crashdump should succeed");
 
         // The dump dir is a fresh per-test tempdir, so exactly one core
@@ -528,7 +526,7 @@ mod tests {
         // module prefix rather than one specific function.
         const EXPECTED_SYMBOL: &str = "hyperlight_guest::exit::";
 
-        let guest_path = hyperlight_testing::simple_guest_as_string().expect("simpleguest binary");
+        let guest_path = hyperlight_testing::simple_guest_as_pathbuf();
 
         let cmd_file = dump_dir.join("gdb_sym_cmds.txt");
         let out_file = dump_dir.join("gdb_sym_output.txt");
@@ -636,7 +634,7 @@ quit
 
         let dump_dir = tempfile::tempdir().expect("create temp dir");
         let core_path = generate_crashdump_with_content(dump_dir.path());
-        let guest_path = hyperlight_testing::simple_guest_as_string().expect("simpleguest binary");
+        let guest_path = hyperlight_testing::simple_guest_as_pathbuf();
 
         let cmd_file = dump_dir.path().join("gdb_reg_cmds.txt");
         let out_file = dump_dir.path().join("gdb_reg_output.txt");
@@ -655,7 +653,7 @@ set logging enabled off
 quit
 ",
             out = out_file.display(),
-            binary = guest_path,
+            binary = guest_path.display(),
             core = core_path.display(),
         );
 
@@ -683,7 +681,7 @@ quit
     fn test_crashdump_gdb_memory() {
         let dump_dir = tempfile::tempdir().expect("create temp dir");
         let core_path = generate_crashdump_with_content(dump_dir.path());
-        let guest_path = hyperlight_testing::simple_guest_as_string().expect("simpleguest binary");
+        let guest_path = hyperlight_testing::simple_guest_as_pathbuf();
 
         let cmd_file = dump_dir.path().join("gdb_mem_cmds.txt");
         let out_file = dump_dir.path().join("gdb_mem_output.txt");
@@ -704,7 +702,7 @@ set logging enabled off
 quit
 ",
             out = out_file.display(),
-            binary = guest_path,
+            binary = guest_path.display(),
             core = core_path.display(),
             addr = MAP_GUEST_BASE,
         );

src/hyperlight_host/examples/func_ctx/main.rs

@@ -16,12 +16,12 @@ limitations under the License.
 
 use hyperlight_host::GuestBinary;
 use hyperlight_host::sandbox::UninitializedSandbox;
-use hyperlight_testing::simple_guest_as_string;
+use hyperlight_testing::simple_guest_as_pathbuf;
 
 fn main() {
     // create a new `MultiUseSandbox` configured to run the `simpleguest.exe`
     // test guest binary
-    let path = simple_guest_as_string().unwrap();
+    let path = simple_guest_as_pathbuf();
     let mut sbox = UninitializedSandbox::new(GuestBinary::FilePath(path), None)
         .unwrap()
         .evolve()

src/hyperlight_host/examples/guest-debugging/main.rs

@@ -40,17 +40,13 @@ fn main() -> hyperlight_host::Result<()> {
 
     // Create an uninitialized sandbox with a guest binary and debug enabled
     let mut uninitialized_sandbox_dbg = UninitializedSandbox::new(
-        hyperlight_host::GuestBinary::FilePath(
-            hyperlight_testing::simple_guest_as_string().unwrap(),
-        ),
+        hyperlight_host::GuestBinary::FilePath(hyperlight_testing::simple_guest_as_pathbuf()),
         cfg, // sandbox configuration
     )?;
 
     // 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::GuestBinary::FilePath(hyperlight_testing::simple_guest_as_pathbuf()),
         None, // sandbox configuration
     )?;
 
@@ -378,9 +374,7 @@ mod tests {
 
         // Build a sandbox the normal way and snapshot it in-memory.
         let mut producer: MultiUseSandbox = UninitializedSandbox::new(
-            hyperlight_host::GuestBinary::FilePath(
-                hyperlight_testing::simple_guest_as_string().unwrap(),
-            ),
+            hyperlight_host::GuestBinary::FilePath(hyperlight_testing::simple_guest_as_pathbuf()),
             None,
         )
         .unwrap()

src/hyperlight_host/examples/hello-world/main.rs

@@ -20,9 +20,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::GuestBinary::FilePath(hyperlight_testing::simple_guest_as_pathbuf()),
         None, // default configuration
     )?;
 

src/hyperlight_host/examples/logging/main.rs

@@ -19,7 +19,7 @@ use std::sync::{Arc, Barrier};
 
 use hyperlight_host::sandbox::uninitialized::UninitializedSandbox;
 use hyperlight_host::{GuestBinary, Result};
-use hyperlight_testing::simple_guest_as_string;
+use hyperlight_testing::simple_guest_as_pathbuf;
 
 fn fn_writer(_msg: String) -> Result<i32> {
     Ok(0)
@@ -33,8 +33,7 @@ fn main() -> Result<()> {
         .parse_filters("none,hyperlight=info")
         .init();
     // Get the path to a simple guest binary.
-    let hyperlight_guest_path =
-        simple_guest_as_string().expect("Cannot find the guest binary at the expected location.");
+    let hyperlight_guest_path = simple_guest_as_pathbuf();
 
     for _ in 0..20 {
         let path = hyperlight_guest_path.clone();

src/hyperlight_host/examples/map-file-cow-test/main.rs

@@ -39,9 +39,7 @@ fn run_once(test_file: &Path, label: &str) -> hyperlight_host::Result<()> {
     config.set_scratch_size(64 * 1024 * 1024);
 
     let mut usbox = UninitializedSandbox::new(
-        hyperlight_host::GuestBinary::FilePath(
-            hyperlight_testing::simple_guest_as_string().unwrap(),
-        ),
+        hyperlight_host::GuestBinary::FilePath(hyperlight_testing::simple_guest_as_pathbuf()),
         Some(config),
     )?;
     eprintln!("[{label}] UninitializedSandbox::new OK");