ktstr/vmm/
blobs.rs

1//! Blob extraction / install / load helpers shared by the `ktstr`
2//! and `cargo-ktstr` binaries.
3//!
4//! The `ktstr` library itself embeds no binary blob bytes (busybox,
5//! wprof, etc.): those live inside each *binary*'s executable via
6//! `include_bytes!`, kept out of `ktstr.rlib` so library consumers
7//! (test binaries, scheduler-author crates depending on `ktstr` as a
8//! dev-dep) do not pay the size cost for blobs they never invoke. The
9//! extraction *mechanism* lives here (no bytes) so both binaries share
10//! one implementation.
11//!
12//! At startup each binary calls [`install_blob_env_if_unset`] (or, for
13//! `cargo-ktstr`, its own always-set `install_env`) to extract its
14//! embedded blob to a content-addressed tempfile and export the path
15//! via an env var. Child processes inherit the var; the load helpers
16//! here ([`load_busybox_bytes`]) read it and load the bytes on demand
17//! at the point the library packs the blob into an initramfs.
18//!
19//! The standalone `ktstr` binary embeds busybox and installs it this
20//! way, so `ktstr shell` works with no env var. Direct `cargo nextest
21//! run` invocations run bare test binaries that install nothing and
22//! leave the env vars unset — the load helpers return an error in that
23//! case, never silently no-op. The canonical test invocation is
24//! `cargo ktstr test`.
25
26use anyhow::{Context, Result};
27
28/// Load the busybox blob bytes from the path exported at binary
29/// startup via the `KTSTR_BUSYBOX_PATH` env var.
30///
31/// Returns an error if the env var is unset (running a bare test
32/// binary, or a binary built without the busybox blob) or if the file
33/// cannot be read (tempfile gone, permissions wrong, etc.). Never
34/// returns `None` silently — busybox is a load-bearing dependency for
35/// shell-mode VMs and disk-template builds; a missing blob must fail
36/// loudly.
37pub fn load_busybox_bytes() -> Result<Vec<u8>> {
38    load_blob_from_env(crate::KTSTR_BUSYBOX_PATH_ENV, "busybox")
39}
40
41/// Return the on-disk path to the wprof binary extracted by
42/// `cargo-ktstr` at startup. Returns an error if `KTSTR_WPROF_PATH`
43/// is unset.
44#[cfg(feature = "wprof")]
45pub fn load_wprof_path() -> Result<std::path::PathBuf> {
46    let env_var = crate::KTSTR_WPROF_PATH_ENV;
47    let path = std::env::var(env_var).map_err(|_| {
48        anyhow::anyhow!(
49            "{env_var} env var unset — wprof blob is provided \
50             by `cargo-ktstr` at startup. Run tests via \
51             `cargo ktstr test`, not direct `cargo nextest run`."
52        )
53    })?;
54    Ok(std::path::PathBuf::from(path))
55}
56
57fn load_blob_from_env(env_var: &str, blob_name: &str) -> Result<Vec<u8>> {
58    let path = std::env::var(env_var).map_err(|_| {
59        anyhow::anyhow!(
60            "{env_var} env var unset — the `ktstr` and `cargo-ktstr` \
61             binaries embed the {blob_name} blob and export this path \
62             at startup. An unset var means either the binary was \
63             built without the {blob_name} blob (a skip-build \
64             override) or you are running a bare test binary directly \
65             — run tests via `cargo ktstr test`, not direct \
66             `cargo nextest run`."
67        )
68    })?;
69    std::fs::read(&path).with_context(|| format!("read {blob_name} blob from {env_var}={path}"))
70}
71
72/// Extract `bytes` to `$TMPDIR/ktstr-blob-{name_hint}-{sha256:16}`
73/// and return the path.
74///
75/// Content-addressed naming makes extraction idempotent across
76/// invocations: identical bytes always resolve to the same path, so a
77/// fresh invocation that finds a sized-matching file at the target
78/// reuses it instead of rewriting. A different blob (different bytes →
79/// different hash) writes a new file alongside; sweeping stale files
80/// is delegated to the OS `$TMPDIR` lifecycle (tmpfiles.d cleanup,
81/// container teardown, CI workspace wipe).
82///
83/// The hash is truncated to 16 hex chars (64 bits) — collision-
84/// resistant for the handful of blobs ktstr ships; the birthday bound
85/// against a 64-bit hash keeps the collision probability far below any
86/// rate that matters here.
87///
88/// Concurrency: two processes racing on the same blob both write a
89/// sibling staging tempfile and `rename(2)` it onto the target. rename
90/// is atomic on a single filesystem, and last-writer-wins is safe
91/// because both writers produce bit-identical content.
92pub fn extract_blob(bytes: &[u8], name_hint: &str) -> std::io::Result<std::path::PathBuf> {
93    use sha2::{Digest, Sha256};
94    use std::io::Write;
95    use std::os::unix::fs::PermissionsExt;
96
97    let mut hasher = Sha256::new();
98    hasher.update(bytes);
99    let digest = hasher.finalize();
100    let hash_hex = hex::encode(&digest[..8]);
101
102    let target = std::env::temp_dir().join(format!("ktstr-blob-{name_hint}-{hash_hex}"));
103
104    // Reuse if a sized-matching file already exists. A
105    // (name, truncated-sha256) match implies the bytes are
106    // identical — see fn-level doc on the truncation bound.
107    if let Ok(meta) = std::fs::metadata(&target)
108        && meta.len() == bytes.len() as u64
109    {
110        return Ok(target);
111    }
112
113    // Write to a sibling staging tempfile so the rename below is
114    // same-filesystem (atomic). keep() disables the tempfile's
115    // drop-cleanup and returns the persisted staging path; the
116    // subsequent rename(staging_path, target) removes the
117    // random-suffix name and installs the content-addressed target.
118    let dir = target.parent().unwrap_or_else(|| std::path::Path::new("."));
119    let mut staging = tempfile::Builder::new()
120        .prefix(&format!("ktstr-blob-{name_hint}-staging-"))
121        .tempfile_in(dir)?;
122    staging.write_all(bytes)?;
123    staging.flush()?;
124    std::fs::set_permissions(staging.path(), std::fs::Permissions::from_mode(0o755))?;
125    let (_file, staging_path) = staging
126        .keep()
127        .map_err(|e| std::io::Error::other(format!("persist staging tempfile: {e}")))?;
128    std::fs::rename(&staging_path, &target)?;
129    Ok(target)
130}
131
132/// Extract `bytes` via [`extract_blob`] and export its path through
133/// `env_var`, unless the var is already set or `bytes` is empty.
134///
135/// An already-set `env_var` wins (explicit override — used by tests
136/// and callers pointing ktstr at a pre-extracted blob). Empty `bytes`
137/// mean the blob's build was skipped (e.g. `KTSTR_SKIP_BUSYBOX_BUILD`
138/// wrote a 0-byte placeholder): nothing is exported, so consumers get
139/// the clean "unset" error from the load helpers at use time rather
140/// than an opaque "exec format error" on a 0-byte blob.
141///
142/// Mirrors `cargo-ktstr`'s startup blob install for the standalone
143/// `ktstr` binary, which embeds its own copy of busybox and calls this
144/// from `main`.
145///
146/// # Safety
147///
148/// The caller MUST invoke this before spawning any thread or running
149/// any code that reads environment variables concurrently:
150/// `std::env::set_var` is unsound with a concurrent reader.
151pub fn install_blob_env_if_unset(
152    env_var: &str,
153    name_hint: &str,
154    bytes: &[u8],
155) -> std::io::Result<()> {
156    if std::env::var_os(env_var).is_some() || bytes.is_empty() {
157        return Ok(());
158    }
159    let path = extract_blob(bytes, name_hint)?;
160    // SAFETY: per the fn-level precondition, the caller runs this
161    // before any thread spawn, so no concurrent env reader exists.
162    unsafe {
163        std::env::set_var(env_var, &path);
164    }
165    Ok(())
166}
167
168#[cfg(test)]
169mod tests {
170    use super::*;
171
172    /// Same blob bytes resolve to the same content-addressed path
173    /// across calls — the second call must not write a new file.
174    /// Pins the idempotency contract that motivates content
175    /// addressing (no per-invocation `$TMPDIR` accumulation).
176    #[test]
177    fn extract_blob_is_idempotent_for_same_bytes() {
178        let bytes = b"ktstr-blob-test-idempotent-payload";
179        let name = "idempotent-test";
180
181        let first = extract_blob(bytes, name).expect("first extract");
182        let first_mtime = std::fs::metadata(&first)
183            .expect("first metadata")
184            .modified()
185            .expect("mtime");
186
187        let second = extract_blob(bytes, name).expect("second extract");
188        let second_mtime = std::fs::metadata(&second)
189            .expect("second metadata")
190            .modified()
191            .expect("mtime");
192
193        assert_eq!(
194            first, second,
195            "same bytes must resolve to the same content-addressed path",
196        );
197        assert_eq!(
198            first_mtime, second_mtime,
199            "second call must reuse the existing file, not rewrite it (would bump mtime)",
200        );
201
202        // Hygiene — keep `$TMPDIR` clean for parallel test runs.
203        let _ = std::fs::remove_file(&first);
204    }
205
206    /// Different blob bytes resolve to different paths — pins that
207    /// the hash is actually content-derived, not derived from the
208    /// name_hint alone.
209    #[test]
210    fn extract_blob_distinguishes_distinct_bytes() {
211        let name = "distinguish-test";
212        let alpha = extract_blob(b"alpha-payload-bytes", name).expect("alpha extract");
213        let beta = extract_blob(b"beta-payload-bytes", name).expect("beta extract");
214
215        assert_ne!(
216            alpha, beta,
217            "distinct bytes under the same name_hint must produce distinct paths",
218        );
219
220        let _ = std::fs::remove_file(&alpha);
221        let _ = std::fs::remove_file(&beta);
222    }
223
224    /// The extracted file must be executable (mode 0o755) — pins the
225    /// executable-mode contract set at the
226    /// `set_permissions(.., from_mode(0o755))` call. The extracted
227    /// host tempfile is never exec'd: the library reads its bytes to
228    /// pack them into the guest initramfs, where the guest exec bit is
229    /// set independently by the cpio `write_entry` mode (`0o100755`).
230    #[test]
231    fn extract_blob_sets_executable_mode() {
232        use std::os::unix::fs::PermissionsExt;
233        let path = extract_blob(b"exec-mode-test-bytes", "exec-mode-test").expect("extract");
234        let mode = std::fs::metadata(&path)
235            .expect("metadata")
236            .permissions()
237            .mode()
238            & 0o777;
239        assert_eq!(
240            mode, 0o755,
241            "extracted blob must be rwx for owner / rx for everyone — got {mode:o}",
242        );
243        let _ = std::fs::remove_file(&path);
244    }
245
246    /// Empty bytes (blob build skipped) must leave the env var unset —
247    /// consumers then get the clean "unset" error, never a 0-byte blob.
248    #[test]
249    fn install_blob_env_if_unset_skips_empty_bytes() {
250        use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
251        let _lock = lock_env();
252        let env_var = "KTSTR_TEST_BLOB_EMPTY_PATH";
253        let _guard = EnvVarGuard::remove(env_var);
254        install_blob_env_if_unset(env_var, "empty-blob-test", b"").expect("install empty");
255        assert!(
256            std::env::var_os(env_var).is_none(),
257            "empty bytes must not export a blob path",
258        );
259    }
260
261    /// A preset env var wins — the embedded blob never overrides an
262    /// explicit override (the tests/override precedence contract).
263    #[test]
264    fn install_blob_env_if_unset_preserves_preset_var() {
265        use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
266        let _lock = lock_env();
267        let env_var = "KTSTR_TEST_BLOB_PRESET_PATH";
268        let _guard = EnvVarGuard::set(env_var, "/preset/override/path");
269        install_blob_env_if_unset(env_var, "preset-blob-test", b"nonempty-bytes")
270            .expect("install with preset");
271        assert_eq!(
272            std::env::var(env_var).ok().as_deref(),
273            Some("/preset/override/path"),
274            "a preset env var must win over the embedded blob",
275        );
276    }
277
278    /// Unset var + non-empty bytes: the extracted, content-addressed
279    /// path is exported and points at a readable file.
280    #[test]
281    fn install_blob_env_if_unset_exports_extracted_path() {
282        use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
283        let _lock = lock_env();
284        let env_var = "KTSTR_TEST_BLOB_EXPORT_PATH";
285        let _guard = EnvVarGuard::remove(env_var);
286        let bytes = b"install-export-payload-bytes";
287        install_blob_env_if_unset(env_var, "export-blob-test", bytes).expect("install export");
288        let exported = std::env::var(env_var).expect("env var must be set after install");
289        let read_back = std::fs::read(&exported).expect("exported path must be readable");
290        assert_eq!(read_back, bytes, "exported blob bytes must round-trip");
291        let _ = std::fs::remove_file(&exported);
292    }
293}