use std::path::Path;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
pub const STAMP_FILE: &str = ".varve-export.json";
#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Clone)]
pub struct ExportStamp {
pub layer: String,
pub manifest_digest: String,
pub kind: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub content_digest: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub files: Vec<FileEntry>,
}
#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Clone)]
pub struct FileEntry {
pub path: String,
pub digest: String,
}
#[derive(Debug, thiserror::Error)]
pub enum ExportStampError {
#[error(
"no export stamp ({STAMP_FILE}) in {0} — not a varve export \
(or produced before stamping); re-run the export"
)]
Missing(String),
#[error("export stamp in {0} is malformed: {1}")]
Malformed(String, String),
#[error("i/o error on export stamp in {0}: {1}")]
Io(String, String),
#[error(
"cannot digest the export in {0}: {1} — the export is not a plain tree of \
files and symlinks, so varve will not vouch for it"
)]
Unhashable(String, String),
}
#[derive(Debug, PartialEq, Eq)]
pub enum ExportStatus {
Current,
Stale { stamped: String, current: String },
}
#[derive(Debug, PartialEq, Eq, Clone)]
pub enum ContentDrift {
Modified(String),
Missing(String),
Extra(String),
}
impl ContentDrift {
pub fn path(&self) -> &str {
match self {
ContentDrift::Modified(p) | ContentDrift::Missing(p) | ContentDrift::Extra(p) => p,
}
}
}
impl std::fmt::Display for ContentDrift {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
ContentDrift::Modified(p) => write!(f, "{p} was modified after export"),
ContentDrift::Missing(p) => write!(f, "{p} is missing (it was exported, now deleted)"),
ContentDrift::Extra(p) => {
write!(f, "{p} is an unexpected extra file (never exported)")
}
}
}
}
#[derive(Debug, PartialEq, Eq)]
pub enum ContentStatus {
Intact,
Unverifiable,
Drifted(ContentDrift),
}
pub fn tree_digest(files: &[FileEntry]) -> String {
let mut h = Sha256::new();
for f in files {
h.update(f.path.as_bytes());
h.update([0u8]);
h.update(f.digest.as_bytes());
h.update(b"\n");
}
format!("sha256:{}", hex::encode(h.finalize()))
}
pub fn scan_tree(dir: &Path) -> Result<Vec<FileEntry>, ExportStampError> {
let shown = dir.display().to_string();
let io = |e: std::io::Error| ExportStampError::Io(shown.clone(), e.to_string());
let mut out = Vec::new();
let mut stack = vec![(dir.to_path_buf(), String::new())];
while let Some((d, prefix)) = stack.pop() {
for entry in std::fs::read_dir(&d).map_err(io)? {
let entry = entry.map_err(io)?;
let name = entry.file_name().into_string().map_err(|n| {
ExportStampError::Unhashable(
shown.clone(),
format!("{:?} in {} is not valid UTF-8", n, d.display()),
)
})?;
let rel = if prefix.is_empty() {
name.clone()
} else {
format!("{prefix}/{name}")
};
let ft = entry.file_type().map_err(io)?;
if ft.is_symlink() {
let target = std::fs::read_link(entry.path()).map_err(io)?;
out.push(FileEntry {
path: rel,
digest: format!("link:{}", target.to_string_lossy()),
});
} else if ft.is_dir() {
stack.push((entry.path(), rel));
} else if ft.is_file() {
if rel == STAMP_FILE {
continue;
}
let mut h = Sha256::new();
let mut file = std::fs::File::open(entry.path()).map_err(io)?;
let mut buf = vec![0u8; 1 << 16];
loop {
let n = std::io::Read::read(&mut file, &mut buf).map_err(io)?;
if n == 0 {
break;
}
h.update(&buf[..n]);
}
out.push(FileEntry {
path: rel,
digest: format!("sha256:{}", hex::encode(h.finalize())),
});
} else {
return Err(ExportStampError::Unhashable(
shown.clone(),
format!("{rel} is not a regular file, directory or symlink"),
));
}
}
}
out.sort_by(|a, b| a.path.cmp(&b.path));
Ok(out)
}
pub fn stamp_for(
dir: &Path,
layer: &str,
manifest_digest: &str,
kind: &str,
) -> Result<ExportStamp, ExportStampError> {
let files = scan_tree(dir)?;
Ok(ExportStamp {
layer: layer.to_string(),
manifest_digest: manifest_digest.to_string(),
kind: kind.to_string(),
content_digest: Some(tree_digest(&files)),
files,
})
}
pub fn verify_content(dir: &Path, stamp: &ExportStamp) -> Result<ContentStatus, ExportStampError> {
let Some(recorded) = &stamp.content_digest else {
return Ok(ContentStatus::Unverifiable);
};
if tree_digest(&stamp.files) != *recorded {
return Err(ExportStampError::Malformed(
dir.display().to_string(),
"the recorded file list does not match its content digest".into(),
));
}
let now = scan_tree(dir)?;
let (mut a, mut b) = (stamp.files.iter().peekable(), now.iter().peekable());
loop {
match (a.peek(), b.peek()) {
(None, None) => return Ok(ContentStatus::Intact),
(Some(r), None) => {
return Ok(ContentStatus::Drifted(ContentDrift::Missing(
r.path.clone(),
)));
}
(None, Some(n)) => {
return Ok(ContentStatus::Drifted(ContentDrift::Extra(n.path.clone())));
}
(Some(r), Some(n)) => match r.path.cmp(&n.path) {
std::cmp::Ordering::Less => {
return Ok(ContentStatus::Drifted(ContentDrift::Missing(
r.path.clone(),
)));
}
std::cmp::Ordering::Greater => {
return Ok(ContentStatus::Drifted(ContentDrift::Extra(n.path.clone())));
}
std::cmp::Ordering::Equal => {
if r.digest != n.digest {
return Ok(ContentStatus::Drifted(ContentDrift::Modified(
r.path.clone(),
)));
}
a.next();
b.next();
}
},
}
}
}
pub fn write_stamp(dir: &Path, stamp: &ExportStamp) -> Result<(), ExportStampError> {
let path = dir.join(STAMP_FILE);
std::fs::create_dir_all(dir)
.map_err(|e| ExportStampError::Io(dir.display().to_string(), e.to_string()))?;
let json = serde_json::to_string_pretty(stamp)
.map_err(|e| ExportStampError::Malformed(dir.display().to_string(), e.to_string()))?;
std::fs::write(&path, json)
.map_err(|e| ExportStampError::Io(dir.display().to_string(), e.to_string()))
}
pub fn read_stamp(dir: &Path) -> Result<ExportStamp, ExportStampError> {
let path = dir.join(STAMP_FILE);
let bytes = match std::fs::read(&path) {
Ok(b) => b,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
return Err(ExportStampError::Missing(dir.display().to_string()));
}
Err(e) => {
return Err(ExportStampError::Io(
dir.display().to_string(),
e.to_string(),
));
}
};
serde_json::from_slice(&bytes)
.map_err(|e| ExportStampError::Malformed(dir.display().to_string(), e.to_string()))
}
pub fn status(stamp: &ExportStamp, current_manifest_digest: &str) -> ExportStatus {
if stamp.manifest_digest == current_manifest_digest {
ExportStatus::Current
} else {
ExportStatus::Stale {
stamped: stamp.manifest_digest.clone(),
current: current_manifest_digest.to_string(),
}
}
}
#[cfg(test)]
mod tests {
#[cfg(unix)]
fn premise_unavailable() -> bool {
use std::os::unix::fs::PermissionsExt;
let Ok(dir) = tempfile::tempdir() else {
return true;
};
let probe = dir.path().join("probe");
if std::fs::write(&probe, b"x").is_err() {
return true;
}
if std::fs::set_permissions(&probe, std::fs::Permissions::from_mode(0o000)).is_err() {
return true;
}
let readable = std::fs::read(&probe).is_ok();
let _ = std::fs::set_permissions(&probe, std::fs::Permissions::from_mode(0o644));
readable
}
use super::*;
fn sample() -> ExportStamp {
ExportStamp {
layer: "2026.08.0".into(),
manifest_digest: "sha256:aaaa".into(),
kind: "cargo".into(),
content_digest: None,
files: Vec::new(),
}
}
fn put(dir: &Path, rel: &str, bytes: &[u8]) {
let p = dir.join(rel);
std::fs::create_dir_all(p.parent().unwrap()).unwrap();
std::fs::write(p, bytes).unwrap();
}
fn stamped_export() -> (tempfile::TempDir, ExportStamp) {
let dir = tempfile::tempdir().unwrap();
put(dir.path(), "a.txt", b"alpha");
put(dir.path(), "m/b.txt", b"bravo");
put(dir.path(), "z.txt", b"zulu");
let stamp = stamp_for(dir.path(), "2026.08.0", "sha256:aaaa", "cargo").unwrap();
write_stamp(dir.path(), &stamp).unwrap();
(dir, stamp)
}
#[test]
fn write_then_read_round_trips() {
let dir = tempfile::tempdir().unwrap();
let s = sample();
write_stamp(dir.path(), &s).unwrap();
assert!(dir.path().join(STAMP_FILE).exists());
assert_eq!(read_stamp(dir.path()).unwrap(), s);
}
#[test]
fn read_missing_stamp_is_missing_error() {
let dir = tempfile::tempdir().unwrap();
match read_stamp(dir.path()) {
Err(ExportStampError::Missing(_)) => {}
other => panic!("expected Missing, got {other:?}"),
}
}
#[cfg(unix)]
#[test]
fn an_unreadable_stamp_is_an_io_error_not_a_missing_one() {
if premise_unavailable() {
eprintln!("skipping: this environment does not deny reads on mode 000");
return;
}
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join(STAMP_FILE);
std::fs::write(&path, b"{}").unwrap();
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o000)).unwrap();
let got = read_stamp(dir.path());
let _ = std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644));
match got {
Err(ExportStampError::Io(..)) => {}
other => panic!("expected Io for an unreadable stamp, got {other:?}"),
}
}
#[test]
fn read_malformed_stamp_is_malformed_error() {
let dir = tempfile::tempdir().unwrap();
std::fs::write(dir.path().join(STAMP_FILE), b"{not json").unwrap();
match read_stamp(dir.path()) {
Err(ExportStampError::Malformed(..)) => {}
other => panic!("expected Malformed, got {other:?}"),
}
}
#[test]
fn status_is_current_when_digests_match() {
assert_eq!(status(&sample(), "sha256:aaaa"), ExportStatus::Current);
}
#[test]
fn status_is_stale_when_digests_differ() {
assert_eq!(
status(&sample(), "sha256:bbbb"),
ExportStatus::Stale {
stamped: "sha256:aaaa".into(),
current: "sha256:bbbb".into(),
}
);
}
#[test]
fn the_stamp_records_a_sorted_per_file_list_and_one_digest_over_it() {
let (dir, stamp) = stamped_export();
let paths: Vec<&str> = stamp.files.iter().map(|f| f.path.as_str()).collect();
assert_eq!(
paths,
["a.txt", "m/b.txt", "z.txt"],
"sorted, `/`-separated"
);
assert_eq!(
stamp.files[0].digest,
"sha256:8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8"
);
assert_eq!(
stamp.content_digest.as_deref(),
Some(tree_digest(&stamp.files).as_str())
);
assert!(
stamp
.content_digest
.as_ref()
.unwrap()
.starts_with("sha256:")
);
assert_eq!(read_stamp(dir.path()).unwrap(), stamp);
assert!(!paths.contains(&STAMP_FILE));
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Intact
);
}
#[test]
fn the_tree_digest_depends_on_every_path_and_every_digest() {
let e = |p: &str, d: &str| FileEntry {
path: p.into(),
digest: d.into(),
};
let base = tree_digest(&[e("a", "sha256:1"), e("b", "sha256:2")]);
assert_ne!(base, tree_digest(&[e("a", "sha256:1"), e("b", "sha256:3")]));
assert_ne!(base, tree_digest(&[e("a", "sha256:1"), e("c", "sha256:2")]));
assert_ne!(base, tree_digest(&[e("a", "sha256:1")]));
assert_ne!(
tree_digest(&[e("ab", "sha256:1")]),
tree_digest(&[e("a", "bsha256:1")])
);
assert_ne!(
tree_digest(&[e("a", "sha256:1"), e("b", "sha256:2")]),
tree_digest(&[e("a", "sha256:1b"), e("", "sha256:2")])
);
assert_eq!(base, tree_digest(&[e("a", "sha256:1"), e("b", "sha256:2")]));
}
#[test]
fn one_flipped_byte_is_a_modified_path() {
let (dir, stamp) = stamped_export();
put(dir.path(), "m/b.txt", b"bravp");
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Drifted(ContentDrift::Modified("m/b.txt".into()))
);
}
#[test]
fn a_deleted_file_is_a_missing_path() {
for gone in ["a.txt", "m/b.txt", "z.txt"] {
let (dir, stamp) = stamped_export();
std::fs::remove_file(dir.path().join(gone)).unwrap();
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Drifted(ContentDrift::Missing(gone.into())),
"deleting {gone}"
);
}
}
#[test]
fn an_added_file_is_an_extra_path_wherever_it_sorts() {
for added in ["0-first.txt", "m/c.txt", "zz-last.txt"] {
let (dir, stamp) = stamped_export();
put(dir.path(), added, b"planted");
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Drifted(ContentDrift::Extra(added.into())),
"adding {added}"
);
}
}
#[test]
fn the_first_differing_path_in_sorted_order_is_the_one_named() {
let (dir, stamp) = stamped_export();
put(dir.path(), "z.txt", b"changed"); put(dir.path(), "m/b.txt", b"changed"); assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Drifted(ContentDrift::Modified("m/b.txt".into()))
);
std::fs::remove_file(dir.path().join("a.txt")).unwrap(); assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Drifted(ContentDrift::Missing("a.txt".into()))
);
}
#[test]
fn only_the_stamp_at_the_root_is_exempt_from_the_digest() {
let dir = tempfile::tempdir().unwrap();
put(dir.path(), "a.txt", b"x");
put(dir.path(), &format!("sub/{STAMP_FILE}"), b"{}");
let stamp = stamp_for(dir.path(), "l", "sha256:aaaa", "cargo").unwrap();
let paths: Vec<&str> = stamp.files.iter().map(|f| f.path.as_str()).collect();
assert_eq!(paths, ["a.txt", "sub/.varve-export.json"]);
write_stamp(dir.path(), &stamp).unwrap();
assert_eq!(scan_tree(dir.path()).unwrap(), stamp.files);
}
#[test]
fn a_stamp_without_a_content_digest_is_unverifiable_not_current() {
let dir = tempfile::tempdir().unwrap();
put(dir.path(), "a.txt", b"x");
assert_eq!(
verify_content(dir.path(), &sample()).unwrap(),
ContentStatus::Unverifiable
);
std::fs::write(
dir.path().join(STAMP_FILE),
br#"{"layer":"2026.08.0","manifest_digest":"sha256:aaaa","kind":"cargo"}"#,
)
.unwrap();
let old = read_stamp(dir.path()).unwrap();
assert_eq!(old.content_digest, None);
assert!(old.files.is_empty());
assert_eq!(
verify_content(dir.path(), &old).unwrap(),
ContentStatus::Unverifiable
);
}
#[test]
fn a_file_list_that_disagrees_with_its_own_digest_is_malformed() {
let (dir, mut stamp) = stamped_export();
stamp.files[0].digest = "sha256:00".into();
match verify_content(dir.path(), &stamp) {
Err(ExportStampError::Malformed(..)) => {}
other => panic!("expected Malformed, got {other:?}"),
}
}
#[test]
fn an_empty_export_verifies_and_gaining_a_file_is_caught() {
let dir = tempfile::tempdir().unwrap();
let stamp = stamp_for(dir.path(), "l", "sha256:aaaa", "cargo").unwrap();
assert!(stamp.files.is_empty());
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Intact
);
put(dir.path(), "x", b"1");
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Drifted(ContentDrift::Extra("x".into()))
);
}
#[test]
fn a_drift_names_its_path_and_says_how() {
let m = ContentDrift::Modified("a/b".into());
let x = ContentDrift::Missing("a/b".into());
let e = ContentDrift::Extra("a/b".into());
for d in [&m, &x, &e] {
assert_eq!(d.path(), "a/b");
}
assert!(m.to_string().contains("modified"));
assert!(x.to_string().contains("missing"));
assert!(e.to_string().contains("unexpected"));
}
#[cfg(unix)]
#[test]
fn a_symlink_is_recorded_by_target_and_never_followed() {
let outside = tempfile::tempdir().unwrap();
put(outside.path(), "secret", b"outside the export");
let dir = tempfile::tempdir().unwrap();
put(dir.path(), "real.txt", b"x");
std::os::unix::fs::symlink(outside.path().join("secret"), dir.path().join("link")).unwrap();
std::os::unix::fs::symlink(outside.path(), dir.path().join("dirlink")).unwrap();
let stamp = stamp_for(dir.path(), "l", "sha256:aaaa", "sdk").unwrap();
let by_path = |p: &str| stamp.files.iter().find(|f| f.path == p).unwrap();
assert_eq!(
by_path("link").digest,
format!("link:{}", outside.path().join("secret").display())
);
assert!(by_path("dirlink").digest.starts_with("link:"));
assert!(
!stamp.files.iter().any(|f| f.path.starts_with("dirlink/")),
"walked through a symlink"
);
put(outside.path(), "secret", b"changed out there");
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Intact
);
std::fs::remove_file(dir.path().join("link")).unwrap();
std::os::unix::fs::symlink("/etc/hosts", dir.path().join("link")).unwrap();
assert_eq!(
verify_content(dir.path(), &stamp).unwrap(),
ContentStatus::Drifted(ContentDrift::Modified("link".into()))
);
}
#[cfg(unix)]
#[test]
fn a_special_file_is_refused_rather_than_skipped() {
let dir = tempfile::tempdir().unwrap();
put(dir.path(), "a.txt", b"x");
let made = std::process::Command::new("mkfifo")
.arg(dir.path().join("pipe"))
.status();
if !matches!(made, Ok(s) if s.success()) {
eprintln!("skipping: mkfifo is unavailable here");
return;
}
match stamp_for(dir.path(), "l", "sha256:aaaa", "cargo") {
Err(ExportStampError::Unhashable(_, why)) => assert!(why.contains("pipe"), "{why}"),
other => panic!("expected Unhashable, got {other:?}"),
}
}
}