use std::path::Path;
use std::path::PathBuf;
use std::process::Command;
use std::process::Stdio;
use detcore::Digest;
use hermit::Context;
use hermit::Error;
const REQUIRED_DIRS: &[&str] = &["proc", "sys", "dev", "dev/pts", "tmp"];
pub(super) const DEV_BIND_TARGETS: &[&str] = &["null", "zero", "full", "random", "urandom"];
const DEV_SYMLINKS: &[(&str, &str)] = &[
("ptmx", "pts/ptmx"),
("fd", "/proc/self/fd"),
("stdin", "/proc/self/fd/0"),
("stdout", "/proc/self/fd/1"),
("stderr", "/proc/self/fd/2"),
];
const ROOTFS_LAYOUT_VERSION: &str = "rootfs-layout-v2-dev";
const ENV_BASENAME: &str = ".hermit-oci-env";
const WORKDIR_BASENAME: &str = ".hermit-oci-workdir";
fn rootfs_cache_dir(image_ref: &str) -> Result<PathBuf, Error> {
let base = if let Ok(xdg) = std::env::var("XDG_CACHE_HOME") {
PathBuf::from(xdg)
} else if let Ok(home) = std::env::var("HOME") {
PathBuf::from(home).join(".cache")
} else {
std::env::temp_dir()
};
let mut keyed = Vec::from(image_ref.as_bytes());
keyed.push(0);
keyed.extend_from_slice(ROOTFS_LAYOUT_VERSION.as_bytes());
let key = Digest::new(&keyed).to_string();
Ok(base.join("hermit").join("oci-rootfs").join(key))
}
fn ready_marker(cache: &Path) -> PathBuf {
cache.join(".hermit-oci-ready")
}
fn workdir_file(cache: &Path) -> PathBuf {
cache.join(WORKDIR_BASENAME)
}
fn env_file(cache: &Path) -> PathBuf {
cache.join(ENV_BASENAME)
}
#[derive(Default)]
pub(crate) struct ImageConfig {
pub env: Vec<(String, String)>,
pub workdir: Option<String>,
}
fn read_image_config_files(
env_path: &Path,
workdir_path: &Path,
) -> Result<Option<ImageConfig>, Error> {
let env_exists = env_path.try_exists().with_context(|| {
format!(
"Failed to inspect OCI environment file {}",
env_path.display()
)
})?;
let workdir_exists = workdir_path.try_exists().with_context(|| {
format!(
"Failed to inspect OCI working-directory file {}",
workdir_path.display()
)
})?;
if !env_exists && !workdir_exists {
return Ok(None);
}
let env = if env_exists {
parse_env(&std::fs::read_to_string(env_path).with_context(|| {
format!("Failed to read OCI environment file {}", env_path.display())
})?)
} else {
Vec::new()
};
let workdir = if workdir_exists {
parse_workdir(&std::fs::read_to_string(workdir_path).with_context(|| {
format!(
"Failed to read OCI working-directory file {}",
workdir_path.display()
)
})?)
} else {
None
};
Ok(Some(ImageConfig { env, workdir }))
}
pub(crate) fn read_image_config(image_ref: &str) -> Result<ImageConfig, Error> {
let cache = rootfs_cache_dir(image_ref)?;
if let Some(host) = read_image_config_files(&env_file(&cache), &workdir_file(&cache))? {
return Ok(host);
}
if let Some(in_root) = read_image_config_files(
&Path::new("/").join(ENV_BASENAME),
&Path::new("/").join(WORKDIR_BASENAME),
)? {
return Ok(in_root);
}
Ok(ImageConfig::default())
}
fn parse_env(contents: &str) -> Vec<(String, String)> {
contents
.lines()
.filter_map(|line| {
let line = line.trim_end_matches('\r');
if line.is_empty() {
return None;
}
line.split_once('=')
.map(|(k, v)| (k.to_string(), v.to_string()))
})
.collect()
}
fn parse_workdir(contents: &str) -> Option<String> {
let trimmed = contents.trim();
if trimmed.is_empty() || trimmed == "/" {
None
} else {
Some(trimmed.to_string())
}
}
pub(crate) fn materialize_rootfs(image_ref: &str) -> Result<PathBuf, Error> {
let cache = rootfs_cache_dir(image_ref)?;
let rootfs = cache.join("rootfs");
if ready_marker(&cache).exists() {
tracing::info!(
"Reusing cached OCI rootfs for {} at {}",
image_ref,
rootfs.display()
);
return Ok(rootfs);
}
tracing::info!("Materializing OCI rootfs for {}", image_ref);
std::fs::create_dir_all(&rootfs)
.with_context(|| format!("Failed to create rootfs cache dir {}", rootfs.display()))?;
let mkdirs = REQUIRED_DIRS
.iter()
.map(|d| {
format!(
"{dest}/{d}",
dest = shell_quote(&rootfs.to_string_lossy()),
d = d
)
})
.collect::<Vec<_>>()
.join(" ");
let dev_targets = DEV_BIND_TARGETS
.iter()
.map(|node| {
format!(
"{dest}/dev/{node}",
dest = shell_quote(&rootfs.to_string_lossy())
)
})
.collect::<Vec<_>>()
.join(" ");
let dev_symlinks = DEV_SYMLINKS
.iter()
.map(|(link, target)| {
format!(
"\tln -sfn {target} {dest}/dev/{link}\n",
target = shell_quote(target),
dest = shell_quote(&rootfs.to_string_lossy()),
)
})
.collect::<String>();
let script = format!(
r#"set -euo pipefail
cid=$(buildah from -- {ref})
trap 'buildah umount "$cid" >/dev/null 2>&1 || true; buildah rm "$cid" >/dev/null 2>&1 || true' EXIT
mp=$(buildah mount "$cid")
cp -a "$mp"/. {dest}/
root_mode=$(stat -c '%a' {dest})
chmod u+w {dest}
mkdir -p {mkdirs}
chmod u+rwx {mkdirs}
rm -f {dev_targets}
touch {dev_targets}
chmod u+rw {dev_targets}
{dev_symlinks} buildah inspect --type image --format '{{{{.OCIv1.Config.WorkingDir}}}}' {ref} > {workdir_file}
buildah inspect --type image --format '{{{{range .OCIv1.Config.Env}}}}{{{{println .}}}}{{{{end}}}}' {ref} > {env_file}
cp -f {workdir_file} {dest}/{workdir_base}
cp -f {env_file} {dest}/{env_base}
chmod "$root_mode" {dest}
"#,
ref = shell_quote(image_ref),
dest = shell_quote(&rootfs.to_string_lossy()),
mkdirs = mkdirs,
dev_targets = dev_targets,
dev_symlinks = dev_symlinks,
workdir_file = shell_quote(&workdir_file(&cache).to_string_lossy()),
env_file = shell_quote(&env_file(&cache).to_string_lossy()),
workdir_base = WORKDIR_BASENAME,
env_base = ENV_BASENAME,
);
let status = Command::new("buildah")
.arg("unshare")
.arg("bash")
.arg("-c")
.arg(&script)
.stdin(Stdio::null())
.status()
.context(
"Failed to spawn `buildah unshare` to materialize the OCI rootfs. \
The prototype requires a rootless `buildah` on PATH.",
)?;
if !status.success() {
return Err(Error::msg(format!(
"buildah failed to materialize OCI image {image_ref} (exit {status}); \
ensure the reference is valid and the registry is reachable \
(set a proxy in the environment if required)"
)));
}
std::fs::write(ready_marker(&cache), image_ref.as_bytes())
.context("Failed to write OCI rootfs readiness marker")?;
Ok(rootfs)
}
pub(crate) fn resolve_in_rootfs(rootfs: &Path, guest_abs: &Path) -> PathBuf {
const MAX_HOPS: usize = 40;
let mut current = rootfs.to_path_buf();
let mut pending: Vec<std::ffi::OsString> = guest_abs
.components()
.filter_map(|c| match c {
std::path::Component::Normal(part) => Some(part.to_os_string()),
std::path::Component::ParentDir => Some(std::ffi::OsString::from("..")),
_ => None,
})
.rev()
.collect();
let mut hops = 0usize;
while let Some(part) = pending.pop() {
if part == ".." {
if current != rootfs {
current.pop();
}
continue;
}
let candidate = current.join(&part);
match std::fs::symlink_metadata(&candidate) {
Ok(meta) if meta.file_type().is_symlink() => {
hops += 1;
if hops > MAX_HOPS {
return candidate;
}
match std::fs::read_link(&candidate) {
Ok(target) => {
if target.is_absolute() {
current = rootfs.to_path_buf();
}
for comp in target
.components()
.filter_map(|c| match c {
std::path::Component::Normal(p) => Some(p.to_os_string()),
std::path::Component::ParentDir => {
Some(std::ffi::OsString::from(".."))
}
_ => None,
})
.rev()
{
pending.push(comp);
}
}
Err(_) => return candidate,
}
}
_ => {
current = candidate;
}
}
}
current
}
fn shell_quote(s: &str) -> String {
let mut out = String::with_capacity(s.len() + 2);
out.push('\'');
for c in s.chars() {
if c == '\'' {
out.push_str("'\\''");
} else {
out.push(c);
}
}
out.push('\'');
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn cache_key_is_filesystem_safe_and_stable() {
let a = rootfs_cache_dir("docker.io/library/busybox@sha256:abc123").unwrap();
let b = rootfs_cache_dir("docker.io/library/busybox@sha256:abc123").unwrap();
assert_eq!(a, b, "same reference must map to the same cache dir");
let comp = a.file_name().unwrap().to_string_lossy();
assert!(
comp.len() == 64 && comp.chars().all(|c| c.is_ascii_hexdigit()),
"cache key component must be a SHA-256 hex digest, got {comp}"
);
}
#[test]
fn every_dev_bind_target_is_created_by_the_materializer() {
assert!(
REQUIRED_DIRS.contains(&"dev"),
"the /dev directory itself must be created"
);
assert!(
REQUIRED_DIRS.contains(&"dev/pts"),
"the devpts mount point must be created"
);
for node in DEV_BIND_TARGETS {
assert!(
!node.contains('/'),
"{node} must be a bare basename under /dev; a nested target would \
need its parent directory created too"
);
assert!(
Path::new("/dev").join(node).exists(),
"/dev/{node} does not exist on this host, so binding it would fail"
);
}
}
#[test]
fn minimal_dev_excludes_host_coupled_nodes() {
for excluded in ["tty", "shm", "console", "kvm", "fuse"] {
assert!(
!DEV_BIND_TARGETS.contains(&excluded),
"/dev/{excluded} is host-coupled and must not be bound into an image guest"
);
}
assert!(DEV_BIND_TARGETS.contains(&"random"));
assert!(DEV_BIND_TARGETS.contains(&"urandom"));
}
#[test]
fn ptmx_resolves_into_the_container_devpts_instance() {
let ptmx = DEV_SYMLINKS
.iter()
.find(|(link, _)| *link == "ptmx")
.expect("a /dev/ptmx symlink must be created");
assert_eq!(ptmx.1, "pts/ptmx", "ptmx must be instance-relative");
assert!(
!ptmx.1.starts_with('/'),
"an absolute ptmx target would resolve outside the devpts instance"
);
assert!(
!DEV_BIND_TARGETS.contains(&"ptmx"),
"ptmx must come from the container's own devpts, not a host bind"
);
}
#[test]
fn layout_version_participates_in_the_cache_key() {
let reference = "docker.io/library/busybox:latest";
let current = rootfs_cache_dir(reference).unwrap();
let mut keyed = Vec::from(reference.as_bytes());
keyed.push(0);
keyed.extend_from_slice(b"some-other-layout");
let other = Digest::new(&keyed).to_string();
assert_ne!(
current.file_name().unwrap().to_string_lossy(),
other,
"a different layout version must produce a different cache dir"
);
let unversioned = Digest::new(reference.as_bytes()).to_string();
assert_ne!(
current.file_name().unwrap().to_string_lossy(),
unversioned,
"the versioned key must differ from the historical un-versioned key"
);
}
#[test]
fn distinct_references_get_distinct_cache_dirs() {
let a = rootfs_cache_dir("busybox@sha256:aaaa").unwrap();
let b = rootfs_cache_dir("busybox@sha256:bbbb").unwrap();
assert_ne!(a, b);
let slash = rootfs_cache_dir("registry.example/a/b:latest").unwrap();
let colon = rootfs_cache_dir("registry.example/a:b/latest").unwrap();
assert_ne!(slash, colon);
}
#[test]
fn shell_quote_escapes_single_quotes() {
assert_eq!(shell_quote("a'b"), "'a'\\''b'");
assert_eq!(shell_quote("plain"), "'plain'");
}
#[test]
fn parse_env_splits_key_value_and_skips_blanks() {
let parsed = parse_env("USER=root\n\nPATH=/a:/b\r\nNOEQUALS\n");
assert_eq!(
parsed,
vec![
("USER".to_string(), "root".to_string()),
("PATH".to_string(), "/a:/b".to_string()),
]
);
}
#[test]
fn parse_workdir_treats_root_and_blank_as_none() {
assert_eq!(parse_workdir(""), None);
assert_eq!(parse_workdir(" \n"), None);
assert_eq!(parse_workdir("/"), None);
assert_eq!(parse_workdir("/srv/app\n"), Some("/srv/app".to_string()));
}
#[test]
fn config_location_with_empty_env_still_preserves_workdir() {
let tmp = tempfile::TempDir::new().unwrap();
let env = tmp.path().join("env");
let workdir = tmp.path().join("workdir");
std::fs::write(&env, "").unwrap();
std::fs::write(&workdir, "/srv/app\n").unwrap();
let config = read_image_config_files(&env, &workdir).unwrap().unwrap();
assert!(config.env.is_empty());
assert_eq!(config.workdir.as_deref(), Some("/srv/app"));
}
#[test]
fn resolve_in_rootfs_reroots_absolute_symlink_targets() {
let tmp = tempfile::TempDir::new().unwrap();
let rootfs = tmp.path();
std::fs::create_dir_all(rootfs.join("store")).unwrap();
std::fs::write(rootfs.join("store/bash"), b"#!/bin/true\n").unwrap();
std::fs::create_dir_all(rootfs.join("bin")).unwrap();
std::os::unix::fs::symlink("/store/bash", rootfs.join("bin/sh")).unwrap();
let resolved = resolve_in_rootfs(rootfs, Path::new("/bin/sh"));
assert_eq!(
resolved,
rootfs.join("store/bash"),
"absolute symlink target must be re-rooted onto the rootfs"
);
assert!(resolved.exists(), "resolved target should exist on host");
}
#[test]
fn resolve_in_rootfs_handles_relative_symlinks_and_bounded_parent() {
let tmp = tempfile::TempDir::new().unwrap();
let rootfs = tmp.path();
std::fs::create_dir_all(rootfs.join("usr/bin")).unwrap();
std::fs::write(rootfs.join("usr/bin/coreutils"), b"x").unwrap();
std::fs::create_dir_all(rootfs.join("bin")).unwrap();
std::os::unix::fs::symlink("../usr/bin/coreutils", rootfs.join("bin/ls")).unwrap();
assert_eq!(
resolve_in_rootfs(rootfs, Path::new("/bin/ls")),
rootfs.join("usr/bin/coreutils")
);
assert_eq!(
resolve_in_rootfs(rootfs, Path::new("/../../../store")),
rootfs.join("store")
);
}
}