microsandbox_utils/
lib.rs

1//! Shared constants and utilities for the microsandbox project.
2
3pub mod copy;
4pub mod format;
5pub mod log_text;
6pub mod size;
7pub mod ttl_reverse_index;
8pub mod wake_pipe;
9
10//--------------------------------------------------------------------------------------------------
11// Constants: Directory Layout
12//--------------------------------------------------------------------------------------------------
13
14/// Name of the microsandbox home directory (relative to user's home).
15pub const BASE_DIR_NAME: &str = ".microsandbox";
16
17/// Subdirectory for shared libraries (libkrunfw).
18pub const LIB_SUBDIR: &str = "lib";
19
20/// Subdirectory for helper binaries.
21pub const BIN_SUBDIR: &str = "bin";
22
23/// Subdirectory for the database.
24pub const DB_SUBDIR: &str = "db";
25
26/// Subdirectory for OCI layer cache.
27pub const CACHE_SUBDIR: &str = "cache";
28
29/// Subdirectory for per-sandbox state.
30pub const SANDBOXES_SUBDIR: &str = "sandboxes";
31
32/// Subdirectory for named volumes.
33pub const VOLUMES_SUBDIR: &str = "volumes";
34
35/// Subdirectory for snapshot artifacts.
36pub const SNAPSHOTS_SUBDIR: &str = "snapshots";
37
38/// Subdirectory for logs.
39pub const LOGS_SUBDIR: &str = "logs";
40
41/// Subdirectory for secrets.
42pub const SECRETS_SUBDIR: &str = "secrets";
43
44/// Subdirectory for TLS certificates.
45pub const TLS_SUBDIR: &str = "tls";
46
47/// Subdirectory for SSH keys.
48pub const SSH_SUBDIR: &str = "ssh";
49
50/// Subdirectory for ephemeral runtime artifacts that should not be backed up.
51pub const RUN_SUBDIR: &str = "run";
52
53/// Subdirectory under `run` for metrics-related diagnostic artifacts.
54pub const METRICS_RUN_SUBDIR: &str = "metrics";
55
56/// Filename of the optional registry-name diagnostic file under `run/metrics`.
57pub const METRICS_REGISTRY_NAME_FILENAME: &str = "registry-v1.name";
58
59/// Prefix used when constructing the POSIX shared-memory object name for the
60/// live metrics registry. Combined with a stable hash of `GlobalConfig::home()`
61/// so concurrent `MSB_HOME`-isolated environments do not collide.
62///
63/// Kept short because macOS limits `shm_open` names to ~31 bytes including the
64/// leading slash; the final form is `<prefix>-<hex16>-v1` (28 bytes).
65pub const METRICS_SHM_PREFIX: &str = "/msb-met";
66
67//--------------------------------------------------------------------------------------------------
68// Constants: Binary Names
69//--------------------------------------------------------------------------------------------------
70
71/// Guest agent binary name.
72pub const AGENTD_BINARY: &str = "agentd";
73
74/// CLI binary name.
75pub const MSB_BINARY: &str = "msb";
76
77//--------------------------------------------------------------------------------------------------
78// Constants: Versions
79//--------------------------------------------------------------------------------------------------
80
81/// Version for downloading prebuilt release artifacts.
82///
83/// This tracks the published crate/package version so the SDK and the
84/// downloaded runtime bundle stay aligned.
85pub const PREBUILT_VERSION: &str = env!("CARGO_PKG_VERSION");
86
87/// libkrunfw release version. Keep in sync with justfile.
88pub const LIBKRUNFW_VERSION: &str = "5.2.1";
89
90/// libkrunfw ABI version (soname major). Keep in sync with justfile.
91pub const LIBKRUNFW_ABI: &str = "5";
92
93//--------------------------------------------------------------------------------------------------
94// Constants: Filenames
95//--------------------------------------------------------------------------------------------------
96
97/// Database filename.
98pub const DB_FILENAME: &str = "msb.db";
99
100/// Global configuration filename.
101pub const CONFIG_FILENAME: &str = "config.json";
102
103/// Project-local sandbox configuration filename.
104pub const SANDBOXFILE_NAME: &str = "Sandboxfile";
105
106//--------------------------------------------------------------------------------------------------
107// Constants: GitHub
108//--------------------------------------------------------------------------------------------------
109
110/// GitHub organization.
111pub const GITHUB_ORG: &str = "superradcompany";
112
113/// Main repository name.
114pub const MICROSANDBOX_REPO: &str = "microsandbox";
115
116//--------------------------------------------------------------------------------------------------
117// Functions
118//--------------------------------------------------------------------------------------------------
119
120/// Derive a short, stable identifier from a path.
121///
122/// Used to build a POSIX shared-memory object name that depends only on the
123/// resolved home directory, so two processes pointed at the same `MSB_HOME`
124/// agree on a single registry without leaking the absolute path through a
125/// public name.
126pub fn stable_hash_path(path: &std::path::Path) -> String {
127    // Avoid pulling sha2 into the utils crate for one filename; a stable
128    // 64-bit FNV-1a over the OS-bytes is plenty for collision-resistance at
129    // this scale (one entry per concurrent MSB_HOME on a host).
130    let bytes = path.as_os_str().as_encoded_bytes();
131    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
132    for byte in bytes {
133        hash ^= u64::from(*byte);
134        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
135    }
136    format!("{hash:016x}")
137}
138
139/// Resolve the microsandbox home directory.
140///
141/// Order of resolution:
142/// 1. `MSB_HOME` env var (used as-is, no `.microsandbox` suffix appended)
143/// 2. `~/.microsandbox/` (i.e. `dirs::home_dir().join(BASE_DIR_NAME)`)
144/// 3. `./.microsandbox/` if no home is available
145///
146/// `MSB_HOME` lets CI and integration tests isolate microsandbox state
147/// (db, sandboxes, cache, logs) per process without disturbing other
148/// `$HOME`-rooted tooling.
149pub fn resolve_home() -> std::path::PathBuf {
150    if let Some(path) = std::env::var_os("MSB_HOME") {
151        return std::path::PathBuf::from(path);
152    }
153    dirs::home_dir()
154        .unwrap_or_else(|| std::path::PathBuf::from("."))
155        .join(BASE_DIR_NAME)
156}
157
158/// Returns the platform-specific libkrunfw filename.
159pub fn libkrunfw_filename(os: &str) -> String {
160    if os == "macos" {
161        format!("libkrunfw.{LIBKRUNFW_ABI}.dylib")
162    } else {
163        format!("libkrunfw.so.{LIBKRUNFW_VERSION}")
164    }
165}
166
167/// Returns the GitHub release download URL for libkrunfw.
168pub fn libkrunfw_download_url(version: &str, arch: &str, os: &str) -> String {
169    let (target_os, ext) = if os == "macos" {
170        ("darwin", "dylib")
171    } else {
172        ("linux", "so")
173    };
174
175    format!(
176        "https://github.com/{GITHUB_ORG}/{MICROSANDBOX_REPO}/releases/download/v{version}/libkrunfw-{target_os}-{arch}.{ext}"
177    )
178}
179
180/// Returns the GitHub release download URL for the agentd binary.
181pub fn agentd_download_url(version: &str, arch: &str) -> String {
182    format!(
183        "https://github.com/{GITHUB_ORG}/{MICROSANDBOX_REPO}/releases/download/v{version}/{AGENTD_BINARY}-{arch}"
184    )
185}
186
187/// Returns the GitHub release download URL for the microsandbox bundle tarball.
188pub fn bundle_download_url(version: &str, arch: &str, os: &str) -> String {
189    let target_os = if os == "macos" { "darwin" } else { "linux" };
190    format!(
191        "https://github.com/{GITHUB_ORG}/{MICROSANDBOX_REPO}/releases/download/v{version}/{MICROSANDBOX_REPO}-{target_os}-{arch}.tar.gz"
192    )
193}
194
195/// Returns an HTTP client configured for release asset downloads.
196#[cfg(feature = "http-client")]
197pub fn http_client() -> ureq::Agent {
198    ureq::Agent::config_builder()
199        .tls_config(
200            ureq::tls::TlsConfig::builder()
201                .root_certs(ureq::tls::RootCerts::PlatformVerifier)
202                .build(),
203        )
204        .build()
205        .new_agent()
206}
207
208/// Returns true when a user-provided text value should be interpreted as a
209/// local filesystem path rather than a named resource or OCI reference.
210pub fn looks_like_local_path_text(s: &str) -> bool {
211    s == "." || s == ".." || s.starts_with('/') || s.starts_with("./") || s.starts_with("../")
212}
213
214//--------------------------------------------------------------------------------------------------
215// Tests
216//--------------------------------------------------------------------------------------------------
217
218#[cfg(test)]
219mod tests {
220    use super::*;
221
222    /// `MSB_HOME` is honoured verbatim (no `.microsandbox` suffix appended)
223    /// so callers can isolate state per process without disturbing tooling
224    /// that reads `$HOME` (npm cache, ssh keys, etc.).
225    ///
226    /// Uses a unique env var per test process to avoid clashing with other
227    /// parallel tests that read `MSB_HOME`.
228    #[test]
229    fn test_resolve_home_respects_env_override() {
230        // SAFETY: This test sets a process-global env var. Vitest-style
231        // single-test isolation isn't available; rely on the test being
232        // the sole reader of `MSB_HOME` in this binary.
233        let custom = std::path::PathBuf::from("/tmp/msb-home-resolve-test-12345");
234        unsafe { std::env::set_var("MSB_HOME", &custom) };
235        let resolved = resolve_home();
236        unsafe { std::env::remove_var("MSB_HOME") };
237        assert_eq!(resolved, custom);
238    }
239}
microsandbox_utils/lib.rs

microsandbox_utils/
lib.rs
