From 83843c31c699eac2e8885bac2a3f38a3948203fb Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:21:30 +0800 Subject: [PATCH 1/8] fix(sandbox): one copy of an image per machine at a time, and room checked before anything exists A copy of an image resolved its Docker Id and then raced every other copy of that image: "another copy is running" meant only that the staged part had grown in the last 30 s (`image_artifact::RECEIVING`), a waiter went ahead anyway after 10 minutes (`image_load::WAIT`), and both copies shared the export container `layerfs-export-` and the part `.recv-.part`, so a second `write` at offset 0 truncated the first one's bytes. - `ImageLock`: one exclusive `flock` per home, machine and image, at `/run/image-lock//.lock`, held for the whole copy, with the owner recorded beside it (`pid`, `pid_start`, `pid_boot`, machine, image, since). The lock is the exclusion and the record is only what a waiter reports: the kernel releases a dead owner's lock, so the next copy takes it over and resumes the part, and a record whose pid was reused holds nothing. No deadline: a live owner is waited for, with `{phase: "lock", waiting: "lock", holder}` each second. - Capacity runs before the first effect: the check now precedes the export container, so a refusal leaves no container, no staged byte and no cache folder; the container's `SizeRootFs` only refines the progress estimate. `NoSpace {need, free}` becomes `Capacity {needed, free, where}`; `needed` counts the bytes a resumed copy already staged once, and `where` names the filesystem the probe measured (`probe`'s new `root`). - The export container is one per image and machine (`layerfs-export--`), so two machines copying the same image neither share nor remove each other's container. - `Target` carries the home and the machine whose cache it fills (`Target::local`, `Target::worker`), so an in-process Linux load takes the same lock as a worker load. - `image_artifact`: `probe` drops `receiving` (the 30 s mtime test) and adds `root`. Tests: `tests/lp176_image_lock.rs` (a second copy of the same target waits and then reuses, another machine's copy is not locked out, a dead owner is taken over and a reused pid holds nothing, a short machine is refused with no effect, a resumed copy needs only what it has not staged, an in-process copy takes the same lock) and `tests/image_copy.rs` moved to `Capacity`/`needed`/`where` and to the probe's `root`. Production LOC: 169,640 -> 169,779 (delta +139) core 39,795 -> 39,795 (0) engine 75,102 -> 75,102 (0) control 48,397 -> 48,536 (+139) layerfs-sandbox +139 api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on 4a8efe63b and the committed tree --- .../layerfs-sandbox/src/image_artifact.rs | 21 +- .../crates/layerfs-sandbox/src/image_load.rs | 292 ++++++++-- control/crates/layerfs-sandbox/src/route.rs | 6 +- .../layerfs-sandbox/tests/image_copy.rs | 57 +- .../layerfs-sandbox/tests/lp176_image_lock.rs | 551 ++++++++++++++++++ docs/architecture/api/sdk/machine.md | 42 +- docs/architecture/api/sdk/sandbox.md | 2 +- docs/architecture/control/home/README.md | 1 + docs/versioned/2.0.0/calls.md | 15 +- 9 files changed, 888 insertions(+), 99 deletions(-) create mode 100644 control/crates/layerfs-sandbox/tests/lp176_image_lock.rs diff --git a/control/crates/layerfs-sandbox/src/image_artifact.rs b/control/crates/layerfs-sandbox/src/image_artifact.rs index 24cc64980..80b02d5fb 100644 --- a/control/crates/layerfs-sandbox/src/image_artifact.rs +++ b/control/crates/layerfs-sandbox/src/image_artifact.rs @@ -7,7 +7,9 @@ //! size, architecture, source, config and the time a Sandbox last used it. //! The host keeps nothing; Docker is the source. A staged file is resumed //! from its length when its bytes are a prefix of the next export -//! (`probe`'s `prefix_sha256`). +//! (`probe`'s `prefix_sha256`). Whether another copy is still writing it is +//! the copy's own lock in the home (`image_load::ImageLock`), never the +//! staged file's age. use crate::deploy::{self, Side}; use crate::host::Deploy; use layerfs_bridge::control::{SdkRefusal, SdkValue}; @@ -20,13 +22,9 @@ use std::fs::{self, OpenOptions}; use std::io::{Read, Seek, SeekFrom, Write}; use std::os::unix::fs::OpenOptionsExt; use std::path::{Path, PathBuf}; -use std::time::{Duration, SystemTime}; /// The largest frame of image bytes one `write` carries. pub const CHUNK: usize = 1 << 20; -/// How recently a staged file must have grown for `probe` to say another -/// caller is still sending it. -const RECEIVING: Duration = Duration::from_secs(30); /// Whether a value is a full lowercase digest, `sha256:<64 hex>`. pub fn digest(value: &str) -> bool { @@ -320,7 +318,8 @@ pub fn step(side: &Side<'_>, args: &SdkValue) -> Outcome { /// Whether this machine holds image `id` (unpacked, or in the archive its /// Sandboxes read), or which image a sidecar names `ref` by; its -/// architecture, free bytes, and how much of `id` is staged. +/// architecture, the image cache measured for free bytes and where it is, +/// and how much of `id` is staged. fn probe(side: &Side<'_>, cache: &Path, id: Option<&str>, args: &SdkValue) -> Outcome { let mut out = vec![ ("architecture".to_owned(), SdkValue::text(architecture())), @@ -328,6 +327,10 @@ fn probe(side: &Side<'_>, cache: &Path, id: Option<&str>, args: &SdkValue) -> Ou "free".to_owned(), free(cache).map_or(SdkValue::Null, |n| SdkValue::Int(n as i64)), ), + ( + "root".to_owned(), + SdkValue::text(cache.to_string_lossy().as_ref()), + ), ]; let id = match (id, args.get_text("ref")) { (Some(id), _) => Some(id.to_owned()), @@ -354,17 +357,11 @@ fn probe(side: &Side<'_>, cache: &Path, id: Option<&str>, args: &SdkValue) -> Ou let staged = part(cache, hex); if let Ok(meta) = fs::symlink_metadata(&staged) { if meta.file_type().is_file() { - let recent = meta - .modified() - .ok() - .and_then(|m| SystemTime::now().duration_since(m).ok()) - .is_some_and(|age| age < RECEIVING); out.push(("offset".to_owned(), SdkValue::Int(meta.len() as i64))); out.push(( "prefix_sha256".to_owned(), SdkValue::text(sha256_file(&staged)?), )); - out.push(("receiving".to_owned(), SdkValue::Bool(recent))); } } Ok(SdkValue::Map(out)) diff --git a/control/crates/layerfs-sandbox/src/image_load.rs b/control/crates/layerfs-sandbox/src/image_load.rs index 605480798..0a076c7eb 100644 --- a/control/crates/layerfs-sandbox/src/image_load.rs +++ b/control/crates/layerfs-sandbox/src/image_load.rs @@ -4,8 +4,11 @@ //! exported from the host's Docker as one flat root filesystem tar //! ([`crate::image_tar`]), sent in 1 MiB frames and unpacked once there //! ([`crate::image_artifact`]). The machine is asked first, so an image it -//! holds needs neither Docker nor a byte sent. Progress phases are -//! `inspect`, `export`, `send` (`done`/`total` bytes) and `unpack`. +//! holds needs neither Docker nor a byte sent. One copy per image and machine +//! at a time: the second one waits in [`ImageLock`], and a copy whose owner +//! died is taken over at once (#175 R01). Progress phases are `inspect`, +//! `lock` (`waiting: "lock"` while another copy holds it), `export`, `send` +//! (`done`/`total` bytes) and `unpack`. use crate::deploy::Side; use crate::docker::{self, Docker, Failure, Inspected}; use crate::image_artifact::{self as cache, CHUNK}; @@ -13,36 +16,80 @@ use crate::image_tar::Filtered; use crate::images::{refused_with, stopped}; use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::events::Events; +use layerfs_home::home::{self, private_dir, read_record, write_record}; use layerfs_home::outcome::{failed, refused, Outcome}; +use layerfs_home::process; use layerfs_store::place::Worker; use sha2::{Digest, Sha256}; +use std::fs::{File, OpenOptions}; use std::io::Read; -use std::path::Path; +use std::os::unix::fs::OpenOptionsExt; +use std::path::{Path, PathBuf}; use std::time::{Duration, Instant}; type Result = std::result::Result; -/// How long a copy waits for another caller's copy of the same image. -const WAIT: Duration = Duration::from_secs(600); /// A leftover export container older than this is removed by the next copy. const STALE_SECS: u64 = 3600; +/// How often a waiting copy looks at the lock again: one look every 200 ms +/// reacts to a released or taken-over lock, and to a killed waiter, at once. +const LOCK_POLL: Duration = Duration::from_millis(200); +/// How often a waiting copy says so: the longest silence of a wait is this. +const WAIT_REPORT: Duration = Duration::from_secs(1); -/// The side an image is copied to. -pub enum Target<'a> { - /// A machine's worker. +/// The side an image is copied to: the image cache of `machine`, reached +/// through its worker or in this process (native Linux), and the `home` that +/// keeps the copy's lock. +pub struct Target<'a> { + home: &'a Path, + machine: &'a str, + place: Place<'a>, +} + +/// Where the bytes are written. +pub enum Place<'a> { + /// This process, whose root is the home at the path. + Local, + /// The machine's worker. Worker(&'a mut Worker), - /// This process (native Linux), with the home at the path. - Local(&'a Path), } -impl Target<'_> { +impl<'a> Target<'a> { + /// A copy into this process's own image cache (`native` on Linux). + pub fn local(home: &'a Path, machine: &'a str) -> Self { + Target { + home, + machine, + place: Place::Local, + } + } + + /// A copy into `machine`'s image cache through its worker. + pub fn worker(home: &'a Path, machine: &'a str, worker: &'a mut Worker) -> Self { + Target { + home, + machine, + place: Place::Worker(worker), + } + } + + /// The home that keeps this copy's lock. + pub fn home(&self) -> &Path { + self.home + } + + /// The machine whose image cache the copy fills. + pub fn machine(&self) -> &str { + self.machine + } + /// One `image.artifact` step there. fn step(&mut self, args: SdkValue) -> Outcome { - match self { - Target::Worker(worker) => worker + match &mut self.place { + Place::Worker(worker) => worker .attempt("image.artifact", args, &mut |_| {}) .map_err(|unreached| stopped(unreached.0))?, - Target::Local(home) => cache::step(&Side::Home(home), &args), + Place::Local => cache::step(&Side::Home(self.home), &args), } } @@ -173,18 +220,25 @@ pub fn load( ]), )); } - // another caller is sending the same image: wait for it (bounded) - let start = Instant::now(); - while !held(&probe) && probe.get_bool("receiving") && start.elapsed() < WAIT { - std::thread::sleep(Duration::from_secs(1)); - probe = target.probe(Some(id), None, archive)?; + if held(&probe) { + let size = kept(&probe).or(Some(inspected.size)); + return Ok(reused(id, refs.clone(), size)); } + // one copy at a time of this image on this machine (#175 R01): a second + // copy waits here, and takes over at once from one whose owner died + let machine = target.machine().to_owned(); + let _lock = ImageLock::take(target.home(), &machine, id, events)?; + // under the lock: the copy that held it may have published the image + probe = target.probe(Some(id), None, archive)?; if held(&probe) { let size = kept(&probe).or(Some(inspected.size)); return Ok(reused(id, refs.clone(), size)); } - let hex = &id["sha256:".len()..]; - let container = format!("layerfs-export-{hex}"); + // capacity before the first effect on the machine (#175 R03): no export + // container, no staged byte and no cache folder; a resumed copy counts + // the bytes it already staged once + capacity(&machine, &probe, id, inspected.size)?; + let container = container(&machine, id); phase(events, "export", None); remove_stale(docker, &container); created(docker, &container, id)?; @@ -203,23 +257,9 @@ pub fn load( .ok() .and_then(|out| out.trim().parse::().ok()) .filter(|n| *n > 0); - // the larger of what the layers unpack to and the container's root - let size = unpacked.unwrap_or(0).max(inspected.size); - let estimate = Some(size).filter(|n| *n > 0); - let free = probe.get_int("free").map(|n| n.max(0) as u64); - if let Some(free) = free { - let need = docker::need(size); - if need > free { - return Err(refused_with( - "NoSpace", - format!("copying image {image} needs {need} bytes on the machine; {free} are free"), - SdkValue::map([ - ("need", SdkValue::Int(need as i64)), - ("free", SdkValue::Int(free as i64)), - ]), - )); - } - } + // the container's root refines the progress estimate only: the capacity + // decision above is taken before anything is created + let estimate = Some(unpacked.unwrap_or(0).max(inspected.size)).filter(|n| *n > 0); let staged = probe.get_int("offset").unwrap_or(0).max(0) as u64; let prefix = probe.get_text("prefix_sha256").map(str::to_owned); let (sent, sha256) = match send( @@ -267,6 +307,164 @@ fn reused(id: &str, refs: Vec, size: Option) -> Loaded { } } +/// The lock of one image on one machine, in the home: +/// `/run/image-lock//.lock`, an exclusive `flock` held +/// for the whole copy, with its owner recorded beside it in `.json` +/// (pid, its kernel start time and boot, the machine and the image; #175 +/// R01 and #176's intent). +/// +/// The lock is the exclusion and the record is not: a waiter reads the record +/// only to say whom it waits for. An owner that dies releases the kernel +/// lock, so the next copy takes it over and resumes the staged part; a record +/// whose pid another process now holds does not keep the lock, because the +/// lock is not that process's. There is no deadline: a live owner is waited +/// for as long as it lives and the wait says `waiting: "lock"` every second. +/// Interrupting a waiting copy today means killing it, which leaves nothing +/// to undo — a released kernel lock and at most its record, which the next +/// copy replaces; a wait a shared Cancel can end is X01's, not this card's. +pub struct ImageLock { + file: File, + record: PathBuf, +} + +impl Drop for ImageLock { + fn drop(&mut self) { + // the copy is over; a copy that died left its record behind for the + // next owner to replace + let _ = std::fs::remove_file(&self.record); + layerfs_home::home::flock::unlock(&self.file); + } +} + +impl ImageLock { + /// The folder of machine `machine`'s image locks in `home`. + pub fn dir(home: &Path, machine: &str) -> PathBuf { + home.join("run").join("image-lock").join(machine) + } + + /// The lock file of `hex` on `machine`. + pub fn path(home: &Path, machine: &str, hex: &str) -> PathBuf { + Self::dir(home, machine).join(format!("{hex}.lock")) + } + + /// The owner record beside it. + pub fn record_path(home: &Path, machine: &str, hex: &str) -> PathBuf { + Self::dir(home, machine).join(format!("{hex}.json")) + } + + /// Takes the lock of image `id` on `machine`, waiting while a live copy + /// holds it and recording this copy as the owner. `events` say + /// `{phase: "lock", waiting: "lock", holder}` once a second meanwhile. + pub fn take(home: &Path, machine: &str, id: &str, events: &mut Events<'_>) -> Result { + let hex = hex_of(id).ok_or_else(|| refused("InvalidInput", "image id"))?; + let dir = Self::dir(home, machine); + private_dir(&dir)?; + let file = OpenOptions::new() + .read(true) + .write(true) + .create(true) + .truncate(false) + .mode(0o600) + .custom_flags(libc::O_NOFOLLOW) + .open(Self::path(home, machine, hex)) + .map_err(failed)?; + let mut reported: Option = None; + loop { + if layerfs_home::home::flock::try_lock(&file, true).map_err(failed)? { + break; + } + if reported.is_none_or(|at| at.elapsed() >= WAIT_REPORT) { + let record = Self::record_path(home, machine, hex); + events.progress(SdkValue::map([ + ("phase", SdkValue::text("lock")), + ("waiting", SdkValue::text("lock")), + ( + "holder", + read_record(&record) + .ok() + .flatten() + .unwrap_or(SdkValue::Null), + ), + ])); + reported = Some(Instant::now()); + } + std::thread::sleep(LOCK_POLL); + } + let lock = Self { + file, + record: Self::record_path(home, machine, hex), + }; + lock.record(machine, id)?; + Ok(lock) + } + + /// Records this copy as the lock's owner before it does anything else. + fn record(&self, machine: &str, id: &str) -> Result<()> { + let now = home::now_ms(); + let mut fields = process::identity(); + fields.extend([ + ("machine", SdkValue::text(machine)), + ("image", SdkValue::text(id)), + ("since", SdkValue::text(cache::utc(now))), + ("since_ms", SdkValue::Int(now)), + ]); + let record = SdkValue::Map( + fields + .into_iter() + .map(|(name, value)| (name.to_owned(), value)) + .collect(), + ); + write_record(&self.record, &record) + } +} + +/// The export container of image `id` for `machine`: one per image and +/// machine, so two machines copying the same image neither share nor remove +/// each other's container. Nothing runs in it. +fn container(machine: &str, id: &str) -> String { + format!("layerfs-export-{machine}-{}", &id["sha256:".len()..]) +} + +/// `id`'s 64 hex digits, the name of its files under the cache and the lock. +fn hex_of(id: &str) -> Option<&str> { + cache::digest(id).then(|| &id["sha256:".len()..]) +} + +/// Refuses `Capacity` before the copy creates anything on the machine or in +/// the home (#175 R03): `needed` is what the copy still has to find room for +/// — the bytes already staged for a resumed copy are on the machine's +/// filesystem and are counted once — `free` is what it has, and `where` names +/// the filesystem that was measured. +fn capacity(machine: &str, probe: &SdkValue, id: &str, size: u64) -> Result<()> { + // a machine that does not say how much room it has cannot be refused + let Some(free) = probe.get_int("free").map(|n| n.max(0) as u64) else { + return Ok(()); + }; + let staged = probe.get_int("offset").unwrap_or(0).max(0) as u64; + let needed = docker::need(size).saturating_sub(staged); + if needed <= free { + return Ok(()); + } + let at = probe.get_text("root").unwrap_or(machine); + let staged_note = if staged > 0 { + format!(" ({staged} bytes are already staged and are not counted again)") + } else { + String::new() + }; + let int = |n: u64| SdkValue::Int(n.min(i64::MAX as u64) as i64); + Err(refused_with( + "Capacity", + format!( + "machine {machine} needs {needed} more bytes in {at} to copy image {id}; {free} are free{staged_note}" + ), + SdkValue::map([ + ("needed", int(needed)), + ("free", int(free)), + ("where", SdkValue::text(at)), + ]), + )) +} + /// The export container `name` of image `id`: the one a failed copy kept /// (so a retry exports identical bytes), else a new one. Nothing runs in it. fn created(docker: &Docker, name: &str, id: &str) -> Result<()> { @@ -447,10 +645,20 @@ pub fn machine_load( let docker = Docker::of(home)?; let archive = choice.archive.as_deref(); let loaded = match &mut executor { - Executor::Local => load(&docker, events, &mut Target::Local(home), archive, image)?, - Executor::Worker(worker) => { - load(&docker, events, &mut Target::Worker(worker), archive, image)? - } + Executor::Local => load( + &docker, + events, + &mut Target::local(home, machine), + archive, + image, + )?, + Executor::Worker(worker) => load( + &docker, + events, + &mut Target::worker(home, machine, worker), + archive, + image, + )?, }; Ok(loaded.to_value()) } diff --git a/control/crates/layerfs-sandbox/src/route.rs b/control/crates/layerfs-sandbox/src/route.rs index 33799ecdc..2757a9759 100644 --- a/control/crates/layerfs-sandbox/src/route.rs +++ b/control/crates/layerfs-sandbox/src/route.rs @@ -307,8 +307,10 @@ fn host_op( let archive = deploy::choose(&home, machine, None)?.archive; let docker = crate::docker::Docker::of(&home)?; let mut target = match &mut executor { - Executor::Local => crate::image_load::Target::Local(&home), - Executor::Worker(worker) => crate::image_load::Target::Worker(worker), + Executor::Local => crate::image_load::Target::local(&home, machine), + Executor::Worker(worker) => { + crate::image_load::Target::worker(&home, machine, worker) + } }; let loaded = crate::image_load::load(&docker, events, &mut target, archive.as_deref(), &named)?; diff --git a/control/crates/layerfs-sandbox/tests/image_copy.rs b/control/crates/layerfs-sandbox/tests/image_copy.rs index 42434ee1d..0e7bc6157 100644 --- a/control/crates/layerfs-sandbox/tests/image_copy.rs +++ b/control/crates/layerfs-sandbox/tests/image_copy.rs @@ -61,7 +61,7 @@ fn run( let out = load( &standin.docker(), &mut events, - &mut Target::Local(home), + &mut Target::local(home, "native"), None, image, ); @@ -141,7 +141,7 @@ fn a_reference_is_copied_once_then_reused_with_nothing_sent() { let found = load( &none, &mut Events::new(&mut sink), - &mut Target::Local(&home), + &mut Target::local(&home, "native"), None, "demo/pg:17", ) @@ -172,20 +172,39 @@ fn refusals_carry_their_detail() { let error = load( &none, &mut Events::new(&mut sink), - &mut Target::Local(&home), + &mut Target::local(&home, "native"), None, "demo/pg:17", ) .unwrap_err(); assert_eq!(error.code, "Unavailable"); assert_eq!(error.detail.get_text("what"), Some("docker")); - // larger than twice what the machine has free - standin.set_rootfs_size(u64::MAX / 8); + // larger than twice what the machine has free: refused before anything + // exists, and the container's root is not what decides it + standin.image(ID, &["demo/pg:17"], ("linux", architecture()), u64::MAX / 8); let error = run(&standin, &home, "demo/pg:17").0.unwrap_err(); - assert_eq!(error.code, "NoSpace"); - let need = error.detail.get_int("need").unwrap(); + assert_eq!(error.code, "Capacity"); + let needed = error.detail.get_int("needed").unwrap(); let free = error.detail.get_int("free").unwrap(); - assert!(need > free, "{need} {free}"); + assert!(needed > free, "{needed} {free}"); + assert_eq!( + needed as u64, + layerfs_sandbox::docker::need(u64::MAX / 8), + "a fresh copy needs the whole unpacked size" + ); + assert_eq!( + error.detail.get_text("where"), + Some(cache::cache(&home).to_string_lossy().as_ref()), + "the refusal names the filesystem it measured" + ); + assert!( + !standin.dir.join("containers").exists(), + "no export container is created" + ); + assert_eq!(standin.exports(), 0, "no byte is exported"); + assert!(!cache::cache(&home) + .join(format!(".recv-{HEX}.part")) + .exists()); assert!(!cache::cache(&home).join(format!("{HEX}.2")).exists()); } @@ -197,9 +216,9 @@ fn need_counts_what_the_layers_unpack_to() { let layers = [u64::MAX / 32, 0, u64::MAX / 32]; standin.layers(ID, &layers); let error = run(&standin, &home, "demo/pg:17").0.unwrap_err(); - assert_eq!(error.code, "NoSpace", "{}", error.message); - let need = layerfs_sandbox::docker::need(layers.iter().sum()); - assert_eq!(error.detail.get_int("need"), Some(need as i64)); + assert_eq!(error.code, "Capacity", "{}", error.message); + let needed = layerfs_sandbox::docker::need(layers.iter().sum()); + assert_eq!(error.detail.get_int("needed"), Some(needed as i64)); } #[test] @@ -254,14 +273,8 @@ fn a_staged_prefix_is_resumed_and_a_mismatched_one_restarted() { vec![9u8; 1024] }; cache::write(&cache::cache(&home), HEX, 0, &staged).unwrap(); - // left by a copy that stopped a minute ago, not one still sending - let part = cache::cache(&home).join(format!(".recv-{HEX}.part")); - fs::File::options() - .write(true) - .open(&part) - .unwrap() - .set_modified(std::time::SystemTime::now() - std::time::Duration::from_secs(60)) - .unwrap(); + // left by a copy that is not running: no lock holds it, so its bytes + // are resumed whatever their age let (out, run) = run(&standin, &home, "demo/pg:17"); out.unwrap(); let first = named(&run, "send")[0].get_int("done").unwrap(); @@ -289,7 +302,11 @@ fn frames_out_of_order_are_refused_and_publish_checks_the_bytes() { ])) .unwrap(); assert_eq!(probe.get_int("offset"), Some(3)); - assert!(probe.get_bool("receiving")); + assert_eq!( + probe.get_text("root"), + Some(cache::cache(&home).to_string_lossy().as_ref()), + "a probe says which filesystem its free bytes are" + ); assert!(!probe.get_bool("present")); let wrong = step(SdkValue::map([ ("step", SdkValue::text("publish")), diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_lock.rs b/control/crates/layerfs-sandbox/tests/lp176_image_lock.rs new file mode 100644 index 000000000..41a2e6405 --- /dev/null +++ b/control/crates/layerfs-sandbox/tests/lp176_image_lock.rs @@ -0,0 +1,551 @@ +//! One copy of an image per machine at a time, and the capacity check that +//! runs before the copy touches anything (layerfs-project#175 R01, R03): +//! a second copy of the same image on the same machine waits on the home's +//! lock and then reuses what the first published; another machine's copy of +//! the same image is another lock; a copy whose owner died is taken over at +//! once and a record naming a reused pid holds nothing; a machine short of +//! room is refused `Capacity` before a container, a staged byte or a cache +//! folder exists, and a resumed copy counts the bytes it already staged once. +//! +//! The Docker here is a stand-in shell script (no Engine, no root); one test +//! holds its `docker export` until the test lets it go, so a second copy is +//! really waiting while the first is really sending. +#[allow(dead_code)] +#[path = "../../layerfs-sandbox-backend/tests/support/image.rs"] +mod fixture; +use fixture::{Scratch, Tar}; +use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_home::events::Events; +use layerfs_home::home; +use layerfs_sandbox::docker::{self, Docker}; +use layerfs_sandbox::image_artifact::{self as cache, architecture}; +use layerfs_sandbox::image_load::{load, ImageLock, Loaded, Target}; +use layerfs_sandbox::image_tar::Filtered; +use std::fs; +use std::io::Read; +use std::os::unix::fs::PermissionsExt; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +const ID: &str = "sha256:4444444444444444444444444444444444444444444444444444444444444444"; +const HEX: &str = "4444444444444444444444444444444444444444444444444444444444444444"; + +/// A stand-in `docker` CLI over files in its own directory: the answers +/// `image.artifact`'s copy asks for, and an `export` that waits for `go` +/// while `hold` exists, so a test decides when a copy finishes. +const SCRIPT: &str = r#"#!/bin/sh +D="$(dirname "$0")" +if [ "$1" = "-H" ]; then shift 2; fi +key() { printf '%s' "$1" | tr '/:' '__'; } +case "$1 $2" in + "image inspect") + shift 4; missing=0 + for ref in "$@"; do + f="$D/images/$(key "$ref").json" + if [ -f "$f" ]; then cat "$f"; echo; else echo "Error: No such image: $ref" >&2; missing=1; fi + done + exit $missing ;; + "image ls") cat "$D/ls.txt" 2>/dev/null; exit 0 ;; + "container inspect") + if [ "$3" = "--size" ]; then cat "$D/rootfs_size"; exit 0; fi + if [ -f "$D/containers/$5" ]; then echo id; exit 0; fi + echo "Error: No such object: $5" >&2; exit 1 ;; +esac +case "$1" in + create) + mkdir -p "$D/containers" + echo x >> "$D/creates" + while [ $# -gt 0 ]; do + case "$1" in + --name) name="$2"; shift 2 ;; + --label|--network|--entrypoint) shift 2 ;; + *) shift ;; + esac + done + : > "$D/containers/$name" + echo id ;; + export) + echo x >> "$D/starts" + if [ -f "$D/hold" ]; then + while [ ! -f "$D/go" ]; do sleep 0.02; done + fi + echo x >> "$D/exports" + cat "$D/export.tar" ;; + history) + f="$D/history/$(key "$5")" + if [ -f "$f" ]; then cat "$f"; exit 0; fi + echo "Error: No such image" >&2; exit 1 ;; + rm) + shift + if [ "$1" = "-f" ]; then shift; fi + rm -f "$D/containers/$1" ;; + ps) ;; + *) echo "unexpected: $*" >&2; exit 2 ;; +esac +"#; + +/// The stand-in Docker's directory. +struct Standin { + dir: PathBuf, +} + +impl Standin { + fn new(dir: &Path) -> Self { + fs::create_dir_all(dir.join("images")).unwrap(); + let program = dir.join("docker"); + fs::write(&program, SCRIPT).unwrap(); + fs::set_permissions(&program, fs::Permissions::from_mode(0o755)).unwrap(); + fs::write(dir.join("rootfs_size"), "0\n").unwrap(); + Self { + dir: dir.to_owned(), + } + } + + fn docker(&self) -> Docker { + Docker::at(Some(self.dir.join("docker")), None) + } + + /// The image `id` Docker holds as `refs`, of `size` bytes. + fn image(&self, id: &str, refs: &[&str], architecture: &str, size: u64) { + let tags = refs + .iter() + .map(|r| format!("\"{r}\"")) + .collect::>() + .join(","); + let json = format!( + r#"{{"Id":"{id}","RepoTags":[{tags}],"Os":"linux","Architecture":"{architecture}","Size":{size},"Config":{{"Env":["PATH=/usr/bin"]}}}}"# + ); + for reference in refs.iter().copied().chain([id]) { + let key = reference.replace(['/', ':'], "_"); + fs::write(self.dir.join("images").join(format!("{key}.json")), &json).unwrap(); + } + let mut ls = fs::read_to_string(self.dir.join("ls.txt")).unwrap_or_default(); + for reference in refs { + ls.push_str(reference); + ls.push('\n'); + } + fs::write(self.dir.join("ls.txt"), ls).unwrap(); + } + + /// `docker export` answers these bytes. + fn export(&self, bytes: &[u8]) { + fs::write(self.dir.join("export.tar"), bytes).unwrap(); + } + + /// `docker export` waits for [`Standin::release`] before answering. + fn hold(&self) { + fs::write(self.dir.join("hold"), b"").unwrap(); + } + + fn release(&self) { + fs::write(self.dir.join("go"), b"").unwrap(); + } + + fn count(&self, name: &str) -> usize { + fs::read_to_string(self.dir.join(name)) + .map(|text| text.lines().count()) + .unwrap_or(0) + } + + /// How many `docker create` calls ran. + fn creates(&self) -> usize { + self.count("creates") + } + + /// How many `docker export` calls started. + fn starts(&self) -> usize { + self.count("starts") + } + + /// How many `docker export` calls answered every byte. + fn exports(&self) -> usize { + self.count("exports") + } + + /// The export containers Docker holds here now. + fn containers(&self) -> Vec { + let mut names: Vec = fs::read_dir(self.dir.join("containers")) + .map(|entries| { + entries + .filter_map(|entry| entry.ok()) + .filter_map(|entry| entry.file_name().into_string().ok()) + .collect() + }) + .unwrap_or_default(); + names.sort(); + names + } +} + +/// One tar of a small root filesystem, as `docker export` writes it. +fn export() -> Vec { + Tar::new() + .directory("etc/", 0o755) + .file("etc/app", 0o644, b"hello\n") + .file("usr/bin/app", 0o755, &vec![7u8; 2048]) + .finish() +} + +/// A tar of 4 MiB, so a test can stage megabytes of it: the staged bytes of a +/// resumed copy have to cover a gap far above the few kilobytes another test +/// writes to the same filesystem while this one runs. +fn big_export() -> Vec { + Tar::new() + .directory("data/", 0o755) + .file("data/blob", 0o644, &vec![3u8; 4 << 20]) + .finish() +} + +/// The same bytes after [`Filtered`] dropped the init layer's files. +fn filtered(bytes: &[u8]) -> Vec { + let mut out = Vec::new(); + Filtered::new(bytes).read_to_end(&mut out).unwrap(); + out +} + +/// A copy into `machine`'s cache, in this process, recording its events. +fn copy( + docker: &Docker, + at_home: &Path, + machine: &str, + image: &str, + events: &Arc>>, +) -> Result { + let seen = events.clone(); + let mut sink = move |event: SdkValue| seen.lock().unwrap().push(event); + load( + docker, + &mut Events::new(&mut sink), + &mut Target::local(at_home, machine), + None, + image, + ) +} + +/// The lock's events of phase `phase` (its `progress` values). +fn phases(events: &Arc>>, phase: &str) -> Vec { + events + .lock() + .unwrap() + .iter() + .filter_map(|event| event.get("progress")) + .filter(|progress| progress.get_text("phase") == Some(phase)) + .cloned() + .collect() +} + +/// Waits, bounded, until `done`; a test that waits longer than 20 s hangs. +fn wait_for(what: &str, done: impl Fn() -> bool) { + let start = Instant::now(); + while !done() { + assert!( + start.elapsed() < Duration::from_secs(20), + "timed out waiting for {what}" + ); + std::thread::sleep(Duration::from_millis(20)); + } +} + +fn setup(name: &str) -> (Scratch, Standin, PathBuf) { + let scratch = Scratch::new(name); + let standin = Standin::new(&scratch.base.join("standin")); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + standin.image(ID, &["demo/app:1"], architecture(), 4000); + standin.export(&filtered(&export())); + (scratch, standin, home) +} + +#[test] +fn one_copy_of_an_image_per_machine() { + let (_scratch, standin, home) = setup("lp176-one-writer"); + standin.hold(); + // the first copy: it holds the lock and waits in `docker export` + let first_events = Arc::new(Mutex::new(Vec::new())); + let first = { + let (docker, at_home, events) = (standin.docker(), home.clone(), first_events.clone()); + std::thread::spawn(move || copy(&docker, &at_home, "docker", "demo/app:1", &events)) + }; + wait_for("the first copy to start its export", || { + standin.starts() == 1 + }); + // the second copy: it says it waits, and it sends nothing meanwhile + let second_events = Arc::new(Mutex::new(Vec::new())); + let second = { + let (docker, at_home, events) = (standin.docker(), home.clone(), second_events.clone()); + std::thread::spawn(move || copy(&docker, &at_home, "docker", "demo/app:1", &events)) + }; + wait_for("the second copy to say it waits", || { + !phases(&second_events, "lock").is_empty() + }); + let waited = &phases(&second_events, "lock")[0]; + assert_eq!(waited.get_text("waiting"), Some("lock")); + let holder = waited.get("holder").expect("the wait names its holder"); + assert_eq!( + holder.get_int("pid"), + Some(std::process::id() as i64), + "the holder is the copy in this process: {holder:?}" + ); + assert_eq!(holder.get_text("image"), Some(ID)); + assert_eq!(holder.get_text("machine"), Some("docker")); + assert_eq!(standin.starts(), 1, "one writer at a time"); + assert_eq!(standin.creates(), 1, "one export container at a time"); + assert!(phases(&second_events, "export").is_empty(), "no export yet"); + assert_eq!(standin.exports(), 0, "no byte left the first copy yet"); + assert!( + !cache::cache(&home).join(format!("{HEX}.2")).exists(), + "nothing is unpacked while the first copy sends" + ); + // the first copy finishes: the second reuses what it published + standin.release(); + let first = first.join().unwrap().unwrap(); + assert!(!first.reused); + let second = second.join().unwrap().unwrap(); + assert!(second.reused, "the waiter reuses the published image"); + assert_eq!(second.size, first.size); + assert_eq!(standin.starts(), 1, "one export in all"); + assert!(cache::cache(&home).join(format!("{HEX}.2")).is_dir()); + assert!(!cache::cache(&home) + .join(format!(".recv-{HEX}.part")) + .exists()); + assert!( + !ImageLock::record_path(&home, "docker", HEX).exists(), + "a finished copy leaves no record" + ); + assert!(standin.containers().is_empty(), "its container is gone"); +} + +#[test] +fn another_machine_is_another_lock() { + let (_scratch, standin, home) = setup("lp176-two-machines"); + let mut sink = |_: SdkValue| {}; + let held = ImageLock::take(&home, "docker", ID, &mut Events::new(&mut sink)).unwrap(); + // the same image on another machine is another lock, so its copy runs + let events = Arc::new(Mutex::new(Vec::new())); + let loaded = copy(&standin.docker(), &home, "box", "demo/app:1", &events).unwrap(); + assert!(!loaded.reused); + assert!( + phases(&events, "lock").is_empty(), + "the other machine's copy does not wait" + ); + assert_eq!(standin.exports(), 1); + // the record names the machine that holds the lock, not the other one + let record = home::read_record(&ImageLock::record_path(&home, "docker", HEX)) + .unwrap() + .expect("the holder's record"); + assert_eq!(record.get_text("machine"), Some("docker")); + assert_eq!(record.get_text("image"), Some(ID)); + assert_eq!(record.get_int("pid"), Some(std::process::id() as i64)); + assert!( + record.get("pid_start").is_some(), + "the record names its process" + ); + drop(held); + assert!(!ImageLock::record_path(&home, "docker", HEX).exists()); + // and the lock is free now + let mut sink = |_: SdkValue| {}; + ImageLock::take(&home, "docker", ID, &mut Events::new(&mut sink)).unwrap(); +} + +#[test] +fn a_dead_owner_is_taken_over_and_a_reused_pid_holds_nothing() { + let (_scratch, _standin, home) = setup("lp176-dead-owner"); + let record = ImageLock::record_path(&home, "docker", HEX); + // a record left by a copy whose pid another process now holds: the pid + // is alive, the process is not that copy, and no lock is held + fs::create_dir_all(record.parent().unwrap()).unwrap(); + home::write_record( + &record, + &SdkValue::map([ + ("pid", SdkValue::Int(std::process::id() as i64)), + ("pid_start", SdkValue::text("1")), + ("pid_boot", SdkValue::text("00")), + ("machine", SdkValue::text("docker")), + ("image", SdkValue::text(ID)), + ]), + ) + .unwrap(); + let events = Arc::new(Mutex::new(Vec::new())); + let start = Instant::now(); + let reused = { + let seen = events.clone(); + let mut sink = move |event: SdkValue| seen.lock().unwrap().push(event); + ImageLock::take(&home, "docker", ID, &mut Events::new(&mut sink)) + }; + let reused = reused.unwrap(); + assert!( + start.elapsed() < Duration::from_secs(2), + "a record alone is not a lock" + ); + assert!(phases(&events, "lock").is_empty(), "no wait on a dead name"); + let mine = home::read_record(&record).unwrap().unwrap(); + assert_eq!(mine.get_int("pid"), Some(std::process::id() as i64)); + assert_ne!( + mine.get_text("pid_start"), + Some("1"), + "this copy replaced it" + ); + drop(reused); + assert!(!record.exists()); + // a copy in another process that is killed: the kernel releases its + // lock, and the waiting copy takes over without a deadline + let helper = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "holds_the_lock_for_another_copy", "--nocapture"]) + .env("LP176_LOCK_HOLD", &home) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(); + wait_for("the other process to hold the lock", || { + home.join("helper-held").exists() + }); + let events = Arc::new(Mutex::new(Vec::new())); + let start = Instant::now(); + let waiter = { + let (at_home, seen) = (home.clone(), events.clone()); + std::thread::spawn(move || { + let sink = seen.clone(); + let mut sink = move |event: SdkValue| sink.lock().unwrap().push(event); + ImageLock::take(&at_home, "docker", ID, &mut Events::new(&mut sink)) + }) + }; + wait_for("the second copy to say it waits", || { + !phases(&events, "lock").is_empty() + }); + assert!(!waiter.is_finished(), "a live owner is waited for"); + let holder = &phases(&events, "lock")[0]; + assert_eq!( + holder + .get("holder") + .and_then(|record| record.get_int("pid")), + Some(helper.id() as i64), + "the wait names the other process" + ); + // killed: no drop runs in it, so its record stays and its lock is freed + let mut helper = helper; + helper.kill().unwrap(); + helper.wait().unwrap(); + let taken = waiter.join().unwrap().unwrap(); + assert!( + start.elapsed() < Duration::from_secs(10), + "a dead owner is taken over at once" + ); + let mine = home::read_record(&record).unwrap().unwrap(); + assert_eq!(mine.get_int("pid"), Some(std::process::id() as i64)); + drop(taken); +} + +/// The other process of the test above: it takes the lock, says so and +/// blocks until the test kills it. Run only with `LP176_LOCK_HOLD` set. +#[test] +fn holds_the_lock_for_another_copy() { + let Ok(at_home) = std::env::var("LP176_LOCK_HOLD") else { + return; + }; + let at_home = PathBuf::from(at_home); + let mut sink = |_: SdkValue| {}; + let _held = ImageLock::take(&at_home, "docker", ID, &mut Events::new(&mut sink)).unwrap(); + fs::write(at_home.join("helper-held"), b"").unwrap(); + loop { + std::thread::sleep(Duration::from_secs(1)); + } +} + +#[test] +fn a_short_machine_is_refused_before_any_effect() { + let (_scratch, standin, home) = setup("lp176-capacity"); + // larger than twice what any machine has free + let big = u64::MAX / 8; + standin.image(ID, &["demo/app:1"], architecture(), big); + let events = Arc::new(Mutex::new(Vec::new())); + let error = copy(&standin.docker(), &home, "docker", "demo/app:1", &events).unwrap_err(); + assert_eq!(error.code, "Capacity", "{}", error.message); + let needed = error.detail.get_int("needed").unwrap(); + let free = error.detail.get_int("free").unwrap(); + assert!(needed > free, "{needed} {free}"); + assert_eq!( + needed as u64, + docker::need(big), + "a fresh copy needs the whole image" + ); + assert_eq!( + error.detail.get_text("where"), + Some(cache::cache(&home).to_string_lossy().as_ref()), + "the refusal names the filesystem it measured" + ); + assert!(error.message.contains("more bytes"), "{}", error.message); + // nothing was created on the machine or in the home + assert_eq!(standin.creates(), 0, "no export container"); + assert_eq!(standin.starts(), 0, "no export"); + assert_eq!(standin.exports(), 0); + assert!(!cache::cache(&home).exists(), "no image cache folder"); + assert!(!ImageLock::record_path(&home, "docker", HEX).exists()); +} + +#[test] +fn a_resumed_copy_needs_only_the_bytes_it_has_not_staged() { + let (_scratch, standin, home) = setup("lp176-resume-capacity"); + let bytes = filtered(&big_export()); + // a machine with room for neither copy: both are refused, and what is + // already staged is counted once instead of twice + let big = u64::MAX / 8; + standin.image(ID, &["demo/app:1"], architecture(), big); + let fresh = Arc::new(Mutex::new(Vec::new())); + let error = copy(&standin.docker(), &home, "docker", "demo/app:1", &fresh).unwrap_err(); + assert_eq!(error.code, "Capacity", "{}", error.message); + let whole = error.detail.get_int("needed").unwrap(); + assert_eq!(whole as u64, docker::need(big)); + assert!(error.detail.get_int("free").unwrap() < whole); + // 3 of the tar's 4 MiB are staged; the copy needs those 3 MiB less + let staged = 3 << 20; + cache::write(&cache::cache(&home), HEX, 0, &bytes[..staged]).unwrap(); + let events = Arc::new(Mutex::new(Vec::new())); + let error = copy(&standin.docker(), &home, "docker", "demo/app:1", &events).unwrap_err(); + assert_eq!(error.code, "Capacity", "{}", error.message); + let left = error.detail.get_int("needed").unwrap(); + assert_eq!( + whole - left, + staged as i64, + "the staged bytes are not counted twice" + ); + assert!( + error.detail.get_int("free").is_some(), + "a refusal names the free bytes" + ); + // and a refusal changes nothing: no container, no export, same part + assert_eq!(standin.creates(), 0, "no export container"); + assert_eq!(standin.starts(), 0, "no export"); + let part = cache::cache(&home).join(format!(".recv-{HEX}.part")); + assert_eq!(fs::symlink_metadata(&part).unwrap().len(), staged as u64); + assert!(!cache::cache(&home).join(format!("{HEX}.2")).exists()); +} + +#[test] +fn a_native_copy_in_this_process_takes_the_same_lock() { + // `machine.load` on native Linux copies in this process (`Target::local`) + // and takes the very lock a worker copy takes + let (_scratch, standin, home) = setup("lp176-native-lock"); + let mut sink = |_: SdkValue| {}; + let held = ImageLock::take(&home, "native", ID, &mut Events::new(&mut sink)).unwrap(); + let events = Arc::new(Mutex::new(Vec::new())); + let running = { + let (docker, at_home, seen) = (standin.docker(), home.clone(), events.clone()); + std::thread::spawn(move || copy(&docker, &at_home, "native", "demo/app:1", &seen)) + }; + wait_for("the in-process copy to wait on the same lock", || { + !phases(&events, "lock").is_empty() + }); + assert_eq!(standin.starts(), 0, "it exported nothing while locked out"); + assert!(!events_has(&events, "export")); + drop(held); + assert!(running.join().unwrap().is_ok()); + assert_eq!(standin.starts(), 1); + assert!(cache::cache(&home).join(format!("{HEX}.2")).is_dir()); +} + +/// Whether any event of `phase` was sent. +fn events_has(events: &Arc>>, phase: &str) -> bool { + !phases(events, phase).is_empty() +} diff --git a/docs/architecture/api/sdk/machine.md b/docs/architecture/api/sdk/machine.md index 5451ed725..d871d7d76 100644 --- a/docs/architecture/api/sdk/machine.md +++ b/docs/architecture/api/sdk/machine.md @@ -205,24 +205,34 @@ CLI layerfs machine load [--progress] `image` is a digest, Docker image Id or Docker reference. The machine is asked first: an image it holds is `reused: true` and needs neither Docker nor -a byte sent. Otherwise `docker image inspect` resolves it; the host keeps an -export container `layerfs-export-` (removed once the machine publishes -the image), streams `docker export` without the init layer's files -(`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, `etc/mtab`, -`dev/*`) and device or FIFO entries in 1 MiB `image.artifact` frames to -`.recv-.part`, and the machine checks its size and sha256, unpacks it +a byte sent. Otherwise `docker image inspect` resolves it; one copy of that Id +on that machine at a time holds `/run/image-lock//.lock` +(an exclusive `flock` with the owner's `pid`, `pid_start` and `pid_boot` +beside it), so a second copy waits — `{phase: "lock", waiting: "lock", +holder}` each second, with no deadline — and then reuses what the first +published; a copy whose owner died takes the lock over at once, because the +kernel released it, and a record naming a reused pid holds nothing. The +machine's free bytes are checked before anything is created on either side: +`Capacity` `{needed, free, where}` refuses a machine too small for the copy, +with no export container, no staged byte and no cache folder, `needed` +counting the bytes a resumed copy already staged once and `where` the +filesystem `probe` measured. Only then does the host create the export +container `layerfs-export--` (one per image and machine, +removed once the machine publishes the image) and stream `docker export` +without the init layer's files (`.dockerenv`, `etc/hosts`, `etc/hostname`, +`etc/resolv.conf`, `etc/mtab`, `dev/*`) and device or FIFO entries in 1 MiB +`image.artifact` frames to `.recv-.part`; the machine checks its size and sha256, unpacks it once into `.2/`, writes the sidecar and deletes the staged tar. A staged -tar left by a stopped copy is resumed when its bytes hash as this export's -prefix, else restarted; one still growing (under 30 s old) is another -caller's copy, which this one waits for. `NoSpace`'s `need` counts the -larger of the layers' unpacked size and the export container's root -(`SizeRootFs`); `size` is the bytes sent, else the sidecar's, else the -layers' unpacked size. Progress: `inspect`, `export`, `send` (`done`, -`total`: an estimate, never below `done`, until the last `send` event, whose -`done` and `total` are both the bytes sent), `unpack`. Errors: `Unsupported` `{reason: "host"}` +tar left by a copy that is not running is resumed when its bytes hash as this +export's prefix, else restarted; `size` is the bytes sent, else the sidecar's, +else the layers' unpacked size, and the export container's `SizeRootFs` only +refines the progress estimate. Progress: `inspect`, `lock`, `export`, `send` +(`done`, `total`: an estimate, never below `done`, until the last `send` +event, whose `done` and `total` are both the bytes sent), `unpack`. Errors: +`Unsupported` `{reason: "host"}` (macOS `native`), `{reason: "arch" | "os", value}`; `InvalidInput` (Docker -has no such image); `Unavailable` `{what: "docker" | "machine"}`; `NoSpace` -`{need, free}`. +has no such image); `Unavailable` `{what: "docker" | "machine"}`; `Capacity` +`{needed, free, where}`. ### machine.prune diff --git a/docs/architecture/api/sdk/sandbox.md b/docs/architecture/api/sdk/sandbox.md index 732fe6d42..e7a6a16fb 100644 --- a/docs/architecture/api/sdk/sandbox.md +++ b/docs/architecture/api/sdk/sandbox.md @@ -76,7 +76,7 @@ first. Nothing starts a stopped machine. | Error | When | | --- | --- | | `InvalidInput` | `native`/`docker` as the name, or a name ending in `.root`; an image Docker does not have | -| `NoSpace` | copying the image needs `2 × size × 1.05` bytes and the machine has fewer (`detail { need, free }`) | +| `Capacity` | copying the image needs `2 × size × 1.05` bytes, less what a resumed copy already staged, and the machine has fewer (`detail { needed, free, where }`) | | `Unavailable` | the machine is stopped (`detail { what: "machine" }`) or Docker cannot be read (`detail { what: "docker" }`) | | `NotFound` | no machine of that name | | `NoStore` | the project has no installed Store | diff --git a/docs/architecture/control/home/README.md b/docs/architecture/control/home/README.md index c5bfbf860..d8099d2e1 100644 --- a/docs/architecture/control/home/README.md +++ b/docs/architecture/control/home/README.md @@ -110,6 +110,7 @@ is the home or a worker's root. | `layerfs.json`, `layerfs.lock`, `machine/native/`, `machine/docker/` | the first call on an empty or missing folder; `docker`'s record carries its `vm_name` | never | [`home/layout.rs`](../../../../control/crates/layerfs-home/src/home/layout.rs), [`spec.rs`](../../../../control/crates/layerfs-machine/src/spec.rs) `ensure_built_ins` | | `machine//forward.log`, `forward.1.log` | the stderr of each detached `ssh -N -L` a `lima` machine's forwards run. Lima's `ssh.config` is not here: it stays in Lima's own instance folder and is only read | with the machine's folder, at `machine.remove` | [`setup/forward.rs`](../../../../control/crates/layerfs-platform/src/setup/forward.rs), [`lima/observe.rs`](../../../../control/crates/layerfs-platform/src/platforms/lima/observe.rs) `tunnel` | | `machine/docker/worker.log.ended` | a copy of an ended worker's log, taken out of its stopped container | in the call that read it | [`docker/power.rs`](../../../../control/crates/layerfs-platform/src/platforms/docker/power.rs) `ended` | +| `/run/image-lock//.lock`, `.json` | one copy of an image on one machine: the `flock` it holds to its end, and its owner record (`pid`, `pid_start`, `pid_boot`, machine, image, since) | both end with the copy, and the next copy overwrites a record an owner left by dying | [`image_load.rs`](../../../../control/crates/layerfs-sandbox/src/image_load.rs) `ImageLock` | | `/store//store.sqlite.incoming` | the receiving side of a `store.push` or `store.pull` | renamed to `store.sqlite` at install | [`transfer/steps.rs`](../../../../control/crates/layerfs-store/src/sqlite/transfer/steps.rs) | | `store//backup.lock` | `backup.create`, which holds its `flock` to its end | never; the file stays | [`backup/create.rs`](../../../../control/crates/layerfs-store/src/backup/create.rs) `Creating` | | `/store//store.sqlite.backup`; `store//backup.staging` | `backup.create`: the snapshot staged beside the Store's file, and in the home the copy fetched from a worker | when the create ends | same, [`transfer/steps.rs`](../../../../control/crates/layerfs-store/src/sqlite/transfer/steps.rs) `Stage`, `Unstage` | diff --git a/docs/versioned/2.0.0/calls.md b/docs/versioned/2.0.0/calls.md index c64318d82..a134d3edb 100644 --- a/docs/versioned/2.0.0/calls.md +++ b/docs/versioned/2.0.0/calls.md @@ -255,16 +255,19 @@ $ printf '%s' '[{"op":"write","path":"/b.txt","content":"b\\n"},{"op":"mkdir","p (unpacked, or in its archive) starts at once; any other is resolved with `docker image inspect` through the `docker` machine's recorded socket (else Docker's default context), refused `Unsupported` - `{reason: "arch", value}` for another architecture, `NoSpace` - `{need, free}` when `2 × size × 1.05` is over the machine's free bytes - (`size`: what the image's layers unpack to, the sum of `docker history`'s - layer sizes, or the export container's root if larger), + `{reason: "arch", value}` for another architecture, `Capacity` + `{needed, free, where}` when `2 × size × 1.05`, less the bytes a resumed + copy already staged, is over the machine's free bytes (`size`: what the + image's layers unpack to, the sum of `docker history`'s layer sizes), and otherwise exported once (`docker create` + `docker export`, without the init layer's files), sent in 1 MiB frames and unpacked on the machine under `machines/native/run/images/.2/` with a sidecar `.2.json`; the staged tar is deleted. Docker unreachable is `Unavailable` `{what: "docker"}`, the machine stopped `Unavailable` - `{what: "machine"}`. `--progress` reports `inspect`, `export`, `send` + `{what: "machine"}`. One copy of an image on one machine at a time: a + second waits for the first (phase `lock`, `waiting: "lock"`, the holder + in `holder`), then reuses what it published. `--progress` reports + `inspect`, `lock`, `export`, `send` (`done`, `total`; `total` is an estimate until the last `send` event, which has `done` equal to `total`, the bytes sent), `unpack` and `start`. The record keeps the image's id, and every create sets its sidecar's `last_used`. The worker container's own @@ -886,7 +889,7 @@ Codes seen in the 2.0 library include: | `Unavailable`, `Denied` | a server, bucket, worker or host cannot be reached, or refused the login or secret | | `Conflict` | a merge or Commit conflict; for `backup.restore`, the Store changed since its last backup or restore | | `Binary` | `file.read` of a file that is not text | -| `Capacity` | a Sandbox's Workspace limit; a `store push` or `store pull` target without room for the Store (`detail.needed`, `detail.free`) | +| `Capacity` | a Sandbox's Workspace limit; a `store push` or `store pull` target without room for the Store (`detail.needed`, `detail.free`); copying an image to a machine without room for it (`detail.needed`, `detail.free`, `detail.where`) | | `Failed` | it was tried and did not happen; whatever exists is kept | | `Unknown` | the outcome is not known; both sides are kept and logged in `log/uncertain.jsonl`, and the entity keeps an uncertain `op` (later calls on it are `Unresolved`) | From e6e05eab999c26e3b2387223968e2ebc518b589d Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 17 Nov 2026 03:48:22 +0000 Subject: [PATCH 2/8] fix(sandbox): exclusive export container and deterministic tar directory mtime Every image export previously used `layerfs-export--` and swept older `layerfs-export-*` containers by age (`STALE_SECS = 30 * 60`) with plain `docker rm -f`: an in-flight failure could leave or collide on a predictable name across homes or runs, an idle copy >30 minutes old risked having another caller remove its container, `docker rm -f` leaked anonymous volumes on images that declare `VOLUME`, and two `docker export` runs >=2 s apart differed on containerd-snapshotter directory timestamps (`dev/`, `etc/`, `proc/`, `sys/`), breaking resume across separate exports. - `image_load`: replace age-based `STALE_SECS` / `remove_stale` with an exclusive per-export container named `layerfs-export---` and labeled with `layerfs.role=image-export`, `layerfs.home`, `layerfs.machine`, `layerfs.image`, and `layerfs.export.nonce`. Guard both the container (`ExportContainer`) and streamed child (`ExportChild`) so error, cancel, or drop kills the export process and removes only that copy's container and its anonymous volumes (`docker rm -v`, with inspect + `docker volume rm` fallback when a container or stand-in still remains). - Ownership enumeration and recovery: add `owned_containers` and `cleanup_owned` plus `ImageLock::try_take` so residual containers belonging to a home after a hard kill are listed and cleaned under I01's `ImageLock` (skipping active locked copies in `active` and leaving other homes untouched). Clean any stale container of the same `(home_id, machine, id)` under `ImageLock` before creating a new export container or probing sizes. Keep `docker.rs` untouched. - `image_tar::Filtered`: normalize directory (`flag == b'5'`) `mtime` to `00000000000\0`, recompute ustar header checksums, strip `mtime`/`atime`/ `ctime` from PAX `x` extended headers (dropping now-empty `x` blocks), and zero extended-header `mtime` (`x`/`L`/`K`) + checksum for directory entries so separate real `docker create` + `docker export` runs >=2 s apart yield byte-identical filtered tars and valid resume prefixes. Tests: new `tests/lp176_image_export.rs` (7 tests covering PAX/directory mtime normalization with real flat rootfs unpack, real Docker >=2 s identical SHA + prefix resume, `VOLUME` image anonymous volume cleanup, error + cancel container cleanup, killed load recovery via `owned_containers` / `cleanup_owned` under `ImageLock`, cross-home isolation, and pause helper); I01 `tests/lp176_image_lock.rs` (7), `tests/image_copy.rs` (9), `tests/image_tar.rs` (4) pass. Deleted tests: none. Docs: updated `docs/architecture/api/sdk/machine.md` and `docs/versioned/2.0.0/calls.md` (layerfs-machine / SDK `machine.load`). Production LOC: 169,779 -> 170,091 (delta +312) core 39,795 -> 39,795 (0) engine 75,102 -> 75,102 (0) control 48,536 -> 48,848 (+312) layerfs-sandbox +312 api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on 83843c31c and this tree --- .../crates/layerfs-sandbox/src/image_load.rs | 442 ++++++++-- .../crates/layerfs-sandbox/src/image_tar.rs | 102 ++- .../tests/lp176_image_export.rs | 805 ++++++++++++++++++ docs/architecture/api/sdk/machine.md | 17 +- docs/versioned/2.0.0/calls.md | 7 +- 5 files changed, 1277 insertions(+), 96 deletions(-) create mode 100644 control/crates/layerfs-sandbox/tests/lp176_image_export.rs diff --git a/control/crates/layerfs-sandbox/src/image_load.rs b/control/crates/layerfs-sandbox/src/image_load.rs index 0a076c7eb..1e4a78d87 100644 --- a/control/crates/layerfs-sandbox/src/image_load.rs +++ b/control/crates/layerfs-sandbox/src/image_load.rs @@ -2,11 +2,17 @@ //! `machine.load`; R1, R3): the image named by digest, Docker Id or Docker //! reference is resolved, and when the machine does not hold it yet, it is //! exported from the host's Docker as one flat root filesystem tar -//! ([`crate::image_tar`]), sent in 1 MiB frames and unpacked once there -//! ([`crate::image_artifact`]). The machine is asked first, so an image it -//! holds needs neither Docker nor a byte sent. One copy per image and machine -//! at a time: the second one waits in [`ImageLock`], and a copy whose owner -//! died is taken over at once (#175 R01). Progress phases are `inspect`, +//! ([`crate::image_tar`], with directory mtimes normalized so exports >=2 s +//! apart are byte-identical for resume), sent in 1 MiB frames and unpacked +//! once there ([`crate::image_artifact`]). The machine is asked first, so an +//! image it holds needs neither Docker nor a byte sent. One copy per image and +//! machine at a time: the second one waits in [`ImageLock`], and a copy whose +//! owner died is taken over at once (#175 R01). Each export uses its own +//! container (`layerfs-export---`) labeled with the +//! home, machine, image and nonce, and removes only that container and its +//! anonymous volumes on exit or error; residual containers of this home left +//! by killed copies can be enumerated ([`owned_containers`]) and removed +//! under [`ImageLock`] ([`cleanup_owned`]). Progress phases are `inspect`, //! `lock` (`waiting: "lock"` while another copy holds it), `export`, `send` //! (`done`/`total` bytes) and `unpack`. use crate::deploy::Side; @@ -21,16 +27,18 @@ use layerfs_home::outcome::{failed, refused, Outcome}; use layerfs_home::process; use layerfs_store::place::Worker; use sha2::{Digest, Sha256}; +use std::collections::BTreeMap; use std::fs::{File, OpenOptions}; use std::io::Read; use std::os::unix::fs::OpenOptionsExt; use std::path::{Path, PathBuf}; +use std::process::Child; use std::time::{Duration, Instant}; type Result = std::result::Result; -/// A leftover export container older than this is removed by the next copy. -const STALE_SECS: u64 = 3600; +/// Docker `layerfs.role` label marking an ephemeral image-export container. +pub const EXPORT_ROLE: &str = "image-export"; /// How often a waiting copy looks at the lock again: one look every 200 ms /// reacts to a released or taken-over lock, and to a killed waiter, at once. const LOCK_POLL: Duration = Duration::from_millis(200); @@ -229,6 +237,13 @@ pub fn load( let machine = target.machine().to_owned(); let _lock = ImageLock::take(target.home(), &machine, id, events)?; // under the lock: the copy that held it may have published the image + if let Some(home_id) = existing_home_id(target.home())? { + if let Ok(residual) = owned_for_home_id(docker, &home_id, Some(&machine), Some(id)) { + for entry in residual { + remove_container(docker, &entry.name); + } + } + } probe = target.probe(Some(id), None, archive)?; if held(&probe) { let size = kept(&probe).or(Some(inspected.size)); @@ -238,10 +253,9 @@ pub fn load( // container, no staged byte and no cache folder; a resumed copy counts // the bytes it already staged once capacity(&machine, &probe, id, inspected.size)?; - let container = container(&machine, id); + let home_id = ensure_home_id(target.home())?; phase(events, "export", None); - remove_stale(docker, &container); - created(docker, &container, id)?; + let container = ExportContainer::create(docker, &home_id, &machine, id)?; let unpacked = docker .read( &[ @@ -250,7 +264,7 @@ pub fn load( "--size", "--format", "{{.SizeRootFs}}", - &container, + container.name(), ], docker::READ, ) @@ -266,15 +280,23 @@ pub fn load( docker, events, target, - &container, + container.name(), id, (staged, prefix), estimate, )? { Some(done) => done, // the staged bytes are not this export's prefix: start over - None => send(docker, events, target, &container, id, (0, None), estimate)? - .ok_or_else(|| refused("Failed", "the image export changed while it was sent"))?, + None => send( + docker, + events, + target, + container.name(), + id, + (0, None), + estimate, + )? + .ok_or_else(|| refused("Failed", "the image export changed while it was sent"))?, }; phase(events, "unpack", None); target.step(SdkValue::map([ @@ -289,7 +311,7 @@ pub fn load( ("architecture", SdkValue::text(&inspected.architecture)), ("config", inspected.config.clone()), ]))?; - let _ = docker.read(&["rm", "-f", &container], docker::READ); + container.remove(); Ok(Loaded { id: id.clone(), refs: refs.clone(), @@ -352,14 +374,10 @@ impl ImageLock { Self::dir(home, machine).join(format!("{hex}.json")) } - /// Takes the lock of image `id` on `machine`, waiting while a live copy - /// holds it and recording this copy as the owner. `events` say - /// `{phase: "lock", waiting: "lock", holder}` once a second meanwhile. - pub fn take(home: &Path, machine: &str, id: &str, events: &mut Events<'_>) -> Result { - let hex = hex_of(id).ok_or_else(|| refused("InvalidInput", "image id"))?; - let dir = Self::dir(home, machine); - private_dir(&dir)?; - let file = OpenOptions::new() + /// Opens (creating if absent) the lock file of `hex` on `machine`. + fn open_file(home: &Path, machine: &str, hex: &str) -> Result { + private_dir(&Self::dir(home, machine))?; + OpenOptions::new() .read(true) .write(true) .create(true) @@ -367,7 +385,31 @@ impl ImageLock { .mode(0o600) .custom_flags(libc::O_NOFOLLOW) .open(Self::path(home, machine, hex)) - .map_err(failed)?; + .map_err(failed) + } + + /// Takes the lock of image `id` on `machine` without waiting; returns + /// `Ok(None)` when another live copy currently holds it. + pub fn try_take(home: &Path, machine: &str, id: &str) -> Result> { + let hex = hex_of(id).ok_or_else(|| refused("InvalidInput", "image id"))?; + let file = Self::open_file(home, machine, hex)?; + if !layerfs_home::home::flock::try_lock(&file, true).map_err(failed)? { + return Ok(None); + } + let lock = Self { + file, + record: Self::record_path(home, machine, hex), + }; + lock.record(machine, id)?; + Ok(Some(lock)) + } + + /// Takes the lock of image `id` on `machine`, waiting while a live copy + /// holds it and recording this copy as the owner. `events` say + /// `{phase: "lock", waiting: "lock", holder}` once a second meanwhile. + pub fn take(home: &Path, machine: &str, id: &str, events: &mut Events<'_>) -> Result { + let hex = hex_of(id).ok_or_else(|| refused("InvalidInput", "image id"))?; + let file = Self::open_file(home, machine, hex)?; let mut reported: Option = None; loop { if layerfs_home::home::flock::try_lock(&file, true).map_err(failed)? { @@ -418,11 +460,174 @@ impl ImageLock { } } -/// The export container of image `id` for `machine`: one per image and -/// machine, so two machines copying the same image neither share nor remove -/// each other's container. Nothing runs in it. -fn container(machine: &str, id: &str) -> String { - format!("layerfs-export-{machine}-{}", &id["sha256:".len()..]) +/// An export container owned by a LayerFS home (`layerfs.role=image-export`). +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct OwnedContainer { + /// Docker container name (`layerfs-export---`). + pub name: String, + /// Full 32-hex home id (`layerfs.home`). + pub home_id: String, + /// Target machine name (`layerfs.machine`). + pub machine: String, + /// Docker image Id (`layerfs.image`). + pub image: String, + /// One-time export nonce (`layerfs.export.nonce`). + pub nonce: String, +} + +/// Outcome of recovering residual export containers owned by a home. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Cleanup { + /// Container names (with their anonymous volumes) removed under [`ImageLock`]. + pub removed: Vec, + /// Container names left alone because a live copy holds their [`ImageLock`]. + pub active: Vec, +} + +/// Reads `home`'s 32-hex id without creating files when `home` is empty. +fn existing_home_id(home: &Path) -> Result> { + if home::guest::is_root(home) { + return Ok(Some(home::guest::file(home)?.id)); + } + match home::detect(home)? { + home::Layout::Current(file) | home::Layout::Previous(file) => Ok(Some(file.id)), + home::Layout::Empty => Ok(None), + home::Layout::Old => Err(refused( + "InvalidInput", + format!( + "{} is a LayerFS 1.1.0 home; it is converted on its first 2.0 call that writes", + home.display() + ), + )), + } +} + +/// Returns `home`'s 32-hex id, creating `layerfs.json` under the home lock when +/// `home` is an empty folder (such as an isolated test home). +fn ensure_home_id(home: &Path) -> Result { + if let Some(id) = existing_home_id(home)? { + return Ok(id); + } + let _guard = home::lock::take(home)?; + Ok(home::ensure(home)?.id) +} + +fn export_nonce() -> Result { + let bytes = layerfs_home::helpers::random()?; + Ok(layerfs_bridge::sdk_values::hex(&bytes[..8])) +} + +fn container_name(home_id: &str, machine: &str, nonce: &str) -> String { + let home8 = &home_id[..8.min(home_id.len())]; + format!("layerfs-export-{home8}-{machine}-{nonce}") +} + +/// Enumerates residual export containers owned by `home` (never another home's). +pub fn owned_containers(docker: &Docker, home: &Path) -> Result> { + let Some(home_id) = existing_home_id(home)? else { + return Ok(Vec::new()); + }; + owned_for_home_id(docker, &home_id, None, None) +} + +fn owned_for_home_id( + docker: &Docker, + home_id: &str, + machine: Option<&str>, + image: Option<&str>, +) -> Result> { + let role_filter = format!("label=layerfs.role={EXPORT_ROLE}"); + let home_filter = format!("label=layerfs.home={home_id}"); + let mut args = vec![ + "ps", + "-a", + "--filter", + &role_filter, + "--filter", + &home_filter, + ]; + let machine_filter = machine.map(|m| format!("label=layerfs.machine={m}")); + if let Some(filter) = &machine_filter { + args.extend(["--filter", filter.as_str()]); + } + let image_filter = image.map(|i| format!("label=layerfs.image={i}")); + if let Some(filter) = &image_filter { + args.extend(["--filter", filter.as_str()]); + } + let format = "{{.Names}}\t{{.Label \"layerfs.home\"}}\t{{.Label \"layerfs.machine\"}}\t{{.Label \"layerfs.image\"}}\t{{.Label \"layerfs.export.nonce\"}}"; + args.extend(["--format", format]); + let listed = docker + .read(&args, docker::READ) + .map_err(|f| f.refusal(""))?; + let prefix = format!("layerfs-export-{}-", &home_id[..8.min(home_id.len())]); + let mut found = Vec::new(); + for line in listed.lines() { + let mut cols = line.split('\t'); + let (Some(name), Some(l_home), Some(l_machine), Some(l_image), Some(l_nonce)) = ( + cols.next(), + cols.next(), + cols.next(), + cols.next(), + cols.next(), + ) else { + continue; + }; + if l_home != home_id + || !name.starts_with(&prefix) + || l_machine.is_empty() + || !cache::digest(l_image) + || l_nonce.is_empty() + { + continue; + } + if machine.is_some_and(|m| m != l_machine) || image.is_some_and(|i| i != l_image) { + continue; + } + found.push(OwnedContainer { + name: name.to_owned(), + home_id: l_home.to_owned(), + machine: l_machine.to_owned(), + image: l_image.to_owned(), + nonce: l_nonce.to_owned(), + }); + } + found.sort_by(|a, b| a.name.cmp(&b.name)); + Ok(found) +} + +/// Removes residual export containers owned by `home` (optionally scoped to +/// `machine` and/or `image`) under I01's [`ImageLock`], skipping any whose lock +/// is currently held by a live copy. +pub fn cleanup_owned( + docker: &Docker, + home: &Path, + machine: Option<&str>, + image: Option<&str>, +) -> Result { + let Some(home_id) = existing_home_id(home)? else { + return Ok(Cleanup::default()); + }; + let owned = owned_for_home_id(docker, &home_id, machine, image)?; + let mut by_key: BTreeMap<(String, String), Vec> = BTreeMap::new(); + for entry in owned { + by_key + .entry((entry.machine, entry.image)) + .or_default() + .push(entry.name); + } + let mut out = Cleanup::default(); + for ((m, img), names) in by_key { + match ImageLock::try_take(home, &m, &img)? { + Some(_lock) => { + for name in names { + remove_container(docker, &name); + out.removed.push(name); + } + } + None => out.active.extend(names), + } + } + Ok(out) } /// `id`'s 64 hex digits, the name of its files under the cache and the lock. @@ -465,9 +670,93 @@ fn capacity(machine: &str, probe: &SdkValue, id: &str, size: u64) -> Result<()> )) } -/// The export container `name` of image `id`: the one a failed copy kept -/// (so a retry exports identical bytes), else a new one. Nothing runs in it. -fn created(docker: &Docker, name: &str, id: &str) -> Result<()> { +/// Ephemeral export container owned by one copy; removed (with its anonymous +/// volumes) on exit, error, or unwind. +struct ExportContainer<'a> { + docker: &'a Docker, + name: String, + active: bool, +} + +impl<'a> ExportContainer<'a> { + fn create(docker: &'a Docker, home_id: &str, machine: &str, id: &str) -> Result { + let nonce = export_nonce()?; + let name = container_name(home_id, machine, &nonce); + create_container(docker, &name, home_id, machine, id, &nonce)?; + Ok(Self { + docker, + name, + active: true, + }) + } + + fn name(&self) -> &str { + &self.name + } + + fn remove(mut self) { + self.active = false; + remove_container(self.docker, &self.name); + } +} + +impl Drop for ExportContainer<'_> { + fn drop(&mut self) { + if self.active { + self.active = false; + remove_container(self.docker, &self.name); + } + } +} + +fn create_container( + docker: &Docker, + name: &str, + home_id: &str, + machine: &str, + id: &str, + nonce: &str, +) -> Result<()> { + let role_label = format!("layerfs.role={EXPORT_ROLE}"); + let home_label = format!("layerfs.home={home_id}"); + let machine_label = format!("layerfs.machine={machine}"); + let image_label = format!("layerfs.image={id}"); + let nonce_label = format!("layerfs.export.nonce={nonce}"); + let result = docker.read( + &[ + "create", + "--name", + name, + "--label", + &role_label, + "--label", + &home_label, + "--label", + &machine_label, + "--label", + &image_label, + "--label", + &nonce_label, + "--network", + "none", + "--entrypoint", + "/layerfs-export", + id, + ], + Duration::from_secs(60), + ); + if let Err(Failure::NotRunning(_)) = &result { + // A timed-out `docker create` may still have created the container. + remove_container(docker, name); + } + result.map(drop).map_err(|f| f.refusal(id)) +} + +fn remove_container(docker: &Docker, name: &str) { + // Remove the created export container together with its anonymous volumes. + let _ = docker.read(&["rm", "-v", name], docker::READ); + // If still present (for instance with a stand-in `docker` that only handles + // `rm -f `, or a container requiring force), clean volumes then `-f`. if docker .read( &["container", "inspect", "--format", "{{.Id}}", name], @@ -475,58 +764,41 @@ fn created(docker: &Docker, name: &str, id: &str) -> Result<()> { ) .is_ok() { - return Ok(()); + let volumes = anonymous_volumes(docker, name); + let _ = docker.read(&["rm", "-f", name], docker::READ); + for volume in volumes { + let _ = docker.read(&["volume", "rm", &volume], docker::READ); + } } - let started = format!( - "layerfs.export.started={}", - layerfs_home::home::now_ms() / 1000 - ); - docker - .read( - &[ - "create", - "--name", - name, - "--label", - &started, - "--network", - "none", - "--entrypoint", - "/layerfs-export", - id, - ], - Duration::from_secs(60), - ) - .map(drop) - .map_err(|f| f.refusal(id)) } -/// Removes export containers other copies left more than an hour ago. -fn remove_stale(docker: &Docker, keep: &str) { - let Ok(listed) = docker.read( +fn anonymous_volumes(docker: &Docker, name: &str) -> Vec { + let Ok(out) = docker.read( &[ - "ps", - "-a", - "--filter", - "label=layerfs.export.started", + "container", + "inspect", "--format", - "{{.Names}} {{.Label \"layerfs.export.started\"}}", + "{{range .Mounts}}{{if eq .Type \"volume\"}}{{.Name}}{{\"\\n\"}}{{end}}{{end}}", + name, ], docker::READ, ) else { - return; + return Vec::new(); }; - let now = (layerfs_home::home::now_ms() / 1000) as u64; - for line in listed.lines() { - let mut words = line.split_whitespace(); - let (Some(name), Some(started)) = (words.next(), words.next()) else { - continue; - }; - let old = started - .parse::() - .is_ok_and(|t| now.saturating_sub(t) > STALE_SECS); - if name != keep && name.starts_with("layerfs-export-") && old { - let _ = docker.read(&["rm", "-f", name], docker::READ); + out.lines() + .map(str::trim) + .filter(|v| v.len() == 64 && v.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f'))) + .map(str::to_owned) + .collect() +} + +struct ExportChild(Option); + +impl Drop for ExportChild { + fn drop(&mut self) { + if let Some(mut child) = self.0.take() { + let _ = child.kill(); + let _ = child.wait(); } } } @@ -543,10 +815,15 @@ fn send( (staged, prefix): (u64, Option), total: Option, ) -> Result> { - let mut child = docker - .stream(&["export", container]) - .map_err(|f| f.refusal(id))?; + let mut child = ExportChild(Some( + docker + .stream(&["export", container]) + .map_err(|f| f.refusal(id))?, + )); let stdout = child + .0 + .as_mut() + .expect("export child still held") .stdout .take() .ok_or_else(|| refused("Failed", "docker export gave no output"))?; @@ -570,8 +847,6 @@ fn send( let matched = left == 0 && Some(layerfs_bridge::sdk_values::hex(&head.finalize())) == prefix; if !matched { - let _ = child.kill(); - let _ = child.wait(); return Ok(None); } } @@ -598,7 +873,12 @@ fn send( last = Instant::now(); } } - let status = child.wait().map_err(failed)?; + let status = child + .0 + .take() + .expect("export child still held") + .wait() + .map_err(failed)?; if !status.success() { return Err(refused( "Failed", diff --git a/control/crates/layerfs-sandbox/src/image_tar.rs b/control/crates/layerfs-sandbox/src/image_tar.rs index 1837455e1..95926e935 100644 --- a/control/crates/layerfs-sandbox/src/image_tar.rs +++ b/control/crates/layerfs-sandbox/src/image_tar.rs @@ -1,9 +1,10 @@ //! The flat root filesystem tar a Sandbox image is copied as: `docker //! export`'s output with the files `docker create`'s init layer adds taken //! out (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, -//! `etc/mtab`, everything under `dev/`), and every device node and FIFO, -//! which the unpacker refuses. Those are the bytes that differ between two -//! exports of one image; what is left is the image's own tree. The filter +//! `etc/mtab`, everything under `dev/`), every device node and FIFO (which +//! the unpacker refuses), and directory modification times normalized to 0 +//! with recomputed header checksums. Those are the bytes that differ between +//! two exports of one image; what is left is the image's own tree. The filter //! streams: it holds at most one entry's extended headers, never a file's //! bytes. use std::io::{self, Read}; @@ -87,7 +88,7 @@ impl Filtered { /// Decides the next entry: fills `out` with its headers when it is kept /// (its data then follows through `copying`), or skips it. fn next_entry(&mut self) -> io::Result<()> { - let mut pending: Vec = Vec::new(); + let mut pending: Vec<([u8; BLOCK], Vec)> = Vec::new(); let mut long_name: Option = None; loop { let mut header = [0u8; BLOCK]; @@ -127,8 +128,7 @@ impl Filtered { b'L' => long_name = Some(text(body)), _ => {} } - pending.extend_from_slice(&header); - pending.extend_from_slice(&data); + pending.push((header, data)); continue; } let path = long_name.take().unwrap_or_else(|| ustar_name(&header)); @@ -141,7 +141,35 @@ impl Filtered { if dropped(&path, flag) { return self.skip(data); } - self.out.extend_from_slice(&pending); + if flag == b'5' { + for (mut ext_hdr, ext_data) in pending { + if ext_hdr[156] == b'x' { + if let Some((mut h, d)) = strip_pax_times(ext_hdr, ext_data)? { + h[136..148].copy_from_slice(b"00000000000\0"); + recompute_checksum(&mut h); + self.out.extend_from_slice(&h); + self.out.extend_from_slice(&d); + } + } else { + if matches!(ext_hdr[156], b'L' | b'K') { + ext_hdr[136..148].copy_from_slice(b"00000000000\0"); + recompute_checksum(&mut ext_hdr); + } + self.out.extend_from_slice(&ext_hdr); + self.out.extend_from_slice(&ext_data); + } + } + // `docker create`'s init layer touches directories such as `dev/` + // and `etc/` at container creation time; normalize every kept + // directory's mtime so exports >=2 s apart stay byte-identical. + header[136..148].copy_from_slice(b"00000000000\0"); + recompute_checksum(&mut header); + } else { + for (ext_hdr, ext_data) in pending { + self.out.extend_from_slice(&ext_hdr); + self.out.extend_from_slice(&ext_data); + } + } self.out.extend_from_slice(&header); self.copying = data; return Ok(()); @@ -238,3 +266,63 @@ fn octal(field: &[u8]) -> io::Result { u64::from_str_radix(digits, 8) .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "tar header number")) } + +/// Drops `mtime`, `atime`, and `ctime` records from a pax extended header +/// block (`flag == b'x'`), rebuilding its header and padded body only if any +/// time record was removed. Returns `None` when no records remain. +fn strip_pax_times( + mut header: [u8; BLOCK], + data: Vec, +) -> io::Result)>> { + let size = octal(&header[124..136])? as usize; + let body = &data[..size.min(data.len())]; + let Some(mut kept) = filter_pax_records(body) else { + return Ok(Some((header, data))); + }; + if kept.is_empty() { + return Ok(None); + } + write_octal(&mut header[124..136], kept.len() as u64); + recompute_checksum(&mut header); + let padded = kept.len().div_ceil(BLOCK) * BLOCK; + kept.resize(padded, 0); + Ok(Some((header, kept))) +} + +/// Filters `mtime`, `atime`, and `ctime` records out of a pax extended header +/// body; returns `None` when no time record was present or parsing fails. +fn filter_pax_records(body: &[u8]) -> Option> { + let mut kept = Vec::new(); + let mut changed = false; + let mut rest = body; + while !rest.is_empty() { + let space = rest.iter().position(|b| *b == b' ')?; + let length: usize = std::str::from_utf8(&rest[..space]).ok()?.parse().ok()?; + if length <= space + 1 || length > rest.len() { + return None; + } + let record = &rest[space + 1..length]; + let record = record.strip_suffix(b"\n").unwrap_or(record); + let key = record.split(|b| *b == b'=').next(); + if matches!(key, Some(b"mtime" | b"atime" | b"ctime")) { + changed = true; + } else { + kept.extend_from_slice(&rest[..length]); + } + rest = &rest[length..]; + } + changed.then_some(kept) +} + +fn write_octal(field: &mut [u8], value: u64) { + let width = field.len() - 1; + let text = format!("{value:0width$o}\0"); + field.copy_from_slice(&text.as_bytes()[..field.len()]); +} + +fn recompute_checksum(header: &mut [u8; BLOCK]) { + header[148..156].fill(b' '); + let sum: u64 = header.iter().map(|b| u64::from(*b)).sum(); + let text = format!("{sum:06o}\0 "); + header[148..156].copy_from_slice(text.as_bytes()); +} diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_export.rs b/control/crates/layerfs-sandbox/tests/lp176_image_export.rs new file mode 100644 index 000000000..b90e0543c --- /dev/null +++ b/control/crates/layerfs-sandbox/tests/lp176_image_export.rs @@ -0,0 +1,805 @@ +//! Real-Docker proof for exclusive per-export containers, deterministic tar +//! exports (>=2 s apart for resume), anonymous volume cleanup on `VOLUME` +//! images, and home-scoped owned-container recovery under `ImageLock` +//! (#176 I02). +#[allow(dead_code)] +#[path = "../../layerfs-sandbox-backend/tests/support/image.rs"] +mod fixture; +use fixture::{pax_record, Scratch, Tar}; +use layerfs_bridge::control::SdkValue; +use layerfs_home::events::Events; +use layerfs_home::home; +use layerfs_sandbox::docker::Docker; +use layerfs_sandbox::image_artifact::{self as cache, CHUNK}; +use layerfs_sandbox::image_load::{ + cleanup_owned, load, owned_containers, Cleanup, ImageLock, Loaded, Target, EXPORT_ROLE, +}; +use layerfs_sandbox::image_tar::Filtered; +use layerfs_sandbox_backend::{rootfs, Image}; +use sha2::{Digest, Sha256}; +use std::collections::BTreeSet; +use std::fs; +use std::io::{Read, Write}; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{Duration, Instant}; + +static SEQ: AtomicU64 = AtomicU64::new(0); + +fn docker_available() -> bool { + Command::new("docker") + .arg("info") + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status() + .is_ok_and(|s| s.success()) +} + +fn container_exists(name: &str) -> bool { + Command::new("docker") + .args(["container", "inspect", "--format", "{{.Id}}", name]) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status() + .is_ok_and(|s| s.success()) +} + +fn volume_exists(name: &str) -> bool { + Command::new("docker") + .args(["volume", "inspect", name]) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status() + .is_ok_and(|s| s.success()) +} + +fn container_volumes(container: &str) -> Vec { + let Ok(out) = Command::new("docker") + .args([ + "container", + "inspect", + "--format", + "{{range .Mounts}}{{if eq .Type \"volume\"}}{{.Name}}{{\"\\n\"}}{{end}}{{end}}", + container, + ]) + .output() + else { + return Vec::new(); + }; + if !out.status.success() { + return Vec::new(); + } + String::from_utf8_lossy(&out.stdout) + .lines() + .map(str::trim) + .filter(|l| !l.is_empty()) + .map(str::to_owned) + .collect() +} + +fn containers_for_home(home_id: &str) -> Vec { + let Ok(out) = Command::new("docker") + .args([ + "ps", + "-a", + "--filter", + &format!("label=layerfs.home={home_id}"), + "--format", + "{{.Names}}", + ]) + .output() + else { + return Vec::new(); + }; + if !out.status.success() { + return Vec::new(); + } + String::from_utf8_lossy(&out.stdout) + .lines() + .map(str::trim) + .filter(|l| !l.is_empty()) + .map(str::to_owned) + .collect() +} + +fn wait_for(what: &str, done: impl Fn() -> bool) { + let start = Instant::now(); + while !done() { + assert!( + start.elapsed() < Duration::from_secs(30), + "timed out waiting for {what}" + ); + std::thread::sleep(Duration::from_millis(20)); + } +} + +/// Builds a tiny unique Linux image with `dev/`, `etc/`, a >1 MiB blob (for +/// resume across `CHUNK`) and optionally `VOLUME /data/vol`. Tracks registered +/// homes so Drop removes any test-owned containers, anonymous volumes and the +/// test image even if a test panics. +struct TestImage { + base_tag: String, + tag: String, + id: String, + scratch: Scratch, + homes: Vec, +} + +impl TestImage { + fn build(name: &str, with_volume: bool) -> Self { + let seq = SEQ.fetch_add(1, Ordering::Relaxed); + let pid = std::process::id(); + let scratch = Scratch::new(&format!("lp176-exp-{name}-{seq}")); + let base_tag = format!("layerfs-lp176-base-{pid}-{seq}:test"); + let tag = format!("layerfs-lp176-img-{pid}-{seq}:test"); + let tar = Tar::new() + .at(1_700_000_000) + .directory("dev/", 0o755) + .directory("etc/", 0o755) + .file( + "etc/app.conf", + 0o644, + format!("mode=test-{pid}-{seq}\n").as_bytes(), + ) + .directory("usr/", 0o755) + .directory("usr/bin/", 0o755) + .file("usr/bin/blob", 0o755, &vec![0x5a; CHUNK + 131_072]) + .finish(); + let mut child = Command::new("docker") + .args(["import", "-", &base_tag]) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .expect("spawn docker import"); + child.stdin.take().unwrap().write_all(&tar).unwrap(); + let out = child.wait_with_output().unwrap(); + assert!( + out.status.success(), + "docker import failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + let final_tag = if with_volume { + let build_dir = scratch.base.join("build"); + fs::create_dir_all(&build_dir).unwrap(); + fs::write( + build_dir.join("Dockerfile"), + format!("FROM {base_tag}\nVOLUME /data/vol\n"), + ) + .unwrap(); + let out = Command::new("docker") + .args([ + "build", + "--pull=false", + "-q", + "-t", + &tag, + build_dir.to_str().unwrap(), + ]) + .output() + .expect("docker build"); + assert!( + out.status.success(), + "docker build failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + tag + } else { + base_tag.clone() + }; + let inspect = Command::new("docker") + .args(["image", "inspect", "--format", "{{.Id}}", &final_tag]) + .output() + .expect("docker image inspect"); + assert!(inspect.status.success()); + let id = String::from_utf8_lossy(&inspect.stdout).trim().to_owned(); + Self { + base_tag, + tag: final_tag, + id, + scratch, + homes: Vec::new(), + } + } + + fn hex(&self) -> &str { + self.id.strip_prefix("sha256:").expect("sha256 image id") + } + + fn make_home(&mut self, name: &str) -> (PathBuf, String) { + let home = self.scratch.base.join(name); + fs::create_dir_all(&home).unwrap(); + let id = home::ensure(&home).unwrap().id; + self.homes.push(id.clone()); + (home, id) + } +} + +impl Drop for TestImage { + fn drop(&mut self) { + let mut cnames = BTreeSet::new(); + for home_id in &self.homes { + cnames.extend(containers_for_home(home_id)); + } + if let Ok(out) = Command::new("docker") + .args([ + "ps", + "-a", + "--filter", + &format!("ancestor={}", self.id), + "--format", + "{{.Names}}", + ]) + .output() + { + if out.status.success() { + for line in String::from_utf8_lossy(&out.stdout).lines() { + let line = line.trim(); + if line.starts_with("layerfs-export-") || line.starts_with("lp176-exp-") { + cnames.insert(line.to_owned()); + } + } + } + } + for cname in cnames { + let vols = container_volumes(&cname); + let _ = Command::new("docker") + .args(["rm", "-f", "-v", &cname]) + .output(); + for v in vols { + let _ = Command::new("docker").args(["volume", "rm", &v]).output(); + } + } + if self.tag != self.base_tag { + let _ = Command::new("docker") + .args(["rmi", "-f", &self.tag]) + .output(); + } + let _ = Command::new("docker") + .args(["rmi", "-f", &self.base_tag]) + .output(); + } +} + +fn real_docker() -> Docker { + let path = std::env::var_os("PATH").unwrap_or_default(); + let program = std::env::split_paths(&path) + .filter(|d| !d.as_os_str().is_empty()) + .map(|d| d.join("docker")) + .find(|p| p.is_file()); + Docker::at(program, None) +} + +fn filtered_export(image_id: &str, cname: &str) -> (Vec, String) { + let out = Command::new("docker") + .args([ + "create", + "--name", + cname, + "--network", + "none", + "--entrypoint", + "/layerfs-export", + image_id, + ]) + .output() + .expect("docker create"); + assert!( + out.status.success(), + "docker create {cname} failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + let mut child = Command::new("docker") + .args(["export", cname]) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .expect("docker export"); + let mut filtered = Vec::new(); + Filtered::new(child.stdout.take().unwrap()) + .read_to_end(&mut filtered) + .unwrap(); + let status = child.wait_with_output().unwrap(); + let _ = Command::new("docker") + .args(["rm", "-f", "-v", cname]) + .output(); + assert!(status.status.success()); + let sha = layerfs_bridge::sdk_values::hex(&Sha256::digest(&filtered)); + (filtered, sha) +} + +fn run_load( + docker: &Docker, + home: &Path, + machine: &str, + image: &str, +) -> ( + Result, + Vec, +) { + let mut phases = Vec::new(); + let mut sink = |event: SdkValue| { + if let Some(p) = event.get("progress") { + phases.push(p.clone()); + } + }; + let mut events = Events::new(&mut sink); + let out = load( + docker, + &mut events, + &mut Target::local(home, machine), + None, + image, + ); + (out, phases) +} + +#[test] +fn pax_and_directory_mtimes_are_normalized_with_valid_checksums() { + let mut pax_dir = pax_record("path", "var/cache/dir/"); + pax_dir.extend_from_slice(&pax_record("mtime", "1700000123.456789")); + pax_dir.extend_from_slice(&pax_record("atime", "1700000123.111")); + let pax_only_mtime = pax_record("mtime", "1700000999.5"); + let pax_file = pax_record("mtime", "1700000555.25"); + + let build = |dir_sec: u64| { + Tar::new() + .at(dir_sec) + .directory("dev/", 0o755) + .directory("etc/", 0o755) + .raw("PaxHeaders/dir1", b'x', 0o644, &pax_dir) + .directory("placeholder-dir", 0o755) + .raw("PaxHeaders/dir2", b'x', 0o644, &pax_only_mtime) + .directory("var/", 0o755) + .at(1_650_000_000) + .raw("PaxHeaders/file1", b'x', 0o644, &pax_file) + .file("etc/app.conf", 0o644, b"hello\n") + .symlink("etc/link", "/etc/app.conf") + .finish() + }; + + let mut out1 = Vec::new(); + Filtered::new(build(1_700_000_010).as_slice()) + .read_to_end(&mut out1) + .unwrap(); + let mut out2 = Vec::new(); + Filtered::new(build(1_700_000_025).as_slice()) + .read_to_end(&mut out2) + .unwrap(); + assert_eq!(out1, out2); + + // Unpack with the real rootfs tar reader to verify every recomputed header + // checksum and directory/file mtime. + let scratch = Scratch::new("lp176-tar-norm"); + let tar_path = scratch.base.join("flat.tar"); + fs::write(&tar_path, &out1).unwrap(); + let id = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; + let (root, unpacked) = + rootfs::ensure_flat(&tar_path, &Image::parse(id).unwrap(), &scratch.cache).unwrap(); + assert!(unpacked); + assert_eq!( + fs::read(root.directory().join("etc/app.conf")).unwrap(), + b"hello\n" + ); + assert!(root.directory().join("var/cache/dir").is_dir()); + let file_mtime = fs::symlink_metadata(root.directory().join("etc/app.conf")) + .unwrap() + .modified() + .unwrap(); + let dir_mtime = fs::symlink_metadata(root.directory().join("etc")) + .unwrap() + .modified() + .unwrap(); + assert_eq!( + file_mtime + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_secs(), + 1_700_000_555 + ); + assert_eq!( + dir_mtime + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_secs(), + 0 + ); +} + +#[test] +fn real_docker_two_exports_over_2s_apart_match_sha_and_resume() { + if !docker_available() { + eprintln!("NOT_RUN: docker unavailable"); + return; + } + let mut img = TestImage::build("resume", false); + let (bytes1, sha1) = + filtered_export(&img.id, &format!("lp176-exp-probe1-{}", std::process::id())); + assert!(bytes1.len() > CHUNK); + std::thread::sleep(Duration::from_millis(2200)); + let (bytes2, sha2) = + filtered_export(&img.id, &format!("lp176-exp-probe2-{}", std::process::id())); + assert_eq!( + sha1, sha2, + "two exports >= 2s apart must yield identical filtered tar SHA-256" + ); + assert_eq!(bytes1, bytes2); + + // Stage the first CHUNK from export 1 into a fresh home, wait >=2s, and + // verify `load()` resumes from offset CHUNK rather than restarting at 0. + let (home, _) = img.make_home("home-resume"); + cache::write(&cache::cache(&home), img.hex(), 0, &bytes1[..CHUNK]).unwrap(); + std::thread::sleep(Duration::from_millis(2200)); + + let docker = real_docker(); + let (loaded, phases) = run_load(&docker, &home, "native", &img.tag); + let loaded = loaded.unwrap(); + assert!(!loaded.reused); + assert_eq!(loaded.size, Some(bytes1.len() as u64)); + let sends: Vec<_> = phases + .iter() + .filter(|p| p.get_text("phase") == Some("send")) + .collect(); + let first_done = sends[0].get_int("done").unwrap(); + assert_eq!( + first_done, CHUNK as i64, + "resume must start sending from staged CHUNK={CHUNK}, got phases={sends:?}" + ); + assert!(owned_containers(&docker, &home).unwrap().is_empty()); +} + +#[test] +fn real_docker_volume_image_leaves_no_anonymous_volumes() { + if !docker_available() { + eprintln!("NOT_RUN: docker unavailable"); + return; + } + let mut img = TestImage::build("volume", true); + let (home, home_id) = img.make_home("home-vol"); + + // Pause a real `load()` mid-send to inspect the exact anonymous volume ID + // created for the container, then let `load()` finish normally and assert + // both container and anonymous volume are gone. + let child = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_load_with_pause", "--nocapture"]) + .env("LP176_PAUSE_HOME", &home) + .env("LP176_PAUSE_MACHINE", "native") + .env("LP176_PAUSE_IMAGE", &img.tag) + .stdout(Stdio::null()) + .stderr(Stdio::piped()) + .spawn() + .unwrap(); + + wait_for("child load to pause in send", || { + home.join("paused").exists() + }); + let docker = real_docker(); + let owned = owned_containers(&docker, &home).unwrap(); + assert_eq!(owned.len(), 1, "expected 1 live owned container: {owned:?}"); + let cname = &owned[0].name; + assert!(cname.starts_with(&format!("layerfs-export-{}-native-", &home_id[..8]))); + let vols = container_volumes(cname); + assert_eq!( + vols.len(), + 1, + "VOLUME /data/vol must create 1 anonymous volume on {cname}" + ); + let vol_id = vols[0].clone(); + assert!(volume_exists(&vol_id)); + + fs::write(home.join("proceed"), b"").unwrap(); + let out = child.wait_with_output().unwrap(); + assert!( + out.status.success(), + "paused load child failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert!( + !container_exists(cname), + "completed load left container {cname}" + ); + assert!( + !volume_exists(&vol_id), + "completed load on VOLUME image leaked anonymous volume {vol_id}" + ); + assert!(owned_containers(&docker, &home).unwrap().is_empty()); +} + +#[test] +fn real_docker_error_and_cancel_clean_container_without_leaks() { + if !docker_available() { + eprintln!("NOT_RUN: docker unavailable"); + return; + } + let mut img = TestImage::build("err-cancel", true); + let (home, _) = img.make_home("home-err"); + let docker = real_docker(); + + // Case A: error during `send` (`.recv-.part` is a directory, so + // `target.step(write)` fails EISDIR after container creation and export). + let cache_dir = cache::cache(&home); + fs::create_dir_all(cache_dir.join(format!(".recv-{}.part", img.hex()))).unwrap(); + let (err, _) = run_load(&docker, &home, "docker", &img.tag); + assert!( + err.is_err(), + "expected write failure when .part is a directory" + ); + assert!( + owned_containers(&docker, &home).unwrap().is_empty(), + "errored load leaked owned container" + ); + fs::remove_dir_all(cache_dir.join(format!(".recv-{}.part", img.hex()))).unwrap(); + + // Case B: simulated cancellation via unwind inside the progress sink after + // the export container has been created and `send` has begun. + let (home_cancel, _) = img.make_home("home-cancel"); + let panicked = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + let mut sink = |event: SdkValue| { + if let Some(p) = event.get("progress") { + if p.get_text("phase") == Some("send") { + panic!("simulated caller cancel"); + } + } + }; + let mut events = Events::new(&mut sink); + let _ = load( + &docker, + &mut events, + &mut Target::local(&home_cancel, "docker"), + None, + &img.tag, + ); + })); + assert!(panicked.is_err()); + assert!( + owned_containers(&docker, &home_cancel).unwrap().is_empty(), + "cancelled load leaked owned container" + ); + assert!( + ImageLock::try_take(&home_cancel, "docker", &img.id) + .unwrap() + .is_some(), + "lock must be released after cancel unwind" + ); +} + +#[test] +fn real_docker_killed_load_enumerates_and_recovers_under_lock() { + if !docker_available() { + eprintln!("NOT_RUN: docker unavailable"); + return; + } + let mut img = TestImage::build("kill", true); + let (home, home_id) = img.make_home("home-kill"); + let docker = real_docker(); + + // 1. Spawn child that creates container, stages >= CHUNK bytes, then pauses. + let mut child1 = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_load_with_pause", "--nocapture"]) + .env("LP176_PAUSE_HOME", &home) + .env("LP176_PAUSE_MACHINE", "docker") + .env("LP176_PAUSE_IMAGE", &img.tag) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(); + wait_for("first killed-to-be child pauses in send", || { + home.join("paused").exists() + }); + + // While child1 is alive and holding ImageLock: + // - owned_containers enumerates its container; + // - ImageLock::try_take returns None; + // - cleanup_owned leaves the active container untouched. + let owned_live = owned_containers(&docker, &home).unwrap(); + assert_eq!(owned_live.len(), 1); + let c1 = owned_live[0].clone(); + assert_eq!(c1.home_id, home_id); + assert_eq!(c1.machine, "docker"); + assert_eq!(c1.image, img.id); + assert!(!c1.nonce.is_empty()); + assert!(c1.name.starts_with(&format!( + "layerfs-export-{}-docker-{}", + &home_id[..8], + c1.nonce + ))); + let vols1 = container_volumes(&c1.name); + assert_eq!(vols1.len(), 1); + let v1 = vols1[0].clone(); + assert!(volume_exists(&v1)); + assert!(ImageLock::try_take(&home, "docker", &img.id) + .unwrap() + .is_none()); + let during_live = cleanup_owned(&docker, &home, None, None).unwrap(); + assert_eq!( + during_live, + Cleanup { + removed: Vec::new(), + active: vec![c1.name.clone()], + } + ); + assert!(container_exists(&c1.name)); + + // Kill child1 (no Drop runs). + child1.kill().unwrap(); + child1.wait().unwrap(); + + // After SIGKILL: residual owned container is still enumerable, and + // cleanup_owned removes both the container and its anonymous volume under I01's lock. + assert_eq!(owned_containers(&docker, &home).unwrap(), vec![c1.clone()]); + let cleaned = cleanup_owned(&docker, &home, None, None).unwrap(); + assert_eq!( + cleaned, + Cleanup { + removed: vec![c1.name.clone()], + active: Vec::new(), + } + ); + assert!(!container_exists(&c1.name)); + assert!(!volume_exists(&v1)); + assert!(owned_containers(&docker, &home).unwrap().is_empty()); + + // 2. Kill a second child after staging CHUNK bytes; verify the next `load()` + // recovers under I01's lock: removes the stale owned container + volume, + // exports with a new nonce container, resumes from CHUNK, and cleans up. + let _ = fs::remove_file(home.join("paused")); + let mut child2 = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_load_with_pause", "--nocapture"]) + .env("LP176_PAUSE_HOME", &home) + .env("LP176_PAUSE_MACHINE", "docker") + .env("LP176_PAUSE_IMAGE", &img.tag) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(); + wait_for("second killed-to-be child pauses in send", || { + home.join("paused").exists() + }); + let c2 = owned_containers(&docker, &home).unwrap().remove(0); + assert_ne!(c2.nonce, c1.nonce); + let v2 = container_volumes(&c2.name)[0].clone(); + child2.kill().unwrap(); + child2.wait().unwrap(); + + std::thread::sleep(Duration::from_millis(2200)); + let (resumed, phases) = run_load(&docker, &home, "docker", &img.tag); + let resumed = resumed.unwrap(); + assert!(!resumed.reused); + let sends: Vec<_> = phases + .iter() + .filter(|p| p.get_text("phase") == Some("send")) + .collect(); + assert!( + sends[0].get_int("done").unwrap() >= CHUNK as i64, + "resumed load after kill must resume from staged bytes: {sends:?}" + ); + assert!(!container_exists(&c2.name)); + assert!(!volume_exists(&v2)); + assert!(owned_containers(&docker, &home).unwrap().is_empty()); +} + +#[test] +fn real_docker_different_homes_do_not_collide_or_delete_each_other() { + if !docker_available() { + eprintln!("NOT_RUN: docker unavailable"); + return; + } + let mut img = TestImage::build("two-homes", true); + let (home1, id1) = img.make_home("home-1"); + let (home2, id2) = img.make_home("home-2"); + assert_ne!(id1, id2); + let docker = real_docker(); + + // Leave a residual container from home1 (via killed helper, plus an old + // `layerfs.export.started=1` container owned by home1). + let mut child = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_load_with_pause", "--nocapture"]) + .env("LP176_PAUSE_HOME", &home1) + .env("LP176_PAUSE_MACHINE", "docker") + .env("LP176_PAUSE_IMAGE", &img.tag) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(); + wait_for("home1 child pauses in send", || { + home1.join("paused").exists() + }); + let owned1 = owned_containers(&docker, &home1).unwrap(); + assert_eq!(owned1.len(), 1); + let c1 = owned1[0].name.clone(); + let v1 = container_volumes(&c1)[0].clone(); + child.kill().unwrap(); + child.wait().unwrap(); + + // Also create an aged container labeled for home1 to ensure STALE_SECS + // age-based sweeping is gone. + let aged_c1 = format!("layerfs-export-{}-docker-0000000000000001", &id1[..8]); + let out = Command::new("docker") + .args([ + "create", + "--name", + &aged_c1, + "--label", + &format!("layerfs.role={EXPORT_ROLE}"), + "--label", + &format!("layerfs.home={id1}"), + "--label", + "layerfs.machine=docker", + "--label", + &format!("layerfs.image={}", img.id), + "--label", + "layerfs.export.nonce=0000000000000001", + "--label", + "layerfs.export.started=1", + "--network", + "none", + "--entrypoint", + "/layerfs-export", + &img.id, + ]) + .output() + .unwrap(); + assert!(out.status.success()); + + // home2 neither sees nor deletes home1's containers. + assert!(owned_containers(&docker, &home2).unwrap().is_empty()); + assert_eq!( + cleanup_owned(&docker, &home2, None, None).unwrap(), + Cleanup::default() + ); + let (loaded2, _) = run_load(&docker, &home2, "docker", &img.tag); + loaded2.unwrap(); + assert!(container_exists(&c1), "home2 must not delete home1's {c1}"); + assert!( + container_exists(&aged_c1), + "home2 must not delete aged container {aged_c1} of home1" + ); + + // home1's own cleanup enumerates and removes both of home1's containers + // and their anonymous volumes. + let cleaned = cleanup_owned(&docker, &home1, None, None).unwrap(); + assert_eq!(cleaned.removed.len(), 2); + assert!(!container_exists(&c1)); + assert!(!volume_exists(&v1)); + assert!(!container_exists(&aged_c1)); +} + +/// Helper process used by the kill/volume tests: runs real `load()`, signals +/// `/paused` once `send` reaches `done >= CHUNK` (so `.part` has data +/// and the container + volume exist in Docker), and waits for `/proceed`. +#[test] +fn helper_load_with_pause() { + let Ok(home) = std::env::var("LP176_PAUSE_HOME") else { + return; + }; + let home = PathBuf::from(home); + let machine = std::env::var("LP176_PAUSE_MACHINE").unwrap(); + let image = std::env::var("LP176_PAUSE_IMAGE").unwrap(); + let docker = real_docker(); + let mut paused = false; + let mut sink = |event: SdkValue| { + if !paused { + if let Some(p) = event.get("progress") { + if p.get_text("phase") == Some("send") + && p.get_int("done").unwrap_or(0) >= CHUNK as i64 + { + paused = true; + fs::write(home.join("paused"), b"").unwrap(); + while !home.join("proceed").exists() { + std::thread::sleep(Duration::from_millis(20)); + } + } + } + } + }; + let mut events = Events::new(&mut sink); + load( + &docker, + &mut events, + &mut Target::local(&home, &machine), + None, + &image, + ) + .unwrap(); +} diff --git a/docs/architecture/api/sdk/machine.md b/docs/architecture/api/sdk/machine.md index d871d7d76..1efb83d26 100644 --- a/docs/architecture/api/sdk/machine.md +++ b/docs/architecture/api/sdk/machine.md @@ -216,12 +216,17 @@ machine's free bytes are checked before anything is created on either side: `Capacity` `{needed, free, where}` refuses a machine too small for the copy, with no export container, no staged byte and no cache folder, `needed` counting the bytes a resumed copy already staged once and `where` the -filesystem `probe` measured. Only then does the host create the export -container `layerfs-export--` (one per image and machine, -removed once the machine publishes the image) and stream `docker export` -without the init layer's files (`.dockerenv`, `etc/hosts`, `etc/hostname`, -`etc/resolv.conf`, `etc/mtab`, `dev/*`) and device or FIFO entries in 1 MiB -`image.artifact` frames to `.recv-.part`; the machine checks its size and sha256, unpacks it +filesystem `probe` measured. Only then does the host create an exclusive export +container `layerfs-export---` (labeled with +`layerfs.role=image-export`, `layerfs.home`, `layerfs.machine`, `layerfs.image` +and `layerfs.export.nonce`, removed with its anonymous volumes on exit or +error, and recoverable under `ImageLock` via `owned_containers` / +`cleanup_owned` if killed) and stream `docker export` without the init layer's +files (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, `etc/mtab`, +`dev/*`), device or FIFO entries, and with directory modification times +normalized (header checksum recomputed, so exports separated in time are +byte-identical for resume) in 1 MiB `image.artifact` frames to `.recv-.part`; +the machine checks its size and sha256, unpacks it once into `.2/`, writes the sidecar and deletes the staged tar. A staged tar left by a copy that is not running is resumed when its bytes hash as this export's prefix, else restarted; `size` is the bytes sent, else the sidecar's, diff --git a/docs/versioned/2.0.0/calls.md b/docs/versioned/2.0.0/calls.md index a134d3edb..8efa091cb 100644 --- a/docs/versioned/2.0.0/calls.md +++ b/docs/versioned/2.0.0/calls.md @@ -259,8 +259,11 @@ $ printf '%s' '[{"op":"write","path":"/b.txt","content":"b\\n"},{"op":"mkdir","p `{needed, free, where}` when `2 × size × 1.05`, less the bytes a resumed copy already staged, is over the machine's free bytes (`size`: what the image's layers unpack to, the sum of `docker history`'s layer sizes), - and otherwise exported once (`docker create` + `docker export`, without - the init layer's files), sent in 1 MiB frames and unpacked on the + and otherwise exported once into an exclusive per-export container (`docker + create` + `docker export`, without the init layer's files and with directory + mtimes normalized so resume across separate exports sees identical bytes; the + container and its anonymous volumes are removed on completion or error), sent + in 1 MiB frames and unpacked on the machine under `machines/native/run/images/.2/` with a sidecar `.2.json`; the staged tar is deleted. Docker unreachable is `Unavailable` `{what: "docker"}`, the machine stopped `Unavailable` From 464dd6d2bf04c066d655e7765a702980982a5e0f Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 17 Nov 2026 04:16:08 +0000 Subject: [PATCH 3/8] fix(sandbox): reclaim home export containers on load and report cleanup failures - Wire cleanup_owned(docker, home, None, None) into load() under ImageLock after clearing the current (machine, image) residuals so killed exports from other images or machines in the same home are reclaimed without waiting on active locks. - Make remove_container return whether the container and its anonymous volumes were actually removed (treating Missing as gone and checking container inspect + volume rm), add Cleanup.failed, and route failed removals to Cleanup.failed instead of Cleanup.removed. - Add tests: real Docker M1 test verifying load() on a different image and machine reclaims a SIGKILLed container and its anonymous volume without touching a concurrent active load; S2 fake-docker tests for rm failure and volume rm failure; S4 byte-level image_tar tests for empty PAX blocks, malformed length fields, time-only PAX blocks dropped, and mixed time + SCHILY.xattr.* blocks. - Update docs/architecture/api/sdk/machine.md and docs/versioned/2.0.0/calls.md to document epoch 0 (1970-01-01) directory mtime normalization, SIGKILL recovery on the next load in the same home, and manual docker rm for legacy layerfs-export-- containers. Tests: cargo +1.85.1 fmt -p layerfs-sandbox -- --check, clippy --locked -p layerfs-sandbox --all-targets -- -D warnings, tests/lp176_image_export.rs (9), tests/lp176_image_lock.rs (7), tests/image_copy.rs (9), tests/image_tar.rs (5), tools/check_product_boundary.py, tools unittest (180) pass. Deleted tests: none. Docs: updated docs/architecture/api/sdk/machine.md and docs/versioned/2.0.0/calls.md. Production LOC: 170,091 -> 170,118 (delta +27; cumulative from 83843c31c: +339) core 39,795 -> 39,795 (0) engine 75,102 -> 75,102 (0) control 48,848 -> 48,875 (+27) layerfs-sandbox +27 api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on e6e05eab9 and this tree --- .../crates/layerfs-sandbox/src/image_load.rs | 102 +++++++---- .../crates/layerfs-sandbox/tests/image_tar.rs | 94 ++++++++++ .../tests/lp176_image_export.rs | 173 ++++++++++++++++++ docs/architecture/api/sdk/machine.md | 13 +- docs/versioned/2.0.0/calls.md | 10 +- 5 files changed, 350 insertions(+), 42 deletions(-) diff --git a/control/crates/layerfs-sandbox/src/image_load.rs b/control/crates/layerfs-sandbox/src/image_load.rs index 1e4a78d87..b8191ff2d 100644 --- a/control/crates/layerfs-sandbox/src/image_load.rs +++ b/control/crates/layerfs-sandbox/src/image_load.rs @@ -2,8 +2,8 @@ //! `machine.load`; R1, R3): the image named by digest, Docker Id or Docker //! reference is resolved, and when the machine does not hold it yet, it is //! exported from the host's Docker as one flat root filesystem tar -//! ([`crate::image_tar`], with directory mtimes normalized so exports >=2 s -//! apart are byte-identical for resume), sent in 1 MiB frames and unpacked +//! ([`crate::image_tar`], with directory mtimes normalized to epoch 0 so exports +//! >=2 s apart are byte-identical for resume), sent in 1 MiB frames and unpacked //! once there ([`crate::image_artifact`]). The machine is asked first, so an //! image it holds needs neither Docker nor a byte sent. One copy per image and //! machine at a time: the second one waits in [`ImageLock`], and a copy whose @@ -11,8 +11,8 @@ //! container (`layerfs-export---`) labeled with the //! home, machine, image and nonce, and removes only that container and its //! anonymous volumes on exit or error; residual containers of this home left -//! by killed copies can be enumerated ([`owned_containers`]) and removed -//! under [`ImageLock`] ([`cleanup_owned`]). Progress phases are `inspect`, +//! by killed copies can be enumerated ([`owned_containers`]) and are reclaimed +//! under [`ImageLock`] via [`cleanup_owned`] on subsequent loads in that home. Progress phases are `inspect`, //! `lock` (`waiting: "lock"` while another copy holds it), `export`, `send` //! (`done`/`total` bytes) and `unpack`. use crate::deploy::Side; @@ -243,6 +243,10 @@ pub fn load( remove_container(docker, &entry.name); } } + // Reclaim any other unheld residual export containers in this home + // (such as killed loads for other images or machines) without waiting + // on another copy's lock. + let _ = cleanup_owned(docker, target.home(), None, None); } probe = target.probe(Some(id), None, archive)?; if held(&probe) { @@ -482,6 +486,8 @@ pub struct Cleanup { pub removed: Vec, /// Container names left alone because a live copy holds their [`ImageLock`]. pub active: Vec, + /// Container names (or their anonymous volumes) that failed to be removed. + pub failed: Vec, } /// Reads `home`'s 32-hex id without creating files when `home` is empty. @@ -620,8 +626,11 @@ pub fn cleanup_owned( match ImageLock::try_take(home, &m, &img)? { Some(_lock) => { for name in names { - remove_container(docker, &name); - out.removed.push(name); + if remove_container(docker, &name) { + out.removed.push(name); + } else { + out.failed.push(name); + } } } None => out.active.extend(names), @@ -752,44 +761,67 @@ fn create_container( result.map(drop).map_err(|f| f.refusal(id)) } -fn remove_container(docker: &Docker, name: &str) { +fn is_missing_error(err: &Failure) -> bool { + if matches!(err, Failure::Missing(_)) { + return true; + } + let lower = err.message().to_lowercase(); + lower.contains("no such container") || lower.contains("no such volume") +} + +fn remove_container(docker: &Docker, name: &str) -> bool { // Remove the created export container together with its anonymous volumes. let _ = docker.read(&["rm", "-v", name], docker::READ); // If still present (for instance with a stand-in `docker` that only handles // `rm -f `, or a container requiring force), clean volumes then `-f`. - if docker - .read( - &["container", "inspect", "--format", "{{.Id}}", name], - docker::READ, - ) - .is_ok() - { - let volumes = anonymous_volumes(docker, name); + match docker.read( + &["container", "inspect", "--format", "{{.Id}}", name], + docker::READ, + ) { + Err(err) if is_missing_error(&err) => return true, + Err(_) => return false, + Ok(_) => {} + } + let Some(volumes) = anonymous_volumes(docker, name) else { let _ = docker.read(&["rm", "-f", name], docker::READ); - for volume in volumes { - let _ = docker.read(&["volume", "rm", &volume], docker::READ); + return false; + }; + if let Err(err) = docker.read(&["rm", "-f", name], docker::READ) { + if !is_missing_error(&err) { + return false; + } + } + let mut removed = true; + for volume in volumes { + if let Err(err) = docker.read(&["volume", "rm", &volume], docker::READ) { + if !is_missing_error(&err) { + removed = false; + } } } + removed } -fn anonymous_volumes(docker: &Docker, name: &str) -> Vec { - let Ok(out) = docker.read( - &[ - "container", - "inspect", - "--format", - "{{range .Mounts}}{{if eq .Type \"volume\"}}{{.Name}}{{\"\\n\"}}{{end}}{{end}}", - name, - ], - docker::READ, - ) else { - return Vec::new(); - }; - out.lines() - .map(str::trim) - .filter(|v| v.len() == 64 && v.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f'))) - .map(str::to_owned) - .collect() +fn anonymous_volumes(docker: &Docker, name: &str) -> Option> { + let out = docker + .read( + &[ + "container", + "inspect", + "--format", + "{{range .Mounts}}{{if eq .Type \"volume\"}}{{.Name}}{{\"\\n\"}}{{end}}{{end}}", + name, + ], + docker::READ, + ) + .ok()?; + Some( + out.lines() + .map(str::trim) + .filter(|v| v.len() == 64 && v.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f'))) + .map(str::to_owned) + .collect(), + ) } struct ExportChild(Option); diff --git a/control/crates/layerfs-sandbox/tests/image_tar.rs b/control/crates/layerfs-sandbox/tests/image_tar.rs index edeb372bd..87c01b48b 100644 --- a/control/crates/layerfs-sandbox/tests/image_tar.rs +++ b/control/crates/layerfs-sandbox/tests/image_tar.rs @@ -95,3 +95,97 @@ fn two_exports_differing_only_in_the_init_layer_filter_to_the_same_bytes() { }; assert_eq!(filtered(&base(b"abc\n")), filtered(&base(b"defg\n"))); } + +#[test] +fn pax_time_stripping_handles_empty_malformed_xattr_and_all_time_blocks_byte_for_byte() { + // 1. Empty PAX `x` block: kept intact (header mtime zeroed on directories, untouched on files). + let empty_pax_dir = Tar::new() + .at(1_700_000_123) + .raw("PaxHeaders/empty", b'x', 0o644, b"") + .directory("dir/", 0o755) + .raw("PaxHeaders/emptyf", b'x', 0o644, b"") + .file("file.txt", 0o644, b"ok") + .finish(); + let expected_empty_pax = Tar::new() + .at(0) + .raw("PaxHeaders/empty", b'x', 0o644, b"") + .directory("dir/", 0o755) + .at(1_700_000_123) + .raw("PaxHeaders/emptyf", b'x', 0o644, b"") + .file("file.txt", 0o644, b"ok") + .finish(); + assert_eq!(filtered(&empty_pax_dir), expected_empty_pax); + + // 2. Malformed PAX length fields: missing space, non-numeric, length <= space + 1, length > rest.len(). + for malformed in [ + b"mtime=1700000000\n".as_slice(), + b"abc mtime=1700000000\n".as_slice(), + b"2 mtime=1\n".as_slice(), + b"0 a=b\n".as_slice(), + b"999 mtime=1700000000\n".as_slice(), + ] { + let input = Tar::new() + .at(1_700_000_456) + .raw("PaxHeaders/bad", b'x', 0o644, malformed) + .directory("dir/", 0o755) + .finish(); + let expected = Tar::new() + .at(0) + .raw("PaxHeaders/bad", b'x', 0o644, malformed) + .directory("dir/", 0o755) + .finish(); + assert_eq!(filtered(&input), expected); + } + + // 3. PAX `x` block with only time records (mtime, atime, ctime) becomes empty -> entire `x` block dropped. + let mut only_times = pax_record("mtime", "1700000001.1"); + only_times.extend_from_slice(&pax_record("atime", "1700000002.2")); + only_times.extend_from_slice(&pax_record("ctime", "1700000003.3")); + let input_only_times = Tar::new() + .at(1_700_000_789) + .raw("PaxHeaders/times", b'x', 0o644, &only_times) + .directory("dir/", 0o755) + .finish(); + let expected_only_times = Tar::new().at(0).directory("dir/", 0o755).finish(); + assert_eq!(filtered(&input_only_times), expected_only_times); + + // 4. PAX `x` block mixing times with SCHILY.xattr.* (and path): only time records are stripped on + // directories while SCHILY.xattr.* stays intact; regular files keep all PAX records untouched. + let xattr_cap = pax_record("SCHILY.xattr.security.capability", "cap_net_bind"); + let xattr_user = pax_record("SCHILY.xattr.user.note", "kept-value"); + let dir_path = pax_record("path", "var/with-xattr/"); + + let mut mixed_dir_pax = Vec::new(); + mixed_dir_pax.extend_from_slice(&dir_path); + mixed_dir_pax.extend_from_slice(&pax_record("mtime", "1700000100.5")); + mixed_dir_pax.extend_from_slice(&xattr_cap); + mixed_dir_pax.extend_from_slice(&pax_record("atime", "1700000200.5")); + mixed_dir_pax.extend_from_slice(&pax_record("ctime", "1700000300.5")); + mixed_dir_pax.extend_from_slice(&xattr_user); + + let mut expected_dir_pax = Vec::new(); + expected_dir_pax.extend_from_slice(&dir_path); + expected_dir_pax.extend_from_slice(&xattr_cap); + expected_dir_pax.extend_from_slice(&xattr_user); + + let mut mixed_file_pax = pax_record("mtime", "1700000555.25"); + mixed_file_pax.extend_from_slice(&xattr_user); + + let input_mixed = Tar::new() + .at(1_700_000_111) + .raw("PaxHeaders/mixed_dir", b'x', 0o644, &mixed_dir_pax) + .directory("placeholder-dir", 0o755) + .at(1_700_000_222) + .raw("PaxHeaders/mixed_file", b'x', 0o644, &mixed_file_pax) + .file("usr/bin/app", 0o755, b"elf") + .finish(); + let expected_mixed = Tar::new() + .at(0) + .raw("PaxHeaders/mixed_dir", b'x', 0o644, &expected_dir_pax) + .directory("placeholder-dir", 0o755) + .at(1_700_000_222) + .raw("PaxHeaders/mixed_file", b'x', 0o644, &mixed_file_pax) + .file("usr/bin/app", 0o755, b"elf") + .finish(); + assert_eq!(filtered(&input_mixed), expected_mixed); +} diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_export.rs b/control/crates/layerfs-sandbox/tests/lp176_image_export.rs index b90e0543c..52ed31c42 100644 --- a/control/crates/layerfs-sandbox/tests/lp176_image_export.rs +++ b/control/crates/layerfs-sandbox/tests/lp176_image_export.rs @@ -617,6 +617,7 @@ fn real_docker_killed_load_enumerates_and_recovers_under_lock() { Cleanup { removed: Vec::new(), active: vec![c1.name.clone()], + failed: Vec::new(), } ); assert!(container_exists(&c1.name)); @@ -634,6 +635,7 @@ fn real_docker_killed_load_enumerates_and_recovers_under_lock() { Cleanup { removed: vec![c1.name.clone()], active: Vec::new(), + failed: Vec::new(), } ); assert!(!container_exists(&c1.name)); @@ -760,11 +762,182 @@ fn real_docker_different_homes_do_not_collide_or_delete_each_other() { // and their anonymous volumes. let cleaned = cleanup_owned(&docker, &home1, None, None).unwrap(); assert_eq!(cleaned.removed.len(), 2); + assert!(cleaned.failed.is_empty()); assert!(!container_exists(&c1)); assert!(!volume_exists(&v1)); assert!(!container_exists(&aged_c1)); } +#[test] +fn real_docker_load_reclaims_killed_other_image_and_machine_without_touching_active() { + if !docker_available() { + eprintln!("NOT_RUN: docker unavailable"); + return; + } + let mut img_killed = TestImage::build("m1-killed", true); + let mut img_active = TestImage::build("m1-active", true); + let mut img_next = TestImage::build("m1-next", false); + let (home, _) = img_killed.make_home("home-m1"); + let home_id = home::ensure(&home).unwrap().id; + img_active.homes.push(home_id.clone()); + img_next.homes.push(home_id); + let docker = real_docker(); + + // 1. SIGKILL a load on (machine="docker", img_killed), leaving container + anonymous volume. + let mut killed_child = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_load_with_pause", "--nocapture"]) + .env("LP176_PAUSE_HOME", &home) + .env("LP176_PAUSE_MACHINE", "docker") + .env("LP176_PAUSE_IMAGE", &img_killed.tag) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(); + wait_for("killed-to-be load pauses in send", || { + home.join("paused").exists() + }); + let killed_owned = owned_containers(&docker, &home).unwrap(); + assert_eq!(killed_owned.len(), 1); + let c_killed = killed_owned[0].clone(); + let v_killed = container_volumes(&c_killed.name)[0].clone(); + assert!(volume_exists(&v_killed)); + killed_child.kill().unwrap(); + killed_child.wait().unwrap(); + fs::remove_file(home.join("paused")).unwrap(); + + // 2. Keep a second load actively paused on (machine="lima", img_active). + let active_child = Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_load_with_pause", "--nocapture"]) + .env("LP176_PAUSE_HOME", &home) + .env("LP176_PAUSE_MACHINE", "lima") + .env("LP176_PAUSE_IMAGE", &img_active.tag) + .stdout(Stdio::null()) + .stderr(Stdio::piped()) + .spawn() + .unwrap(); + wait_for("active load pauses in send", || { + home.join("paused").exists() + }); + let c_active = owned_containers(&docker, &home) + .unwrap() + .into_iter() + .find(|c| c.image == img_active.id) + .expect("active container present"); + let v_active = container_volumes(&c_active.name)[0].clone(); + + // 3. Run a normal load on a DIFFERENT image and machine ("native", img_next): + // it must automatically reclaim c_killed + v_killed while leaving c_active + v_active intact. + let (loaded, _) = run_load(&docker, &home, "native", &img_next.tag); + assert!(!loaded.unwrap().reused); + assert!( + !container_exists(&c_killed.name), + "load() must reclaim killed container {} from other image/machine", + c_killed.name + ); + assert!( + !volume_exists(&v_killed), + "load() must reclaim anonymous volume {v_killed} of killed container" + ); + assert!( + container_exists(&c_active.name), + "load() must not delete active container {}", + c_active.name + ); + assert!( + volume_exists(&v_active), + "load() must not delete active volume {v_active}" + ); + assert_eq!( + owned_containers(&docker, &home).unwrap(), + vec![c_active.clone()] + ); + + // 4. Let active_child finish and verify full cleanup. + fs::write(home.join("proceed"), b"").unwrap(); + let out = active_child.wait_with_output().unwrap(); + assert!( + out.status.success(), + "active load child failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert!(!container_exists(&c_active.name)); + assert!(!volume_exists(&v_active)); + assert!(owned_containers(&docker, &home).unwrap().is_empty()); +} + +#[test] +fn cleanup_owned_reports_failed_when_removal_fails() { + use std::os::unix::fs::PermissionsExt; + + let scratch = Scratch::new("lp176-cleanup-fail"); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + let home_id = home::ensure(&home).unwrap().id; + let cname = format!("layerfs-export-{}-docker-deadbeef00000001", &home_id[..8]); + let img_id = "sha256:1111111111111111111111111111111111111111111111111111111111111111"; + let vol_id = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; + + // Case 1: `rm -v` and `rm -f` both fail while `container inspect` confirms container remains. + let bin_rm_fail = scratch.base.join("docker-rm-fail"); + let script_rm_fail = format!( + "#!/bin/sh\n\ + case \"$1 $2\" in\n\ + \"ps -a\") printf '%s\\t%s\\tdocker\\t%s\\tdeadbeef00000001\\n' '{cname}' '{home_id}' '{img_id}'; exit 0 ;;\n\ + \"container inspect\")\n\ + case \"$*\" in\n\ + *Mounts*) exit 0 ;;\n\ + *) echo id; exit 0 ;;\n\ + esac ;;\n\ + esac\n\ + case \"$1\" in\n\ + rm) echo 'permission denied' >&2; exit 1 ;;\n\ + *) exit 2 ;;\n\ + esac\n" + ); + fs::write(&bin_rm_fail, script_rm_fail).unwrap(); + fs::set_permissions(&bin_rm_fail, fs::Permissions::from_mode(0o755)).unwrap(); + let res1 = cleanup_owned(&Docker::at(Some(bin_rm_fail), None), &home, None, None).unwrap(); + assert_eq!( + res1, + Cleanup { + removed: Vec::new(), + active: Vec::new(), + failed: vec![cname.clone()], + } + ); + + // Case 2: `rm -v` fails, `rm -f` succeeds, but `volume rm` fails on an anonymous volume. + let bin_vol_fail = scratch.base.join("docker-vol-fail"); + let script_vol_fail = format!( + "#!/bin/sh\n\ + case \"$1 $2\" in\n\ + \"ps -a\") printf '%s\\t%s\\tdocker\\t%s\\tdeadbeef00000001\\n' '{cname}' '{home_id}' '{img_id}'; exit 0 ;;\n\ + \"container inspect\")\n\ + case \"$*\" in\n\ + *Mounts*) echo '{vol_id}'; exit 0 ;;\n\ + *) echo id; exit 0 ;;\n\ + esac ;;\n\ + \"volume rm\") echo 'volume in use' >&2; exit 1 ;;\n\ + esac\n\ + case \"$1 $2\" in\n\ + \"rm -v\") echo 'cannot remove volume' >&2; exit 1 ;;\n\ + \"rm -f\") exit 0 ;;\n\ + esac\n\ + exit 2\n" + ); + fs::write(&bin_vol_fail, script_vol_fail).unwrap(); + fs::set_permissions(&bin_vol_fail, fs::Permissions::from_mode(0o755)).unwrap(); + let res2 = cleanup_owned(&Docker::at(Some(bin_vol_fail), None), &home, None, None).unwrap(); + assert_eq!( + res2, + Cleanup { + removed: Vec::new(), + active: Vec::new(), + failed: vec![cname], + } + ); +} + /// Helper process used by the kill/volume tests: runs real `load()`, signals /// `/paused` once `send` reaches `done >= CHUNK` (so `.part` has data /// and the container + volume exist in Docker), and waits for `/proceed`. diff --git a/docs/architecture/api/sdk/machine.md b/docs/architecture/api/sdk/machine.md index 1efb83d26..e25ac270c 100644 --- a/docs/architecture/api/sdk/machine.md +++ b/docs/architecture/api/sdk/machine.md @@ -220,12 +220,17 @@ filesystem `probe` measured. Only then does the host create an exclusive export container `layerfs-export---` (labeled with `layerfs.role=image-export`, `layerfs.home`, `layerfs.machine`, `layerfs.image` and `layerfs.export.nonce`, removed with its anonymous volumes on exit or -error, and recoverable under `ImageLock` via `owned_containers` / -`cleanup_owned` if killed) and stream `docker export` without the init layer's +error; any residual containers left by a `SIGKILL`ed copy are reclaimed under +`ImageLock` on the next `load` in the same home via `cleanup_owned` without +waiting on active locks, and can also be enumerated via `owned_containers`; +legacy `layerfs-export--` containers labeled +`layerfs.export.started` are no longer swept automatically and require manual +`docker rm`) and stream `docker export` without the init layer's files (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, `etc/mtab`, `dev/*`), device or FIFO entries, and with directory modification times -normalized (header checksum recomputed, so exports separated in time are -byte-identical for resume) in 1 MiB `image.artifact` frames to `.recv-.part`; +normalized to epoch 0 (`1970-01-01T00:00:00Z`, PAX time records stripped and +header checksum recomputed, so exports separated in time are byte-identical for +resume) in 1 MiB `image.artifact` frames to `.recv-.part`; the machine checks its size and sha256, unpacks it once into `.2/`, writes the sidecar and deletes the staged tar. A staged tar left by a copy that is not running is resumed when its bytes hash as this diff --git a/docs/versioned/2.0.0/calls.md b/docs/versioned/2.0.0/calls.md index 8efa091cb..2229f4d1e 100644 --- a/docs/versioned/2.0.0/calls.md +++ b/docs/versioned/2.0.0/calls.md @@ -261,9 +261,13 @@ $ printf '%s' '[{"op":"write","path":"/b.txt","content":"b\\n"},{"op":"mkdir","p image's layers unpack to, the sum of `docker history`'s layer sizes), and otherwise exported once into an exclusive per-export container (`docker create` + `docker export`, without the init layer's files and with directory - mtimes normalized so resume across separate exports sees identical bytes; the - container and its anonymous volumes are removed on completion or error), sent - in 1 MiB frames and unpacked on the + mtimes normalized to epoch 0 (`1970-01-01`) so resume across separate exports + sees identical bytes; the container and its anonymous volumes are removed on + completion or error, and any residual containers left after `SIGKILL` are + reclaimed under `ImageLock` on the next `load` in the same home without + waiting on active locks; legacy `layerfs-export--` containers + labeled `layerfs.export.started` are no longer swept and require manual + `docker rm`), sent in 1 MiB frames and unpacked on the machine under `machines/native/run/images/.2/` with a sidecar `.2.json`; the staged tar is deleted. Docker unreachable is `Unavailable` `{what: "docker"}`, the machine stopped `Unavailable` From a5616c8c72e20e7dec4f6b2a013184bace5d30e1 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 17 Nov 2026 11:07:47 +0000 Subject: [PATCH 4/8] sandbox: image recovery, staged listing, lock/InUse prune, and tar sparse/hardlink safety (#176 I03) Production LOC: - core: 39795 -> 39795 (+0) - engine: 75102 -> 75102 (+0) - control: 48875 -> 49834 (+959, layerfs-sandbox 13322 -> 14281) - api: 6346 -> 6346 (+0) - total: 170118 -> 171077 (+959) Test plan: lp176_image_recovery, image_tar, image_copy, lp176_image_lock, lp176_image_export, fmt, clippy, check_product_boundary.py, tools unittests, lf-ci.sh fast. --- .../layerfs-sandbox/src/image_artifact.rs | 271 +++- .../crates/layerfs-sandbox/src/image_tar.rs | 683 +++++++- control/crates/layerfs-sandbox/src/images.rs | 409 ++++- .../tests/lp176_image_recovery.rs | 1390 +++++++++++++++++ docs/architecture/api/sdk/machine.md | 49 +- docs/versioned/2.0.0/calls.md | 6 +- 6 files changed, 2631 insertions(+), 177 deletions(-) create mode 100644 control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs diff --git a/control/crates/layerfs-sandbox/src/image_artifact.rs b/control/crates/layerfs-sandbox/src/image_artifact.rs index 80b02d5fb..4cc7c65db 100644 --- a/control/crates/layerfs-sandbox/src/image_artifact.rs +++ b/control/crates/layerfs-sandbox/src/image_artifact.rs @@ -12,6 +12,7 @@ //! staged file's age. use crate::deploy::{self, Side}; use crate::host::Deploy; +use crate::images::{lowers, refused_with}; use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::home::{self, paths}; use layerfs_home::outcome::{failed, refused, Outcome}; @@ -45,18 +46,32 @@ pub fn cache(root: &Path) -> PathBuf { rootfs::cache(&paths::run_root(root)) } -/// Whether `deploy`'s runtime root already holds `image` unpacked: an image -/// copied from Docker needs no archive then. +/// Whether `deploy`'s runtime root already holds `image` unpacked and published +/// (both `.2` and its sidecar `.2.json`): an image copied from +/// Docker needs no archive then, and an interrupted unpack without a sidecar is +/// not treated as ready. pub fn unpacked(deploy: &Deploy, image: &Image) -> bool { deploy.local_dir.as_deref().is_some_and(|dir| { - rootfs::cache(Path::new(dir)) - .join(format!("{}.2", image.hex())) - .is_dir() + let cache = rootfs::cache(Path::new(dir)); + let hex = image.hex(); + cache.join(format!("{hex}.2")).is_dir() && matches!(Sidecar::read(&cache, hex), Ok(Some(_))) }) } +/// Whether `value` is a 64-character lowercase SHA-256 hex digest. +pub fn is_hex(value: &str) -> bool { + hex(value) +} + +/// The 64-character lowercase digest hex of a staged part filename +/// (`.recv-.part`). +pub fn part_hex(name: &str) -> Option<&str> { + let digest_hex = name.strip_prefix(".recv-")?.strip_suffix(".part")?; + hex(digest_hex).then_some(digest_hex) +} + /// The staged tar of image `hex` while it is received. -fn part(cache: &Path, hex: &str) -> PathBuf { +pub fn part(cache: &Path, hex: &str) -> PathBuf { cache.join(format!(".recv-{hex}.part")) } @@ -151,6 +166,43 @@ impl Sidecar { } } +/// Extended sidecar record keeping optional `variant` alongside [`Sidecar`]. +#[derive(Clone, Debug, PartialEq)] +pub struct SidecarInfo { + /// Core sidecar metadata stored in `.2.json`. + pub sidecar: Sidecar, + /// Image variant (`v8`, ...), recorded only and never applied. + pub variant: Option, +} + +impl SidecarInfo { + /// Its JSON record, including optional `variant` and `config`. + pub fn to_value(&self) -> SdkValue { + let opt_text = |v: &Option| v.clone().map_or(SdkValue::Null, SdkValue::Text); + home::with_field(self.sidecar.to_value(), "variant", opt_text(&self.variant)) + } + + /// Reads one from its JSON record; `None` when it names no valid Id. + pub fn from_value(value: &SdkValue) -> Option { + let sidecar = Sidecar::from_value(value)?; + let variant = value.get_text("variant").map(str::to_owned); + Some(Self { sidecar, variant }) + } + + /// The extended sidecar of image `hex` in `cache`, if there is one. + pub fn read(cache: &Path, hex: &str) -> Result, SdkRefusal> { + Ok(home::read_record(&sidecar_path(cache, hex))? + .as_ref() + .and_then(Self::from_value)) + } + + /// Writes it beside its image's directory (one rename). + pub fn write(&self, cache: &Path) -> Result<(), SdkRefusal> { + let hex = &self.sidecar.id["sha256:".len()..]; + home::write_record(&sidecar_path(cache, hex), &self.to_value()) + } +} + /// The text items of a list value. pub fn texts(value: Option<&SdkValue>) -> Vec { match value { @@ -202,20 +254,23 @@ pub fn touch(side: &Side<'_>, archive: Option<&str>, image: &str) -> Result<(), if !cache.join(format!("{hex}.2")).is_dir() { return Ok(()); } - let mut sidecar = match Sidecar::read(&cache, hex)? { - Some(sidecar) => sidecar, - None => from_archive(side, archive, image)?.unwrap_or(Sidecar { - id: image.to_owned(), - refs: Vec::new(), - size: None, - architecture: None, - source: "bundle".to_owned(), - config: SdkValue::Null, - last_used: None, - }), + let mut info = match SidecarInfo::read(&cache, hex)? { + Some(info) => info, + None => SidecarInfo { + sidecar: from_archive(side, archive, image)?.unwrap_or(Sidecar { + id: image.to_owned(), + refs: Vec::new(), + size: None, + architecture: None, + source: "bundle".to_owned(), + config: SdkValue::Null, + last_used: None, + }), + variant: None, + }, }; - sidecar.last_used = Some(utc(home::now_ms())); - sidecar.write(&cache) + info.sidecar.last_used = Some(utc(home::now_ms())); + info.write(&cache) } /// What the archive a Sandbox of `side` reads (`archive`, the machine's own, @@ -342,17 +397,33 @@ fn probe(side: &Side<'_>, cache: &Path, id: Option<&str>, args: &SdkValue) -> Ou return Ok(SdkValue::Map(out)); }; let hex = &id["sha256:".len()..]; + let dir_ready = cache.join(format!("{hex}.2")).is_dir(); + let info = SidecarInfo::read(cache, hex)?; // an archive that cannot be found or read holds nothing - let present = cache.join(format!("{hex}.2")).is_dir() - || deploy::archive(side, args.get_text("archive")) - .ok() - .and_then(|archive| rootfs::images(&archive).ok()) - .is_some_and(|entries| entries.iter().any(|e| e.digest.as_str() == id)); + let in_archive = deploy::archive(side, args.get_text("archive")) + .ok() + .and_then(|archive| rootfs::images(&archive).ok()) + .is_some_and(|entries| entries.iter().any(|e| e.digest.as_str() == id)); + // Interrupted publish (renamed `.2` without `.2.json`, and not from + // an archive) stays unpublished so recovery removes the stranded dir and + // republishes cleanly under lock. + let present = (dir_ready && info.is_some()) || in_archive; out.push(("id".to_owned(), SdkValue::text(&id))); out.push(("present".to_owned(), SdkValue::Bool(present))); + if dir_ready && info.is_none() && !in_archive { + out.push(("stranded".to_owned(), SdkValue::Bool(true))); + } // the size `machine.images` lists, so a reused load answers the same - if let Some(size) = Sidecar::read(cache, hex)?.and_then(|sidecar| sidecar.size) { - out.push(("size".to_owned(), SdkValue::Int(size as i64))); + if let Some(info) = info { + if let Some(size) = info.sidecar.size { + out.push(("size".to_owned(), SdkValue::Int(size as i64))); + } + if let Some(variant) = info.variant { + out.push(("variant".to_owned(), SdkValue::text(variant))); + } + if !matches!(info.sidecar.config, SdkValue::Null) { + out.push(("config".to_owned(), info.sidecar.config)); + } } let staged = part(cache, hex); if let Ok(meta) = fs::symlink_metadata(&staged) { @@ -367,16 +438,39 @@ fn probe(side: &Side<'_>, cache: &Path, id: Option<&str>, args: &SdkValue) -> Ou Ok(SdkValue::Map(out)) } -/// The image whose sidecar lists `reference` among its refs. +/// The image whose sidecar lists `reference` among its refs; refuses when +/// multiple cached images claim the same reference. fn named(cache: &Path, reference: &str) -> Result, SdkRefusal> { - Ok(sidecars(cache)? + let mut matches: Vec = sidecars(cache)? .into_iter() - .find(|s| s.refs.iter().any(|r| r == reference)) - .map(|s| s.id)) + .filter(|s| s.refs.iter().any(|r| r == reference)) + .map(|s| s.id) + .collect(); + matches.sort(); + matches.dedup(); + match matches.len() { + 0 => Ok(None), + 1 => Ok(Some(matches.remove(0))), + _ => Err(refused_with( + "InvalidInput", + format!( + "image reference `{reference}` is ambiguous across cached images: {}", + matches.join(", ") + ), + SdkValue::map([ + ("reason", SdkValue::text("ambiguous")), + ("ref", SdkValue::text(reference)), + ( + "ids", + SdkValue::List(matches.into_iter().map(SdkValue::Text).collect()), + ), + ]), + )), + } } -/// Every sidecar in `cache` whose image is unpacked there. -pub fn sidecars(cache: &Path) -> Result, SdkRefusal> { +/// Every extended sidecar in `cache` whose image directory `.2` exists. +pub fn sidecar_infos(cache: &Path) -> Result, SdkRefusal> { let mut found = Vec::new(); let entries = match fs::read_dir(cache) { Ok(entries) => entries, @@ -391,14 +485,22 @@ pub fn sidecars(cache: &Path) -> Result, SdkRefusal> { if !(self::hex(hex) && cache.join(format!("{hex}.2")).is_dir()) { continue; } - if let Some(sidecar) = Sidecar::read(cache, hex)? { - found.push(sidecar); + if let Some(info) = SidecarInfo::read(cache, hex)? { + found.push(info); } } - found.sort_by(|a, b| a.id.cmp(&b.id)); + found.sort_by(|a, b| a.sidecar.id.cmp(&b.sidecar.id)); Ok(found) } +/// Every sidecar in `cache` whose image is unpacked there. +pub fn sidecars(cache: &Path) -> Result, SdkRefusal> { + Ok(sidecar_infos(cache)? + .into_iter() + .map(|info| info.sidecar) + .collect()) +} + /// Appends one frame at `offset` to image `hex`'s staged tar; offset 0 /// starts it over. A frame whose offset is not the staged length is /// refused, so a lost reply's resend never doubles bytes. @@ -460,23 +562,100 @@ fn publish(cache: &Path, id: &str, args: &SdkValue) -> Outcome { )); } let image = Image::parse(id).map_err(|e| refused("InvalidInput", e.to_string()))?; + let old = SidecarInfo::read(cache, hex)?; + // Option B interrupted-publish recovery: `.2` without `.2.json` + // means an earlier publish stopped after rename; remove the stranded tree + // (unless in use) so `ensure_flat` unpacks cleanly before committing the sidecar. + if old.is_none() && cache.join(format!("{hex}.2")).is_dir() { + let users = lowers(cache.parent().unwrap_or(cache))?; + let removed = rootfs::remove(&image, cache, |path| users.iter().any(|l| l == path)) + .map_err(failed)?; + if !removed { + let dir_path = cache.join(format!("{hex}.2")); + let count = users.iter().filter(|l| **l == dir_path).count().max(1); + return Err(refused_with( + "InUse", + format!("image {id} has a stranded directory in use on this machine"), + SdkValue::map([("count", SdkValue::Int(count as i64))]), + )); + } + } let (_, unpacked) = rootfs::ensure_flat(&staged, &image, cache) .map_err(|e| refused("InvalidInput", format!("image {id}: {e}")))?; - let old = Sidecar::read(cache, hex)?; let mut refs = texts(args.get("refs")); - refs.extend(old.iter().flat_map(|s| s.refs.clone())); + refs.extend(old.iter().flat_map(|s| s.sidecar.refs.clone())); refs.sort(); refs.dedup(); - Sidecar { - id: id.to_owned(), - refs, - size: Some(size), - architecture: args.get_text("architecture").map(str::to_owned), - source: "imported".to_owned(), - config: args.get("config").cloned().unwrap_or(SdkValue::Null), - last_used: old.and_then(|s| s.last_used), + let variant = args + .get_text("variant") + .map(str::to_owned) + .or_else(|| old.as_ref().and_then(|s| s.variant.clone())); + let config = match args.get("config") { + Some(c) if !matches!(c, SdkValue::Null) => c.clone(), + _ => old + .as_ref() + .map(|s| s.sidecar.config.clone()) + .unwrap_or(SdkValue::Null), + }; + strip_moved_refs(cache, hex, &refs)?; + SidecarInfo { + sidecar: Sidecar { + id: id.to_owned(), + refs, + size: Some(size), + architecture: args.get_text("architecture").map(str::to_owned), + source: "imported".to_owned(), + config: config.clone(), + last_used: old.and_then(|s| s.sidecar.last_used), + }, + variant: variant.clone(), } .write(cache)?; fs::remove_file(&staged).map_err(failed)?; - Ok(SdkValue::map([("unpacked", SdkValue::Bool(unpacked))])) + let mut out = vec![("unpacked".to_owned(), SdkValue::Bool(unpacked))]; + if let Some(variant) = variant { + out.push(("variant".to_owned(), SdkValue::text(variant))); + } + if !matches!(config, SdkValue::Null) { + out.push(("config".to_owned(), config)); + } + Ok(SdkValue::Map(out)) +} + +/// Removes any ref in `claimed` from other sidecars in `cache` so moved tags +/// never stay bound to stale images. +fn strip_moved_refs( + cache: &Path, + published_hex: &str, + claimed: &[String], +) -> Result<(), SdkRefusal> { + if claimed.is_empty() { + return Ok(()); + } + let entries = match fs::read_dir(cache) { + Ok(entries) => entries, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()), + Err(e) => return Err(failed(e)), + }; + for entry in entries { + let name = entry.map_err(failed)?.file_name(); + let Some(other_hex) = name.to_str().and_then(|n| n.strip_suffix(".2.json")) else { + continue; + }; + if !hex(other_hex) || other_hex == published_hex { + continue; + } + let Some(mut other) = SidecarInfo::read(cache, other_hex)? else { + continue; + }; + let before = other.sidecar.refs.len(); + other + .sidecar + .refs + .retain(|r| !claimed.iter().any(|c| c == r)); + if other.sidecar.refs.len() != before { + other.write(cache)?; + } + } + Ok(()) } diff --git a/control/crates/layerfs-sandbox/src/image_tar.rs b/control/crates/layerfs-sandbox/src/image_tar.rs index 95926e935..fb8b76308 100644 --- a/control/crates/layerfs-sandbox/src/image_tar.rs +++ b/control/crates/layerfs-sandbox/src/image_tar.rs @@ -2,11 +2,13 @@ //! export`'s output with the files `docker create`'s init layer adds taken //! out (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, //! `etc/mtab`, everything under `dev/`), every device node and FIFO (which -//! the unpacker refuses), and directory modification times normalized to 0 -//! with recomputed header checksums. Those are the bytes that differ between -//! two exports of one image; what is left is the image's own tree. The filter -//! streams: it holds at most one entry's extended headers, never a file's -//! bytes. +//! the unpacker refuses), hardlinks targeting dropped entries refused clearly, +//! sparse entries expanded to regular files, and directory modification times +//! normalized to 0 with recomputed header checksums. Those are the bytes that +//! differ between two exports of one image; what is left is the image's own +//! tree. The filter streams: it holds at most one entry's extended headers and +//! sparse chunk map, never a file's bytes. +use std::collections::HashSet; use std::io::{self, Read}; const BLOCK: usize = 512; @@ -22,6 +24,13 @@ const INIT_FILES: [&str; 5] = [ "etc/mtab", ]; +fn clean_path(path: &str) -> String { + path.trim_start_matches("./") + .trim_start_matches('/') + .trim_end_matches('/') + .to_owned() +} + /// Whether an entry at `path` of type `flag` is left out of the copy. pub fn dropped(path: &str, flag: u8) -> bool { let path = path.trim_start_matches("./").trim_start_matches('/'); @@ -33,8 +42,61 @@ pub fn dropped(path: &str, flag: u8) -> bool { .is_some_and(|rest| !rest.is_empty()) } +/// One sparse tar entry expanded into a regular file (`b'0'`). +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct SparseReport { + /// Entry path with `./` and leading `/` removed. + pub path: String, + /// Expanded logical size in bytes. + pub expanded_bytes: u64, + /// Stored sparse payload bytes read from the source tar. + pub stored_bytes: u64, +} + +/// Report of dropped entries and expanded sparse files seen while filtering. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct TarReport { + /// Paths of dropped FIFO (`b'6'`) entries. + pub fifos: Vec, + /// Paths of dropped character/block device (`b'3'`, `b'4'`) entries. + pub devices: Vec, + /// Paths of dropped container init entries (`.dockerenv`, `/etc/hosts`, `dev/*`, ...). + pub init: Vec, + /// Details of every sparse entry expanded while streaming. + pub sparse_files: Vec, + /// Total expanded logical bytes across all sparse entries. + pub sparse_expanded_bytes: u64, +} + +impl TarReport { + /// Number of dropped FIFO entries. + pub fn fifo_count(&self) -> usize { + self.fifos.len() + } + + /// Number of dropped device entries. + pub fn device_count(&self) -> usize { + self.devices.len() + } + + /// Number of dropped init/runtime entries. + pub fn init_count(&self) -> usize { + self.init.len() + } +} + +struct SparseStream { + chunks: Vec<(u64, u64)>, + chunk_idx: usize, + chunk_left: u64, + pos: u64, + realsize: u64, + out_pad: u64, + input_skip: u64, +} + /// A reader of `input` (a tar stream) that yields the same tar without the -/// [`dropped`] entries. +/// [`dropped`] entries and with sparse entries expanded to regular files. pub struct Filtered { input: R, /// Bytes ready to hand out. @@ -42,6 +104,9 @@ pub struct Filtered { at: usize, /// Bytes of the current kept entry's data (with padding) still to copy. copying: u64, + sparse: Option, + dropped_paths: HashSet, + report: TarReport, done: bool, } @@ -53,10 +118,23 @@ impl Filtered { out: Vec::new(), at: 0, copying: 0, + sparse: None, + dropped_paths: HashSet::new(), + report: TarReport::default(), done: false, } } + /// Report of entries dropped or sparse files expanded so far. + pub fn report(&self) -> &TarReport { + &self.report + } + + /// Consumes the filter and returns its [`TarReport`]. + pub fn into_report(self) -> TarReport { + self.report + } + /// Reads exactly `buffer.len()` bytes, or none at a clean end. fn block(&mut self, buffer: &mut [u8]) -> io::Result { let mut read = 0; @@ -78,6 +156,9 @@ impl Filtered { /// Skips `count` bytes of input. fn skip(&mut self, count: u64) -> io::Result<()> { + if count == 0 { + return Ok(()); + } let copied = io::copy(&mut (&mut self.input).take(count), &mut io::sink())?; if copied != count { return Err(io::ErrorKind::UnexpectedEof.into()); @@ -85,11 +166,120 @@ impl Filtered { Ok(()) } + /// Reads GNU oldgnu extended sparse header blocks that follow a `b'S'` header. + fn read_gnu_sparse_map(&mut self, header: &[u8; BLOCK]) -> io::Result> { + let mut chunks = Vec::new(); + for i in 0..4 { + let base = 386 + i * 24; + let off = octal(&header[base..base + 12])?; + let len = octal(&header[base + 12..base + 24])?; + if len > 0 { + chunks.push((off, len)); + } + } + let mut extended = header[482] != 0; + while extended { + let mut ext = [0u8; BLOCK]; + if !self.block(&mut ext)? { + return Err(io::ErrorKind::UnexpectedEof.into()); + } + for slot in 0..21 { + let base = slot * 24; + let off = octal(&ext[base..base + 12])?; + let len = octal(&ext[base + 12..base + 24])?; + if len > 0 { + chunks.push((off, len)); + } + } + extended = ext[504] != 0; + } + Ok(chunks) + } + + /// Reads the PAX `1.0` inline newline-delimited sparse map (512-byte padded) + /// from the beginning of the entry's payload, returning `(chunks, map_bytes)`. + fn read_pax1_sparse_map(&mut self, max_bytes: u64) -> io::Result<(Vec<(u64, u64)>, u64)> { + let mut raw = Vec::new(); + let mut num_chunks: Option = None; + let mut needed_lines: usize = 1; + loop { + if raw.len() as u64 + BLOCK as u64 > max_bytes.min(EXTENDED_MAX) { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "PAX sparse map exceeds entry size or extended header limit", + )); + } + let mut blk = [0u8; BLOCK]; + if !self.block(&mut blk)? { + return Err(io::ErrorKind::UnexpectedEof.into()); + } + raw.extend_from_slice(&blk); + if num_chunks.is_none() { + if let Some(nl) = raw.iter().position(|b| *b == b'\n') { + let count: usize = std::str::from_utf8(&raw[..nl]) + .ok() + .and_then(|s| s.trim().parse().ok()) + .ok_or_else(|| { + io::Error::new( + io::ErrorKind::InvalidData, + "invalid PAX sparse chunk count", + ) + })?; + needed_lines = + 1usize.checked_add(count.saturating_mul(2)).ok_or_else(|| { + io::Error::new(io::ErrorKind::InvalidData, "sparse map overflow") + })?; + num_chunks = Some(count); + } + } + if num_chunks.is_some() { + let newlines = raw.iter().filter(|b| **b == b'\n').count(); + if newlines >= needed_lines { + break; + } + } + } + let map_bytes = raw.len() as u64; + let count = num_chunks.unwrap_or(0); + let mut lines = raw + .split(|b| *b == b'\n') + .take(needed_lines) + .map(|l| std::str::from_utf8(l).map(str::trim)); + let _ = lines.next(); + let mut chunks = Vec::with_capacity(count); + for _ in 0..count { + let off: u64 = lines + .next() + .transpose() + .ok() + .flatten() + .and_then(|s| s.parse().ok()) + .ok_or_else(|| { + io::Error::new(io::ErrorKind::InvalidData, "invalid PAX sparse offset") + })?; + let len: u64 = lines + .next() + .transpose() + .ok() + .flatten() + .and_then(|s| s.parse().ok()) + .ok_or_else(|| { + io::Error::new(io::ErrorKind::InvalidData, "invalid PAX sparse length") + })?; + if len > 0 { + chunks.push((off, len)); + } + } + Ok((chunks, map_bytes)) + } + /// Decides the next entry: fills `out` with its headers when it is kept - /// (its data then follows through `copying`), or skips it. + /// (its data then follows through `copying` or `sparse`), or skips it. fn next_entry(&mut self) -> io::Result<()> { let mut pending: Vec<([u8; BLOCK], Vec)> = Vec::new(); let mut long_name: Option = None; + let mut long_link: Option = None; + let mut pax = PaxMeta::default(); loop { let mut header = [0u8; BLOCK]; if !self.block(&mut header)? { @@ -116,22 +306,34 @@ impl Filtered { } let mut data = vec![0u8; padded as usize]; if !self.block(&mut data)? { - return Err(io::ErrorKind::UnexpectedEof.into()); + return Err(io::Error::new( + io::ErrorKind::UnexpectedEof, + "unexpected EOF inside extended tar header", + )); } let body = &data[..size as usize]; match flag { - b'x' => { - if let Some(path) = pax_path(body) { - long_name = Some(path); - } - } + b'x' => pax.parse_into(body)?, b'L' => long_name = Some(text(body)), + b'K' => long_link = Some(text(body)), _ => {} } pending.push((header, data)); continue; } - let path = long_name.take().unwrap_or_else(|| ustar_name(&header)); + let gnu_chunks = if flag == b'S' { + Some(self.read_gnu_sparse_map(&header)?) + } else { + None + }; + let pax_path = pax.path.take(); + let pax_link = pax.linkpath.take(); + let sparse_name = pax.sparse_name.take(); + let path = sparse_name + .clone() + .or(pax_path) + .or_else(|| long_name.take()) + .unwrap_or_else(|| ustar_name(&header)); // a link or directory carries no data, whatever its size says let data = if matches!(flag, b'1' | b'2' | b'3' | b'4' | b'5' | b'6') { 0 @@ -139,8 +341,96 @@ impl Filtered { padded }; if dropped(&path, flag) { + let norm = clean_path(&path); + if matches!(flag, b'6') { + self.report.fifos.push(norm.clone()); + } else if matches!(flag, b'3' | b'4') { + self.report.devices.push(norm.clone()); + } else { + self.report.init.push(norm.clone()); + } + self.dropped_paths.insert(norm); return self.skip(data); } + if flag == b'1' { + let link_target = pax_link + .or_else(|| long_link.take()) + .unwrap_or_else(|| text(&header[157..257])); + let target_norm = clean_path(&link_target); + if self.dropped_paths.contains(&target_norm) || dropped(&target_norm, b'0') { + let entry_norm = clean_path(&path); + return Err(io::Error::new( + io::ErrorKind::InvalidData, + format!("hardlink `{entry_norm}` points to dropped target `{target_norm}`"), + )); + } + } + let is_sparse = flag == b'S' || (matches!(flag, b'0' | b'\0') && pax.has_sparse); + if is_sparse { + let realsize = if flag == b'S' { + pax.sparse_realsize.unwrap_or(octal(&header[483..495])?) + } else { + pax.sparse_realsize.ok_or_else(|| { + io::Error::new( + io::ErrorKind::InvalidData, + "PAX sparse file missing realsize", + ) + })? + }; + let (raw_chunks, map_bytes) = + if pax.sparse_major == Some(1) && pax.sparse_minor == Some(0) { + self.read_pax1_sparse_map(size)? + } else if let Some(chunks) = gnu_chunks { + (chunks, 0) + } else { + (pax.sparse_chunks, 0) + }; + let (chunks, stored_bytes) = validate_sparse_chunks(raw_chunks, realsize)?; + let payload_needed = map_bytes.checked_add(stored_bytes).ok_or_else(|| { + io::Error::new(io::ErrorKind::InvalidData, "sparse payload overflow") + })?; + if payload_needed > size { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "sparse chunks exceed tar entry size", + )); + } + let input_skip = padded - payload_needed; + let override_path = sparse_name.as_deref(); + emit_sparse_pax_headers(&mut pending, override_path, &mut self.out)?; + let is_oldgnu = flag == b'S' || &header[257..263] == b"ustar "; + header[156] = b'0'; + if is_oldgnu { + header[257..263].copy_from_slice(b"ustar\0"); + header[263..265].copy_from_slice(b"00"); + header[329..512].fill(0); + } + write_size_field(&mut header[124..136], realsize)?; + recompute_checksum(&mut header); + self.out.extend_from_slice(&header); + self.report.sparse_files.push(SparseReport { + path: clean_path(&path), + expanded_bytes: realsize, + stored_bytes, + }); + self.report.sparse_expanded_bytes = + self.report.sparse_expanded_bytes.saturating_add(realsize); + let out_pad = (BLOCK as u64 - (realsize % BLOCK as u64)) % BLOCK as u64; + if realsize == 0 { + self.skip(input_skip)?; + return Ok(()); + } + self.sparse = Some(SparseStream { + chunks, + chunk_idx: 0, + chunk_left: 0, + pos: 0, + realsize, + out_pad, + input_skip, + }); + return Ok(()); + } if flag == b'5' { for (mut ext_hdr, ext_data) in pending { if ext_hdr[156] == b'x' { @@ -175,6 +465,63 @@ impl Filtered { return Ok(()); } } + + fn read_sparse( + &mut self, + st: &mut SparseStream, + buffer: &mut [u8], + ) -> io::Result> { + loop { + if st.chunk_left > 0 { + let want = (buffer.len() as u64).min(st.chunk_left) as usize; + let n = self.input.read(&mut buffer[..want])?; + if n == 0 { + return Err(io::Error::new( + io::ErrorKind::UnexpectedEof, + "unexpected EOF in sparse tar chunk", + )); + } + st.chunk_left -= n as u64; + st.pos += n as u64; + if st.chunk_left == 0 { + st.chunk_idx += 1; + } + return Ok(Some(n)); + } + if st.pos < st.realsize { + let hole_end = st + .chunks + .get(st.chunk_idx) + .map_or(st.realsize, |(off, _)| *off); + if st.pos < hole_end { + let zeros = (hole_end - st.pos).min(buffer.len() as u64) as usize; + buffer[..zeros].fill(0); + st.pos += zeros as u64; + if st.pos == hole_end { + if let Some((_, len)) = st.chunks.get(st.chunk_idx) { + st.chunk_left = *len; + } + } + return Ok(Some(zeros)); + } + if let Some((_, len)) = st.chunks.get(st.chunk_idx) { + st.chunk_left = *len; + continue; + } + } + let to_skip = std::mem::take(&mut st.input_skip); + if to_skip > 0 { + self.skip(to_skip)?; + } + if st.out_pad > 0 { + let zeros = st.out_pad.min(buffer.len() as u64) as usize; + buffer[..zeros].fill(0); + st.out_pad -= zeros as u64; + return Ok(Some(zeros)); + } + return Ok(None); + } + } } impl Read for Filtered { @@ -188,6 +535,9 @@ impl Read for Filtered { } self.out.clear(); self.at = 0; + if buffer.is_empty() { + return Ok(0); + } if self.copying > 0 { let wanted = (buffer.len() as u64).min(self.copying) as usize; let n = self.input.read(&mut buffer[..wanted])?; @@ -197,7 +547,16 @@ impl Read for Filtered { self.copying -= n as u64; return Ok(n); } - if self.done || buffer.is_empty() { + if let Some(mut st) = self.sparse.take() { + match self.read_sparse(&mut st, buffer)? { + Some(n) => { + self.sparse = Some(st); + return Ok(n); + } + None => continue, + } + } + if self.done { return Ok(0); } self.next_entry()?; @@ -205,10 +564,248 @@ impl Read for Filtered { } } +#[derive(Default)] +struct PaxMeta { + path: Option, + linkpath: Option, + has_sparse: bool, + sparse_major: Option, + sparse_minor: Option, + sparse_name: Option, + sparse_realsize: Option, + sparse_chunks: Vec<(u64, u64)>, +} + +fn walk_pax_records( + body: &[u8], + mut visit: impl FnMut(&[u8], &[u8], &[u8]) -> io::Result<()>, +) -> io::Result { + let mut rest = body; + while !rest.is_empty() { + let Some(space) = rest.iter().position(|b| *b == b' ') else { + return Ok(false); + }; + let Some(length) = std::str::from_utf8(&rest[..space]) + .ok() + .and_then(|s| s.parse::().ok()) + .filter(|len| *len > space + 1 && *len <= rest.len()) + else { + return Ok(false); + }; + let record = &rest[space + 1..length]; + let record = record.strip_suffix(b"\n").unwrap_or(record); + let (key, val) = match record.iter().position(|b| *b == b'=') { + Some(eq) => (&record[..eq], &record[eq + 1..]), + None => (record, &b""[..]), + }; + visit(&rest[..length], key, val)?; + rest = &rest[length..]; + } + Ok(true) +} + +impl PaxMeta { + fn parse_into(&mut self, body: &[u8]) -> io::Result<()> { + let mut pending_offset: Option = None; + let _ = walk_pax_records(body, |_, key, val| { + let val_str = String::from_utf8_lossy(val); + let parse_u64 = |label: &str| { + val_str.trim().parse::().map_err(|_| { + io::Error::new(io::ErrorKind::InvalidData, format!("invalid pax {label}")) + }) + }; + match key { + b"path" => self.path = Some(val_str.into_owned()), + b"linkpath" => self.linkpath = Some(val_str.into_owned()), + b"GNU.sparse.major" => { + self.has_sparse = true; + self.sparse_major = Some(parse_u64("GNU.sparse.major")?); + } + b"GNU.sparse.minor" => { + self.has_sparse = true; + self.sparse_minor = Some(parse_u64("GNU.sparse.minor")?); + } + b"GNU.sparse.name" => { + self.has_sparse = true; + self.sparse_name = Some(val_str.into_owned()); + } + b"GNU.sparse.realsize" | b"GNU.sparse.size" => { + self.has_sparse = true; + self.sparse_realsize = Some(parse_u64("GNU.sparse.realsize")?); + } + b"GNU.sparse.offset" => { + self.has_sparse = true; + pending_offset = Some(parse_u64("GNU.sparse.offset")?); + } + b"GNU.sparse.numbytes" => { + self.has_sparse = true; + let off = pending_offset.take().ok_or_else(|| { + io::Error::new( + io::ErrorKind::InvalidData, + "GNU.sparse.numbytes without offset", + ) + })?; + let len = parse_u64("GNU.sparse.numbytes")?; + if len > 0 { + self.sparse_chunks.push((off, len)); + } + } + b"GNU.sparse.map" => { + self.has_sparse = true; + let mut parts = val_str.split(',').filter(|s| !s.is_empty()); + while let Some(o_str) = parts.next() { + let l_str = parts.next().ok_or_else(|| { + io::Error::new( + io::ErrorKind::InvalidData, + "odd item count in GNU.sparse.map", + ) + })?; + let off: u64 = o_str.trim().parse().map_err(|_| { + io::Error::new(io::ErrorKind::InvalidData, "invalid sparse map offset") + })?; + let len: u64 = l_str.trim().parse().map_err(|_| { + io::Error::new(io::ErrorKind::InvalidData, "invalid sparse map len") + })?; + if len > 0 { + self.sparse_chunks.push((off, len)); + } + } + } + _ => { + if key.starts_with(b"GNU.sparse.") { + self.has_sparse = true; + } + } + } + Ok(()) + })?; + Ok(()) + } +} + +fn validate_sparse_chunks( + chunks: Vec<(u64, u64)>, + realsize: u64, +) -> io::Result<(Vec<(u64, u64)>, u64)> { + let mut prev_end = 0u64; + let mut stored_bytes = 0u64; + let mut valid = Vec::with_capacity(chunks.len()); + for (off, len) in chunks { + if off > realsize { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "sparse chunk starts past realsize", + )); + } + if len == 0 { + continue; + } + if off < prev_end { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "sparse chunks overlap or are out of order", + )); + } + let end = off.checked_add(len).ok_or_else(|| { + io::Error::new(io::ErrorKind::InvalidData, "sparse chunk end overflow") + })?; + if end > realsize { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "sparse chunk extends past realsize", + )); + } + stored_bytes = stored_bytes.checked_add(len).ok_or_else(|| { + io::Error::new(io::ErrorKind::InvalidData, "sparse byte count overflow") + })?; + prev_end = end; + valid.push((off, len)); + } + Ok((valid, stored_bytes)) +} + +fn emit_sparse_pax_headers( + pending: &mut Vec<([u8; BLOCK], Vec)>, + override_path: Option<&str>, + out: &mut Vec, +) -> io::Result<()> { + let mut wrote_path = false; + let last_pax = pending.iter().rposition(|(h, _)| h[156] == b'x'); + for (idx, (mut ext_hdr, ext_data)) in std::mem::take(pending).into_iter().enumerate() { + if ext_hdr[156] != b'x' { + out.extend_from_slice(&ext_hdr); + out.extend_from_slice(&ext_data); + continue; + } + let size = octal(&ext_hdr[124..136])? as usize; + let body = &ext_data[..size.min(ext_data.len())]; + let mut kept = strip_pax_keys(body, |k| { + k.starts_with(b"GNU.sparse.") + || k == b"size" + || (override_path.is_some() && k == b"path") + })?; + if last_pax == Some(idx) { + if let Some(real_path) = override_path { + kept.extend_from_slice(&pax_kv("path", real_path)); + wrote_path = true; + } + } + if kept.is_empty() { + continue; + } + write_octal(&mut ext_hdr[124..136], kept.len() as u64); + recompute_checksum(&mut ext_hdr); + let padded = kept.len().div_ceil(BLOCK) * BLOCK; + kept.resize(padded, 0); + out.extend_from_slice(&ext_hdr); + out.extend_from_slice(&kept); + } + if let Some(real_path) = override_path.filter(|_| !wrote_path) { + let mut body = pax_kv("path", real_path); + let mut hdr = [0u8; BLOCK]; + hdr[0..11].copy_from_slice(b"PaxHeaders/"); + write_octal(&mut hdr[100..108], 0o644); + write_octal(&mut hdr[124..136], body.len() as u64); + hdr[156] = b'x'; + hdr[257..263].copy_from_slice(b"ustar\0"); + hdr[263..265].copy_from_slice(b"00"); + recompute_checksum(&mut hdr); + let padded = body.len().div_ceil(BLOCK) * BLOCK; + body.resize(padded, 0); + out.extend_from_slice(&hdr); + out.extend_from_slice(&body); + } + Ok(()) +} + +fn pax_kv(key: &str, value: &str) -> Vec { + let body_len = 1 + key.len() + 1 + value.len() + 1; + let mut digits = 1usize; + loop { + let total = digits + body_len; + let d = total.to_string().len(); + if d == digits { + return format!("{total} {key}={value}\n").into_bytes(); + } + digits = d; + } +} + +fn strip_pax_keys(body: &[u8], mut drop_key: impl FnMut(&[u8]) -> bool) -> io::Result> { + let mut kept = Vec::new(); + walk_pax_records(body, |raw, key, _| { + if !drop_key(key) { + kept.extend_from_slice(raw); + } + Ok(()) + })?; + Ok(kept) +} + /// A header's name: ustar `prefix/name`, or the name alone. fn ustar_name(header: &[u8; BLOCK]) -> String { let name = text(&header[0..100]); - if &header[257..262] == b"ustar" { + if &header[257..263] == b"ustar\0" { let prefix = text(&header[345..500]); if !prefix.is_empty() { return format!("{prefix}/{name}"); @@ -217,25 +814,6 @@ fn ustar_name(header: &[u8; BLOCK]) -> String { name } -/// The `path` record of a pax header. -fn pax_path(body: &[u8]) -> Option { - let mut rest = body; - while !rest.is_empty() { - let space = rest.iter().position(|b| *b == b' ')?; - let length: usize = std::str::from_utf8(&rest[..space]).ok()?.parse().ok()?; - if length <= space || length > rest.len() { - return None; - } - let record = &rest[space + 1..length]; - let record = record.strip_suffix(b"\n").unwrap_or(record); - if let Some(path) = record.strip_prefix(b"path=") { - return Some(String::from_utf8_lossy(path).into_owned()); - } - rest = &rest[length..]; - } - None -} - /// Bytes up to the first NUL, as text. fn text(field: &[u8]) -> String { let end = field.iter().position(|b| *b == 0).unwrap_or(field.len()); @@ -294,24 +872,31 @@ fn strip_pax_times( fn filter_pax_records(body: &[u8]) -> Option> { let mut kept = Vec::new(); let mut changed = false; - let mut rest = body; - while !rest.is_empty() { - let space = rest.iter().position(|b| *b == b' ')?; - let length: usize = std::str::from_utf8(&rest[..space]).ok()?.parse().ok()?; - if length <= space + 1 || length > rest.len() { - return None; - } - let record = &rest[space + 1..length]; - let record = record.strip_suffix(b"\n").unwrap_or(record); - let key = record.split(|b| *b == b'=').next(); - if matches!(key, Some(b"mtime" | b"atime" | b"ctime")) { + let complete = walk_pax_records(body, |raw, key, _| { + if matches!(key, b"mtime" | b"atime" | b"ctime") { changed = true; } else { - kept.extend_from_slice(&rest[..length]); + kept.extend_from_slice(raw); } - rest = &rest[length..]; + Ok(()) + }) + .ok()?; + (complete && changed).then_some(kept) +} + +fn write_size_field(field: &mut [u8], value: u64) -> io::Result<()> { + if value <= 0o77_777_777_777 { + write_octal(field, value); + return Ok(()); + } + if field.len() != 12 { + return Err(io::Error::new(io::ErrorKind::InvalidData, "tar size field")); } - changed.then_some(kept) + let be = value.to_be_bytes(); + field[0] = 0x80; + field[1..4].fill(0); + field[4..12].copy_from_slice(&be); + Ok(()) } fn write_octal(field: &mut [u8], value: u64) { diff --git a/control/crates/layerfs-sandbox/src/images.rs b/control/crates/layerfs-sandbox/src/images.rs index 0ec99160a..58a1b3758 100644 --- a/control/crates/layerfs-sandbox/src/images.rs +++ b/control/crates/layerfs-sandbox/src/images.rs @@ -7,14 +7,20 @@ //! (`available`, read through the Docker the copy uses). macOS native runs //! no image (`mode: 'host'`). use crate::deploy::{self, Choice, Side}; -use crate::image_artifact::{self as cache, Sidecar}; +use crate::image_artifact::{self as cache, SidecarInfo}; +use crate::image_load::ImageLock; use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_home::home; use layerfs_home::names::MachineName; use layerfs_home::outcome::{failed, refused, Outcome}; -use layerfs_sandbox_backend::rootfs; +use layerfs_sandbox_backend::rootfs::{self, Temporary}; use layerfs_sandbox_backend::Image; use layerfs_store::place::{self, Executor}; +use std::collections::{BTreeMap, BTreeSet}; +use std::io::ErrorKind; +use std::os::unix::fs::OpenOptionsExt; use std::path::Path; +use std::time::SystemTime; type Result = std::result::Result; @@ -81,18 +87,30 @@ pub fn list(home: &Path, name: &MachineName) -> Outcome { .count() as i64 }; let images = match answer.get("images") { - Some(SdkValue::List(rows)) => rows - .iter() - .map(|row| { - let n = count(row.get_text("id").unwrap_or("")); - layerfs_home::home::with_field(row.clone(), "sandboxes", SdkValue::Int(n)) - }) - .collect(), + Some(SdkValue::List(rows)) => { + let mut out = Vec::with_capacity(rows.len()); + for row in rows { + let id = row.get_text("id").unwrap_or(""); + let mut enriched = + home::with_field(row.clone(), "sandboxes", SdkValue::Int(count(id))); + if enriched.get_bool("staged") { + if let Some(hex) = id.strip_prefix("sha256:").filter(|h| cache::is_hex(h)) { + if is_flock_held(&ImageLock::path(home, machine, hex))? { + enriched = + home::with_field(enriched, "resumable", SdkValue::Bool(false)); + } + } + } + out.push(enriched); + } + out + } _ => Vec::new(), }; - // the host's Docker images this machine could copy, minus those it holds + // the host's Docker images this machine could copy, minus those it holds completely let held: Vec<(String, Vec)> = images .iter() + .filter(|row| !row.get_bool("staged") && !row.get_bool("stranded")) .map(|row| { ( row.get_text("id").unwrap_or("").to_owned(), @@ -156,7 +174,7 @@ fn listing(machine: &str, side: &Side<'_>, choice: &Choice) -> Outcome { Side::Home(root) | Side::Worker(root) => *root, }; let dir = cache::cache(root); - let mut rows: Vec = cache::sidecars(&dir)?; + let mut rows: Vec = cache::sidecar_infos(&dir)?; // the archives a Sandbox here reads: the machine's own, and the bundle's let mut archives = Vec::new(); if choice.archive.is_some() { @@ -174,24 +192,29 @@ fn listing(machine: &str, side: &Side<'_>, choice: &Choice) -> Outcome { } for entry in entries { let id = entry.digest.as_str(); - if rows.iter().any(|row| row.id == id) { + if rows.iter().any(|row| row.sidecar.id == id) { continue; } if let Some(row) = cache::from_archive(side, archive, id)? { - rows.push(row); + rows.push(SidecarInfo { + sidecar: row, + variant: None, + }); } } } - let images = rows + let published: BTreeSet = rows.iter().map(|r| r.sidecar.id.clone()).collect(); + let mut images: Vec = rows .into_iter() - .map(|row| { - let mut value = row.to_value(); - if let SdkValue::Map(fields) = &mut value { - fields.retain(|(name, _)| name != "config"); - } - value - }) + .map(|row| home::with_field(row.to_value(), "staged", SdkValue::Bool(false))) .collect(); + append_cache_leftovers(root, machine, &dir, &published, &mut images)?; + images.sort_by(|a, b| { + a.get_text("id") + .unwrap_or("") + .cmp(b.get_text("id").unwrap_or("")) + .then_with(|| a.get_bool("staged").cmp(&b.get_bool("staged"))) + }); Ok(SdkValue::map([ ("machine", SdkValue::text(machine)), ("mode", SdkValue::text("images")), @@ -205,6 +228,77 @@ fn listing(machine: &str, side: &Side<'_>, choice: &Choice) -> Outcome { ])) } +/// Appends staged `.recv-.part` rows and stranded `.2` rows found in `dir`. +fn append_cache_leftovers( + root: &Path, + machine: &str, + dir: &Path, + published: &BTreeSet, + images: &mut Vec, +) -> Result<()> { + let entries = match std::fs::read_dir(dir) { + Ok(entries) => entries, + Err(e) if e.kind() == ErrorKind::NotFound => return Ok(()), + Err(e) => return Err(failed(e)), + }; + let now = SystemTime::now(); + for entry in entries { + let entry = entry.map_err(failed)?; + let fname = entry.file_name(); + let Some(name) = fname.to_str() else { continue }; + if let Some(hex) = cache::part_hex(name) { + let meta = match std::fs::symlink_metadata(entry.path()) { + Ok(meta) => meta, + Err(e) if e.kind() == ErrorKind::NotFound => continue, + Err(e) => return Err(failed(e)), + }; + let id = format!("sha256:{hex}"); + let age = meta + .modified() + .ok() + .and_then(|mtime| now.duration_since(mtime).ok()) + .map_or(0, |d| d.as_secs() as i64); + let lock_held = is_flock_held(&dir.join(format!("{hex}.2.lock")))? + || is_flock_held(&ImageLock::path(root, machine, hex))?; + let resumable = meta.file_type().is_file() + && meta.len() > 0 + && !published.contains(&id) + && !lock_held; + images.push(SdkValue::map([ + ("id", SdkValue::text(&id)), + ("refs", SdkValue::List(Vec::new())), + ("size", SdkValue::Int(meta.len() as i64)), + ("age", SdkValue::Int(age)), + ("resumable", SdkValue::Bool(resumable)), + ("architecture", SdkValue::Null), + ("source", SdkValue::text("staged")), + ("variant", SdkValue::Null), + ("config", SdkValue::Null), + ("last_used", SdkValue::Null), + ("staged", SdkValue::Bool(true)), + ])); + } else if let Some(hex) = name.strip_suffix(".2").filter(|h| cache::is_hex(h)) { + let id = format!("sha256:{hex}"); + if published.contains(&id) || !entry.file_type().is_ok_and(|t| t.is_dir()) { + continue; + } + images.push(SdkValue::map([ + ("id", SdkValue::text(&id)), + ("refs", SdkValue::List(Vec::new())), + ("size", SdkValue::Null), + ("architecture", SdkValue::Null), + ("source", SdkValue::text("stranded")), + ("variant", SdkValue::Null), + ("config", SdkValue::Null), + ("last_used", SdkValue::Null), + ("staged", SdkValue::Bool(false)), + ("stranded", SdkValue::Bool(true)), + ])); + } + } + Ok(()) +} + /// `machine.prune(name, image?, { unused })`: removes image `image`, or with /// `unused` every image no Sandbox uses except the machine's default: /// `{removed: [id], freed}`, `freed` measured on the filesystem. @@ -227,13 +321,36 @@ pub fn prune(home: &Path, name: &MachineName, image: Option<&str>, unused: bool) if host_mode(&executor) { return Err(host_only(machine)); } + let locked = locked_image_ids(&ImageLock::dir(home, machine))?; + let _target_lock = if let Some(target) = image { + if locked.contains(target) { + return Err(refused_with( + "InUse", + format!("image {target} has an active copy lock on this machine"), + SdkValue::map([("count", SdkValue::Int(1))]), + )); + } + Some(ImageLock::try_take(home, machine, target)?.ok_or_else(|| { + refused_with( + "InUse", + format!("image {target} has an active copy lock on this machine"), + SdkValue::map([("count", SdkValue::Int(1))]), + ) + })?) + } else { + None + }; let mut args = request(machine, &choice); - args = layerfs_home::home::with_field( + args = home::with_field(args, "target", image.map_or(SdkValue::Null, SdkValue::text)); + args = home::with_field(args, "unused", SdkValue::Bool(unused)); + args = home::with_field( args, - "target", - image.map_or(SdkValue::Null, SdkValue::text), + "locked", + SdkValue::List(locked.into_iter().map(SdkValue::Text).collect()), ); - args = layerfs_home::home::with_field(args, "unused", SdkValue::Bool(unused)); + if image.is_some() { + args = home::with_field(args, "target_guarded", SdkValue::Bool(true)); + } match executor { Executor::Local => pruning(&Side::Home(home), &args), Executor::Worker(mut worker) => worker @@ -248,15 +365,36 @@ pub fn prune_in_worker(root: &Path, args: SdkValue) -> Outcome { pruning(&Side::Worker(root), &args) } -/// Removes the images `args` names on `side`. +/// Artifacts present in the image cache directory for one digest hex. +#[derive(Default)] +struct CacheEntry { + has_unpacked: bool, + has_sidecar: bool, + has_part: bool, + temps: Vec, +} + +/// Removes the images `args` names on `side`, plus unheld staged parts, +/// temporary unpack directories, stranded unpacked directories, and dangling +/// sidecars, while never touching live-locked or in-use entries. fn pruning(side: &Side<'_>, args: &SdkValue) -> Outcome { let root = match side { Side::Home(root) | Side::Worker(root) => *root, }; let dir = cache::cache(root); let choice = choice_of(args); + let machine = args.get_text("machine").unwrap_or(""); let target = args.get_text("target").filter(|t| cache::digest(t)); let unused = args.get_bool("unused"); + let target_guarded = args.get_bool("target_guarded"); + let mut locked: BTreeSet = cache::texts(args.get("locked")).into_iter().collect(); + if !machine.is_empty() { + for id in locked_image_ids(&ImageLock::dir(root, machine))? { + if !(target_guarded && target == Some(id.as_str())) { + locked.insert(id); + } + } + } let default = match &choice.image { Some(image) => Some(image.clone()), None => deploy::archive(side, choice.archive.as_deref()) @@ -266,40 +404,104 @@ fn pruning(side: &Side<'_>, args: &SdkValue) -> Outcome { .map(|entries| entries[0].digest.as_str().to_owned()), }; let before = cache::free(&dir); - let candidates: Vec = match target { - Some(target) => vec![target.to_owned()], - None => unpacked(&dir)?, - }; + let target_hex = target.map(|t| &t["sha256:".len()..]); + let entries = collect_cache_entries(&dir, target_hex)?; + if target.is_some() && entries.is_empty() { + return Err(refused( + "NotFound", + format!("machine has no unpacked image {}", target.unwrap_or("")), + )); + } let lowers = lowers(dir.parent().unwrap_or(&dir))?; let mut removed = Vec::new(); - for id in candidates { - if target.is_none() && unused && default.as_deref() == Some(id.as_str()) { + for (hex, item) in entries { + let id = format!("sha256:{hex}"); + let held = [dir.join(format!("{hex}.2")), dir.join(&hex)]; + let lower_users = lowers.iter().filter(|l| held.contains(l)).count(); + let img_locked = locked.contains(&id); + let hold_locked = is_flock_held(&dir.join(format!("{hex}.2.lock")))?; + if img_locked || lower_users > 0 || hold_locked { + if target.is_some() { + let count = lower_users.max(1); + return Err(refused_with( + "InUse", + format!( + "image {id} is used by a Sandbox on this machine (or one being created)" + ), + SdkValue::map([("count", SdkValue::Int(count as i64))]), + )); + } continue; } - let hex = &id["sha256:".len()..]; - let held = [dir.join(format!("{hex}.2")), dir.join(hex)]; - if target.is_some() && !held.iter().any(|p| p.exists()) { - return Err(refused( - "NotFound", - format!("machine has no unpacked image {id}"), - )); + let is_default = target.is_none() && unused && default.as_deref() == Some(id.as_str()); + let _local_guard = if target.is_none() + && matches!(side, Side::Home(_)) + && !machine.is_empty() + && ImageLock::dir(root, machine).is_dir() + { + match ImageLock::try_take(root, machine, &id)? { + Some(guard) => Some(guard), + None => continue, + } + } else { + None + }; + let mut removed_any = false; + let mut temp_held = false; + for temp_name in &item.temps { + match rootfs::remove_temporary(&dir, temp_name).map_err(failed)? { + Temporary::Removed => removed_any = true, + Temporary::Absent => {} + Temporary::Held => { + temp_held = true; + break; + } + } + } + if temp_held { + if target.is_some() { + return Err(refused_with( + "InUse", + format!("image {id} is being unpacked on this machine"), + SdkValue::map([("count", SdkValue::Int(1))]), + )); + } + continue; } - let image = Image::parse(&id).map_err(|e| refused("InvalidInput", e.to_string()))?; - let gone = rootfs::remove(&image, &dir, |path| lowers.iter().any(|l| l == path)) - .map_err(failed)?; - if gone { - match std::fs::remove_file(cache::sidecar_path(&dir, hex)) { - Err(e) if e.kind() != std::io::ErrorKind::NotFound => return Err(failed(e)), - _ => {} + if item.has_part && remove_file_if_present(&cache::part(&dir, &hex))? { + removed_any = true; + } + if is_default { + if removed_any && !item.has_unpacked { + removed.push(SdkValue::Text(id)); + } + continue; + } + if item.has_unpacked { + let image = Image::parse(&id).map_err(|e| refused("InvalidInput", e.to_string()))?; + let gone = rootfs::remove(&image, &dir, |path| lowers.iter().any(|l| l == path)) + .map_err(failed)?; + if gone { + removed_any = true; + } else { + if target.is_some() { + let count = lower_users.max(1); + return Err(refused_with( + "InUse", + format!( + "image {id} is used by a Sandbox on this machine (or one being created)" + ), + SdkValue::map([("count", SdkValue::Int(count as i64))]), + )); + } + continue; } + } + if item.has_sidecar && remove_file_if_present(&cache::sidecar_path(&dir, &hex))? { + removed_any = true; + } + if removed_any { removed.push(SdkValue::Text(id)); - } else if target.is_some() { - let users = lowers.iter().filter(|l| held.contains(l)).count(); - return Err(refused_with( - "InUse", - format!("image {id} is used by a Sandbox on this machine (or one being created)"), - SdkValue::map([("count", SdkValue::Int(users as i64))]), - )); } } let after = cache::free(&dir); @@ -313,31 +515,106 @@ fn pruning(side: &Side<'_>, args: &SdkValue) -> Outcome { ])) } -/// Every image unpacked in `dir`, the current layout's and older ones'. -fn unpacked(dir: &Path) -> Result> { - let mut ids = Vec::new(); +/// Scans `dir` for unpacked images, sidecars, staged `.part` files, and temporary +/// `.tmp-*` directories, optionally filtered to a single `target_hex`. +fn collect_cache_entries( + dir: &Path, + target_hex: Option<&str>, +) -> Result> { + let mut found: BTreeMap = BTreeMap::new(); let entries = match std::fs::read_dir(dir) { Ok(entries) => entries, - Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(ids), + Err(e) if e.kind() == ErrorKind::NotFound => return Ok(found), Err(e) => return Err(failed(e)), }; for entry in entries { let entry = entry.map_err(failed)?; - let name = entry.file_name(); - let Some(name) = name.to_str() else { continue }; - let hex = name.strip_suffix(".2").unwrap_or(name); - let id = format!("sha256:{hex}"); - if cache::digest(&id) && entry.path().is_dir() && !ids.contains(&id) { - ids.push(id); + let fname = entry.file_name(); + let Some(name) = fname.to_str() else { continue }; + if let Some(hex) = cache::part_hex(name) { + if target_hex.is_none_or(|t| t == hex) { + found.entry(hex.to_owned()).or_default().has_part = true; + } + } else if let Some(hex) = rootfs::temporary_digest(name) { + if target_hex.is_none_or(|t| t == hex) { + found + .entry(hex.to_owned()) + .or_default() + .temps + .push(name.to_owned()); + } + } else if let Some(hex) = name.strip_suffix(".2.json").filter(|h| cache::is_hex(h)) { + if target_hex.is_none_or(|t| t == hex) { + found.entry(hex.to_owned()).or_default().has_sidecar = true; + } + } else { + let hex = name.strip_suffix(".2").unwrap_or(name); + if cache::is_hex(hex) + && target_hex.is_none_or(|t| t == hex) + && entry.file_type().is_ok_and(|t| t.is_dir()) + { + found.entry(hex.to_owned()).or_default().has_unpacked = true; + } + } + } + Ok(found) +} + +fn remove_file_if_present(path: &Path) -> Result { + match std::fs::remove_file(path) { + Ok(()) => Ok(true), + Err(e) if e.kind() == ErrorKind::NotFound => Ok(false), + Err(e) => Err(failed(e)), + } +} + +/// Checks whether an `flock` exists and is currently held on `path` without +/// creating or mutating any file on disk. +fn is_flock_held(path: &Path) -> Result { + let file = match std::fs::OpenOptions::new() + .read(true) + .custom_flags(libc::O_NOFOLLOW) + .open(path) + { + Ok(file) => file, + Err(e) if e.kind() == ErrorKind::NotFound => return Ok(false), + Err(e) => return Err(failed(e)), + }; + let acquired = home::flock::try_lock(&file, true).map_err(failed)?; + if acquired { + home::flock::unlock(&file); + Ok(false) + } else { + Ok(true) + } +} + +/// Every `sha256:` image digest whose `ImageLock` file in `lock_dir` is +/// held by a live process or open file description. +fn locked_image_ids(lock_dir: &Path) -> Result> { + let mut locked = BTreeSet::new(); + let entries = match std::fs::read_dir(lock_dir) { + Ok(entries) => entries, + Err(e) if e.kind() == ErrorKind::NotFound => return Ok(locked), + Err(e) => return Err(failed(e)), + }; + for entry in entries { + let entry = entry.map_err(failed)?; + let fname = entry.file_name(); + let Some(name) = fname.to_str() else { continue }; + let Some(hex) = name.strip_suffix(".lock").filter(|h| cache::is_hex(h)) else { + continue; + }; + if is_flock_held(&entry.path())? { + locked.insert(format!("sha256:{hex}")); } } - ids.sort(); - Ok(ids) + Ok(locked) } /// The image directories the Sandboxes under runtime root `run` are built on: /// each Sandbox directory's `config/helper.spec` `lower=` line. -fn lowers(run: &Path) -> Result> { +pub(crate) fn lowers(run: &Path) -> Result> { let mut found = Vec::new(); let entries = match std::fs::read_dir(run) { Ok(entries) => entries, diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs new file mode 100644 index 000000000..a9ec6c878 --- /dev/null +++ b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs @@ -0,0 +1,1390 @@ +//! Image parts enumeration, lock- & InUse-safe prune, interrupted publish +//! recovery, moved/ambiguous ref handling, sparse tar expansion, hardlink to +//! dropped target refusal, declared-loss metadata/SHA verification, and +//! record-only variant/config (#176 I03). +#[allow(dead_code)] +#[path = "../../layerfs-sandbox-backend/tests/support/image.rs"] +mod fixture; +use fixture::{pax_record, Scratch, Tar}; +use layerfs_bridge::control::SdkValue; +use layerfs_home::events::Events; +use layerfs_home::home; +use layerfs_home::names::MachineName; +use layerfs_sandbox::docker::Docker; +use layerfs_sandbox::image_artifact::{self as cache, architecture, Sidecar, CHUNK}; +use layerfs_sandbox::image_load::{load, ImageLock, Loaded, Target}; +use layerfs_sandbox::image_tar::{Filtered, TarReport}; +use layerfs_sandbox::images; +use layerfs_sandbox_backend::{rootfs, Image}; +use sha2::{Digest, Sha256}; +use std::collections::BTreeSet; +use std::fs; +use std::io::Read; +use std::os::unix::fs::{MetadataExt, PermissionsExt}; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{Duration, Instant, UNIX_EPOCH}; + +static SEQ: AtomicU64 = AtomicU64::new(0); + +fn sha256_hex(bytes: &[u8]) -> String { + layerfs_bridge::sdk_values::hex(&Sha256::digest(bytes)) +} + +fn docker_available() -> bool { + Command::new("docker") + .arg("info") + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status() + .is_ok_and(|s| s.success()) +} + +fn real_docker() -> Docker { + let path = std::env::var_os("PATH").unwrap_or_default(); + let program = std::env::split_paths(&path) + .filter(|d| !d.as_os_str().is_empty()) + .map(|d| d.join("docker")) + .find(|p| p.is_file()); + Docker::at(program, None) +} + +fn wait_for(what: &str, done: impl Fn() -> bool) { + let start = Instant::now(); + while !done() { + assert!( + start.elapsed() < Duration::from_secs(30), + "timed out waiting for {what}" + ); + std::thread::sleep(Duration::from_millis(20)); + } +} + +fn containers_for_home(home_id: &str) -> Vec { + let Ok(out) = Command::new("docker") + .args([ + "ps", + "-a", + "--filter", + &format!("label=layerfs.home={home_id}"), + "--format", + "{{.Names}}", + ]) + .output() + else { + return Vec::new(); + }; + if !out.status.success() { + return Vec::new(); + } + String::from_utf8_lossy(&out.stdout) + .lines() + .map(str::trim) + .filter(|l| !l.is_empty()) + .map(str::to_owned) + .collect() +} + +fn container_volumes(container: &str) -> Vec { + let Ok(out) = Command::new("docker") + .args([ + "container", + "inspect", + "--format", + "{{range .Mounts}}{{if eq .Type \"volume\"}}{{.Name}}{{\"\\n\"}}{{end}}{{end}}", + container, + ]) + .output() + else { + return Vec::new(); + }; + if !out.status.success() { + return Vec::new(); + } + String::from_utf8_lossy(&out.stdout) + .lines() + .map(str::trim) + .filter(|l| !l.is_empty()) + .map(str::to_owned) + .collect() +} + +/// Manages real-Docker test images/tags/containers and cleans up only its own +/// resources on Drop. +struct DockerGuard { + tags: Vec, + homes: Vec, + scratch: Scratch, +} + +impl DockerGuard { + fn new(name: &str) -> Self { + Self { + tags: Vec::new(), + homes: Vec::new(), + scratch: Scratch::new(name), + } + } + + fn make_home(&mut self, name: &str) -> (PathBuf, String) { + let home = self.scratch.base.join(name); + fs::create_dir_all(&home).unwrap(); + let id = home::ensure(&home).unwrap().id; + self.homes.push(id.clone()); + (home, id) + } + + fn import_tar(&mut self, tag: &str, tar: &[u8]) -> String { + use std::io::Write; + let mut child = Command::new("docker") + .args(["import", "-", tag]) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .expect("spawn docker import"); + child.stdin.take().unwrap().write_all(tar).unwrap(); + let out = child.wait_with_output().unwrap(); + assert!( + out.status.success(), + "docker import failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + self.tags.push(tag.to_owned()); + self.inspect_id(tag) + } + + fn build_dockerfile(&mut self, tag: &str, dockerfile: &str) -> String { + let dir = self + .scratch + .base + .join(format!("df-{}", SEQ.fetch_add(1, Ordering::Relaxed))); + fs::create_dir_all(&dir).unwrap(); + fs::write(dir.join("Dockerfile"), dockerfile).unwrap(); + let out = Command::new("docker") + .args([ + "build", + "--pull=false", + "-q", + "-t", + tag, + dir.to_str().unwrap(), + ]) + .output() + .expect("docker build"); + assert!( + out.status.success(), + "docker build failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + self.tags.push(tag.to_owned()); + self.inspect_id(tag) + } + + fn retag(&mut self, src: &str, dst: &str) { + let out = Command::new("docker") + .args(["tag", src, dst]) + .output() + .expect("docker tag"); + assert!( + out.status.success(), + "docker tag failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + if !self.tags.iter().any(|t| t == dst) { + self.tags.push(dst.to_owned()); + } + } + + fn inspect_id(&self, ref_or_id: &str) -> String { + let inspect = Command::new("docker") + .args(["image", "inspect", "--format", "{{.Id}}", ref_or_id]) + .output() + .expect("docker image inspect"); + assert!(inspect.status.success()); + String::from_utf8_lossy(&inspect.stdout).trim().to_owned() + } +} + +impl Drop for DockerGuard { + fn drop(&mut self) { + let mut cnames = BTreeSet::new(); + for home_id in &self.homes { + cnames.extend(containers_for_home(home_id)); + } + for cname in cnames { + let vols = container_volumes(&cname); + let _ = Command::new("docker") + .args(["rm", "-f", "-v", &cname]) + .output(); + for v in vols { + let _ = Command::new("docker").args(["volume", "rm", &v]).output(); + } + } + for tag in self.tags.iter().rev() { + let _ = Command::new("docker").args(["rmi", "-f", tag]).output(); + } + } +} + +fn filtered_with_report(bytes: &[u8]) -> std::io::Result<(Vec, TarReport)> { + let mut out = Vec::new(); + let mut reader = Filtered::new(bytes); + reader.read_to_end(&mut out)?; + Ok((out, reader.into_report())) +} + +fn filtered_bytes(bytes: &[u8]) -> std::io::Result> { + filtered_with_report(bytes).map(|(out, _)| out) +} + +struct ChildGuard(Option); + +impl ChildGuard { + fn new(child: std::process::Child) -> Self { + Self(Some(child)) + } + + fn kill_and_wait(&mut self) { + if let Some(mut child) = self.0.take() { + let _ = child.kill(); + let _ = child.wait(); + } + } +} + +impl Drop for ChildGuard { + fn drop(&mut self) { + self.kill_and_wait(); + } +} + +fn run_load( + docker: &Docker, + home: &Path, + machine: &str, + image: &str, +) -> Result { + let mut sink = |_: SdkValue| {}; + let mut events = Events::new(&mut sink); + load( + docker, + &mut events, + &mut Target::local(home, machine), + None, + image, + ) +} + +fn native_name() -> MachineName { + MachineName::parse("native").unwrap() +} + +fn image_rows(home: &Path) -> Vec { + let out = images::list(home, &native_name()).unwrap(); + match out.get("images") { + Some(SdkValue::List(rows)) => rows.clone(), + other => panic!("unexpected images field: {other:?}"), + } +} + +fn step(home: &Path, args: SdkValue) -> Result { + cache::step(&layerfs_sandbox::deploy::Side::Home(home), &args) +} + +/// Builds a GNU oldgnu sparse (`b'S'`) tar entry with arbitrary chunks (supports >4 chunks). +fn build_gnu_sparse_tar( + path: &str, + mode: u32, + mtime: u64, + realsize: u64, + chunks: &[(u64, &[u8])], +) -> Vec { + let stored_size: u64 = chunks.iter().map(|(_, d)| d.len() as u64).sum(); + let mut hdr = [0u8; 512]; + hdr[..path.len()].copy_from_slice(path.as_bytes()); + let oct = |f: &mut [u8], v: u64| { + let w = f.len() - 1; + let t = format!("{v:0w$o}\0"); + f.copy_from_slice(&t.as_bytes()[..f.len()]); + }; + oct(&mut hdr[100..108], u64::from(mode)); + oct(&mut hdr[108..116], 0); + oct(&mut hdr[116..124], 0); + oct(&mut hdr[124..136], stored_size); + oct(&mut hdr[136..148], mtime); + hdr[156] = b'S'; + hdr[257..263].copy_from_slice(b"ustar "); + hdr[263..265].copy_from_slice(b" \0"); + + for (i, (off, data)) in chunks.iter().take(4).enumerate() { + let base = 386 + i * 24; + oct(&mut hdr[base..base + 12], *off); + oct(&mut hdr[base + 12..base + 24], data.len() as u64); + } + let has_ext = chunks.len() > 4; + hdr[482] = u8::from(has_ext); + oct(&mut hdr[483..495], realsize); + hdr[148..156].fill(b' '); + let sum: u64 = hdr.iter().map(|b| u64::from(*b)).sum(); + hdr[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes()); + + let mut out = Vec::new(); + out.extend_from_slice(&hdr); + + let mut idx = 4; + while idx < chunks.len() { + let mut ext = [0u8; 512]; + for (slot, (off, data)) in chunks[idx..].iter().take(21).enumerate() { + let base = slot * 24; + oct(&mut ext[base..base + 12], *off); + oct(&mut ext[base + 12..base + 24], data.len() as u64); + } + idx += 21; + ext[504] = u8::from(idx < chunks.len()); + out.extend_from_slice(&ext); + } + + for (_, data) in chunks { + out.extend_from_slice(data); + } + let rem = out.len() % 512; + if rem != 0 { + out.resize(out.len() + (512 - rem), 0); + } + out.resize(out.len() + 1024, 0); + out +} + +#[test] +fn real_docker_tag_move_leaves_enumerable_part_and_clears_stale_ref_on_publish() { + if !docker_available() { + eprintln!("NOT_RUN: docker unavailable"); + return; + } + let mut guard = DockerGuard::new("lp176-rec-tagmove"); + let pid = std::process::id(); + let seq = SEQ.fetch_add(1, Ordering::Relaxed); + let repo_tag = format!("layerfs-lp176-rec-app-{pid}-{seq}:latest"); + let v1_base = format!("layerfs-lp176-rec-v1b-{pid}-{seq}:test"); + let v2_base = format!("layerfs-lp176-rec-v2b-{pid}-{seq}:test"); + let v2_tag = format!("layerfs-lp176-rec-v2-{pid}-{seq}:test"); + + let tar1 = Tar::new() + .at(1_700_000_000) + .directory("etc/", 0o755) + .file("etc/ver", 0o644, b"v1\n") + .file("usr/bin/blob1", 0o755, &vec![0x11; CHUNK + 65_536]) + .finish(); + let v1_id = guard.import_tar(&v1_base, &tar1); + let v1_hex = v1_id.strip_prefix("sha256:").unwrap().to_owned(); + guard.retag(&v1_base, &repo_tag); + + let tar2 = Tar::new() + .at(1_700_000_000) + .directory("etc/", 0o755) + .file("etc/ver", 0o644, b"v2\n") + .file("usr/bin/blob2", 0o755, &vec![0x22; CHUNK + 131_072]) + .finish(); + guard.import_tar(&v2_base, &tar2); + let v2_id = guard.build_dockerfile( + &v2_tag, + &format!("FROM {v2_base}\nENV APP_MODE=prod\nWORKDIR /app\nUSER 1000:1000\n"), + ); + let v2_hex = v2_id.strip_prefix("sha256:").unwrap().to_owned(); + + let (home, _) = guard.make_home("home"); + let docker = real_docker(); + + // 1. Load V1 under repo_tag. + let loaded1 = run_load(&docker, &home, "native", &repo_tag).unwrap(); + assert_eq!(loaded1.id, v1_id); + assert!(!loaded1.reused); + + // 2. Move repo_tag in Docker to V2, start loading repo_tag, and kill mid-send. + guard.retag(&v2_tag, &repo_tag); + let mut child = ChildGuard::new( + Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_pause_load", "--nocapture"]) + .env("LP176_REC_PAUSE_HOME", &home) + .env("LP176_REC_PAUSE_MACHINE", "native") + .env("LP176_REC_PAUSE_IMAGE", &repo_tag) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(), + ); + wait_for("child pauses with staged part", || { + home.join("paused").exists() + }); + child.kill_and_wait(); + + // 3. machine.images must enumerate both V1 (unpacked) and V2's staged part! + let rows = image_rows(&home); + let v1_row = rows + .iter() + .find(|r| r.get_text("id") == Some(v1_id.as_str()) && !r.get_bool("staged")) + .expect("V1 published row"); + assert!(cache::texts(v1_row.get("refs")).contains(&repo_tag)); + + let v2_part = rows + .iter() + .find(|r| r.get_text("id") == Some(v2_id.as_str()) && r.get_bool("staged")) + .unwrap_or_else(|| panic!("missing staged part row for V2 in machine.images: {rows:?}")); + let part_len = fs::symlink_metadata(cache::cache(&home).join(format!(".recv-{v2_hex}.part"))) + .unwrap() + .len(); + assert_eq!(v2_part.get_int("size"), Some(part_len as i64)); + assert!(v2_part.get_int("age").is_some_and(|a| a >= 0)); + assert!(v2_part.get_bool("resumable")); + + // 4. Finish loading repo_tag: V2 publishes, clears stale repo_tag from V1 sidecar, records config. + std::thread::sleep(Duration::from_millis(2200)); + let loaded2 = run_load(&docker, &home, "native", &repo_tag).unwrap(); + assert_eq!(loaded2.id, v2_id); + assert!(!loaded2.reused); + + let v1_sidecar = Sidecar::read(&cache::cache(&home), &v1_hex) + .unwrap() + .unwrap(); + assert!( + !v1_sidecar.refs.contains(&repo_tag), + "stale ref {repo_tag} must be removed from V1 sidecar: {v1_sidecar:?}" + ); + let v2_sidecar = Sidecar::read(&cache::cache(&home), &v2_hex) + .unwrap() + .unwrap(); + assert!(v2_sidecar.refs.contains(&repo_tag)); + + // Offline ref probe must resolve to V2, never V1. + let probe_by_ref = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("probe")), + ("ref", SdkValue::text(&repo_tag)), + ]), + ) + .unwrap(); + assert_eq!(probe_by_ref.get_text("id"), Some(v2_id.as_str())); + + let rows_after = image_rows(&home); + assert!(!rows_after.iter().any(|r| r.get_bool("staged"))); + let v2_row = rows_after + .iter() + .find(|r| r.get_text("id") == Some(v2_id.as_str())) + .unwrap(); + let cfg = v2_row + .get("config") + .expect("config visible in machine.images"); + assert_eq!(cfg.get_text("WorkingDir"), Some("/app")); + assert_eq!(cfg.get_text("User"), Some("1000:1000")); +} + +#[test] +fn prune_reclaims_parts_temps_and_stranded_while_protecting_live_locks_and_in_use() { + let scratch = Scratch::new("lp176-rec-prune"); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + home::ensure(&home).unwrap(); + let cache_dir = cache::cache(&home); + fs::create_dir_all(&cache_dir).unwrap(); + + let hex_unheld = "1".repeat(64); + let hex_stranded = "2".repeat(64); + let hex_dangling = "3".repeat(64); + let hex_locked = "4".repeat(64); + let id_locked = format!("sha256:{hex_locked}"); + let hex_inuse = "5".repeat(64); + let id_inuse = format!("sha256:{hex_inuse}"); + let hex_held = "6".repeat(64); + let id_held = format!("sha256:{hex_held}"); + + // 1. Unheld part + temp dir. + cache::write(&cache_dir, &hex_unheld, 0, b"partial-tar-bytes").unwrap(); + fs::create_dir_all(cache_dir.join(format!(".tmp-{hex_unheld}.2-ab12/usr"))).unwrap(); + + // 2. Stranded unpacked dir (no .2.json) + dangling sidecar (no .2 dir). + let flat_tar = scratch.base.join("flat.tar"); + let small_tar = filtered_bytes(&Tar::new().file("etc/a", 0o644, b"a").finish()).unwrap(); + fs::write(&flat_tar, &small_tar).unwrap(); + rootfs::ensure_flat( + &flat_tar, + &Image::parse(&format!("sha256:{hex_stranded}")).unwrap(), + &cache_dir, + ) + .unwrap(); + Sidecar { + id: format!("sha256:{hex_dangling}"), + refs: vec!["dangling:1".to_owned()], + size: Some(10), + architecture: Some(architecture().to_owned()), + source: "imported".to_owned(), + config: SdkValue::Null, + last_used: None, + } + .write(&cache_dir) + .unwrap(); + + // 3. Live-locked part + temp dir (held by child process). + cache::write(&cache_dir, &hex_locked, 0, b"locked-partial-bytes").unwrap(); + fs::create_dir_all(cache_dir.join(format!(".tmp-{hex_locked}.2-cd34/bin"))).unwrap(); + let mut lock_child = ChildGuard::new( + Command::new(std::env::current_exe().unwrap()) + .args(["--exact", "helper_hold_image_lock", "--nocapture"]) + .env("LP176_REC_LOCK_HOME", &home) + .env("LP176_REC_LOCK_MACHINE", "native") + .env("LP176_REC_LOCK_IMAGE", &id_locked) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(), + ); + wait_for("lock child holds ImageLock", || { + home.join("lock-held").exists() + }); + + // 4. InUse image via helper.spec lower= (with an extra part + temp dir too) and ImageHold. + rootfs::ensure_flat(&flat_tar, &Image::parse(&id_inuse).unwrap(), &cache_dir).unwrap(); + Sidecar { + id: id_inuse.clone(), + refs: vec!["inuse:1".to_owned()], + size: Some(small_tar.len() as u64), + architecture: Some(architecture().to_owned()), + source: "imported".to_owned(), + config: SdkValue::Null, + last_used: None, + } + .write(&cache_dir) + .unwrap(); + cache::write(&cache_dir, &hex_inuse, 0, b"inuse-part").unwrap(); + let spec_dir = cache_dir.parent().unwrap().join("sb-active/config"); + fs::create_dir_all(&spec_dir).unwrap(); + fs::write( + spec_dir.join("helper.spec"), + format!( + "root=/x\nlower={}\n", + cache_dir.join(format!("{hex_inuse}.2")).display() + ), + ) + .unwrap(); + rootfs::ensure_flat(&flat_tar, &Image::parse(&id_held).unwrap(), &cache_dir).unwrap(); + Sidecar { + id: id_held.clone(), + refs: vec!["held:1".to_owned()], + size: Some(small_tar.len() as u64), + architecture: Some(architecture().to_owned()), + source: "imported".to_owned(), + config: SdkValue::Null, + last_used: None, + } + .write(&cache_dir) + .unwrap(); + let (_, hold) = + rootfs::ensure_held(&flat_tar, &Image::parse(&id_held).unwrap(), &cache_dir).unwrap(); + + // Verify machine.images shows unheld part as resumable=true and locked part as resumable=false. + let rows = image_rows(&home); + let r_unheld = rows + .iter() + .find(|r| r.get_text("id") == Some(&format!("sha256:{hex_unheld}")) && r.get_bool("staged")) + .expect("unheld staged part listed"); + assert!(r_unheld.get_bool("resumable")); + let r_locked = rows + .iter() + .find(|r| r.get_text("id") == Some(&id_locked) && r.get_bool("staged")) + .expect("locked staged part listed"); + assert!( + !r_locked.get_bool("resumable"), + "live-locked part must not be resumable: {r_locked:?}" + ); + + // Targeted prune on live-locked or InUse must refuse InUse. + assert_eq!( + images::prune(&home, &native_name(), Some(&id_locked), false) + .unwrap_err() + .code, + "InUse" + ); + assert_eq!( + images::prune(&home, &native_name(), Some(&id_inuse), false) + .unwrap_err() + .code, + "InUse" + ); + + // Unused prune must clean unheld part, unheld temp, stranded image, and dangling sidecar, + // while leaving live-locked and InUse artifacts untouched. + images::prune(&home, &native_name(), None, true).unwrap(); + + assert!(!cache_dir.join(format!(".recv-{hex_unheld}.part")).exists()); + assert!(!cache_dir.join(format!(".tmp-{hex_unheld}.2-ab12")).exists()); + assert!(!cache_dir.join(format!("{hex_stranded}.2")).exists()); + assert!(!cache_dir.join(format!("{hex_dangling}.2.json")).exists()); + + assert!(cache_dir.join(format!(".recv-{hex_locked}.part")).exists()); + assert!(cache_dir.join(format!(".tmp-{hex_locked}.2-cd34")).exists()); + assert!(cache_dir.join(format!("{hex_inuse}.2")).exists()); + assert!(cache_dir.join(format!("{hex_inuse}.2.json")).exists()); + assert!(cache_dir.join(format!(".recv-{hex_inuse}.part")).exists()); + assert!(cache_dir.join(format!("{hex_held}.2")).exists()); + + // Release locks and InUse, then prune locked part explicitly by target id before unused sweep. + lock_child.kill_and_wait(); + drop(hold); + fs::remove_dir_all(cache_dir.parent().unwrap().join("sb-active")).unwrap(); + + // Targeted prune can remove a part-only digest and then reports NotFound once gone. + let single = images::prune(&home, &native_name(), Some(&id_locked), false).unwrap(); + assert_eq!( + single.get("removed"), + Some(&SdkValue::List(vec![SdkValue::text(&id_locked)])) + ); + assert_eq!( + images::prune(&home, &native_name(), Some(&id_locked), false) + .unwrap_err() + .code, + "NotFound" + ); + + images::prune(&home, &native_name(), None, true).unwrap(); + let leftovers: Vec = fs::read_dir(&cache_dir) + .unwrap() + .filter_map(|e| e.ok()) + .filter_map(|e| e.file_name().into_string().ok()) + .filter(|n| !n.ends_with(".lock")) + .collect(); + assert!( + leftovers.is_empty(), + "expected clean cache after prune, left: {leftovers:?}" + ); +} + +#[test] +fn interrupted_publish_with_renamed_dir_and_missing_sidecar_recovers_and_prunes() { + let scratch = Scratch::new("lp176-rec-publish"); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + home::ensure(&home).unwrap(); + let cache_dir = cache::cache(&home); + fs::create_dir_all(&cache_dir).unwrap(); + + let hex = "7".repeat(64); + let id = format!("sha256:{hex}"); + let tar_bytes = filtered_bytes( + &Tar::new() + .directory("etc/", 0o755) + .file("etc/hello", 0o644, b"world\n") + .finish(), + ) + .unwrap(); + + // Stage part and simulate crash right after ensure_flat renamed `.2` before Sidecar::write. + cache::write(&cache_dir, &hex, 0, &tar_bytes).unwrap(); + let part_path = cache_dir.join(format!(".recv-{hex}.part")); + rootfs::ensure_flat(&part_path, &Image::parse(&id).unwrap(), &cache_dir).unwrap(); + assert!(cache_dir.join(format!("{hex}.2")).is_dir()); + assert!(!cache_dir.join(format!("{hex}.2.json")).exists()); + + // probe must NOT claim an unpublished directory without sidecar is present. + let probed = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("probe")), + ("id", SdkValue::text(&id)), + ]), + ) + .unwrap(); + assert!( + !probed.get_bool("present"), + "dir without sidecar must not be treated as published: {probed:?}" + ); + assert!(probed.get_bool("stranded")); + assert_eq!(probed.get_int("offset"), Some(tar_bytes.len() as i64)); + let deploy = layerfs_sandbox::host::Deploy { + sandbox: Some("namespaces".to_owned()), + local_dir: cache::cache(&home) + .parent() + .unwrap() + .to_str() + .map(str::to_owned), + container_prefix: None, + legacy_prefix: None, + daemon: None, + image_archive: None, + image: Some(id.clone()), + platform: None, + }; + assert!(!cache::unpacked(&deploy, &Image::parse(&id).unwrap())); + let rows_before = image_rows(&home); + assert!(rows_before + .iter() + .any(|r| r.get_text("id") == Some(id.as_str()) && r.get_bool("stranded"))); + + // Stand-in Docker recovery load completes publish, writes sidecar, deletes .part. + let standin_dir = scratch.base.join("standin"); + fs::create_dir_all(standin_dir.join("images")).unwrap(); + let script = r#"#!/bin/sh +D="$(dirname "$0")" +key() { printf '%s' "$1" | tr '/:' '__'; } +case "$1 $2" in + "image inspect") + shift 4 + cat "$D/images/$(key "$1").json"; echo; exit 0 ;; + "container inspect") + if [ "$3" = "--size" ]; then echo 0; exit 0; fi + if [ -f "$D/containers/$5" ]; then echo id; exit 0; fi + echo "No such object" >&2; exit 1 ;; +esac +case "$1" in + create) mkdir -p "$D/containers"; while [ $# -gt 0 ]; do case "$1" in --name) n="$2"; shift 2;; *) shift;; esac; done; : > "$D/containers/$n"; echo id ;; + export) cat "$D/export.tar" ;; + history) echo 0 ;; + rm) shift; [ "$1" = "-f" ] && shift; [ "$1" = "-v" ] && shift; rm -f "$D/containers/$1" ;; + ps) ;; +esac +"#; + let dbin = standin_dir.join("docker"); + fs::write(&dbin, script).unwrap(); + fs::set_permissions(&dbin, fs::Permissions::from_mode(0o755)).unwrap(); + let json = format!( + r#"{{"Id":"{id}","RepoTags":["rec/app:1"],"Os":"linux","Architecture":"{}","Size":100,"Config":{{"Env":["A=1"],"WorkingDir":"/srv","User":"app"}}}}"#, + architecture() + ); + for k in ["rec/app:1", &id] { + fs::write( + standin_dir + .join("images") + .join(format!("{}.json", k.replace(['/', ':'], "_"))), + &json, + ) + .unwrap(); + } + fs::write(standin_dir.join("export.tar"), &tar_bytes).unwrap(); + + let docker = Docker::at(Some(dbin), None); + let loaded = run_load(&docker, &home, "native", "rec/app:1").unwrap(); + assert_eq!(loaded.id, id); + assert!(!loaded.reused); + assert!(Sidecar::read(&cache_dir, &hex).unwrap().is_some()); + assert!(!part_path.exists()); + + // Subsequent probe sees present=true, and cache::unpacked sees true. + assert!(cache::unpacked(&deploy, &Image::parse(&id).unwrap())); + let probed2 = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("probe")), + ("id", SdkValue::text(&id)), + ]), + ) + .unwrap(); + assert!(probed2.get_bool("present")); + assert!(!probed2.get_bool("stranded")); +} + +#[test] +fn ambiguous_ref_is_refused_and_moved_ref_never_selects_old_image() { + let scratch = Scratch::new("lp176-rec-refs"); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + let cache_dir = cache::cache(&home); + fs::create_dir_all(&cache_dir).unwrap(); + let tar_bytes = filtered_bytes(&Tar::new().file("f", 0o644, b"x").finish()).unwrap(); + let sha = sha256_hex(&tar_bytes); + + let hex1 = "8".repeat(64); + let id1 = format!("sha256:{hex1}"); + let hex2 = "9".repeat(64); + let id2 = format!("sha256:{hex2}"); + + // Two images both claiming "shared/app:latest" -> ambiguous ref must be refused naming the ref. + cache::write(&cache_dir, &hex1, 0, &tar_bytes).unwrap(); + step( + &home, + SdkValue::map([ + ("step", SdkValue::text("publish")), + ("id", SdkValue::text(&id1)), + ("size", SdkValue::Int(tar_bytes.len() as i64)), + ("sha256", SdkValue::text(&sha)), + ( + "refs", + SdkValue::List(vec![SdkValue::text("shared/app:latest")]), + ), + ]), + ) + .unwrap(); + + cache::write(&cache_dir, &hex2, 0, &tar_bytes).unwrap(); + let flat2 = scratch.base.join("flat2.tar"); + fs::write(&flat2, &tar_bytes).unwrap(); + rootfs::ensure_flat(&flat2, &Image::parse(&id2).unwrap(), &cache_dir).unwrap(); + Sidecar { + id: id2.clone(), + refs: vec!["shared/app:latest".to_owned()], + size: Some(tar_bytes.len() as u64), + architecture: Some(architecture().to_owned()), + source: "imported".to_owned(), + config: SdkValue::Null, + last_used: None, + } + .write(&cache_dir) + .unwrap(); + + let err = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("probe")), + ("ref", SdkValue::text("shared/app:latest")), + ]), + ) + .unwrap_err(); + assert_eq!(err.code, "InvalidInput", "{err:?}"); + assert!( + err.message.contains("shared/app:latest"), + "ambiguous ref error must name the ref: {}", + err.message + ); + + let offline = Docker::at(None, None); + let load_err = run_load(&offline, &home, "native", "shared/app:latest").unwrap_err(); + assert!( + load_err.message.contains("shared/app:latest"), + "{load_err:?}" + ); + + // Publish id2 with "moved/app:latest" after id1 had ["moved/app:latest", "moved/app:v1"]: + // id1 must lose "moved/app:latest" and keep "moved/app:v1". + let hex_old = "a".repeat(64); + let id_old = format!("sha256:{hex_old}"); + let hex_new = "b".repeat(64); + let id_new = format!("sha256:{hex_new}"); + cache::write(&cache_dir, &hex_old, 0, &tar_bytes).unwrap(); + step( + &home, + SdkValue::map([ + ("step", SdkValue::text("publish")), + ("id", SdkValue::text(&id_old)), + ("size", SdkValue::Int(tar_bytes.len() as i64)), + ("sha256", SdkValue::text(&sha)), + ( + "refs", + SdkValue::List(vec![ + SdkValue::text("moved/app:latest"), + SdkValue::text("moved/app:v1"), + ]), + ), + ]), + ) + .unwrap(); + + cache::write(&cache_dir, &hex_new, 0, &tar_bytes).unwrap(); + step( + &home, + SdkValue::map([ + ("step", SdkValue::text("publish")), + ("id", SdkValue::text(&id_new)), + ("size", SdkValue::Int(tar_bytes.len() as i64)), + ("sha256", SdkValue::text(&sha)), + ( + "refs", + SdkValue::List(vec![SdkValue::text("moved/app:latest")]), + ), + ]), + ) + .unwrap(); + + let old_sidecar = Sidecar::read(&cache_dir, &hex_old).unwrap().unwrap(); + assert_eq!(old_sidecar.refs, vec!["moved/app:v1".to_owned()]); + let p_latest = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("probe")), + ("ref", SdkValue::text("moved/app:latest")), + ]), + ) + .unwrap(); + assert_eq!(p_latest.get_text("id"), Some(id_new.as_str())); + let p_v1 = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("probe")), + ("ref", SdkValue::text("moved/app:v1")), + ]), + ) + .unwrap(); + assert_eq!(p_v1.get_text("id"), Some(id_old.as_str())); +} + +#[test] +fn sparse_files_expand_with_exact_bytes_and_hardlink_to_dropped_target_fails() { + let scratch = Scratch::new("lp176-rec-sparse-hl"); + + // 1. GNU oldgnu sparse file with 5 chunks (exercises extended sparse header block) + trailing hole. + let mut expected_gnu = vec![0u8; 32 * 1024]; + expected_gnu[0..4].copy_from_slice(b"C000"); + expected_gnu[4096..4100].copy_from_slice(b"C001"); + expected_gnu[8192..8196].copy_from_slice(b"C002"); + expected_gnu[16384..16388].copy_from_slice(b"C003"); + expected_gnu[24576..24581].copy_from_slice(b"C004!"); + let gnu_tar = build_gnu_sparse_tar( + "var/big.bin", + 0o640, + 1_700_000_222, + expected_gnu.len() as u64, + &[ + (0, b"C000"), + (4096, b"C001"), + (8192, b"C002"), + (16384, b"C003"), + (24576, b"C004!"), + ], + ); + let (filtered_gnu, report_gnu) = filtered_with_report(&gnu_tar).expect("filter GNU sparse tar"); + assert_eq!(report_gnu.sparse_files.len(), 1); + assert_eq!(report_gnu.sparse_files[0].path, "var/big.bin"); + assert_eq!(report_gnu.sparse_files[0].expanded_bytes, 32 * 1024); + assert_eq!(report_gnu.sparse_files[0].stored_bytes, 21); + assert_eq!(report_gnu.sparse_expanded_bytes, 32 * 1024); + let gnu_path = scratch.base.join("gnu.tar"); + fs::write(&gnu_path, &filtered_gnu).unwrap(); + let (root1, _) = rootfs::ensure_flat( + &gnu_path, + &Image::parse(&format!("sha256:{}", "c".repeat(64))).unwrap(), + &scratch.cache, + ) + .unwrap(); + let unpacked_gnu = fs::read(root1.directory().join("var/big.bin")).unwrap(); + assert_eq!(sha256_hex(&unpacked_gnu), sha256_hex(&expected_gnu)); + let meta_gnu = fs::symlink_metadata(root1.directory().join("var/big.bin")).unwrap(); + assert_eq!(meta_gnu.permissions().mode() & 0o777, 0o640); + assert_eq!( + meta_gnu + .modified() + .unwrap() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_secs(), + 1_700_000_222 + ); + + // 2. PAX 1.0 sparse file (real GNU tar --format=posix --sparse). + let pax_src = scratch.base.join("pax_src"); + fs::create_dir_all(&pax_src).unwrap(); + let sp_file = pax_src.join("pax.bin"); + { + use std::io::{Seek, SeekFrom, Write}; + let mut f = fs::File::create(&sp_file).unwrap(); + f.write_all(b"HEAD").unwrap(); + f.seek(SeekFrom::Start(65_536)).unwrap(); + f.write_all(b"TAIL").unwrap(); + f.set_len(131_072).unwrap(); + } + let expected_pax = fs::read(&sp_file).unwrap(); + let pax_tar = Command::new("tar") + .args(["--format=posix", "--sparse", "-cf", "-", "-C"]) + .arg(&pax_src) + .arg("pax.bin") + .output() + .unwrap(); + assert!(pax_tar.status.success()); + let (filtered_pax, report_pax) = + filtered_with_report(&pax_tar.stdout).expect("filter PAX sparse tar"); + assert_eq!(report_pax.sparse_files.len(), 1); + assert_eq!(report_pax.sparse_files[0].path, "pax.bin"); + assert_eq!(report_pax.sparse_files[0].expanded_bytes, 131_072); + assert_eq!(report_pax.sparse_expanded_bytes, 131_072); + let pax_path = scratch.base.join("pax.tar"); + fs::write(&pax_path, &filtered_pax).unwrap(); + let (root2, _) = rootfs::ensure_flat( + &pax_path, + &Image::parse(&format!("sha256:{}", "d".repeat(64))).unwrap(), + &scratch.cache, + ) + .unwrap(); + let unpacked_pax = fs::read(root2.directory().join("pax.bin")).unwrap(); + assert_eq!(sha256_hex(&unpacked_pax), sha256_hex(&expected_pax)); + + // 2b. PAX 0.1 sparse entry (`GNU.sparse.map`) and PAX 0.0 (`offset`/`numbytes`). + let mut pax01_meta = pax_record("GNU.sparse.major", "0"); + pax01_meta.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + pax01_meta.extend_from_slice(&pax_record("GNU.sparse.name", "opt/sp01.bin")); + pax01_meta.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); + pax01_meta.extend_from_slice(&pax_record("GNU.sparse.map", "0,4,8192,4")); + let mut pax00_meta = pax_record("GNU.sparse.major", "0"); + pax00_meta.extend_from_slice(&pax_record("GNU.sparse.minor", "0")); + pax00_meta.extend_from_slice(&pax_record("GNU.sparse.name", "opt/sp00.bin")); + pax00_meta.extend_from_slice(&pax_record("GNU.sparse.realsize", "8192")); + pax00_meta.extend_from_slice(&pax_record("GNU.sparse.offset", "4096")); + pax00_meta.extend_from_slice(&pax_record("GNU.sparse.numbytes", "5")); + let pax0x_tar = Tar::new() + .directory("opt/", 0o755) + .raw("PaxHeaders/sp01", b'x', 0o644, &pax01_meta) + .file("opt/sp01.bin", 0o644, b"ABCDWXYZ") + .raw("PaxHeaders/sp00", b'x', 0o644, &pax00_meta) + .file("opt/sp00.bin", 0o644, b"12345") + .finish(); + let (filtered_0x, report_0x) = + filtered_with_report(&pax0x_tar).expect("filter PAX 0.x sparse tar"); + assert_eq!(report_0x.sparse_files.len(), 2); + assert_eq!(report_0x.sparse_expanded_bytes, 16_384 + 8_192); + let pax0x_path = scratch.base.join("pax0x.tar"); + fs::write(&pax0x_path, &filtered_0x).unwrap(); + let (root2b, _) = rootfs::ensure_flat( + &pax0x_path, + &Image::parse(&format!("sha256:{}", "0".repeat(64))).unwrap(), + &scratch.cache, + ) + .unwrap(); + let mut expected_01 = vec![0u8; 16_384]; + expected_01[..4].copy_from_slice(b"ABCD"); + expected_01[8192..8196].copy_from_slice(b"WXYZ"); + assert_eq!( + fs::read(root2b.directory().join("opt/sp01.bin")).unwrap(), + expected_01 + ); + let mut expected_00 = vec![0u8; 8_192]; + expected_00[4096..4101].copy_from_slice(b"12345"); + assert_eq!( + fs::read(root2b.directory().join("opt/sp00.bin")).unwrap(), + expected_00 + ); + + // 3. Hardlinks pointing to dropped targets must produce a clear error. + let bad_init = Tar::new() + .file("etc/hosts", 0o644, b"127.0.0.1 localhost\n") + .hard_link("app/hosts-alias", "etc/hosts") + .finish(); + let err_init = filtered_bytes(&bad_init).unwrap_err(); + let msg_init = err_init.to_string(); + assert!( + msg_init.contains("etc/hosts") && msg_init.contains("app/hosts-alias"), + "hardlink->dropped init error unclear: {msg_init}" + ); + + let bad_fifo = Tar::new() + .raw("var/run/pipe", b'6', 0o644, b"") + .hard_link("app/pipe-alias", "var/run/pipe") + .finish(); + let err_fifo = filtered_bytes(&bad_fifo).unwrap_err(); + let msg_fifo = err_fifo.to_string(); + assert!( + msg_fifo.contains("var/run/pipe") && msg_fifo.contains("app/pipe-alias"), + "hardlink->dropped fifo error unclear: {msg_fifo}" + ); + + let bad_dev = Tar::new() + .raw("tmp/null", b'3', 0o666, b"") + .hard_link("app/null-alias", "tmp/null") + .finish(); + let err_dev = filtered_bytes(&bad_dev).unwrap_err(); + let msg_dev = err_dev.to_string(); + assert!( + msg_dev.contains("tmp/null") && msg_dev.contains("app/null-alias"), + "hardlink->dropped device error unclear: {msg_dev}" + ); + + // 4. Hardlink to a kept file succeeds and preserves shared inode. + let good_hl = Tar::new() + .directory("usr/", 0o755) + .file("usr/orig", 0o644, b"shared-bytes\n") + .hard_link("usr/alias", "usr/orig") + .finish(); + let filtered_hl = filtered_bytes(&good_hl).unwrap(); + let hl_path = scratch.base.join("hl.tar"); + fs::write(&hl_path, &filtered_hl).unwrap(); + let (root3, _) = rootfs::ensure_flat( + &hl_path, + &Image::parse(&format!("sha256:{}", "e".repeat(64))).unwrap(), + &scratch.cache, + ) + .unwrap(); + assert_eq!( + fs::symlink_metadata(root3.directory().join("usr/orig")) + .unwrap() + .ino(), + fs::symlink_metadata(root3.directory().join("usr/alias")) + .unwrap() + .ino() + ); +} + +#[test] +fn real_docker_and_small_tar_preserve_mtime_mode_sha_and_record_config() { + let scratch = Scratch::new("lp176-rec-meta"); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + let cache_dir = cache::cache(&home); + fs::create_dir_all(&cache_dir).unwrap(); + + // Verify small tar mtime, mode, sha, symlink, hardlink vs declared drops (FIFO, dev, init, dir mtime=0). + let mut pax_link = pax_record("mtime", "1700000777.25"); + pax_link.extend_from_slice(&pax_record("linkpath", "/etc/app.conf")); + let input = Tar::new() + .at(1_700_000_111) + .file(".dockerenv", 0o755, b"") + .directory("dev/", 0o755) + .file("dev/console", 0o600, b"") + .directory("etc/", 0o750) + .file("etc/hosts", 0o644, b"127.0.0.1\n") + .file("etc/app.conf", 0o640, b"secret-config\n") + .raw("PaxHeaders/etc/link", b'x', 0o644, &pax_link) + .symlink("etc/link", "") + .at(1_700_000_333) + .file("etc/exec.sh", 0o755, b"#!/bin/sh\n") + .hard_link("etc/exec_hl.sh", "etc/exec.sh") + .raw("var/fifo", b'6', 0o644, b"") + .raw("var/chr", b'3', 0o660, b"") + .finish(); + let (filtered, report) = filtered_with_report(&input).unwrap(); + assert_eq!(report.fifo_count(), 1); + assert_eq!(report.fifos, vec!["var/fifo"]); + assert_eq!(report.device_count(), 1); + assert_eq!(report.devices, vec!["var/chr"]); + assert_eq!(report.init_count(), 3); + assert_eq!(report.init, vec![".dockerenv", "dev/console", "etc/hosts"]); + let tar_path = scratch.base.join("meta.tar"); + fs::write(&tar_path, &filtered).unwrap(); + let hex = "f".repeat(64); + let id = format!("sha256:{hex}"); + let (root, _) = + rootfs::ensure_flat(&tar_path, &Image::parse(&id).unwrap(), &cache_dir).unwrap(); + let r = root.directory(); + + // Declared losses: init, dev/*, FIFO, device are dropped; directory mtime is normalized to 0. + assert!(!r.join(".dockerenv").exists()); + assert!(!r.join("dev/console").exists()); + assert!(!r.join("etc/hosts").exists()); + assert!(!r.join("var/fifo").exists()); + assert!(!r.join("var/chr").exists()); + assert!(r.join("dev").is_dir()); + assert_eq!( + fs::symlink_metadata(r.join("etc")) + .unwrap() + .modified() + .unwrap() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_secs(), + 0 + ); + + // Non-lost attributes must be preserved. + assert_eq!( + sha256_hex(&fs::read(r.join("etc/app.conf")).unwrap()), + sha256_hex(b"secret-config\n") + ); + assert_eq!( + fs::symlink_metadata(r.join("etc")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o750 + ); + assert_eq!( + fs::symlink_metadata(r.join("etc/app.conf")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o640 + ); + assert_eq!( + fs::symlink_metadata(r.join("etc/exec.sh")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o755 + ); + assert_eq!( + fs::symlink_metadata(r.join("etc/app.conf")) + .unwrap() + .modified() + .unwrap() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_secs(), + 1_700_000_111 + ); + assert_eq!( + fs::symlink_metadata(r.join("etc/exec.sh")) + .unwrap() + .modified() + .unwrap() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_secs(), + 1_700_000_333 + ); + assert_eq!( + fs::symlink_metadata(r.join("etc/link")) + .unwrap() + .modified() + .unwrap() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_secs(), + 1_700_000_777 + ); + assert_eq!( + fs::symlink_metadata(r.join("etc/exec.sh")).unwrap().ino(), + fs::symlink_metadata(r.join("etc/exec_hl.sh")) + .unwrap() + .ino() + ); + + // Publish with variant + config (Env, WorkingDir, User) and verify publish/probe/touch/machine.images + // preserve them without applying them. + let sha = sha256_hex(&filtered); + cache::write(&cache_dir, &hex, 0, &filtered).unwrap(); + let cfg = SdkValue::map([ + ( + "Env", + SdkValue::List(vec![SdkValue::text("LP176_TEST_VAR=recorded_only")]), + ), + ("WorkingDir", SdkValue::text("/srv/work")), + ("User", SdkValue::text("nobody")), + ]); + let pub_out = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("publish")), + ("id", SdkValue::text(&id)), + ("size", SdkValue::Int(filtered.len() as i64)), + ("sha256", SdkValue::text(&sha)), + ("refs", SdkValue::List(vec![SdkValue::text("meta/app:1")])), + ("architecture", SdkValue::text(architecture())), + ("variant", SdkValue::text("v8")), + ("config", cfg.clone()), + ]), + ) + .unwrap(); + assert_eq!(pub_out.get_text("variant"), Some("v8")); + assert_eq!(pub_out.get("config"), Some(&cfg)); + assert!(std::env::var_os("LP176_TEST_VAR").is_none()); + let probed = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("probe")), + ("id", SdkValue::text(&id)), + ]), + ) + .unwrap(); + assert_eq!(probed.get_text("variant"), Some("v8")); + assert_eq!(probed.get("config"), Some(&cfg)); + cache::touch(&layerfs_sandbox::deploy::Side::Home(&home), None, &id).unwrap(); + let rows = image_rows(&home); + let row = rows + .iter() + .find(|r| r.get_text("id") == Some(id.as_str())) + .unwrap(); + assert_eq!(row.get_text("variant"), Some("v8")); + assert_eq!( + row.get("config"), + Some(&cfg), + "config must be visible in machine.images: {row:?}" + ); + + // Also test real Docker image with ENV/WORKDIR/USER/FIFO/mode/mtime. + if docker_available() { + let mut guard = DockerGuard::new("lp176-rec-docker-meta"); + let pid = std::process::id(); + let seq = SEQ.fetch_add(1, Ordering::Relaxed); + let base_tag = format!("layerfs-lp176-rec-mbase-{pid}-{seq}:test"); + let final_tag = format!("layerfs-lp176-rec-mfinal-{pid}-{seq}:test"); + let dtar = Tar::new() + .at(1_700_000_500) + .directory("app/", 0o755) + .file("app/run.sh", 0o750, b"#!/bin/sh\necho ok\n") + .symlink("app/run.link", "/app/run.sh") + .raw("app/p.fifo", b'6', 0o644, b"") + .file("app/blob", 0o644, &vec![0x33; CHUNK + 1024]) + .finish(); + guard.import_tar(&base_tag, &dtar); + let did = guard.build_dockerfile( + &final_tag, + &format!("FROM {base_tag}\nENV LP176_DOCKER_ENV=yes\nWORKDIR /app\nUSER 1001:1001\n"), + ); + let dhex = did.strip_prefix("sha256:").unwrap().to_owned(); + let (dhome, _) = guard.make_home("dhome"); + let docker = real_docker(); + run_load(&docker, &dhome, "native", &final_tag).unwrap(); + let droot = cache::cache(&dhome).join(format!("{dhex}.2")); + assert!(!droot.join("app/p.fifo").exists()); + assert_eq!( + fs::symlink_metadata(droot.join("app/run.sh")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o750 + ); + assert_eq!( + sha256_hex(&fs::read(droot.join("app/run.sh")).unwrap()), + sha256_hex(b"#!/bin/sh\necho ok\n") + ); + let drows = image_rows(&dhome); + let drow = drows + .iter() + .find(|r| r.get_text("id") == Some(did.as_str())) + .unwrap(); + let dcfg = drow + .get("config") + .expect("real Docker config visible in machine.images"); + assert_eq!(dcfg.get_text("WorkingDir"), Some("/app")); + assert_eq!(dcfg.get_text("User"), Some("1001:1001")); + } +} + +#[test] +fn helper_pause_load() { + let Ok(home) = std::env::var("LP176_REC_PAUSE_HOME") else { + return; + }; + let home = PathBuf::from(home); + let machine = std::env::var("LP176_REC_PAUSE_MACHINE").unwrap(); + let image = std::env::var("LP176_REC_PAUSE_IMAGE").unwrap(); + let docker = real_docker(); + let mut paused = false; + let mut sink = |event: SdkValue| { + if !paused { + if let Some(p) = event.get("progress") { + if p.get_text("phase") == Some("send") + && p.get_int("done").unwrap_or(0) >= CHUNK as i64 + { + paused = true; + fs::write(home.join("paused"), b"").unwrap(); + while !home.join("proceed").exists() { + std::thread::sleep(Duration::from_millis(20)); + } + } + } + } + }; + let mut events = Events::new(&mut sink); + let _ = load( + &docker, + &mut events, + &mut Target::local(&home, &machine), + None, + &image, + ); +} + +#[test] +fn helper_hold_image_lock() { + let Ok(home) = std::env::var("LP176_REC_LOCK_HOME") else { + return; + }; + let home = PathBuf::from(home); + let machine = std::env::var("LP176_REC_LOCK_MACHINE").unwrap(); + let image = std::env::var("LP176_REC_LOCK_IMAGE").unwrap(); + let mut sink = |_: SdkValue| {}; + let _held = ImageLock::take(&home, &machine, &image, &mut Events::new(&mut sink)).unwrap(); + fs::write(home.join("lock-held"), b"").unwrap(); + for _ in 0..120 { + std::thread::sleep(Duration::from_secs(1)); + } +} diff --git a/docs/architecture/api/sdk/machine.md b/docs/architecture/api/sdk/machine.md index e25ac270c..9deded854 100644 --- a/docs/architecture/api/sdk/machine.md +++ b/docs/architecture/api/sdk/machine.md @@ -163,24 +163,31 @@ CLI layerfs machine images ```text { machine, mode: "images" | "host", architecture, default, free, - images: [{ id, refs, size, architecture, source, sandboxes, last_used }], + images: [{ id, refs, size, architecture, source, variant, config, sandboxes, last_used, staged, stranded?, age?, resumable? }], docker: null | { available: true } | { available: false, reason: "not-installed" | "not-running" | "error", message }, available: [{ id, refs, size, os, architecture, usable, reason?, need, fits }] } ``` -`images` are the unpacked images with their sidecars +`images` lists published unpacked images with their sidecars (`machines/native/run/images/.2.json`: `source: "imported"` for one -copied from Docker) and what the archives its Sandboxes read still hold -(`bundle`, `machine`), unpacked or not. `id` is the Docker image Id for an +copied from Docker, `staged: false`), what the archives its Sandboxes read +still hold (`bundle`, `machine`, `staged: false`), staged partial downloads +(`.recv-.part`: `source: "staged"`, `staged: true`, received `size`, `age` +in seconds, and `resumable` true only when a non-empty regular file is not yet +published and not held by a live `ImageLock` or `.2.lock`), and any stranded +unpacked directories left without a sidecar (`source: "stranded"`, +`staged: false`, `stranded: true`). `variant` and `config` (such as `Env`, +`WorkingDir`, `User`) are recorded on import/publish and surfaced without +being applied. `id` is the Docker image Id for an imported image and the config digest for an archive's. `sandboxes` counts the Sandbox records on this machine naming that `id`; `last_used` is the last create's time (RFC 3339) or null. `default` is the record's image, else the archive's only one. `free` is the image cache's free bytes. `available` lists the host's tagged Docker images (one `docker image ls`, one batched `docker image inspect`, 10 s each) through the `docker` machine's socket, -else Docker's default context, minus any whose id or refs `images` already -has (the bundle's image in Docker, `layerfs-cache/sandbox:`, included). +else Docker's default context, minus any published id or refs (`images` entries +with `!staged && !stranded`, the bundle's image in Docker, `layerfs-cache/sandbox:`, included). A row for another OS or architecture is `usable: false` with `reason {kind: "os" | "arch", value}`. `size` is what the image's layers unpack to: the sum of `docker history`'s layer sizes (one call per image, eight at a time, @@ -227,12 +234,23 @@ legacy `layerfs-export--` containers labeled `layerfs.export.started` are no longer swept automatically and require manual `docker rm`) and stream `docker export` without the init layer's files (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, `etc/mtab`, -`dev/*`), device or FIFO entries, and with directory modification times -normalized to epoch 0 (`1970-01-01T00:00:00Z`, PAX time records stripped and +`dev/*`), device or FIFO entries, refuses hardlinks whose targets were dropped, +expands GNU oldgnu (`S`) and PAX (`0.0`, `0.1`, `1.0`) sparse entries while +streaming (`image_tar::TarReport` records dropped counts/paths and expanded +sparse bytes), and normalizes directory modification times +to epoch 0 (`1970-01-01T00:00:00Z`, PAX time records stripped and header checksum recomputed, so exports separated in time are byte-identical for resume) in 1 MiB `image.artifact` frames to `.recv-.part`; the machine checks its size and sha256, unpacks it -once into `.2/`, writes the sidecar and deletes the staged tar. A staged +once into `.2/`, strips the newly claimed `refs` from other cached +sidecars so moved tags cannot select stale images, writes the sidecar (keeping +`variant` and `config` recorded-only), and deletes the staged tar. +`.2.json` is the publication commit point (Option B interrupted-publish +recovery): a read-only `probe` treats an un-sidecared `.2/` outside a +sealed archive as `present: false, stranded: true` instead of backfilling +incomplete `refs`/`config`/`variant` without a lock, while `publish` removes +any non-in-use stranded `.2/` under `ImageLock` before re-unpacking, and +`probe` refuses ambiguous `ref` lookups matching multiple cached images. A staged tar left by a copy that is not running is resumed when its bytes hash as this export's prefix, else restarted; `size` is the bytes sent, else the sidecar's, else the layers' unpacked size, and the export container's `SizeRootFs` only @@ -257,12 +275,17 @@ CLI layerfs machine prune [] [--unused] ``` An image is in use while a Sandbox directory's `config/helper.spec` -`lower=` names it, or while a create holds its lock between its unpack and -its spec: a named one is refused `InUse` (`detail.count`), `unused` skips -it. Naming the default removes it; the next create unpacks it again from +`lower=` names it, while a create holds `.2.lock`, or while a live process +holds `ImageLock` (`/run/image-lock//.lock`): a named one +is refused `InUse` (`detail.count`), and `unused` leaves its artifacts +untouched. Otherwise `prune` removes unpacked directories (including stranded +`.2` without `.2.json`), dangling `.2.json` sidecars, unheld +`.recv-.part` staged files, and temporary `.tmp-.2-*` unpack +directories (`unused` keeps valid unpacked copies of the machine's default). +Naming the default removes it; the next create unpacks it again from its archive. `freed` is the free bytes after minus before. Errors: `InvalidInput` (neither an image nor `unused`, or not an id), `NotFound` -(not unpacked here), `InUse`, `Unsupported` `{reason: "host"}`. +(no matching artifact here), `InUse`, `Unsupported` `{reason: "host"}`. ### machine.status diff --git a/docs/versioned/2.0.0/calls.md b/docs/versioned/2.0.0/calls.md index 2229f4d1e..fb62054cb 100644 --- a/docs/versioned/2.0.0/calls.md +++ b/docs/versioned/2.0.0/calls.md @@ -467,9 +467,9 @@ form. | `list` | — | — | every machine, with what it supports (`supports`: `sqlite`, `postgresql_sandbox`, `reason`, and `log`, whether it has a worker whose log can be read; never on `native`) | | `platforms` | — | — | the platforms this host and build support: backend, kernel route, where Store calls run, whether a PostgreSQL Sandbox runs and why not, readiness and options (#535; the rows of `control/SUPPORT.json`) | | `get` | `name` | — | a machine's record | -| `images` | `name` | — | the Sandbox images the machine holds (`images`: `id`, `refs`, `size`, `architecture`, `source` `bundle`/`machine`/`imported`, `sandboxes`, `last_used`), its `default`, `free` bytes and `architecture`; and the host's tagged Docker images it could copy (`docker`, `available`: `id`, `refs`, `size`, `os`, `architecture`, `usable`, `reason`, `need`, `fits`). macOS `native` answers `mode: "host"` with none. Never starts a machine | -| `load` | `name`, `image` | `on_progress` | copies an image to the machine as `sandbox create --image` does, without a Sandbox: `{id, refs, size, reused}` | -| `prune` | `name`, `image`? | `unused` | removes one unpacked image, or with `unused` every one no Sandbox uses but the machine's default: `{removed, freed}` (`freed` measured on the filesystem); an image in use is `InUse` | +| `images` | `name` | — | the Sandbox images and staged parts the machine holds (`images`: `id`, `refs`, `size`, `architecture`, `source` `bundle`/`machine`/`imported`/`staged`/`stranded`, `variant`, `config`, `sandboxes`, `last_used`, `staged`, and for parts `age`, `resumable`), its `default`, `free` bytes and `architecture`; and the host's tagged Docker images it could copy (`docker`, `available`: `id`, `refs`, `size`, `os`, `architecture`, `usable`, `reason`, `need`, `fits`). macOS `native` answers `mode: "host"` with none. Never starts a machine | +| `load` | `name`, `image` | `on_progress` | copies an image to the machine as `sandbox create --image` does, without a Sandbox: `{id, refs, size, reused}`; removes stranded `.2` without `.2.json` on publish, strips moved `refs` from older sidecars, records `variant`/`config` without applying, drops FIFOs/devices/init files, expands sparse entries, and refuses hardlinks to dropped targets or ambiguous refs | +| `prune` | `name`, `image`? | `unused` | removes one image's artifacts or with `unused` every unheld unpacked image, stranded unpack, dangling sidecar, staged `.part` and `.tmp-*` dir except the machine's default: `{removed, freed}` (`freed` measured on the filesystem); live `ImageLock` or `InUse` entries are skipped on `unused` and refused `InUse` by name | | `status` | `name` | — | a machine's live state, free disk and tool version; `op` while a create or remove holds it (#536 H6) | | `stats` | `machine` | — | what a machine has and uses now: processors, memory and data disk, each sqlite Store's size, how many of its Sandboxes have a running daemon (#164). For a UI that polls: it writes no call-log line | | `space` | `machine` | — | where a machine's data disk goes: each Store, each Sandbox's run folder, the image cache and LayerFS's logs, and what the disk uses that is not LayerFS's. For a UI: it writes no call-log line | From 6804a04c40b0fe74d0ed740d099150505df6f808 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 17 Nov 2026 13:36:13 +0000 Subject: [PATCH 5/8] sandbox: harden prune locks, corrupt sidecar skip, sparse caps, and docs (#176 I03 R1) - M1: add ImageLock::try_hold (flock without owner record), isolate per-hex lock probe/guard errors in images::prune/pruning, record skipped reasons, and fail only on targeted bad locks. - N2: skip corrupt unrelated sidecars in image_artifact::strip_moved_refs instead of aborting publish. - N5: enforce image_tar::SPARSE_MAX on sparse realsize and cumulative expanded bytes, and count streamed expanded bytes against image_load::capacity. - N6 & sparse validation: cap oldgnu and PAX 0.x chunk counts by entry size while streaming, require payload_needed == size, and reject malformed PAX records after GNU.sparse.* keys with InvalidData. - Docs & named(): hint machine.prune on ambiguous ref errors and document N1/N3/N4 known limitations in docs/architecture/api/sdk/machine.md (and skipped in calls.md). Production LOC (tools/production_loc.py --detail): - combined: 171,077 -> 171,232 (+155) - core: 39,795 -> 39,795 (0) - engine: 75,102 -> 75,102 (0) - control: 49,834 -> 49,989 (+155; layerfs-sandbox: 14,281 -> 14,436, +155) - api: 6,346 -> 6,346 (0) - reference: absent (0) --- .../layerfs-sandbox/src/image_artifact.rs | 4 +- .../crates/layerfs-sandbox/src/image_load.rs | 75 +-- .../crates/layerfs-sandbox/src/image_tar.rs | 137 ++++-- control/crates/layerfs-sandbox/src/images.rs | 116 ++++- .../tests/lp176_image_recovery.rs | 437 +++++++++++++++++- docs/architecture/api/sdk/machine.md | 33 +- docs/versioned/2.0.0/calls.md | 2 +- 7 files changed, 712 insertions(+), 92 deletions(-) diff --git a/control/crates/layerfs-sandbox/src/image_artifact.rs b/control/crates/layerfs-sandbox/src/image_artifact.rs index 4cc7c65db..819f1b813 100644 --- a/control/crates/layerfs-sandbox/src/image_artifact.rs +++ b/control/crates/layerfs-sandbox/src/image_artifact.rs @@ -454,7 +454,7 @@ fn named(cache: &Path, reference: &str) -> Result, SdkRefusal> { _ => Err(refused_with( "InvalidInput", format!( - "image reference `{reference}` is ambiguous across cached images: {}", + "image reference `{reference}` is ambiguous across cached images: {}; remove one with `machine.prune`", matches.join(", ") ), SdkValue::map([ @@ -645,7 +645,7 @@ fn strip_moved_refs( if !hex(other_hex) || other_hex == published_hex { continue; } - let Some(mut other) = SidecarInfo::read(cache, other_hex)? else { + let Ok(Some(mut other)) = SidecarInfo::read(cache, other_hex) else { continue; }; let before = other.sidecar.refs.len(); diff --git a/control/crates/layerfs-sandbox/src/image_load.rs b/control/crates/layerfs-sandbox/src/image_load.rs index b8191ff2d..7dae98893 100644 --- a/control/crates/layerfs-sandbox/src/image_load.rs +++ b/control/crates/layerfs-sandbox/src/image_load.rs @@ -256,7 +256,8 @@ pub fn load( // capacity before the first effect on the machine (#175 R03): no export // container, no staged byte and no cache folder; a resumed copy counts // the bytes it already staged once - capacity(&machine, &probe, id, inspected.size)?; + let staged = probe.get_int("offset").unwrap_or(0).max(0) as u64; + capacity(&machine, &probe, id, inspected.size, staged)?; let home_id = ensure_home_id(target.home())?; phase(events, "export", None); let container = ExportContainer::create(docker, &home_id, &machine, id)?; @@ -278,14 +279,13 @@ pub fn load( // the container's root refines the progress estimate only: the capacity // decision above is taken before anything is created let estimate = Some(unpacked.unwrap_or(0).max(inspected.size)).filter(|n| *n > 0); - let staged = probe.get_int("offset").unwrap_or(0).max(0) as u64; let prefix = probe.get_text("prefix_sha256").map(str::to_owned); let (sent, sha256) = match send( docker, events, target, - container.name(), - id, + (&probe, inspected.size), + (container.name(), id), (staged, prefix), estimate, )? { @@ -295,8 +295,8 @@ pub fn load( docker, events, target, - container.name(), - id, + (&probe, inspected.size), + (container.name(), id), (0, None), estimate, )? @@ -350,14 +350,16 @@ fn reused(id: &str, refs: Vec, size: Option) -> Loaded { /// copy replaces; a wait a shared Cancel can end is X01's, not this card's. pub struct ImageLock { file: File, - record: PathBuf, + record: Option, } impl Drop for ImageLock { fn drop(&mut self) { // the copy is over; a copy that died left its record behind for the // next owner to replace - let _ = std::fs::remove_file(&self.record); + if let Some(record) = &self.record { + let _ = std::fs::remove_file(record); + } layerfs_home::home::flock::unlock(&self.file); } } @@ -392,20 +394,30 @@ impl ImageLock { .map_err(failed) } - /// Takes the lock of image `id` on `machine` without waiting; returns - /// `Ok(None)` when another live copy currently holds it. - pub fn try_take(home: &Path, machine: &str, id: &str) -> Result> { + /// Opens `.lock` and tries an exclusive `flock` without waiting. + fn try_lock_file(home: &Path, machine: &str, id: &str) -> Result> { let hex = hex_of(id).ok_or_else(|| refused("InvalidInput", "image id"))?; let file = Self::open_file(home, machine, hex)?; if !layerfs_home::home::flock::try_lock(&file, true).map_err(failed)? { return Ok(None); } - let lock = Self { - file, - record: Self::record_path(home, machine, hex), + Ok(Some((file, hex.to_owned()))) + } + + /// Takes the lock of image `id` on `machine` without waiting or writing an + /// owner record (`machine.prune` guard); returns `Ok(None)` when another + /// live owner currently holds it. + pub fn try_hold(home: &Path, machine: &str, id: &str) -> Result> { + Ok(Self::try_lock_file(home, machine, id)?.map(|(file, _)| Self { file, record: None })) + } + + /// Takes the lock of image `id` on `machine` without waiting; returns + /// `Ok(None)` when another live copy currently holds it. + pub fn try_take(home: &Path, machine: &str, id: &str) -> Result> { + let Some((file, hex)) = Self::try_lock_file(home, machine, id)? else { + return Ok(None); }; - lock.record(machine, id)?; - Ok(Some(lock)) + Self::with_record(file, home, machine, &hex, id).map(Some) } /// Takes the lock of image `id` on `machine`, waiting while a live copy @@ -436,16 +448,12 @@ impl ImageLock { } std::thread::sleep(LOCK_POLL); } - let lock = Self { - file, - record: Self::record_path(home, machine, hex), - }; - lock.record(machine, id)?; - Ok(lock) + Self::with_record(file, home, machine, hex, id) } - /// Records this copy as the lock's owner before it does anything else. - fn record(&self, machine: &str, id: &str) -> Result<()> { + /// Wraps `file` with its owner record path and writes the owner record. + fn with_record(file: File, home: &Path, machine: &str, hex: &str, id: &str) -> Result { + let path = Self::record_path(home, machine, hex); let now = home::now_ms(); let mut fields = process::identity(); fields.extend([ @@ -460,7 +468,11 @@ impl ImageLock { .map(|(name, value)| (name.to_owned(), value)) .collect(), ); - write_record(&self.record, &record) + write_record(&path, &record)?; + Ok(Self { + file, + record: Some(path), + }) } } @@ -649,12 +661,11 @@ fn hex_of(id: &str) -> Option<&str> { /// — the bytes already staged for a resumed copy are on the machine's /// filesystem and are counted once — `free` is what it has, and `where` names /// the filesystem that was measured. -fn capacity(machine: &str, probe: &SdkValue, id: &str, size: u64) -> Result<()> { +fn capacity(machine: &str, probe: &SdkValue, id: &str, size: u64, staged: u64) -> Result<()> { // a machine that does not say how much room it has cannot be refused let Some(free) = probe.get_int("free").map(|n| n.max(0) as u64) else { return Ok(()); }; - let staged = probe.get_int("offset").unwrap_or(0).max(0) as u64; let needed = docker::need(size).saturating_sub(staged); if needed <= free { return Ok(()); @@ -842,8 +853,8 @@ fn send( docker: &Docker, events: &mut Events<'_>, target: &mut Target<'_>, - container: &str, - id: &str, + (probe, checked): (&SdkValue, u64), + (container, id): (&str, &str), (staged, prefix): (u64, Option), total: Option, ) -> Result> { @@ -892,6 +903,10 @@ fn send( if n == 0 { break; } + let next = offset + n as u64; + if next > checked { + capacity(target.machine(), probe, id, next, staged)?; + } whole.update(&buffer[..n]); target.step(SdkValue::map([ ("step", SdkValue::text("write")), @@ -899,7 +914,7 @@ fn send( ("offset", SdkValue::Int(offset as i64)), ("bytes", SdkValue::Bytes(buffer[..n].to_vec())), ]))?; - offset += n as u64; + offset = next; if last.elapsed() >= Duration::from_millis(200) { phase(events, "send", shown(offset)); last = Instant::now(); diff --git a/control/crates/layerfs-sandbox/src/image_tar.rs b/control/crates/layerfs-sandbox/src/image_tar.rs index fb8b76308..ef21a1dcf 100644 --- a/control/crates/layerfs-sandbox/src/image_tar.rs +++ b/control/crates/layerfs-sandbox/src/image_tar.rs @@ -14,6 +14,36 @@ use std::io::{self, Read}; const BLOCK: usize = 512; /// The largest pax or GNU extended header kept while its entry is decided. const EXTENDED_MAX: u64 = 1 << 20; +/// Maximum logical expanded size (`realsize` and cumulative sparse output) permitted. +pub const SPARSE_MAX: u64 = 16 << 30; +/// Hard cap on parsed sparse chunk descriptors across extended headers. +const SPARSE_CHUNKS_MAX: usize = 1 << 20; + +fn invalid(msg: &str) -> io::Error { + io::Error::new(io::ErrorKind::InvalidData, msg) +} + +fn push_gnu_slot( + chunks: &mut Vec<(u64, u64)>, + stored: &mut u64, + slot: &[u8], + entry_size: u64, +) -> io::Result { + let off = octal(&slot[..12])?; + let len = octal(&slot[12..24])?; + if len == 0 { + return Ok(false); + } + if (chunks.len() as u64) >= entry_size + || chunks.len() >= SPARSE_CHUNKS_MAX + || stored.checked_add(len).is_none_or(|s| s > entry_size) + { + return Err(invalid("GNU sparse chunks exceed tar entry size")); + } + *stored += len; + chunks.push((off, len)); + Ok(true) +} /// Paths the init layer of `docker create` adds or replaces. const INIT_FILES: [&str; 5] = [ @@ -105,6 +135,7 @@ pub struct Filtered { /// Bytes of the current kept entry's data (with padding) still to copy. copying: u64, sparse: Option, + sparse_max: u64, dropped_paths: HashSet, report: TarReport, done: bool, @@ -119,12 +150,19 @@ impl Filtered { at: 0, copying: 0, sparse: None, + sparse_max: SPARSE_MAX, dropped_paths: HashSet::new(), report: TarReport::default(), done: false, } } + /// Sets the maximum expanded sparse byte budget (per entry and cumulative). + pub fn with_sparse_max(mut self, max: u64) -> Self { + self.sparse_max = max; + self + } + /// Report of entries dropped or sparse files expanded so far. pub fn report(&self) -> &TarReport { &self.report @@ -167,15 +205,21 @@ impl Filtered { } /// Reads GNU oldgnu extended sparse header blocks that follow a `b'S'` header. - fn read_gnu_sparse_map(&mut self, header: &[u8; BLOCK]) -> io::Result> { + fn read_gnu_sparse_map( + &mut self, + header: &[u8; BLOCK], + entry_size: u64, + ) -> io::Result> { let mut chunks = Vec::new(); + let mut stored = 0u64; for i in 0..4 { let base = 386 + i * 24; - let off = octal(&header[base..base + 12])?; - let len = octal(&header[base + 12..base + 24])?; - if len > 0 { - chunks.push((off, len)); - } + push_gnu_slot( + &mut chunks, + &mut stored, + &header[base..base + 24], + entry_size, + )?; } let mut extended = header[482] != 0; while extended { @@ -183,15 +227,17 @@ impl Filtered { if !self.block(&mut ext)? { return Err(io::ErrorKind::UnexpectedEof.into()); } + let mut added = false; for slot in 0..21 { let base = slot * 24; - let off = octal(&ext[base..base + 12])?; - let len = octal(&ext[base + 12..base + 24])?; - if len > 0 { - chunks.push((off, len)); + if push_gnu_slot(&mut chunks, &mut stored, &ext[base..base + 24], entry_size)? { + added = true; } } extended = ext[504] != 0; + if !added && extended { + return Err(invalid("empty GNU sparse extended block")); + } } Ok(chunks) } @@ -321,8 +367,10 @@ impl Filtered { pending.push((header, data)); continue; } + let size = pax.pax_size.unwrap_or(size); + let padded = size.div_ceil(BLOCK as u64) * BLOCK as u64; let gnu_chunks = if flag == b'S' { - Some(self.read_gnu_sparse_map(&header)?) + Some(self.read_gnu_sparse_map(&header, size)?) } else { None }; @@ -370,30 +418,35 @@ impl Filtered { let realsize = if flag == b'S' { pax.sparse_realsize.unwrap_or(octal(&header[483..495])?) } else { - pax.sparse_realsize.ok_or_else(|| { - io::Error::new( - io::ErrorKind::InvalidData, - "PAX sparse file missing realsize", - ) - })? + pax.sparse_realsize + .ok_or_else(|| invalid("PAX sparse file missing realsize"))? }; + if realsize > self.sparse_max + || self + .report + .sparse_expanded_bytes + .checked_add(realsize) + .is_none_or(|total| total > self.sparse_max) + { + return Err(invalid("sparse entry realsize exceeds maximum")); + } let (raw_chunks, map_bytes) = if pax.sparse_major == Some(1) && pax.sparse_minor == Some(0) { self.read_pax1_sparse_map(size)? } else if let Some(chunks) = gnu_chunks { (chunks, 0) } else { + if (pax.sparse_chunks.len() as u64) > size { + return Err(invalid("PAX sparse chunk count exceeds tar entry size")); + } (pax.sparse_chunks, 0) }; let (chunks, stored_bytes) = validate_sparse_chunks(raw_chunks, realsize)?; - let payload_needed = map_bytes.checked_add(stored_bytes).ok_or_else(|| { - io::Error::new(io::ErrorKind::InvalidData, "sparse payload overflow") - })?; - if payload_needed > size { - return Err(io::Error::new( - io::ErrorKind::InvalidData, - "sparse chunks exceed tar entry size", - )); + let payload_needed = map_bytes + .checked_add(stored_bytes) + .ok_or_else(|| invalid("sparse payload overflow"))?; + if payload_needed != size { + return Err(invalid("sparse payload size does not match tar entry size")); } let input_skip = padded - payload_needed; let override_path = sparse_name.as_deref(); @@ -568,6 +621,7 @@ impl Read for Filtered { struct PaxMeta { path: Option, linkpath: Option, + pax_size: Option, has_sparse: bool, sparse_major: Option, sparse_minor: Option, @@ -605,9 +659,25 @@ fn walk_pax_records( } impl PaxMeta { + fn push_chunk(&mut self, off: u64, len: u64) -> io::Result<()> { + if len > 0 { + let cap = self + .pax_size + .unwrap_or(u64::MAX) + .min(SPARSE_CHUNKS_MAX as u64); + if (self.sparse_chunks.len() as u64) >= cap { + return Err(invalid( + "PAX sparse chunk count exceeds entry size or limit", + )); + } + self.sparse_chunks.push((off, len)); + } + Ok(()) + } + fn parse_into(&mut self, body: &[u8]) -> io::Result<()> { let mut pending_offset: Option = None; - let _ = walk_pax_records(body, |_, key, val| { + let complete = walk_pax_records(body, |_, key, val| { let val_str = String::from_utf8_lossy(val); let parse_u64 = |label: &str| { val_str.trim().parse::().map_err(|_| { @@ -617,6 +687,7 @@ impl PaxMeta { match key { b"path" => self.path = Some(val_str.into_owned()), b"linkpath" => self.linkpath = Some(val_str.into_owned()), + b"size" => self.pax_size = Some(parse_u64("size")?), b"GNU.sparse.major" => { self.has_sparse = true; self.sparse_major = Some(parse_u64("GNU.sparse.major")?); @@ -646,9 +717,7 @@ impl PaxMeta { ) })?; let len = parse_u64("GNU.sparse.numbytes")?; - if len > 0 { - self.sparse_chunks.push((off, len)); - } + self.push_chunk(off, len)?; } b"GNU.sparse.map" => { self.has_sparse = true; @@ -666,9 +735,7 @@ impl PaxMeta { let len: u64 = l_str.trim().parse().map_err(|_| { io::Error::new(io::ErrorKind::InvalidData, "invalid sparse map len") })?; - if len > 0 { - self.sparse_chunks.push((off, len)); - } + self.push_chunk(off, len)?; } } _ => { @@ -679,6 +746,12 @@ impl PaxMeta { } Ok(()) })?; + if !complete && self.has_sparse { + return Err(invalid("malformed PAX record after GNU.sparse.* key")); + } + if pending_offset.is_some() { + return Err(invalid("GNU.sparse.offset without numbytes")); + } Ok(()) } } diff --git a/control/crates/layerfs-sandbox/src/images.rs b/control/crates/layerfs-sandbox/src/images.rs index 58a1b3758..00187359a 100644 --- a/control/crates/layerfs-sandbox/src/images.rs +++ b/control/crates/layerfs-sandbox/src/images.rs @@ -321,8 +321,11 @@ pub fn prune(home: &Path, name: &MachineName, image: Option<&str>, unused: bool) if host_mode(&executor) { return Err(host_only(machine)); } - let locked = locked_image_ids(&ImageLock::dir(home, machine))?; + let (locked, lock_errors) = scan_image_locks(&ImageLock::dir(home, machine))?; let _target_lock = if let Some(target) = image { + if let Some(reason) = lock_errors.get(target) { + return Err(refused("Failed", reason.clone())); + } if locked.contains(target) { return Err(refused_with( "InUse", @@ -330,7 +333,7 @@ pub fn prune(home: &Path, name: &MachineName, image: Option<&str>, unused: bool) SdkValue::map([("count", SdkValue::Int(1))]), )); } - Some(ImageLock::try_take(home, machine, target)?.ok_or_else(|| { + Some(ImageLock::try_hold(home, machine, target)?.ok_or_else(|| { refused_with( "InUse", format!("image {target} has an active copy lock on this machine"), @@ -348,6 +351,23 @@ pub fn prune(home: &Path, name: &MachineName, image: Option<&str>, unused: bool) "locked", SdkValue::List(locked.into_iter().map(SdkValue::Text).collect()), ); + if !lock_errors.is_empty() { + args = home::with_field( + args, + "lock_errors", + SdkValue::List( + lock_errors + .into_iter() + .map(|(id, reason)| { + SdkValue::map([ + ("id", SdkValue::text(id)), + ("reason", SdkValue::text(reason)), + ]) + }) + .collect(), + ), + ); + } if image.is_some() { args = home::with_field(args, "target_guarded", SdkValue::Bool(true)); } @@ -388,12 +408,30 @@ fn pruning(side: &Side<'_>, args: &SdkValue) -> Outcome { let unused = args.get_bool("unused"); let target_guarded = args.get_bool("target_guarded"); let mut locked: BTreeSet = cache::texts(args.get("locked")).into_iter().collect(); + let mut lock_errors: BTreeMap = match args.get("lock_errors") { + Some(SdkValue::List(items)) => items + .iter() + .filter_map(|item| { + Some(( + item.get_text("id")?.to_owned(), + item.get_text("reason")?.to_owned(), + )) + }) + .collect(), + _ => BTreeMap::new(), + }; if !machine.is_empty() { - for id in locked_image_ids(&ImageLock::dir(root, machine))? { + let (local_locked, local_errors) = scan_image_locks(&ImageLock::dir(root, machine))?; + for id in local_locked { if !(target_guarded && target == Some(id.as_str())) { locked.insert(id); } } + for (id, reason) in local_errors { + if !(target_guarded && target == Some(id.as_str())) { + lock_errors.insert(id, reason); + } + } } let default = match &choice.image { Some(image) => Some(image.clone()), @@ -414,12 +452,35 @@ fn pruning(side: &Side<'_>, args: &SdkValue) -> Outcome { } let lowers = lowers(dir.parent().unwrap_or(&dir))?; let mut removed = Vec::new(); + let mut skipped = Vec::new(); for (hex, item) in entries { let id = format!("sha256:{hex}"); + if let Some(reason) = lock_errors.get(&id) { + if target.is_some() { + return Err(refused("Failed", reason.clone())); + } + skipped.push(SdkValue::map([ + ("id", SdkValue::text(&id)), + ("reason", SdkValue::text(reason)), + ])); + continue; + } let held = [dir.join(format!("{hex}.2")), dir.join(&hex)]; let lower_users = lowers.iter().filter(|l| held.contains(l)).count(); let img_locked = locked.contains(&id); - let hold_locked = is_flock_held(&dir.join(format!("{hex}.2.lock")))?; + let hold_locked = match is_flock_held(&dir.join(format!("{hex}.2.lock"))) { + Ok(held) => held, + Err(err) => { + if target.is_some() { + return Err(err); + } + skipped.push(SdkValue::map([ + ("id", SdkValue::text(&id)), + ("reason", SdkValue::text(err.message)), + ])); + continue; + } + }; if img_locked || lower_users > 0 || hold_locked { if target.is_some() { let count = lower_users.max(1); @@ -439,9 +500,16 @@ fn pruning(side: &Side<'_>, args: &SdkValue) -> Outcome { && !machine.is_empty() && ImageLock::dir(root, machine).is_dir() { - match ImageLock::try_take(root, machine, &id)? { - Some(guard) => Some(guard), - None => continue, + match ImageLock::try_hold(root, machine, &id) { + Ok(Some(guard)) => Some(guard), + Ok(None) => continue, + Err(err) => { + skipped.push(SdkValue::map([ + ("id", SdkValue::text(&id)), + ("reason", SdkValue::text(err.message)), + ])); + continue; + } } } else { None @@ -509,10 +577,14 @@ fn pruning(side: &Side<'_>, args: &SdkValue) -> Outcome { (Some(before), Some(after)) => after.saturating_sub(before) as i64, _ => 0, }; - Ok(SdkValue::map([ - ("removed", SdkValue::List(removed)), - ("freed", SdkValue::Int(freed)), - ])) + let mut out = vec![ + ("removed".to_owned(), SdkValue::List(removed)), + ("freed".to_owned(), SdkValue::Int(freed)), + ]; + if !skipped.is_empty() { + out.push(("skipped".to_owned(), SdkValue::List(skipped))); + } + Ok(SdkValue::Map(out)) } /// Scans `dir` for unpacked images, sidecars, staged `.part` files, and temporary @@ -589,13 +661,14 @@ fn is_flock_held(path: &Path) -> Result { } } -/// Every `sha256:` image digest whose `ImageLock` file in `lock_dir` is -/// held by a live process or open file description. -fn locked_image_ids(lock_dir: &Path) -> Result> { +/// Scans `lock_dir` for `ImageLock` files held by live processes and per-image +/// lock probe errors (e.g. a symlink or unreadable `.lock` file). +fn scan_image_locks(lock_dir: &Path) -> Result<(BTreeSet, BTreeMap)> { let mut locked = BTreeSet::new(); + let mut errors = BTreeMap::new(); let entries = match std::fs::read_dir(lock_dir) { Ok(entries) => entries, - Err(e) if e.kind() == ErrorKind::NotFound => return Ok(locked), + Err(e) if e.kind() == ErrorKind::NotFound => return Ok((locked, errors)), Err(e) => return Err(failed(e)), }; for entry in entries { @@ -605,11 +678,18 @@ fn locked_image_ids(lock_dir: &Path) -> Result> { let Some(hex) = name.strip_suffix(".lock").filter(|h| cache::is_hex(h)) else { continue; }; - if is_flock_held(&entry.path())? { - locked.insert(format!("sha256:{hex}")); + let id = format!("sha256:{hex}"); + match is_flock_held(&entry.path()) { + Ok(true) => { + locked.insert(id); + } + Ok(false) => {} + Err(err) => { + errors.insert(id, err.message); + } } } - Ok(locked) + Ok((locked, errors)) } /// The image directories the Sandboxes under runtime root `run` are built on: diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs index a9ec6c878..92df70f9d 100644 --- a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs +++ b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs @@ -8,14 +8,16 @@ mod fixture; use fixture::{pax_record, Scratch, Tar}; use layerfs_bridge::control::SdkValue; use layerfs_home::events::Events; -use layerfs_home::home; +use layerfs_home::home::{self, paths, write_record}; use layerfs_home::names::MachineName; +use layerfs_machine::worker::{read_frame, read_frame_within, write_frame, MAX_HELLO, PROTOCOL}; use layerfs_sandbox::docker::Docker; use layerfs_sandbox::image_artifact::{self as cache, architecture, Sidecar, CHUNK}; use layerfs_sandbox::image_load::{load, ImageLock, Loaded, Target}; -use layerfs_sandbox::image_tar::{Filtered, TarReport}; +use layerfs_sandbox::image_tar::{Filtered, TarReport, SPARSE_MAX}; use layerfs_sandbox::images; use layerfs_sandbox_backend::{rootfs, Image}; +use layerfs_store::place::{self, Executor}; use sha2::{Digest, Sha256}; use std::collections::BTreeSet; use std::fs; @@ -841,8 +843,8 @@ fn ambiguous_ref_is_refused_and_moved_ref_never_selects_old_image() { .unwrap_err(); assert_eq!(err.code, "InvalidInput", "{err:?}"); assert!( - err.message.contains("shared/app:latest"), - "ambiguous ref error must name the ref: {}", + err.message.contains("shared/app:latest") && err.message.contains("machine.prune"), + "ambiguous ref error must name the ref and suggest machine.prune: {}", err.message ); @@ -1338,6 +1340,433 @@ fn real_docker_and_small_tar_preserve_mtime_mode_sha_and_record_config() { } } +struct ModeGuard(PathBuf, u32); +impl Drop for ModeGuard { + fn drop(&mut self) { + let _ = fs::set_permissions(&self.0, fs::Permissions::from_mode(self.1)); + } +} + +#[test] +fn prune_skips_unwritable_lock_dir_and_bad_lock_symlinks_while_reclaiming_others() { + use std::os::unix::fs::symlink; + + // 1. Unwritable lock dir (simulates ENOSPC / EACCES for record/file creation): + // pre-existing `.lock` is still guarded via try_hold (no .json written) and reclaimed, + // while a hex needing a new `.lock` is skipped with a reason rather than aborting prune. + let scratch1 = Scratch::new("lp176-r1-lock-ro"); + let home1 = scratch1.base.join("home"); + fs::create_dir_all(&home1).unwrap(); + home::ensure(&home1).unwrap(); + let cache1 = cache::cache(&home1); + fs::create_dir_all(&cache1).unwrap(); + + let hex_existing = "1".repeat(64); + let id_existing = format!("sha256:{hex_existing}"); + let hex_new = "2".repeat(64); + let id_new = format!("sha256:{hex_new}"); + + cache::write(&cache1, &hex_existing, 0, b"part-existing").unwrap(); + cache::write(&cache1, &hex_new, 0, b"part-new").unwrap(); + drop( + ImageLock::try_take(&home1, "native", &id_existing) + .unwrap() + .unwrap(), + ); + assert!(ImageLock::path(&home1, "native", &hex_existing).is_file()); + + let lock_dir1 = ImageLock::dir(&home1, "native"); + let _mode_guard = ModeGuard(lock_dir1.clone(), 0o700); + fs::set_permissions(&lock_dir1, fs::Permissions::from_mode(0o555)).unwrap(); + + let out1 = images::prune(&home1, &native_name(), None, true).unwrap(); + let removed1 = cache::texts(out1.get("removed")); + assert_eq!(removed1, vec![id_existing.clone()], "{out1:?}"); + assert!(!cache1.join(format!(".recv-{hex_existing}.part")).exists()); + assert!(cache1.join(format!(".recv-{hex_new}.part")).exists()); + let skipped1 = match out1.get("skipped") { + Some(SdkValue::List(items)) => items.clone(), + other => panic!("expected skipped entry for unwritable lock dir: {other:?}"), + }; + assert!( + skipped1.iter().any(|s| s.get_text("id") == Some(&id_new) + && s.get_text("reason").is_some_and(|r| !r.is_empty())), + "expected skip reason for {id_new}: {skipped1:?}" + ); + drop(_mode_guard); + + // 2. Bad `.lock` symlinks (in ImageLock dir and in cache `.2.lock`) must not abort + // `prune --unused` or targeted prune of unrelated hexes, while targeted prune on the + // bad-lock hex returns an error. + let scratch2 = Scratch::new("lp176-r1-lock-symlink"); + let home2 = scratch2.base.join("home"); + fs::create_dir_all(&home2).unwrap(); + home::ensure(&home2).unwrap(); + let cache2 = cache::cache(&home2); + fs::create_dir_all(&cache2).unwrap(); + let lock_dir2 = ImageLock::dir(&home2, "native"); + fs::create_dir_all(&lock_dir2).unwrap(); + + let hex_good_unused = "3".repeat(64); + let id_good_unused = format!("sha256:{hex_good_unused}"); + let hex_good_target = "4".repeat(64); + let id_good_target = format!("sha256:{hex_good_target}"); + let hex_bad_lock = "5".repeat(64); + let id_bad_lock = format!("sha256:{hex_bad_lock}"); + let hex_bad_hold = "6".repeat(64); + let id_bad_hold = format!("sha256:{hex_bad_hold}"); + + cache::write(&cache2, &hex_good_unused, 0, b"good-unused").unwrap(); + cache::write(&cache2, &hex_good_target, 0, b"good-target").unwrap(); + cache::write(&cache2, &hex_bad_lock, 0, b"bad-lock").unwrap(); + cache::write(&cache2, &hex_bad_hold, 0, b"bad-hold").unwrap(); + + let dummy_target = scratch2.base.join("dummy"); + fs::write(&dummy_target, b"x").unwrap(); + symlink( + &dummy_target, + ImageLock::path(&home2, "native", &hex_bad_lock), + ) + .unwrap(); + symlink(&dummy_target, cache2.join(format!("{hex_bad_hold}.2.lock"))).unwrap(); + + // Targeted prune of an unrelated healthy hex succeeds despite bad sibling locks. + let targeted = images::prune(&home2, &native_name(), Some(&id_good_target), false).unwrap(); + assert_eq!( + cache::texts(targeted.get("removed")), + vec![id_good_target.clone()] + ); + assert!(!cache2 + .join(format!(".recv-{hex_good_target}.part")) + .exists()); + + // Targeted prune of the bad-lock hexes returns an error. + assert!(images::prune(&home2, &native_name(), Some(&id_bad_lock), false).is_err()); + assert!(images::prune(&home2, &native_name(), Some(&id_bad_hold), false).is_err()); + + // Unused prune reclaims healthy hex and records skip reasons for both bad-lock hexes. + let out2 = images::prune(&home2, &native_name(), None, true).unwrap(); + assert_eq!( + cache::texts(out2.get("removed")), + vec![id_good_unused.clone()], + "{out2:?}" + ); + assert!(!cache2 + .join(format!(".recv-{hex_good_unused}.part")) + .exists()); + assert!(cache2.join(format!(".recv-{hex_bad_lock}.part")).exists()); + assert!(cache2.join(format!(".recv-{hex_bad_hold}.part")).exists()); + let skipped2 = match out2.get("skipped") { + Some(SdkValue::List(items)) => items.clone(), + other => panic!("expected skipped entries for bad symlinks: {other:?}"), + }; + for bad_id in [&id_bad_lock, &id_bad_hold] { + assert!( + skipped2.iter().any(|s| s.get_text("id") == Some(bad_id) + && s.get_text("reason").is_some_and(|r| !r.is_empty())), + "missing skip reason for {bad_id}: {skipped2:?}" + ); + } +} + +#[test] +fn publish_skips_corrupt_unrelated_sidecar() { + let scratch = Scratch::new("lp176-r1-corrupt-sidecar"); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + let cache_dir = cache::cache(&home); + fs::create_dir_all(&cache_dir).unwrap(); + + let hex_bad = "7".repeat(64); + fs::create_dir_all(cache_dir.join(format!("{hex_bad}.2"))).unwrap(); + let bad_sidecar_path = cache::sidecar_path(&cache_dir, &hex_bad); + fs::write(&bad_sidecar_path, b"{not valid json").unwrap(); + + let hex_good = "8".repeat(64); + let id_good = format!("sha256:{hex_good}"); + let tar_bytes = filtered_bytes(&Tar::new().file("etc/ok", 0o644, b"ok\n").finish()).unwrap(); + let sha = sha256_hex(&tar_bytes); + cache::write(&cache_dir, &hex_good, 0, &tar_bytes).unwrap(); + + let out = step( + &home, + SdkValue::map([ + ("step", SdkValue::text("publish")), + ("id", SdkValue::text(&id_good)), + ("size", SdkValue::Int(tar_bytes.len() as i64)), + ("sha256", SdkValue::text(&sha)), + ( + "refs", + SdkValue::List(vec![SdkValue::text("r1/app:latest")]), + ), + ]), + ) + .unwrap(); + assert!(out.get_bool("unpacked")); + let good_sidecar = Sidecar::read(&cache_dir, &hex_good).unwrap().unwrap(); + assert_eq!(good_sidecar.refs, vec!["r1/app:latest".to_owned()]); + assert_eq!(fs::read(&bad_sidecar_path).unwrap(), b"{not valid json"); +} + +#[test] +fn sparse_safety_rejects_oversized_realsize_excess_chunks_size_mismatch_and_malformed_pax() { + let assert_invalid_data = |label: &str, tar_bytes: Vec| { + let err = filtered_bytes(&tar_bytes).expect_err(label); + assert_eq!( + err.kind(), + std::io::ErrorKind::InvalidData, + "{label}: got {err:?}" + ); + }; + + // 1. N5: realsize exceeding SPARSE_MAX (oldgnu and PAX 0.1). + let huge_gnu = build_gnu_sparse_tar("big.bin", 0o644, 0, SPARSE_MAX + 1, &[(0, b"A")]); + assert_invalid_data("oldgnu realsize > SPARSE_MAX", huge_gnu); + + let mut huge_pax = pax_record("GNU.sparse.major", "0"); + huge_pax.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + huge_pax.extend_from_slice(&pax_record("GNU.sparse.name", "big_pax.bin")); + huge_pax.extend_from_slice(&pax_record( + "GNU.sparse.realsize", + &(SPARSE_MAX + 1).to_string(), + )); + huge_pax.extend_from_slice(&pax_record("GNU.sparse.map", "0,1")); + let huge_pax_tar = Tar::new() + .raw("PaxHeaders/big", b'x', 0o644, &huge_pax) + .file("big_pax.bin", 0o644, b"A") + .finish(); + assert_invalid_data("PAX 0.1 realsize > SPARSE_MAX", huge_pax_tar); + + // 2. N6: oldgnu extended block chain exceeding entry `size` (aborts before EOF/extra blocks). + let mut gnu_hdr = [0u8; 512]; + gnu_hdr[..7].copy_from_slice(b"bad.bin"); + let oct = |f: &mut [u8], v: u64| { + let w = f.len() - 1; + let t = format!("{v:0w$o}\0"); + f.copy_from_slice(&t.as_bytes()[..f.len()]); + }; + oct(&mut gnu_hdr[100..108], 0o644); + oct(&mut gnu_hdr[124..136], 3); // entry size = 3 => at most 3 chunks + gnu_hdr[156] = b'S'; + gnu_hdr[257..263].copy_from_slice(b"ustar "); + gnu_hdr[263..265].copy_from_slice(b" \0"); + for i in 0..4 { + let base = 386 + i * 24; + oct(&mut gnu_hdr[base..base + 12], (i as u64) * 4096); + oct(&mut gnu_hdr[base + 12..base + 24], 1); // 4th chunk already exceeds size=3! + } + gnu_hdr[482] = 1; // claims an extended block follows (intentionally absent!) + oct(&mut gnu_hdr[483..495], 65_536); + gnu_hdr[148..156].fill(b' '); + let sum: u64 = gnu_hdr.iter().map(|b| u64::from(*b)).sum(); + gnu_hdr[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes()); + assert_invalid_data( + "oldgnu chunk count > size before extended block", + gnu_hdr.to_vec(), + ); + + // 3. N6: PAX 0.x GNU.sparse.map with chunk count > entry `size` (both PAX `size` and ustar `size`). + let mut pax_chunks_over_pax_size = pax_record("GNU.sparse.major", "0"); + pax_chunks_over_pax_size.extend_from_slice(&pax_record("size", "2")); + pax_chunks_over_pax_size.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + pax_chunks_over_pax_size.extend_from_slice(&pax_record("GNU.sparse.name", "m.bin")); + pax_chunks_over_pax_size.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); + pax_chunks_over_pax_size.extend_from_slice(&pax_record("GNU.sparse.map", "0,1,4096,1,8192,1")); + let tar_over_pax_size = Tar::new() + .raw("PaxHeaders/m", b'x', 0o644, &pax_chunks_over_pax_size) + .file("m.bin", 0o644, b"AB") + .finish(); + assert_invalid_data("PAX 0.1 chunk count > PAX size", tar_over_pax_size); + + let mut pax_chunks_over_hdr_size = pax_record("GNU.sparse.major", "0"); + pax_chunks_over_hdr_size.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + pax_chunks_over_hdr_size.extend_from_slice(&pax_record("GNU.sparse.name", "m2.bin")); + pax_chunks_over_hdr_size.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); + pax_chunks_over_hdr_size.extend_from_slice(&pax_record("GNU.sparse.map", "0,1,4096,1,8192,1")); + let tar_over_hdr_size = Tar::new() + .raw("PaxHeaders/m2", b'x', 0o644, &pax_chunks_over_hdr_size) + .file("m2.bin", 0o644, b"AB") + .finish(); + assert_invalid_data("PAX 0.1 chunk count > ustar size", tar_over_hdr_size); + + // 4. Item 5a: payload_needed != size (extra trailing bytes inside tar entry) for oldgnu, PAX 0.1, PAX 1.0. + let mut bad_size_gnu = build_gnu_sparse_tar("pad.bin", 0o644, 0, 8192, &[(0, b"ABCD")]); + oct(&mut bad_size_gnu[124..136], 100); // stored=4 != size=100 + bad_size_gnu[148..156].fill(b' '); + let sum2: u64 = bad_size_gnu[..512].iter().map(|b| u64::from(*b)).sum(); + bad_size_gnu[148..156].copy_from_slice(format!("{sum2:06o}\0 ").as_bytes()); + assert_invalid_data("oldgnu payload_needed != size", bad_size_gnu); + + let mut pax01_mismatch = pax_record("GNU.sparse.major", "0"); + pax01_mismatch.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + pax01_mismatch.extend_from_slice(&pax_record("GNU.sparse.name", "s01.bin")); + pax01_mismatch.extend_from_slice(&pax_record("GNU.sparse.realsize", "8192")); + pax01_mismatch.extend_from_slice(&pax_record("GNU.sparse.map", "0,4")); + let pax01_mismatch_tar = Tar::new() + .raw("PaxHeaders/s01", b'x', 0o644, &pax01_mismatch) + .file("s01.bin", 0o644, b"ABCDEXTRA") // stored=4 != size=9 + .finish(); + assert_invalid_data("PAX 0.1 payload_needed != size", pax01_mismatch_tar); + + let mut pax10_mismatch = pax_record("GNU.sparse.major", "1"); + pax10_mismatch.extend_from_slice(&pax_record("GNU.sparse.minor", "0")); + pax10_mismatch.extend_from_slice(&pax_record("GNU.sparse.name", "s10.bin")); + pax10_mismatch.extend_from_slice(&pax_record("GNU.sparse.realsize", "8192")); + let mut pax10_payload = b"1\n0\n4\n".to_vec(); + pax10_payload.resize(512, 0); // 1-block sparse map + pax10_payload.extend_from_slice(b"ABCDEXTRA"); // 512 + 4 != 512 + 9 + let pax10_mismatch_tar = Tar::new() + .raw("PaxHeaders/s10", b'x', 0o644, &pax10_mismatch) + .file("s10.bin", 0o644, &pax10_payload) + .finish(); + assert_invalid_data("PAX 1.0 payload_needed != size", pax10_mismatch_tar); + + // 5. Item 5b: malformed PAX record after GNU.sparse.* key must return InvalidData. + let mut malformed_after_sparse = pax_record("GNU.sparse.major", "0"); + malformed_after_sparse.extend_from_slice(b"999 bad=record\n"); + let malformed_pax_tar = Tar::new() + .raw("PaxHeaders/bad", b'x', 0o644, &malformed_after_sparse) + .file("plain.bin", 0o644, b"RAW") + .finish(); + assert_invalid_data("malformed PAX after GNU.sparse.*", malformed_pax_tar); +} + +#[test] +fn sparse_expanded_bytes_are_counted_in_load_capacity_check() { + use std::net::TcpListener; + + let scratch = Scratch::new("lp176-r1-sparse-cap"); + let home = scratch.base.join("home"); + fs::create_dir_all(&home).unwrap(); + home::ensure(&home).unwrap(); + + // Stand-in Docker reports small inspected.size (64 KiB) so initial capacity() passes, + // but streams a sparse file expanding to 512 KiB (docker::need(512 KiB) > 512 KiB free). + let standin = scratch.base.join("standin"); + fs::create_dir_all(standin.join("images")).unwrap(); + let id = format!("sha256:{}", "9".repeat(64)); + let sparse_tar = build_gnu_sparse_tar("big.bin", 0o644, 0, 512 * 1024, &[(0, b"HEAD")]); + fs::write(standin.join("export.tar"), &sparse_tar).unwrap(); + let img_json = format!( + r#"{{"Id":"{id}","RepoTags":["cap/sparse:1"],"Os":"linux","Architecture":"{}","Size":65536,"Config":{{}}}}"#, + architecture() + ); + fs::write(standin.join("images/cap_sparse_1.json"), &img_json).unwrap(); + let dbin = standin.join("docker"); + fs::write( + &dbin, + r#"#!/bin/sh +D="$(dirname "$0")" +case "$1 $2" in + "image inspect") cat "$D/images/cap_sparse_1.json"; echo; exit 0 ;; + "container inspect") + if [ "$3" = "--size" ]; then echo 65536; exit 0; fi + echo "No such object" >&2; exit 1 ;; +esac +case "$1" in + create) echo id ;; + export) cat "$D/export.tar" ;; + history) echo 65536 ;; + rm|ps) ;; +esac +"#, + ) + .unwrap(); + fs::set_permissions(&dbin, fs::Permissions::from_mode(0o755)).unwrap(); + + // Mock worker reporting 512 KiB free so initial 64 KiB check passes, + // then expanded streaming bytes hit Capacity during send(). + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let addr = listener.local_addr().unwrap(); + write_record( + &paths::machine_record(&home, "vm1"), + &SdkValue::map([ + ("name", SdkValue::text("vm1")), + ("platform", SdkValue::text("lima")), + ]), + ) + .unwrap(); + write_record( + &paths::worker_record(&home, "vm1"), + &SdkValue::map([ + ("address", SdkValue::text(addr.to_string())), + ("secret", SdkValue::text("k")), + ]), + ) + .unwrap(); + let (done_tx, done_rx) = std::sync::mpsc::channel(); + let server = std::thread::spawn(move || { + let mut writes = 0usize; + while let Ok((mut stream, _)) = listener.accept() { + if done_rx.try_recv().is_ok() { + break; + } + if read_frame_within(&mut stream, MAX_HELLO) + .ok() + .flatten() + .is_none() + { + continue; + } + write_frame( + &mut stream, + &SdkValue::map([ + ("ready", SdkValue::Bool(true)), + ("protocol", SdkValue::Int(PROTOCOL)), + ]), + ) + .unwrap(); + while let Ok(Some(req)) = read_frame(&mut stream) { + let args = req.get("args").cloned().unwrap_or(SdkValue::Null); + let step = args.get_text("step").unwrap_or(""); + if step == "write" { + writes += 1; + } + let value = match step { + "probe" => SdkValue::map([ + ("architecture", SdkValue::text(architecture())), + ("free", SdkValue::Int(512 * 1024)), + ( + "root", + SdkValue::text("/layerfs/data/machine/native/run/images"), + ), + ("present", SdkValue::Bool(false)), + ]), + _ => SdkValue::Null, + }; + write_frame(&mut stream, &SdkValue::map([("value", value)])).unwrap(); + } + if done_rx.try_recv().is_ok() { + break; + } + } + writes + }); + + let Executor::Worker(mut worker) = place::on_machine(&home, "vm1").unwrap() else { + panic!("expected worker executor"); + }; + let docker = Docker::at(Some(dbin), None); + let mut sink = |_: SdkValue| {}; + let mut events = Events::new(&mut sink); + let err = load( + &docker, + &mut events, + &mut Target::worker(&home, "vm1", &mut worker), + None, + "cap/sparse:1", + ) + .unwrap_err(); + assert_eq!(err.code, "Capacity", "{err:?}"); + let _ = done_tx.send(()); + let _ = std::net::TcpStream::connect(addr); + let writes = server.join().unwrap(); + assert_eq!( + writes, 0, + "capacity check must reject expanded frame before writing it" + ); +} + #[test] fn helper_pause_load() { let Ok(home) = std::env::var("LP176_REC_PAUSE_HOME") else { diff --git a/docs/architecture/api/sdk/machine.md b/docs/architecture/api/sdk/machine.md index 9deded854..a315a3b5b 100644 --- a/docs/architecture/api/sdk/machine.md +++ b/docs/architecture/api/sdk/machine.md @@ -236,21 +236,34 @@ legacy `layerfs-export--` containers labeled files (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, `etc/mtab`, `dev/*`), device or FIFO entries, refuses hardlinks whose targets were dropped, expands GNU oldgnu (`S`) and PAX (`0.0`, `0.1`, `1.0`) sparse entries while -streaming (`image_tar::TarReport` records dropped counts/paths and expanded -sparse bytes), and normalizes directory modification times +streaming (enforcing `image_tar::SPARSE_MAX` on per-entry `realsize` and +cumulative expanded bytes, bounding oldgnu/PAX `0.x` chunk counts by entry +`size`, requiring `payload_needed == size` after padding, refusing malformed PAX +records after `GNU.sparse.*` keys with `InvalidData`, counting expanded bytes +written to `.part` against `Capacity`, and recording dropped counts/paths and +expanded sparse bytes in `image_tar::TarReport`), and normalizes directory +modification times to epoch 0 (`1970-01-01T00:00:00Z`, PAX time records stripped and header checksum recomputed, so exports separated in time are byte-identical for resume) in 1 MiB `image.artifact` frames to `.recv-.part`; the machine checks its size and sha256, unpacks it once into `.2/`, strips the newly claimed `refs` from other cached -sidecars so moved tags cannot select stale images, writes the sidecar (keeping +sidecars (skipping corrupt unrelated sidecars) so moved tags cannot select stale +images, writes the sidecar (keeping `variant` and `config` recorded-only), and deletes the staged tar. `.2.json` is the publication commit point (Option B interrupted-publish recovery): a read-only `probe` treats an un-sidecared `.2/` outside a sealed archive as `present: false, stranded: true` instead of backfilling incomplete `refs`/`config`/`variant` without a lock, while `publish` removes any non-in-use stranded `.2/` under `ImageLock` before re-unpacking, and -`probe` refuses ambiguous `ref` lookups matching multiple cached images. A staged +`probe` refuses ambiguous `ref` lookups matching multiple cached images +(`InvalidInput`, suggesting `machine.prune` to remove one). + +Known limitations of `load` ref maintenance: +- `strip_moved_refs` reads and rewrites other sidecars without a cross-file lock; in a narrow concurrent window between `publish` stripping a moved ref and a simultaneous `touch()` (Sandbox creation) on the older image, the stripped ref can reappear on the older sidecar and cause an ambiguous-ref refusal until one image is removed with `machine.prune`. +- When the target digest is already cached on the machine, `load` returns `reused: true` early without calling `publish`, so moving a tag in Docker onto an already-cached target does not strip that tag from an older cached sidecar; if two sidecars claim the same ref, use `machine.prune` on one of them. + +A staged tar left by a copy that is not running is resumed when its bytes hash as this export's prefix, else restarted; `size` is the bytes sent, else the sidecar's, else the layers' unpacked size, and the export container's `SizeRootFs` only @@ -278,7 +291,17 @@ An image is in use while a Sandbox directory's `config/helper.spec` `lower=` names it, while a create holds `.2.lock`, or while a live process holds `ImageLock` (`/run/image-lock//.lock`): a named one is refused `InUse` (`detail.count`), and `unused` leaves its artifacts -untouched. Otherwise `prune` removes unpacked directories (including stranded +untouched. On `native`, `unused` guards each candidate hex with `ImageLock::try_hold` +(taking `flock` without writing an owner record so disk-full cleanups still +proceed), and if probing or guarding a single hex fails (for example an +unwritable lock directory or a bad `.lock` file), `unused` skips that hex, +continues cleaning the rest, and returns `skipped: [{ id, reason }]` when any +were skipped (naming that image directly returns the error). On worker routes +(`lima`, `apple-container`), `prune` skips images based on the `ImageLock` +snapshot taken at the start of the call; a concurrent `load` that starts after +that snapshot may have its `.part` or un-sidecared `.2/` removed and fail +(`write` offset mismatch or missing data, without corrupting cached data). +Otherwise `prune` removes unpacked directories (including stranded `.2` without `.2.json`), dangling `.2.json` sidecars, unheld `.recv-.part` staged files, and temporary `.tmp-.2-*` unpack directories (`unused` keeps valid unpacked copies of the machine's default). diff --git a/docs/versioned/2.0.0/calls.md b/docs/versioned/2.0.0/calls.md index fb62054cb..1292c31df 100644 --- a/docs/versioned/2.0.0/calls.md +++ b/docs/versioned/2.0.0/calls.md @@ -469,7 +469,7 @@ form. | `get` | `name` | — | a machine's record | | `images` | `name` | — | the Sandbox images and staged parts the machine holds (`images`: `id`, `refs`, `size`, `architecture`, `source` `bundle`/`machine`/`imported`/`staged`/`stranded`, `variant`, `config`, `sandboxes`, `last_used`, `staged`, and for parts `age`, `resumable`), its `default`, `free` bytes and `architecture`; and the host's tagged Docker images it could copy (`docker`, `available`: `id`, `refs`, `size`, `os`, `architecture`, `usable`, `reason`, `need`, `fits`). macOS `native` answers `mode: "host"` with none. Never starts a machine | | `load` | `name`, `image` | `on_progress` | copies an image to the machine as `sandbox create --image` does, without a Sandbox: `{id, refs, size, reused}`; removes stranded `.2` without `.2.json` on publish, strips moved `refs` from older sidecars, records `variant`/`config` without applying, drops FIFOs/devices/init files, expands sparse entries, and refuses hardlinks to dropped targets or ambiguous refs | -| `prune` | `name`, `image`? | `unused` | removes one image's artifacts or with `unused` every unheld unpacked image, stranded unpack, dangling sidecar, staged `.part` and `.tmp-*` dir except the machine's default: `{removed, freed}` (`freed` measured on the filesystem); live `ImageLock` or `InUse` entries are skipped on `unused` and refused `InUse` by name | +| `prune` | `name`, `image`? | `unused` | removes one image's artifacts or with `unused` every unheld unpacked image, stranded unpack, dangling sidecar, staged `.part` and `.tmp-*` dir except the machine's default: `{removed, freed, skipped?}` (`freed` measured on the filesystem); live `ImageLock` or `InUse` entries (and on `unused` entries whose lock guard/probe errors, listed in `skipped`) are skipped on `unused` and refused `InUse`/error by name | | `status` | `name` | — | a machine's live state, free disk and tool version; `op` while a create or remove holds it (#536 H6) | | `stats` | `machine` | — | what a machine has and uses now: processors, memory and data disk, each sqlite Store's size, how many of its Sandboxes have a running daemon (#164). For a UI that polls: it writes no call-log line | | `space` | `machine` | — | where a machine's data disk goes: each Store, each Sandbox's run folder, the image cache and LayerFS's logs, and what the disk uses that is not LayerFS's. For a UI: it writes no call-log line | From 5d20e5b6bc772112fdd018b268515b288381a66d Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 17 Nov 2026 14:31:01 +0000 Subject: [PATCH 6/8] sandbox: bound tar block padding and defer PAX parse for order-independent chunk cap (#176 I03 R2) - R2-M1: add checked padded_size() returning InvalidData on u64 overflow for both ustar/base-256 and PAX sizes; ignore unparseable PAX size on non-sparse entries (matching a5616c8c7) while rejecting invalid PAX size on sparse entries. - R2-M2: defer PAX b'x' parsing to PaxMeta::parse_pending after reading the entry header (reusing saved pending blocks), resolving effective entry size first (PAX size or ustar fallback) so push_chunk intercepts excess descriptors regardless of key order or missing PAX size. - Condensed local InvalidData constructors with invalid() to stay within the 999-line file ceiling (996 lines). - Tests: add r2_pax_size_overflow_plain_bad_size_and_order_independent_chunk_cap in lp176_image_recovery.rs. Production LOC (tools/production_loc.py --detail): - combined: 171,232 -> 171,240 (+8) - core: 39,795 -> 39,795 (0) - engine: 75,102 -> 75,102 (0) - control: 49,989 -> 49,997 (+8; layerfs-sandbox: 14,436 -> 14,444, +8) - api: 6,346 -> 6,346 (0) - reference: absent (retired R9c; last counted 65,417 at tree 498dd1917812) --- .../crates/layerfs-sandbox/src/image_tar.rs | 200 +++++++++--------- .../tests/lp176_image_recovery.rs | 125 +++++++++++ 2 files changed, 230 insertions(+), 95 deletions(-) diff --git a/control/crates/layerfs-sandbox/src/image_tar.rs b/control/crates/layerfs-sandbox/src/image_tar.rs index ef21a1dcf..41ad63381 100644 --- a/control/crates/layerfs-sandbox/src/image_tar.rs +++ b/control/crates/layerfs-sandbox/src/image_tar.rs @@ -23,6 +23,12 @@ fn invalid(msg: &str) -> io::Error { io::Error::new(io::ErrorKind::InvalidData, msg) } +fn padded_size(size: u64) -> io::Result { + size.div_ceil(BLOCK as u64) + .checked_mul(BLOCK as u64) + .ok_or_else(|| invalid("tar entry size overflow")) +} + fn push_gnu_slot( chunks: &mut Vec<(u64, u64)>, stored: &mut u64, @@ -250,8 +256,7 @@ impl Filtered { let mut needed_lines: usize = 1; loop { if raw.len() as u64 + BLOCK as u64 > max_bytes.min(EXTENDED_MAX) { - return Err(io::Error::new( - io::ErrorKind::InvalidData, + return Err(invalid( "PAX sparse map exceeds entry size or extended header limit", )); } @@ -265,16 +270,10 @@ impl Filtered { let count: usize = std::str::from_utf8(&raw[..nl]) .ok() .and_then(|s| s.trim().parse().ok()) - .ok_or_else(|| { - io::Error::new( - io::ErrorKind::InvalidData, - "invalid PAX sparse chunk count", - ) - })?; - needed_lines = - 1usize.checked_add(count.saturating_mul(2)).ok_or_else(|| { - io::Error::new(io::ErrorKind::InvalidData, "sparse map overflow") - })?; + .ok_or_else(|| invalid("invalid PAX sparse chunk count"))?; + needed_lines = 1usize + .checked_add(count.saturating_mul(2)) + .ok_or_else(|| invalid("sparse map overflow"))?; num_chunks = Some(count); } } @@ -293,25 +292,18 @@ impl Filtered { .map(|l| std::str::from_utf8(l).map(str::trim)); let _ = lines.next(); let mut chunks = Vec::with_capacity(count); - for _ in 0..count { - let off: u64 = lines + let mut next_u64 = |msg: &str| -> io::Result { + lines .next() .transpose() .ok() .flatten() .and_then(|s| s.parse().ok()) - .ok_or_else(|| { - io::Error::new(io::ErrorKind::InvalidData, "invalid PAX sparse offset") - })?; - let len: u64 = lines - .next() - .transpose() - .ok() - .flatten() - .and_then(|s| s.parse().ok()) - .ok_or_else(|| { - io::Error::new(io::ErrorKind::InvalidData, "invalid PAX sparse length") - })?; + .ok_or_else(|| invalid(msg)) + }; + for _ in 0..count { + let off = next_u64("invalid PAX sparse offset")?; + let len = next_u64("invalid PAX sparse length")?; if len > 0 { chunks.push((off, len)); } @@ -341,14 +333,11 @@ impl Filtered { return Ok(()); } let size = octal(&header[124..136])?; - let padded = size.div_ceil(BLOCK as u64) * BLOCK as u64; + let padded = padded_size(size)?; let flag = header[156]; if matches!(flag, b'x' | b'L' | b'K' | b'g') { if padded > EXTENDED_MAX { - return Err(io::Error::new( - io::ErrorKind::InvalidData, - "the image tar has an extended header over 1 MiB", - )); + return Err(invalid("the image tar has an extended header over 1 MiB")); } let mut data = vec![0u8; padded as usize]; if !self.block(&mut data)? { @@ -358,17 +347,15 @@ impl Filtered { )); } let body = &data[..size as usize]; - match flag { - b'x' => pax.parse_into(body)?, - b'L' => long_name = Some(text(body)), - b'K' => long_link = Some(text(body)), - _ => {} + if flag == b'L' { + long_name = Some(text(body)); + } else if flag == b'K' { + long_link = Some(text(body)); } pending.push((header, data)); continue; } - let size = pax.pax_size.unwrap_or(size); - let padded = size.div_ceil(BLOCK as u64) * BLOCK as u64; + let (size, padded) = pax.parse_pending(&pending, size, padded, flag)?; let gnu_chunks = if flag == b'S' { Some(self.read_gnu_sparse_map(&header, size)?) } else { @@ -407,10 +394,9 @@ impl Filtered { let target_norm = clean_path(&link_target); if self.dropped_paths.contains(&target_norm) || dropped(&target_norm, b'0') { let entry_norm = clean_path(&path); - return Err(io::Error::new( - io::ErrorKind::InvalidData, - format!("hardlink `{entry_norm}` points to dropped target `{target_norm}`"), - )); + return Err(invalid(&format!( + "hardlink `{entry_norm}` points to dropped target `{target_norm}`" + ))); } } let is_sparse = flag == b'S' || (matches!(flag, b'0' | b'\0') && pax.has_sparse); @@ -436,9 +422,6 @@ impl Filtered { } else if let Some(chunks) = gnu_chunks { (chunks, 0) } else { - if (pax.sparse_chunks.len() as u64) > size { - return Err(invalid("PAX sparse chunk count exceeds tar entry size")); - } (pax.sparse_chunks, 0) }; let (chunks, stored_bytes) = validate_sparse_chunks(raw_chunks, realsize)?; @@ -621,7 +604,6 @@ impl Read for Filtered { struct PaxMeta { path: Option, linkpath: Option, - pax_size: Option, has_sparse: bool, sparse_major: Option, sparse_minor: Option, @@ -659,13 +641,9 @@ fn walk_pax_records( } impl PaxMeta { - fn push_chunk(&mut self, off: u64, len: u64) -> io::Result<()> { + fn push_chunk(&mut self, off: u64, len: u64, entry_size: u64) -> io::Result<()> { if len > 0 { - let cap = self - .pax_size - .unwrap_or(u64::MAX) - .min(SPARSE_CHUNKS_MAX as u64); - if (self.sparse_chunks.len() as u64) >= cap { + if (self.sparse_chunks.len() as u64) >= entry_size.min(SPARSE_CHUNKS_MAX as u64) { return Err(invalid( "PAX sparse chunk count exceeds entry size or limit", )); @@ -675,19 +653,64 @@ impl PaxMeta { Ok(()) } - fn parse_into(&mut self, body: &[u8]) -> io::Result<()> { + fn parse_pending( + &mut self, + pending: &[([u8; BLOCK], Vec)], + ustar_size: u64, + ustar_padded: u64, + flag: u8, + ) -> io::Result<(u64, u64)> { + if !pending.iter().any(|(h, _)| h[156] == b'x') { + return Ok((ustar_size, ustar_padded)); + } + let mut pax_size: Option = None; + let mut pax_size_bad = false; + let mut has_sparse = false; + let mut bodies = Vec::new(); + for (ext_hdr, ext_data) in pending { + if ext_hdr[156] != b'x' { + continue; + } + let ext_size = octal(&ext_hdr[124..136])? as usize; + let body = &ext_data[..ext_size.min(ext_data.len())]; + walk_pax_records(body, |_, key, val| { + if key == b"size" { + let parsed = std::str::from_utf8(val) + .ok() + .and_then(|s| s.trim().parse::().ok()); + pax_size = parsed; + pax_size_bad = parsed.is_none(); + } else if key.starts_with(b"GNU.sparse.") { + has_sparse = true; + } + Ok(()) + })?; + bodies.push(body); + } + if pax_size_bad && (flag == b'S' || has_sparse) { + return Err(invalid("invalid pax size")); + } + let size = pax_size.unwrap_or(ustar_size); + let padded = padded_size(size)?; + for body in bodies { + self.parse_into(body, size)?; + } + Ok((size, padded)) + } + + fn parse_into(&mut self, body: &[u8], entry_size: u64) -> io::Result<()> { let mut pending_offset: Option = None; let complete = walk_pax_records(body, |_, key, val| { let val_str = String::from_utf8_lossy(val); let parse_u64 = |label: &str| { - val_str.trim().parse::().map_err(|_| { - io::Error::new(io::ErrorKind::InvalidData, format!("invalid pax {label}")) - }) + val_str + .trim() + .parse::() + .map_err(|_| invalid(&format!("invalid pax {label}"))) }; match key { b"path" => self.path = Some(val_str.into_owned()), b"linkpath" => self.linkpath = Some(val_str.into_owned()), - b"size" => self.pax_size = Some(parse_u64("size")?), b"GNU.sparse.major" => { self.has_sparse = true; self.sparse_major = Some(parse_u64("GNU.sparse.major")?); @@ -710,32 +733,28 @@ impl PaxMeta { } b"GNU.sparse.numbytes" => { self.has_sparse = true; - let off = pending_offset.take().ok_or_else(|| { - io::Error::new( - io::ErrorKind::InvalidData, - "GNU.sparse.numbytes without offset", - ) - })?; + let off = pending_offset + .take() + .ok_or_else(|| invalid("GNU.sparse.numbytes without offset"))?; let len = parse_u64("GNU.sparse.numbytes")?; - self.push_chunk(off, len)?; + self.push_chunk(off, len, entry_size)?; } b"GNU.sparse.map" => { self.has_sparse = true; let mut parts = val_str.split(',').filter(|s| !s.is_empty()); while let Some(o_str) = parts.next() { - let l_str = parts.next().ok_or_else(|| { - io::Error::new( - io::ErrorKind::InvalidData, - "odd item count in GNU.sparse.map", - ) - })?; - let off: u64 = o_str.trim().parse().map_err(|_| { - io::Error::new(io::ErrorKind::InvalidData, "invalid sparse map offset") - })?; - let len: u64 = l_str.trim().parse().map_err(|_| { - io::Error::new(io::ErrorKind::InvalidData, "invalid sparse map len") - })?; - self.push_chunk(off, len)?; + let l_str = parts + .next() + .ok_or_else(|| invalid("odd item count in GNU.sparse.map"))?; + let off: u64 = o_str + .trim() + .parse() + .map_err(|_| invalid("invalid sparse map offset"))?; + let len: u64 = l_str + .trim() + .parse() + .map_err(|_| invalid("invalid sparse map len"))?; + self.push_chunk(off, len, entry_size)?; } } _ => { @@ -765,32 +784,23 @@ fn validate_sparse_chunks( let mut valid = Vec::with_capacity(chunks.len()); for (off, len) in chunks { if off > realsize { - return Err(io::Error::new( - io::ErrorKind::InvalidData, - "sparse chunk starts past realsize", - )); + return Err(invalid("sparse chunk starts past realsize")); } if len == 0 { continue; } if off < prev_end { - return Err(io::Error::new( - io::ErrorKind::InvalidData, - "sparse chunks overlap or are out of order", - )); + return Err(invalid("sparse chunks overlap or are out of order")); } - let end = off.checked_add(len).ok_or_else(|| { - io::Error::new(io::ErrorKind::InvalidData, "sparse chunk end overflow") - })?; + let end = off + .checked_add(len) + .ok_or_else(|| invalid("sparse chunk end overflow"))?; if end > realsize { - return Err(io::Error::new( - io::ErrorKind::InvalidData, - "sparse chunk extends past realsize", - )); + return Err(invalid("sparse chunk extends past realsize")); } - stored_bytes = stored_bytes.checked_add(len).ok_or_else(|| { - io::Error::new(io::ErrorKind::InvalidData, "sparse byte count overflow") - })?; + stored_bytes = stored_bytes + .checked_add(len) + .ok_or_else(|| invalid("sparse byte count overflow"))?; prev_end = end; valid.push((off, len)); } diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs index 92df70f9d..5ceeeaade 100644 --- a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs +++ b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs @@ -1631,6 +1631,131 @@ fn sparse_safety_rejects_oversized_realsize_excess_chunks_size_mismatch_and_malf assert_invalid_data("malformed PAX after GNU.sparse.*", malformed_pax_tar); } +#[test] +fn r2_pax_size_overflow_plain_bad_size_and_order_independent_chunk_cap() { + let assert_invalid = |label: &str, tar_bytes: &[u8], needle: &str| { + let err = filtered_bytes(tar_bytes).expect_err(label); + assert_eq!( + err.kind(), + std::io::ErrorKind::InvalidData, + "{label}: got {err:?}" + ); + assert!( + err.to_string().contains(needle), + "{label}: expected `{needle}` in `{err}`" + ); + }; + + // 1. R2-M1: PAX size = u64::MAX on both plain and sparse entries returns InvalidData without panic. + let huge_pax_size = pax_record("size", &u64::MAX.to_string()); + let plain_u64_max = Tar::new() + .raw("PaxHeaders/huge-plain", b'x', 0o644, &huge_pax_size) + .file("plain.bin", 0o644, b"RAW") + .finish(); + assert_invalid("plain PAX size=u64::MAX", &plain_u64_max, "overflow"); + + let mut sparse_u64_max_pax = pax_record("GNU.sparse.major", "0"); + sparse_u64_max_pax.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + sparse_u64_max_pax.extend_from_slice(&pax_record("GNU.sparse.realsize", "8192")); + sparse_u64_max_pax.extend_from_slice(&pax_record("GNU.sparse.map", "0,1")); + sparse_u64_max_pax.extend_from_slice(&huge_pax_size); + let sparse_u64_max = Tar::new() + .raw("PaxHeaders/huge-sparse", b'x', 0o644, &sparse_u64_max_pax) + .file("sparse.bin", 0o644, b"A") + .finish(); + assert_invalid("sparse PAX size=u64::MAX", &sparse_u64_max, "overflow"); + + // Ustar/base-256 header size = u64::MAX also returns InvalidData without panic. + let mut b256_hdr = [0u8; 512]; + b256_hdr[..7].copy_from_slice(b"big.bin"); + b256_hdr[100..108].copy_from_slice(b"0000644\0"); + b256_hdr[124] = 0x80; + b256_hdr[128..136].copy_from_slice(&u64::MAX.to_be_bytes()); + b256_hdr[156] = b'0'; + b256_hdr[257..263].copy_from_slice(b"ustar\0"); + b256_hdr[263..265].copy_from_slice(b"00"); + b256_hdr[148..156].fill(b' '); + let sum: u64 = b256_hdr.iter().map(|b| u64::from(*b)).sum(); + b256_hdr[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes()); + assert_invalid("ustar base-256 size=u64::MAX", &b256_hdr, "overflow"); + + // 2. R2-M1: Plain file with `12 size=bad\n` and no GNU.sparse.* passes through intact (a5616c8c7 parity). + let bad_pax_size = pax_record("size", "bad"); + assert_eq!(bad_pax_size, b"12 size=bad\n"); + let plain_bad_size = Tar::new() + .raw("PaxHeaders/bad-size", b'x', 0o644, &bad_pax_size) + .file("plain.bin", 0o644, b"RAW") + .finish(); + assert_eq!(filtered_bytes(&plain_bad_size).unwrap(), plain_bad_size); + + let mut sparse_bad_size_pax = pax_record("GNU.sparse.major", "0"); + sparse_bad_size_pax.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + sparse_bad_size_pax.extend_from_slice(&pax_record("GNU.sparse.realsize", "8192")); + sparse_bad_size_pax.extend_from_slice(&pax_record("GNU.sparse.map", "0,1")); + sparse_bad_size_pax.extend_from_slice(&bad_pax_size); + let sparse_bad_size = Tar::new() + .raw("PaxHeaders/sparse-bad", b'x', 0o644, &sparse_bad_size_pax) + .file("sparse.bin", 0o644, b"A") + .finish(); + assert_invalid("sparse PAX size=bad", &sparse_bad_size, "invalid pax size"); + + // 3. R2-M2: Order-independent PAX chunk count cap aborts before trailing invalid descriptors. + let map_with_trailing_bad = "0,1,4096,1,8192,1,bad,bad"; + let chunk_err = "PAX sparse chunk count exceeds entry size or limit"; + + // 3a. PAX `size` BEFORE `GNU.sparse.map`. + let mut size_before_map = pax_record("GNU.sparse.major", "0"); + size_before_map.extend_from_slice(&pax_record("size", "2")); + size_before_map.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + size_before_map.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); + size_before_map.extend_from_slice(&pax_record("GNU.sparse.map", map_with_trailing_bad)); + let tar_before = Tar::new() + .raw("PaxHeaders/before", b'x', 0o644, &size_before_map) + .file("m1.bin", 0o644, b"AB") + .finish(); + assert_invalid("PAX size before map", &tar_before, chunk_err); + + // 3b. PAX `size` AFTER `GNU.sparse.map`. + let mut size_after_map = pax_record("GNU.sparse.major", "0"); + size_after_map.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + size_after_map.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); + size_after_map.extend_from_slice(&pax_record("GNU.sparse.map", map_with_trailing_bad)); + size_after_map.extend_from_slice(&pax_record("size", "2")); + let tar_after = Tar::new() + .raw("PaxHeaders/after", b'x', 0o644, &size_after_map) + .file("m2.bin", 0o644, b"AB") + .finish(); + assert_invalid("PAX size after map", &tar_after, chunk_err); + + // 3c. No PAX `size` (falls back to ustar header size = 2) still aborts before `,bad,bad`. + let mut no_pax_size = pax_record("GNU.sparse.major", "0"); + no_pax_size.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + no_pax_size.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); + no_pax_size.extend_from_slice(&pax_record("GNU.sparse.map", map_with_trailing_bad)); + let tar_no_pax_size = Tar::new() + .raw("PaxHeaders/nosize", b'x', 0o644, &no_pax_size) + .file("m3.bin", 0o644, b"AB") + .finish(); + assert_invalid("PAX no size (ustar fallback)", &tar_no_pax_size, chunk_err); + + // 3d. PAX 0.0 offset/numbytes pairs with `size` AFTER pairs and trailing invalid offset. + let mut pax00_size_after = pax_record("GNU.sparse.major", "0"); + pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.minor", "0")); + pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); + for i in 0..3u64 { + pax00_size_after + .extend_from_slice(&pax_record("GNU.sparse.offset", &(i * 4096).to_string())); + pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.numbytes", "1")); + } + pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.offset", "bad")); + pax00_size_after.extend_from_slice(&pax_record("size", "2")); + let tar_pax00 = Tar::new() + .raw("PaxHeaders/pax00", b'x', 0o644, &pax00_size_after) + .file("m4.bin", 0o644, b"AB") + .finish(); + assert_invalid("PAX 0.0 size after chunks", &tar_pax00, chunk_err); +} + #[test] fn sparse_expanded_bytes_are_counted_in_load_capacity_check() { use std::net::TcpListener; From f19ae105332a936fb33412ca45af1879d77dcd16 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:17:31 +0000 Subject: [PATCH 7/8] sandbox: split tar PAX/sparse pipeline into staged modules and bound extended headers (#176 I03 R3) - Split control/crates/layerfs-sandbox/src/image_tar.rs into image_tar/{mod,header,pax,sparse,filter}.rs, keeping public image_tar items intact and adding EXTENDED_TOTAL_MAX (16 MiB). - Stage 1 (PendingHeaders::admit_header / push, PaxScan::scan_header): enforce 1 MiB per-header (EXTENDED_MAX) and 16 MiB per-entry cumulative (EXTENDED_TOTAL_MAX, accounting 512 + padded per extended header so zero-length header floods are bounded) before allocating payloads; validate size-independent PAX/sparse syntax (when GNU.sparse.* is present), sparse numbers, offset/numbytes pairing, and cross-header SPARSE_CHUNKS_MAX count on arrival without building a descriptor Vec. - Stage 2 (resolve_entry_size, ensure_chunk_count_within, collect_sparse_chunks, in-place validate_sparse_chunks): resolve effective entry size (preserving plain bad-size fallback and checked 512B alignment), enforce min(size, SPARSE_CHUNKS_MAX) before materializing PAX 0.x chunks, and validate in place without a duplicate Vec. - Stage 3 (clean EOF & zero end-blocks): bad sparse PAX headers already failed in Stage 1 while trailing plain extended headers retain a5616c8c7 parity. - Tests: add consecutive_pax_x_interleaved_g_long_paths_and_dir_times_match_baseline (image_tar.rs) and r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom (lp176_image_recovery.rs); update r2_pax_size_overflow_plain_bad_size_and_order_independent_chunk_cap 3a-3d sentinels to Stage-2 out-of-range chunk (32768, 1) past realsize=16384 while 3e asserts Stage-1 rejection on ,bad,bad and offset=bad. Production LOC: 171,240 -> 171,386 (delta +146) core 39,795 -> 39,795 (0) engine 75,102 -> 75,102 (0) control 49,997 -> 50,143 (+146) layerfs-sandbox +146 api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent 5d20e5b6b and the staged tree --- .../crates/layerfs-sandbox/src/image_tar.rs | 996 ------------------ .../layerfs-sandbox/src/image_tar/filter.rs | 351 ++++++ .../layerfs-sandbox/src/image_tar/header.rs | 90 ++ .../layerfs-sandbox/src/image_tar/mod.rs | 18 + .../layerfs-sandbox/src/image_tar/pax.rs | 466 ++++++++ .../layerfs-sandbox/src/image_tar/sparse.rs | 285 +++++ .../crates/layerfs-sandbox/tests/image_tar.rs | 140 +++ .../tests/lp176_image_recovery.rs | 466 +++++++- 8 files changed, 1804 insertions(+), 1008 deletions(-) delete mode 100644 control/crates/layerfs-sandbox/src/image_tar.rs create mode 100644 control/crates/layerfs-sandbox/src/image_tar/filter.rs create mode 100644 control/crates/layerfs-sandbox/src/image_tar/header.rs create mode 100644 control/crates/layerfs-sandbox/src/image_tar/mod.rs create mode 100644 control/crates/layerfs-sandbox/src/image_tar/pax.rs create mode 100644 control/crates/layerfs-sandbox/src/image_tar/sparse.rs diff --git a/control/crates/layerfs-sandbox/src/image_tar.rs b/control/crates/layerfs-sandbox/src/image_tar.rs deleted file mode 100644 index 41ad63381..000000000 --- a/control/crates/layerfs-sandbox/src/image_tar.rs +++ /dev/null @@ -1,996 +0,0 @@ -//! The flat root filesystem tar a Sandbox image is copied as: `docker -//! export`'s output with the files `docker create`'s init layer adds taken -//! out (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, -//! `etc/mtab`, everything under `dev/`), every device node and FIFO (which -//! the unpacker refuses), hardlinks targeting dropped entries refused clearly, -//! sparse entries expanded to regular files, and directory modification times -//! normalized to 0 with recomputed header checksums. Those are the bytes that -//! differ between two exports of one image; what is left is the image's own -//! tree. The filter streams: it holds at most one entry's extended headers and -//! sparse chunk map, never a file's bytes. -use std::collections::HashSet; -use std::io::{self, Read}; - -const BLOCK: usize = 512; -/// The largest pax or GNU extended header kept while its entry is decided. -const EXTENDED_MAX: u64 = 1 << 20; -/// Maximum logical expanded size (`realsize` and cumulative sparse output) permitted. -pub const SPARSE_MAX: u64 = 16 << 30; -/// Hard cap on parsed sparse chunk descriptors across extended headers. -const SPARSE_CHUNKS_MAX: usize = 1 << 20; - -fn invalid(msg: &str) -> io::Error { - io::Error::new(io::ErrorKind::InvalidData, msg) -} - -fn padded_size(size: u64) -> io::Result { - size.div_ceil(BLOCK as u64) - .checked_mul(BLOCK as u64) - .ok_or_else(|| invalid("tar entry size overflow")) -} - -fn push_gnu_slot( - chunks: &mut Vec<(u64, u64)>, - stored: &mut u64, - slot: &[u8], - entry_size: u64, -) -> io::Result { - let off = octal(&slot[..12])?; - let len = octal(&slot[12..24])?; - if len == 0 { - return Ok(false); - } - if (chunks.len() as u64) >= entry_size - || chunks.len() >= SPARSE_CHUNKS_MAX - || stored.checked_add(len).is_none_or(|s| s > entry_size) - { - return Err(invalid("GNU sparse chunks exceed tar entry size")); - } - *stored += len; - chunks.push((off, len)); - Ok(true) -} - -/// Paths the init layer of `docker create` adds or replaces. -const INIT_FILES: [&str; 5] = [ - ".dockerenv", - "etc/hosts", - "etc/hostname", - "etc/resolv.conf", - "etc/mtab", -]; - -fn clean_path(path: &str) -> String { - path.trim_start_matches("./") - .trim_start_matches('/') - .trim_end_matches('/') - .to_owned() -} - -/// Whether an entry at `path` of type `flag` is left out of the copy. -pub fn dropped(path: &str, flag: u8) -> bool { - let path = path.trim_start_matches("./").trim_start_matches('/'); - let path = path.trim_end_matches('/'); - matches!(flag, b'3' | b'4' | b'6') - || INIT_FILES.contains(&path) - || path - .strip_prefix("dev/") - .is_some_and(|rest| !rest.is_empty()) -} - -/// One sparse tar entry expanded into a regular file (`b'0'`). -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct SparseReport { - /// Entry path with `./` and leading `/` removed. - pub path: String, - /// Expanded logical size in bytes. - pub expanded_bytes: u64, - /// Stored sparse payload bytes read from the source tar. - pub stored_bytes: u64, -} - -/// Report of dropped entries and expanded sparse files seen while filtering. -#[derive(Clone, Debug, Default, PartialEq, Eq)] -pub struct TarReport { - /// Paths of dropped FIFO (`b'6'`) entries. - pub fifos: Vec, - /// Paths of dropped character/block device (`b'3'`, `b'4'`) entries. - pub devices: Vec, - /// Paths of dropped container init entries (`.dockerenv`, `/etc/hosts`, `dev/*`, ...). - pub init: Vec, - /// Details of every sparse entry expanded while streaming. - pub sparse_files: Vec, - /// Total expanded logical bytes across all sparse entries. - pub sparse_expanded_bytes: u64, -} - -impl TarReport { - /// Number of dropped FIFO entries. - pub fn fifo_count(&self) -> usize { - self.fifos.len() - } - - /// Number of dropped device entries. - pub fn device_count(&self) -> usize { - self.devices.len() - } - - /// Number of dropped init/runtime entries. - pub fn init_count(&self) -> usize { - self.init.len() - } -} - -struct SparseStream { - chunks: Vec<(u64, u64)>, - chunk_idx: usize, - chunk_left: u64, - pos: u64, - realsize: u64, - out_pad: u64, - input_skip: u64, -} - -/// A reader of `input` (a tar stream) that yields the same tar without the -/// [`dropped`] entries and with sparse entries expanded to regular files. -pub struct Filtered { - input: R, - /// Bytes ready to hand out. - out: Vec, - at: usize, - /// Bytes of the current kept entry's data (with padding) still to copy. - copying: u64, - sparse: Option, - sparse_max: u64, - dropped_paths: HashSet, - report: TarReport, - done: bool, -} - -impl Filtered { - /// Filters `input`. - pub fn new(input: R) -> Self { - Self { - input, - out: Vec::new(), - at: 0, - copying: 0, - sparse: None, - sparse_max: SPARSE_MAX, - dropped_paths: HashSet::new(), - report: TarReport::default(), - done: false, - } - } - - /// Sets the maximum expanded sparse byte budget (per entry and cumulative). - pub fn with_sparse_max(mut self, max: u64) -> Self { - self.sparse_max = max; - self - } - - /// Report of entries dropped or sparse files expanded so far. - pub fn report(&self) -> &TarReport { - &self.report - } - - /// Consumes the filter and returns its [`TarReport`]. - pub fn into_report(self) -> TarReport { - self.report - } - - /// Reads exactly `buffer.len()` bytes, or none at a clean end. - fn block(&mut self, buffer: &mut [u8]) -> io::Result { - let mut read = 0; - while read < buffer.len() { - let n = self.input.read(&mut buffer[read..])?; - if n == 0 { - if read == 0 { - return Ok(false); - } - return Err(io::Error::new( - io::ErrorKind::UnexpectedEof, - "the image tar ends inside a block", - )); - } - read += n; - } - Ok(true) - } - - /// Skips `count` bytes of input. - fn skip(&mut self, count: u64) -> io::Result<()> { - if count == 0 { - return Ok(()); - } - let copied = io::copy(&mut (&mut self.input).take(count), &mut io::sink())?; - if copied != count { - return Err(io::ErrorKind::UnexpectedEof.into()); - } - Ok(()) - } - - /// Reads GNU oldgnu extended sparse header blocks that follow a `b'S'` header. - fn read_gnu_sparse_map( - &mut self, - header: &[u8; BLOCK], - entry_size: u64, - ) -> io::Result> { - let mut chunks = Vec::new(); - let mut stored = 0u64; - for i in 0..4 { - let base = 386 + i * 24; - push_gnu_slot( - &mut chunks, - &mut stored, - &header[base..base + 24], - entry_size, - )?; - } - let mut extended = header[482] != 0; - while extended { - let mut ext = [0u8; BLOCK]; - if !self.block(&mut ext)? { - return Err(io::ErrorKind::UnexpectedEof.into()); - } - let mut added = false; - for slot in 0..21 { - let base = slot * 24; - if push_gnu_slot(&mut chunks, &mut stored, &ext[base..base + 24], entry_size)? { - added = true; - } - } - extended = ext[504] != 0; - if !added && extended { - return Err(invalid("empty GNU sparse extended block")); - } - } - Ok(chunks) - } - - /// Reads the PAX `1.0` inline newline-delimited sparse map (512-byte padded) - /// from the beginning of the entry's payload, returning `(chunks, map_bytes)`. - fn read_pax1_sparse_map(&mut self, max_bytes: u64) -> io::Result<(Vec<(u64, u64)>, u64)> { - let mut raw = Vec::new(); - let mut num_chunks: Option = None; - let mut needed_lines: usize = 1; - loop { - if raw.len() as u64 + BLOCK as u64 > max_bytes.min(EXTENDED_MAX) { - return Err(invalid( - "PAX sparse map exceeds entry size or extended header limit", - )); - } - let mut blk = [0u8; BLOCK]; - if !self.block(&mut blk)? { - return Err(io::ErrorKind::UnexpectedEof.into()); - } - raw.extend_from_slice(&blk); - if num_chunks.is_none() { - if let Some(nl) = raw.iter().position(|b| *b == b'\n') { - let count: usize = std::str::from_utf8(&raw[..nl]) - .ok() - .and_then(|s| s.trim().parse().ok()) - .ok_or_else(|| invalid("invalid PAX sparse chunk count"))?; - needed_lines = 1usize - .checked_add(count.saturating_mul(2)) - .ok_or_else(|| invalid("sparse map overflow"))?; - num_chunks = Some(count); - } - } - if num_chunks.is_some() { - let newlines = raw.iter().filter(|b| **b == b'\n').count(); - if newlines >= needed_lines { - break; - } - } - } - let map_bytes = raw.len() as u64; - let count = num_chunks.unwrap_or(0); - let mut lines = raw - .split(|b| *b == b'\n') - .take(needed_lines) - .map(|l| std::str::from_utf8(l).map(str::trim)); - let _ = lines.next(); - let mut chunks = Vec::with_capacity(count); - let mut next_u64 = |msg: &str| -> io::Result { - lines - .next() - .transpose() - .ok() - .flatten() - .and_then(|s| s.parse().ok()) - .ok_or_else(|| invalid(msg)) - }; - for _ in 0..count { - let off = next_u64("invalid PAX sparse offset")?; - let len = next_u64("invalid PAX sparse length")?; - if len > 0 { - chunks.push((off, len)); - } - } - Ok((chunks, map_bytes)) - } - - /// Decides the next entry: fills `out` with its headers when it is kept - /// (its data then follows through `copying` or `sparse`), or skips it. - fn next_entry(&mut self) -> io::Result<()> { - let mut pending: Vec<([u8; BLOCK], Vec)> = Vec::new(); - let mut long_name: Option = None; - let mut long_link: Option = None; - let mut pax = PaxMeta::default(); - loop { - let mut header = [0u8; BLOCK]; - if !self.block(&mut header)? { - // a stream without its end blocks: end it here - self.out.extend_from_slice(&[0u8; BLOCK * 2]); - self.done = true; - return Ok(()); - } - if header.iter().all(|b| *b == 0) { - // the end of the archive: two zero blocks, nothing after - self.out.extend_from_slice(&[0u8; BLOCK * 2]); - self.done = true; - return Ok(()); - } - let size = octal(&header[124..136])?; - let padded = padded_size(size)?; - let flag = header[156]; - if matches!(flag, b'x' | b'L' | b'K' | b'g') { - if padded > EXTENDED_MAX { - return Err(invalid("the image tar has an extended header over 1 MiB")); - } - let mut data = vec![0u8; padded as usize]; - if !self.block(&mut data)? { - return Err(io::Error::new( - io::ErrorKind::UnexpectedEof, - "unexpected EOF inside extended tar header", - )); - } - let body = &data[..size as usize]; - if flag == b'L' { - long_name = Some(text(body)); - } else if flag == b'K' { - long_link = Some(text(body)); - } - pending.push((header, data)); - continue; - } - let (size, padded) = pax.parse_pending(&pending, size, padded, flag)?; - let gnu_chunks = if flag == b'S' { - Some(self.read_gnu_sparse_map(&header, size)?) - } else { - None - }; - let pax_path = pax.path.take(); - let pax_link = pax.linkpath.take(); - let sparse_name = pax.sparse_name.take(); - let path = sparse_name - .clone() - .or(pax_path) - .or_else(|| long_name.take()) - .unwrap_or_else(|| ustar_name(&header)); - // a link or directory carries no data, whatever its size says - let data = if matches!(flag, b'1' | b'2' | b'3' | b'4' | b'5' | b'6') { - 0 - } else { - padded - }; - if dropped(&path, flag) { - let norm = clean_path(&path); - if matches!(flag, b'6') { - self.report.fifos.push(norm.clone()); - } else if matches!(flag, b'3' | b'4') { - self.report.devices.push(norm.clone()); - } else { - self.report.init.push(norm.clone()); - } - self.dropped_paths.insert(norm); - return self.skip(data); - } - if flag == b'1' { - let link_target = pax_link - .or_else(|| long_link.take()) - .unwrap_or_else(|| text(&header[157..257])); - let target_norm = clean_path(&link_target); - if self.dropped_paths.contains(&target_norm) || dropped(&target_norm, b'0') { - let entry_norm = clean_path(&path); - return Err(invalid(&format!( - "hardlink `{entry_norm}` points to dropped target `{target_norm}`" - ))); - } - } - let is_sparse = flag == b'S' || (matches!(flag, b'0' | b'\0') && pax.has_sparse); - if is_sparse { - let realsize = if flag == b'S' { - pax.sparse_realsize.unwrap_or(octal(&header[483..495])?) - } else { - pax.sparse_realsize - .ok_or_else(|| invalid("PAX sparse file missing realsize"))? - }; - if realsize > self.sparse_max - || self - .report - .sparse_expanded_bytes - .checked_add(realsize) - .is_none_or(|total| total > self.sparse_max) - { - return Err(invalid("sparse entry realsize exceeds maximum")); - } - let (raw_chunks, map_bytes) = - if pax.sparse_major == Some(1) && pax.sparse_minor == Some(0) { - self.read_pax1_sparse_map(size)? - } else if let Some(chunks) = gnu_chunks { - (chunks, 0) - } else { - (pax.sparse_chunks, 0) - }; - let (chunks, stored_bytes) = validate_sparse_chunks(raw_chunks, realsize)?; - let payload_needed = map_bytes - .checked_add(stored_bytes) - .ok_or_else(|| invalid("sparse payload overflow"))?; - if payload_needed != size { - return Err(invalid("sparse payload size does not match tar entry size")); - } - let input_skip = padded - payload_needed; - let override_path = sparse_name.as_deref(); - emit_sparse_pax_headers(&mut pending, override_path, &mut self.out)?; - let is_oldgnu = flag == b'S' || &header[257..263] == b"ustar "; - header[156] = b'0'; - if is_oldgnu { - header[257..263].copy_from_slice(b"ustar\0"); - header[263..265].copy_from_slice(b"00"); - header[329..512].fill(0); - } - write_size_field(&mut header[124..136], realsize)?; - recompute_checksum(&mut header); - self.out.extend_from_slice(&header); - self.report.sparse_files.push(SparseReport { - path: clean_path(&path), - expanded_bytes: realsize, - stored_bytes, - }); - self.report.sparse_expanded_bytes = - self.report.sparse_expanded_bytes.saturating_add(realsize); - let out_pad = (BLOCK as u64 - (realsize % BLOCK as u64)) % BLOCK as u64; - if realsize == 0 { - self.skip(input_skip)?; - return Ok(()); - } - self.sparse = Some(SparseStream { - chunks, - chunk_idx: 0, - chunk_left: 0, - pos: 0, - realsize, - out_pad, - input_skip, - }); - return Ok(()); - } - if flag == b'5' { - for (mut ext_hdr, ext_data) in pending { - if ext_hdr[156] == b'x' { - if let Some((mut h, d)) = strip_pax_times(ext_hdr, ext_data)? { - h[136..148].copy_from_slice(b"00000000000\0"); - recompute_checksum(&mut h); - self.out.extend_from_slice(&h); - self.out.extend_from_slice(&d); - } - } else { - if matches!(ext_hdr[156], b'L' | b'K') { - ext_hdr[136..148].copy_from_slice(b"00000000000\0"); - recompute_checksum(&mut ext_hdr); - } - self.out.extend_from_slice(&ext_hdr); - self.out.extend_from_slice(&ext_data); - } - } - // `docker create`'s init layer touches directories such as `dev/` - // and `etc/` at container creation time; normalize every kept - // directory's mtime so exports >=2 s apart stay byte-identical. - header[136..148].copy_from_slice(b"00000000000\0"); - recompute_checksum(&mut header); - } else { - for (ext_hdr, ext_data) in pending { - self.out.extend_from_slice(&ext_hdr); - self.out.extend_from_slice(&ext_data); - } - } - self.out.extend_from_slice(&header); - self.copying = data; - return Ok(()); - } - } - - fn read_sparse( - &mut self, - st: &mut SparseStream, - buffer: &mut [u8], - ) -> io::Result> { - loop { - if st.chunk_left > 0 { - let want = (buffer.len() as u64).min(st.chunk_left) as usize; - let n = self.input.read(&mut buffer[..want])?; - if n == 0 { - return Err(io::Error::new( - io::ErrorKind::UnexpectedEof, - "unexpected EOF in sparse tar chunk", - )); - } - st.chunk_left -= n as u64; - st.pos += n as u64; - if st.chunk_left == 0 { - st.chunk_idx += 1; - } - return Ok(Some(n)); - } - if st.pos < st.realsize { - let hole_end = st - .chunks - .get(st.chunk_idx) - .map_or(st.realsize, |(off, _)| *off); - if st.pos < hole_end { - let zeros = (hole_end - st.pos).min(buffer.len() as u64) as usize; - buffer[..zeros].fill(0); - st.pos += zeros as u64; - if st.pos == hole_end { - if let Some((_, len)) = st.chunks.get(st.chunk_idx) { - st.chunk_left = *len; - } - } - return Ok(Some(zeros)); - } - if let Some((_, len)) = st.chunks.get(st.chunk_idx) { - st.chunk_left = *len; - continue; - } - } - let to_skip = std::mem::take(&mut st.input_skip); - if to_skip > 0 { - self.skip(to_skip)?; - } - if st.out_pad > 0 { - let zeros = st.out_pad.min(buffer.len() as u64) as usize; - buffer[..zeros].fill(0); - st.out_pad -= zeros as u64; - return Ok(Some(zeros)); - } - return Ok(None); - } - } -} - -impl Read for Filtered { - fn read(&mut self, buffer: &mut [u8]) -> io::Result { - loop { - if self.at < self.out.len() { - let n = (self.out.len() - self.at).min(buffer.len()); - buffer[..n].copy_from_slice(&self.out[self.at..self.at + n]); - self.at += n; - return Ok(n); - } - self.out.clear(); - self.at = 0; - if buffer.is_empty() { - return Ok(0); - } - if self.copying > 0 { - let wanted = (buffer.len() as u64).min(self.copying) as usize; - let n = self.input.read(&mut buffer[..wanted])?; - if n == 0 { - return Err(io::ErrorKind::UnexpectedEof.into()); - } - self.copying -= n as u64; - return Ok(n); - } - if let Some(mut st) = self.sparse.take() { - match self.read_sparse(&mut st, buffer)? { - Some(n) => { - self.sparse = Some(st); - return Ok(n); - } - None => continue, - } - } - if self.done { - return Ok(0); - } - self.next_entry()?; - } - } -} - -#[derive(Default)] -struct PaxMeta { - path: Option, - linkpath: Option, - has_sparse: bool, - sparse_major: Option, - sparse_minor: Option, - sparse_name: Option, - sparse_realsize: Option, - sparse_chunks: Vec<(u64, u64)>, -} - -fn walk_pax_records( - body: &[u8], - mut visit: impl FnMut(&[u8], &[u8], &[u8]) -> io::Result<()>, -) -> io::Result { - let mut rest = body; - while !rest.is_empty() { - let Some(space) = rest.iter().position(|b| *b == b' ') else { - return Ok(false); - }; - let Some(length) = std::str::from_utf8(&rest[..space]) - .ok() - .and_then(|s| s.parse::().ok()) - .filter(|len| *len > space + 1 && *len <= rest.len()) - else { - return Ok(false); - }; - let record = &rest[space + 1..length]; - let record = record.strip_suffix(b"\n").unwrap_or(record); - let (key, val) = match record.iter().position(|b| *b == b'=') { - Some(eq) => (&record[..eq], &record[eq + 1..]), - None => (record, &b""[..]), - }; - visit(&rest[..length], key, val)?; - rest = &rest[length..]; - } - Ok(true) -} - -impl PaxMeta { - fn push_chunk(&mut self, off: u64, len: u64, entry_size: u64) -> io::Result<()> { - if len > 0 { - if (self.sparse_chunks.len() as u64) >= entry_size.min(SPARSE_CHUNKS_MAX as u64) { - return Err(invalid( - "PAX sparse chunk count exceeds entry size or limit", - )); - } - self.sparse_chunks.push((off, len)); - } - Ok(()) - } - - fn parse_pending( - &mut self, - pending: &[([u8; BLOCK], Vec)], - ustar_size: u64, - ustar_padded: u64, - flag: u8, - ) -> io::Result<(u64, u64)> { - if !pending.iter().any(|(h, _)| h[156] == b'x') { - return Ok((ustar_size, ustar_padded)); - } - let mut pax_size: Option = None; - let mut pax_size_bad = false; - let mut has_sparse = false; - let mut bodies = Vec::new(); - for (ext_hdr, ext_data) in pending { - if ext_hdr[156] != b'x' { - continue; - } - let ext_size = octal(&ext_hdr[124..136])? as usize; - let body = &ext_data[..ext_size.min(ext_data.len())]; - walk_pax_records(body, |_, key, val| { - if key == b"size" { - let parsed = std::str::from_utf8(val) - .ok() - .and_then(|s| s.trim().parse::().ok()); - pax_size = parsed; - pax_size_bad = parsed.is_none(); - } else if key.starts_with(b"GNU.sparse.") { - has_sparse = true; - } - Ok(()) - })?; - bodies.push(body); - } - if pax_size_bad && (flag == b'S' || has_sparse) { - return Err(invalid("invalid pax size")); - } - let size = pax_size.unwrap_or(ustar_size); - let padded = padded_size(size)?; - for body in bodies { - self.parse_into(body, size)?; - } - Ok((size, padded)) - } - - fn parse_into(&mut self, body: &[u8], entry_size: u64) -> io::Result<()> { - let mut pending_offset: Option = None; - let complete = walk_pax_records(body, |_, key, val| { - let val_str = String::from_utf8_lossy(val); - let parse_u64 = |label: &str| { - val_str - .trim() - .parse::() - .map_err(|_| invalid(&format!("invalid pax {label}"))) - }; - match key { - b"path" => self.path = Some(val_str.into_owned()), - b"linkpath" => self.linkpath = Some(val_str.into_owned()), - b"GNU.sparse.major" => { - self.has_sparse = true; - self.sparse_major = Some(parse_u64("GNU.sparse.major")?); - } - b"GNU.sparse.minor" => { - self.has_sparse = true; - self.sparse_minor = Some(parse_u64("GNU.sparse.minor")?); - } - b"GNU.sparse.name" => { - self.has_sparse = true; - self.sparse_name = Some(val_str.into_owned()); - } - b"GNU.sparse.realsize" | b"GNU.sparse.size" => { - self.has_sparse = true; - self.sparse_realsize = Some(parse_u64("GNU.sparse.realsize")?); - } - b"GNU.sparse.offset" => { - self.has_sparse = true; - pending_offset = Some(parse_u64("GNU.sparse.offset")?); - } - b"GNU.sparse.numbytes" => { - self.has_sparse = true; - let off = pending_offset - .take() - .ok_or_else(|| invalid("GNU.sparse.numbytes without offset"))?; - let len = parse_u64("GNU.sparse.numbytes")?; - self.push_chunk(off, len, entry_size)?; - } - b"GNU.sparse.map" => { - self.has_sparse = true; - let mut parts = val_str.split(',').filter(|s| !s.is_empty()); - while let Some(o_str) = parts.next() { - let l_str = parts - .next() - .ok_or_else(|| invalid("odd item count in GNU.sparse.map"))?; - let off: u64 = o_str - .trim() - .parse() - .map_err(|_| invalid("invalid sparse map offset"))?; - let len: u64 = l_str - .trim() - .parse() - .map_err(|_| invalid("invalid sparse map len"))?; - self.push_chunk(off, len, entry_size)?; - } - } - _ => { - if key.starts_with(b"GNU.sparse.") { - self.has_sparse = true; - } - } - } - Ok(()) - })?; - if !complete && self.has_sparse { - return Err(invalid("malformed PAX record after GNU.sparse.* key")); - } - if pending_offset.is_some() { - return Err(invalid("GNU.sparse.offset without numbytes")); - } - Ok(()) - } -} - -fn validate_sparse_chunks( - chunks: Vec<(u64, u64)>, - realsize: u64, -) -> io::Result<(Vec<(u64, u64)>, u64)> { - let mut prev_end = 0u64; - let mut stored_bytes = 0u64; - let mut valid = Vec::with_capacity(chunks.len()); - for (off, len) in chunks { - if off > realsize { - return Err(invalid("sparse chunk starts past realsize")); - } - if len == 0 { - continue; - } - if off < prev_end { - return Err(invalid("sparse chunks overlap or are out of order")); - } - let end = off - .checked_add(len) - .ok_or_else(|| invalid("sparse chunk end overflow"))?; - if end > realsize { - return Err(invalid("sparse chunk extends past realsize")); - } - stored_bytes = stored_bytes - .checked_add(len) - .ok_or_else(|| invalid("sparse byte count overflow"))?; - prev_end = end; - valid.push((off, len)); - } - Ok((valid, stored_bytes)) -} - -fn emit_sparse_pax_headers( - pending: &mut Vec<([u8; BLOCK], Vec)>, - override_path: Option<&str>, - out: &mut Vec, -) -> io::Result<()> { - let mut wrote_path = false; - let last_pax = pending.iter().rposition(|(h, _)| h[156] == b'x'); - for (idx, (mut ext_hdr, ext_data)) in std::mem::take(pending).into_iter().enumerate() { - if ext_hdr[156] != b'x' { - out.extend_from_slice(&ext_hdr); - out.extend_from_slice(&ext_data); - continue; - } - let size = octal(&ext_hdr[124..136])? as usize; - let body = &ext_data[..size.min(ext_data.len())]; - let mut kept = strip_pax_keys(body, |k| { - k.starts_with(b"GNU.sparse.") - || k == b"size" - || (override_path.is_some() && k == b"path") - })?; - if last_pax == Some(idx) { - if let Some(real_path) = override_path { - kept.extend_from_slice(&pax_kv("path", real_path)); - wrote_path = true; - } - } - if kept.is_empty() { - continue; - } - write_octal(&mut ext_hdr[124..136], kept.len() as u64); - recompute_checksum(&mut ext_hdr); - let padded = kept.len().div_ceil(BLOCK) * BLOCK; - kept.resize(padded, 0); - out.extend_from_slice(&ext_hdr); - out.extend_from_slice(&kept); - } - if let Some(real_path) = override_path.filter(|_| !wrote_path) { - let mut body = pax_kv("path", real_path); - let mut hdr = [0u8; BLOCK]; - hdr[0..11].copy_from_slice(b"PaxHeaders/"); - write_octal(&mut hdr[100..108], 0o644); - write_octal(&mut hdr[124..136], body.len() as u64); - hdr[156] = b'x'; - hdr[257..263].copy_from_slice(b"ustar\0"); - hdr[263..265].copy_from_slice(b"00"); - recompute_checksum(&mut hdr); - let padded = body.len().div_ceil(BLOCK) * BLOCK; - body.resize(padded, 0); - out.extend_from_slice(&hdr); - out.extend_from_slice(&body); - } - Ok(()) -} - -fn pax_kv(key: &str, value: &str) -> Vec { - let body_len = 1 + key.len() + 1 + value.len() + 1; - let mut digits = 1usize; - loop { - let total = digits + body_len; - let d = total.to_string().len(); - if d == digits { - return format!("{total} {key}={value}\n").into_bytes(); - } - digits = d; - } -} - -fn strip_pax_keys(body: &[u8], mut drop_key: impl FnMut(&[u8]) -> bool) -> io::Result> { - let mut kept = Vec::new(); - walk_pax_records(body, |raw, key, _| { - if !drop_key(key) { - kept.extend_from_slice(raw); - } - Ok(()) - })?; - Ok(kept) -} - -/// A header's name: ustar `prefix/name`, or the name alone. -fn ustar_name(header: &[u8; BLOCK]) -> String { - let name = text(&header[0..100]); - if &header[257..263] == b"ustar\0" { - let prefix = text(&header[345..500]); - if !prefix.is_empty() { - return format!("{prefix}/{name}"); - } - } - name -} - -/// Bytes up to the first NUL, as text. -fn text(field: &[u8]) -> String { - let end = field.iter().position(|b| *b == 0).unwrap_or(field.len()); - String::from_utf8_lossy(&field[..end]).into_owned() -} - -/// An octal header number, or GNU's base-256 form. -fn octal(field: &[u8]) -> io::Result { - if field[0] & 0x80 != 0 { - let mut n: u64 = u64::from(field[0] & 0x7f); - for b in &field[1..] { - n = n - .checked_mul(256) - .and_then(|n| n.checked_add(u64::from(*b))) - .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "tar size"))?; - } - return Ok(n); - } - let digits: String = field - .iter() - .take_while(|b| **b != 0) - .map(|b| *b as char) - .collect(); - let digits = digits.trim(); - if digits.is_empty() { - return Ok(0); - } - u64::from_str_radix(digits, 8) - .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "tar header number")) -} - -/// Drops `mtime`, `atime`, and `ctime` records from a pax extended header -/// block (`flag == b'x'`), rebuilding its header and padded body only if any -/// time record was removed. Returns `None` when no records remain. -fn strip_pax_times( - mut header: [u8; BLOCK], - data: Vec, -) -> io::Result)>> { - let size = octal(&header[124..136])? as usize; - let body = &data[..size.min(data.len())]; - let Some(mut kept) = filter_pax_records(body) else { - return Ok(Some((header, data))); - }; - if kept.is_empty() { - return Ok(None); - } - write_octal(&mut header[124..136], kept.len() as u64); - recompute_checksum(&mut header); - let padded = kept.len().div_ceil(BLOCK) * BLOCK; - kept.resize(padded, 0); - Ok(Some((header, kept))) -} - -/// Filters `mtime`, `atime`, and `ctime` records out of a pax extended header -/// body; returns `None` when no time record was present or parsing fails. -fn filter_pax_records(body: &[u8]) -> Option> { - let mut kept = Vec::new(); - let mut changed = false; - let complete = walk_pax_records(body, |raw, key, _| { - if matches!(key, b"mtime" | b"atime" | b"ctime") { - changed = true; - } else { - kept.extend_from_slice(raw); - } - Ok(()) - }) - .ok()?; - (complete && changed).then_some(kept) -} - -fn write_size_field(field: &mut [u8], value: u64) -> io::Result<()> { - if value <= 0o77_777_777_777 { - write_octal(field, value); - return Ok(()); - } - if field.len() != 12 { - return Err(io::Error::new(io::ErrorKind::InvalidData, "tar size field")); - } - let be = value.to_be_bytes(); - field[0] = 0x80; - field[1..4].fill(0); - field[4..12].copy_from_slice(&be); - Ok(()) -} - -fn write_octal(field: &mut [u8], value: u64) { - let width = field.len() - 1; - let text = format!("{value:0width$o}\0"); - field.copy_from_slice(&text.as_bytes()[..field.len()]); -} - -fn recompute_checksum(header: &mut [u8; BLOCK]) { - header[148..156].fill(b' '); - let sum: u64 = header.iter().map(|b| u64::from(*b)).sum(); - let text = format!("{sum:06o}\0 "); - header[148..156].copy_from_slice(text.as_bytes()); -} diff --git a/control/crates/layerfs-sandbox/src/image_tar/filter.rs b/control/crates/layerfs-sandbox/src/image_tar/filter.rs new file mode 100644 index 000000000..1ade3dfb0 --- /dev/null +++ b/control/crates/layerfs-sandbox/src/image_tar/filter.rs @@ -0,0 +1,351 @@ +//! Streaming tar entry filter (`Filtered`) and filter report (`TarReport`), +//! structured in three phases: +//! 1. Extended-header accumulation and size-independent validation (`x`, `L`, `K`, `g`). +//! 2. Entry-header resolution, entry-size-bounded descriptor construction, and checks. +//! 3. Archive end-block / clean EOF termination and streaming payload output. + +use std::collections::HashSet; +use std::io::{self, Read}; + +use super::header::{ + invalid, octal, padded_size, recompute_checksum, text, ustar_name, write_size_field, + zero_header_mtime, BLOCK, +}; +use super::pax::PendingHeaders; +use super::sparse::{ + read_block, read_gnu_sparse_map, read_pax1_sparse_map, skip_bytes, validate_sparse_chunks, + SparseStream, +}; + +/// Maximum logical expanded size (`realsize` and cumulative sparse output) permitted. +pub const SPARSE_MAX: u64 = 16 << 30; + +/// Paths the init layer of `docker create` adds or replaces. +const INIT_FILES: [&str; 5] = [ + ".dockerenv", + "etc/hosts", + "etc/hostname", + "etc/resolv.conf", + "etc/mtab", +]; + +fn clean_path(path: &str) -> String { + path.trim_start_matches("./") + .trim_start_matches('/') + .trim_end_matches('/') + .to_owned() +} + +/// Whether an entry at `path` of type `flag` is left out of the copy. +pub fn dropped(path: &str, flag: u8) -> bool { + let path = path.trim_start_matches("./").trim_start_matches('/'); + let path = path.trim_end_matches('/'); + matches!(flag, b'3' | b'4' | b'6') + || INIT_FILES.contains(&path) + || path + .strip_prefix("dev/") + .is_some_and(|rest| !rest.is_empty()) +} + +/// One sparse tar entry expanded into a regular file (`b'0'`). +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct SparseReport { + /// Entry path with `./` and leading `/` removed. + pub path: String, + /// Expanded logical size in bytes. + pub expanded_bytes: u64, + /// Stored sparse payload bytes read from the source tar. + pub stored_bytes: u64, +} + +/// Report of dropped entries and expanded sparse files seen while filtering. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct TarReport { + /// Paths of dropped FIFO (`b'6'`) entries. + pub fifos: Vec, + /// Paths of dropped character/block device (`b'3'`, `b'4'`) entries. + pub devices: Vec, + /// Paths of dropped container init entries (`.dockerenv`, `/etc/hosts`, `dev/*`, ...). + pub init: Vec, + /// Details of every sparse entry expanded while streaming. + pub sparse_files: Vec, + /// Total expanded logical bytes across all sparse entries. + pub sparse_expanded_bytes: u64, +} + +impl TarReport { + /// Number of dropped FIFO entries. + pub fn fifo_count(&self) -> usize { + self.fifos.len() + } + + /// Number of dropped device entries. + pub fn device_count(&self) -> usize { + self.devices.len() + } + + /// Number of dropped init/runtime entries. + pub fn init_count(&self) -> usize { + self.init.len() + } +} + +/// A reader of `input` (a tar stream) that yields the same tar without the +/// [`dropped`] entries and with sparse entries expanded to regular files. +pub struct Filtered { + input: R, + /// Bytes ready to hand out. + out: Vec, + at: usize, + /// Bytes of the current kept entry's data (with padding) still to copy. + copying: u64, + sparse: Option, + sparse_max: u64, + dropped_paths: HashSet, + report: TarReport, + done: bool, +} + +impl Filtered { + /// Filters `input`. + pub fn new(input: R) -> Self { + Self { + input, + out: Vec::new(), + at: 0, + copying: 0, + sparse: None, + sparse_max: SPARSE_MAX, + dropped_paths: HashSet::new(), + report: TarReport::default(), + done: false, + } + } + + /// Sets the maximum expanded sparse byte budget (per entry and cumulative). + pub fn with_sparse_max(mut self, max: u64) -> Self { + self.sparse_max = max; + self + } + + /// Report of entries dropped or sparse files expanded so far. + pub fn report(&self) -> &TarReport { + &self.report + } + + /// Consumes the filter and returns its [`TarReport`]. + pub fn into_report(self) -> TarReport { + self.report + } + + /// Decides the next entry: fills `out` with its headers when it is kept + /// (its data then follows through `copying` or `sparse`), or skips it. + fn next_entry(&mut self) -> io::Result<()> { + let mut pending = PendingHeaders::default(); + + // Stage 1 & Stage 3: consume extended headers (`x`, `L`, `K`, `g`), + // running size-independent validation and caps on arrival, until + // either archive end / clean EOF (Stage 3) or a real entry header. + let (mut header, ustar_size, ustar_padded, flag) = loop { + let mut header = [0u8; BLOCK]; + if !read_block(&mut self.input, &mut header)? { + // Stage 3a: clean EOF without end blocks (any bad sparse PAX in + // `pending` already errored during Stage 1). + self.out.extend_from_slice(&[0u8; BLOCK * 2]); + self.done = true; + return Ok(()); + } + if header.iter().all(|b| *b == 0) { + // Stage 3b: two zero end blocks, nothing after (any bad sparse + // PAX in `pending` already errored during Stage 1). + self.out.extend_from_slice(&[0u8; BLOCK * 2]); + self.done = true; + return Ok(()); + } + let size = octal(&header[124..136])?; + let padded = padded_size(size)?; + let flag = header[156]; + if matches!(flag, b'x' | b'L' | b'K' | b'g') { + pending.admit_header(padded)?; + let mut data = vec![0u8; padded as usize]; + if !read_block(&mut self.input, &mut data)? { + return Err(io::Error::new( + io::ErrorKind::UnexpectedEof, + "unexpected EOF inside extended tar header", + )); + } + pending.push(header, data, size)?; + continue; + } + break (header, size, padded, flag); + }; + + // Stage 2: entry header arrived — effective entry size is now known. + let (size, padded) = pending.resolve_entry_size(ustar_size, ustar_padded, flag)?; + pending.ensure_chunk_count_within(size)?; + let gnu_chunks = if flag == b'S' { + Some(read_gnu_sparse_map(&mut self.input, &header, size)?) + } else { + None + }; + + let pax_path = pending.pax.path.take(); + let pax_link = pending.pax.linkpath.take(); + let sparse_name = pending.pax.sparse_name.take(); + let path = sparse_name + .clone() + .or(pax_path) + .or_else(|| pending.long_name.take()) + .unwrap_or_else(|| ustar_name(&header)); + // A link or directory carries no data, whatever its size says. + let data = if matches!(flag, b'1' | b'2' | b'3' | b'4' | b'5' | b'6') { + 0 + } else { + padded + }; + + if dropped(&path, flag) { + let norm = clean_path(&path); + if matches!(flag, b'6') { + self.report.fifos.push(norm.clone()); + } else if matches!(flag, b'3' | b'4') { + self.report.devices.push(norm.clone()); + } else { + self.report.init.push(norm.clone()); + } + self.dropped_paths.insert(norm); + return skip_bytes(&mut self.input, data); + } + + if flag == b'1' { + let link_target = pax_link + .or_else(|| pending.long_link.take()) + .unwrap_or_else(|| text(&header[157..257])); + let target_norm = clean_path(&link_target); + if self.dropped_paths.contains(&target_norm) || dropped(&target_norm, b'0') { + let entry_norm = clean_path(&path); + return Err(invalid(format!( + "hardlink `{entry_norm}` points to dropped target `{target_norm}`" + ))); + } + } + + let is_sparse = flag == b'S' || (matches!(flag, b'0' | b'\0') && pending.pax.has_sparse); + if is_sparse { + let realsize = if flag == b'S' { + pending + .pax + .sparse_realsize + .unwrap_or(octal(&header[483..495])?) + } else { + pending + .pax + .sparse_realsize + .ok_or_else(|| invalid("PAX sparse file missing realsize"))? + }; + if realsize > self.sparse_max + || self + .report + .sparse_expanded_bytes + .checked_add(realsize) + .is_none_or(|total| total > self.sparse_max) + { + return Err(invalid("sparse entry realsize exceeds maximum")); + } + let (raw_chunks, map_bytes) = + if pending.pax.sparse_major == Some(1) && pending.pax.sparse_minor == Some(0) { + read_pax1_sparse_map(&mut self.input, size)? + } else if let Some(chunks) = gnu_chunks { + (chunks, 0) + } else { + (pending.collect_sparse_chunks(size)?, 0) + }; + let (chunks, stored_bytes) = validate_sparse_chunks(raw_chunks, realsize)?; + let payload_needed = map_bytes + .checked_add(stored_bytes) + .ok_or_else(|| invalid("sparse payload overflow"))?; + if payload_needed != size { + return Err(invalid("sparse payload size does not match tar entry size")); + } + let input_skip = padded - payload_needed; + pending.emit_for_sparse(sparse_name.as_deref(), &mut self.out)?; + let is_oldgnu = flag == b'S' || &header[257..263] == b"ustar "; + header[156] = b'0'; + if is_oldgnu { + header[257..263].copy_from_slice(b"ustar\0"); + header[263..265].copy_from_slice(b"00"); + header[329..512].fill(0); + } + write_size_field(&mut header[124..136], realsize)?; + recompute_checksum(&mut header); + self.out.extend_from_slice(&header); + self.report.sparse_files.push(SparseReport { + path: clean_path(&path), + expanded_bytes: realsize, + stored_bytes, + }); + self.report.sparse_expanded_bytes = + self.report.sparse_expanded_bytes.saturating_add(realsize); + let out_pad = (BLOCK as u64 - (realsize % BLOCK as u64)) % BLOCK as u64; + if realsize == 0 { + skip_bytes(&mut self.input, input_skip)?; + return Ok(()); + } + self.sparse = Some(SparseStream::new(chunks, realsize, out_pad, input_skip)); + return Ok(()); + } + + if flag == b'5' { + pending.emit_for_directory(&mut self.out)?; + // `docker create`'s init layer touches directories such as `dev/` + // and `etc/` at container creation time; normalize every kept + // directory's mtime so exports >=2 s apart stay byte-identical. + zero_header_mtime(&mut header); + } else { + pending.emit_passthrough(&mut self.out); + } + self.out.extend_from_slice(&header); + self.copying = data; + Ok(()) + } +} + +impl Read for Filtered { + fn read(&mut self, buffer: &mut [u8]) -> io::Result { + loop { + if self.at < self.out.len() { + let n = (self.out.len() - self.at).min(buffer.len()); + buffer[..n].copy_from_slice(&self.out[self.at..self.at + n]); + self.at += n; + return Ok(n); + } + self.out.clear(); + self.at = 0; + if buffer.is_empty() { + return Ok(0); + } + if self.copying > 0 { + let wanted = (buffer.len() as u64).min(self.copying) as usize; + let n = self.input.read(&mut buffer[..wanted])?; + if n == 0 { + return Err(io::ErrorKind::UnexpectedEof.into()); + } + self.copying -= n as u64; + return Ok(n); + } + if let Some(mut st) = self.sparse.take() { + match st.read_chunk(&mut self.input, buffer)? { + Some(n) => { + self.sparse = Some(st); + return Ok(n); + } + None => continue, + } + } + if self.done { + return Ok(0); + } + self.next_entry()?; + } + } +} diff --git a/control/crates/layerfs-sandbox/src/image_tar/header.rs b/control/crates/layerfs-sandbox/src/image_tar/header.rs new file mode 100644 index 000000000..d0d5f75b1 --- /dev/null +++ b/control/crates/layerfs-sandbox/src/image_tar/header.rs @@ -0,0 +1,90 @@ +//! 512-byte ustar/GNU tar header parsing, alignment, and checksum helpers. + +use std::io; + +pub(super) const BLOCK: usize = 512; + +pub(super) fn invalid(msg: impl Into) -> io::Error { + io::Error::new(io::ErrorKind::InvalidData, msg.into()) +} + +pub(super) fn padded_size(size: u64) -> io::Result { + size.div_ceil(BLOCK as u64) + .checked_mul(BLOCK as u64) + .ok_or_else(|| invalid("tar entry size overflow")) +} + +/// A header's name: ustar `prefix/name`, or the name alone. +pub(super) fn ustar_name(header: &[u8; BLOCK]) -> String { + let name = text(&header[0..100]); + if &header[257..263] == b"ustar\0" { + let prefix = text(&header[345..500]); + if !prefix.is_empty() { + return format!("{prefix}/{name}"); + } + } + name +} + +/// Bytes up to the first NUL, as text. +pub(super) fn text(field: &[u8]) -> String { + let end = field.iter().position(|b| *b == 0).unwrap_or(field.len()); + String::from_utf8_lossy(&field[..end]).into_owned() +} + +/// An octal header number, or GNU's base-256 form. +pub(super) fn octal(field: &[u8]) -> io::Result { + if field[0] & 0x80 != 0 { + let mut n: u64 = u64::from(field[0] & 0x7f); + for b in &field[1..] { + n = n + .checked_mul(256) + .and_then(|n| n.checked_add(u64::from(*b))) + .ok_or_else(|| invalid("tar size"))?; + } + return Ok(n); + } + let digits: String = field + .iter() + .take_while(|b| **b != 0) + .map(|b| *b as char) + .collect(); + let digits = digits.trim(); + if digits.is_empty() { + return Ok(0); + } + u64::from_str_radix(digits, 8).map_err(|_| invalid("tar header number")) +} + +pub(super) fn write_size_field(field: &mut [u8], value: u64) -> io::Result<()> { + if value <= 0o77_777_777_777 { + write_octal(field, value); + return Ok(()); + } + if field.len() != 12 { + return Err(invalid("tar size field")); + } + let be = value.to_be_bytes(); + field[0] = 0x80; + field[1..4].fill(0); + field[4..12].copy_from_slice(&be); + Ok(()) +} + +pub(super) fn write_octal(field: &mut [u8], value: u64) { + let width = field.len() - 1; + let text = format!("{value:0width$o}\0"); + field.copy_from_slice(&text.as_bytes()[..field.len()]); +} + +pub(super) fn recompute_checksum(header: &mut [u8; BLOCK]) { + header[148..156].fill(b' '); + let sum: u64 = header.iter().map(|b| u64::from(*b)).sum(); + let text = format!("{sum:06o}\0 "); + header[148..156].copy_from_slice(text.as_bytes()); +} + +pub(super) fn zero_header_mtime(header: &mut [u8; BLOCK]) { + header[136..148].copy_from_slice(b"00000000000\0"); + recompute_checksum(header); +} diff --git a/control/crates/layerfs-sandbox/src/image_tar/mod.rs b/control/crates/layerfs-sandbox/src/image_tar/mod.rs new file mode 100644 index 000000000..53682fdf4 --- /dev/null +++ b/control/crates/layerfs-sandbox/src/image_tar/mod.rs @@ -0,0 +1,18 @@ +//! The flat root filesystem tar a Sandbox image is copied as: `docker +//! export`'s output with the files `docker create`'s init layer adds taken +//! out (`.dockerenv`, `etc/hosts`, `etc/hostname`, `etc/resolv.conf`, +//! `etc/mtab`, everything under `dev/`), every device node and FIFO (which +//! the unpacker refuses), hardlinks targeting dropped entries refused clearly, +//! sparse entries expanded to regular files, and directory modification times +//! normalized to 0 with recomputed header checksums. Those are the bytes that +//! differ between two exports of one image; what is left is the image's own +//! tree. The filter streams: it holds at most one entry's extended headers and +//! sparse chunk map, never a file's bytes. + +mod filter; +mod header; +mod pax; +mod sparse; + +pub use filter::{dropped, Filtered, SparseReport, TarReport, SPARSE_MAX}; +pub use pax::EXTENDED_TOTAL_MAX; diff --git a/control/crates/layerfs-sandbox/src/image_tar/pax.rs b/control/crates/layerfs-sandbox/src/image_tar/pax.rs new file mode 100644 index 000000000..8facf1f51 --- /dev/null +++ b/control/crates/layerfs-sandbox/src/image_tar/pax.rs @@ -0,0 +1,466 @@ +//! PAX and GNU extended header accumulation, Stage-1 size-independent +//! validation, Stage-2 entry-sized descriptor extraction, and header emission. + +use std::io; + +use super::header::{ + invalid, octal, padded_size, recompute_checksum, text, write_octal, zero_header_mtime, BLOCK, +}; + +/// The largest single pax or GNU extended header kept while its entry is decided. +pub(super) const EXTENDED_MAX: u64 = 1 << 20; +/// Maximum total bytes (`512 + padded` per header) buffered across all extended +/// headers (`x`, `L`, `K`, `g`) of a single tar entry. +/// +/// 16 MiB accommodates deep container paths/linkpaths plus large `SCHILY.xattr.*` +/// sets while bounding buffered memory on header floods (even zero-length `x` +/// headers) and exceeding the ~10 MiB PAX text of `SPARSE_CHUNKS_MAX` descriptors. +pub const EXTENDED_TOTAL_MAX: u64 = 16 << 20; +/// Hard cap on parsed sparse chunk descriptors across extended headers. +pub(super) const SPARSE_CHUNKS_MAX: usize = 1 << 20; + +#[derive(Default)] +pub(super) struct PaxScan { + pub(super) path: Option, + pub(super) linkpath: Option, + pub(super) pax_size: Option, + pub(super) pax_size_bad: bool, + pub(super) saw_malformed: bool, + pub(super) has_sparse: bool, + pub(super) sparse_major: Option, + pub(super) sparse_minor: Option, + pub(super) sparse_name: Option, + pub(super) sparse_realsize: Option, + pub(super) sparse_chunk_count: usize, +} + +#[derive(Default)] +pub(super) struct PendingHeaders { + raw: Vec<([u8; BLOCK], Vec)>, + total_bytes: u64, + pub(super) long_name: Option, + pub(super) long_link: Option, + pub(super) pax: PaxScan, +} + +impl PendingHeaders { + /// Stage 1 admission check: enforces per-header 1 MiB and per-entry 16 MiB + /// extended-header budgets before allocating the extended header payload. + pub(super) fn admit_header(&mut self, padded: u64) -> io::Result<()> { + if padded > EXTENDED_MAX { + return Err(invalid("the image tar has an extended header over 1 MiB")); + } + let next = self + .total_bytes + .checked_add((BLOCK as u64) + padded) + .ok_or_else(|| invalid("the image tar extended headers exceed 16 MiB"))?; + if next > EXTENDED_TOTAL_MAX { + return Err(invalid("the image tar extended headers exceed 16 MiB")); + } + self.total_bytes = next; + Ok(()) + } + + /// Stage 1 ingestion: runs size-independent PAX/sparse validation immediately + /// as each extended header arrives, without building chunk tables yet. + pub(super) fn push(&mut self, header: [u8; BLOCK], data: Vec, size: u64) -> io::Result<()> { + let body = &data[..size as usize]; + match header[156] { + b'x' => self.pax.scan_header(body)?, + b'L' => self.long_name = Some(text(body)), + b'K' => self.long_link = Some(text(body)), + _ => {} + } + self.raw.push((header, data)); + Ok(()) + } + + /// Stage 2 entry size resolution: applies PAX `size` when present (ignoring + /// bad PAX `size` on plain entries, matching baseline) and checks 512B padding. + pub(super) fn resolve_entry_size( + &self, + ustar_size: u64, + ustar_padded: u64, + flag: u8, + ) -> io::Result<(u64, u64)> { + if self.pax.pax_size_bad && (flag == b'S' || self.pax.has_sparse) { + return Err(invalid("invalid pax size")); + } + match self.pax.pax_size { + Some(sz) => Ok((sz, padded_size(sz)?)), + None => Ok((ustar_size, ustar_padded)), + } + } + + /// Stage 2 chunk budget check: verifies the cross-header descriptor count + /// fits within `min(entry_size, SPARSE_CHUNKS_MAX)` once entry size is known. + pub(super) fn ensure_chunk_count_within(&self, entry_size: u64) -> io::Result<()> { + if (self.pax.sparse_chunk_count as u64) > entry_size.min(SPARSE_CHUNKS_MAX as u64) { + return Err(invalid( + "PAX sparse chunk count exceeds entry size or limit", + )); + } + Ok(()) + } + + /// Stage 2 descriptor materialization: extracts validated `(offset, len)` + /// descriptors from buffered `x` headers, bounded by `min(entry_size, SPARSE_CHUNKS_MAX)`. + pub(super) fn collect_sparse_chunks(&self, entry_size: u64) -> io::Result> { + self.ensure_chunk_count_within(entry_size)?; + let limit = entry_size.min(SPARSE_CHUNKS_MAX as u64); + let mut chunks = Vec::with_capacity(self.pax.sparse_chunk_count); + for (ext_hdr, ext_data) in &self.raw { + if ext_hdr[156] != b'x' { + continue; + } + let ext_size = octal(&ext_hdr[124..136])? as usize; + let body = &ext_data[..ext_size.min(ext_data.len())]; + let mut pending_offset: Option = None; + walk_pax_records(body, |_, key, val| { + let val_str = String::from_utf8_lossy(val); + match key { + b"GNU.sparse.offset" => { + pending_offset = Some( + val_str + .trim() + .parse::() + .map_err(|_| invalid("invalid pax GNU.sparse.offset"))?, + ); + } + b"GNU.sparse.numbytes" => { + let off = pending_offset + .take() + .ok_or_else(|| invalid("GNU.sparse.numbytes without offset"))?; + let len = val_str + .trim() + .parse::() + .map_err(|_| invalid("invalid pax GNU.sparse.numbytes"))?; + push_chunk(&mut chunks, off, len, limit)?; + } + b"GNU.sparse.map" => { + let mut parts = val_str.split(',').filter(|s| !s.is_empty()); + while let Some(o_str) = parts.next() { + let l_str = parts + .next() + .ok_or_else(|| invalid("odd item count in GNU.sparse.map"))?; + let off: u64 = o_str + .trim() + .parse() + .map_err(|_| invalid("invalid sparse map offset"))?; + let len: u64 = l_str + .trim() + .parse() + .map_err(|_| invalid("invalid sparse map len"))?; + push_chunk(&mut chunks, off, len, limit)?; + } + } + _ => {} + } + Ok(()) + })?; + } + Ok(chunks) + } + + pub(super) fn emit_for_sparse( + &mut self, + override_path: Option<&str>, + out: &mut Vec, + ) -> io::Result<()> { + let mut wrote_path = false; + let last_pax = self.raw.iter().rposition(|(h, _)| h[156] == b'x'); + for (idx, (mut ext_hdr, ext_data)) in std::mem::take(&mut self.raw).into_iter().enumerate() + { + if ext_hdr[156] != b'x' { + out.extend_from_slice(&ext_hdr); + out.extend_from_slice(&ext_data); + continue; + } + let size = octal(&ext_hdr[124..136])? as usize; + let body = &ext_data[..size.min(ext_data.len())]; + let mut kept = strip_pax_keys(body, |k| { + k.starts_with(b"GNU.sparse.") + || k == b"size" + || (override_path.is_some() && k == b"path") + })?; + if last_pax == Some(idx) { + if let Some(real_path) = override_path { + kept.extend_from_slice(&pax_kv("path", real_path)); + wrote_path = true; + } + } + if kept.is_empty() { + continue; + } + write_octal(&mut ext_hdr[124..136], kept.len() as u64); + recompute_checksum(&mut ext_hdr); + let padded = kept.len().div_ceil(BLOCK) * BLOCK; + kept.resize(padded, 0); + out.extend_from_slice(&ext_hdr); + out.extend_from_slice(&kept); + } + if let Some(real_path) = override_path.filter(|_| !wrote_path) { + let mut body = pax_kv("path", real_path); + let mut hdr = [0u8; BLOCK]; + hdr[0..11].copy_from_slice(b"PaxHeaders/"); + write_octal(&mut hdr[100..108], 0o644); + write_octal(&mut hdr[124..136], body.len() as u64); + hdr[156] = b'x'; + hdr[257..263].copy_from_slice(b"ustar\0"); + hdr[263..265].copy_from_slice(b"00"); + recompute_checksum(&mut hdr); + let padded = body.len().div_ceil(BLOCK) * BLOCK; + body.resize(padded, 0); + out.extend_from_slice(&hdr); + out.extend_from_slice(&body); + } + Ok(()) + } + + pub(super) fn emit_for_directory(self, out: &mut Vec) -> io::Result<()> { + for (mut ext_hdr, ext_data) in self.raw { + if ext_hdr[156] == b'x' { + if let Some((mut h, d)) = strip_pax_times(ext_hdr, ext_data)? { + zero_header_mtime(&mut h); + out.extend_from_slice(&h); + out.extend_from_slice(&d); + } + } else { + if matches!(ext_hdr[156], b'L' | b'K') { + zero_header_mtime(&mut ext_hdr); + } + out.extend_from_slice(&ext_hdr); + out.extend_from_slice(&ext_data); + } + } + Ok(()) + } + + pub(super) fn emit_passthrough(self, out: &mut Vec) { + for (ext_hdr, ext_data) in self.raw { + out.extend_from_slice(&ext_hdr); + out.extend_from_slice(&ext_data); + } + } +} + +impl PaxScan { + fn count_chunk(&mut self, len: u64) -> io::Result<()> { + if len > 0 { + if self.sparse_chunk_count >= SPARSE_CHUNKS_MAX { + return Err(invalid( + "PAX sparse chunk count exceeds entry size or limit", + )); + } + self.sparse_chunk_count += 1; + } + Ok(()) + } + + /// Scans one local `x` PAX header body in Stage 1: parses `path`/`linkpath`, + /// validates sparse syntax/numbers/pairing, counts non-zero descriptors + /// against `SPARSE_CHUNKS_MAX`, and records `size` without propagating plain + /// entry `size` parse failures. + fn scan_header(&mut self, body: &[u8]) -> io::Result<()> { + let mut pending_offset: Option = None; + let complete = walk_pax_records(body, |_, key, val| { + let val_str = String::from_utf8_lossy(val); + let parse_u64 = |label: &str| { + val_str + .trim() + .parse::() + .map_err(|_| invalid(format!("invalid pax {label}"))) + }; + match key { + b"path" => self.path = Some(val_str.into_owned()), + b"linkpath" => self.linkpath = Some(val_str.into_owned()), + b"size" => match val_str.trim().parse::() { + Ok(sz) => { + self.pax_size = Some(sz); + self.pax_size_bad = false; + } + Err(_) => { + self.pax_size = None; + self.pax_size_bad = true; + } + }, + b"GNU.sparse.major" => { + self.has_sparse = true; + self.sparse_major = Some(parse_u64("GNU.sparse.major")?); + } + b"GNU.sparse.minor" => { + self.has_sparse = true; + self.sparse_minor = Some(parse_u64("GNU.sparse.minor")?); + } + b"GNU.sparse.name" => { + self.has_sparse = true; + self.sparse_name = Some(val_str.into_owned()); + } + b"GNU.sparse.realsize" | b"GNU.sparse.size" => { + self.has_sparse = true; + self.sparse_realsize = Some(parse_u64("GNU.sparse.realsize")?); + } + b"GNU.sparse.offset" => { + self.has_sparse = true; + if pending_offset.is_some() { + return Err(invalid("GNU.sparse.offset without numbytes")); + } + pending_offset = Some(parse_u64("GNU.sparse.offset")?); + } + b"GNU.sparse.numbytes" => { + self.has_sparse = true; + let _off = pending_offset + .take() + .ok_or_else(|| invalid("GNU.sparse.numbytes without offset"))?; + let len = parse_u64("GNU.sparse.numbytes")?; + self.count_chunk(len)?; + } + b"GNU.sparse.map" => { + self.has_sparse = true; + let mut parts = val_str.split(',').filter(|s| !s.is_empty()); + while let Some(o_str) = parts.next() { + let l_str = parts + .next() + .ok_or_else(|| invalid("odd item count in GNU.sparse.map"))?; + let _off: u64 = o_str + .trim() + .parse() + .map_err(|_| invalid("invalid sparse map offset"))?; + let len: u64 = l_str + .trim() + .parse() + .map_err(|_| invalid("invalid sparse map len"))?; + self.count_chunk(len)?; + } + } + _ => { + if key.starts_with(b"GNU.sparse.") { + self.has_sparse = true; + } + } + } + Ok(()) + })?; + if !complete { + self.saw_malformed = true; + } + if self.has_sparse && self.saw_malformed { + return Err(invalid("malformed PAX record after GNU.sparse.* key")); + } + if pending_offset.is_some() { + return Err(invalid("GNU.sparse.offset without numbytes")); + } + if self.has_sparse && self.pax_size_bad { + return Err(invalid("invalid pax size")); + } + if self.has_sparse { + if let Some(sz) = self.pax_size { + padded_size(sz)?; + } + } + Ok(()) + } +} + +fn push_chunk(chunks: &mut Vec<(u64, u64)>, off: u64, len: u64, limit: u64) -> io::Result<()> { + if len > 0 { + if (chunks.len() as u64) >= limit { + return Err(invalid( + "PAX sparse chunk count exceeds entry size or limit", + )); + } + chunks.push((off, len)); + } + Ok(()) +} + +fn walk_pax_records( + body: &[u8], + mut visit: impl FnMut(&[u8], &[u8], &[u8]) -> io::Result<()>, +) -> io::Result { + let mut rest = body; + while !rest.is_empty() { + let Some(space) = rest.iter().position(|b| *b == b' ') else { + return Ok(false); + }; + let Some(length) = std::str::from_utf8(&rest[..space]) + .ok() + .and_then(|s| s.parse::().ok()) + .filter(|len| *len > space + 1 && *len <= rest.len()) + else { + return Ok(false); + }; + let record = &rest[space + 1..length]; + let record = record.strip_suffix(b"\n").unwrap_or(record); + let (key, val) = match record.iter().position(|b| *b == b'=') { + Some(eq) => (&record[..eq], &record[eq + 1..]), + None => (record, &b""[..]), + }; + visit(&rest[..length], key, val)?; + rest = &rest[length..]; + } + Ok(true) +} + +fn pax_kv(key: &str, value: &str) -> Vec { + let body_len = 1 + key.len() + 1 + value.len() + 1; + let mut digits = 1usize; + loop { + let total = digits + body_len; + let d = total.to_string().len(); + if d == digits { + return format!("{total} {key}={value}\n").into_bytes(); + } + digits = d; + } +} + +fn strip_pax_keys(body: &[u8], mut drop_key: impl FnMut(&[u8]) -> bool) -> io::Result> { + let mut kept = Vec::new(); + walk_pax_records(body, |raw, key, _| { + if !drop_key(key) { + kept.extend_from_slice(raw); + } + Ok(()) + })?; + Ok(kept) +} + +/// Drops `mtime`, `atime`, and `ctime` records from a pax extended header +/// block (`flag == b'x'`), rebuilding its header and padded body only if any +/// time record was removed. Returns `None` when no records remain. +fn strip_pax_times( + mut header: [u8; BLOCK], + data: Vec, +) -> io::Result)>> { + let size = octal(&header[124..136])? as usize; + let body = &data[..size.min(data.len())]; + let Some(mut kept) = filter_pax_records(body) else { + return Ok(Some((header, data))); + }; + if kept.is_empty() { + return Ok(None); + } + write_octal(&mut header[124..136], kept.len() as u64); + recompute_checksum(&mut header); + let padded = kept.len().div_ceil(BLOCK) * BLOCK; + kept.resize(padded, 0); + Ok(Some((header, kept))) +} + +/// Filters `mtime`, `atime`, and `ctime` records out of a pax extended header +/// body; returns `None` when no time record was present or parsing fails. +fn filter_pax_records(body: &[u8]) -> Option> { + let mut kept = Vec::new(); + let mut changed = false; + let complete = walk_pax_records(body, |raw, key, _| { + if matches!(key, b"mtime" | b"atime" | b"ctime") { + changed = true; + } else { + kept.extend_from_slice(raw); + } + Ok(()) + }) + .ok()?; + (complete && changed).then_some(kept) +} diff --git a/control/crates/layerfs-sandbox/src/image_tar/sparse.rs b/control/crates/layerfs-sandbox/src/image_tar/sparse.rs new file mode 100644 index 000000000..a30e30d91 --- /dev/null +++ b/control/crates/layerfs-sandbox/src/image_tar/sparse.rs @@ -0,0 +1,285 @@ +//! Sparse map parsing (GNU oldgnu & PAX 1.0), chunk validation, and streaming +//! hole/data expansion. + +use std::io::{self, Read}; + +use super::header::{invalid, octal, BLOCK}; +use super::pax::{EXTENDED_MAX, SPARSE_CHUNKS_MAX}; + +pub(super) struct SparseStream { + pub(super) chunks: Vec<(u64, u64)>, + pub(super) chunk_idx: usize, + /// Stored bytes remaining to copy from the current chunk's input stream. + pub(super) chunk_left: u64, + /// Current logical byte offset emitted into the expanded regular file. + pub(super) pos: u64, + pub(super) realsize: u64, + /// Trailing tar block-alignment zero padding remaining after `realsize`. + pub(super) out_pad: u64, + /// Remaining input padding bytes to discard once all chunks are read. + pub(super) input_skip: u64, +} + +impl SparseStream { + pub(super) fn new( + chunks: Vec<(u64, u64)>, + realsize: u64, + out_pad: u64, + input_skip: u64, + ) -> Self { + Self { + chunks, + chunk_idx: 0, + chunk_left: 0, + pos: 0, + realsize, + out_pad, + input_skip, + } + } + + pub(super) fn read_chunk( + &mut self, + input: &mut R, + buffer: &mut [u8], + ) -> io::Result> { + loop { + if self.chunk_left > 0 { + let want = (buffer.len() as u64).min(self.chunk_left) as usize; + let n = input.read(&mut buffer[..want])?; + if n == 0 { + return Err(io::Error::new( + io::ErrorKind::UnexpectedEof, + "unexpected EOF in sparse tar chunk", + )); + } + self.chunk_left -= n as u64; + self.pos += n as u64; + if self.chunk_left == 0 { + self.chunk_idx += 1; + } + return Ok(Some(n)); + } + if self.pos < self.realsize { + let hole_end = self + .chunks + .get(self.chunk_idx) + .map_or(self.realsize, |(off, _)| *off); + if self.pos < hole_end { + let zeros = (hole_end - self.pos).min(buffer.len() as u64) as usize; + buffer[..zeros].fill(0); + self.pos += zeros as u64; + if self.pos == hole_end { + if let Some((_, len)) = self.chunks.get(self.chunk_idx) { + self.chunk_left = *len; + } + } + return Ok(Some(zeros)); + } + if let Some((_, len)) = self.chunks.get(self.chunk_idx) { + self.chunk_left = *len; + continue; + } + } + let to_skip = std::mem::take(&mut self.input_skip); + if to_skip > 0 { + skip_bytes(input, to_skip)?; + } + if self.out_pad > 0 { + let zeros = self.out_pad.min(buffer.len() as u64) as usize; + buffer[..zeros].fill(0); + self.out_pad -= zeros as u64; + return Ok(Some(zeros)); + } + return Ok(None); + } + } +} + +/// Reads exactly `buffer.len()` bytes, or none at a clean end. +pub(super) fn read_block(input: &mut R, buffer: &mut [u8]) -> io::Result { + let mut read = 0; + while read < buffer.len() { + let n = input.read(&mut buffer[read..])?; + if n == 0 { + if read == 0 { + return Ok(false); + } + return Err(io::Error::new( + io::ErrorKind::UnexpectedEof, + "the image tar ends inside a block", + )); + } + read += n; + } + Ok(true) +} + +/// Skips `count` bytes of input. +pub(super) fn skip_bytes(input: &mut R, count: u64) -> io::Result<()> { + if count == 0 { + return Ok(()); + } + let copied = io::copy(&mut input.take(count), &mut io::sink())?; + if copied != count { + return Err(io::ErrorKind::UnexpectedEof.into()); + } + Ok(()) +} + +/// Reads GNU oldgnu extended sparse header blocks that follow a `b'S'` header. +pub(super) fn read_gnu_sparse_map( + input: &mut R, + header: &[u8; BLOCK], + entry_size: u64, +) -> io::Result> { + let mut chunks = Vec::new(); + let mut stored = 0u64; + for i in 0..4 { + let base = 386 + i * 24; + push_gnu_slot( + &mut chunks, + &mut stored, + &header[base..base + 24], + entry_size, + )?; + } + let mut extended = header[482] != 0; + while extended { + let mut ext = [0u8; BLOCK]; + if !read_block(input, &mut ext)? { + return Err(io::ErrorKind::UnexpectedEof.into()); + } + let mut added = false; + for slot in 0..21 { + let base = slot * 24; + if push_gnu_slot(&mut chunks, &mut stored, &ext[base..base + 24], entry_size)? { + added = true; + } + } + extended = ext[504] != 0; + if !added && extended { + return Err(invalid("empty GNU sparse extended block")); + } + } + Ok(chunks) +} + +fn push_gnu_slot( + chunks: &mut Vec<(u64, u64)>, + stored: &mut u64, + slot: &[u8], + entry_size: u64, +) -> io::Result { + let off = octal(&slot[..12])?; + let len = octal(&slot[12..24])?; + if len == 0 { + return Ok(false); + } + if (chunks.len() as u64) >= entry_size + || chunks.len() >= SPARSE_CHUNKS_MAX + || stored.checked_add(len).is_none_or(|s| s > entry_size) + { + return Err(invalid("GNU sparse chunks exceed tar entry size")); + } + *stored += len; + chunks.push((off, len)); + Ok(true) +} + +/// Reads the PAX `1.0` inline newline-delimited sparse map (512-byte padded) +/// from the beginning of the entry's payload, returning `(chunks, map_bytes)`. +pub(super) fn read_pax1_sparse_map( + input: &mut R, + max_bytes: u64, +) -> io::Result<(Vec<(u64, u64)>, u64)> { + let mut raw = Vec::new(); + let mut num_chunks: Option = None; + let mut needed_lines: usize = 1; + loop { + if raw.len() as u64 + BLOCK as u64 > max_bytes.min(EXTENDED_MAX) { + return Err(invalid( + "PAX sparse map exceeds entry size or extended header limit", + )); + } + let mut blk = [0u8; BLOCK]; + if !read_block(input, &mut blk)? { + return Err(io::ErrorKind::UnexpectedEof.into()); + } + raw.extend_from_slice(&blk); + if num_chunks.is_none() { + if let Some(nl) = raw.iter().position(|b| *b == b'\n') { + let count: usize = std::str::from_utf8(&raw[..nl]) + .ok() + .and_then(|s| s.trim().parse().ok()) + .ok_or_else(|| invalid("invalid PAX sparse chunk count"))?; + needed_lines = 1usize + .checked_add(count.saturating_mul(2)) + .ok_or_else(|| invalid("sparse map overflow"))?; + num_chunks = Some(count); + } + } + if num_chunks.is_some() { + let newlines = raw.iter().filter(|b| **b == b'\n').count(); + if newlines >= needed_lines { + break; + } + } + } + let map_bytes = raw.len() as u64; + let count = num_chunks.unwrap_or(0); + let mut lines = raw + .split(|b| *b == b'\n') + .take(needed_lines) + .map(|l| std::str::from_utf8(l).map(str::trim)); + let _ = lines.next(); + let mut chunks = Vec::with_capacity(count); + let mut next_u64 = |msg: &str| -> io::Result { + lines + .next() + .transpose() + .ok() + .flatten() + .and_then(|s| s.parse().ok()) + .ok_or_else(|| invalid(msg)) + }; + for _ in 0..count { + let off = next_u64("invalid PAX sparse offset")?; + let len = next_u64("invalid PAX sparse length")?; + if len > 0 { + chunks.push((off, len)); + } + } + Ok((chunks, map_bytes)) +} + +pub(super) fn validate_sparse_chunks( + mut chunks: Vec<(u64, u64)>, + realsize: u64, +) -> io::Result<(Vec<(u64, u64)>, u64)> { + let mut prev_end = 0u64; + let mut stored_bytes = 0u64; + for &(off, len) in &chunks { + if off > realsize { + return Err(invalid("sparse chunk starts past realsize")); + } + if len == 0 { + continue; + } + if off < prev_end { + return Err(invalid("sparse chunks overlap or are out of order")); + } + let end = off + .checked_add(len) + .ok_or_else(|| invalid("sparse chunk end overflow"))?; + if end > realsize { + return Err(invalid("sparse chunk extends past realsize")); + } + stored_bytes = stored_bytes + .checked_add(len) + .ok_or_else(|| invalid("sparse byte count overflow"))?; + prev_end = end; + } + chunks.retain(|(_, len)| *len > 0); + Ok((chunks, stored_bytes)) +} diff --git a/control/crates/layerfs-sandbox/tests/image_tar.rs b/control/crates/layerfs-sandbox/tests/image_tar.rs index 87c01b48b..a007d8fb9 100644 --- a/control/crates/layerfs-sandbox/tests/image_tar.rs +++ b/control/crates/layerfs-sandbox/tests/image_tar.rs @@ -189,3 +189,143 @@ fn pax_time_stripping_handles_empty_malformed_xattr_and_all_time_blocks_byte_for .finish(); assert_eq!(filtered(&input_mixed), expected_mixed); } + +#[test] +fn consecutive_pax_x_interleaved_g_long_paths_and_dir_times_match_baseline() { + let long_gnu_name = format!("gnu/long/{}/dir/", "a".repeat(120)); + let long_dir_1 = format!("var/tmp/{}/", "b".repeat(120)); + let long_dir_2 = format!("opt/data/{}/", "c".repeat(135)); + let long_sym_path = format!("usr/local/share/{}/link", "d".repeat(125)); + let long_sym_target = format!("/opt/targets/{}/real-bin", "e".repeat(130)); + let long_keep_file = format!("srv/app/{}/keep.bin", "f".repeat(120)); + let long_hl_path = format!("srv/app/{}/keep.hardlink", "h".repeat(120)); + + let g1 = pax_record("comment", "global-1"); + let g2 = pax_record("hdrcharset", "ISO-IR 10646 2000"); + + let mut x_dir_1 = pax_record("path", &long_dir_1); + x_dir_1.extend_from_slice(&pax_record("mtime", "1700000100.5")); + x_dir_1.extend_from_slice(&pax_record("atime", "1700000200.5")); + x_dir_1.extend_from_slice(&pax_record("SCHILY.xattr.user.k1", "v1")); + + let mut x_dir_1_expected = pax_record("path", &long_dir_1); + x_dir_1_expected.extend_from_slice(&pax_record("SCHILY.xattr.user.k1", "v1")); + + let mut x_dir_2 = pax_record("path", &long_dir_2); + x_dir_2.extend_from_slice(&pax_record("ctime", "1700000300.5")); + x_dir_2.extend_from_slice(&pax_record( + "SCHILY.xattr.security.capability", + "cap_net_admin", + )); + + let mut x_dir_2_expected = pax_record("path", &long_dir_2); + x_dir_2_expected.extend_from_slice(&pax_record( + "SCHILY.xattr.security.capability", + "cap_net_admin", + )); + + let mut x_dir_only_times = pax_record("mtime", "1700000400.1"); + x_dir_only_times.extend_from_slice(&pax_record("ctime", "1700000500.2")); + + let mut x_sym = pax_record("path", &long_sym_path); + x_sym.extend_from_slice(&pax_record("linkpath", &long_sym_target)); + x_sym.extend_from_slice(&pax_record("mtime", "1700000600.25")); + + let mut x_hl = pax_record("path", &long_hl_path); + x_hl.extend_from_slice(&pax_record("linkpath", &long_keep_file)); + + let input = Tar::new() + .at(1_700_000_111) + .raw("PaxHeaders/global-1", b'g', 0o644, &g1) + .raw("././@LongLink", b'L', 0o644, long_gnu_name.as_bytes()) + .raw("PaxHeaders/dir-1", b'x', 0o644, &x_dir_1) + .raw("PaxHeaders/global-2", b'g', 0o644, &g2) + .raw("PaxHeaders/dir-2", b'x', 0o644, &x_dir_2) + .raw("PaxHeaders/dir-3", b'x', 0o644, &x_dir_only_times) + .directory("placeholder-dir", 0o755) + .at(1_700_000_222) + .raw( + "PaxHeaders/override-keep-1", + b'x', + 0o644, + &pax_record("path", "etc/hosts"), + ) + .raw( + "PaxHeaders/override-keep-2", + b'x', + 0o644, + &pax_record("path", "etc/hosts.allow"), + ) + .file("placeholder-keep", 0o644, b"allow-me\n") + .raw( + "PaxHeaders/override-drop-1", + b'x', + 0o644, + &pax_record("path", "usr/keep.txt"), + ) + .raw( + "PaxHeaders/override-drop-2", + b'x', + 0o644, + &pax_record("path", "./etc/hosts"), + ) + .file("placeholder-drop", 0o644, b"dropped\n") + .raw("PaxHeaders/global-3", b'g', 0o644, &g1) + .raw("././@LongLink", b'K', 0o644, b"ignored-gnu-link-target\0") + .raw("PaxHeaders/sym", b'x', 0o644, &x_sym) + .symlink("placeholder-sym", "placeholder-target") + .raw( + "PaxHeaders/keep-file", + b'x', + 0o644, + &pax_record("path", &long_keep_file), + ) + .file("placeholder-file", 0o644, b"payload\n") + .raw("PaxHeaders/global-4", b'g', 0o644, &g2) + .raw("PaxHeaders/hl", b'x', 0o644, &x_hl) + .hard_link("placeholder-hl", "placeholder-hl-target") + .finish(); + + let expected = Tar::new() + .at(1_700_000_111) + .raw("PaxHeaders/global-1", b'g', 0o644, &g1) + .at(0) + .raw("././@LongLink", b'L', 0o644, long_gnu_name.as_bytes()) + .raw("PaxHeaders/dir-1", b'x', 0o644, &x_dir_1_expected) + .at(1_700_000_111) + .raw("PaxHeaders/global-2", b'g', 0o644, &g2) + .at(0) + .raw("PaxHeaders/dir-2", b'x', 0o644, &x_dir_2_expected) + .directory("placeholder-dir", 0o755) + .at(1_700_000_222) + .raw( + "PaxHeaders/override-keep-1", + b'x', + 0o644, + &pax_record("path", "etc/hosts"), + ) + .raw( + "PaxHeaders/override-keep-2", + b'x', + 0o644, + &pax_record("path", "etc/hosts.allow"), + ) + .file("placeholder-keep", 0o644, b"allow-me\n") + .raw("PaxHeaders/global-3", b'g', 0o644, &g1) + .raw("././@LongLink", b'K', 0o644, b"ignored-gnu-link-target\0") + .raw("PaxHeaders/sym", b'x', 0o644, &x_sym) + .symlink("placeholder-sym", "placeholder-target") + .raw( + "PaxHeaders/keep-file", + b'x', + 0o644, + &pax_record("path", &long_keep_file), + ) + .file("placeholder-file", 0o644, b"payload\n") + .raw("PaxHeaders/global-4", b'g', 0o644, &g2) + .raw("PaxHeaders/hl", b'x', 0o644, &x_hl) + .hard_link("placeholder-hl", "placeholder-hl-target") + .finish(); + + assert_eq!(filtered(&input), expected); +} diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs index 5ceeeaade..62d926002 100644 --- a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs +++ b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs @@ -14,7 +14,7 @@ use layerfs_machine::worker::{read_frame, read_frame_within, write_frame, MAX_HE use layerfs_sandbox::docker::Docker; use layerfs_sandbox::image_artifact::{self as cache, architecture, Sidecar, CHUNK}; use layerfs_sandbox::image_load::{load, ImageLock, Loaded, Target}; -use layerfs_sandbox::image_tar::{Filtered, TarReport, SPARSE_MAX}; +use layerfs_sandbox::image_tar::{Filtered, TarReport, EXTENDED_TOTAL_MAX, SPARSE_MAX}; use layerfs_sandbox::images; use layerfs_sandbox_backend::{rootfs, Image}; use layerfs_store::place::{self, Executor}; @@ -1699,8 +1699,10 @@ fn r2_pax_size_overflow_plain_bad_size_and_order_independent_chunk_cap() { .finish(); assert_invalid("sparse PAX size=bad", &sparse_bad_size, "invalid pax size"); - // 3. R2-M2: Order-independent PAX chunk count cap aborts before trailing invalid descriptors. - let map_with_trailing_bad = "0,1,4096,1,8192,1,bad,bad"; + // 3. R2-M2 + R3: Order-independent PAX chunk count cap aborts in Stage 2 before + // `validate_sparse_chunks` would hit `"sparse chunk starts past realsize"`, while + // Stage-1 syntax errors (like `,bad,bad`) abort even earlier while scanning `x`. + let map_with_trailing_past_realsize = "0,1,4096,1,8192,1,32768,1"; let chunk_err = "PAX sparse chunk count exceeds entry size or limit"; // 3a. PAX `size` BEFORE `GNU.sparse.map`. @@ -1708,7 +1710,10 @@ fn r2_pax_size_overflow_plain_bad_size_and_order_independent_chunk_cap() { size_before_map.extend_from_slice(&pax_record("size", "2")); size_before_map.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); size_before_map.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); - size_before_map.extend_from_slice(&pax_record("GNU.sparse.map", map_with_trailing_bad)); + size_before_map.extend_from_slice(&pax_record( + "GNU.sparse.map", + map_with_trailing_past_realsize, + )); let tar_before = Tar::new() .raw("PaxHeaders/before", b'x', 0o644, &size_before_map) .file("m1.bin", 0o644, b"AB") @@ -1719,7 +1724,10 @@ fn r2_pax_size_overflow_plain_bad_size_and_order_independent_chunk_cap() { let mut size_after_map = pax_record("GNU.sparse.major", "0"); size_after_map.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); size_after_map.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); - size_after_map.extend_from_slice(&pax_record("GNU.sparse.map", map_with_trailing_bad)); + size_after_map.extend_from_slice(&pax_record( + "GNU.sparse.map", + map_with_trailing_past_realsize, + )); size_after_map.extend_from_slice(&pax_record("size", "2")); let tar_after = Tar::new() .raw("PaxHeaders/after", b'x', 0o644, &size_after_map) @@ -1727,33 +1735,60 @@ fn r2_pax_size_overflow_plain_bad_size_and_order_independent_chunk_cap() { .finish(); assert_invalid("PAX size after map", &tar_after, chunk_err); - // 3c. No PAX `size` (falls back to ustar header size = 2) still aborts before `,bad,bad`. + // 3c. No PAX `size` (falls back to ustar header size = 2) still aborts before + // `validate_sparse_chunks` sees `(32768, 1)` past `realsize=16384`. let mut no_pax_size = pax_record("GNU.sparse.major", "0"); no_pax_size.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); no_pax_size.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); - no_pax_size.extend_from_slice(&pax_record("GNU.sparse.map", map_with_trailing_bad)); + no_pax_size.extend_from_slice(&pax_record( + "GNU.sparse.map", + map_with_trailing_past_realsize, + )); let tar_no_pax_size = Tar::new() .raw("PaxHeaders/nosize", b'x', 0o644, &no_pax_size) .file("m3.bin", 0o644, b"AB") .finish(); assert_invalid("PAX no size (ustar fallback)", &tar_no_pax_size, chunk_err); - // 3d. PAX 0.0 offset/numbytes pairs with `size` AFTER pairs and trailing invalid offset. + // 3d. PAX 0.0 offset/numbytes pairs with `size` AFTER pairs and trailing chunk past realsize. let mut pax00_size_after = pax_record("GNU.sparse.major", "0"); pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.minor", "0")); pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.realsize", "16384")); - for i in 0..3u64 { - pax00_size_after - .extend_from_slice(&pax_record("GNU.sparse.offset", &(i * 4096).to_string())); + for off in [0u64, 4096, 8192, 32768] { + pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.offset", &off.to_string())); pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.numbytes", "1")); } - pax00_size_after.extend_from_slice(&pax_record("GNU.sparse.offset", "bad")); pax00_size_after.extend_from_slice(&pax_record("size", "2")); let tar_pax00 = Tar::new() .raw("PaxHeaders/pax00", b'x', 0o644, &pax00_size_after) .file("m4.bin", 0o644, b"AB") .finish(); assert_invalid("PAX 0.0 size after chunks", &tar_pax00, chunk_err); + + // 3e. Stage-1 syntax/numeric validation rejects malformed sparse map/offset immediately. + let mut stage1_bad_map = pax_record("GNU.sparse.major", "0"); + stage1_bad_map.extend_from_slice(&pax_record("GNU.sparse.map", "0,1,4096,1,8192,1,bad,bad")); + let tar_stage1_map = Tar::new() + .raw("PaxHeaders/s1-map", b'x', 0o644, &stage1_bad_map) + .file("m5.bin", 0o644, b"AB") + .finish(); + assert_invalid( + "Stage 1 bad sparse map syntax", + &tar_stage1_map, + "invalid sparse map offset", + ); + + let mut stage1_bad_off = pax_record("GNU.sparse.major", "0"); + stage1_bad_off.extend_from_slice(&pax_record("GNU.sparse.offset", "bad")); + let tar_stage1_off = Tar::new() + .raw("PaxHeaders/s1-off", b'x', 0o644, &stage1_bad_off) + .file("m6.bin", 0o644, b"AB") + .finish(); + assert_invalid( + "Stage 1 bad sparse offset", + &tar_stage1_off, + "invalid pax GNU.sparse.offset", + ); } #[test] @@ -1892,6 +1927,413 @@ esac ); } +#[test] +fn r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom() { + assert_eq!(EXTENDED_TOTAL_MAX, 16 << 20); + fn make_raw_header(name: &str, flag: u8, size: u64) -> [u8; 512] { + let mut hdr = [0u8; 512]; + hdr[..name.len()].copy_from_slice(name.as_bytes()); + let oct = |f: &mut [u8], v: u64| { + let w = f.len() - 1; + let t = format!("{v:0w$o}\0"); + f.copy_from_slice(&t.as_bytes()[..f.len()]); + }; + oct(&mut hdr[100..108], 0o644); + oct(&mut hdr[108..116], 0); + oct(&mut hdr[116..124], 0); + oct(&mut hdr[124..136], size); + oct(&mut hdr[136..148], 0); + hdr[156] = flag; + hdr[257..263].copy_from_slice(b"ustar\0"); + hdr[263..265].copy_from_slice(b"00"); + hdr[148..156].fill(b' '); + let sum: u64 = hdr.iter().map(|b| u64::from(*b)).sum(); + hdr[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes()); + hdr + } + + fn append_raw_entry(buf: &mut Vec, name: &str, flag: u8, body: &[u8]) { + buf.extend_from_slice(&make_raw_header(name, flag, body.len() as u64)); + buf.extend_from_slice(body); + let pad = (512 - body.len() % 512) % 512; + buf.resize(buf.len() + pad, 0); + } + + let assert_invalid = |label: &str, input: Vec, needle: &str| { + let err = filtered_bytes(&input).expect_err(label); + assert_eq!( + err.kind(), + std::io::ErrorKind::InvalidData, + "{label}: got {err:?}" + ); + assert!( + err.to_string().contains(needle), + "{label}: expected `{needle}` in `{err}`" + ); + }; + + // 1. Bad sparse PAX metadata followed by zero end blocks OR clean EOF must fail immediately. + let mut bad_after_sparse = pax_record("GNU.sparse.major", "0"); + bad_after_sparse.extend_from_slice(b"999 bad=record\n"); + let mut bad_sparse_size = pax_record("GNU.sparse.major", "0"); + bad_sparse_size.extend_from_slice(&pax_record("size", "bad")); + + let bad_sparse_cases: [(&str, Vec, &str); 8] = [ + ( + "bad major", + pax_record("GNU.sparse.major", "bad"), + "invalid pax GNU.sparse.major", + ), + ( + "bad realsize", + pax_record("GNU.sparse.realsize", "bad"), + "invalid pax GNU.sparse.realsize", + ), + ( + "bad map item", + pax_record("GNU.sparse.map", "0,1,bad,1"), + "invalid sparse map offset", + ), + ( + "odd map item", + pax_record("GNU.sparse.map", "0,1,4096"), + "odd item count in GNU.sparse.map", + ), + ( + "unpaired offset", + pax_record("GNU.sparse.offset", "0"), + "GNU.sparse.offset without numbytes", + ), + ( + "unpaired numbytes", + pax_record("GNU.sparse.numbytes", "4"), + "GNU.sparse.numbytes without offset", + ), + ( + "malformed after sparse", + bad_after_sparse, + "malformed PAX record after GNU.sparse.*", + ), + ( + "bad pax size with sparse", + bad_sparse_size, + "invalid pax size", + ), + ]; + + for (label, body, needle) in bad_sparse_cases { + let mut with_end_blocks = Vec::new(); + append_raw_entry(&mut with_end_blocks, "PaxHeaders/bad", b'x', &body); + with_end_blocks.resize(with_end_blocks.len() + 1024, 0); + assert_invalid(&format!("{label} + zero blocks"), with_end_blocks, needle); + + let mut clean_eof = Vec::new(); + append_raw_entry(&mut clean_eof, "PaxHeaders/bad", b'x', &body); + assert_invalid(&format!("{label} + clean EOF"), clean_eof, needle); + } + + // Plain trailing PAX headers followed by end blocks or clean EOF stay tolerated (a5616c8c7 parity). + for (label, body) in [ + ("plain mtime", pax_record("mtime", "1700000000")), + ("plain bad size", pax_record("size", "bad")), + ] { + let mut with_end_blocks = Vec::new(); + append_raw_entry(&mut with_end_blocks, "PaxHeaders/plain", b'x', &body); + with_end_blocks.resize(with_end_blocks.len() + 1024, 0); + assert_eq!( + filtered_bytes(&with_end_blocks).expect(label), + vec![0u8; 1024], + "{label} + zero blocks" + ); + + let mut clean_eof = Vec::new(); + append_raw_entry(&mut clean_eof, "PaxHeaders/plain", b'x', &body); + assert_eq!( + filtered_bytes(&clean_eof).expect(label), + vec![0u8; 1024], + "{label} + clean EOF" + ); + } + + // 2. On-demand Reader: consecutive `x` headers exceeding SPARSE_CHUNKS_MAX (1,048,576) + // must fail before reading a trailing malformed header (distinct error). + enum StreamKind { + SparseChunks, + ExtendedTotal, + BadSparseThenMore, + } + + struct OnDemandFloodReader { + kind: StreamKind, + index: usize, + cur: Vec, + pos: usize, + headers_emitted: usize, + illegal_tail_read: bool, + } + + impl OnDemandFloodReader { + fn new(kind: StreamKind) -> Self { + Self { + kind, + index: 0, + cur: Vec::new(), + pos: 0, + headers_emitted: 0, + illegal_tail_read: false, + } + } + + fn refill(&mut self) -> bool { + use std::cmp::Ordering; + self.cur.clear(); + self.pos = 0; + match self.kind { + StreamKind::SparseChunks => { + // 17 headers * 65,536 chunks = 1,114,112 > SPARSE_CHUNKS_MAX (1,048,576), + // with ~600 KiB per header (< 1 MiB) and ~10.3 MiB total (< 16 MiB). + match self.index.cmp(&17) { + Ordering::Less => { + let mut map = String::new(); + let base = (self.index as u64) * 65_536; + for j in 0..65_536u64 { + if j > 0 { + map.push(','); + } + use std::fmt::Write as _; + let _ = write!(map, "{},1", (base + j) * 2); + } + let mut body = pax_record("GNU.sparse.major", "0"); + body.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + body.extend_from_slice(&pax_record("GNU.sparse.map", &map)); + append_raw_entry(&mut self.cur, "PaxHeaders/flood", b'x', &body); + self.index += 1; + self.headers_emitted += 1; + true + } + Ordering::Equal => { + self.illegal_tail_read = true; + let mut bad = [0u8; 512]; + bad[..8].copy_from_slice(b"tail.bin"); + bad[124..136].copy_from_slice(b"zzzzzzzzzzz\0"); + bad[156] = b'0'; + self.cur.extend_from_slice(&bad); + self.index += 1; + true + } + Ordering::Greater => false, + } + } + StreamKind::ExtendedTotal => { + // 35 headers * ~512.5 KiB > 16 MiB extended header total limit. + match self.index.cmp(&35) { + Ordering::Less => { + let blob = "x".repeat(512 * 1024); + let body = pax_record("SCHILY.xattr.user.pad", &blob); + append_raw_entry(&mut self.cur, "PaxHeaders/xattr-flood", b'x', &body); + self.index += 1; + self.headers_emitted += 1; + true + } + Ordering::Equal => { + self.illegal_tail_read = true; + let mut bad = [0u8; 512]; + bad[..8].copy_from_slice(b"tail.bin"); + bad[124..136].copy_from_slice(b"zzzzzzzzzzz\0"); + bad[156] = b'0'; + self.cur.extend_from_slice(&bad); + self.index += 1; + true + } + Ordering::Greater => false, + } + } + StreamKind::BadSparseThenMore => { + if self.index == 0 { + let body = pax_record("GNU.sparse.major", "bad"); + append_raw_entry(&mut self.cur, "PaxHeaders/bad", b'x', &body); + self.index += 1; + self.headers_emitted += 1; + true + } else if self.index < 10 { + self.illegal_tail_read = true; + let body = pax_record("mtime", "1700000000"); + append_raw_entry(&mut self.cur, "PaxHeaders/next", b'x', &body); + self.index += 1; + self.headers_emitted += 1; + true + } else { + false + } + } + } + } + } + + impl Read for OnDemandFloodReader { + fn read(&mut self, buf: &mut [u8]) -> std::io::Result { + if self.pos >= self.cur.len() && !self.refill() { + return Ok(0); + } + let n = (self.cur.len() - self.pos).min(buf.len()); + buf[..n].copy_from_slice(&self.cur[self.pos..self.pos + n]); + self.pos += n; + Ok(n) + } + } + + let mut chunk_flood_reader = OnDemandFloodReader::new(StreamKind::SparseChunks); + let mut chunk_flood_filtered = Filtered::new(&mut chunk_flood_reader); + let err = chunk_flood_filtered + .read_to_end(&mut Vec::new()) + .expect_err("consecutive x headers exceeding SPARSE_CHUNKS_MAX must fail"); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); + assert!( + err.to_string() + .contains("PAX sparse chunk count exceeds entry size or limit"), + "expected hard chunk cap error, got: {err}" + ); + assert!( + !chunk_flood_reader.illegal_tail_read, + "must hit SPARSE_CHUNKS_MAX before reading trailing illegal header" + ); + assert_eq!(chunk_flood_reader.headers_emitted, 17); + + let mut bad_first_reader = OnDemandFloodReader::new(StreamKind::BadSparseThenMore); + let mut bad_first_filtered = Filtered::new(&mut bad_first_reader); + let err = bad_first_filtered + .read_to_end(&mut Vec::new()) + .expect_err("bad sparse x header must abort before buffering trailing headers"); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); + assert!(err.to_string().contains("invalid pax GNU.sparse.major")); + assert!( + !bad_first_reader.illegal_tail_read, + "must reject on first bad sparse x header without reading second header" + ); + + // 3. Per-entry extended header total byte cap (16 MiB) catches both multi-header xattr floods + // and zero-length empty `x` header floods without unbounded buffering. + let mut ext_flood_reader = OnDemandFloodReader::new(StreamKind::ExtendedTotal); + let mut ext_flood_filtered = Filtered::new(&mut ext_flood_reader); + let err = ext_flood_filtered + .read_to_end(&mut Vec::new()) + .expect_err("extended headers exceeding 16 MiB must fail"); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); + assert!( + err.to_string().contains("extended headers exceed"), + "unexpected error for extended total cap: {err}" + ); + assert!( + !ext_flood_reader.illegal_tail_read, + "must hit extended total cap before reading trailing illegal header" + ); + + struct EmptyHeaderFlood { + emitted: usize, + offset: usize, + } + impl Read for EmptyHeaderFlood { + fn read(&mut self, buf: &mut [u8]) -> std::io::Result { + // Each zero-length `x` header adds 512 bytes to total extended budget -> + // > 32,768 headers exceeds 16 MiB. + let hdr = make_raw_header("PaxHeaders/empty", b'x', 0); + let mut n = 0; + while n < buf.len() && self.emitted < 40_000 { + let take = (512 - self.offset).min(buf.len() - n); + buf[n..n + take].copy_from_slice(&hdr[self.offset..self.offset + take]); + n += take; + self.offset += take; + if self.offset == 512 { + self.offset = 0; + self.emitted += 1; + } + } + Ok(n) + } + } + let mut empty_flood = EmptyHeaderFlood { + emitted: 0, + offset: 0, + }; + let err = Filtered::new(&mut empty_flood) + .read_to_end(&mut Vec::new()) + .expect_err("empty extended header flood must hit total cap"); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); + assert!(err.to_string().contains("extended headers exceed")); + assert!( + empty_flood.emitted <= 32_769, + "emitted {} empty headers", + empty_flood.emitted + ); + + // 4. Realistic container entry with long path/linkpath and heavy SCHILY.xattr.* set passes + // both filtering and rootfs::ensure_flat without being rejected. + let long_file_path = format!( + "var/lib/containers/storage/overlay/{}/{}/diff/usr/libexec/app", + "p".repeat(130), + "q".repeat(130) + ); + let long_link_path = format!( + "var/lib/containers/storage/overlay/{}/{}/diff/usr/bin/app-link", + "l".repeat(130), + "m".repeat(130) + ); + let long_link_target = format!("../libexec/{}/{}/app", "t".repeat(120), "u".repeat(120)); + let mut xattrs_a = pax_record("path", &long_file_path); + xattrs_a.extend_from_slice(&pax_record("mtime", "1700000123.5")); + xattrs_a.extend_from_slice(&pax_record( + "SCHILY.xattr.security.capability", + "cap_net_bind", + )); + xattrs_a.extend_from_slice(&pax_record( + "SCHILY.xattr.security.selinux", + "system_u:object_r:container_file_t:s0:c123,c456", + )); + let mut xattrs_b = Vec::new(); + let xattr_val = "v".repeat(600); + for i in 0..200 { + xattrs_b.extend_from_slice(&pax_record( + &format!("SCHILY.xattr.user.attr_{i:03}"), + &xattr_val, + )); + } + assert!(xattrs_a.len() + xattrs_b.len() > 120_000); + let g_hdr = pax_record("comment", "oci-export"); + let mut x_sym = pax_record("path", &long_link_path); + x_sym.extend_from_slice(&pax_record("linkpath", &long_link_target)); + + let realistic_tar = Tar::new() + .raw("PaxHeaders/global", b'g', 0o644, &g_hdr) + .raw("PaxHeaders/x1", b'x', 0o644, &xattrs_a) + .raw("PaxHeaders/x2", b'x', 0o644, &xattrs_b) + .file("placeholder-bin", 0o755, b"ELF-mock-binary\n") + .raw("PaxHeaders/sym", b'x', 0o644, &x_sym) + .symlink("placeholder-sym", "target") + .finish(); + let filtered_realistic = filtered_bytes(&realistic_tar).expect("realistic xattr entry allowed"); + assert_eq!(filtered_realistic, realistic_tar); + + let scratch = Scratch::new("lp176-r3-xattr-headroom"); + let tar_path = scratch.base.join("realistic.tar"); + fs::write(&tar_path, &filtered_realistic).unwrap(); + let (root, _) = rootfs::ensure_flat( + &tar_path, + &Image::parse(&format!("sha256:{}", "e".repeat(64))).unwrap(), + &scratch.cache, + ) + .unwrap(); + assert_eq!( + fs::read(root.directory().join(&long_file_path)).unwrap(), + b"ELF-mock-binary\n" + ); + assert_eq!( + fs::read_link(root.directory().join(&long_link_path)) + .unwrap() + .to_string_lossy(), + long_link_target + ); +} + #[test] fn helper_pause_load() { let Ok(home) = std::env::var("LP176_REC_PAUSE_HOME") else { From e390334fb2a99312612bd6edf54bc2dca4e9d889 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:06:26 +0000 Subject: [PATCH 8/8] sandbox: defer PAX size finality to entry/EOF and raise extended header cap to 48 MiB (#176 I03 R4) - R4-M1: keep Stage-1 immediate sparse syntax, numeric, pairing, and SPARSE_CHUNKS_MAX checks in PaxScan::scan_header while recording pax_size/pax_size_bad without finalizing per header so later x headers can override earlier bad/overflow size; add PendingHeaders::finish_at_end() invoked on both Stage-3 clean EOF and zero end-block paths so trailing sparse bad/overflow size still returns InvalidData. - R4-M2: raise EXTENDED_TOTAL_MAX from 16 MiB to 48 MiB (covering worst-case decimal encoding of SPARSE_CHUNKS_MAX = 1,048,576 descriptors at 42 bytes/descriptor ~= 44 MB plus per-header framing/xattrs) while preserving 512 + padded accounting. - Tests: add r4_m1_cross_header_pax_size_override_and_final_validation and r4_m2_long_digit_sparse_map_above_16mib_succeeds in lp176_image_recovery.rs; adjust r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom flood bounds to 48 MiB. Production LOC: 171,386 -> 171,391 (delta +5) core 39,795 -> 39,795 (0) engine 75,102 -> 75,102 (0) control 50,143 -> 50,148 (+5) layerfs-sandbox +5 api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent f19ae1053 and the staged tree --- .../layerfs-sandbox/src/image_tar/filter.rs | 9 +- .../layerfs-sandbox/src/image_tar/pax.rs | 38 +- .../tests/lp176_image_recovery.rs | 439 ++++++++++++++++-- 3 files changed, 425 insertions(+), 61 deletions(-) diff --git a/control/crates/layerfs-sandbox/src/image_tar/filter.rs b/control/crates/layerfs-sandbox/src/image_tar/filter.rs index 1ade3dfb0..f3c9b2202 100644 --- a/control/crates/layerfs-sandbox/src/image_tar/filter.rs +++ b/control/crates/layerfs-sandbox/src/image_tar/filter.rs @@ -149,15 +149,18 @@ impl Filtered { let (mut header, ustar_size, ustar_padded, flag) = loop { let mut header = [0u8; BLOCK]; if !read_block(&mut self.input, &mut header)? { + pending.finish_at_end()?; // Stage 3a: clean EOF without end blocks (any bad sparse PAX in - // `pending` already errored during Stage 1). + // `pending` already errored during Stage 1, and final sparse + // `size` state is checked above). self.out.extend_from_slice(&[0u8; BLOCK * 2]); self.done = true; return Ok(()); } if header.iter().all(|b| *b == 0) { - // Stage 3b: two zero end blocks, nothing after (any bad sparse - // PAX in `pending` already errored during Stage 1). + pending.finish_at_end()?; + // Stage 3b: two zero end blocks, nothing after (same Stage-1 + // and final sparse `size` invariants as clean EOF). self.out.extend_from_slice(&[0u8; BLOCK * 2]); self.done = true; return Ok(()); diff --git a/control/crates/layerfs-sandbox/src/image_tar/pax.rs b/control/crates/layerfs-sandbox/src/image_tar/pax.rs index 8facf1f51..cd7e6f983 100644 --- a/control/crates/layerfs-sandbox/src/image_tar/pax.rs +++ b/control/crates/layerfs-sandbox/src/image_tar/pax.rs @@ -12,10 +12,12 @@ pub(super) const EXTENDED_MAX: u64 = 1 << 20; /// Maximum total bytes (`512 + padded` per header) buffered across all extended /// headers (`x`, `L`, `K`, `g`) of a single tar entry. /// -/// 16 MiB accommodates deep container paths/linkpaths plus large `SCHILY.xattr.*` -/// sets while bounding buffered memory on header floods (even zero-length `x` -/// headers) and exceeding the ~10 MiB PAX text of `SPARSE_CHUNKS_MAX` descriptors. -pub const EXTENDED_TOTAL_MAX: u64 = 16 << 20; +/// 48 MiB covers the worst-case decimal encoding of `SPARSE_CHUNKS_MAX` +/// (`1,048,576`) descriptors in `GNU.sparse.map` (two up-to-20-digit `u64`s +/// plus separators = 42 bytes/descriptor, ~42 MiB / 44 MB) with headroom for +/// per-header framing/padding, long paths, and `SCHILY.xattr.*`, while keeping +/// `512 + padded` accounting for empty and non-sparse header floods. +pub const EXTENDED_TOTAL_MAX: u64 = 48 << 20; /// Hard cap on parsed sparse chunk descriptors across extended headers. pub(super) const SPARSE_CHUNKS_MAX: usize = 1 << 20; @@ -44,7 +46,7 @@ pub(super) struct PendingHeaders { } impl PendingHeaders { - /// Stage 1 admission check: enforces per-header 1 MiB and per-entry 16 MiB + /// Stage 1 admission check: enforces per-header 1 MiB and per-entry 48 MiB /// extended-header budgets before allocating the extended header payload. pub(super) fn admit_header(&mut self, padded: u64) -> io::Result<()> { if padded > EXTENDED_MAX { @@ -53,9 +55,9 @@ impl PendingHeaders { let next = self .total_bytes .checked_add((BLOCK as u64) + padded) - .ok_or_else(|| invalid("the image tar extended headers exceed 16 MiB"))?; + .ok_or_else(|| invalid("the image tar extended headers exceed 48 MiB"))?; if next > EXTENDED_TOTAL_MAX { - return Err(invalid("the image tar extended headers exceed 16 MiB")); + return Err(invalid("the image tar extended headers exceed 48 MiB")); } self.total_bytes = next; Ok(()) @@ -75,6 +77,20 @@ impl PendingHeaders { Ok(()) } + /// Stage 3 termination check: validates a pending sparse entry's final + /// `size` state when the archive ends before a regular entry header arrives. + pub(super) fn finish_at_end(&self) -> io::Result<()> { + if self.pax.has_sparse { + if self.pax.pax_size_bad { + return Err(invalid("invalid pax size")); + } + if let Some(sz) = self.pax.pax_size { + padded_size(sz)?; + } + } + Ok(()) + } + /// Stage 2 entry size resolution: applies PAX `size` when present (ignoring /// bad PAX `size` on plain entries, matching baseline) and checks 512B padding. pub(super) fn resolve_entry_size( @@ -350,14 +366,6 @@ impl PaxScan { if pending_offset.is_some() { return Err(invalid("GNU.sparse.offset without numbytes")); } - if self.has_sparse && self.pax_size_bad { - return Err(invalid("invalid pax size")); - } - if self.has_sparse { - if let Some(sz) = self.pax_size { - padded_size(sz)?; - } - } Ok(()) } } diff --git a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs index 62d926002..84607eacd 100644 --- a/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs +++ b/control/crates/layerfs-sandbox/tests/lp176_image_recovery.rs @@ -1927,37 +1927,38 @@ esac ); } +fn make_raw_header(name: &str, flag: u8, size: u64) -> [u8; 512] { + let mut hdr = [0u8; 512]; + hdr[..name.len()].copy_from_slice(name.as_bytes()); + let oct = |f: &mut [u8], v: u64| { + let w = f.len() - 1; + let t = format!("{v:0w$o}\0"); + f.copy_from_slice(&t.as_bytes()[..f.len()]); + }; + oct(&mut hdr[100..108], 0o644); + oct(&mut hdr[108..116], 0); + oct(&mut hdr[116..124], 0); + oct(&mut hdr[124..136], size); + oct(&mut hdr[136..148], 0); + hdr[156] = flag; + hdr[257..263].copy_from_slice(b"ustar\0"); + hdr[263..265].copy_from_slice(b"00"); + hdr[148..156].fill(b' '); + let sum: u64 = hdr.iter().map(|b| u64::from(*b)).sum(); + hdr[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes()); + hdr +} + +fn append_raw_entry(buf: &mut Vec, name: &str, flag: u8, body: &[u8]) { + buf.extend_from_slice(&make_raw_header(name, flag, body.len() as u64)); + buf.extend_from_slice(body); + let pad = (512 - body.len() % 512) % 512; + buf.resize(buf.len() + pad, 0); +} + #[test] fn r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom() { - assert_eq!(EXTENDED_TOTAL_MAX, 16 << 20); - fn make_raw_header(name: &str, flag: u8, size: u64) -> [u8; 512] { - let mut hdr = [0u8; 512]; - hdr[..name.len()].copy_from_slice(name.as_bytes()); - let oct = |f: &mut [u8], v: u64| { - let w = f.len() - 1; - let t = format!("{v:0w$o}\0"); - f.copy_from_slice(&t.as_bytes()[..f.len()]); - }; - oct(&mut hdr[100..108], 0o644); - oct(&mut hdr[108..116], 0); - oct(&mut hdr[116..124], 0); - oct(&mut hdr[124..136], size); - oct(&mut hdr[136..148], 0); - hdr[156] = flag; - hdr[257..263].copy_from_slice(b"ustar\0"); - hdr[263..265].copy_from_slice(b"00"); - hdr[148..156].fill(b' '); - let sum: u64 = hdr.iter().map(|b| u64::from(*b)).sum(); - hdr[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes()); - hdr - } - - fn append_raw_entry(buf: &mut Vec, name: &str, flag: u8, body: &[u8]) { - buf.extend_from_slice(&make_raw_header(name, flag, body.len() as u64)); - buf.extend_from_slice(body); - let pad = (512 - body.len() % 512) % 512; - buf.resize(buf.len() + pad, 0); - } + assert_eq!(EXTENDED_TOTAL_MAX, 48 << 20); let assert_invalid = |label: &str, input: Vec, needle: &str| { let err = filtered_bytes(&input).expect_err(label); @@ -2125,10 +2126,11 @@ fn r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom() { } } StreamKind::ExtendedTotal => { - // 35 headers * ~512.5 KiB > 16 MiB extended header total limit. - match self.index.cmp(&35) { + // 64 headers * (512 + 786,944) = 50,397,184 > 48 MiB (50,331,648); + // 63 headers = 49,609,728 <= 48 MiB. + match self.index.cmp(&64) { Ordering::Less => { - let blob = "x".repeat(512 * 1024); + let blob = "x".repeat(768 * 1024); let body = pax_record("SCHILY.xattr.user.pad", &blob); append_raw_entry(&mut self.cur, "PaxHeaders/xattr-flood", b'x', &body); self.index += 1; @@ -2211,22 +2213,23 @@ fn r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom() { "must reject on first bad sparse x header without reading second header" ); - // 3. Per-entry extended header total byte cap (16 MiB) catches both multi-header xattr floods + // 3. Per-entry extended header total byte cap (48 MiB) catches both multi-header xattr floods // and zero-length empty `x` header floods without unbounded buffering. let mut ext_flood_reader = OnDemandFloodReader::new(StreamKind::ExtendedTotal); let mut ext_flood_filtered = Filtered::new(&mut ext_flood_reader); let err = ext_flood_filtered .read_to_end(&mut Vec::new()) - .expect_err("extended headers exceeding 16 MiB must fail"); + .expect_err("extended headers exceeding 48 MiB must fail"); assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); assert!( - err.to_string().contains("extended headers exceed"), + err.to_string().contains("extended headers exceed 48 MiB"), "unexpected error for extended total cap: {err}" ); assert!( !ext_flood_reader.illegal_tail_read, "must hit extended total cap before reading trailing illegal header" ); + assert_eq!(ext_flood_reader.headers_emitted, 64); struct EmptyHeaderFlood { emitted: usize, @@ -2235,10 +2238,10 @@ fn r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom() { impl Read for EmptyHeaderFlood { fn read(&mut self, buf: &mut [u8]) -> std::io::Result { // Each zero-length `x` header adds 512 bytes to total extended budget -> - // > 32,768 headers exceeds 16 MiB. + // 98,304 headers == 48 MiB; the 98,305th exceeds 48 MiB. let hdr = make_raw_header("PaxHeaders/empty", b'x', 0); let mut n = 0; - while n < buf.len() && self.emitted < 40_000 { + while n < buf.len() && self.emitted < 105_000 { let take = (512 - self.offset).min(buf.len() - n); buf[n..n + take].copy_from_slice(&hdr[self.offset..self.offset + take]); n += take; @@ -2259,12 +2262,8 @@ fn r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom() { .read_to_end(&mut Vec::new()) .expect_err("empty extended header flood must hit total cap"); assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); - assert!(err.to_string().contains("extended headers exceed")); - assert!( - empty_flood.emitted <= 32_769, - "emitted {} empty headers", - empty_flood.emitted - ); + assert!(err.to_string().contains("extended headers exceed 48 MiB")); + assert_eq!(empty_flood.emitted, ((48 << 20) / 512) + 1); // 4. Realistic container entry with long path/linkpath and heavy SCHILY.xattr.* set passes // both filtering and rootfs::ensure_flat without being rejected. @@ -2334,6 +2333,360 @@ fn r3_bad_sparse_eof_cross_header_caps_and_xattr_headroom() { ); } +#[test] +fn r4_m1_cross_header_pax_size_override_and_final_validation() { + let scratch = Scratch::new("lp176-r4-m1"); + let mut base_meta = pax_record("GNU.sparse.major", "0"); + base_meta.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + base_meta.extend_from_slice(&pax_record("GNU.sparse.realsize", "8192")); + base_meta.extend_from_slice(&pax_record("GNU.sparse.map", "0,1")); + + let mut single_meta = base_meta.clone(); + single_meta.extend_from_slice(&pax_record("size", "1")); + + // 1. Success cases: bad or overflowing PAX `size` in first `x`, overridden by `size=1` in second `x`. + for (idx, (label, first_size, name, byte)) in [ + ("overflow then 1", u64::MAX.to_string(), "sp1.bin", b'A'), + ("bad then 1", "bad".to_owned(), "sp2.bin", b'B'), + ] + .into_iter() + .enumerate() + { + let mut x1 = base_meta.clone(); + x1.extend_from_slice(&pax_record("size", &first_size)); + let x2 = pax_record("size", "1"); + let input = Tar::new() + .raw("PaxHeaders/x1", b'x', 0o644, &x1) + .raw("PaxHeaders/x2", b'x', 0o644, &x2) + .file(name, 0o644, &[byte]) + .finish(); + let single = Tar::new() + .raw("PaxHeaders/single", b'x', 0o644, &single_meta) + .file(name, 0o644, &[byte]) + .finish(); + + let (filtered, report) = filtered_with_report(&input).expect(label); + let expected_single = filtered_bytes(&single).expect("single header baseline"); + assert_eq!(filtered, expected_single, "{label}: single-header parity"); + assert_eq!(report.sparse_files.len(), 1, "{label}"); + assert_eq!(report.sparse_files[0].expanded_bytes, 8192, "{label}"); + assert_eq!(report.sparse_files[0].stored_bytes, 1, "{label}"); + + let tar_path = scratch.base.join(format!("ok-{idx}.tar")); + fs::write(&tar_path, &filtered).unwrap(); + let (root, _) = rootfs::ensure_flat( + &tar_path, + &Image::parse(&format!("sha256:{}", format!("{idx}").repeat(64))).unwrap(), + &scratch.cache, + ) + .unwrap(); + let mut expected = vec![0u8; 8192]; + expected[0] = byte; + assert_eq!(fs::read(root.directory().join(name)).unwrap(), expected); + + // Trailing sparse `x` pair ending in `size=1` followed by zero end-blocks or clean EOF succeeds. + let mut with_end = Vec::new(); + append_raw_entry(&mut with_end, "PaxHeaders/x1", b'x', &x1); + append_raw_entry(&mut with_end, "PaxHeaders/x2", b'x', &x2); + with_end.resize(with_end.len() + 1024, 0); + assert_eq!( + filtered_bytes(&with_end).expect("overridden size + end blocks"), + vec![0u8; 1024] + ); + + let mut clean_eof = Vec::new(); + append_raw_entry(&mut clean_eof, "PaxHeaders/x1", b'x', &x1); + append_raw_entry(&mut clean_eof, "PaxHeaders/x2", b'x', &x2); + assert_eq!( + filtered_bytes(&clean_eof).expect("overridden size + clean EOF"), + vec![0u8; 1024] + ); + } + + // 2. Rejection cases: valid `size=1` in first `x`, bad or overflowing `size` in second `x` + // must fail both before a real entry header and at zero end-blocks / clean EOF. + let assert_invalid = |label: &str, input: Vec, needle: &str| { + let err = filtered_bytes(&input).expect_err(label); + assert_eq!( + err.kind(), + std::io::ErrorKind::InvalidData, + "{label}: got {err:?}" + ); + assert!( + err.to_string().contains(needle), + "{label}: expected `{needle}` in `{err}`" + ); + }; + + for (label, second_size, needle) in [ + ("1 then bad", "bad".to_owned(), "invalid pax size"), + ("1 then overflow", u64::MAX.to_string(), "overflow"), + ] { + let x2 = pax_record("size", &second_size); + + let with_entry = Tar::new() + .raw("PaxHeaders/x1", b'x', 0o644, &single_meta) + .raw("PaxHeaders/x2", b'x', 0o644, &x2) + .file("sp.bin", 0o644, b"A") + .finish(); + assert_invalid(&format!("{label} + entry"), with_entry, needle); + + let mut with_end = Vec::new(); + append_raw_entry(&mut with_end, "PaxHeaders/x1", b'x', &single_meta); + append_raw_entry(&mut with_end, "PaxHeaders/x2", b'x', &x2); + with_end.resize(with_end.len() + 1024, 0); + assert_invalid(&format!("{label} + end blocks"), with_end, needle); + + let mut clean_eof = Vec::new(); + append_raw_entry(&mut clean_eof, "PaxHeaders/x1", b'x', &single_meta); + append_raw_entry(&mut clean_eof, "PaxHeaders/x2", b'x', &x2); + assert_invalid(&format!("{label} + clean EOF"), clean_eof, needle); + } +} + +#[test] +fn r4_m2_long_digit_sparse_map_above_16mib_succeeds() { + fn push_u64(dst: &mut Vec, mut n: u64) { + if n == 0 { + dst.push(b'0'); + return; + } + let mut digits = [0u8; 20]; + let mut i = digits.len(); + while n > 0 { + i -= 1; + digits[i] = b'0' + (n % 10) as u8; + n /= 10; + } + dst.extend_from_slice(&digits[i..]); + } + + fn push_u64_padded11(dst: &mut Vec, mut n: u64) { + let mut digits = [b'0'; 11]; + for slot in digits.iter_mut().rev() { + *slot = b'0' + (n % 10) as u8; + n /= 10; + } + dst.extend_from_slice(&digits); + } + + fn pax_record_bytes(key: &str, value: &[u8]) -> Vec { + let body_len = 1 + key.len() + 1 + value.len() + 1; + let mut digits = 1usize; + let total = loop { + let candidate = digits + body_len; + let d = candidate.to_string().len(); + if d == digits { + break candidate; + } + digits = d; + }; + let mut out = Vec::with_capacity(total); + push_u64(&mut out, total as u64); + out.push(b' '); + out.extend_from_slice(key.as_bytes()); + out.push(b'='); + out.extend_from_slice(value); + out.push(b'\n'); + out + } + + enum MapShape { + Review4HugeRealsize, + CompactEof, + } + + struct LongDigitSparseTarReader { + shape: MapShape, + headers: usize, + per_hdr: usize, + payload_bytes: u64, + real_size: u64, + stage: usize, + cur: Vec, + pos: usize, + payload_left: u64, + pad_left: usize, + tail_left: usize, + extended_bytes: u64, + } + + impl LongDigitSparseTarReader { + fn new(shape: MapShape) -> Self { + let (payload_bytes, real_size) = match shape { + MapShape::Review4HugeRealsize => (1_000_000_000, 12_000_000_000), + MapShape::CompactEof => (1_000_000, 2_000_000), + }; + let pad_left = ((512 - (payload_bytes % 512)) % 512) as usize; + Self { + shape, + headers: 32, + per_hdr: 31_250, + payload_bytes, + real_size, + stage: 0, + cur: Vec::new(), + pos: 0, + payload_left: payload_bytes, + pad_left, + tail_left: 1024, + extended_bytes: 0, + } + } + + fn build_next(&mut self) -> bool { + self.cur.clear(); + self.pos = 0; + match self.stage.cmp(&self.headers) { + std::cmp::Ordering::Less => { + let mut map = Vec::with_capacity(self.per_hdr * 17); + let base = (self.stage as u64) * (self.per_hdr as u64); + for j in 0..self.per_hdr as u64 { + if j > 0 { + map.push(b','); + } + match self.shape { + MapShape::Review4HugeRealsize => { + push_u64(&mut map, 10_000_000_000u64 + 2_000u64 * (base + j)); + map.extend_from_slice(b",1000"); + } + MapShape::CompactEof => { + push_u64_padded11(&mut map, 2u64 * (base + j)); + map.extend_from_slice(b",0001"); + } + } + } + let mut body = Vec::with_capacity(map.len() + 256); + if self.stage == 0 { + body.extend_from_slice(&pax_record("GNU.sparse.major", "0")); + body.extend_from_slice(&pax_record("GNU.sparse.minor", "1")); + body.extend_from_slice(&pax_record("GNU.sparse.name", "big-sparse.bin")); + body.extend_from_slice(&pax_record( + "GNU.sparse.realsize", + &self.real_size.to_string(), + )); + body.extend_from_slice(&pax_record( + "size", + &self.payload_bytes.to_string(), + )); + } + body.extend_from_slice(&pax_record_bytes("GNU.sparse.map", &map)); + append_raw_entry(&mut self.cur, "PaxHeaders/long-map", b'x', &body); + self.extended_bytes += self.cur.len() as u64; + self.stage += 1; + true + } + std::cmp::Ordering::Equal => { + let hdr = make_raw_header("placeholder", b'0', self.payload_bytes); + self.cur.extend_from_slice(&hdr); + self.stage += 1; + true + } + std::cmp::Ordering::Greater => false, + } + } + } + + impl Read for LongDigitSparseTarReader { + fn read(&mut self, buf: &mut [u8]) -> std::io::Result { + if self.pos < self.cur.len() { + let n = (self.cur.len() - self.pos).min(buf.len()); + buf[..n].copy_from_slice(&self.cur[self.pos..self.pos + n]); + self.pos += n; + return Ok(n); + } + if self.stage <= self.headers && self.build_next() { + let n = self.cur.len().min(buf.len()); + buf[..n].copy_from_slice(&self.cur[..n]); + self.pos = n; + return Ok(n); + } + if self.payload_left > 0 { + let n = (buf.len() as u64).min(self.payload_left) as usize; + let fill = match self.shape { + MapShape::Review4HugeRealsize => b'A', + MapShape::CompactEof => b'Z', + }; + buf[..n].fill(fill); + self.payload_left -= n as u64; + return Ok(n); + } + if self.pad_left > 0 { + let n = buf.len().min(self.pad_left); + buf[..n].fill(0); + self.pad_left -= n; + return Ok(n); + } + if self.tail_left > 0 { + let n = buf.len().min(self.tail_left); + buf[..n].fill(0); + self.tail_left -= n; + return Ok(n); + } + Ok(0) + } + } + + // Part A: Exact Review-4 counterexample (1,000,000 11-digit/4-digit items across 32 `x` + // headers, ~17.0 MB > 16 MiB, realsize=12 GB, stored=1 GB). Reading the first 64 KiB + // exercises all Stage-1 & Stage-2 validation over all 32 extended headers and 1M chunks. + let mut source_a = LongDigitSparseTarReader::new(MapShape::Review4HugeRealsize); + let mut filtered_a = Filtered::new(&mut source_a); + let mut head = Vec::with_capacity(64 * 1024); + let mut scratch_buf = [0u8; 16 * 1024]; + while head.len() < 64 * 1024 { + let n = filtered_a + .read(&mut scratch_buf) + .expect("17 MB PAX map must pass Stage 1 & Stage 2"); + assert!(n > 0); + head.extend_from_slice(&scratch_buf[..n]); + } + assert_eq!(head[0..512][156], b'x'); + assert_eq!(head[1024..1536][156], b'0'); + assert_eq!(head[1024 + 124], 0x80); + assert_eq!( + u64::from_be_bytes(head[1024 + 128..1024 + 136].try_into().unwrap()), + 12_000_000_000 + ); + assert!(head[1536..].iter().all(|b| *b == 0)); + let report_a = filtered_a.report(); + assert_eq!(report_a.sparse_files.len(), 1); + assert_eq!(report_a.sparse_files[0].path, "big-sparse.bin"); + assert_eq!(report_a.sparse_files[0].expanded_bytes, 12_000_000_000); + assert_eq!(report_a.sparse_files[0].stored_bytes, 1_000_000_000); + assert_eq!(report_a.sparse_expanded_bytes, 12_000_000_000); + drop(filtered_a); + assert!(source_a.extended_bytes > (16 << 20)); + assert!(source_a.extended_bytes < (48 << 20)); + + // Part B: Complete start-to-EOF streaming on a >16 MiB, 1M-descriptor long-digit PAX 0.1 + // archive (11-digit offsets, 4-digit lengths, compact 2 MB realsize) verifying end-to-end + // payload bytes, padding, end-blocks, and report totals. + let mut source_b = LongDigitSparseTarReader::new(MapShape::CompactEof); + let mut filtered_b = Filtered::new(&mut source_b); + let mut out_b = Vec::new(); + filtered_b + .read_to_end(&mut out_b) + .expect("complete 17 MB PAX 0.1 stream must succeed to EOF"); + let out_pad = 512 - (2_000_000usize % 512); + assert_eq!(out_b.len(), 1536 + 2_000_000 + out_pad + 1024); + assert_eq!(out_b[1024 + 156], b'0'); + for (i, &byte) in out_b[1536..1536 + 2_000_000].iter().enumerate() { + let expected = if i % 2 == 0 { b'Z' } else { 0 }; + if byte != expected { + panic!("mismatch at expanded offset {i}: got {byte}, expected {expected}"); + } + } + assert!(out_b[1536 + 2_000_000..].iter().all(|b| *b == 0)); + let report_b = filtered_b.into_report(); + assert_eq!(report_b.sparse_files.len(), 1); + assert_eq!(report_b.sparse_files[0].path, "big-sparse.bin"); + assert_eq!(report_b.sparse_files[0].expanded_bytes, 2_000_000); + assert_eq!(report_b.sparse_files[0].stored_bytes, 1_000_000); + assert!(source_b.extended_bytes > (16 << 20)); + assert!(source_b.extended_bytes < (48 << 20)); +} + #[test] fn helper_pause_load() { let Ok(home) = std::env::var("LP176_REC_PAUSE_HOME") else {