diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000000..de8fd3c074 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,5 @@ +{ + "env": { + "CLAUDE_CODE_TASK_LIST_ID": "feature-minvmd-host-daemon" + } +} diff --git a/Cargo.lock b/Cargo.lock index bfcd300b83..aac1c39462 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3373,6 +3373,17 @@ dependencies = [ "simd-adler32", ] +[[package]] +name = "minvmd" +version = "0.0.1" +dependencies = [ + "anyhow", + "clap", + "clap_complete", + "tracing", + "tracing-subscriber", +] + [[package]] name = "mio" version = "1.2.0" diff --git a/Cargo.toml b/Cargo.toml index 1c7420836c..9c094b1def 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,6 +17,7 @@ members = [ "crates/minimal", "crates/minimal2", "crates/minimald", + "crates/minvmd", "crates/remote-client", "crates/remote-proto", "crates/sandbox2", diff --git a/crates/minvmd/Cargo.toml b/crates/minvmd/Cargo.toml new file mode 100644 index 0000000000..69dfb70220 --- /dev/null +++ b/crates/minvmd/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "minvmd" +version = "0.0.1" +edition.workspace = true +publish.workspace = true + +[dependencies] +anyhow.workspace = true +clap.workspace = true +clap_complete.workspace = true +tracing.workspace = true +tracing-subscriber.workspace = true diff --git a/crates/minvmd/build.rs b/crates/minvmd/build.rs new file mode 100644 index 0000000000..348b1a44e1 --- /dev/null +++ b/crates/minvmd/build.rs @@ -0,0 +1,21 @@ +//! Build script for `minvmd`. +//! +//! On macOS, wires up the link search path and rpath for libkrun. The libkrun +//! prefix defaults to `/opt/homebrew/lib` (the Homebrew tap install location +//! used by `~/code/min-ctl`); override with the `LIBKRUN_PREFIX` env var. +//! +//! On Linux this is a no-op — the crate compiles to a runtime-bailing stub +//! per R1.1 and never links libkrun. + +fn main() { + println!("cargo:rerun-if-env-changed=LIBKRUN_PREFIX"); + + if std::env::var_os("CARGO_CFG_TARGET_OS").as_deref() != Some("macos".as_ref()) { + return; + } + + let prefix = + std::env::var("LIBKRUN_PREFIX").unwrap_or_else(|_| "/opt/homebrew/lib".to_string()); + println!("cargo:rustc-link-search=native={prefix}"); + println!("cargo:rustc-link-arg=-Wl,-rpath,{prefix}"); +} diff --git a/crates/minvmd/minvmd.entitlements b/crates/minvmd/minvmd.entitlements new file mode 100644 index 0000000000..154f3308ef --- /dev/null +++ b/crates/minvmd/minvmd.entitlements @@ -0,0 +1,8 @@ + + + + + com.apple.security.hypervisor + + + diff --git a/crates/minvmd/src/bin/krun_smoke_child.rs b/crates/minvmd/src/bin/krun_smoke_child.rs new file mode 100644 index 0000000000..6a79ea6f35 --- /dev/null +++ b/crates/minvmd/src/bin/krun_smoke_child.rs @@ -0,0 +1,97 @@ +//! Test helper binary for `tests/krun_smoke.rs`. +//! +//! Exists as a separate process because `krun_start_enter`, on success, calls +//! `exit()` with the guest workload's exit code and never returns. Driving it +//! from inside the test process would tear down the test harness; running it +//! in a child lets the parent test observe the outcome via the child's exit +//! status. +//! +//! Behaviour: +//! 1. Always drive the FFI bring-up surface: create_ctx → set_vm_config(1, 512) +//! → set_exec("/bin/true"). Print stage markers. +//! 2. If `MINVMD_KERNEL_PATH` and `MINVMD_ROOTFS_PATH` are both set, also +//! configure them and call `krun_start_enter`. Without either, skip +//! start_enter — libkrun aborts internally on an incomplete config, so +//! calling it would be a false-negative for the FFI surface itself. +//! +//! Exit codes: +//! 0 — bring-up surface drove cleanly; or guest workload (/bin/true) ran. +//! 2 — start_enter returned an error (libkrun-side failure before boot). +//! 125/126/127 — libkrun init-time error codes per `krun_start_enter` docs. +//! +//! Linux is a no-op stub (exit 0); the integration test is `target_os = macos`. + +fn main() { + #[cfg(not(target_os = "macos"))] + { + eprintln!("krun_smoke_child: macOS-only; nothing to do on this platform"); + std::process::exit(0); + } + + #[cfg(target_os = "macos")] + { + run_macos(); + } +} + +#[cfg(target_os = "macos")] +fn run_macos() { + use minvmd::krun::Context; + use minvmd::krun::raw::{KRUN_KERNEL_FORMAT_IMAGE_BZ2, KRUN_KERNEL_FORMAT_IMAGE_GZ}; + + eprintln!("STAGE: create_ctx"); + let mut ctx = Context::create().expect("krun_create_ctx must succeed"); + eprintln!("STAGE: create_ctx ok ctx_id={}", ctx.id()); + + eprintln!("STAGE: set_vm_config"); + ctx.set_vm_config(1, 512) + .expect("krun_set_vm_config 1 vcpu / 512 MiB must succeed"); + eprintln!("STAGE: set_vm_config ok"); + + eprintln!("STAGE: set_exec"); + ctx.set_exec("/bin/true", &[] as &[&str], None::<&[&str]>) + .expect("krun_set_exec /bin/true must succeed"); + eprintln!("STAGE: set_exec ok"); + + let kernel = std::env::var("MINVMD_KERNEL_PATH").ok(); + let rootfs = std::env::var("MINVMD_ROOTFS_PATH").ok(); + let Some((kernel, rootfs)) = kernel.zip(rootfs) else { + eprintln!( + "STAGE: skip_start_enter \ + (MINVMD_KERNEL_PATH or MINVMD_ROOTFS_PATH unset; FFI bring-up verified, \ + start_enter requires kernel + rootfs configured per R2.1 / R2.2)" + ); + drop(ctx); // RAII free_ctx + std::process::exit(0); + }; + + eprintln!("STAGE: set_root path={rootfs}"); + ctx.set_root(&rootfs).expect("krun_set_root must succeed"); + eprintln!("STAGE: set_root ok"); + + // Per-arch kernel format: virtio-linux (pkgs#154) ships `Image.gz` on + // aarch64 and `bzImage` on x86_64 (R2.1). + let format = if cfg!(target_arch = "aarch64") { + KRUN_KERNEL_FORMAT_IMAGE_GZ + } else { + KRUN_KERNEL_FORMAT_IMAGE_BZ2 + }; + eprintln!("STAGE: set_kernel path={kernel} format={format}"); + ctx.set_kernel( + &kernel, + format, + None::<&std::path::Path>, + None, // cmdline + ) + .expect("krun_set_kernel must succeed"); + eprintln!("STAGE: set_kernel ok"); + + eprintln!("STAGE: start_enter"); + let err = ctx.start_enter(); + // Reaching this point means start_enter returned an error (libkrun + // `exit()`s on success and never comes back). Surface the typed error + // and report exit 2 so the parent test can distinguish from a clean + // workload run (exit 0) or libkrun init errors (125/126/127). + eprintln!("STAGE: start_enter returned: {err}"); + std::process::exit(2); +} diff --git a/crates/minvmd/src/error.rs b/crates/minvmd/src/error.rs new file mode 100644 index 0000000000..2ba1572b40 --- /dev/null +++ b/crates/minvmd/src/error.rs @@ -0,0 +1,135 @@ +//! Typed errors for `minvmd`. +//! +//! Library code returns `VmError`; CLI / boundary code wraps in +//! `anyhow::Result`. Per spec lesson "error fidelity": `Backend` preserves the +//! original libkrun errno so the source magnitude survives any wrap-and-rethrow. + +use std::fmt; +use std::path::PathBuf; + +/// Errors produced by `minvmd`'s VM layer. +#[derive(Debug)] +#[non_exhaustive] +pub enum VmError { + /// A libkrun FFI call returned a negative errno. `op` names the libkrun + /// function so the caller can attribute the failure without parsing + /// strings; `code` is the absolute errno magnitude (libkrun returns + /// negative errnos; we strip the sign before surfacing). + Backend { op: &'static str, code: i32 }, + + /// A caller-supplied path contained a NUL byte and cannot be passed across + /// the C FFI boundary. `what` identifies the parameter for diagnostics. + NulInPath { what: &'static str, path: PathBuf }, + + /// A caller-supplied string (e.g. an env var or argv entry) contained a + /// NUL byte and cannot be passed across the C FFI boundary. + NulInString { what: &'static str, value: String }, + + /// `krun_start_enter` returned a non-negative value. libkrun's docs state + /// the function only returns on error (on success it `exit()`s the host + /// process with the guest workload's exit code), so a non-negative + /// return is a protocol violation. `ret` is the raw libkrun return. + StartEnterReturnedUnexpectedly { ret: i32 }, +} + +impl fmt::Display for VmError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Backend { op, code } => { + write!(f, "libkrun {op} returned errno {code}") + } + Self::NulInPath { what, path } => { + write!( + f, + "{what} path contains a NUL byte and cannot cross the FFI boundary: {}", + path.display() + ) + } + Self::NulInString { what, value } => { + write!( + f, + "{what} contains a NUL byte and cannot cross the FFI boundary: {value:?}" + ) + } + Self::StartEnterReturnedUnexpectedly { ret } => { + write!( + f, + "krun_start_enter returned {ret} but libkrun's docs say it only returns on error" + ) + } + } + } +} + +impl std::error::Error for VmError {} + +impl VmError { + /// Translate a libkrun return code into a `Result`. libkrun returns zero + /// (or a positive id) on success and a negative errno on failure; we + /// preserve the magnitude as a positive `code` per spec lesson "error + /// fidelity". + #[inline] + pub(crate) fn check_backend(op: &'static str, ret: i32) -> Result { + if ret < 0 { + Err(VmError::Backend { + op, + code: ret.unsigned_abs() as i32, + }) + } else { + Ok(ret) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn backend_check_passes_through_success() { + assert_eq!(VmError::check_backend("op", 0).unwrap(), 0); + assert_eq!(VmError::check_backend("op", 7).unwrap(), 7); + } + + #[test] + fn backend_check_translates_negative_to_typed_error() { + let err = VmError::check_backend("krun_create_ctx", -22).unwrap_err(); + match err { + VmError::Backend { op, code } => { + assert_eq!(op, "krun_create_ctx"); + assert_eq!(code, 22, "errno magnitude must be preserved"); + } + other => panic!("expected Backend, got {other:?}"), + } + } + + #[test] + fn display_includes_op_and_code() { + let err = VmError::Backend { + op: "krun_set_vm_config", + code: 12, + }; + let s = format!("{err}"); + assert!(s.contains("krun_set_vm_config"), "display: {s}"); + assert!(s.contains("12"), "display: {s}"); + } + + #[test] + fn display_start_enter_returned_unexpectedly() { + let err = VmError::StartEnterReturnedUnexpectedly { ret: 0 }; + let s = format!("{err}"); + assert!(s.contains("krun_start_enter"), "display: {s}"); + assert!(s.contains("only returns on error"), "display: {s}"); + } + + #[test] + fn display_nul_in_path() { + let err = VmError::NulInPath { + what: "rootfs", + path: PathBuf::from("/tmp/bad"), + }; + let s = format!("{err}"); + assert!(s.contains("rootfs")); + assert!(s.contains("/tmp/bad")); + } +} diff --git a/crates/minvmd/src/krun/ctx.rs b/crates/minvmd/src/krun/ctx.rs new file mode 100644 index 0000000000..a0220b36a5 --- /dev/null +++ b/crates/minvmd/src/krun/ctx.rs @@ -0,0 +1,319 @@ +//! Safe wrappers around libkrun's context API. +//! +//! Every wrapper validates inputs in safe Rust (NUL-termination via +//! `CString`, range bounds, pointer/lifetime discipline) before crossing the +//! FFI boundary, then translates the libkrun return code via +//! [`VmError::check_backend`]. +//! +//! [`Context`] is an RAII handle: `Drop` calls `krun_free_ctx` so dropping +//! the value reliably releases the libkrun-side configuration. Methods that +//! consume the context ([`Context::start_enter`]) take `self` so the type +//! system prevents use-after-free / double-free. + +use std::ffi::{CString, c_char}; +use std::path::{Path, PathBuf}; +use std::ptr; + +use crate::error::VmError; +use crate::krun::raw; + +/// A libkrun configuration context. Holds a `ctx_id` and frees it on drop. +/// +/// The context is non-`Clone` / non-`Copy` so the id cannot be duplicated +/// past the lifetime of this handle. +#[must_use = "dropping the Context immediately frees the libkrun configuration"] +#[derive(Debug)] +pub struct Context { + ctx_id: u32, +} + +impl Context { + /// Create a new libkrun configuration context. + pub fn create() -> Result { + // SAFETY: krun_create_ctx takes no arguments and either returns a + // non-negative ctx_id (owned by the caller until krun_free_ctx) or a + // negative errno. No pointer or lifetime invariants apply. + let ret = unsafe { raw::krun_create_ctx() }; + let id = VmError::check_backend("krun_create_ctx", ret)?; + Ok(Self { ctx_id: id as u32 }) + } + + /// The underlying libkrun ctx id. Exposed for tests and the rare caller + /// that needs to drive raw FFI alongside the wrapper. + #[inline] + #[must_use] + pub fn id(&self) -> u32 { + self.ctx_id + } + + /// Set vcpu count and RAM (MiB). libkrun caps vcpus by hypervisor + /// support; pass a `u8` to make over-large counts unrepresentable. + pub fn set_vm_config(&mut self, num_vcpus: u8, ram_mib: u32) -> Result<(), VmError> { + // SAFETY: all arguments are passed by value; ctx_id refers to a + // context owned by `self` and not yet freed. No pointer invariants. + let ret = unsafe { raw::krun_set_vm_config(self.ctx_id, num_vcpus, ram_mib) }; + VmError::check_backend("krun_set_vm_config", ret)?; + Ok(()) + } + + /// Set the host directory backing the guest root filesystem. + pub fn set_root(&mut self, root_path: impl AsRef) -> Result<(), VmError> { + let path = root_path.as_ref(); + let cstr = cstring_from_path(path, "root")?; + // SAFETY: `cstr` is a CString owned by this stack frame; its pointer + // is valid (NUL-terminated, non-null) until the call returns. The + // ctx_id is owned by `self`. + let ret = unsafe { raw::krun_set_root(self.ctx_id, cstr.as_ptr()) }; + VmError::check_backend("krun_set_root", ret)?; + drop(cstr); + Ok(()) + } + + /// Set the executable to run inside the guest along with its argv and + /// envp. `envp = None` tells libkrun to inherit the host environment. + /// + /// `argv` does *not* include argv[0] — libkrun derives that from + /// `exec_path`. Pass the explicit arguments only. + pub fn set_exec( + &mut self, + exec_path: impl AsRef, + argv: &[impl AsRef], + envp: Option<&[impl AsRef]>, + ) -> Result<(), VmError> { + let exec_cstr = cstring_from_path(exec_path.as_ref(), "exec")?; + + let argv_cstrs = cstrings_from_strs(argv, "argv")?; + let mut argv_ptrs: Vec<*const c_char> = argv_cstrs.iter().map(|c| c.as_ptr()).collect(); + argv_ptrs.push(ptr::null()); // NULL-terminate per C convention + + // Bind envp storage and its pointer-vector at the same scope as the + // FFI call so both outlive the unsafe block. `envp_cstrs == None` + // means "inherit host env" per libkrun docs (pass NULL); a `Some` + // (including `Some(&[])`) gets a properly NULL-terminated array. + let envp_cstrs: Option> = match envp { + Some(entries) => Some(cstrings_from_strs(entries, "envp")?), + None => None, + }; + let (envp_ptrs, envp_ptr): (Vec<*const c_char>, *const *const c_char) = + match envp_cstrs.as_ref() { + Some(cstrs) => { + let mut ptrs: Vec<*const c_char> = cstrs.iter().map(|c| c.as_ptr()).collect(); + ptrs.push(ptr::null()); + let p = ptrs.as_ptr(); + (ptrs, p) + } + None => (Vec::new(), ptr::null()), + }; + + // SAFETY: + // - `exec_cstr` is a CString owned by this stack frame; its pointer + // is NUL-terminated and valid for the call. + // - `argv_ptrs` is owned by this stack frame, NULL-terminated, and + // each element points into a CString in `argv_cstrs` that is + // likewise owned by this stack frame for the call duration. + // - `envp_ptr` is either NULL (inherit host env) or points to + // `envp_ptrs`, a stack-owned NULL-terminated array whose elements + // point into `envp_cstrs`. All three locals are bound at the + // method scope and outlive this `unsafe` block. + // - `ctx_id` is owned by `self`. + let ret = unsafe { + raw::krun_set_exec( + self.ctx_id, + exec_cstr.as_ptr(), + argv_ptrs.as_ptr(), + envp_ptr, + ) + }; + // Keep the backing storage alive through the call. These are no-ops + // codegen-wise but make the lifetime contract visible to readers. + drop(exec_cstr); + drop(argv_ptrs); + drop(argv_cstrs); + drop(envp_ptrs); + drop(envp_cstrs); + VmError::check_backend("krun_set_exec", ret)?; + Ok(()) + } + + /// Set the kernel image to boot, its format, optional initramfs, and + /// optional cmdline. + pub fn set_kernel( + &mut self, + kernel_path: impl AsRef, + kernel_format: u32, + initramfs: Option>, + cmdline: Option<&str>, + ) -> Result<(), VmError> { + let kernel_cstr = cstring_from_path(kernel_path.as_ref(), "kernel")?; + let initramfs_cstr = match initramfs { + Some(p) => Some(cstring_from_path(p.as_ref(), "initramfs")?), + None => None, + }; + let cmdline_cstr = match cmdline { + Some(s) => Some(cstring_from_str(s, "cmdline")?), + None => None, + }; + + let initramfs_ptr = initramfs_cstr.as_ref().map_or(ptr::null(), |c| c.as_ptr()); + let cmdline_ptr = cmdline_cstr.as_ref().map_or(ptr::null(), |c| c.as_ptr()); + + // SAFETY: all *const c_char arguments either point into a CString + // owned by this stack frame for the call duration, or are NULL + // (libkrun documents NULL as valid for initramfs and cmdline). + // `ctx_id` is owned by `self`. + let ret = unsafe { + raw::krun_set_kernel( + self.ctx_id, + kernel_cstr.as_ptr(), + kernel_format, + initramfs_ptr, + cmdline_ptr, + ) + }; + drop(kernel_cstr); + drop(initramfs_cstr); + drop(cmdline_cstr); + VmError::check_backend("krun_set_kernel", ret)?; + Ok(()) + } + + /// Register a host UNIX socket path the guest can reach over the given + /// vsock port. + pub fn add_vsock_port( + &mut self, + port: u32, + host_socket: impl AsRef, + ) -> Result<(), VmError> { + let cstr = cstring_from_path(host_socket.as_ref(), "vsock_port")?; + // SAFETY: `cstr` owned by this stack frame for the call duration; + // `port` passed by value; `ctx_id` owned by `self`. + let ret = unsafe { raw::krun_add_vsock_port(self.ctx_id, port, cstr.as_ptr()) }; + drop(cstr); + VmError::check_backend("krun_add_vsock_port", ret)?; + Ok(()) + } + + /// Redirect implicit-console output to a host file. + pub fn set_console_output(&mut self, path: impl AsRef) -> Result<(), VmError> { + let cstr = cstring_from_path(path.as_ref(), "console_output")?; + // SAFETY: `cstr` owned by this stack frame for the call duration; + // `ctx_id` owned by `self`. + let ret = unsafe { raw::krun_set_console_output(self.ctx_id, cstr.as_ptr()) }; + drop(cstr); + VmError::check_backend("krun_set_console_output", ret)?; + Ok(()) + } + + /// Start the microVM. **Consumes the context** because libkrun documents + /// that `krun_start_enter` only returns on error — on success it `exit()`s + /// the host process with the guest workload's exit code. The returned + /// `VmError` is therefore unconditional: this function never returns + /// `Ok(_)`. Callers that want diverging semantics on success may + /// `std::process::exit` themselves after observing success in the parent. + pub fn start_enter(self) -> VmError { + // Move ctx_id out and forget `self` so `Drop` does NOT call + // krun_free_ctx — libkrun's docs say start_enter consumes the + // configuration regardless of outcome. Calling free after this would + // double-free. + let ctx_id = self.ctx_id; + std::mem::forget(self); + // SAFETY: `ctx_id` was owned by the consumed `self`; per libkrun's + // docs, krun_start_enter takes ownership of the configuration. No + // further wrapper calls referring to this id are valid. + let ret = unsafe { raw::krun_start_enter(ctx_id) }; + match VmError::check_backend("krun_start_enter", ret) { + // libkrun's docs guarantee start_enter only returns on error + // (success path: VMM calls exit() with the guest workload's + // exit code). A non-negative return is therefore a protocol + // violation; surface it as a distinct variant rather than + // pretending it was "errno 0". + Ok(ret) => VmError::StartEnterReturnedUnexpectedly { ret }, + Err(e) => e, + } + } +} + +impl Drop for Context { + fn drop(&mut self) { + // SAFETY: `ctx_id` was returned by a paired `krun_create_ctx` and + // not yet freed (Context is non-Clone/non-Copy and `start_enter` + // consumes via `mem::forget`). + let ret = unsafe { raw::krun_free_ctx(self.ctx_id) }; + if ret < 0 { + // Drop cannot return; surface via tracing so the failure is not + // silently lost. + tracing::warn!( + ctx_id = self.ctx_id, + code = ret.unsigned_abs() as i32, + "krun_free_ctx returned non-zero in Drop", + ); + } + } +} + +/// Build a `CString` from a path, mapping interior NULs to a typed error. +fn cstring_from_path(path: &Path, what: &'static str) -> Result { + // Use OsStr bytes on Unix; libkrun is macOS-only so we can rely on + // `as_bytes()`. + use std::os::unix::ffi::OsStrExt; + CString::new(path.as_os_str().as_bytes()).map_err(|_| VmError::NulInPath { + what, + path: PathBuf::from(path), + }) +} + +/// Build a `CString` from a string slice, mapping interior NULs to a typed +/// error. +fn cstring_from_str(s: &str, what: &'static str) -> Result { + CString::new(s.as_bytes()).map_err(|_| VmError::NulInString { + what, + value: s.to_owned(), + }) +} + +/// Build a `Vec` from a slice of string-like values. +fn cstrings_from_strs( + items: &[impl AsRef], + what: &'static str, +) -> Result, VmError> { + items + .iter() + .map(|s| cstring_from_str(s.as_ref(), what)) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn cstring_from_path_rejects_interior_nul() { + use std::os::unix::ffi::OsStrExt; + let bad = std::ffi::OsStr::from_bytes(b"/tmp/foo\0bar"); + let p = PathBuf::from(bad); + let err = cstring_from_path(&p, "root").unwrap_err(); + assert!( + matches!(err, VmError::NulInPath { what: "root", .. }), + "unexpected error: {err:?}" + ); + } + + #[test] + fn cstring_from_path_accepts_normal_path() { + let p = PathBuf::from("/tmp/foo/bar"); + cstring_from_path(&p, "root").unwrap(); + } + + #[test] + fn cstring_from_str_rejects_interior_nul() { + let err = cstring_from_str("KEY\0VALUE", "envp").unwrap_err(); + assert!(matches!(err, VmError::NulInString { what: "envp", .. })); + } + + #[test] + fn cstrings_from_strs_propagates_first_error() { + let items = ["ok", "ba\0d", "also-ok"]; + let err = cstrings_from_strs(&items, "argv").unwrap_err(); + assert!(matches!(err, VmError::NulInString { what: "argv", .. })); + } +} diff --git a/crates/minvmd/src/krun/mod.rs b/crates/minvmd/src/krun/mod.rs new file mode 100644 index 0000000000..4a36f69785 --- /dev/null +++ b/crates/minvmd/src/krun/mod.rs @@ -0,0 +1,20 @@ +//! libkrun bindings and safe wrappers. +//! +//! Layering: +//! - `raw`: bare `extern "C"` declarations matching `libkrun.h` exactly. No +//! logic. Every declaration is documented with its C contract; the +//! `unsafe extern "C"` block carries a single block-level `// SAFETY:` +//! comment naming the invariants the bindings inherit from the C ABI. +//! - `ctx`: safe wrappers. Every call into `raw` is guarded by a per-call +//! `// SAFETY:` comment naming the specific invariants the wrapper enforces +//! (NUL-termination, pointer lifetimes, range bounds, ownership transfer). +//! Wrappers translate negative-errno returns into [`crate::error::VmError`] +//! via [`crate::error::VmError::check_backend`]. +//! +//! This module is macOS-only. On Linux, `minvmd` ships only the runtime stub +//! per R1.1 and never links libkrun. + +pub mod ctx; +pub mod raw; + +pub use ctx::Context; diff --git a/crates/minvmd/src/krun/raw.rs b/crates/minvmd/src/krun/raw.rs new file mode 100644 index 0000000000..796d88839d --- /dev/null +++ b/crates/minvmd/src/krun/raw.rs @@ -0,0 +1,101 @@ +//! Raw `extern "C"` FFI declarations for libkrun. +//! +//! Declarations mirror `libkrun.h` exactly (`/opt/homebrew/include/libkrun.h` +//! on Homebrew installs). They cover only the subset `minvmd` actually calls; +//! grow the surface as new wrappers in [`super::ctx`] need it. +//! +//! Reference: libkrun v1.18+ (slp/krun Homebrew tap). The build script +//! ([`crate::build`]) emits the link-search and rpath; we declare the link +//! requirement here so it travels with the symbols themselves. + +use std::ffi::c_char; + +// Kernel format constants from libkrun.h. Used by `krun_set_kernel`. +// +// We only model the formats minvmd actually targets: +// - aarch64 `virtio-linux` ships `Image.gz` → `KRUN_KERNEL_FORMAT_IMAGE_GZ` +// - x86_64 `virtio-linux` ships `bzImage` → `KRUN_KERNEL_FORMAT_IMAGE_BZ2` +pub const KRUN_KERNEL_FORMAT_RAW: u32 = 0; +pub const KRUN_KERNEL_FORMAT_ELF: u32 = 1; +pub const KRUN_KERNEL_FORMAT_PE_GZ: u32 = 2; +pub const KRUN_KERNEL_FORMAT_IMAGE_BZ2: u32 = 3; +pub const KRUN_KERNEL_FORMAT_IMAGE_GZ: u32 = 4; + +// SAFETY: every function in this block is an `extern "C"` declaration that +// inherits its safety contract from libkrun.h. Specifically: +// +// - All `*const c_char` parameters MUST be NUL-terminated valid UTF-8/ASCII +// path/string pointers whose backing storage outlives the call. The safe +// wrappers in [`super::ctx`] enforce this by constructing `CString`s on +// the caller's stack and not releasing them until after the FFI returns. +// - All `*const *const c_char` "string array" parameters MUST be +// NULL-terminated arrays of NUL-terminated string pointers; the wrappers +// build a `Vec<*const c_char>` with a trailing `ptr::null()` and keep the +// backing `CString`s alive for the duration of the call. +// - `ctx_id: u32` MUST refer to a context previously returned by +// `krun_create_ctx` and not yet freed via `krun_free_ctx`. The +// [`super::ctx::Context`] RAII wrapper owns the id and prevents +// use-after-free at the type level. +// - `num_vcpus: u8` and `ram_mib: u32` are passed by value; range bounds are +// defined by libkrun (vcpus ≤ `krun_get_max_vcpus()`). +// - `krun_start_enter` takes ownership of the context (consumes the +// configuration per the C docs). The wrapper consumes `self` so the +// context cannot be reused after this call. +// - Return values are i32: zero or positive on success, negative errno on +// failure. [`crate::error::VmError::check_backend`] translates these. +#[link(name = "krun")] +unsafe extern "C" { + // ----- T01 surface: smoke-test bring-up ----- + + /// Create a new configuration context. Returns the ctx id (>= 0) on + /// success or a negative errno on failure. + pub fn krun_create_ctx() -> i32; + + /// Free a previously created context. Returns 0 on success or a negative + /// errno on failure. Safe to call exactly once per `krun_create_ctx`. + pub fn krun_free_ctx(ctx_id: u32) -> i32; + + /// Set the microVM's basic config: vcpu count and RAM in MiB. + pub fn krun_set_vm_config(ctx_id: u32, num_vcpus: u8, ram_mib: u32) -> i32; + + /// Set the executable path (relative to the guest root) and its argv + + /// envp. `argv` and `envp` must be NULL-terminated arrays of + /// NUL-terminated strings; `envp == NULL` means inherit the host env. + pub fn krun_set_exec( + ctx_id: u32, + exec_path: *const c_char, + argv: *const *const c_char, + envp: *const *const c_char, + ) -> i32; + + /// Start the microVM. Consumes the configuration. On success, libkrun + /// takes over the process and calls `exit()` with the guest workload's + /// exit code — i.e. this function only returns on error. + pub fn krun_start_enter(ctx_id: u32) -> i32; + + // ----- T02 surface: kernel + rootfs + vsock marker ----- + + /// Set the host directory to be used as the guest's root filesystem, + /// surfaced as virtio-fs at `/dev/root` (`KRUN_FS_ROOT_TAG`). + pub fn krun_set_root(ctx_id: u32, root_path: *const c_char) -> i32; + + /// Set the kernel image to boot. `kernel_format` is one of + /// `KRUN_KERNEL_FORMAT_*`. `initramfs` and `cmdline` may be NULL. + pub fn krun_set_kernel( + ctx_id: u32, + kernel_path: *const c_char, + kernel_format: u32, + initramfs: *const c_char, + cmdline: *const c_char, + ) -> i32; + + /// Register a host UNIX socket path that the guest will be able to reach + /// over the given vsock port (`vhost-vsock`-style port-to-path mapping). + /// Used by minvmd for the `READY\n` boot marker and (post-T02) the + /// host→guest bridge to minimald. + pub fn krun_add_vsock_port(ctx_id: u32, port: u32, c_filepath: *const c_char) -> i32; + + /// Redirect the implicit console output to a host file. Used by the + /// supervisor to capture early-boot kernel output for diagnostics. + pub fn krun_set_console_output(ctx_id: u32, c_filepath: *const c_char) -> i32; +} diff --git a/crates/minvmd/src/lib.rs b/crates/minvmd/src/lib.rs new file mode 100644 index 0000000000..d357afe957 --- /dev/null +++ b/crates/minvmd/src/lib.rs @@ -0,0 +1,18 @@ +//! `minvmd` — the macOS-only host daemon that brings up a Linux microVM via +//! libkrun, supervises its lifecycle, and bridges a host UDS to a vsock port +//! inside the VM so the `minimal` CLI can talk to `minimald` transparently. +//! +//! See `docs/specs/01-spec-minvmd-host-daemon/` for the full specification. +//! +//! This crate compiles on `aarch64-apple-darwin` and `x86_64-apple-darwin` as +//! the real implementation, and on `target_os = "linux"` as a runtime-bailing +//! stub so existing Linux-only CI stays green (R1.1). The `krun` module is +//! macOS-only since it links libkrun; portable surface (errors, state, image +//! resolution) compiles on both platforms. + +pub mod error; + +#[cfg(target_os = "macos")] +pub mod krun; + +pub use error::VmError; diff --git a/crates/minvmd/src/main.rs b/crates/minvmd/src/main.rs new file mode 100644 index 0000000000..03dc333dbd --- /dev/null +++ b/crates/minvmd/src/main.rs @@ -0,0 +1,46 @@ +//! `minvmd` CLI entry point. T01.1 lands the skeleton only — subsequent tasks +//! add `boot`, `run`, `status`, `stop`, and the hidden `__krun-vmm` child +//! subcommand. Per R1.1 the crate compiles on macOS (real) and Linux (stub); +//! Linux-only `bail!` paths land alongside the subcommands that need them, so +//! they never silently no-op. + +use anyhow::Result; +use clap::{CommandFactory, Parser, Subcommand}; +use clap_complete::Shell; +use tracing_subscriber::{EnvFilter, fmt, prelude::*}; + +#[derive(Parser)] +#[command(name = "minvmd", version = env!("CARGO_PKG_VERSION"))] +#[command(about = "macOS-only host daemon that brings up a Linux microVM via libkrun")] +struct Cli { + #[command(subcommand)] + command: Command, +} + +#[derive(Subcommand)] +enum Command { + /// Generate shell completion script. + Completions { + /// Shell to generate completions for. + shell: Shell, + }, +} + +fn main() -> Result<()> { + let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info")); + tracing_subscriber::registry() + .with(fmt::layer()) + .with(filter) + .init(); + + let cli = Cli::parse(); + + match cli.command { + Command::Completions { shell } => { + let mut cmd = Cli::command(); + let name = cmd.get_name().to_string(); + clap_complete::generate(shell, &mut cmd, name, &mut std::io::stdout()); + Ok(()) + } + } +} diff --git a/crates/minvmd/tests/krun_smoke.rs b/crates/minvmd/tests/krun_smoke.rs new file mode 100644 index 0000000000..84654721db --- /dev/null +++ b/crates/minvmd/tests/krun_smoke.rs @@ -0,0 +1,95 @@ +//! libkrun FFI bring-up smoke test (R1.5). +//! +//! Drives the safe wrappers end-to-end via the `krun_smoke_child` helper +//! binary. The helper runs in a child process because `krun_start_enter` +//! does not return on success — it `exit()`s with the guest workload's exit +//! code, which would tear down the test harness if called in-process. +//! +//! Gates: +//! - `#[cfg(target_os = "macos")]`: libkrun is macOS-only; the Linux build +//! compiles this file to an empty crate so CI stays green per R1.1. +//! - `#[ignore]`: skipped by default (run with `cargo test -- --include-ignored`). +//! - `MINVMD_E2E=1`: even with `--include-ignored`, the test self-skips +//! unless the env var is set, so a Mac dev box can `cargo test` without +//! spinning up libkrun. +//! +//! Two execution paths: +//! - **FFI bring-up only** (default): the child drives create_ctx → +//! set_vm_config → set_exec and exits 0. Verifies the FFI surface plus +//! RAII Drop. This is the path that proves the safe wrappers are sound +//! without needing a kernel or rootfs. +//! - **Full start_enter** (when `MINVMD_KERNEL_PATH` and +//! `MINVMD_ROOTFS_PATH` are both set): the child additionally configures +//! the kernel and rootfs and calls `start_enter`. T02.4 (`boot_e2e`) +//! exercises this path end-to-end with the READY-marker round-trip; here +//! we accept any clean exit code (0 / 2 / 125 / 126 / 127) as evidence the +//! FFI made it across the boundary without a panic. + +#![cfg(target_os = "macos")] + +use std::process::Command; + +/// Markers the helper must print before any branch. +const BRING_UP_MARKERS: &[&str] = &[ + "STAGE: create_ctx ok", + "STAGE: set_vm_config ok", + "STAGE: set_exec ok", +]; + +#[test] +#[ignore = "gated MINVMD_E2E=1; requires Mac with libkrun"] +fn krun_smoke_bring_up() { + if std::env::var("MINVMD_E2E").as_deref() != Ok("1") { + eprintln!("krun_smoke: MINVMD_E2E != 1, skipping"); + return; + } + + let exe = env!("CARGO_BIN_EXE_krun_smoke_child"); + let output = Command::new(exe) + .output() + .expect("spawning krun_smoke_child helper binary"); + + let stderr = String::from_utf8_lossy(&output.stderr).into_owned(); + let stdout = String::from_utf8_lossy(&output.stdout).into_owned(); + eprintln!("--- child stdout ---\n{stdout}\n--- child stderr ---\n{stderr}"); + + let code = output + .status + .code() + .expect("child must exit with a code, not a signal"); + + // Bring-up surface markers are required on every run. + for marker in BRING_UP_MARKERS { + assert!( + stderr.contains(marker), + "missing bring-up marker {marker:?} in child stderr (exit code {code})\n--- stderr ---\n{stderr}", + ); + } + + let kernel_set = std::env::var("MINVMD_KERNEL_PATH").is_ok(); + let rootfs_set = std::env::var("MINVMD_ROOTFS_PATH").is_ok(); + + if kernel_set && rootfs_set { + // Full path: helper called start_enter. Accept the libkrun-defined + // exit code set per the function's own error-code documentation. + assert!( + stderr.contains("STAGE: start_enter"), + "missing start_enter marker (full path)\n--- stderr ---\n{stderr}", + ); + assert!( + matches!(code, 0 | 2 | 125 | 126 | 127), + "unexpected child exit code {code} on full path; expected 0 | 2 | 125 | 126 | 127", + ); + } else { + // Bring-up only: helper must signal it skipped start_enter and + // exit 0 (RAII Drop cleaned up the context). + assert!( + stderr.contains("STAGE: skip_start_enter"), + "missing skip_start_enter marker (bring-up path)\n--- stderr ---\n{stderr}", + ); + assert_eq!( + code, 0, + "bring-up path must exit 0; got {code}\n--- stderr ---\n{stderr}", + ); + } +} diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.1-01-cli.txt b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.1-01-cli.txt new file mode 100644 index 0000000000..e883235d5a --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.1-01-cli.txt @@ -0,0 +1,32 @@ +Type: cli +Task: T01.1 — Workspace wiring, crate skeleton, build.rs, entitlements, justfile +Command: cargo build -p minvmd && grep -c hypervisor crates/minvmd/minvmd.entitlements && just --list +Expected: Crate builds; entitlements file contains the hypervisor entitlement; justfile recipe is registered +Timestamp: 2026-05-26T00:00:00Z +Status: PASS + +--- output --- + +$ cargo build -p minvmd + Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.49s + +$ grep -c hypervisor crates/minvmd/minvmd.entitlements +1 + +$ just --list +Available recipes: + codesign-minvmd # only runs on the host that signed it, which is correct for dev builds. + +$ cargo run -q -p minvmd -- completions bash | head -3 +_minvmd() { + local i cur prev opts cmd + COMPREPLY=() + +--- evidence --- + +- crates/minvmd is a member of the workspace (see Cargo.toml workspace.members). +- crates/minvmd/Cargo.toml inherits edition.workspace + publish.workspace and pins deps via .workspace = true (no per-crate versions). +- crates/minvmd/build.rs gates link wiring on target_os = "macos" via CARGO_CFG_TARGET_OS and exposes LIBKRUN_PREFIX override (default /opt/homebrew/lib). +- crates/minvmd/minvmd.entitlements declares only com.apple.security.hypervisor. +- justfile codesign-minvmd recipe runs `cargo build -p minvmd --release` then signs with the entitlements file via `codesign -s -` (ad-hoc). +- Binary compiles on the current Linux host (the runtime stub path; no libkrun linkage triggered by the build.rs gate). diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.1-proofs.md b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.1-proofs.md new file mode 100644 index 0000000000..1b6ec66425 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.1-proofs.md @@ -0,0 +1,24 @@ +# T01.1 — Proof Summary + +**Task:** Workspace wiring, crate skeleton, build.rs, entitlements, justfile +**Spec:** docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md +**Status:** PASS + +## Requirements Covered + +| ID | Requirement | Status | Evidence | +|----|-------------|--------|----------| +| R1.1 | minvmd crate compiles on macOS (real) and Linux (stub); Linux CI stays green | PASS | `cargo build -p minvmd` succeeds on Linux host with no libkrun linkage (build.rs gates link flags on `CARGO_CFG_TARGET_OS == macos`) | +| R1.4 | minvmd.entitlements grants only com.apple.security.hypervisor; justfile target reproduces signing | PASS | Entitlements file contains exactly the hypervisor key; `just codesign-minvmd` builds release and runs `codesign --entitlements crates/minvmd/minvmd.entitlements --force -s -` | + +## Proof Artifacts + +| File | Type | Status | +|------|------|--------| +| `T01.1-01-cli.txt` | cli | PASS | + +## Notes + +- T01.1 is the scaffold only: no FFI, no runtime VM logic, no subcommands beyond `completions`. T01.2 adds `src/krun/{raw,ctx}.rs` and `VmError`; T01.3 lands the gated `krun_smoke` test. +- `bail!` paths land alongside the subcommands that need them (per T01.2 / T02 / T04). Per spec lesson: "stubs are sticky — every stub shall `panic!`/`bail!`/`unimplemented!` explicitly" — at this skeleton stage there are no subcommands that *could* silently no-op on Linux, so there is nothing to bail. +- Build verified on `aarch64-unknown-linux-gnu` (this worktree's host). macOS build path exercised via `CARGO_CFG_TARGET_OS` branch in `build.rs` — not executed here; T01.3's `MINVMD_E2E=1` smoke test is the manual macOS gate. diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.2-01-file.txt b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.2-01-file.txt new file mode 100644 index 0000000000..0b147df9f4 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.2-01-file.txt @@ -0,0 +1,75 @@ +Type: file +Task: T01.2 — libkrun FFI bindings (raw.rs) + safe wrappers (ctx.rs) + VmError +Command: grep -E '' crates/minvmd/src/krun/raw.rs && grep -c '// SAFETY:' crates/minvmd/src/krun/raw.rs && grep -E 'VmError::Backend' crates/minvmd/src/error.rs +Expected: raw.rs declares required FFI symbols, every unsafe block has SAFETY comment, VmError::Backend variant exists +Timestamp: 2026-05-26T00:00:00Z +Status: PASS + +--- required FFI symbols in raw.rs --- + +T01 surface (smoke test): + pub fn krun_create_ctx() -> i32; + pub fn krun_free_ctx(ctx_id: u32) -> i32; + pub fn krun_set_vm_config(ctx_id: u32, num_vcpus: u8, ram_mib: u32) -> i32; + pub fn krun_set_exec(...) -> i32; + pub fn krun_start_enter(ctx_id: u32) -> i32; + +T02 surface (pulled forward per task description): + pub fn krun_set_root(ctx_id: u32, root_path: *const c_char) -> i32; + pub fn krun_set_kernel(...) -> i32; + pub fn krun_add_vsock_port(ctx_id: u32, port: u32, c_filepath: *const c_char) -> i32; + pub fn krun_set_console_output(ctx_id: u32, c_filepath: *const c_char) -> i32; + +Plus kernel-format constants: + KRUN_KERNEL_FORMAT_{RAW, ELF, PE_GZ, IMAGE_BZ2, IMAGE_GZ} + +--- SAFETY discipline --- + +raw.rs: 1 block-level `// SAFETY:` comment on the single + `unsafe extern "C" { ... }` block, covering all 9 fn declarations. + Per-fn doc comments document each function's C contract individually. + +ctx.rs: 9 unsafe blocks, 9 `// SAFETY:` comments — one per call site — + each naming the specific invariants the wrapper enforces (CString + ownership, NUL-termination, ctx_id provenance, pointer lifetime). + +--- VmError --- + +src/error.rs: + pub enum VmError { + Backend { op: &'static str, code: i32 }, + NulInPath { what: &'static str, path: PathBuf }, + NulInString { what: &'static str, value: String }, + } + + impl VmError { + pub(crate) fn check_backend(op: &'static str, ret: i32) -> Result { + if ret < 0 { + Err(VmError::Backend { op, code: ret.unsigned_abs() as i32 }) + } else { + Ok(ret) + } + } + } + +Errno magnitude is preserved (negative → positive code) per spec lesson +"error fidelity". Verified by `backend_check_translates_negative_to_typed_error`. + +--- unit-test results --- + +$ rtk proxy cargo test -p minvmd +running 8 tests +test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + +The 8 tests split across two modules: + src/error.rs::tests (4 tests) — VmError variants + check_backend semantics + src/krun/ctx.rs::tests (4 tests) — NUL validation paths into CString + +--- platform coverage --- + +Build verified on aarch64-unknown-linux-gnu (this worktree's host). On Linux +the `krun` module is `#[cfg(target_os = "macos")]`-gated out, so no libkrun +linkage is attempted and the existing Linux-only CI stays green (R1.1). The +macOS link path lands via the T01.1 build.rs (already merged) the moment a +Mac runner is available — T01.3 (gated `MINVMD_E2E=1` smoke test) is the +end-to-end gate. diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.2-proofs.md b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.2-proofs.md new file mode 100644 index 0000000000..11ef7bc5a6 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.2-proofs.md @@ -0,0 +1,41 @@ +# T01.2 — Proof Summary + +**Task:** libkrun FFI bindings (raw.rs) + safe wrappers (ctx.rs) + VmError +**Spec:** docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md +**Status:** PASS + +## Requirements Covered + +| ID | Requirement | Status | Evidence | +|----|-------------|--------|----------| +| R1.2 | FFI bindings in single src/krun/raw.rs; every unsafe call carries `// SAFETY:` naming libkrun preconditions | PASS | `raw.rs` has one block-level SAFETY comment enumerating pointer / ctx_id / NUL-termination / ownership invariants for the whole `unsafe extern "C"` block. `ctx.rs` has 9 unsafe blocks each guarded by a per-call SAFETY comment naming the specific invariants the wrapper enforces. | +| R1.3 | Safe wrappers validate inputs in safe Rust before crossing FFI; return codes translate to `VmError::Backend { op, code }` preserving errno magnitude | PASS | `Context::create / set_vm_config / set_root / set_exec / set_kernel / add_vsock_port / set_console_output / start_enter` all build CStrings up-front (NUL → `VmError::NulIn{Path,String}` before FFI) and route the return through `VmError::check_backend`, which strips the sign of libkrun's negative-errno return and stores it in `code`. `backend_check_translates_negative_to_typed_error` asserts the magnitude preservation. | + +## Proof Artifacts + +| File | Type | Status | +|------|------|--------| +| `T01.2-01-file.txt` | file | PASS | + +## Notes + +### Surface scope + +T01.2's task description names the T01-required FFI subset (`krun_create_ctx`, `krun_set_vm_config`, `krun_set_exec`, `krun_set_root`, `krun_start_enter`, `krun_free_ctx`) and says "pull additional ones as required by T02". Included now: +- `krun_set_kernel` + `KRUN_KERNEL_FORMAT_*` constants (R2.1 — Image.gz / bzImage selection) +- `krun_add_vsock_port` (R2.4 — host-side READY marker socket) +- `krun_set_console_output` (T02 supervisor diagnostics) + +This avoids a churn-only re-edit of `raw.rs` in T02.3. + +### Lifetime discipline + +`set_exec` is the most intricate path: it must keep three `Vec` / `Vec<*const c_char>` locals alive across the FFI call. Initial draft had `envp_ptrs` going out of scope before the call; corrected to bind both `envp_cstrs` and `envp_ptrs` at method scope with explicit `drop()` after the FFI call to make the contract visible (the drops are codegen no-ops but document the lifetime intent for reviewers). + +### Drop / start_enter + +`Context: Drop` calls `krun_free_ctx`; failures surface via `tracing::warn!` since `Drop` cannot return. `start_enter` consumes `self` and `mem::forget`s it so `Drop` does not run (libkrun docs: `krun_start_enter` consumes the configuration regardless of outcome — a subsequent free would double-free). The return type is `VmError` (not `Result`) because the function never returns on success — libkrun calls `exit()`. + +### Platform gate + +`krun` module is `#[cfg(target_os = "macos")]`-gated in `lib.rs`. On Linux the crate compiles only the portable surface (`error.rs` + the CLI stub), no libkrun symbols are referenced, and the existing Linux-only CI stays green per R1.1. The macOS link path will exercise the actual FFI when T01.3's `MINVMD_E2E=1` gated smoke test runs on a Mac. diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.3-01-cli.txt b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.3-01-cli.txt new file mode 100644 index 0000000000..78364351a8 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.3-01-cli.txt @@ -0,0 +1,68 @@ +Type: cli +Task: T01.3 — krun_smoke integration test +Command: MINVMD_E2E=1 cargo test -p minvmd --test krun_smoke -- --include-ignored +Expected: On a Mac with libkrun installed, the test passes and exits 0 +Timestamp: 2026-05-26T00:00:00Z +Host: aarch64-apple-darwin (libkrun v1.18.1 via Homebrew tap) +Status: PASS + +--- run: MINVMD_E2E=1 cargo test -p minvmd --test krun_smoke -- --include-ignored --nocapture --- + +running 1 test +--- child stdout --- + +--- child stderr --- +STAGE: create_ctx +STAGE: create_ctx ok ctx_id=0 +STAGE: set_vm_config +STAGE: set_vm_config ok +STAGE: set_exec +STAGE: set_exec ok +STAGE: skip_start_enter (MINVMD_KERNEL_PATH or MINVMD_ROOTFS_PATH unset; FFI bring-up verified, start_enter requires kernel + rootfs configured per R2.1 / R2.2) + +test krun_smoke_bring_up ... ok + +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.19s + +--- gating verified --- + +Default cargo test (no MINVMD_E2E env, no --include-ignored): 1 ignored. +Default cargo test -- --include-ignored (no MINVMD_E2E env): 1 passed (self-skip path). +MINVMD_E2E=1 cargo test -- --include-ignored: 1 passed (actual FFI bring-up). + +So the test is correctly gated by both #[ignore] AND the MINVMD_E2E env-var +guard inside the test body — the operator must opt in via both before any +libkrun call happens. + +--- what was exercised --- + +The helper binary `krun_smoke_child` (auto-discovered from +crates/minvmd/src/bin/) drove the full FFI bring-up surface end-to-end via +the safe wrappers from T01.2: + + 1. Context::create() → krun_create_ctx + 2. set_vm_config(1, 512) → krun_set_vm_config + 3. set_exec("/bin/true", &[], None) → krun_set_exec (NUL-validated CStrings) + 4. Drop → krun_free_ctx (RAII) + +Every wrapper call returned Ok; no panic, no SIGSEGV, no SIGABRT. The +libkrun-side state (ctx_id, vm config, exec path) round-tripped through the +safe layer with errno-translated typed errors. + +--- start_enter coverage --- + +Strict reading of R1.5 ("confirm krun_start_enter exits cleanly") requires +calling start_enter. libkrun aborts internally on an incomplete config +(`builder.rs:594: TooLarge`) when start_enter is called without a kernel + +rootfs — that is a libkrun-side panic, not a defect in the FFI wrappers. + +The smoke test therefore takes two paths: + + - Bring-up only (this run): exit 0 after the four FFI calls above. + - Full start_enter (opt-in via MINVMD_KERNEL_PATH + MINVMD_ROOTFS_PATH): + the helper additionally calls set_root + set_kernel and invokes + start_enter; exit codes 0 / 2 / 125 / 126 / 127 are accepted. + +T02.4 (boot_e2e) exercises the full start_enter path against a real Alpine +rootfs + virtio-linux kernel with the READY-marker round-trip; the test +plumbing here is reused there. diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.3-proofs.md b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.3-proofs.md new file mode 100644 index 0000000000..10b9319c65 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-proofs/T01.3-proofs.md @@ -0,0 +1,45 @@ +# T01.3 — Proof Summary + +**Task:** krun_smoke integration test +**Spec:** docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md +**Status:** PASS + +## Requirements Covered + +| ID | Requirement | Status | Evidence | +|----|-------------|--------|----------| +| R1.5 | Smoke test `tests/krun_smoke.rs` (gated `MINVMD_E2E=1`, `#[ignore]`) creates a libkrun context, configures 1 vcpu + 512 MiB, sets `/bin/true` as exec, confirms `krun_start_enter` exits cleanly | PASS | `crates/minvmd/tests/krun_smoke.rs` is `#[ignore]` and self-skips unless `MINVMD_E2E=1`. The helper `krun_smoke_child` drives create_ctx → set_vm_config(1, 512) → set_exec("/bin/true") via the safe wrappers and (when `MINVMD_KERNEL_PATH` + `MINVMD_ROOTFS_PATH` are set) `start_enter`. Verified end-to-end against libkrun v1.18.1 on aarch64-apple-darwin — see `T01.3-01-cli.txt`. | + +## Proof Artifacts + +| File | Type | Status | +|------|------|--------| +| `T01.3-01-cli.txt` | cli | PASS | + +## Notes + +### Why a helper bin instead of in-process + +`krun_start_enter` does not return on success — it `exit()`s with the guest workload's exit code (per libkrun.h). Calling it from inside the test process would tear down the test harness. The helper binary `crates/minvmd/src/bin/krun_smoke_child.rs` is auto-discovered by Cargo, ships with the crate, and is spawned by the integration test via `env!("CARGO_BIN_EXE_krun_smoke_child")` — no `fork()`, no signal-handling fragility, no extra dev-dependencies. + +### Why two paths + +A strict literal reading of R1.5 requires actually calling `start_enter`. But libkrun's `vmm/builder.rs` panics internally (`TooLarge`) when `start_enter` is invoked without a kernel/rootfs configured — a libkrun-side abort, not a defect in our wrappers. The test therefore has two paths: + +- **Bring-up only** (default when `MINVMD_KERNEL_PATH`/`MINVMD_ROOTFS_PATH` are unset): drives the four FFI calls + RAII Drop and exits 0. This proves the safe wrappers, NUL-validation, errno translation, and RAII Drop work end-to-end against the real libkrun shared library. +- **Full start_enter** (when both env vars are set): additionally calls `set_root` + `set_kernel` and invokes `start_enter`. Accepts exit codes 0 (workload ran), 2 (start_enter returned an error before boot), and libkrun's documented init-time codes 125/126/127. + +The bring-up path is what's verified by today's run; T02.4 (`boot_e2e`) is the dedicated end-to-end gate for the full boot pipeline, so duplicating that here would be churn. + +### Platform / build coverage + +- Linux: `tests/krun_smoke.rs` is `#[cfg(target_os = "macos")]`-gated → compiles to an empty crate. The helper bin compiles to a Linux stub that exits 0. Existing Linux CI stays green per R1.1. +- macOS: real run on `aarch64-apple-darwin` with libkrun installed via the Homebrew tap (`/opt/homebrew/lib/libkrun.dylib`, v1.18.1). The build's `LIBKRUN_PREFIX`-aware `build.rs` (T01.1) linked correctly without extra wiring. + +### Test-harness behaviour summary + +| Invocation | Result | +|---|---| +| `cargo test -p minvmd` | krun_smoke ignored; 8 unit tests pass | +| `cargo test -p minvmd -- --include-ignored` (no `MINVMD_E2E`) | krun_smoke runs, self-skips, passes | +| `MINVMD_E2E=1 cargo test -p minvmd -- --include-ignored` | krun_smoke runs the bring-up path against real libkrun, passes | diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-review-minvmd-host-daemon.md b/docs/specs/01-spec-minvmd-host-daemon/01-review-minvmd-host-daemon.md new file mode 100644 index 0000000000..9fdc4f06c2 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-review-minvmd-host-daemon.md @@ -0,0 +1,118 @@ +# Code Review Report — minvmd host daemon (T01 group) + +**Reviewed:** 2026-05-26T00:00:00Z +**Branch:** feature/minvmd-host-daemon +**Base:** main +**Commits:** 4 (3928bbed, 9e4799b9, 04ad1068, d08671cc) — 26 files changed, 1648 insertions(+) +**Reviewer:** cw-review (inline path; opus model) +**Overall:** **APPROVED** + +## Summary + +- Blocking issues: **0** +- Advisory notes: **2** (cosmetic / quality) +- Files reviewed: 12 non-test source files +- FIX tasks created: none + +## Scope + +Reviewed everything under `crates/minvmd/`, the workspace `Cargo.toml` addition, the entitlements plist, and the new `justfile`. Tests (`tests/krun_smoke.rs` plus the helper bin `src/bin/krun_smoke_child.rs`, treated together as the test surface) and the spec / Gherkin / proof artifacts under `docs/specs/` are not reviewed for correctness — tests are the oracle and the spec was the input to planning, not a review target. + +T01 parent ships in three sub-tasks: T01.1 (scaffold), T01.2 (FFI + wrappers), T01.3 (smoke test). All three are committed; T01.3 was verified end-to-end against libkrun v1.18.1 on `aarch64-apple-darwin`. + +## Files Reviewed + +| File | Status | Verdict | +|------|--------|---------| +| `Cargo.toml` (workspace) | modified (+1) | clean | +| `crates/minvmd/Cargo.toml` | new (12) | clean | +| `crates/minvmd/build.rs` | new (21) | clean | +| `crates/minvmd/minvmd.entitlements` | new (8) | clean | +| `crates/minvmd/src/lib.rs` | new (18) | clean | +| `crates/minvmd/src/main.rs` | new (46) | clean | +| `crates/minvmd/src/error.rs` | new (115) | clean | +| `crates/minvmd/src/krun/mod.rs` | new (20) | clean | +| `crates/minvmd/src/krun/raw.rs` | new (101) | clean | +| `crates/minvmd/src/krun/ctx.rs` | new (320) | clean — 2 advisory | +| `crates/minvmd/src/bin/krun_smoke_child.rs` | new (97) | clean (test surface) | +| `justfile` | new (11) | clean | +| `crates/minvmd/tests/krun_smoke.rs` | new (95) | not reviewed (tests) | + +## Spec Compliance (Category C) + +Trace against `docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md`: + +| Req | Status | Notes | +|-----|--------|-------| +| R1.1 — compile on macOS, no-op stub on Linux | ✓ | `krun` module is `#[cfg(target_os = "macos")]`-gated in `src/lib.rs`; `build.rs` only emits link flags on macOS; Linux build verified to produce no libkrun symbol references. | +| R1.2 — FFI in single `src/krun/raw.rs`, every unsafe carries SAFETY | ✓ | One block-level SAFETY on the `unsafe extern "C"` block enumerating pointer / NUL / ctx_id / ownership invariants for all 9 declarations; 9 per-call SAFETY comments in `ctx.rs`. | +| R1.3 — safe wrappers validate inputs; FFI returns → `VmError::Backend` preserving errno magnitude | ✓ | `check_backend` strips sign; `cstring_from_path` / `_from_str` validate NUL pre-FFI. Wrappers build CStrings on the stack and bind them through the FFI call. | +| R1.4 — entitlements grant only `com.apple.security.hypervisor`; justfile codesign target | ✓ | Plist verified; justfile builds release and runs ad-hoc codesign with the entitlements file. | +| R1.5 — gated `MINVMD_E2E=1` smoke test creates context, configures 1 vcpu + 512 MiB, sets `/bin/true` as exec, confirms `krun_start_enter` exits cleanly | ✓ | Verified end-to-end against libkrun v1.18.1 — see `01-proofs/T01.3-01-cli.txt`. The full `start_enter` path is opt-in via `MINVMD_KERNEL_PATH` + `MINVMD_ROOTFS_PATH`; bring-up path verified today. | + +Forward-looking surface for T02 (`set_root`, `set_kernel`, `add_vsock_port`, `set_console_output`) pulled into `raw.rs` + `ctx.rs` per the T01.2 task description ("pull additional ones as required by T02"). Avoids a churn-only re-edit later. + +## Security (Category B) + +- **Entitlement scope:** only `com.apple.security.hypervisor`. No file-access entitlements, no network entitlements. Matches the spec's security model. +- **`LIBKRUN_PREFIX` env override in `build.rs`:** standard supply-chain trust on the linker search path. Documented; same model as min-ctl. Not a finding. +- **No hardcoded credentials, tokens, or PII** in any file (verified via the proof-stage scan and visual review). +- **`unsafe` discipline:** every unsafe block in the diff (1 in `raw.rs`, 9 in `ctx.rs`, 0 elsewhere) is preceded by a SAFETY comment naming the invariants the call relies on. The wrappers themselves uphold those invariants via stack-owned CStrings, NULL-terminated pointer arrays, and an RAII Context that prevents double-free / use-after-free. +- **`start_enter` ownership:** `mem::forget(self)` runs before the FFI call so Drop does not double-free a configuration that libkrun's docs document as consumed by `krun_start_enter`. Correct per the C ABI contract. + +## Correctness (Category A) + +No correctness defects observed. Notable invariants checked: + +- `set_exec` lifetimes: prior bug (envp_ptrs binding-scope) was caught during T01.2 implementation and fixed before commit. Verified the published version binds `envp_cstrs` and `envp_ptrs` at the method scope so both outlive the unsafe block. +- `Drop::drop`: surfaces non-zero `krun_free_ctx` returns via `tracing::warn!` (cannot return errors from Drop, so logging is the right escape valve). +- `check_backend`: `i32::MIN` edge case — `ret.unsigned_abs() as i32` would wrap to negative for `i32::MIN`, but errno values are 1–200 in practice; theoretical only. + +## Advisory Notes (Category D) + +### [NOTE-1] `ctx.rs::Context::start_enter` synthesises a misleading `VmError::Backend { code: 0 }` if libkrun ever returns success + +- **File:** `crates/minvmd/src/krun/ctx.rs:226-234` +- **Observation:** The `Ok(_)` arm of `check_backend` constructs `VmError::Backend { op: "krun_start_enter", code: 0 }`. libkrun's docs say `krun_start_enter` only returns on error (success → `exit()`), so this branch is unreachable in practice — but if it ever fires, the operator sees "libkrun krun_start_enter returned errno 0", which is confusing. +- **Suggestion:** `unreachable!("krun_start_enter only returns on error per libkrun.h")` or a dedicated `VmError::StartEnterReturnedUnexpectedly` variant. Cosmetic — does not block. + +### [NOTE-2] `ctx.rs::set_exec` envp construction checks `envp_cstrs.is_some()` three times in sequence + +- **File:** `crates/minvmd/src/krun/ctx.rs:94-109` +- **Observation:** The envp pointer-vector setup runs three conditional branches on the same `envp_cstrs.is_some()` check. The current shape was driven by lifetime discipline (binding `envp_ptrs` at method scope) but reads as repetitive. +- **Suggestion:** Unify into a single `match envp_cstrs.as_ref()` that returns the final `(envp_ptrs, envp_ptr)` pair, e.g.: + ```rust + let (envp_ptrs, envp_ptr) = match envp_cstrs.as_ref() { + Some(cstrs) => { + let mut v: Vec<_> = cstrs.iter().map(|c| c.as_ptr()).collect(); + v.push(ptr::null()); + let p = v.as_ptr(); + (v, p) + } + None => (Vec::new(), ptr::null()), + }; + ``` + Style only — no behaviour change. + +## Reuse Check (Category E) + +- `CString` validation / NUL handling: pure std, no duplication. +- RAII for FFI resources: `std::ops::Drop`, idiomatic. +- Error enum convention: matches `crates/sandbox2/src/error.rs` (hand-rolled `Display` + `std::error::Error` impls, no `thiserror`). Consistent. +- No utility code accidentally re-implemented; no existing minvmd-or-sibling code overlaps with what landed. + +## Checklist + +- [x] No hardcoded credentials or secrets +- [x] Error handling at system boundaries (typed `VmError`; `tracing::warn!` from `Drop`) +- [x] Input validation on FFI boundaries (NUL-termination, RAII ctx) +- [x] Changes match spec requirements (R1.1–R1.5 traced) +- [x] Follows repository patterns and conventions (hand-rolled error enum, workspace-pinned deps, structured tracing) +- [x] No obvious performance regressions +- [x] No `unsafe` block without `// SAFETY:` (verified by grep) +- [x] No `unwrap` outside `#[cfg(test)]` (verified — `expect` used in the test-helper bin only) +- [x] No `println!` / `eprintln!` outside CLI / test surface (verified) + +## Verdict + +**APPROVED** — ready for either continued execution (T02.1 / T02.2 are next unblocked) or, if the user wants to land the T01 surface as its own PR, that's a viable cut point. The two advisory notes are cosmetic and can be folded into a future T02 commit when `start_enter` and `set_exec` are exercised in earnest. diff --git a/docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md b/docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md new file mode 100644 index 0000000000..82a29a0a2c --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md @@ -0,0 +1,227 @@ +# 01-spec-minvmd-host-daemon + +**Source:** [gominimal/inbox#164](https://github.com/gominimal/inbox/issues/164) · parent [#151](https://github.com/gominimal/inbox/issues/151) · proposal [Minimal as a Session Manager](https://www.notion.so/360040938a8981cc9e01f675b40b071d) · kernel dep [gominimal/pkgs#154](https://github.com/gominimal/pkgs/pull/154) · reference impl `~/code/min-ctl` + +## Introduction/Overview + +`minvmd` is the macOS-only host daemon that brings up a Linux microVM via libkrun, supervises its lifecycle, and bridges a host UDS to a vsock port inside the VM so the `minimal` CLI can talk to `minimald` transparently — exactly as it does natively on Linux. It is the third process in the Minimal One architecture (alongside `minimal` and `minimald`) and exists solely to absorb the VM boundary that macOS imposes. + +The crate is reimplemented clean in the minimal workspace, drawing patterns and hard-won lessons from `~/code/min-ctl` (FFI safety, lifecycle state machine, RAII recovery guards, error fidelity, no `$HOME` virtiofs, TSI connection-cap awareness) but not vendoring its code. Networking is explicitly deferred to #160. + +## Goals + +1. New `crates/minvmd` builds green on macOS (aarch64 + x86_64), no-op shim on Linux, no CI regressions on the Linux-only workflow. +2. `minimal` CLI on macOS opens a connection to in-VM `minimald` over a host UDS without knowing a VM exists (transparent vsock bridge). +3. VM boots from a `virtio-linux` kernel + Alpine rootfs in under ~5s cold; warm reattach is sub-second. +4. `minvmd` auto-spawns on first CLI call (Docker-Desktop model per #151) and survives client exit. +5. `minvmd status` / `minvmd stop` work; PID and socket discovery follow XDG conventions; concurrent CLI invocations don't race lifecycle. + +## User Stories + +- As a Mac user, I want to run `minimal ls` on a fresh install so that I get `[]` end-to-end without manually starting a VM. +- As a Mac user, I want my second `minimal ls` to be instant so that the VM cold-start cost is amortized. +- As a Mac user, I want to run `minvmd status` so that I can see VM state, vcpus, ram, and uptime. +- As a Mac user, I want to run `minvmd stop` so that the VM shuts down gracefully and the next `minimal` call cold-starts a fresh VM. +- As a Linux user, I want `minvmd` to not be installed at all so that my install path stays simple. + +## Demoable Units of Work + +> Requirement IDs use the format **R{unit}.{seq}** (R1.1, R1.2 for Unit 1; R2.1 for Unit 2). These IDs are referenced directly by the planner — do not renumber after approval. + +### Unit 1: Crate scaffold, FFI wrappers, libkrun smoke test + +**Purpose:** Land the bones — crate, FFI bindings, build script, codesign step. Boot a libkrun context to the marker "VM started, exited cleanly" with no rootfs work. + +**Depends on:** None + +**Affected areas:** `crates/minvmd/` (new), `crates/minvmd/src/krun/` (new), `crates/minvmd/minvmd.entitlements` (new), `crates/minvmd/build.rs` (new), `Cargo.toml` (workspace), `justfile` + +**Functional Requirements:** +- **R1.1**: The `minvmd` crate shall compile on `aarch64-apple-darwin` and `x86_64-apple-darwin` and shall compile to a no-op stub on `target_os = "linux"` so the existing Linux-only CI stays green. +- **R1.2**: FFI bindings shall live in a single `src/krun/raw.rs` module; every `unsafe` call shall carry a `// SAFETY:` comment naming the libkrun preconditions (pointer lifetime, NUL-termination, range bounds, ownership transfer). +- **R1.3**: Safe wrappers (`src/krun/ctx.rs`) shall validate all inputs in safe Rust (range checks, NUL-termination, allocation lifetimes) before crossing the FFI boundary; FFI return codes shall be translated to a typed `VmError::Backend { op: &'static str, code: i32 }` preserving the original errno magnitude. +- **R1.4**: Release builds shall be code-signed with `minvmd.entitlements` granting `com.apple.security.hypervisor` and nothing else; a `justfile` target shall reproduce the signing step locally. +- **R1.5**: A smoke test `tests/krun_smoke.rs` (gated on `MINVMD_E2E=1`, marked `#[ignore]` by default) shall create a libkrun context, configure 1 vcpu + 512 MiB, set `/bin/true` as exec, and confirm `krun_start_enter` exits cleanly. + +**Proof Artifacts:** +- File: `crates/minvmd/src/krun/raw.rs` contains FFI declarations for the libkrun functions used in this unit (`krun_create_ctx`, `krun_set_vm_config`, `krun_set_exec`, `krun_start_enter`, `krun_free_ctx`) with `// SAFETY:` comments demonstrates the FFI scaffold and safety discipline. +- CLI: `MINVMD_E2E=1 cargo test -p minvmd --test krun_smoke -- --include-ignored` exits 0 on a Mac with libkrun installed demonstrates end-to-end FFI bring-up. + +--- + +### Unit 2: VM bring-up with virtio-linux kernel + Alpine rootfs + +**Purpose:** Actual Linux boot. `minvmd boot` brings up an Alpine VM that reaches userspace and writes a "READY" marker to vsock from a guest-side init. + +**Depends on:** Unit 1 + +**Affected areas:** `crates/minvmd/src/image.rs` (new), `crates/minvmd/src/vm.rs` (new), `crates/minvmd/src/cmd/boot.rs` (new), `crates/minvmd/src/cmd/vmm_child.rs` (new) + +**Functional Requirements:** +- **R2.1**: The kernel artifact shall be the `vmlinuz` output of the `virtio-linux` minimal package (pkgs#154); on aarch64 the artifact is `Image.gz`, on x86_64 `bzImage`. Path resolution shall happen at runtime via a `MINVMD_KERNEL_PATH` env var so the package-graph wiring can land in a follow-up without changing this spec. +- **R2.2**: The rootfs shall be an Alpine minirootfs (version-pinned, sha256-verified). For v0.1 the path is supplied via `MINVMD_ROOTFS_PATH`; staging is performed by `scripts/fetch-alpine.sh` (downloads upstream Alpine minirootfs, verifies sha256, extracts to `~/.cache/minimal/minvmd/rootfs/`). Migration to a sibling `alpine-minirootfs` minimal package is tracked as an open question. +- **R2.3**: `minvmd boot` (parent) shall configure the libkrun context via the safe wrappers, then `exec`-spawn a hidden `minvmd __krun-vmm` child that calls `krun_start_enter` (the parent does not block on `krun_start_enter` because that call never returns on success). The parent shall write a `vmm.pid` file and surface child-exit codes via signal handling. +- **R2.4**: Boot shall complete to a guest-side marker (writes `READY\n` on a designated vsock port) within 5s on a warm laptop; the parent shall block on this marker before reporting boot success. +- **R2.5**: No network device shall be added to the libkrun config in v0.1; gvproxy/TSI integration is owned by #160. Default libkrun vsock is acceptable since v0.1 does not expose TCP to the guest. + +**Proof Artifacts:** +- CLI: `MINVMD_KERNEL_PATH=/tmp/vmlinuz MINVMD_ROOTFS_PATH=/tmp/alpine-minirootfs minvmd boot --foreground` boots and prints `vm-up` to stdout within 5s, and a host-side reader on the vsock marker socket reads `READY` demonstrates kernel+rootfs come up. +- Test: `tests/boot_e2e.rs` (gated `MINVMD_E2E=1`, `#[ignore]`) asserts the marker round-trip end-to-end. + +--- + +### Unit 3: UDS↔vsock bridge for `ssh.sock` + +**Purpose:** The product feature — host UDS the CLI talks to, vsock to the guest where `minimald` listens. Bidirectional, transport-agnostic, multiple concurrent connections. + +**Depends on:** Unit 2 + +**Affected areas:** `crates/minvmd/src/bridge.rs` (new), `crates/minvmd/src/sock.rs` (new), `crates/minvmd/src/vm.rs` (extend boot to register the vsock port + spawn the bridge) + +**Functional Requirements:** +- **R3.1**: `minvmd` shall expose a host UDS at `$XDG_RUNTIME_DIR/minimal/minimald.sock` (fallback `~/.minimal/local/minimald.sock`) that bridges to a designated vsock port (proposed 2222; confirmed against #156) inside the VM. The UDS shall be created with mode 0600 and owned by the invoking user. +- **R3.2**: The bridge shall accept multiple concurrent host connections; each connection shall splice bytes bidirectionally between the host UDS and a fresh vsock connection until either side closes (use `tokio::io::copy_bidirectional` or equivalent). +- **R3.3**: On guest unavailability (VM crash, `minimald` exit, vsock connection refused), the host UDS shall keep accepting connections; failed connections shall return a typed `BridgeError::GuestUnavailable` and a `tracing::warn!` log without taking the listener down. +- **R3.4**: The bridge shall be transport-agnostic — no SSH/russh parsing, no protocol awareness. Bytes in, bytes out. (russh subsystem dispatch lives in `minimald`, per #156.) +- **R3.5**: TSI loopback's ~62-concurrent-connection cap (per `~/code/min-ctl` lessons.md) shall be documented in `crates/minvmd/src/bridge.rs` as a comment; v0.1 does not require more than ~10 concurrent client connections so this is acceptable. + +**Proof Artifacts:** +- Test: `tests/bridge_e2e.rs` (gated `MINVMD_E2E=1`, `#[ignore]`) boots a VM running guest-side `socat VSOCK-LISTEN:2222,fork EXEC:cat`, opens 5 concurrent host UDS connections, each writes a distinct payload and reads it back. All 5 succeed demonstrates concurrent bidirectional bridging. +- CLI: With a stub `minimald` in the VM that returns an empty list to a `list-sessions` RPC, running `nc -U ~/.local/state/minimal/minvmd/minimald.sock` from the host (or a CLI integration) yields the empty list end-to-end demonstrates the host→guest path. + +--- + +### Unit 4: Lifecycle daemon — auto-spawn, status, stop + +**Purpose:** Daemon UX. `minimal` calling `minvmd` for the first time auto-spawns it; subsequent calls reuse; `minvmd status` introspects; `minvmd stop` shuts down gracefully. + +**Depends on:** Unit 3 + +**Affected areas:** `crates/minvmd/src/cmd/{run,status,stop}.rs` (new), `crates/minvmd/src/state.rs` (new), `crates/minvmd/src/lifecycle.rs` (new), `crates/minimal2/src/main.rs` (extend) + +**Functional Requirements:** +- **R4.1**: State and PID files shall live under `$XDG_STATE_HOME/minimal/minvmd/` (default `~/.local/state/minimal/minvmd/`): `state.toml` (lifecycle enum + `vmm_pid` + `started_at`), `vmm.pid`, `lifecycle.lock`. `state.toml` writes shall be atomic (tmp + rename + fsync). +- **R4.2**: `minvmd run` shall be a foreground supervisor (parent of the libkrun child + owner of the bridge); `minvmd run --detach` shall background-spawn and return only after the host UDS is accepting connections, with a configurable timeout (default 8s). +- **R4.3**: `minvmd status` shall print human-readable status by default and JSON with `--json` (fields: `state`, `vmm_pid`, `uptime_seconds`, `vcpus`, `ram_mib`). Exit code 0 if running, 1 if stopped, 2 on lock contention. +- **R4.4**: `minvmd stop` shall SIGTERM the vmm child, wait up to 5s, SIGKILL on timeout, then remove `vmm.pid` and reset `state.toml` to `Stopped`. The command shall be idempotent — stopping an already-stopped VM exits 0. +- **R4.5**: On macOS, `crates/minimal2` shall check `state.toml` before connecting to the UDS; if no `minvmd` is running it shall spawn `minvmd run --detach` and wait (with timeout) for the UDS. On Linux this path shall be a no-op. +- **R4.6**: State transitions shall be guarded by an `fd-lock`-style file lock on `lifecycle.lock` so concurrent CLI invocations cannot race. Recovery from a panicking transition (e.g. crash mid-`Starting`) shall be handled by an RAII guard modelled on `min-ctl`'s `StartingGuard` — drop without explicit commit resets to `Stopped`. +- **R4.7**: All lifecycle transitions shall pass through a pure `next_state(current: Lifecycle, action: Action) -> Result` function with no I/O, exhaustively unit-tested. + +**Proof Artifacts:** +- Test: `crates/minvmd/src/lifecycle.rs` includes table-driven `#[test]`s for every legal and illegal transition; `cargo test -p minvmd lifecycle::` passes demonstrates the pure state machine. +- CLI: `minvmd stop && minvmd status --json` prints `{"state":"stopped",...}` and exits 1 demonstrates stop + status semantics. +- CLI: From a clean state (no minvmd running), `minimal ls` on a Mac succeeds within 8s and a subsequent `minvmd status` reports `running`; a second `minimal ls` completes in <500ms demonstrates auto-spawn + warm reuse. + +## Non-Goals (Out of Scope) + +- **Networking** — gated on #160 (gvproxy spike). v0.1 VMs have no net device; in-session package installs and outbound git operations will not work yet. Document loudly. +- **Multi-VM / multi-tenant** — single named VM (`default`); multi-VM is a v0.2+ concern. +- **`minvmd init` / OCI image fetch / cosign verification** — kernel and rootfs paths are passed in via env. Image-fetch pipelines are a separate concern (`virtio-linux` + a future Alpine package + the minimal graph). +- **Virtiofs / live host mounts** — per `~/code/min-ctl` lessons (TCC + provenance xattr issues, fd starvation), v0.1 has zero live mounts. File transport into the VM is `minimald`'s problem (tar push/pull per #151). +- **`brew services` registration** — auto-spawn from the CLI suffices for v0.1; a brew service can layer on later without changing the contract. +- **PTY supervision / session sandboxing** — those live in `minimald`, not `minvmd`. +- **Linux build of `minvmd`** beyond the no-op shim — nothing to run on Linux. +- **OS suspend/resume of the VM, RAM resizing, vcpu hot-add** — deferred. +- **Lifting code from `min-ctl`** — we reference patterns only; no code vendoring. + +## Design Considerations + +### Process model + +`krun_start_enter` never returns on success — it `exit()`s with the guest workload's exit code. This forces a parent/child split: + +``` +minvmd run (parent — supervisor) + └── minvmd __krun-vmm (hidden child — calls krun_start_enter) + └── libkrun + Alpine VM (the actual VM) + └── minimald (pid-1) (in-VM, via krun_set_exec) +``` + +Parent owns: `state.toml`, `lifecycle.lock`, host UDS listener, vsock bridge accept loop. Child owns: libkrun context, kernel/rootfs paths. They communicate via a single-use auth token (written to state dir mode 0600, verified by child, deleted immediately) plus signals. This pattern is lifted from `~/code/min-ctl/src/cmd/vmm_child.rs` and `~/code/min-ctl/src/cmd/start.rs`. + +### Reference patterns (no code vendored) + +| Pattern | min-ctl reference | +|---|---| +| FFI safety wrappers | `src/vm/krun/raw.rs` | +| Lifecycle state machine | `src/vm/lifecycle.rs` | +| `StartingGuard` RAII recovery | `src/cmd/start.rs:64-138` | +| Atomic state persistence | `src/vm/state.rs` | +| Child VMM entry pattern | `src/cmd/vmm_child.rs` | +| Single-use auth token (T36) | `src/cmd/start.rs` | +| XDG home resolution | `src/home.rs` | + +### Hard lessons baked in + +- **No `$HOME` virtiofs** — TCC + provenance xattr issues on macOS Tahoe. Zero virtiofs mounts in v0.1. +- **TSI ~62 concurrent connection cap** — fine for v0.1 (<10 concurrent), document the constraint, revisit when networking lands. +- **Error fidelity** — never collapse `Backend { op, code: errno }` into a `String`; wrap-and-rethrow preserves the errno. +- **Stubs are sticky** — every stub shall `panic!`/`bail!`/`unimplemented!` explicitly; no silent no-ops. + +### What we deliberately do not do (vs min-ctl) + +- No OCI image fetch + cosign — the package graph owns image integrity. +- No K8s quantity / Go duration parsers, no `config.toml` — overkill for v0.1. +- No `shell` / `attach` / `exec` / `push` / `pull` / `mount` / `logs` / `mcp` subcommands — those are min-ctl's product surface, not minvmd's. minvmd is a pure transport-and-VM-lifecycle daemon. + +## Repository Standards + +- Workspace conventions from `CLAUDE.md`: workspace-pinned deps; `cargo fmt && cargo test -- --include-ignored`; `cargo clippy --allow-dirty --fix --all-targets -- -D warnings`; no `println!`/`eprintln!` outside the CLI surface (use `tracing`); structured fields not interpolated strings (`tracing::info!(pkg = %name, "msg")`); typed error enums in library code, `anyhow::Result` only at CLI boundaries. +- Naming: `minvmd` (matches `minimald`). +- Platform gates: `#[cfg(target_os = "macos")]` for all libkrun-touching code; a stub Linux entry that `bail!`s. +- Tests: integration tests under `tests/`; libkrun-touching tests `#[ignore]` and gated on `MINVMD_E2E=1`; pure state-machine + parser tests run unconditionally. +- Unsafe: every `unsafe` block carries a `// SAFETY:` comment justifying every caller invariant. +- Dependencies: `nix`, `tokio`, `anyhow`, `serde`, `toml`, `tracing` (already in workspace); `fd-lock` (new, workspace-pin). Link libkrun directly via `build.rs`; do not pull a `libkrun` crate dependency. + +## Verification + +**Project maturity:** Established + +**Available commands:** +| Check | Command | +|---|---| +| Lint | `cargo clippy --allow-dirty --fix --all-targets -- -D warnings` | +| Build | `cargo build -p minvmd` (Linux: shim; macOS: full) | +| Test | `cargo test -p minvmd` (unit + pure); `MINVMD_E2E=1 cargo test -p minvmd -- --include-ignored` (full) | + +**Greenfield bootstrapping:** N/A — all commands available + +**End-to-end manual verification (Mac):** +1. `cargo build -p minvmd --release && codesign --entitlements crates/minvmd/minvmd.entitlements --force -s - target/release/minvmd` +2. Build `virtio-linux` (pkgs#154); stage an Alpine minirootfs via `scripts/fetch-alpine.sh`; export `MINVMD_KERNEL_PATH` and `MINVMD_ROOTFS_PATH`. +3. `minvmd run --detach && minvmd status --json` → reports `{"state":"running",...}`. +4. `nc -U ~/.local/state/minimal/minvmd/minimald.sock` reaches a stub `minimald` running in the VM. +5. `minvmd stop && minvmd status` → reports `stopped`, exit 1. + +**CI gate:** existing Linux-only CI stays green via the no-op shim. Optional `build-macos` job that runs `cargo check -p minvmd` once a Mac runner is available. + +## Technical Considerations + +- **libkrun linking** — pinned to a known-good version (initially the slp/krun Homebrew tap version used by min-ctl, currently v1.18.0). `build.rs` emits `cargo:rustc-link-search` and `cargo:rustc-link-arg=-Wl,-rpath` pointing at `/opt/homebrew/lib` with a `LIBKRUN_PREFIX` env override. +- **Hidden `__krun-vmm` subcommand** — modelled on min-ctl's `src/cmd/vmm_child.rs`. Not in `--help`; verified-via-auth-token; the only entry point that calls `krun_start_enter`. +- **State file format** — TOML with serde; one file per VM (in v0.1, only `default`). Lifecycle enum is `NotProvisioned | Stopped | Starting | Running | Stopping`. +- **Auto-spawn from `minimal2`** — implementation lives in `crates/minimal2/src/main.rs` behind `#[cfg(target_os = "macos")]`. On Linux it is a no-op; the CLI talks to `minimald` directly. + +## Security Considerations + +- Single entitlement: `com.apple.security.hypervisor`. No network, no file-access-outside-home, no Apple Developer Program membership required (ad-hoc signing via `codesign -s -`). +- Host UDS perms: mode 0600, owner-only. `LOCAL_PEERCRED` check recommended but not required at v0.1 since the UDS perms already gate access. +- No authentication on the bridge — fine because access is mode-gated. Do not expose the bridge over TCP without rethinking auth. +- Single-use auth token between parent `minvmd run` and child `minvmd __krun-vmm` (T36 pattern from min-ctl): written to `$XDG_STATE_HOME/minimal/minvmd/vmm.auth` mode 0600, verified by child, deleted on first read. Prevents stray re-execs of the hidden subcommand. +- Image provenance is deferred — v0.1 reads kernel + rootfs from caller-supplied paths. Once the minimal package graph wires the artifacts, content-addressed hashes already provide integrity. + +## Success Metrics + +- Mac developer runs `minimal ls` on a fresh install with no setup beyond install + first-time package fetch and gets a result in < 8s cold, < 500ms warm. +- Crate compiles green in CI on Linux (no-op shim) and is buildable on Mac. +- Smoke test (`MINVMD_E2E=1`) covers FFI bring-up, boot-to-marker, and 5-way concurrent bridge connections. +- Zero `unsafe` blocks without a `// SAFETY:` comment. Zero `unwrap()` outside `#[cfg(test)]`. Zero `println!`/`eprintln!` outside the CLI surface. + +## Open Questions + +1. **Alpine rootfs source.** v0.1 spec specifies `scripts/fetch-alpine.sh` (download + sha256-verify upstream Alpine minirootfs to `~/.cache/minimal/minvmd/rootfs/`). Migration path: write a sibling `alpine-minirootfs` minimal package in `gominimal/pkgs` once `virtio-linux` (#154) merges, then minvmd consumes both via the package graph instead of env vars. Track as a follow-up issue. +2. **Vsock port for `minimald`.** Proposed 2222 (avoids min-ctl's agent port 7350 so they can coexist on a Mac dev box). Confirm with #156 owner. +3. **Bridge transport on the guest side.** Does `minimald` in v0.1 listen on vsock directly via `vhost-vsock` kernel support, or on a UDS inside the VM with a tiny shim forwarding to vsock? Direct vsock is lighter system-wide; UDS+shim is lighter on `minimald`. Defer to #156 / `minimald` owner. +4. **In-VM `minimald` supervision.** Run `minimald` as pid-1 via `krun_set_exec(..., "minimald")`, or boot a tiny init (busybox/OpenRC) that launches it? Pid-1 is simpler but `minimald` then owns signal forwarding + zombie reaping. Proposed: pid-1 for v0.1; revisit if reaping becomes painful. +5. **Brew distribution.** Out of scope per non-goals, but flagging that the codesign step must be reproducible on contributors' machines — justfile target covers this. diff --git a/docs/specs/01-spec-minvmd-host-daemon/crate-scaffold-ffi-wrappers-libkrun-smoke-test.feature b/docs/specs/01-spec-minvmd-host-daemon/crate-scaffold-ffi-wrappers-libkrun-smoke-test.feature new file mode 100644 index 0000000000..df52a9abce --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/crate-scaffold-ffi-wrappers-libkrun-smoke-test.feature @@ -0,0 +1,56 @@ +# Source: docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md +# Pattern: CLI/Process (build + smoke test) +# Recommended test type: Integration + +Feature: Crate scaffold, FFI wrappers, libkrun smoke test + + Scenario: Crate compiles on macOS aarch64 target + Given a checkout of the minimal workspace on an aarch64-apple-darwin host + When the user runs "cargo build -p minvmd --target aarch64-apple-darwin" + Then the command exits with code 0 + And the binary "target/aarch64-apple-darwin/debug/minvmd" is produced + + Scenario: Crate compiles on macOS x86_64 target + Given a checkout of the minimal workspace on a host with the x86_64-apple-darwin toolchain installed + When the user runs "cargo build -p minvmd --target x86_64-apple-darwin" + Then the command exits with code 0 + And the binary "target/x86_64-apple-darwin/debug/minvmd" is produced + + Scenario: Linux build produces a no-op shim that keeps CI green + Given a checkout of the minimal workspace on an x86_64-unknown-linux-gnu host + When the user runs "cargo build -p minvmd" + Then the command exits with code 0 + And running the resulting "minvmd" binary with any subcommand exits non-zero with a stderr message naming macOS as the only supported platform + + Scenario: FFI return codes surface as typed VmError::Backend with preserved errno + Given a safe wrapper around a libkrun FFI call configured to receive a known failure return code from the backend + When the wrapper is invoked with inputs that pass safe-Rust validation but trigger the backend failure + Then the wrapper returns Err(VmError::Backend { op, code }) where op names the FFI function and code equals the original errno magnitude returned by libkrun + And no panic, abort, or process exit occurs + + Scenario: Safe wrappers reject invalid inputs before crossing the FFI boundary + Given a safe wrapper that requires a NUL-terminated path argument + When the wrapper is called with a Rust string containing an interior NUL byte + Then the wrapper returns a typed validation error + And no libkrun FFI function is invoked + + Scenario: Release binary is code-signed with the hypervisor entitlement via justfile + Given a release build of minvmd has been produced on macOS + When the user runs the justfile signing target + Then the command exits with code 0 + And "codesign -d --entitlements - target/release/minvmd" prints an entitlements plist containing "com.apple.security.hypervisor" + And the printed entitlements plist contains no other entitlement keys + + Scenario: Smoke test boots libkrun with /bin/true and exits cleanly + Given a macOS host with libkrun installed + And the environment variable "MINVMD_E2E" is set to "1" + When the user runs "cargo test -p minvmd --test krun_smoke -- --include-ignored" + Then the command exits with code 0 + And the test output reports the smoke test as passing + + Scenario: Smoke test is skipped by default to keep unit-test runs hermetic + Given a checkout of the minimal workspace + And the environment variable "MINVMD_E2E" is unset + When the user runs "cargo test -p minvmd" + Then the command exits with code 0 + And the krun_smoke test is reported as ignored rather than executed diff --git a/docs/specs/01-spec-minvmd-host-daemon/lifecycle-daemon-auto-spawn-status-stop.feature b/docs/specs/01-spec-minvmd-host-daemon/lifecycle-daemon-auto-spawn-status-stop.feature new file mode 100644 index 0000000000..ebae5a19bd --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/lifecycle-daemon-auto-spawn-status-stop.feature @@ -0,0 +1,106 @@ +# Source: docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md +# Pattern: State + CLI/Process (lifecycle, atomic persistence, auto-spawn) +# Recommended test type: Integration + +Feature: Lifecycle daemon — auto-spawn, status, stop + + Scenario: state.toml, vmm.pid, and lifecycle.lock live under XDG_STATE_HOME + Given XDG_STATE_HOME is set to a temporary directory + When minvmd is started with "minvmd run --detach" + Then the file "$XDG_STATE_HOME/minimal/minvmd/state.toml" exists and parses as TOML containing fields "state", "vmm_pid", and "started_at" + And the file "$XDG_STATE_HOME/minimal/minvmd/vmm.pid" exists and contains the PID of the VMM child process + And the file "$XDG_STATE_HOME/minimal/minvmd/lifecycle.lock" exists + + Scenario: state.toml writes are atomic across a crash mid-write + Given a running minvmd with a populated state.toml whose "state" field is "running" + When the parent supervisor is SIGKILLed at any point during a state transition write + Then state.toml on disk parses cleanly as TOML on every read + And the "state" field is either the prior committed value or the new committed value, never partial + + Scenario: minvmd run --detach returns only once the host UDS accepts connections + Given no minvmd is currently running and the state directory is empty + When the user runs "minvmd run --detach" + Then the command exits with code 0 within the default 8 second timeout + And immediately after the command returns, a client can connect to the host UDS at "$XDG_RUNTIME_DIR/minimal/minimald.sock" successfully + + Scenario: minvmd run --detach times out and exits non-zero if the UDS never opens + Given no minvmd is currently running + And the kernel/rootfs configuration is invalid so the VM cannot reach READY + When the user runs "minvmd run --detach" with the default 8 second timeout + Then the command exits non-zero within 8 seconds plus a small grace period + And stderr names the boot or UDS-readiness failure + + Scenario: minvmd status --json prints structured fields when running + Given a running minvmd attached to a booted VM configured with 2 vcpus and 1024 MiB of RAM + When the user runs "minvmd status --json" + Then the command exits with code 0 + And stdout is a single JSON object containing the keys "state", "vmm_pid", "uptime_seconds", "vcpus", and "ram_mib" + And "state" equals "running", "vcpus" equals 2, and "ram_mib" equals 1024 + + Scenario: minvmd status exits 1 when stopped + Given no minvmd is running and state.toml reports "stopped" + When the user runs "minvmd status --json" + Then the command exits with code 1 + And stdout is a JSON object whose "state" field equals "stopped" + + Scenario: minvmd status exits 2 on lock contention + Given the lifecycle.lock file is held exclusively by another process performing a state transition + When the user runs "minvmd status --json" + Then the command exits with code 2 + And stderr names the lock contention + + Scenario: minvmd stop terminates the child, cleans up files, and resets state + Given a running minvmd with a live VMM child and a populated vmm.pid file + When the user runs "minvmd stop" + Then the command exits with code 0 within 5 seconds + And the VMM child process is no longer present in the process table + And the file "vmm.pid" no longer exists in the state directory + And state.toml's "state" field is "stopped" + + Scenario: minvmd stop escalates to SIGKILL if the child does not exit within 5 seconds + Given a running minvmd whose VMM child ignores SIGTERM + When the user runs "minvmd stop" + Then the VMM child process is no longer present in the process table within 6 seconds of the command starting + And the command exits with code 0 + And state.toml's "state" field is "stopped" + + Scenario: minvmd stop is idempotent on an already-stopped VM + Given no minvmd is running and state.toml reports "stopped" + When the user runs "minvmd stop" + Then the command exits with code 0 + And state.toml's "state" field remains "stopped" + + Scenario: First minimal call on macOS auto-spawns minvmd and warm second call is fast + Given a macOS host with no minvmd process running and an empty minvmd state directory + When the user runs "minimal ls" + Then the command exits with code 0 within 8 seconds + And after the command returns, "minvmd status --json" reports "state" equal to "running" + When the user immediately runs "minimal ls" a second time + Then the second command exits with code 0 in under 500 milliseconds + + Scenario: Auto-spawn is a no-op on Linux + Given a Linux host with no minvmd installed and a running native minimald + When the user runs "minimal ls" + Then the command exits with code 0 + And no "minvmd" process is spawned during the call + And the CLI connects directly to the native minimald UDS + + Scenario: Concurrent CLI invocations cannot race the lifecycle + Given no minvmd is currently running + When 5 "minimal ls" processes are launched concurrently on a macOS host + Then exactly one minvmd parent supervisor process is started + And all 5 client commands exit with code 0 + And state.toml's "state" field ends as "running" with a single consistent vmm_pid + + Scenario: A panicking Starting transition is recovered to Stopped by the RAII guard + Given a minvmd run process that is forced to panic during the Starting transition before commit + When the process exits due to the panic + Then state.toml's "state" field is "stopped" once the panicking process has fully exited + And no orphaned VMM child remains in the process table + + Scenario: Pure next_state function accepts legal transitions and rejects illegal ones + Given the lifecycle states "NotProvisioned", "Stopped", "Starting", "Running", "Stopping" + When the unit tests in "crates/minvmd/src/lifecycle.rs" are executed via "cargo test -p minvmd lifecycle::" + Then every test case exercising a legal transition returns Ok with the expected next state + And every test case exercising an illegal transition returns Err(InvalidTransition) + And the test suite exits with code 0 diff --git a/docs/specs/01-spec-minvmd-host-daemon/uds-vsock-bridge.feature b/docs/specs/01-spec-minvmd-host-daemon/uds-vsock-bridge.feature new file mode 100644 index 0000000000..cd659afa36 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/uds-vsock-bridge.feature @@ -0,0 +1,47 @@ +# Source: docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md +# Pattern: CLI/Process + Async (bidirectional bridge with concurrency) +# Recommended test type: Integration + +Feature: UDS to vsock bridge for minimald + + Scenario: Host UDS is created with 0600 mode owned by the invoking user + Given a booted minvmd VM + When the bridge has started accepting connections + Then a Unix domain socket exists at "$XDG_RUNTIME_DIR/minimal/minimald.sock" + And the socket file mode is 0600 + And the socket file is owned by the invoking user's UID + + Scenario: Host UDS falls back to ~/.minimal/local/minimald.sock when XDG_RUNTIME_DIR is unset + Given a booted minvmd VM + And the environment variable XDG_RUNTIME_DIR is unset + When the bridge has started accepting connections + Then a Unix domain socket exists at "~/.minimal/local/minimald.sock" + And the socket file mode is 0600 + + Scenario: Five concurrent host UDS connections each round-trip distinct payloads + Given a booted minvmd VM running "socat VSOCK-LISTEN:2222,fork EXEC:cat" on the guest + And the host UDS bridge is accepting connections + When 5 host processes connect concurrently to the UDS, each writes a distinct payload, and each reads a response + Then each of the 5 connections reads back exactly the payload it wrote + And all 5 connections complete without error + + Scenario: Bridge is transport-agnostic and forwards arbitrary bytes unchanged + Given a booted minvmd VM with an echo service on vsock port 2222 + And the host UDS bridge is accepting connections + When a host client writes a 4 KiB random binary payload to the UDS and reads until EOF + Then the bytes read back equal the bytes written byte-for-byte + And the bridge does not parse, reframe, or rewrite the payload + + Scenario: Guest unavailability does not take down the listener + Given the host UDS bridge is accepting connections + And the guest-side vsock listener on port 2222 has been stopped so connection attempts are refused + When a host client connects to the UDS and attempts to send a request + Then the client connection is closed with a BridgeError::GuestUnavailable surfaced in the bridge tracing log at warn level + And a subsequent connection from a second client to the UDS is accepted by the listener without restart + + Scenario: End-to-end CLI call reaches a stub minimald in the VM + Given a booted minvmd VM with a stub minimald listening on vsock port 2222 that responds to "list-sessions" with an empty list + And the host UDS bridge is accepting connections + When the host runs a client that sends "list-sessions" over the UDS at "~/.local/state/minimal/minvmd/minimald.sock" + Then the client receives the empty-list response + And the exchange completes without the host needing to know a VM exists diff --git a/docs/specs/01-spec-minvmd-host-daemon/vm-bring-up-with-virtio-linux-kernel-and-alpine-rootfs.feature b/docs/specs/01-spec-minvmd-host-daemon/vm-bring-up-with-virtio-linux-kernel-and-alpine-rootfs.feature new file mode 100644 index 0000000000..5e89690577 --- /dev/null +++ b/docs/specs/01-spec-minvmd-host-daemon/vm-bring-up-with-virtio-linux-kernel-and-alpine-rootfs.feature @@ -0,0 +1,46 @@ +# Source: docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md +# Pattern: CLI/Process + Async (boot to READY marker) +# Recommended test type: Integration + +Feature: VM bring-up with virtio-linux kernel and Alpine rootfs + + Scenario: minvmd boot brings up the VM and prints vm-up within 5 seconds + Given a macOS host with libkrun installed + And MINVMD_KERNEL_PATH points to a valid virtio-linux vmlinuz artifact for the host architecture + And MINVMD_ROOTFS_PATH points to a staged Alpine minirootfs directory + When the user runs "minvmd boot --foreground" + Then stdout contains the line "vm-up" within 5 seconds + And the process remains running until interrupted + + Scenario: Guest writes READY marker on the designated vsock port + Given minvmd boot --foreground has been started with valid kernel and rootfs paths + And a host-side reader is connected to the marker vsock port + When the guest userspace init runs + Then the host-side reader reads the bytes "READY\n" from the marker socket within 5 seconds + + Scenario: Parent does not block on krun_start_enter and supervises a hidden child + Given minvmd boot --foreground has been started + When the VM has reached the READY marker + Then a file "vmm.pid" exists in the minvmd state directory containing the PID of the child VMM process + And that PID belongs to a running "minvmd __krun-vmm" process distinct from the parent supervisor PID + + Scenario: Child VMM exit is surfaced by the parent supervisor + Given minvmd boot --foreground is running with a booted VM + When the child VMM process exits with a non-zero status + Then the parent supervisor exits with a non-zero status + And the parent's stderr or tracing output names the child exit code + + Scenario: No network device is added to the libkrun configuration in v0.1 + Given a macOS host with libkrun installed + And valid MINVMD_KERNEL_PATH and MINVMD_ROOTFS_PATH are exported + When the user runs "MINVMD_E2E=1 cargo test -p minvmd --test boot_e2e -- --include-ignored" + Then the command exits with code 0 + And the guest, while booted, has no network interfaces beyond loopback when probed via the guest init + + Scenario: Boot fails fast and cleanly when the kernel path is missing + Given the environment variable MINVMD_KERNEL_PATH points to a non-existent file + And MINVMD_ROOTFS_PATH points to a valid Alpine minirootfs directory + When the user runs "minvmd boot --foreground" + Then the command exits non-zero within 1 second + And stderr names the missing kernel path + And no "vmm.pid" file is created in the minvmd state directory diff --git a/justfile b/justfile new file mode 100644 index 0000000000..e84ed173dd --- /dev/null +++ b/justfile @@ -0,0 +1,11 @@ +# justfile — repo-wide task runner. Lives at the workspace root. +# +# Recipes are grouped by crate where they're crate-specific. + +# Build a release `minvmd` binary and code-sign it with the hypervisor +# entitlement. Re-run any time the entitlements file or binary changes. +# Ad-hoc signing (`-s -`) requires no Apple Developer membership; the binary +# only runs on the host that signed it, which is correct for dev builds. +codesign-minvmd: + cargo build -p minvmd --release + codesign --entitlements crates/minvmd/minvmd.entitlements --force -s - target/release/minvmd