From 1810b4e3d7f490ace518ace60104e4612cbbf3cd Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:09:45 +0000 Subject: [PATCH 01/17] refactor(nfs): move Released and Kernel::release into kernel/released.rs (lp73) Relocation only, no behavior change: `Kernel::release`, `Kernel::held`, `retained_count` and the `Released` struct move out of `kernel.rs` into `kernel/released.rs` verbatim, and `pub use released::Released` keeps every existing path working. This is the first commit of the AppleDouble split (LP636): `kernel.rs` would otherwise cross the 999-line ceiling once the companion work lands. No test or documentation change; the moved functions are the same text in a new module. Production LOC: 163505 -> 163511 (delta +6) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 8cfb6e273 (163505) and this tree (163511). The +6 is the new module's own two `use` lines, its `impl Kernel` block and the `mod released;` / `pub use released::Released;` declaration in kernel.rs. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/kernel.rs | 83 +---------------- .../crates/layerfs-nfs/src/kernel/released.rs | 92 +++++++++++++++++++ 2 files changed, 95 insertions(+), 80 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/kernel/released.rs diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index dd03a6ab8f..43e17fda5c 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -56,6 +56,9 @@ use std::{ }, }; +mod released; +pub use released::Released; + /// Implicit file descriptors kept open at once. pub const FILES_HELD: usize = 1024; /// Implicit directory descriptors (enumerations) kept open at once. @@ -776,61 +779,6 @@ impl Kernel { drop(wait(services.close_directory(self.mount, serial, handle))); } } - /// Gives back everything the synthetic kernel holds: descriptors first, - /// then lookup references. Run once, before the engine mount is revoked. - /// Retained mutation failures keep their custody and are only counted. - pub fn release(&self) -> Released { - let table = std::mem::take(&mut *self.table()); - let companions = self.companions_release(); - let released = Released { - companions, - files: table.files.len(), - directories: table.directories.len(), - lookups: table.lookups.len(), - silly: table.silly.len(), - retained: self.retained_count(), - silly_renamed: self.silly_renamed.load(Ordering::Relaxed), - names_refused: self.names_refused.load(Ordering::Relaxed), - names_detached: self.names_detached.load(Ordering::Relaxed), - collected: self.collected.load(Ordering::Relaxed), - resolved: self.resolved.load(Ordering::Relaxed), - unresolved: self.unresolved.load(Ordering::Relaxed), - }; - for (serial, held) in table.files { - self.close_file(serial, held.handle); - } - for (handle, (serial, _)) in table.directories { - self.close_directory(serial, handle); - } - for serial in table.lookups { - self.forget(serial, 1); - } - released - } - fn retained_count(&self) -> usize { - self.retained - .lock() - .unwrap_or_else(|poison| poison.into_inner()) - .len() - } - /// Current holdings, for diagnostics. - pub fn held(&self) -> Released { - let table = self.table(); - Released { - companions: self.companions_held(), - files: table.files.len(), - directories: table.directories.len(), - lookups: table.lookups.len(), - silly: table.silly.len(), - retained: self.retained_count(), - silly_renamed: self.silly_renamed.load(Ordering::Relaxed), - names_refused: self.names_refused.load(Ordering::Relaxed), - names_detached: self.names_detached.load(Ordering::Relaxed), - collected: self.collected.load(Ordering::Relaxed), - resolved: self.resolved.load(Ordering::Relaxed), - unresolved: self.unresolved.load(Ordering::Relaxed), - } - } /// Closes every implicit file descriptor that no silly name needs, so /// nothing the export opened is held across a Commit. Returns how many. pub fn close_files(&self) -> usize { @@ -906,31 +854,6 @@ fn collectable(table: &mut Table, keep: usize) -> Vec { } candidates.into_iter().map(|(_, serial)| serial).collect() } -/// What [`Kernel::release`] gave back. -#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] -pub struct Released { - pub files: usize, - pub directories: usize, - pub lookups: usize, - /// Silly names whose inode was kept alive until release. - pub silly: usize, - /// Failed mutations still holding engine custody. - pub retained: usize, - /// Client silly renames served as unlinks, over the export's life. - pub silly_renamed: u64, - /// Creations refused for their AppleDouble name, over the export's life. - pub names_refused: u64, - /// AppleDouble companions held in memory (see [`crate::apple_double`]). - pub companions: usize, - /// AppleDouble companions created, over the export's life. - pub names_detached: u64, - /// References collected beyond the bound, over the export's life. - pub collected: u64, - /// SqliteHandles of collected serials resolved again by their name. - pub resolved: u64, - /// SqliteHandles of collected serials whose name no longer reaches them. - pub unresolved: u64, -} fn oldest(entries: impl Iterator) -> Option { entries.min_by_key(|(_, tick)| *tick).map(|(key, _)| key) } diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs new file mode 100644 index 0000000000..5259b14be9 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -0,0 +1,92 @@ +//! What the synthetic kernel gives back, counted. +//! +//! [`Kernel::release`] runs once, before the engine mount is revoked; [`Kernel::held`] +//! reports the same counts while the export serves, for diagnostics. +use super::Kernel; +use std::sync::atomic::Ordering; + +impl Kernel { + /// Gives back everything the synthetic kernel holds: descriptors first, + /// then lookup references. Run once, before the engine mount is revoked. + /// Retained mutation failures keep their custody and are only counted. + pub fn release(&self) -> Released { + let table = std::mem::take(&mut *self.table()); + let companions = self.companions_release(); + let released = Released { + companions, + files: table.files.len(), + directories: table.directories.len(), + lookups: table.lookups.len(), + silly: table.silly.len(), + retained: self.retained_count(), + silly_renamed: self.silly_renamed.load(Ordering::Relaxed), + names_refused: self.names_refused.load(Ordering::Relaxed), + names_detached: self.names_detached.load(Ordering::Relaxed), + collected: self.collected.load(Ordering::Relaxed), + resolved: self.resolved.load(Ordering::Relaxed), + unresolved: self.unresolved.load(Ordering::Relaxed), + }; + for (serial, held) in table.files { + self.close_file(serial, held.handle); + } + for (handle, (serial, _)) in table.directories { + self.close_directory(serial, handle); + } + for serial in table.lookups { + self.forget(serial, 1); + } + released + } + + fn retained_count(&self) -> usize { + self.retained + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .len() + } + + /// Current holdings, for diagnostics. + pub fn held(&self) -> Released { + let table = self.table(); + Released { + companions: self.companions_held(), + files: table.files.len(), + directories: table.directories.len(), + lookups: table.lookups.len(), + silly: table.silly.len(), + retained: self.retained_count(), + silly_renamed: self.silly_renamed.load(Ordering::Relaxed), + names_refused: self.names_refused.load(Ordering::Relaxed), + names_detached: self.names_detached.load(Ordering::Relaxed), + collected: self.collected.load(Ordering::Relaxed), + resolved: self.resolved.load(Ordering::Relaxed), + unresolved: self.unresolved.load(Ordering::Relaxed), + } + } +} + +/// What [`Kernel::release`] gave back. +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] +pub struct Released { + pub files: usize, + pub directories: usize, + pub lookups: usize, + /// Silly names whose inode was kept alive until release. + pub silly: usize, + /// Failed mutations still holding engine custody. + pub retained: usize, + /// Client silly renames served as unlinks, over the export's life. + pub silly_renamed: u64, + /// Creations refused for their AppleDouble name, over the export's life. + pub names_refused: u64, + /// AppleDouble companions held in memory (see [`crate::apple_double`]). + pub companions: usize, + /// AppleDouble companions created, over the export's life. + pub names_detached: u64, + /// References collected beyond the bound, over the export's life. + pub collected: u64, + /// SqliteHandles of collected serials resolved again by their name. + pub resolved: u64, + /// SqliteHandles of collected serials whose name no longer reaches them. + pub unresolved: u64, +} From 210d5f8abc8f4909737cd8f6cfcea81c383259fd Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:17:47 +0000 Subject: [PATCH 02/17] feat(nfs): decode the AppleDouble image a macOS client writes (lp73) The client lays a `._` companion out as an AppleDouble v2 image: a header, a FinderInfo entry that runs into an `ATTR` table of extended attributes, and a resource-fork entry at the end. `apple_double_codec` reads those fields (`Image::parse`) and, when the fields encode back to the very bytes the client wrote (`Image::compact`), keeps them as its own record, so no attribute, value or byte the layout carries is dropped, and one attribute's alignment padding survives a shorter name replacing a longer one. `Image::new`/`Image::encode` lay an image out as the client does, which is what makes the round trip exact and what the macOS evidence compares against. Malformed, truncated or differently laid-out images, and a resource fork with data, parse to `None` and are left as the client wrote them. This is the first layer of the AppleDouble split (LP636): the codec alone, with its own unit tests; the companion that holds its decoded form comes next. Tests: new `tests/apple_double_codec.rs`, 6 cases (byte-exact round trip for every value size, many attributes, alignment padding, whole units, a resource fork, and malformed images that must not decode), all pass. Production LOC: 163511 -> 163792 (delta +281) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 1810b4e3d (163511) and this tree (163792). Engine +281 (`apple_double_codec.rs` +280, `lib.rs` +1). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/src/apple_double_codec.rs | 342 ++++++++++++++++++ engine/crates/layerfs-nfs/src/lib.rs | 1 + .../layerfs-nfs/tests/apple_double_codec.rs | 263 ++++++++++++++ 3 files changed, 606 insertions(+) create mode 100644 engine/crates/layerfs-nfs/src/apple_double_codec.rs create mode 100644 engine/crates/layerfs-nfs/tests/apple_double_codec.rs diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs new file mode 100644 index 0000000000..1d01edabf3 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -0,0 +1,342 @@ +//! The AppleDouble image a macOS NFSv3 client writes as `._`, and its +//! decoded form. +//! +//! The client lays an image out as an AppleDouble v2 header with two entries: +//! the FinderInfo, whose entry runs on into an `ATTR` table of extended +//! attributes (each name with its NUL, padded to four bytes, in entry order; +//! the values packed in the same order), and a resource fork at the end of +//! the image. The image length is a whole number of [`IMAGE_UNIT`] bytes, and +//! the bytes the layout leaves unused are zero. +//! +//! [`Image::parse`] reads those fields. [`Image::compact`] additionally +//! requires that [`Image::encode`] gives back the very same bytes, so a +//! companion held as an [`Image`] encodes again to exactly the image its +//! client wrote: no attribute, value or byte the layout carries is dropped. +//! Each attribute entry keeps the alignment padding the client left after its +//! name, because the client does not clear the bytes a shorter name replaced. +//! +//! Anything else - a resource fork with data, still another layout, a +//! half-written image - yields `None` and is stored as the client wrote it. + +use std::fmt; + +const MAGIC: u32 = 0x0005_1607; +const VERSION: u32 = 0x0002_0000; +const FILLER: &[u8; 16] = b"Mac OS X "; +const FINDER_TAG: u32 = 9; +const FORK_TAG: u32 = 2; +/// Bytes of FinderInfo. +pub const FINDER_INFO: usize = 32; +/// The FinderInfo's offset: after the header, the entry count and two entries. +const FINDER_AT: usize = 50; +/// The `ATTR` header: the FinderInfo and two bytes of padding follow the +/// header of the image. +const ATTR_AT: usize = FINDER_AT + FINDER_INFO + 2; +const ATTR_MAGIC: u32 = 0x4154_5452; +/// The first attribute entry, after the 36-byte `ATTR` header. +const ENTRIES_AT: usize = ATTR_AT + 36; +/// An attribute entry before its name: value offset, value length, flags, +/// name length in bytes including the NUL. +const ENTRY_FIXED: usize = 11; +/// The step an image grows by. +pub const IMAGE_UNIT: usize = 4096; +/// The empty resource fork the client writes at the end of an image. +const BLANK_FORK: usize = 286; +const BLANK_FORK_TAG: &[u8] = b"This resource fork intentionally left blank "; +/// Index bytes counted for one decoded image, besides its names and values. +const IMAGE_OVERHEAD: usize = 96; +/// Index bytes counted for one decoded attribute, besides its name and value. +const ATTR_OVERHEAD: usize = 56; + +/// One extended attribute of a decoded image. +#[derive(Clone, Eq, PartialEq)] +pub struct Attribute { + pub name: Vec, + pub value: Vec, + /// The bytes the client left between the name's NUL and the next entry. + pad: [u8; 3], +} +impl Attribute { + /// An attribute the client would write with a cleared pad. + pub fn new(name: &[u8], value: &[u8]) -> Self { + Self { + name: name.to_vec(), + value: value.to_vec(), + pad: [0; 3], + } + } +} +impl fmt::Debug for Attribute { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("Attribute") + .field("name", &String::from_utf8_lossy(&self.name)) + .field("bytes", &self.value.len()) + .field("pad", &self.pad) + .finish() + } +} + +/// The resource-fork entry of an image that has no resource-fork data. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum Fork { + /// A zero-length entry at the end of the image. + None, + /// The client's own empty resource fork, [`BLANK_FORK`] bytes. + Blank, +} +impl Fork { + fn len(self) -> usize { + match self { + Fork::None => 0, + Fork::Blank => BLANK_FORK, + } + } +} + +/// A decoded image: its FinderInfo, tag, extended attributes in entry order +/// and resource-fork entry, at its image length. +#[derive(Clone, Eq, PartialEq)] +pub struct Image { + finder: [u8; FINDER_INFO], + tag: u32, + attrs: Vec, + fork: Fork, + len: usize, +} +impl fmt::Debug for Image { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("Image") + .field("tag", &self.tag) + .field("attrs", &self.attrs) + .field("fork", &self.fork) + .field("len", &self.len) + .finish() + } +} +impl Image { + /// The image a client would write for these attributes from scratch: the + /// smallest whole number of [`IMAGE_UNIT`] bytes with its empty resource + /// fork, and cleared padding. `None` for an empty name, a name holding a + /// NUL, a name an entry cannot describe, or more attributes than an entry + /// count can say. + pub fn new(finder: [u8; FINDER_INFO], tag: u32, attrs: Vec) -> Option { + let named = |name: &Vec| !name.is_empty() && name.len() < 255 && !name.contains(&0); + if attrs.len() > usize::from(u16::MAX) || !attrs.iter().all(|attr| named(&attr.name)) { + return None; + } + let mut image = Self { + finder, + tag, + attrs, + fork: Fork::Blank, + len: 0, + }; + let used = image.data_start() + image.data_len() + BLANK_FORK; + image.len = used.div_ceil(IMAGE_UNIT) * IMAGE_UNIT; + u32::try_from(image.len).ok()?; + Some(image) + } + /// Its FinderInfo. + pub fn finder_info(&self) -> [u8; FINDER_INFO] { + self.finder + } + /// Its attributes. + pub fn attributes(&self) -> &[Attribute] { + &self.attrs + } + /// Its resource-fork entry. + pub fn fork(&self) -> Fork { + self.fork + } + /// The image length the client wrote, in bytes. + pub fn len(&self) -> usize { + self.len + } + /// Whether no image has an empty length; here for `len`'s sake only. + pub fn is_empty(&self) -> bool { + self.len == 0 + } + /// Index bytes this decoded form is counted for. + pub fn cost(&self) -> usize { + IMAGE_OVERHEAD + + self + .attrs + .iter() + .map(|attr| attr.name.len() + attr.value.len() + ATTR_OVERHEAD) + .sum::() + } + fn entry_end(&self, at: usize) -> usize { + ENTRIES_AT + + self + .attrs + .iter() + .take(at) + .map(|attr| entry_len(attr.name.len() + 1)) + .sum::() + } + fn data_start(&self) -> usize { + self.entry_end(self.attrs.len()) + } + fn data_len(&self) -> usize { + self.attrs.iter().map(|attr| attr.value.len()).sum() + } + /// The image these fields describe, as the client lays one out. + pub fn encode(&self) -> Vec { + let mut out = vec![0u8; self.len]; + let fork_at = self.len - self.fork.len(); + let data_start = self.data_start(); + put32(&mut out, 0, MAGIC); + put32(&mut out, 4, VERSION); + out[8..24].copy_from_slice(FILLER); + put16(&mut out, 24, 2); + put32(&mut out, 26, FINDER_TAG); + put32(&mut out, 30, FINDER_AT as u32); + put32(&mut out, 34, (fork_at - FINDER_AT) as u32); + put32(&mut out, 38, FORK_TAG); + put32(&mut out, 42, fork_at as u32); + put32(&mut out, 46, self.fork.len() as u32); + out[FINDER_AT..FINDER_AT + FINDER_INFO].copy_from_slice(&self.finder); + put32(&mut out, ATTR_AT, ATTR_MAGIC); + put32(&mut out, ATTR_AT + 4, self.tag); + put32(&mut out, ATTR_AT + 8, fork_at as u32); + put32(&mut out, ATTR_AT + 12, data_start as u32); + put32(&mut out, ATTR_AT + 16, self.data_len() as u32); + put16(&mut out, ATTR_AT + 34, self.attrs.len() as u16); + let (mut entry, mut value_at) = (ENTRIES_AT, data_start); + for attr in &self.attrs { + put32(&mut out, entry, value_at as u32); + put32(&mut out, entry + 4, attr.value.len() as u32); + out[entry + 10] = (attr.name.len() + 1) as u8; + let name_at = entry + ENTRY_FIXED; + let name_end = name_at + attr.name.len(); + out[name_at..name_end].copy_from_slice(&attr.name); + let next = entry + entry_len(attr.name.len() + 1); + out[name_end + 1..next].copy_from_slice(&attr.pad[..next - name_end - 1]); + out[value_at..value_at + attr.value.len()].copy_from_slice(&attr.value); + entry = next; + value_at += attr.value.len(); + } + if self.fork == Fork::Blank { + out[fork_at..].copy_from_slice(&blank_fork()); + } + out + } + /// The fields of `image`, laid out as the client writes one; [`Self::compact`] + /// also requires that they encode back to the same bytes. + pub fn parse(image: &[u8]) -> Option { + let len = image.len(); + u32::try_from(len).ok()?; + if len < ENTRIES_AT + || get32(image, 0)? != MAGIC + || get32(image, 4)? != VERSION + || image[8..24] != FILLER[..] + || get16(image, 24)? != 2 + || get32(image, 26)? != FINDER_TAG + || get32(image, 30)? as usize != FINDER_AT + || get32(image, 38)? != FORK_TAG + { + return None; + } + let fork = match get32(image, 46)? as usize { + 0 => Fork::None, + BLANK_FORK => Fork::Blank, + _ => return None, + }; + let fork_at = get32(image, 42)? as usize; + if fork_at.checked_add(fork.len())? != len + || fork_at < ENTRIES_AT + || get32(image, 34)? as usize != fork_at - FINDER_AT + || get32(image, ATTR_AT)? != ATTR_MAGIC + || get32(image, ATTR_AT + 8)? as usize != fork_at + { + return None; + } + let tag = get32(image, ATTR_AT + 4)?; + let data_start = get32(image, ATTR_AT + 12)? as usize; + let data_len = get32(image, ATTR_AT + 16)? as usize; + let count = get16(image, ATTR_AT + 34)?; + let (mut entry, mut value_at) = (ENTRIES_AT, data_start); + let mut attrs = Vec::with_capacity(usize::from(count)); + for _ in 0..count { + let value_len = get32(image, entry + 4)? as usize; + let name_len = usize::from(*image.get(entry + 10)?); + let name_at = entry + ENTRY_FIXED; + let name_end = entry + ENTRY_FIXED + name_len; + let name = image.get(name_at..name_end)?; + let (last, name) = name.split_last()?; + if get32(image, entry)? as usize != value_at || *last != 0 || name.is_empty() { + return None; + } + let value = image.get(value_at..value_at.checked_add(value_len)?)?; + let next = entry + entry_len(name_len); + let mut pad = [0u8; 3]; + pad[..next - name_end].copy_from_slice(image.get(name_end..next)?); + attrs.push(Attribute { + name: name.to_vec(), + value: value.to_vec(), + pad, + }); + entry = next; + value_at += value_len; + } + if entry != data_start + || value_at != data_start.checked_add(data_len)? + || value_at > fork_at + { + return None; + } + let mut finder = [0u8; FINDER_INFO]; + finder.copy_from_slice(image.get(FINDER_AT..FINDER_AT + FINDER_INFO)?); + Some(Self { + finder, + tag, + attrs, + fork, + len, + }) + } + /// The decoded form of `image` when it encodes back to exactly `image`. + pub fn compact(image: &[u8]) -> Option { + let decoded = Self::parse(image)?; + (decoded.encode() == image).then_some(decoded) + } +} + +/// An attribute entry's bytes for a name of `name_len` bytes with its NUL, +/// rounded up to four. +fn entry_len(name_len: usize) -> usize { + (ENTRY_FIXED + name_len + 3) & !3 +} +/// The empty resource fork: a resource map with no types, after the tag. +fn blank_fork() -> [u8; BLANK_FORK] { + let mut fork = [0u8; BLANK_FORK]; + for (at, value) in [ + (0, 0x100), + (4, 0x100), + (12, 0x1e), + (256, 0x100), + (260, 0x100), + ] { + put32(&mut fork, at, value); + } + put32(&mut fork, 268, 0x1e); + put16(&mut fork, 280, 0x1c); + put16(&mut fork, 282, 0x1e); + put16(&mut fork, 284, 0xffff); + fork[16..16 + BLANK_FORK_TAG.len()].copy_from_slice(BLANK_FORK_TAG); + fork +} +fn put32(out: &mut [u8], at: usize, value: u32) { + out[at..at + 4].copy_from_slice(&value.to_be_bytes()); +} +fn put16(out: &mut [u8], at: usize, value: u16) { + out[at..at + 2].copy_from_slice(&value.to_be_bytes()); +} +fn get32(bytes: &[u8], at: usize) -> Option { + Some(u32::from_be_bytes(bytes.get(at..at + 4)?.try_into().ok()?)) +} +fn get16(bytes: &[u8], at: usize) -> Option { + Some(u16::from_be_bytes(bytes.get(at..at + 2)?.try_into().ok()?)) +} diff --git a/engine/crates/layerfs-nfs/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index f5cb633717..84154c19c1 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -17,6 +17,7 @@ #![forbid(unsafe_code)] pub mod apple_double; +pub mod apple_double_codec; pub mod attributes; mod block; pub mod change; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs new file mode 100644 index 0000000000..8bbfc57412 --- /dev/null +++ b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs @@ -0,0 +1,263 @@ +//! The AppleDouble image codec on its own: what a macOS client's images +//! decode to, and that a decoded one encodes back to the very same bytes. +use layerfs_nfs::apple_double_codec::{Attribute, Fork, Image, IMAGE_UNIT}; + +const FILLER_AT: usize = 8; +const COUNT_AT: usize = 24; +const FINDER_TAG_AT: usize = 26; +const FINDER_ENTRY_AT: usize = 30; +const FINDER_ENTRY_LEN_AT: usize = 34; +const FORK_TAG_AT: usize = 38; +const FORK_AT: usize = 42; +const FORK_LEN_AT: usize = 46; +const FINDER_AT: usize = 50; +const ATTR_AT: usize = 84; +const ATTR_TAG_AT: usize = ATTR_AT + 4; +const ATTR_FORK_AT: usize = ATTR_AT + 8; +const ATTR_DATA_AT: usize = ATTR_AT + 12; +const ATTR_DATA_LEN_AT: usize = ATTR_AT + 16; +const ATTR_COUNT_AT: usize = ATTR_AT + 34; +const ENTRIES_AT: usize = ATTR_AT + 36; + +fn pattern(seed: u32, length: usize) -> Vec { + (0..length) + .map(|n| (n as u32).wrapping_mul(31).wrapping_add(seed * 97) as u8) + .collect() +} +fn image(finder: [u8; 32], tag: u32, attrs: &[(&[u8], Vec)]) -> Image { + let attrs = attrs + .iter() + .map(|(name, value)| Attribute::new(name, value)) + .collect(); + Image::new(finder, tag, attrs).expect("attributes an entry can describe") +} +fn get32(bytes: &[u8], at: usize) -> u32 { + u32::from_be_bytes(bytes[at..at + 4].try_into().unwrap()) +} +fn put32(bytes: &mut [u8], at: usize, value: u32) { + bytes[at..at + 4].copy_from_slice(&value.to_be_bytes()); +} +fn get16(bytes: &[u8], at: usize) -> u16 { + u16::from_be_bytes(bytes[at..at + 2].try_into().unwrap()) +} +/// The decoded form of `image`, required to encode back to the same bytes. +fn whole(image: &Image) -> Vec { + let bytes = image.encode(); + let decoded = Image::compact(&bytes).expect("a whole image decodes"); + assert_eq!(decoded.encode(), bytes, "decoded form re-encodes the image"); + assert_eq!(decoded.finder_info(), image.finder_info()); + assert_eq!(decoded.fork(), image.fork()); + assert_eq!(decoded.len(), bytes.len()); + bytes +} +/// Where the first attribute entry's name ends: its NUL byte. +fn first_name_end(name_len: usize) -> usize { + ENTRIES_AT + 11 + name_len +} + +#[test] +fn values_of_every_size_round_trip() { + for size in [0, 1, 4096, 64 * 1024, 100 * 1024] { + let value = pattern(3, size); + let name = format!("user.size-{size}"); + let attrs: &[(&[u8], Vec)] = &[(name.as_bytes(), value)]; + let built = image([1; 32], 0, attrs); + let bytes = whole(&built); + assert_eq!( + bytes.len() % IMAGE_UNIT, + 0, + "an image is whole {IMAGE_UNIT}-byte units" + ); + assert!(bytes.len() >= size); + let decoded = Image::compact(&bytes).unwrap(); + assert_eq!(decoded.attributes()[0].value.len(), size); + assert_eq!(&decoded.attributes()[0].value, &attrs[0].1); + assert_eq!(&decoded.attributes()[0].name, &attrs[0].0); + assert!(decoded.cost() >= size); + } +} + +#[test] +fn many_attributes_and_finder_info_round_trip() { + let finder = [9u8; 32]; + let attrs: Vec<(Vec, Vec)> = (0..12) + .map(|n| { + ( + format!("user.attr-{n:02}").into_bytes(), + pattern(n, 7 + 13 * n as usize), + ) + }) + .collect(); + let mut with_std = vec![ + (b"com.apple.provenance".to_vec(), pattern(21, 40)), + (b"com.apple.quarantine".to_vec(), pattern(22, 150)), + (b"com.apple.FinderInfo".to_vec(), finder.to_vec()), + ]; + with_std.extend(attrs); + let borrowed: Vec<(&[u8], Vec)> = with_std + .iter() + .map(|(name, value)| (name.as_slice(), value.clone())) + .collect(); + let built = image(finder, 0x2a2a_2a2a, &borrowed); + let bytes = whole(&built); + let decoded = Image::compact(&bytes).unwrap(); + assert_eq!(decoded.finder_info(), finder); + let names: Vec> = decoded + .attributes() + .iter() + .map(|attr| attr.name.clone()) + .collect(); + let expected: Vec> = with_std.iter().map(|(name, _)| name.clone()).collect(); + assert_eq!(names, expected, "entry order is kept"); + for (attr, (_, value)) in decoded.attributes().iter().zip(&with_std) { + assert_eq!(&attr.value, value); + } +} + +#[test] +fn the_clients_alignment_padding_is_kept() { + // A client that rewrote a shorter name does not clear what the longer one + // left behind: the bytes after the NUL stay, and the image must still + // decode to itself. + let attrs: &[(&[u8], Vec)] = &[ + (b"com.example.k4", pattern(5, 32)), + (b"user.other", pattern(6, 8)), + ]; + let mut bytes = image([2; 32], 0, attrs).encode(); + let name_end = first_name_end(b"com.example.k4".len()); + bytes[name_end + 1] = 0x5c; + bytes[name_end + 2] = 0x00; + let decoded = Image::compact(&bytes).expect("kept padding still decodes"); + assert_eq!( + decoded.encode(), + bytes, + "the padding is part of the decoded image" + ); + // A byte the layout leaves unused is not: such an image stays as written. + let mut foreign = bytes.clone(); + let fork_at = get32(&foreign, FORK_AT) as usize; + let data_len = get32(&foreign, ATTR_DATA_LEN_AT) as usize; + let data_start = get32(&foreign, ATTR_DATA_AT) as usize; + foreign[data_start + data_len..fork_at].fill(0x7f); + assert!( + Image::compact(&foreign).is_none(), + "a byte the decoded form does not keep is not claimed" + ); + assert!( + Image::parse(&foreign).is_some(), + "the fields still parse, only the round trip does not hold" + ); +} + +#[test] +fn a_resource_fork_is_left_as_the_client_wrote_it() { + // The client's own empty fork is part of the layout and decodes. + let built = image([3; 32], 0, &[(b"user.a", pattern(7, 16))]); + let bytes = whole(&built); + assert_eq!(Image::compact(&bytes).unwrap().fork(), Fork::Blank); + // The same entry holding other bytes is a real resource fork: the body is + // kept as written, so no fork byte is lost. + let mut fork_data = bytes.clone(); + fork_data[bytes.len() - 286..].fill(0x5a); + assert!(Image::parse(&fork_data).is_some()); + assert!(Image::compact(&fork_data).is_none()); + // A fork of another length is not the layout this codec describes. + let mut longer = bytes.clone(); + put32(&mut longer, FORK_LEN_AT, 300); + assert!(Image::parse(&longer).is_none()); + // An image with a zero-length fork entry decodes too. + let fork_at = get32(&bytes, FORK_AT) as usize; + let mut bare = bytes[..fork_at].to_vec(); + put32(&mut bare, FORK_LEN_AT, 0); + let decoded = Image::compact(&bare).expect("a fork-free image decodes"); + assert_eq!(decoded.fork(), Fork::None); + assert_eq!(decoded.encode(), bare); +} + +#[test] +fn malformed_images_are_not_decoded() { + let good = image( + [4; 32], + 0, + &[(b"user.a", pattern(8, 32)), (b"user.b", pattern(9, 4))], + ) + .encode(); + let fork_at = get32(&good, FORK_AT) as usize; + let data_start = get32(&good, ATTR_DATA_AT) as usize; + let mut cases: Vec<(&str, Vec)> = vec![ + ("empty", Vec::new()), + ("one byte", vec![0]), + ("a truncated header", good[..ENTRIES_AT - 1].to_vec()), + ("a truncated value", good[..data_start + 4].to_vec()), + ("a truncated image", good[..good.len() - 1].to_vec()), + ("an extended image", [good.clone(), vec![0]].concat()), + ]; + let mut each = |name: &'static str, at: usize, value: u32| { + let mut bytes = good.clone(); + put32(&mut bytes, at, value); + cases.push((name, bytes)); + }; + each("another magic", 0, 0x0005_1608); + each("another version", 4, 0x0003_0000); + each("another entry count", COUNT_AT, 3); + each("another FinderInfo tag", FINDER_TAG_AT, 8); + each("another FinderInfo offset", FINDER_ENTRY_AT, 51); + each("another FinderInfo length", FINDER_ENTRY_LEN_AT, 32); + each("another fork tag", FORK_TAG_AT, 1); + each( + "a fork before the entries", + FORK_AT, + (ENTRIES_AT - 1) as u32, + ); + each("a fork past the image", FORK_AT, (good.len() + 1) as u32); + each("another fork length", FORK_LEN_AT, 285); + each("another ATTR magic", ATTR_AT, 0x4154_5453); + each("another ATTR fork", ATTR_FORK_AT, (fork_at - 1) as u32); + each( + "a data start past the fork", + ATTR_DATA_AT, + (fork_at + 1) as u32, + ); + each("a longer data length", ATTR_DATA_LEN_AT, 1024); + each("another entry count", ATTR_COUNT_AT, 3); + each("another value offset", ENTRIES_AT, (data_start + 1) as u32); + let mut filler = good.clone(); + filler[FILLER_AT..FILLER_AT + 16].copy_from_slice(b"Mac OS "); + cases.push(("another filler", filler)); + let mut unterminated = good.clone(); + *unterminated + .get_mut(first_name_end(b"user.a".len())) + .unwrap() = b'X'; + cases.push(("a name without its NUL", unterminated)); + let mut nameless = good.clone(); + let name_len_at = ENTRIES_AT + 10; + assert_eq!(nameless[name_len_at], (b"user.a".len() + 1) as u8); + nameless[name_len_at] = 1; + cases.push(("an empty name", nameless)); + for (name, bytes) in cases { + assert!( + Image::compact(&bytes).is_none(), + "{name} is not claimed as a whole image" + ); + } +} + +#[test] +fn an_image_the_client_would_write_has_whole_units() { + let built = image([6; 32], 0, &[]); + let bytes = built.encode(); + assert_eq!(bytes.len() % IMAGE_UNIT, 0); + assert_eq!(bytes.len(), IMAGE_UNIT, "the smallest image is one unit"); + assert_eq!(get16(&bytes, COUNT_AT), 2); + assert_eq!(get32(&bytes, ATTR_TAG_AT), 0); + assert_eq!( + get32(&bytes, ATTR_DATA_AT) as usize, + ENTRIES_AT, + "no attribute, no entry" + ); + assert_eq!(bytes[FINDER_AT..FINDER_AT + 32], [6; 32]); + // An image whose FinderInfo the client filled and whose tag is its own. + let tagged = image([7; 32], 0x1234_5678, &[]); + let bytes = whole(&tagged); + assert_eq!(get32(&bytes, ATTR_TAG_AT), 0x1234_5678); +} From fa5dd34b5ff99a48aac38133deeac8573ca8e9e1 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:19:28 +0000 Subject: [PATCH 03/17] feat(nfs): hold a whole AppleDouble image as its own attributes (lp73) A macOS client writes each companion once, in full, and reads it back unchanged. A body is therefore classified whenever a write or a resize leaves it: one that parses back to the very bytes the companion holds (`Image::compact`) and fits `DECODED_ENTRY_BYTES` is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` instead of its image, and every READ synthesizes the same bytes again. Anything else - a resource fork, another layout, a half-written image - is stored as the client wrote it. This replaces `TOTAL_BYTES` with two budgets that say what they bound: `RESIDENT_BYTES` (32 MiB) of written bodies kept in memory, and `DECODED_BYTES` (512 MiB) of decoded ones counted as `Image::cost`. A write or resize that neither decodes nor fits the resident budget answers `NFS3ERR_NOSPC` and leaves the companion exactly as it was; the next layer spills those bodies to disk instead of refusing them. `Released` now reports `companions_decoded` and `companion_decoded_bytes`, and `companions_release`/`companions_held` answer the `Holding` record the counters live in. Second layer of the AppleDouble split (LP636), on top of the codec. Tests: new `tests/apple_double_decode.rs` with the client's own write sequence (a half-written header, the rest, an edit that breaks the image and one that completes it again, truncate below and resize back up), read back byte for byte. Full `layerfs-nfs` suite: 41 passed, 0 failed. Production LOC: 163792 -> 163886 (delta +94) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 210d5f8ab (163792) and this tree (163886). Engine +94. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 249 ++++++++++++++---- .../crates/layerfs-nfs/src/kernel/released.rs | 34 +-- .../layerfs-nfs/tests/apple_double_decode.rs | 142 ++++++++++ 3 files changed, 351 insertions(+), 74 deletions(-) create mode 100644 engine/crates/layerfs-nfs/tests/apple_double_decode.rs diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 4f2e2eb4c8..c96d1c8b6a 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -16,11 +16,19 @@ //! directory it names, so its `wcc_data` answers both halves from the last //! facts the export saw for it (see [`Kernel::directory_wcc`]). //! -//! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] -//! each and [`TOTAL_BYTES`] in all. Beyond the count a creation is refused -//! (`NFS3ERR_ACCES`, as before this module), beyond the bytes a write -//! (`NFS3ERR_FBIG` per file, `NFS3ERR_NOSPC` in all). +//! Whenever a write leaves a companion holding a whole AppleDouble image the +//! client laid out itself (see [`crate::apple_double_codec`]), it is decoded: a +//! small one keeps only its FinderInfo and attributes in memory (at most +//! [`DECODED_BYTES`] in all, each at most [`DECODED_ENTRY_BYTES`]), and every +//! read synthesizes the same bytes again. +//! +//! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] each, +//! [`RESIDENT_BYTES`] of written bodies and [`DECODED_BYTES`] of decoded ones +//! counted as [`Image::cost`]. Beyond the count a creation is refused +//! (`NFS3ERR_ACCES`, as before this module), beyond a file's bytes a write +//! (`NFS3ERR_FBIG`), beyond the resident body budget a write (`NFS3ERR_NOSPC`). use crate::{ + apple_double_codec::Image, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, @@ -41,23 +49,62 @@ pub const SERIALS: u64 = 1 << 62; pub const HELD: usize = 4096; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; -/// Bytes kept over all companions. -pub const TOTAL_BYTES: usize = 64 << 20; +/// Companion payload bytes kept resident in memory before a write is refused. +pub const RESIDENT_BYTES: usize = 32 << 20; +/// Bytes counted for all decoded companions (see [`Image::cost`]). +pub const DECODED_BYTES: usize = 512 << 20; +/// Bytes counted for one decoded companion; a larger whole image keeps its +/// bytes as written. +pub const DECODED_ENTRY_BYTES: usize = 128 << 10; /// Mode of a companion created without one. const MODE: u32 = 0o644; +enum Body { + Resident(Vec), + /// A whole image kept as its FinderInfo and attributes; a read encodes the + /// image again, byte for byte as the client wrote it. + Decoded(Image), +} + struct Companion { + /// The `._` name it was created or last renamed to. named: (u64, Vec), - data: Vec, + len: usize, + body: Body, metadata: PortableMetadata, } +impl Companion { + fn resident_len(&self) -> usize { + match &self.body { + Body::Resident(bytes) => bytes.len(), + Body::Decoded(_) => 0, + } + } + fn decoded_cost(&self) -> usize { + match &self.body { + Body::Decoded(image) => image.cost(), + Body::Resident(_) => 0, + } + } +} + +/// What an export's companion index holds (see [`crate::kernel::Released`]). +#[derive(Clone, Copy, Debug, Default)] +pub(crate) struct Holding { + pub held: usize, + pub decoded: usize, + pub decoded_bytes: usize, +} + /// The companions of one export. #[derive(Default)] pub(crate) struct Companions { next: u64, files: HashMap, names: HashMap<(u64, Vec), u64>, - bytes: usize, + resident_bytes: usize, + decoded: usize, + decoded_bytes: usize, } impl Companions { pub(crate) fn len(&self) -> usize { @@ -69,31 +116,104 @@ impl Companions { kind: InodeKind::RegularFile, metadata: file.metadata, namespace_refs: 1, - logical_len: file.data.len() as u64, + logical_len: file.len as u64, subdirs: 0, } } + /// Adds `file` to the index and to the byte counts. + fn attach(&mut self, serial: u64, file: Companion) { + self.resident_bytes += file.resident_len(); + self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); + self.decoded_bytes += file.decoded_cost(); + self.files.insert(serial, file); + } + /// Takes `serial` out of the index and the counts; its name key stays for + /// the caller to unindex. + fn detach(&mut self, serial: u64) -> Option { + let file = self.files.remove(&serial)?; + self.resident_bytes -= file.resident_len(); + self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); + self.decoded_bytes -= file.decoded_cost(); + Some(file) + } + /// Drops `serial` and its name key. fn drop_serial(&mut self, serial: u64) { - if let Some(file) = self.files.remove(&serial) { + if let Some(file) = self.detach(serial) { self.names.remove(&file.named); - self.bytes -= file.data.len(); } } - /// Resizes `serial` to `size`, within the bounds. - fn resize(&mut self, serial: u64, size: u64) -> Result<(), Status> { - if size > FILE_BYTES { - return Err(Status::FBig); + /// Decides whether `file`'s body is a whole image: one that parses back to + /// the same bytes and that the decoded budget takes. `file` must be + /// detached from the index. + fn classify(&self, file: &mut Companion) { + let Body::Resident(bytes) = &file.body else { + return; + }; + let Some(image) = Image::compact(bytes) else { + return; + }; + let cost = image.cost(); + if cost <= DECODED_ENTRY_BYTES && self.decoded_bytes + cost <= DECODED_BYTES { + file.body = Body::Decoded(image); } - let file = self.files.get_mut(&serial).ok_or(Status::Stale)?; - let old = file.data.len(); - let new = size as usize; - if new > old && self.bytes + (new - old) > TOTAL_BYTES { + } + /// Replaces `serial`'s body by `len` bytes built from it by `apply`, kept + /// within the budgets: a body that decodes costs its attributes, not its + /// bytes, and any other body stays in memory only while [`RESIDENT_BYTES`] + /// takes it. All of it or nothing: a body the budgets cannot take leaves + /// the companion exactly as it was. + fn edit_body( + &mut self, + serial: u64, + len: usize, + apply: impl FnOnce(&mut Vec), + ) -> Result<(), Status> { + let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); + let mut file = self.detach(serial).ok_or(Status::Stale)?; + let need = len.saturating_sub(file.resident_len()); + let before_len = file.len; + let original = std::mem::replace(&mut file.body, Body::Resident(Vec::new())); + let mut bytes = match &original { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + }; + bytes.resize(len, 0); + apply(&mut bytes); + file.body = Body::Resident(bytes); + file.len = len; + self.classify(&mut file); + if need > avail && !matches!(file.body, Body::Decoded(_)) { + // The body does not decode and the resident budget does not take + // it: the companion keeps what it had and the caller answers NOSPC. + file.body = original; + file.len = before_len; + self.attach(serial, file); return Err(Status::NoSpc); } - file.data.resize(new, 0); - self.bytes = self.bytes + new - old; + touch(&mut file.metadata); + self.attach(serial, file); Ok(()) } + /// Applies a write to `serial`'s body; a write keeps what the body held + /// beyond its end. + fn write(&mut self, serial: u64, offset: usize, data: &[u8]) -> Result<(), Status> { + let file = self.files.get(&serial).ok_or(Status::Stale)?; + let len = file.len.max(offset + data.len()); + self.edit_body(serial, len, |bytes| { + bytes[offset..offset + data.len()].copy_from_slice(data); + }) + } + /// Resizes `serial` to `size`, within the bounds. + fn resize(&mut self, serial: u64, size: usize) -> Result<(), Status> { + self.edit_body(serial, size, |_| {}) + } + fn holding(&self) -> Holding { + Holding { + held: self.files.len(), + decoded: self.decoded, + decoded_bytes: self.decoded_bytes, + } + } } fn now() -> PortableMetadata { let elapsed = SystemTime::now() @@ -181,17 +301,15 @@ impl Kernel { let serial = SERIALS + companions.next; companions.next += 1; let named = (parent, name.to_vec()); - companions.names.insert(named.clone(), serial); - companions.files.insert( - serial, - Companion { - named, - data: Vec::new(), - metadata, - }, - ); - let file = &companions.files[&serial]; - let stat = Companions::stat(serial, file); + let file = Companion { + named, + len: 0, + body: Body::Resident(Vec::new()), + metadata, + }; + let stat = Companions::stat(serial, &file); + companions.names.insert(file.named.clone(), serial); + companions.attach(serial, file); drop(companions); self.names_detached.fetch_add(1, Ordering::Relaxed); Ok((stat, directory)) @@ -201,7 +319,7 @@ impl Kernel { pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { { let mut companions = self.companions(); - let serial = companions.names.get(&(parent, name.to_vec())).copied()?; + let serial = *companions.names.get(&(parent, name.to_vec()))?; companions.drop_serial(serial); } Some(self.directory_wcc(parent)) @@ -244,10 +362,23 @@ impl Kernel { ) -> Result { let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let length = file.data.len() as u64; + let length = file.len as u64; let start = offset.min(length) as usize; let end = offset.saturating_add(u64::from(count)).min(length) as usize; - out.extend_from_slice(&file.data[start..end]); + match &file.body { + Body::Resident(bytes) => { + // A body and its length are recorded under one lock; clamp + // anyway so no reply slices past the bytes it holds. + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + } + Body::Decoded(image) => { + // The image the client wrote, synthesized again. + let bytes = image.encode(); + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + } + } Ok(end as u64 >= length) } /// WRITE to a companion: all of it or nothing. @@ -257,18 +388,17 @@ impl Kernel { offset: u64, data: &[u8], ) -> Result<(u32, Wcc), Status> { - let mut companions = self.companions(); let end = offset.checked_add(data.len() as u64).ok_or(Status::FBig)?; + if end > FILE_BYTES { + return Err(Status::FBig); + } + let mut companions = self.companions(); let before = { let file = companions.files.get(&serial).ok_or(Status::Stale)?; Companions::stat(serial, file) }; - if end > before.logical_len { - companions.resize(serial, end)?; - } - let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.data[offset as usize..end as usize].copy_from_slice(data); - touch(&mut file.metadata); + companions.write(serial, offset as usize, data)?; + let file = companions.files.get(&serial).ok_or(Status::Stale)?; let after = Companions::stat(serial, file); Ok((data.len() as u32, (Some(before), Some(after)))) } @@ -287,19 +417,24 @@ impl Kernel { if foreign { return Err(Status::Perm); } - let mut companions = self.companions(); let before = { + let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - Companions::stat(serial, file) - }; - if let Some(expected) = guard { - if crate::attributes::ctime(&before) != expected { - return Err(Status::NotSync); + let before = Companions::stat(serial, file); + if let Some(expected) = guard { + if crate::attributes::ctime(&before) != expected { + return Err(Status::NotSync); + } } - } + before + }; if let Some(size) = sattr.size { - companions.resize(serial, size)?; + if size > FILE_BYTES { + return Err(Status::FBig); + } + self.companions().resize(serial, size as usize)?; } + let mut companions = self.companions(); let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; if let Some(mode) = sattr.mode { file.metadata.mode = mode & 0o777; @@ -316,15 +451,15 @@ impl Kernel { let after = Companions::stat(serial, file); Ok((after.clone(), (Some(before), Some(after)))) } - /// Drops every companion; their count. - pub(crate) fn companions_release(&self) -> usize { + /// Drops every companion; what the index held. + pub(crate) fn companions_release(&self) -> Holding { let mut companions = self.companions(); - let held = companions.len(); + let holding = companions.holding(); *companions = Companions::default(); - held + holding } - /// Companions held now. - pub(crate) fn companions_held(&self) -> usize { - self.companions().len() + /// What the companion index holds now. + pub(crate) fn companions_held(&self) -> Holding { + self.companions().holding() } } diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index 5259b14be9..f765a6177d 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -2,7 +2,7 @@ //! //! [`Kernel::release`] runs once, before the engine mount is revoked; [`Kernel::held`] //! reports the same counts while the export serves, for diagnostics. -use super::Kernel; +use super::{Kernel, Table}; use std::sync::atomic::Ordering; impl Kernel { @@ -12,20 +12,7 @@ impl Kernel { pub fn release(&self) -> Released { let table = std::mem::take(&mut *self.table()); let companions = self.companions_release(); - let released = Released { - companions, - files: table.files.len(), - directories: table.directories.len(), - lookups: table.lookups.len(), - silly: table.silly.len(), - retained: self.retained_count(), - silly_renamed: self.silly_renamed.load(Ordering::Relaxed), - names_refused: self.names_refused.load(Ordering::Relaxed), - names_detached: self.names_detached.load(Ordering::Relaxed), - collected: self.collected.load(Ordering::Relaxed), - resolved: self.resolved.load(Ordering::Relaxed), - unresolved: self.unresolved.load(Ordering::Relaxed), - }; + let released = self.holdings(&table, companions); for (serial, held) in table.files { self.close_file(serial, held.handle); } @@ -48,8 +35,16 @@ impl Kernel { /// Current holdings, for diagnostics. pub fn held(&self) -> Released { let table = self.table(); + let companions = self.companions_held(); + self.holdings(&table, companions) + } + + /// What this export holds now, as [`Released`] reports it. + fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { Released { - companions: self.companions_held(), + companions: companions.held, + companions_decoded: companions.decoded, + companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -79,8 +74,13 @@ pub struct Released { pub silly_renamed: u64, /// Creations refused for their AppleDouble name, over the export's life. pub names_refused: u64, - /// AppleDouble companions held in memory (see [`crate::apple_double`]). + /// AppleDouble companions held in the export's index (see + /// [`crate::apple_double`]). pub companions: usize, + /// Of the companions held, those kept decoded, and the bytes counted for + /// them. + pub companions_decoded: usize, + pub companion_decoded_bytes: usize, /// AppleDouble companions created, over the export's life. pub names_detached: u64, /// References collected beyond the bound, over the export's life. diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs new file mode 100644 index 0000000000..7acd47a903 --- /dev/null +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -0,0 +1,142 @@ +//! AppleDouble companions decoded into their attributes: a `._` a macOS +//! client writes as a whole image is kept as its FinderInfo and extended +//! attributes, and every read synthesizes the very bytes the client wrote. A +//! body that is not a whole image (a resource fork, another layout, a +//! half-written one) is stored as the client wrote it. +#[allow(dead_code)] +#[path = "support/client.rs"] +mod client; +#[allow(dead_code)] +#[path = "support/rig.rs"] +mod rig; +#[allow(dead_code)] +#[path = "support/spy.rs"] +mod spy; +#[allow(dead_code)] +#[path = "support/tree.rs"] +mod tree; +use client::{Client, Set, STALE}; +use layerfs_nfs::apple_double_codec::{Attribute, Image}; +use std::{ + fs, + net::TcpListener, + path::{Path, PathBuf}, + time::Duration, +}; + +const UID: u32 = 501; +const GID: u32 = 20; + +fn temp(label: &str) -> PathBuf { + std::env::temp_dir().join(format!("layerfs-nfs-ad{}-{label}", std::process::id())) +} +fn source(root: &Path) { + fs::create_dir_all(root.join("docs")).unwrap(); + fs::write(root.join("README.md"), b"# fixture\nhello nfs\n").unwrap(); + fs::write(root.join("docs/guide.md"), b"guide\n").unwrap(); +} +fn pattern(seed: u32, length: usize) -> Vec { + (0..length) + .map(|n| (n as u32).wrapping_mul(31).wrapping_add(seed * 97) as u8) + .collect() +} +/// The image a macOS client writes for these attributes. +fn image(finder: [u8; 32], attrs: &[(&[u8], Vec)]) -> Vec { + let attrs = attrs + .iter() + .map(|(name, value)| Attribute::new(name, value)) + .collect(); + Image::new(finder, 0, attrs) + .expect("an entry can describe these attributes") + .encode() +} + +#[test] +fn the_clients_write_sequence_is_served_byte_for_byte() { + let base = temp("sequence"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + let main = c.touch(&root, b"seq", 0o644).unwrap(); + c.write(&main.handle, 0, b"data").unwrap(); + let ad = c.touch(&root, b"._seq", 0o644).unwrap(); + let whole = image( + [0x33; 32], + &[ + (b"com.apple.provenance", pattern(6, 40)), + (b"user.big", pattern(7, 4096)), + ], + ); + // The client writes the header first: a half-written image is served + // exactly as written and never claimed as a whole one. + c.write(&ad.handle, 0, &whole[..50]).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, 50); + assert_eq!(c.read_all(&ad.handle, 4096), whole[..50]); + assert_eq!(server.held().companions_decoded, 0); + // The rest arrives: the image is whole now and reads synthesize it. + c.write(&ad.handle, 50, &whole[50..]).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions_decoded, 1); + + // A delete and rebuild starts empty and decodes the rewrite again. + c.remove(&root, b"._seq").unwrap(); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + let again = c.touch(&root, b"._seq", 0o644).unwrap(); + assert_eq!(again.attr.size, 0); + assert_eq!(c.read_all(&again.handle, 4096), Vec::::new()); + let rebuilt = image( + [0x44; 32], + &[ + (b"com.apple.provenance", pattern(8, 40)), + (b"user.other", pattern(9, 64 * 1024)), + ], + ); + c.write(&again.handle, 0, &rebuilt).unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + + // An edit that leaves the image not whole is served as written, and a + // later edit that completes it decodes again: both are the client's own + // bytes. + let mut edited = rebuilt.clone(); + edited[24..28].copy_from_slice(b"EDIT"); + c.write(&again.handle, 24, b"EDIT").unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), edited); + assert_eq!(server.held().companions_decoded, 0); + c.write(&again.handle, 24, &rebuilt[24..28]).unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + assert_eq!(server.held().companions_decoded, 1); + + // Truncating below the image is served as the client's truncation, and + // resizing back up serves zeros, as on any file. + let shrink = Set { + size: Some(64), + ..Set::default() + }; + c.setattr(&again.handle, shrink, None).unwrap(); + assert_eq!(c.read_all(&again.handle, 4096), rebuilt[..64]); + let grow = Set { + size: Some(rebuilt.len() as u64), + ..Set::default() + }; + c.setattr(&again.handle, grow, None).unwrap(); + let mut zeros = rebuilt[..64].to_vec(); + zeros.resize(rebuilt.len(), 0); + assert_eq!(c.read_all(&again.handle, 128 * 1024), zeros); + c.write(&again.handle, 0, &rebuilt).unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + + // The companion never reaches the Workspace. + let (entries, _) = c.list(&root, 64 * 1024, true); + assert!(entries.iter().all(|entry| !entry.name.starts_with(b"._"))); + drop(c); + let released = server.stop(); + assert_eq!(released.companions_decoded, 1); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + From 584cc3e66f34f749d82b85b922520f3abc347ff2 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:21:27 +0000 Subject: [PATCH 04/17] docs(nfs): document the decoded AppleDouble companion (lp73) The NFS route guide now names `apple_double_codec.rs` and states what each bound actually holds: `RESIDENT_BYTES` for written bodies and `DECODED_BYTES` / `DECODED_ENTRY_BYTES` for the decoded form, replacing the `TOTAL_BYTES` row the code no longer has. The paragraph after the table says which bodies decode (complete images that encode back to the same bytes) and which stay as written. Documentation only; it describes the codec layer as it stands. Production LOC: 163886 -> 163886 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent fa5dd34b5 (163886) and this tree (163886). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 4c8f4e0325..3b2db39e69 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -163,7 +163,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | The refresh never writes into the Workspace and never reverts a mode the install changed | [`refresh.rs`](../../../../engine/crates/layerfs-nfs/src/refresh.rs) | | `LAYERFS_NFS_REFRESH=0` leaves the client to `actimeo` and close-to-open | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -## AppleDouble files (`apple_double.rs`) +## AppleDouble files (`apple_double.rs`, `apple_double_codec.rs`) On NFSv3 the macOS client keeps extended attributes and resource forks in `._` files. With `refuse_apple_double`, a regular `._` file (at least @@ -174,11 +174,20 @@ never lists it and the engine is never called. Any other kind is `NFS3ERR_ACCES`. `cp`, `copyfile`, `ditto` and `tar` succeed while nothing reaches the Workspace or a Commit; everything is dropped with the export. -| Bound | Value | Over the bound | -| --- | --- | --- | -| `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | -| `FILE_BYTES` | 1 MiB per companion | WRITE `NFS3ERR_FBIG` | -| `TOTAL_BYTES` | 64 MiB in all | WRITE `NFS3ERR_NOSPC` | +| Bound | Value | Over the bound | Source | +| --- | --- | --- | --- | +| `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB resident bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | + +A body a write or resize leaves as a complete AppleDouble image that encodes +back to the exact bytes the companion holds +([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)) +is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` +rather than its image, and every READ synthesizes the same bytes again. Partial +writes, resource forks and other layouts stay as the client wrote them. ## Mount (`mount.rs`, daemon `export.rs`) From 7b38dadc92b37558464e03d31665c7af551d35ee Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:36:30 +0000 Subject: [PATCH 05/17] feat(nfs): spill AppleDouble companion bodies beyond the resident budget (lp73) A client's companion body no longer has to fit in memory and no longer takes memory from every other export. Bodies beyond `RESIDENT_BYTES` (32 MiB) are spilled, least recently touched first, to a scratch directory of the export's own (`/.appledouble//`), and a write that still does not fit the budget after bounded eviction rounds is written out itself and edited in its file, which needs no budget at all. - `apple_double_spill.rs` owns the scratch files: one per companion serial, directory `0700` and files `0600` whatever the umask, written through a `..tmp` that only the adopting call renames to ``, no fsync and no space reserved ahead. A spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open, so companions far outnumbering the process's file limit all work. A failed file operation is answered with the NFS status its errno means (`ENOSPC`/`EDQUOT`, `EFBIG`, `EACCES`, `EPERM`, `EROFS`, else `NFS3ERR_IO`). - `apple_double/edit.rs` holds READ, WRITE and SETATTR and the eviction: one edit of a companion at a time under that companion's own gate, so a truncate and a write can never leave a length its file does not have, and the file I/O never holds the companion lock. - `ExportConfig` gains `companion_spill_dir` and `companion_resident_bytes`. The daemon gives each export `/.appledouble/`, removes it at startup before any Attach, at release and when a failed Attach unwinds, and touches nothing else under the mount home. - `Released` reports `companion_bytes`. Third layer of the AppleDouble split (LP636), on top of the codec; `HELD` and the name index are the layer after this one. Production LOC: 163886 -> 164334 (delta +448) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 584cc3e66 (163886) and this tree (164334). Engine +448, the daemon's `export.rs` share included. Tests for the layer follow in the next commit. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- Cargo.lock | 1 + .../layerfs-daemon/src/control/export.rs | 51 +- engine/crates/layerfs-nfs/Cargo.toml | 1 + engine/crates/layerfs-nfs/src/apple_double.rs | 492 +++++++++--------- .../layerfs-nfs/src/apple_double/edit.rs | 366 +++++++++++++ .../layerfs-nfs/src/apple_double_spill.rs | 151 ++++++ .../crates/layerfs-nfs/src/kernel/released.rs | 3 + engine/crates/layerfs-nfs/src/lib.rs | 1 + engine/crates/layerfs-nfs/src/server.rs | 21 +- 9 files changed, 833 insertions(+), 254 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/apple_double/edit.rs create mode 100644 engine/crates/layerfs-nfs/src/apple_double_spill.rs diff --git a/Cargo.lock b/Cargo.lock index df7846f28a..4a063b0316 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -871,6 +871,7 @@ dependencies = [ "layerfs-storage", "layerfs-telemetry", "layerfs-workspace", + "libc", ] [[package]] diff --git a/engine/crates/layerfs-daemon/src/control/export.rs b/engine/crates/layerfs-daemon/src/control/export.rs index ead80216dd..2128e08893 100644 --- a/engine/crates/layerfs-daemon/src/control/export.rs +++ b/engine/crates/layerfs-daemon/src/control/export.rs @@ -179,27 +179,44 @@ impl ExportServing { fn directory(&self, token: WorkspaceToken) -> PathBuf { self.config.mounts.join(token.namespace.to_string()) } + fn companion_spill_dir(&self, token: WorkspaceToken) -> PathBuf { + self.spill_root().join(token.namespace.to_string()) + } + /// Every companion's scratch directory lives below this one, outside the + /// mount home's mounts. + fn spill_root(&self) -> PathBuf { + self.config.mounts.join(".appledouble") + } /// At startup, before any Attach: every mount the host still has at or /// under the mount home is one a daemon that ended without unmounting /// left (its export is gone, so the client would hang on it). Each is /// forced off once with the force helper; one line per mount says what - /// happened. Nothing is retried. + /// happened. Nothing is retried. The companions' scratch directories of + /// that daemon belong to exports that are gone too, so they go as well; + /// nothing else under the mount home is touched. pub fn reclaim(&self) -> Vec { + let mut lines = Vec::new(); + let spill = self.spill_root(); + if std::fs::remove_dir_all(&spill).is_ok() { + lines.push(format!("removed leftovers under {}", spill.display())); + } let points = match mounted_under(&self.config.mounts) { Ok(points) => points, - Err(error) => return vec![format!("mount table unreadable: {error}")], + Err(error) => { + lines.push(format!("mount table unreadable: {error}")); + return lines; + } }; - (points.into_iter()) - .map(|point| { - let text = point.display().to_string(); - match self.helpers.run(&self.config.mounter.force, 0, &text) { - Ran::Done => format!("forced off {text}"), - Ran::Busy(detail) | Ran::Failed(detail) | Ran::Interrupted(detail) => { - format!("left {text}: {detail}") - } + lines.extend((points.into_iter()).map(|point| { + let text = point.display().to_string(); + match self.helpers.run(&self.config.mounter.force, 0, &text) { + Ran::Done => format!("forced off {text}"), + Ran::Busy(detail) | Ran::Failed(detail) | Ran::Interrupted(detail) => { + format!("left {text}: {detail}") } - }) - .collect() + } + })); + lines } } /// Mount points at or under `home`, deepest first, from the host's table: @@ -481,12 +498,10 @@ impl Service { } }; let export = ExportConfig { - path: "/".into(), - uid: config.command_uid, - gid: config.command_gid, - read_only: false, refuse_apple_double: config.refuse_apple_double, lookups_held: config.lookups_held, + companion_spill_dir: Some(serving.companion_spill_dir(token)), + ..ExportConfig::writable(config.command_uid, config.command_gid) }; let started = TcpListener::bind((config.listen, 0)).and_then(|listener| { Server::start( @@ -531,6 +546,7 @@ impl Service { Ran::Busy(detail) | Ran::Failed(detail) => { let released = server.stop(); drop(std::fs::remove_dir(&directory)); + drop(std::fs::remove_dir(serving.spill_root())); return Err(self.unwind_export( workspace, mount, @@ -751,6 +767,9 @@ impl Service { return Err(Failure::Retained(Box::new(reply))); } drop(std::fs::remove_dir(&ready.directory)); + if let Some(serving) = self.export.as_ref() { + drop(std::fs::remove_dir(serving.spill_root())); + } if let Ok(mut entries) = self.entries.lock() { if let Ok(binding) = bound_mut(&mut entries, token) { binding.kernel = Kernel::Unattached; diff --git a/engine/crates/layerfs-nfs/Cargo.toml b/engine/crates/layerfs-nfs/Cargo.toml index 63bb04f3d1..309e571a94 100644 --- a/engine/crates/layerfs-nfs/Cargo.toml +++ b/engine/crates/layerfs-nfs/Cargo.toml @@ -20,3 +20,4 @@ layerfs-persistence = { path = "../layerfs-persistence" } layerfs-project = { path = "../layerfs-project" } layerfs-storage = { path = "../../../core/crates/layerfs-storage" } layerfs-telemetry = { path = "../../../core/crates/layerfs-telemetry" } +libc = "=0.2.189" diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index c96d1c8b6a..98fe0a665a 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -3,11 +3,11 @@ //! On NFSv3 the macOS client keeps a file's extended attributes and resource //! fork in a `._` companion file (see [`crate::names`]). When the export //! keeps such names out of the Workspace, a CREATE of one makes a file that -//! lives only here, in memory, under its own serial range: LOOKUP, GETATTR, -//! ACCESS, READ, WRITE, SETATTR, COMMIT, REMOVE and a RENAME to another -//! AppleDouble name work on it, READDIR does not list it, and no mutation of -//! it ever reaches the engine, so the Workspace stays clean and no Commit can -//! capture it. Everything is dropped when the export is released. +//! lives only here, under its own serial range: LOOKUP, GETATTR, ACCESS, READ, +//! WRITE, SETATTR, COMMIT, REMOVE and a RENAME to another AppleDouble name +//! work on it, READDIR does not list it, and no mutation of it ever reaches +//! the engine, so the Workspace stays clean and no Commit can capture it. +//! Everything is dropped when the export is released. //! //! The tree is not consulted for such a name: while this mode is on, a //! LOOKUP of a `._` name answers `NFS3ERR_NOENT` unless the export holds that @@ -20,47 +20,58 @@ //! client laid out itself (see [`crate::apple_double_codec`]), it is decoded: a //! small one keeps only its FinderInfo and attributes in memory (at most //! [`DECODED_BYTES`] in all, each at most [`DECODED_ENTRY_BYTES`]), and every -//! read synthesizes the same bytes again. +//! read synthesizes the same bytes again. Any other body (a resource fork, +//! another layout, a half-written image) is kept as the client wrote it. //! //! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] each, //! [`RESIDENT_BYTES`] of written bodies and [`DECODED_BYTES`] of decoded ones -//! counted as [`Image::cost`]. Beyond the count a creation is refused -//! (`NFS3ERR_ACCES`, as before this module), beyond a file's bytes a write -//! (`NFS3ERR_FBIG`), beyond the resident body budget a write (`NFS3ERR_NOSPC`). +//! counted as [`Image::cost`]. Bodies up to that budget stay in memory; when a +//! write or resize crosses it, the least recently touched resident bodies are +//! spilled to the export's own scratch directory (see +//! [`crate::apple_double_spill`]), and a body that still does not fit is +//! written out itself. Everything is dropped when the export is released, +//! which removes that directory too. use crate::{ apple_double_codec::Image, + apple_double_spill::{io_status, now, spill_path, touch, unlink_paths, Edit}, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, }; use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; -use layerfs_mount_ports::operations::write::Stamp; use layerfs_workspace::ViewStat; use std::{ collections::HashMap, - sync::atomic::Ordering, - time::{SystemTime, UNIX_EPOCH}, + fs, + path::{Path, PathBuf}, + sync::{atomic::Ordering, Arc, Mutex}, }; +mod edit; + /// The first serial of the export's own companions, far above any serial the /// engine allocates. pub const SERIALS: u64 = 1 << 62; -/// Companions held at once. +/// Companion index entries held at once. pub const HELD: usize = 4096; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; -/// Companion payload bytes kept resident in memory before a write is refused. +/// Companion payload bytes kept resident in memory before spilling to disk. pub const RESIDENT_BYTES: usize = 32 << 20; /// Bytes counted for all decoded companions (see [`Image::cost`]). pub const DECODED_BYTES: usize = 512 << 20; /// Bytes counted for one decoded companion; a larger whole image keeps its /// bytes as written. pub const DECODED_ENTRY_BYTES: usize = 128 << 10; -/// Mode of a companion created without one. -const MODE: u32 = 0o644; + +/// A name in one directory: (directory serial, name bytes). +type Named = (u64, Vec); enum Body { Resident(Vec), + /// On disk in the spill directory, under the companion's own serial; each + /// operation opens it by path instead of holding it open. + Spilled, /// A whole image kept as its FinderInfo and attributes; a read encodes the /// image again, byte for byte as the client wrote it. Decoded(Image), @@ -68,22 +79,28 @@ enum Body { struct Companion { /// The `._` name it was created or last renamed to. - named: (u64, Vec), + named: Named, len: usize, body: Body, metadata: PortableMetadata, + used: u64, + /// One edit of this companion at a time: its body's bytes, its length and + /// its spilled file change together, so a truncate and a write can never + /// leave a length its file does not have, and no round has to decide + /// again on a body another call changed under it. + editing: Arc>, } impl Companion { fn resident_len(&self) -> usize { match &self.body { Body::Resident(bytes) => bytes.len(), - Body::Decoded(_) => 0, + Body::Spilled | Body::Decoded(_) => 0, } } fn decoded_cost(&self) -> usize { match &self.body { Body::Decoded(image) => image.cost(), - Body::Resident(_) => 0, + Body::Resident(_) | Body::Spilled => 0, } } } @@ -92,23 +109,48 @@ impl Companion { #[derive(Clone, Copy, Debug, Default)] pub(crate) struct Holding { pub held: usize, + pub resident_bytes: usize, pub decoded: usize, pub decoded_bytes: usize, } /// The companions of one export. -#[derive(Default)] pub(crate) struct Companions { next: u64, + tick: u64, files: HashMap, - names: HashMap<(u64, Vec), u64>, + names: HashMap, resident_bytes: usize, decoded: usize, decoded_bytes: usize, + spill_dir: Option, + resident_budget: usize, +} +impl Default for Companions { + fn default() -> Self { + Self { + next: 0, + tick: 0, + files: HashMap::new(), + names: HashMap::new(), + resident_bytes: 0, + decoded: 0, + decoded_bytes: 0, + spill_dir: None, + resident_budget: RESIDENT_BYTES, + } + } } impl Companions { - pub(crate) fn len(&self) -> usize { - self.files.len() + fn tick(&mut self) -> u64 { + self.tick += 1; + self.tick + } + fn use_serial(&mut self, serial: u64) { + let tick = self.tick(); + if let Some(file) = self.files.get_mut(&serial) { + file.used = tick; + } } fn stat(serial: u64, file: &Companion) -> ViewStat { ViewStat { @@ -136,16 +178,39 @@ impl Companions { self.decoded_bytes -= file.decoded_cost(); Some(file) } - /// Drops `serial` and its name key. - fn drop_serial(&mut self, serial: u64) { - if let Some(file) = self.detach(serial) { - self.names.remove(&file.named); + /// Replaces `serial`'s body by the decoded form of `bytes`, the caller's + /// edited body of `len` bytes, when the decoded budget takes it. The + /// decoded form costs its attributes rather than its image, so a body that + /// decodes needs no resident budget at all. + fn keep_decoded(&mut self, serial: u64, bytes: &[u8], len: usize) -> bool { + let Some(image) = Image::compact(bytes) else { + return false; + }; + if image.cost() > DECODED_ENTRY_BYTES { + return false; + } + let cost = image.cost(); + let tick = self.tick(); + let Some(mut file) = self.detach(serial) else { + return false; + }; + if self.decoded_bytes + cost > DECODED_BYTES { + self.attach(serial, file); + return false; } + file.len = len; + file.body = Body::Decoded(image); + file.used = tick; + touch(&mut file.metadata); + self.attach(serial, file); + true } - /// Decides whether `file`'s body is a whole image: one that parses back to - /// the same bytes and that the decoded budget takes. `file` must be - /// detached from the index. + /// Decides whether `file`'s body is a whole image: a resident one is + /// decoded when it parses back to the same bytes and the decoded budget + /// takes it. `file` must be detached from the index. fn classify(&self, file: &mut Companion) { + // A body on disk cannot be decoded here (that reads its file under + // this lock): it keeps the class the write that spilled it left it. let Body::Resident(bytes) = &file.body else { return; }; @@ -157,78 +222,86 @@ impl Companions { file.body = Body::Decoded(image); } } - /// Replaces `serial`'s body by `len` bytes built from it by `apply`, kept - /// within the budgets: a body that decodes costs its attributes, not its - /// bytes, and any other body stays in memory only while [`RESIDENT_BYTES`] - /// takes it. All of it or nothing: a body the budgets cannot take leaves - /// the companion exactly as it was. - fn edit_body( + fn take_serial(&mut self, serial: u64) -> Option { + let file = self.detach(serial)?; + self.names.remove(&file.named); + match file.body { + Body::Resident(_) | Body::Decoded(_) => None, + Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), + } + } + /// Renames the temporary file `temp`, which holds `serial`'s body of `len` + /// bytes, to the companion's own name in the spill directory and switches + /// the companion to it. With `used`, the tick the snapshot was read at, + /// only a companion nothing touched since and whose body is still in memory + /// (resident or decoded) takes it: a body another call changed or already + /// spilled stays, `Ok(false)` then, and `temp` is the caller's to unlink. + /// `None` is an edit's own body written out while it holds the companion's + /// edit gate, so no other edit can have changed it. + fn adopt_spilled( &mut self, serial: u64, + used: Option, + temp: &Path, len: usize, - apply: impl FnOnce(&mut Vec), - ) -> Result<(), Status> { - let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); - let mut file = self.detach(serial).ok_or(Status::Stale)?; - let need = len.saturating_sub(file.resident_len()); - let before_len = file.len; - let original = std::mem::replace(&mut file.body, Body::Resident(Vec::new())); - let mut bytes = match &original { - Body::Resident(bytes) => bytes.clone(), - Body::Decoded(image) => image.encode(), + ) -> Result { + let path = self + .spill_dir + .as_ref() + .map(|dir| spill_path(dir, serial)) + .ok_or(Status::NoSpc)?; + let Some(file) = self.files.get_mut(&serial) else { + return Err(Status::Stale); }; - bytes.resize(len, 0); - apply(&mut bytes); - file.body = Body::Resident(bytes); - file.len = len; - self.classify(&mut file); - if need > avail && !matches!(file.body, Body::Decoded(_)) { - // The body does not decode and the resident budget does not take - // it: the companion keeps what it had and the caller answers NOSPC. - file.body = original; - file.len = before_len; - self.attach(serial, file); - return Err(Status::NoSpc); + if let Some(used) = used { + if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { + return Ok(false); + } } - touch(&mut file.metadata); + fs::rename(temp, path).map_err(|e| io_status(&e))?; + let mut file = self.detach(serial).ok_or(Status::Stale)?; + file.body = Body::Spilled; + // A shorter file than the companion had described is not the body any + // more. + file.len = file.len.max(len); self.attach(serial, file); - Ok(()) + Ok(true) } - /// Applies a write to `serial`'s body; a write keeps what the body held - /// beyond its end. - fn write(&mut self, serial: u64, offset: usize, data: &[u8]) -> Result<(), Status> { - let file = self.files.get(&serial).ok_or(Status::Stale)?; - let len = file.len.max(offset + data.len()); - self.edit_body(serial, len, |bytes| { - bytes[offset..offset + data.len()].copy_from_slice(data); - }) - } - /// Resizes `serial` to `size`, within the bounds. - fn resize(&mut self, serial: u64, size: usize) -> Result<(), Status> { - self.edit_body(serial, size, |_| {}) + fn oldest_resident(&self, skip: Option) -> Option { + self.files + .iter() + .filter(|(serial, file)| { + Some(**serial) != skip + && matches!(file.body, Body::Resident(ref b) if !b.is_empty()) + }) + .min_by_key(|(_, file)| file.used) + .map(|(serial, _)| *serial) } fn holding(&self) -> Holding { Holding { held: self.files.len(), + resident_bytes: self.resident_bytes, decoded: self.decoded, decoded_bytes: self.decoded_bytes, } } } -fn now() -> PortableMetadata { - let elapsed = SystemTime::now() - .duration_since(UNIX_EPOCH) - .unwrap_or_default(); - PortableMetadata { - mode: MODE, - mtime_seconds: i64::try_from(elapsed.as_secs()).unwrap_or(i64::MAX), - mtime_nanoseconds: elapsed.subsec_nanos(), +/// Whether a body a spill wrote out still replaces its companion: only when the +/// companion is the one the snapshot saw (`used` is the tick read then) and its +/// body is still in memory, so no call wrote to it while the file was written. +pub fn spill_applies(used: u64, file_used: u64, resident: bool) -> bool { + used == file_used && resident +} +/// The body length `edit` leaves on a body that had `len` bytes. +fn edited_len(edit: &Edit<'_>, len: usize) -> usize { + match edit { + Edit::Write { .. } => len.max(edit.target_len()), + Edit::Size(size) => *size, } } -fn touch(metadata: &mut PortableMetadata) { - let fresh = now(); - metadata.mtime_seconds = fresh.mtime_seconds; - metadata.mtime_nanoseconds = fresh.mtime_nanoseconds; +/// Records the length `edit` leaves on `file`. +fn record(edit: &Edit<'_>, file: &mut Companion) { + file.len = edited_len(edit, file.len); } /// A serial of the export's own companions. pub fn companion(serial: u64) -> bool { @@ -241,20 +314,57 @@ impl Kernel { .lock() .unwrap_or_else(|poison| poison.into_inner()) } + pub(crate) fn configure_companions(&self, spill_dir: Option, resident_budget: usize) { + if let Some(dir) = &spill_dir { + drop(fs::remove_dir_all(dir)); + } + let mut companions = self.companions(); + companions.spill_dir = spill_dir; + companions.resident_budget = resident_budget; + } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { - let companions = self.companions(); + let mut companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - Ok(Companions::stat(serial, file)) + let stat = Companions::stat(serial, file); + companions.use_serial(serial); + Ok(stat) } - /// LOOKUP of a companion name, if one is held. + /// LOOKUP of a companion name, if one is held for it. pub(crate) fn companion_named(&self, parent: u64, name: &[u8]) -> Option { - let companions = self.companions(); + let mut companions = self.companions(); let serial = *companions.names.get(&(parent, name.to_vec()))?; - companions - .files - .get(&serial) - .map(|file| Companions::stat(serial, file)) + let stat = Companions::stat(serial, companions.files.get(&serial)?); + companions.use_serial(serial); + Some(stat) + } + /// CREATE of an already-held companion name: UNCHECKED applies its size, + /// as an open with truncation would; GUARDED and EXCLUSIVE find it taken. + fn companion_open( + &self, + serial: u64, + how: How, + directory: Wcc, + mut companions: std::sync::MutexGuard<'_, Companions>, + tickets: &mut Tickets, + ) -> Result<(ViewStat, Wcc), Status> { + let stat = Companions::stat(serial, &companions.files[&serial]); + companions.use_serial(serial); + drop(companions); + let How::Unchecked(sattr) = how else { + return Err(Status::Exist); + }; + match sattr.size { + Some(size) => { + let sized = Sattr { + size: Some(size), + ..Sattr::default() + }; + let (stat, _) = self.companion_setattr(stat.serial, sized, None, tickets)?; + Ok((stat, directory)) + } + None => Ok((stat, directory)), + } } /// CREATE of an AppleDouble name. pub(crate) fn companion_create( @@ -265,29 +375,15 @@ impl Kernel { tickets: &mut Tickets, ) -> Result<(ViewStat, Wcc), Status> { let directory = self.directory_wcc(parent); - if let Some(stat) = self.companion_named(parent, name) { - // Opened again: UNCHECKED applies its size, as an open with - // truncation would; GUARDED and EXCLUSIVE find it taken. - let How::Unchecked(sattr) = how else { - return Err(Status::Exist); - }; - return match sattr.size { - Some(size) => { - let sized = Sattr { - size: Some(size), - ..Sattr::default() - }; - let (stat, _) = self.companion_setattr(stat.serial, sized, None, tickets)?; - Ok((stat, directory)) - } - None => Ok((stat, directory)), - }; - } if parent != self.root() && !self.table().parents.contains_key(&parent) { return Err(Status::NotDir); } + let named = (parent, name.to_vec()); let mut companions = self.companions(); - if companions.len() >= HELD { + if let Some(serial) = companions.names.get(&named).copied() { + return self.companion_open(serial, how, directory, companions, tickets); + } + if companions.files.len() >= HELD { drop(companions); self.names_refused.fetch_add(1, Ordering::Relaxed); return Err(Status::Access); @@ -300,15 +396,17 @@ impl Kernel { } let serial = SERIALS + companions.next; companions.next += 1; - let named = (parent, name.to_vec()); + let used = companions.tick(); let file = Companion { - named, + named: named.clone(), len: 0, body: Body::Resident(Vec::new()), metadata, + used, + editing: Arc::new(Mutex::new(())), }; let stat = Companions::stat(serial, &file); - companions.names.insert(file.named.clone(), serial); + companions.names.insert(named, serial); companions.attach(serial, file); drop(companions); self.names_detached.fetch_add(1, Ordering::Relaxed); @@ -317,15 +415,16 @@ impl Kernel { /// REMOVE of a companion name, with the directory's `wcc_data`; `None` /// when no companion has that name. pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { - { + let spilled = { let mut companions = self.companions(); let serial = *companions.names.get(&(parent, name.to_vec()))?; - companions.drop_serial(serial); - } + companions.take_serial(serial) + }; + unlink_paths(spilled); Some(self.directory_wcc(parent)) } - /// RENAME of a companion name: only to another AppleDouble name, which - /// it replaces when held. `None` when no companion has that name. + /// RENAME of a companion name: only to another AppleDouble name, which it + /// replaces when held. `None` when no companion has that name. pub(crate) fn companion_rename( &self, from: u64, @@ -333,129 +432,52 @@ impl Kernel { to: u64, new_name: &[u8], ) -> Option> { - let mut companions = self.companions(); - let serial = *companions.names.get(&(from, name.to_vec()))?; - if !crate::names::apple_double(new_name) || new_name.len() > 255 { - return Some(Err(Status::Access)); - } - let target = (to, new_name.to_vec()); - if let Some(replaced) = companions.names.get(&target).copied() { - if replaced != serial { - companions.drop_serial(replaced); - } - } - companions.names.remove(&(from, name.to_vec())); - companions.names.insert(target.clone(), serial); - if let Some(file) = companions.files.get_mut(&serial) { - file.named = target; - } - Some(Ok(())) - } - /// READ of a companion, at most `count` bytes from `offset`, appended to - /// `out`; `eof` when the reply reaches the companion's end. - pub(crate) fn companion_read( - &self, - serial: u64, - offset: u64, - count: u32, - out: &mut Vec, - ) -> Result { - let companions = self.companions(); - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let length = file.len as u64; - let start = offset.min(length) as usize; - let end = offset.saturating_add(u64::from(count)).min(length) as usize; - match &file.body { - Body::Resident(bytes) => { - // A body and its length are recorded under one lock; clamp - // anyway so no reply slices past the bytes it holds. - let stop = end.min(bytes.len()); - out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + let mut replaced_path = None; + { + let mut companions = self.companions(); + let serial = *companions.names.get(&(from, name.to_vec()))?; + if !crate::names::apple_double(new_name) || new_name.len() > 255 { + return Some(Err(Status::Access)); } - Body::Decoded(image) => { - // The image the client wrote, synthesized again. - let bytes = image.encode(); - let stop = end.min(bytes.len()); - out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + let target = (to, new_name.to_vec()); + if let Some(replaced) = companions.names.get(&target).copied() { + if replaced != serial { + replaced_path = companions.take_serial(replaced); + } } + let tick = companions.tick(); + let mut file = companions.detach(serial)?; + companions.names.remove(&file.named); + file.named = target.clone(); + file.used = tick; + companions.names.insert(target, serial); + companions.attach(serial, file); } - Ok(end as u64 >= length) - } - /// WRITE to a companion: all of it or nothing. - pub(crate) fn companion_write( - &self, - serial: u64, - offset: u64, - data: &[u8], - ) -> Result<(u32, Wcc), Status> { - let end = offset.checked_add(data.len() as u64).ok_or(Status::FBig)?; - if end > FILE_BYTES { - return Err(Status::FBig); - } - let mut companions = self.companions(); - let before = { - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - Companions::stat(serial, file) - }; - companions.write(serial, offset as usize, data)?; - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let after = Companions::stat(serial, file); - Ok((data.len() as u32, (Some(before), Some(after)))) + unlink_paths(replaced_path); + Some(Ok(())) } - /// SETATTR of a companion: mode, size and modification time; the - /// owner is the export's identity, as for every inode. - pub(crate) fn companion_setattr( - &self, - serial: u64, - sattr: Sattr, - guard: Option<(u32, u32)>, - _tickets: &mut Tickets, - ) -> Result<(ViewStat, Wcc), Status> { - let identity = self.identity(); - let foreign = sattr.uid.is_some_and(|uid| uid != identity.uid) - || sattr.gid.is_some_and(|gid| gid != identity.gid); - if foreign { - return Err(Status::Perm); - } - let before = { - let companions = self.companions(); - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let before = Companions::stat(serial, file); - if let Some(expected) = guard { - if crate::attributes::ctime(&before) != expected { - return Err(Status::NotSync); - } - } - before + /// Drops every companion and removes the export's spill directory; returns + /// what the index held. + pub(crate) fn companions_release(&self) -> Holding { + let (held, dir) = { + let mut companions = self.companions(); + let dir = companions.spill_dir.take(); + (std::mem::take(&mut *companions), dir) }; - if let Some(size) = sattr.size { - if size > FILE_BYTES { - return Err(Status::FBig); - } - self.companions().resize(serial, size as usize)?; - } - let mut companions = self.companions(); - let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - if let Some(mode) = sattr.mode { - file.metadata.mode = mode & 0o777; + if let Some(dir) = dir { + drop(fs::remove_dir_all(dir)); } - match sattr.mtime { - Some(Stamp::At(time)) => { - file.metadata.mtime_seconds = time.seconds; - file.metadata.mtime_nanoseconds = time.nanoseconds; - } - Some(Stamp::Processing) => touch(&mut file.metadata), - None if sattr.size.is_some() => touch(&mut file.metadata), - None => {} + let holding = held.holding(); + if holding.held > 0 { + eprintln!( + "layerfs-nfs: AppleDouble companions released: export={:?} held={} decoded={} decoded_bytes={} resident_bytes={}", + self.mount(), + holding.held, + holding.decoded, + holding.decoded_bytes, + holding.resident_bytes + ); } - let after = Companions::stat(serial, file); - Ok((after.clone(), (Some(before), Some(after)))) - } - /// Drops every companion; what the index held. - pub(crate) fn companions_release(&self) -> Holding { - let mut companions = self.companions(); - let holding = companions.holding(); - *companions = Companions::default(); holding } /// What the companion index holds now. diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs new file mode 100644 index 0000000000..555ffb1120 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -0,0 +1,366 @@ +//! Companion bodies: READ, WRITE and SETATTR, and the spill that moves a body +//! from memory to the export's scratch directory. +//! +//! One edit of a companion runs at a time, under that companion's own edit +//! gate (`Companion::editing` in the parent module): it applies to the resident +//! bytes under the +//! companion lock or to the spilled file outside it, and records the length +//! its own bytes leave, so a truncate and a write of the same companion can +//! never leave a length its file does not have and no round has to decide +//! again on a body another call changed under it. +//! +//! A body that does not fit the resident budget is spilled first, least +//! recently touched first; the body that still does not fit is written out +//! itself and edited in its file, which needs no budget. The file I/O never +//! holds the companion lock, and no descriptor is kept for a spilled body: +//! each operation opens its file by path and closes it again. +use super::{edited_len, record, Body, Companions, DECODED_ENTRY_BYTES, FILE_BYTES}; +use crate::{ + apple_double_spill::{create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Room}, + attributes::Status, + change::{Sattr, Tickets, Wcc}, + kernel::Kernel, +}; +use layerfs_mount_ports::operations::write::Stamp; +use layerfs_workspace::ViewStat; +use std::{ + fs::{File, OpenOptions}, + io, + os::unix::fs::FileExt, +}; + +/// Rounds one edit takes to make room in the resident budget before it spills +/// its own body instead. Each round either spills the least recently touched +/// body or finds no body to spill; another call's spill can take the room a +/// round just made, which is why a round is retried at all. +const SPILL_ROUNDS: usize = 4; + +impl Kernel { + /// READ of a companion, at most `count` bytes from `offset`, appended to + /// `out`; `eof` when the reply reaches the companion's end. + pub(crate) fn companion_read( + &self, + serial: u64, + offset: u64, + count: u32, + out: &mut Vec, + ) -> Result { + let (spilled, length, start, end) = { + let mut companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let length = file.len as u64; + let start = offset.min(length) as usize; + let end = offset.saturating_add(u64::from(count)).min(length) as usize; + let spilled = match &file.body { + Body::Resident(bytes) => { + // A body and its length are recorded under one lock; clamp + // anyway so no reply slices past the bytes it holds. + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + false + } + Body::Decoded(image) => { + // The image the client wrote, synthesized again. + let bytes = image.encode(); + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + false + } + Body::Spilled => true, + }; + companions.use_serial(serial); + (spilled, length, start, end) + }; + if spilled { + let mut buf = vec![0u8; end - start]; + self.spill_file(serial, false)? + .read_exact_at(&mut buf, start as u64) + .map_err(|e| io_status(&e))?; + out.extend_from_slice(&buf); + } + Ok(end as u64 >= length) + } + /// WRITE to a companion: all of it or nothing. + pub(crate) fn companion_write( + &self, + serial: u64, + offset: u64, + data: &[u8], + ) -> Result<(u32, Wcc), Status> { + let end = offset.checked_add(data.len() as u64).ok_or(Status::FBig)?; + if end > FILE_BYTES { + return Err(Status::FBig); + } + let before = self.companion_stat(serial)?; + let after = self.edit_companion( + serial, + Edit::Write { + offset: offset as usize, + data, + }, + )?; + Ok((data.len() as u32, (Some(before), Some(after)))) + } + /// SETATTR of a companion: mode, size and modification time; the + /// owner is the export's identity, as for every inode. + pub(crate) fn companion_setattr( + &self, + serial: u64, + sattr: Sattr, + guard: Option<(u32, u32)>, + _tickets: &mut Tickets, + ) -> Result<(ViewStat, Wcc), Status> { + let identity = self.identity(); + if sattr.uid.is_some_and(|uid| uid != identity.uid) + || sattr.gid.is_some_and(|gid| gid != identity.gid) + { + return Err(Status::Perm); + } + let before = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let before = Companions::stat(serial, file); + if let Some(expected) = guard { + if crate::attributes::ctime(&before) != expected { + return Err(Status::NotSync); + } + } + before + }; + if let Some(size) = sattr.size { + if size > FILE_BYTES { + return Err(Status::FBig); + } + self.edit_companion(serial, Edit::Size(size as usize))?; + } + let mut companions = self.companions(); + let tick = companions.tick(); + let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; + file.used = tick; + if let Some(mode) = sattr.mode { + file.metadata.mode = mode & 0o777; + } + match sattr.mtime { + Some(Stamp::At(time)) => { + file.metadata.mtime_seconds = time.seconds; + file.metadata.mtime_nanoseconds = time.nanoseconds; + } + Some(Stamp::Processing) => touch(&mut file.metadata), + None if sattr.size.is_some() => touch(&mut file.metadata), + None => {} + } + let after = Companions::stat(serial, file); + Ok((after.clone(), (Some(before), Some(after)))) + } + /// Applies `edit` to `serial` and answers its stat afterwards: in the + /// resident body while the budget holds it, else in its spilled file + /// outside the companion lock. This companion's gate makes the edit run + /// alone, so the length recorded is the one its own bytes leave. + fn edit_companion(&self, serial: u64, edit: Edit<'_>) -> Result { + let gate = { + let companions = self.companions(); + companions + .files + .get(&serial) + .ok_or(Status::Stale)? + .editing + .clone() + }; + // Held to the end: no other edit of this companion runs meanwhile. + let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); + let target = edit.target_len(); + for _ in 0..SPILL_ROUNDS { + match self.edit_resident(serial, target, &edit)? { + Room::Resident(stat) => return Ok(stat), + Room::Spilled => break, + Room::Grow(need) => { + // No other call changes this body, so a round that finds + // room leaves the next edit in it. + if !self.spill_for(serial, need)? { + break; + } + } + } + } + // The body still does not fit resident memory: write it out and edit + // its file, which needs no body budget. + self.spill_gated(serial, target)?; + edit.disk(&self.spill_file(serial, true)?)?; + self.record_edit(serial, &edit) + } + /// Applies `edit` to `serial`'s body in memory while the budget holds it + /// (a decoded body is encoded first), recording its length, recency and + /// time and deciding again whether it is a whole image, under the same + /// lock, so no other call ever sees a body and a length that disagree. + fn edit_resident(&self, serial: u64, target: usize, edit: &Edit<'_>) -> Result { + let mut companions = self.companions(); + let avail = companions + .resident_budget + .saturating_sub(companions.resident_bytes); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let need = match &file.body { + Body::Spilled => return Ok(Room::Spilled), + Body::Resident(bytes) => target.saturating_sub(bytes.len()), + Body::Decoded(image) => edited_len(edit, image.len()), + }; + if need > avail { + // The body does not fit the resident budget, but the edit may + // complete a whole image, whose decoded form costs its attributes + // and no body budget. Only a body small enough to decode is tried. + if target > DECODED_ENTRY_BYTES + crate::apple_double_codec::IMAGE_UNIT { + return Ok(Room::Grow(need)); + } + let mut bytes = match &file.body { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + Body::Spilled => return Ok(Room::Spilled), + }; + let len = edited_len(edit, file.len); + edit.memory(&mut bytes); + if companions.keep_decoded(serial, &bytes, len) { + let stat = companions + .files + .get(&serial) + .map(|file| Companions::stat(serial, file)); + if let Some(stat) = stat { + return Ok(Room::Resident(stat)); + } + } + return Ok(Room::Grow(need)); + } + let tick = companions.tick(); + let mut file = companions.detach(serial).ok_or(Status::Stale)?; + let mut bytes = match std::mem::replace(&mut file.body, Body::Spilled) { + Body::Resident(bytes) => bytes, + Body::Decoded(image) => image.encode(), + Body::Spilled => { + companions.attach(serial, file); + return Ok(Room::Spilled); + } + }; + edit.memory(&mut bytes); + file.body = Body::Resident(bytes); + record(edit, &mut file); + touch(&mut file.metadata); + file.used = tick; + companions.classify(&mut file); + let stat = Companions::stat(serial, &file); + companions.attach(serial, file); + Ok(Room::Resident(stat)) + } + /// Records an edit applied to `serial`'s spilled file and answers its + /// stat. + fn record_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { + let mut companions = self.companions(); + let tick = companions.tick(); + let mut file = companions.detach(serial).ok_or(Status::Stale)?; + record(edit, &mut file); + file.used = tick; + touch(&mut file.metadata); + let stat = Companions::stat(serial, &file); + companions.attach(serial, file); + Ok(stat) + } + /// Spills the least recently used resident companions to disk (outside the + /// companion lock) until adding `need` bytes stays within `resident_budget`. + /// Returns `true` if `need` fits in resident memory afterwards. A victim + /// another call changed meanwhile is picked again on the next round; the + /// rounds are bounded by the index, and the caller then writes out its own + /// body, which needs no budget at all. + fn spill_for(&self, target: u64, need: usize) -> Result { + let mut rounds = { + let companions = self.companions(); + if companions.resident_bytes + need <= companions.resident_budget { + return Ok(true); + } + companions.files.len() + }; + while rounds > 0 { + rounds -= 1; + let victim = { + let companions = self.companions(); + if companions.resident_bytes + need <= companions.resident_budget { + return Ok(true); + } + companions.oldest_resident(Some(target)) + }; + let Some(victim) = victim else { + return Ok(false); + }; + // A victim another call changed meanwhile leaves the next round to + // pick again; only a disk failure ends the loop. + let _ = self.spill_one(victim, None)?; + } + Ok(false) + } + /// Writes `serial`'s body out to the spill directory and switches it to + /// that file, keeping at least `keep` bytes (all of them when `None`), + /// with the disk I/O outside the companion lock. `Ok(false)` when another + /// call changed the companion, or already spilled it, while the file was + /// written: that temporary file is dropped and the caller decides again on + /// the body it now finds. + fn spill_one(&self, serial: u64, keep: Option) -> Result { + let (dir, bytes, size, used) = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let bytes = match &file.body { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + Body::Spilled => return Ok(true), + }; + let dir = companions.spill_dir.clone().ok_or(Status::NoSpc)?; + let size = keep.unwrap_or(0).max(bytes.len()); + (dir, bytes, size, file.used) + }; + let temp = create_spilled(&dir, serial, &bytes, size as u64)?; + let adopted = self + .companions() + .adopt_spilled(serial, Some(used), &temp, size); + if matches!(adopted, Ok(true)) { + return Ok(true); + } + unlink_paths([temp]); + adopted.map(|_| false) + } + /// Writes `serial`'s body out while its own edit runs alone, keeping + /// `size` bytes: no other edit can change the body, so the file written is + /// the body this edit then applies to. + fn spill_gated(&self, serial: u64, size: usize) -> Result<(), Status> { + let (dir, bytes, size) = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let bytes = match &file.body { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + Body::Spilled => return Ok(()), + }; + let dir = companions.spill_dir.clone().ok_or(Status::NoSpc)?; + let size = size.max(bytes.len()); + (dir, bytes, size) + }; + let temp = create_spilled(&dir, serial, &bytes, size as u64)?; + let adopted = self.companions().adopt_spilled(serial, None, &temp, size); + if !matches!(adopted, Ok(true)) { + unlink_paths([temp]); + } + adopted.map(|_| ()) + } + /// The spill directory's file of `serial`, opened for one operation and + /// closed again when the returned descriptor drops: the export holds no + /// descriptor per spilled companion. A file or directory that is gone + /// means the companion itself is gone. + fn spill_file(&self, serial: u64, write: bool) -> Result { + let dir = { + let companions = self.companions(); + companions.spill_dir.clone().ok_or(Status::Stale)? + }; + OpenOptions::new() + .read(true) + .write(write) + .open(spill_path(&dir, serial)) + .map_err(|e| match e.kind() { + io::ErrorKind::NotFound => Status::Stale, + _ => io_status(&e), + }) + } +} diff --git a/engine/crates/layerfs-nfs/src/apple_double_spill.rs b/engine/crates/layerfs-nfs/src/apple_double_spill.rs new file mode 100644 index 0000000000..738bcc0268 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double_spill.rs @@ -0,0 +1,151 @@ +//! The export's own scratch files for AppleDouble companion bodies. +//! +//! A companion body beyond the resident budget lives in one file per +//! companion serial under the export's spill directory, read and written with +//! `pread`/`pwrite` by an operation that opens it and closes it again: the +//! export holds no descriptor per spilled body. A spill writes a temporary +//! `..tmp` that only the call adopting it renames to ``, so +//! two calls spilling the same companion never share a file. The directory +//! and its files are this user's alone; the modes are set here rather than +//! left to the caller's umask. +use crate::attributes::Status; +use layerfs_content::filesystem::attributes::PortableMetadata; +use std::{ + fs::{self, File, OpenOptions}, + io, + os::unix::fs::{DirBuilderExt, FileExt, OpenOptionsExt}, + path::{Path, PathBuf}, + sync::atomic::{AtomicU64, Ordering}, + time::{SystemTime, UNIX_EPOCH}, +}; + +/// Mode of a companion created without one. +pub(crate) const MODE: u32 = 0o644; +/// Temporary names tried for one spilled body before the spill gives up. +const SPILL_TEMP_TRIES: u32 = 64; +/// Counter behind the distinct temporary name of each spilled body. +static SPILL_TEMP: AtomicU64 = AtomicU64::new(0); + +/// A failed file operation as the client sees it. +pub(crate) fn io_status(error: &io::Error) -> Status { + match (error.kind(), error.raw_os_error()) { + (io::ErrorKind::StorageFull, _) | (_, Some(28 | 69 | 122)) => Status::NoSpc, + (_, Some(27)) => Status::FBig, + (_, Some(1)) => Status::Perm, + (io::ErrorKind::PermissionDenied, _) | (_, Some(13)) => Status::Access, + (io::ErrorKind::ReadOnlyFilesystem, _) | (_, Some(30)) => Status::RoFs, + _ => Status::Io, + } +} +/// The spill directory's own file of `serial`. +pub(crate) fn spill_path(dir: &Path, serial: u64) -> PathBuf { + dir.join(serial.to_string()) +} +/// Creates `dir` and a temporary file in it holding `bytes` extended to `len` +/// bytes, then closes it: the caller adopts it by renaming it to the +/// companion's own name. +pub(crate) fn create_spilled( + dir: &Path, + serial: u64, + bytes: &[u8], + len: u64, +) -> Result { + let made = fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(dir); + made.map_err(|e| io_status(&e))?; + for _ in 0..SPILL_TEMP_TRIES { + let name = SPILL_TEMP.fetch_add(1, Ordering::Relaxed); + let path = dir.join(format!("{serial}.{name}.tmp")); + let file = match OpenOptions::new() + .read(true) + .write(true) + .create_new(true) + .mode(0o600) + .open(&path) + { + Ok(file) => file, + Err(e) if e.kind() == io::ErrorKind::AlreadyExists => continue, + Err(e) => return Err(io_status(&e)), + }; + let written = (file.write_all_at(bytes, 0)).and_then(|()| file.set_len(len)); + drop(file); + return match written { + Ok(()) => Ok(path), + Err(e) => { + drop(fs::remove_file(&path)); + Err(io_status(&e)) + } + }; + } + Err(Status::Io) +} +/// Unlinks the spilled files a companion operation retired, outside the lock. +pub(crate) fn unlink_paths(paths: impl IntoIterator) { + for path in paths { + drop(fs::remove_file(path)); + } +} +/// The facts of a companion body created now. +pub(crate) fn now() -> PortableMetadata { + let elapsed = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default(); + PortableMetadata { + mode: MODE, + mtime_seconds: i64::try_from(elapsed.as_secs()).unwrap_or(i64::MAX), + mtime_nanoseconds: elapsed.subsec_nanos(), + } +} +/// Records a change of a companion body's time, keeping its mode. +pub(crate) fn touch(metadata: &mut PortableMetadata) { + let mode = metadata.mode; + *metadata = now(); + metadata.mode = mode; +} +/// One change to a companion body, applied to the resident bytes under the +/// lock or to the spilled file outside it. +pub(crate) enum Edit<'a> { + Write { offset: usize, data: &'a [u8] }, + Size(usize), +} +impl Edit<'_> { + /// The body length this edit needs; a write keeps what the body had beyond + /// its end. + pub(crate) fn target_len(&self) -> usize { + match self { + Edit::Write { offset, data } => offset + data.len(), + Edit::Size(size) => *size, + } + } + /// Applies the edit to resident bytes, which already hold `target_len`. + pub(crate) fn memory(&self, bytes: &mut Vec) { + match self { + Edit::Write { offset, data } => { + bytes.resize(bytes.len().max(offset + data.len()), 0); + bytes[*offset..*offset + data.len()].copy_from_slice(data); + } + Edit::Size(size) => bytes.resize(*size, 0), + } + } + /// Applies the edit to a spilled file, outside the companion lock. + pub(crate) fn disk(&self, file: &File) -> Result<(), Status> { + match self { + Edit::Write { offset, data } => { + (file.write_all_at(data, *offset as u64)).map_err(|e| io_status(&e)) + } + Edit::Size(size) => (file.set_len(*size as u64)).map_err(|e| io_status(&e)), + } + } +} +/// Where [`crate::apple_double`] found a companion's body. +pub(crate) enum Room { + /// Applied to the resident body, whose length, recency and time were + /// recorded under the same lock: this is the companion's stat afterwards. + Resident(layerfs_workspace::ViewStat), + /// On disk: finish with its file outside the lock. + Spilled, + /// Resident, but growing it needs this many more budget bytes first. + Grow(usize), +} diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index f765a6177d..3c37d964de 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -43,6 +43,7 @@ impl Kernel { fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { Released { companions: companions.held, + companion_bytes: companions.resident_bytes, companions_decoded: companions.decoded, companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), @@ -77,6 +78,8 @@ pub struct Released { /// AppleDouble companions held in the export's index (see /// [`crate::apple_double`]). pub companions: usize, + /// Companion payload bytes currently resident in memory. + pub companion_bytes: usize, /// Of the companions held, those kept decoded, and the bytes counted for /// them. pub companions_decoded: usize, diff --git a/engine/crates/layerfs-nfs/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index 84154c19c1..ca288a9089 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -18,6 +18,7 @@ pub mod apple_double; pub mod apple_double_codec; +mod apple_double_spill; pub mod attributes; mod block; pub mod change; diff --git a/engine/crates/layerfs-nfs/src/server.rs b/engine/crates/layerfs-nfs/src/server.rs index 798282c7eb..3a3e2b6d65 100644 --- a/engine/crates/layerfs-nfs/src/server.rs +++ b/engine/crates/layerfs-nfs/src/server.rs @@ -43,6 +43,14 @@ pub struct ExportConfig { /// Lookup references kept before the least recently used are collected /// (see [`crate::kernel`]); [`crate::kernel::LOOKUPS_HELD`] by default. pub lookups_held: usize, + /// Scratch directory where AppleDouble companion bodies spill when resident + /// bytes exceed [`Self::companion_resident_bytes`]. Removed when set and + /// when the export releases. + pub companion_spill_dir: Option, + /// Resident memory budget for AppleDouble companion bodies before spilling + /// to [`Self::companion_spill_dir`]; [`crate::apple_double::RESIDENT_BYTES`] + /// by default. + pub companion_resident_bytes: usize, } impl ExportConfig { /// A writable export of "/" shown as `uid`:`gid`, refusing AppleDouble @@ -55,6 +63,8 @@ impl ExportConfig { read_only: false, refuse_apple_double: true, lookups_held: crate::kernel::LOOKUPS_HELD, + companion_spill_dir: None, + companion_resident_bytes: crate::apple_double::RESIDENT_BYTES, } } } @@ -137,10 +147,15 @@ impl Server { config: ExportConfig, ) -> io::Result { let address = listener.local_addr()?; + let kernel = Kernel::new(services, mount, config.uid, config.gid) + .refusing_apple_double(config.refuse_apple_double) + .holding(config.lookups_held); + kernel.configure_companions( + config.companion_spill_dir.clone(), + config.companion_resident_bytes, + ); let shared = Arc::new(Shared { - kernel: Kernel::new(services, mount, config.uid, config.gid) - .refusing_apple_double(config.refuse_apple_double) - .holding(config.lookups_held), + kernel, verifier: fresh_verifier(), config, counters: Counters::default(), From 91434f93e7d4d74539159402121a85beb508a204 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:38:06 +0000 Subject: [PATCH 06/17] test(nfs): cover the companion spill, its files and its cleanup (lp73) The rig can now set the resident budget and an explicit spill directory, and the cases exercise the layer end to end: - a body smaller than the budget stays resident and a larger one spills; the spilled file carries the bytes and the length the client wrote; - an edit that leaves a decoded image not whole spills it instead of growing memory, while a truncate of a decoded body needs no room at all; - a spill only replaces a companion no other call changed meanwhile (`spill_applies`); - a truncate and a write of one spilled companion start together, round after round, and the length a reply reports is always the length its file holds; - companions four times the process's own `RLIMIT_NOFILE` all read and write, because a spilled body is opened by path per operation: that case lowers a process-wide limit and counts the process's descriptors, so it re-runs itself in its own process (`run_alone`); - Attach cleans a leftover `.appledouble` of a daemon that died, release and unmount remove it, and startup reclamation removes it while keeping every other entry under the mount home. `libc` is a new dev-dependency of `layerfs-nfs`, only for the file-limit case. Tests: `cargo test -p layerfs-nfs` 46 passed, 0 failed (the raw sum reads 47 because the file-limit case runs itself once in a child process). Production LOC: 164334 -> 164334 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 7b38dadc9 (164334) and this tree (164334). Tests only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/tests/apple_double_decode.rs | 74 ++++++ engine/crates/layerfs-nfs/tests/daemon.rs | 47 ++++ .../crates/layerfs-nfs/tests/support/rig.rs | 15 ++ engine/crates/layerfs-nfs/tests/write.rs | 237 ++++++++++++++++++ 4 files changed, 373 insertions(+) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 7acd47a903..28f95320ba 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -140,3 +140,77 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_decoded_companion_is_edited_under_a_full_resident_budget() { + let base = temp("decoded-budget"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // A body budget smaller than one encoded image: an edit that leaves the + // image not whole has to spill rather than grow memory. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + let main = c.touch(&root, b"full", 0o644).unwrap(); + c.write(&main.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._full", 0o644).unwrap(); + let whole = image( + [0x77; 32], + &[ + (b"com.apple.provenance", pattern(30, 40)), + (b"user.big", pattern(31, 4096)), + ], + ); + // Another companion's body stays in memory; truncating a decoded body needs + // no room for its image, so that body must not be evicted for it. + c.touch(&root, b"other", 0o644).unwrap(); + let other = c.touch(&root, b"._other", 0o644).unwrap(); + c.write(&other.handle, 0, &pattern(35, 100)).unwrap(); + assert_eq!(server.held().companion_bytes, 100); + + // A whole image costs its attributes, not its bytes: it is decoded. + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions_decoded, 1); + + // Truncating a decoded body to nothing is the client's truncation, with no + // resident room for its image, and a rewrite decodes again. + let empty = Set { + size: Some(0), + ..Set::default() + }; + c.setattr(&ad.handle, empty, None).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, 0); + assert_eq!(c.read_all(&ad.handle, 4096), Vec::::new()); + assert_eq!(server.held().companions_decoded, 0); + assert_eq!( + server.held().companion_bytes, + 100, + "the image was never resident, so nothing had to be evicted for it" + ); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions_decoded, 1); + + // An edit that leaves the image not whole cannot grow memory: the decoded + // body is spilled and the write applied to its file, not refused. + let mut edited = whole.clone(); + edited[24..28].copy_from_slice(b"EDIT"); + c.write(&ad.handle, 24, b"EDIT").unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), edited); + assert_eq!(server.held().companions_decoded, 0); + + // Truncating the spilled body is the client's truncation. + c.setattr(&ad.handle, empty, None).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, 0); + assert_eq!(c.read_all(&ad.handle, 4096), Vec::::new()); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + diff --git a/engine/crates/layerfs-nfs/tests/daemon.rs b/engine/crates/layerfs-nfs/tests/daemon.rs index eacaf9e35b..2d831256bb 100644 --- a/engine/crates/layerfs-nfs/tests/daemon.rs +++ b/engine/crates/layerfs-nfs/tests/daemon.rs @@ -136,8 +136,18 @@ fn workspace_control_over_the_nfs_route() { // Mount + Attach: Ready with an NFS receipt; the helper mounted it. let token = bind(&service, 31, rig.branch); + let spill_dir = mounts + .join(".appledouble") + .join(token.namespace.to_string()); + fs::create_dir_all(&spill_dir).unwrap(); + let stale_spill = spill_dir.join("stale-from-crashed-daemon"); + fs::write(&stale_spill, b"stale").unwrap(); assert_eq!(phase(&service, token), MountPhase::Unattached); let ready = attach(&service, token); + assert!( + !stale_spill.exists(), + "Attach cleans any leftover companion spill directory" + ); assert_eq!(ready.receipt.abi_major, 0); assert_eq!( ready.directory, @@ -242,6 +252,7 @@ fn workspace_control_over_the_nfs_route() { Reply::Unmounted(token) ); assert!(!Path::new(&ready.directory).exists()); + assert!(!spill_dir.exists()); let released = service.export_released(token).unwrap(); assert_eq!(released.lookups, held.lookups); assert_eq!(released.retained, 0); @@ -290,3 +301,39 @@ fn workspace_control_over_the_nfs_route() { } fs::remove_file(&log).unwrap(); } + +/// A daemon that ended without unmounting leaves the companions' scratch +/// directories behind. Its successor clears them before serving anything, and +/// touches nothing else under the mount home. +#[test] +fn startup_reclaim_clears_leftover_companion_spill_directories() { + let mounts = temp("reclaim-mounts"); + let log = temp("reclaim-helpers.log"); + drop(fs::remove_dir_all(&mounts)); + drop(fs::remove_file(&log)); + fs::create_dir_all(mounts.join(".appledouble/7")).unwrap(); + fs::write(mounts.join(".appledouble/7/stale"), b"stale").unwrap(); + fs::create_dir_all(mounts.join("kept")).unwrap(); + fs::write(mounts.join("kept/note"), b"keep").unwrap(); + let export = ExportServing::start(ExportServingConfig::new( + mounts.clone(), + UID, + GID, + Mounter { + mount: recording("mount", &log, None), + unmount: recording("unmount", &log, None), + force: recording("force", &log, None), + flush: None, + }, + )); + let lines = export.reclaim(); + assert_eq!(lines.len(), 1, "{lines:?}"); + assert!( + lines[0].starts_with("removed leftovers under "), + "{lines:?}" + ); + assert!(!mounts.join(".appledouble").exists()); + assert_eq!(fs::read(mounts.join("kept/note")).unwrap(), b"keep"); + drop(fs::remove_dir_all(&mounts)); + drop(fs::remove_file(&log)); +} diff --git a/engine/crates/layerfs-nfs/tests/support/rig.rs b/engine/crates/layerfs-nfs/tests/support/rig.rs index f30ad75e95..612b9a2a2f 100644 --- a/engine/crates/layerfs-nfs/tests/support/rig.rs +++ b/engine/crates/layerfs-nfs/tests/support/rig.rs @@ -40,6 +40,10 @@ pub struct Rig { pub entries: u64, /// The reference bound exports of this rig are configured with. pub lookups_held: usize, + /// Resident memory budget for AppleDouble companion bodies. + pub companion_resident_bytes: usize, + /// Optional explicit spill directory override for AppleDouble companions. + pub companion_spill_dir: Option, } impl Rig { /// Initializes a Store from `source`, publishes Branch `main` at that @@ -142,8 +146,15 @@ impl Rig { branch, entries: initialized.entries, lookups_held: layerfs_nfs::kernel::LOOKUPS_HELD, + companion_resident_bytes: layerfs_nfs::apple_double::RESIDENT_BYTES, + companion_spill_dir: None, } } + fn spill_dir(&self, sub: &str) -> PathBuf { + self.companion_spill_dir + .clone() + .unwrap_or_else(|| self.directory.join("tmp").join("appledouble").join(sub)) + } /// Serves this rig's engine mount read-only on `listener`. pub fn serve(&self, listener: TcpListener, uid: u32, gid: u32) -> Server { self.export(listener, uid, gid, true) @@ -179,6 +190,8 @@ impl Rig { read_only, refuse_apple_double: true, lookups_held: self.lookups_held, + companion_spill_dir: Some(self.spill_dir("export")), + companion_resident_bytes: self.companion_resident_bytes, }, ) .unwrap() @@ -247,6 +260,8 @@ impl Rig { read_only: true, refuse_apple_double: true, lookups_held: self.lookups_held, + companion_spill_dir: Some(self.spill_dir(&format!("view-{}", view.1.owner_id()))), + companion_resident_bytes: self.companion_resident_bytes, }, ) .unwrap() diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index a6c94d0f74..0a5a9e596e 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -57,6 +57,15 @@ fn pattern(seed: u32, length: usize) -> Vec { .collect() } +/// The files an export spilled into `dir`, and their bytes. +fn spilled(dir: &Path) -> (usize, u64) { + let files: Vec = (fs::read_dir(dir).into_iter().flatten().flatten()) + .filter_map(|entry| entry.metadata().ok()) + .map(|metadata| metadata.len()) + .collect(); + (files.len(), files.iter().sum()) +} + #[test] fn every_changing_procedure_and_its_statuses() { let base = temp("procedures"); @@ -531,6 +540,234 @@ fn apple_double_files_stay_out_of_the_workspace() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_spill_replaces_a_companion_body_only_when_no_call_changed_it() { + use layerfs_nfs::apple_double::spill_applies; + // The companion the body was written from, still resident and untouched: + // the spilled file replaces it. + assert!(spill_applies(7, 7, true)); + // Another call wrote to the companion while its body was being written out: + // that newer body stays and the file just written is dropped. + assert!(!spill_applies(7, 8, true)); + // Another call spilled the body first: its file stays. + assert!(!spill_applies(7, 7, false)); +} + +/// The process's soft and hard `RLIMIT_NOFILE`. +fn nofile_limits() -> (libc::rlim_t, libc::rlim_t) { + let mut limit = libc::rlimit { + rlim_cur: 0, + rlim_max: 0, + }; + // SAFETY: `getrlimit` only fills the limit structure it is given. + let asked = unsafe { libc::getrlimit(libc::RLIMIT_NOFILE, &mut limit) }; + assert_eq!(asked, 0, "RLIMIT_NOFILE is readable"); + (limit.rlim_cur, limit.rlim_max) +} + +/// Sets the process's soft `RLIMIT_NOFILE`, leaving the hard limit alone. +fn set_nofile_soft(soft: libc::rlim_t) { + let (_, hard) = nofile_limits(); + let limit = libc::rlimit { + rlim_cur: soft, + rlim_max: hard, + }; + // SAFETY: a soft limit at or below the hard limit is always allowed. + let set = unsafe { libc::setrlimit(libc::RLIMIT_NOFILE, &limit) }; + assert_eq!(set, 0, "soft RLIMIT_NOFILE is settable"); +} + +/// Puts the process's soft `RLIMIT_NOFILE` back when it drops, `panic` included. +struct SoftNofile(libc::rlim_t); +impl SoftNofile { + fn lower(soft: libc::rlim_t) -> Self { + let (was, _) = nofile_limits(); + set_nofile_soft(soft); + Self(was) + } +} +impl Drop for SoftNofile { + fn drop(&mut self) { + set_nofile_soft(self.0); + } +} + +/// The descriptors this process holds, counted from the kernel's own view. +fn open_fds() -> Option { + ["/dev/fd", "/proc/self/fd"] + .into_iter() + .find_map(|dir| fs::read_dir(dir).ok()) + .map(|entries| entries.flatten().count()) +} + +#[test] +fn a_spilled_companion_keeps_its_length_and_bytes_together() { + let base = temp("appledouble-spilled-race"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill-race")); + // Smaller than the body below, which therefore lives on disk. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let mut other = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let name = b"._raced".as_slice(); + let made = c.touch(&root, b"raced", 0o644).unwrap(); + let ad = c.touch(&root, name, 0o644).unwrap(); + let payload = pattern(29, 2048); + c.write(&ad.handle, 0, &payload).unwrap(); + assert_eq!(made.handle, c.lookup(&root, b"raced").unwrap().0); + assert_eq!(server.held().companion_bytes, 0, "the body spilled"); + + // A truncate and a write of this companion start together, round after + // round: each runs to completion under the companion's own gate, so the + // length a reply reports is always the length its file holds, and a read + // never asks for bytes the file does not have (NFS3ERR_IO). + for round in 0..64 { + let start = std::sync::Barrier::new(2); + let empty = Set { + size: Some(0), + ..Set::default() + }; + let (a, b) = std::thread::scope(|scope| { + let a = scope.spawn(|| { + start.wait(); + c.setattr(&ad.handle, empty, None) + }); + let b = scope.spawn(|| { + start.wait(); + other.write(&ad.handle, 0, &payload) + }); + (a.join().unwrap(), b.join().unwrap()) + }); + a.unwrap(); + b.unwrap(); + let size = c.getattr(&ad.handle).unwrap().size as usize; + assert!( + size == 0 || size == payload.len(), + "round {round}: length {size} of a truncate or a write" + ); + assert_eq!( + c.read_all(&ad.handle, 4096).len(), + size, + "round {round}: the bytes served match the length" + ); + } + + drop((c, other)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +/// Set in the child process [`run_alone`] starts, so it runs the body of the one +/// test it was started for. +const FD_LIMIT_CHILD: &str = "LAYERFS_NFS_FD_LIMIT_CHILD"; + +/// Re-runs one test of this binary in its own process, so a change of +/// process-wide state (a soft `RLIMIT_NOFILE`, the descriptors this process +/// holds) can neither reach nor be reached by the tests running in parallel in +/// this one. `name` is selected with `--exact`, so exactly that test runs. +fn run_alone(marker: &str, name: &str) { + let exe = std::env::current_exe().expect("the test binary's own path"); + let status = std::process::Command::new(exe) + .arg("--exact") + .arg(name) + .arg("--test-threads=1") + .env(marker, "1") + .status() + .expect("the test binary starts again"); + assert!(status.success(), "{name} failed in its own process"); +} + +/// The export opens a spilled body by path for one operation and closes it +/// again, so companions far outnumbering the process's own file limit all +/// read and write: a descriptor per spilled body would end in `EMFILE` here. +#[test] +fn spilled_companions_outnumber_the_open_file_limit() { + // The soft limit is process-wide and the descriptor count is the whole + // process's: both are set and asserted in a process running this test + // alone, never next to the tests this binary runs in parallel. + if std::env::var_os(FD_LIMIT_CHILD).is_none() { + run_alone( + FD_LIMIT_CHILD, + "spilled_companions_outnumber_the_open_file_limit", + ); + return; + } + let base = temp("appledouble-fd"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let spill_dir = base.join("spill-fd"); + rig.companion_spill_dir = Some(spill_dir.clone()); + rig.companion_resident_bytes = 1024; + let budget = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // Four times as many companions as the process may hold open at once. + // This process runs no other test: the limit and the count are its own. + let (soft, hard) = nofile_limits(); + let limit = soft.min(hard).min(512); + let count = limit as usize * 4; + let payload = pattern(29, 600); + let mut handles = Vec::with_capacity(count); + { + let _restored = SoftNofile::lower(limit); + assert_eq!(nofile_limits().0, limit); + for i in 0..count { + let name = format!("._fd-{i}"); + let made = c.touch(&root, name.as_bytes(), 0o644).unwrap(); + c.write(&made.handle, 0, &payload).unwrap(); + handles.push((made.handle, made.attr.fileid)); + } + assert!(server.held().companion_bytes <= budget); + let (on_disk, _) = spilled(&spill_dir); + assert_eq!(on_disk, count - 1, "all but the newest body spilled"); + if let Some(fds) = open_fds() { + assert!( + fds < count / 4, + "{fds} descriptors open for {count} companions" + ); + } + for (i, (handle, fileid)) in handles.iter().enumerate() { + assert_eq!(c.read_all(handle, 64 * 1024), payload, "companion {i}"); + // The newest body is still resident; every older one is on disk. + assert_eq!( + spill_dir.join(fileid.to_string()).is_file(), + i + 1 < count, + "companion {i}" + ); + } + // The disk half still writes and truncates through its own open. + let (ref h0, _) = handles[0]; + c.write(h0, 0, b"opened by path").unwrap(); + let shrink = Set { + size: Some(14), + ..Set::default() + }; + c.setattr(h0, shrink, None).unwrap(); + assert_eq!(c.read_all(h0, 64), b"opened by path"); + } + assert_eq!(nofile_limits().0, soft, "the soft limit is put back"); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions, count); + assert!(released.companion_bytes <= budget); + assert!( + !spill_dir.exists(), + "export stop removes the spill directory" + ); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} #[test] fn tickets_are_released_only_after_the_reply() { let base = temp("tickets"); From 8183f8969997884b5f50343207f24093a6602307 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:40:11 +0000 Subject: [PATCH 07/17] docs(nfs): document the companion spill area and its cleanup (lp73) The guide names `edit.rs` and `apple_double_spill.rs`, describes what the `RESIDENT_BYTES` row does now (spill to `companion_spill_dir`, and which status each host errno maps to), and records the scratch file's own rules: one file per companion serial under `/.appledouble/`, `0700`/`0600`, written as a temporary and adopted by rename only when no call changed the body, opened by path per operation and never held open, deleted by startup reclamation and by release. `ExportConfig` lists the two new fields, and the `wcc_data` row now says a companion mutation answers from `directory_stats`. Documentation only; it describes the spill layer as it stands. Production LOC: 164334 -> 164334 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 91434f93e (164334) and this tree (164334). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 3b2db39e69..b8acc9f42e 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -35,7 +35,7 @@ The daemon starts it and has the host's own NFS client mount it. | Item | Meaning | Source | | --- | --- | --- | | `Server::start` | Starts the accept thread; one connection serves one call at a time, in arrival order | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | -| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | +| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`, `companion_spill_dir`, `companion_resident_bytes`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | `Server::stop` | Stop accepting, shut down and join every connection, then `Kernel::release`: descriptors first, then lookup references. The engine mount stays with the caller | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | `Kernel` | What a FUSE kernel would hold for a stateless client: one lookup reference per handed-out serial, implicit file and directory descriptors with the facts last published through them, a parent index for `..` | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | Verifier | One WRITE/COMMIT verifier per export, from the clock and process id under a random key | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | @@ -137,7 +137,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | --- | --- | | A publication ticket is released only after the reply's one send attempt, whether or not it reached the client | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | A WRITE is split into `WRITE_WINDOW` (256 KiB) windows, each one publication; a failure after the first is a short write of the windows already published. WRITE answers `FILE_SYNC`: published, not durable | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs), [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs) | -| `wcc_data` pre- and post-op attributes come from the publishing job's own inode state, RENAME included; no reply reads an attribute outside the job | [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs), [`kernel_visit.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_visit.rs) | +| `wcc_data` pre- and post-op attributes come from the publishing job's own inode state, RENAME included; no reply reads an attribute outside the job. An AppleDouble companion's CREATE, REMOVE or RENAME publishes no engine job and answers both halves from `Table::directory_stats` (or absent when unseen) | [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs), [`kernel_visit.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_visit.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | RENAME looks nothing up first; a detached (`nlink == 0`) destination's reference and descriptor are retired inside that job | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs) | | COMMIT answers the attributes last published or observed through the implicit descriptor, so `fsync` costs no owner job | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs) | | A client silly rename (`.nfs` + 24 hex on Linux; `.nfs.` + 8 hex + `.` + 4 hex on macOS) is served as an UNLINK; the export keeps the inode until the final REMOVE | [`names.rs`](../../../../engine/crates/layerfs-nfs/src/names.rs) | @@ -163,7 +163,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | The refresh never writes into the Workspace and never reverts a mode the install changed | [`refresh.rs`](../../../../engine/crates/layerfs-nfs/src/refresh.rs) | | `LAYERFS_NFS_REFRESH=0` leaves the client to `actimeo` and close-to-open | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -## AppleDouble files (`apple_double.rs`, `apple_double_codec.rs`) +## AppleDouble files (`apple_double.rs`, `apple_double/edit.rs`, `apple_double_codec.rs`, `apple_double_spill.rs`) On NFSv3 the macOS client keeps extended attributes and resource forks in `._` files. With `refuse_apple_double`, a regular `._` file (at least @@ -178,7 +178,7 @@ reaches the Workspace or a Commit; everything is dropped with the export. | --- | --- | --- | --- | | `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `RESIDENT_BYTES` | 32 MiB resident bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB resident bodies in all | Spill least recently touched resident bodies to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | | `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | @@ -189,6 +189,15 @@ is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` rather than its image, and every READ synthesizes the same bytes again. Partial writes, resource forks and other layouts stay as the client wrote them. +Resident bodies exceeding `RESIDENT_BYTES` spill outside the companion lock to +`..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by +rename to `` only if unchanged (`used` tick); spilled bodies are opened +by path per `pread`/`pwrite`/`set_len` and never held open. One edit per +companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), +recording length and bytes together and spilling its own body after bounded +eviction rounds (`SPILL_ROUNDS`) rather than failing with `NFS3ERR_IO`. +`ExportServing::reclaim` and release delete `/.appledouble`. + ## Mount (`mount.rs`, daemon `export.rs`) ```text From b01e805988941d28e31eff3b6e652fdbea04e5ae Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:24:33 +0000 Subject: [PATCH 08/17] feat(nfs): encode only the window of the AppleDouble image a READ asks for (lp73) A decoded companion was re-encoded in full under the companion lock on every READ: up to `FILE_BYTES` (1 MiB) allocated and copied to serve a reply of at most `TRANSFER_WINDOW` (256 KiB) bytes, and often far less. `Image::encode_range` lays the image out and fills only `[start, end)`, so a READ pays for the bytes it answers with; `Image::encode` is that same layout over the whole image, so there is one implementation of the layout rather than two that can drift. `edit.rs`'s spill and `edit_resident` still need the whole image and keep calling `encode()`. Whether a READ is served from a window or from the whole image is not observable: the reply bytes are the same either way. Review: finding 7 (full re-encode on every READ). Tests: new `any_window_of_the_image_encodes_to_that_window` compares every window of an image (a padding byte the client left behind, values of several sizes, the empty resource fork) with the same slice of `encode()`, including empty windows, a window past the image and one that starts after it ends. `cargo test -p layerfs-nfs --test apple_double_codec --test apple_double_decode`: 7 + 1 passed, 0 failed. Anti-proof: with `encode_range` clamped to start at 0 again the window test fails (`left` starts at image offset 0 while the expected window starts mid-image). Production LOC: 163886 -> 163908 (delta +22) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 584cc3e66 (163886) and of the staged tree 20b10a3487 (163908). Engine +22. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 8 +- .../layerfs-nfs/src/apple_double_codec.rs | 86 +++++++++++++------ .../layerfs-nfs/tests/apple_double_codec.rs | 53 ++++++++++++ 3 files changed, 117 insertions(+), 30 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index c96d1c8b6a..7aa38ae4e2 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -373,10 +373,10 @@ impl Kernel { out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); } Body::Decoded(image) => { - // The image the client wrote, synthesized again. - let bytes = image.encode(); - let stop = end.min(bytes.len()); - out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + // The image the client wrote, synthesized again over the + // window this reply asks for rather than in full. + let stop = end.min(image.len()); + out.extend_from_slice(&image.encode_range(start, stop)); } } Ok(end as u64 >= length) diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs index 1d01edabf3..1e45130f78 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -14,6 +14,8 @@ //! client wrote: no attribute, value or byte the layout carries is dropped. //! Each attribute entry keeps the alignment padding the client left after its //! name, because the client does not clear the bytes a shorter name replaced. +//! [`Image::encode_range`] gives back any window of the image, so a READ serves +//! the bytes it asked for without laying out the whole image first. //! //! Anything else - a resource fork with data, still another layout, a //! half-written image - yields `None` and is stored as the client wrote it. @@ -184,42 +186,65 @@ impl Image { } /// The image these fields describe, as the client lays one out. pub fn encode(&self) -> Vec { - let mut out = vec![0u8; self.len]; + self.encode_range(0, self.len) + } + /// The bytes of the encoded image in `[start, end)`, both clamped to its + /// length: a READ of one window pays for that window, not for the whole + /// image, and gives back the same bytes [`Self::encode`] would. + pub fn encode_range(&self, start: usize, end: usize) -> Vec { + let start = start.min(self.len); + let end = end.max(start).min(self.len); + let mut out = vec![0u8; end - start]; let fork_at = self.len - self.fork.len(); let data_start = self.data_start(); - put32(&mut out, 0, MAGIC); - put32(&mut out, 4, VERSION); - out[8..24].copy_from_slice(FILLER); - put16(&mut out, 24, 2); - put32(&mut out, 26, FINDER_TAG); - put32(&mut out, 30, FINDER_AT as u32); - put32(&mut out, 34, (fork_at - FINDER_AT) as u32); - put32(&mut out, 38, FORK_TAG); - put32(&mut out, 42, fork_at as u32); - put32(&mut out, 46, self.fork.len() as u32); - out[FINDER_AT..FINDER_AT + FINDER_INFO].copy_from_slice(&self.finder); - put32(&mut out, ATTR_AT, ATTR_MAGIC); - put32(&mut out, ATTR_AT + 4, self.tag); - put32(&mut out, ATTR_AT + 8, fork_at as u32); - put32(&mut out, ATTR_AT + 12, data_start as u32); - put32(&mut out, ATTR_AT + 16, self.data_len() as u32); - put16(&mut out, ATTR_AT + 34, self.attrs.len() as u16); + // The fixed part of the image, whose offsets are absolute and known + // without walking the entries. + let mut head = [0u8; ENTRIES_AT]; + put32(&mut head, 0, MAGIC); + put32(&mut head, 4, VERSION); + head[8..24].copy_from_slice(FILLER); + put16(&mut head, 24, 2); + put32(&mut head, 26, FINDER_TAG); + put32(&mut head, 30, FINDER_AT as u32); + put32(&mut head, 34, (fork_at - FINDER_AT) as u32); + put32(&mut head, 38, FORK_TAG); + put32(&mut head, 42, fork_at as u32); + put32(&mut head, 46, self.fork.len() as u32); + head[FINDER_AT..FINDER_AT + FINDER_INFO].copy_from_slice(&self.finder); + put32(&mut head, ATTR_AT, ATTR_MAGIC); + put32(&mut head, ATTR_AT + 4, self.tag); + put32(&mut head, ATTR_AT + 8, fork_at as u32); + put32(&mut head, ATTR_AT + 12, data_start as u32); + put32(&mut head, ATTR_AT + 16, self.data_len() as u32); + put16(&mut head, ATTR_AT + 34, self.attrs.len() as u16); + emit(&mut out, start, 0, &head); let (mut entry, mut value_at) = (ENTRIES_AT, data_start); for attr in &self.attrs { - put32(&mut out, entry, value_at as u32); - put32(&mut out, entry + 4, attr.value.len() as u32); - out[entry + 10] = (attr.name.len() + 1) as u8; + // Entries and values only grow, and the fork sits past both: once + // neither of this one's is in the window, no later one is either. + if entry >= end && value_at >= end { + break; + } + let name_len = attr.name.len() + 1; + emit(&mut out, start, entry, &(value_at as u32).to_be_bytes()); + emit( + &mut out, + start, + entry + 4, + &(attr.value.len() as u32).to_be_bytes(), + ); + emit(&mut out, start, entry + 10, &[name_len as u8]); let name_at = entry + ENTRY_FIXED; let name_end = name_at + attr.name.len(); - out[name_at..name_end].copy_from_slice(&attr.name); - let next = entry + entry_len(attr.name.len() + 1); - out[name_end + 1..next].copy_from_slice(&attr.pad[..next - name_end - 1]); - out[value_at..value_at + attr.value.len()].copy_from_slice(&attr.value); + emit(&mut out, start, name_at, &attr.name); + let next = entry + entry_len(name_len); + emit(&mut out, start, name_end + 1, &attr.pad[..next - name_end - 1]); + emit(&mut out, start, value_at, &attr.value); entry = next; value_at += attr.value.len(); } if self.fork == Fork::Blank { - out[fork_at..].copy_from_slice(&blank_fork()); + emit(&mut out, start, fork_at, &blank_fork()); } out } @@ -328,6 +353,15 @@ fn blank_fork() -> [u8; BLANK_FORK] { fork[16..16 + BLANK_FORK_TAG.len()].copy_from_slice(BLANK_FORK_TAG); fork } +/// Copies the `bytes` that sit at `at` in the image into `out`, which holds +/// the image from `start` to its end. +fn emit(out: &mut [u8], start: usize, at: usize, bytes: &[u8]) { + let from = at.max(start); + let until = (at + bytes.len()).min(start + out.len()); + if from < until { + out[from - start..until - start].copy_from_slice(&bytes[from - at..until - at]); + } +} fn put32(out: &mut [u8], at: usize, value: u32) { out[at..at + 4].copy_from_slice(&value.to_be_bytes()); } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs index 8bbfc57412..b4d0c32098 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs @@ -55,6 +55,59 @@ fn first_name_end(name_len: usize) -> usize { ENTRIES_AT + 11 + name_len } +#[test] +fn any_window_of_the_image_encodes_to_that_window() { + // An image the client would write and decode: attributes whose names end + // on every alignment, values of several sizes, a padding byte the client + // left behind and its own empty resource fork. + let attrs: &[(&[u8], Vec)] = &[ + (b"user.a", pattern(11, 1)), + (b"com.example.long-name", pattern(12, 300)), + (b"user.c", pattern(13, 0)), + (b"com.apple.provenance", pattern(14, 40)), + (b"user.tail", pattern(15, 1000)), + ]; + let mut bytes = image([0x5a; 32], 0x0123_4567, attrs).encode(); + bytes[first_name_end(b"user.a".len()) + 1] = 0x3d; + let built = Image::compact(&bytes).expect("the image decodes"); + assert_eq!(built.encode(), bytes, "the whole image is unchanged"); + let len = bytes.len(); + let window = |start: usize, end: usize| { + let start = start.min(len); + let end = end.max(start).min(len); + bytes[start..end].to_vec() + }; + // Every window, in and past the image, byte for byte the same as the + // whole encoding: the header, each entry's offset, length and name, the + // padding after a name, each value, and the fork. + for start in (0..=len + 1).step_by(37) { + assert_eq!(built.encode_range(start, len + 1), window(start, len + 1)); + for end in (start..=len + 1).step_by(41) { + assert_eq!( + built.encode_range(start, end), + window(start, end), + "window {start}..{end} of {len} bytes" + ); + } + } + // An empty window, and a window that starts past the image. + assert_eq!(built.encode_range(0, 0), Vec::::new()); + assert_eq!(built.encode_range(len / 2, len / 2), Vec::::new()); + assert_eq!(built.encode_range(len + 10, len + 20), Vec::::new()); + assert_eq!(built.encode_range(7, 3), Vec::::new()); + assert_eq!(built.encode_range(0, len + 10), bytes); + assert_eq!(built.encode_range(len - 1, len + 10), bytes[len - 1..].to_vec()); + // The fork's own bytes are not all zero: a window inside it is served + // from the fork, not from the zeroed layout. + let fork_at = get32(&bytes, FORK_AT) as usize; + assert!(bytes[fork_at..].iter().any(|byte| *byte != 0)); + assert_eq!( + built.encode_range(fork_at, len), + bytes[fork_at..].to_vec(), + "the empty resource fork is part of the window" + ); +} + #[test] fn values_of_every_size_round_trip() { for size in [0, 1, 4096, 64 * 1024, 100 * 1024] { From 7ef50a034d87556b7cbe2bb17b5bcb7d6df2dcf1 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:28:43 +0000 Subject: [PATCH 09/17] refactor(nfs): count decoded AppleDouble images in the resident budget (lp73) `DECODED_BYTES` (512 MiB per export) was memory nothing could evict: many Workspaces can be mounted at once, so a per-export budget that is never paid back does not fit. Decoded images now take the same `RESIDENT_BYTES` (32 MiB) as bodies kept as written, a body at its length and a decoded one as `Image::cost`, so the budget sees every byte the export holds. `Companion::resident_cost` is that one number; `attach`, `detach` and `edit_body` count it, `edit_body` decides with it (a body either fits or the whole edit answers `NFS3ERR_NOSPC` and leaves the companion as it was), and `classify` no longer consults a second budget. `DECODED_ENTRY_BYTES` stays, now as the most `Image::cost` one decoded companion may be counted for: a whole image costing more keeps the client's bytes, so one companion cannot take the whole pool. This layer has no disk to spill to, so a body the budget does not take is still refused; the next layer spills it. `Released` reports the merged pool as `companion_bytes` and keeps `companions_decoded` as a count, instead of `companion_decoded_bytes` beside a separate resident total. Review: owner decision 3 (`DECODED_BYTES` rejected), first half (the budget and the counts); the spill half is the next layer. Tests: `the_clients_write_sequence_is_served_byte_for_byte` now asserts the merged pool: the decoded image's `Image::cost()` after the image arrives, the written body's length while it does not decode, the cost again once it does, and zero after the companion is removed. `cargo test -p layerfs-nfs`: 42 passed, 0 failed. Anti-proof: with a decoded body counted as zero again the test fails at the first assertion (`left: 0, right: 4372`). Production LOC: 163908 -> 163896 (delta -12) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent b01e80598 (163908) and of the staged tree bfc489bb4e (163896). Engine -12. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 14 ++-- engine/crates/layerfs-nfs/src/apple_double.rs | 68 +++++++++---------- .../crates/layerfs-nfs/src/kernel/released.rs | 10 +-- .../layerfs-nfs/tests/apple_double_decode.rs | 17 +++++ 4 files changed, 62 insertions(+), 47 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 3b2db39e69..22ebe232a6 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -178,16 +178,18 @@ reaches the Workspace or a Commit; everything is dropped with the export. | --- | --- | --- | --- | | `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `RESIDENT_BYTES` | 32 MiB resident bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB of companion bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | A body a write or resize leaves as a complete AppleDouble image that encodes back to the exact bytes the companion holds ([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)) -is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` -rather than its image, and every READ synthesizes the same bytes again. Partial -writes, resource forks and other layouts stay as the client wrote them. +is kept as its FinderInfo and attributes, and every READ synthesizes the same +bytes again. It takes the same `RESIDENT_BYTES` budget as a body kept as +written, counted as `Image::cost` (its names and values, not its image), so no +decoded image is memory the budget cannot see. Partial writes, resource forks +and other layouts stay as the client wrote them, and a body the budget does not +take leaves the companion as it was. ## Mount (`mount.rs`, daemon `export.rs`) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 7aa38ae4e2..3aff737e07 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -18,15 +18,17 @@ //! //! Whenever a write leaves a companion holding a whole AppleDouble image the //! client laid out itself (see [`crate::apple_double_codec`]), it is decoded: a -//! small one keeps only its FinderInfo and attributes in memory (at most -//! [`DECODED_BYTES`] in all, each at most [`DECODED_ENTRY_BYTES`]), and every -//! read synthesizes the same bytes again. +//! small one keeps only its FinderInfo and attributes in memory (each at most +//! [`DECODED_ENTRY_BYTES`] counted), and every read synthesizes the same bytes +//! again. //! //! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] each, -//! [`RESIDENT_BYTES`] of written bodies and [`DECODED_BYTES`] of decoded ones -//! counted as [`Image::cost`]. Beyond the count a creation is refused +//! and [`RESIDENT_BYTES`] of bodies in all, a body kept as written counted at +//! its length and a decoded one as [`Image::cost`], so a decoded image is never +//! memory the budget cannot see. Beyond the count a creation is refused //! (`NFS3ERR_ACCES`, as before this module), beyond a file's bytes a write -//! (`NFS3ERR_FBIG`), beyond the resident body budget a write (`NFS3ERR_NOSPC`). +//! (`NFS3ERR_FBIG`), beyond the body budget a write (`NFS3ERR_NOSPC`), which +//! leaves the companion exactly as it was. use crate::{ apple_double_codec::Image, attributes::Status, @@ -49,12 +51,12 @@ pub const SERIALS: u64 = 1 << 62; pub const HELD: usize = 4096; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; -/// Companion payload bytes kept resident in memory before a write is refused. +/// Companion payload bytes kept resident in memory before a write is refused: +/// a body kept as written counts its length, a decoded one [`Image::cost`]. pub const RESIDENT_BYTES: usize = 32 << 20; -/// Bytes counted for all decoded companions (see [`Image::cost`]). -pub const DECODED_BYTES: usize = 512 << 20; -/// Bytes counted for one decoded companion; a larger whole image keeps its -/// bytes as written. +/// Most bytes counted for one decoded companion, [`Image::cost`]; a whole +/// image costing more keeps its bytes as written, so one companion cannot take +/// the whole budget. pub const DECODED_ENTRY_BYTES: usize = 128 << 10; /// Mode of a companion created without one. const MODE: u32 = 0o644; @@ -74,16 +76,12 @@ struct Companion { metadata: PortableMetadata, } impl Companion { - fn resident_len(&self) -> usize { + /// The bytes it takes of [`RESIDENT_BYTES`]: its body as written, or what + /// its decoded form is counted as. + fn resident_cost(&self) -> usize { match &self.body { Body::Resident(bytes) => bytes.len(), - Body::Decoded(_) => 0, - } - } - fn decoded_cost(&self) -> usize { - match &self.body { Body::Decoded(image) => image.cost(), - Body::Resident(_) => 0, } } } @@ -93,7 +91,7 @@ impl Companion { pub(crate) struct Holding { pub held: usize, pub decoded: usize, - pub decoded_bytes: usize, + pub resident_bytes: usize, } /// The companions of one export. @@ -104,7 +102,6 @@ pub(crate) struct Companions { names: HashMap<(u64, Vec), u64>, resident_bytes: usize, decoded: usize, - decoded_bytes: usize, } impl Companions { pub(crate) fn len(&self) -> usize { @@ -122,18 +119,16 @@ impl Companions { } /// Adds `file` to the index and to the byte counts. fn attach(&mut self, serial: u64, file: Companion) { - self.resident_bytes += file.resident_len(); + self.resident_bytes += file.resident_cost(); self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); - self.decoded_bytes += file.decoded_cost(); self.files.insert(serial, file); } /// Takes `serial` out of the index and the counts; its name key stays for /// the caller to unindex. fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; - self.resident_bytes -= file.resident_len(); + self.resident_bytes -= file.resident_cost(); self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); - self.decoded_bytes -= file.decoded_cost(); Some(file) } /// Drops `serial` and its name key. @@ -143,7 +138,7 @@ impl Companions { } } /// Decides whether `file`'s body is a whole image: one that parses back to - /// the same bytes and that the decoded budget takes. `file` must be + /// the same bytes and that [`DECODED_ENTRY_BYTES`] takes. `file` must be /// detached from the index. fn classify(&self, file: &mut Companion) { let Body::Resident(bytes) = &file.body else { @@ -152,25 +147,23 @@ impl Companions { let Some(image) = Image::compact(bytes) else { return; }; - let cost = image.cost(); - if cost <= DECODED_ENTRY_BYTES && self.decoded_bytes + cost <= DECODED_BYTES { + if image.cost() <= DECODED_ENTRY_BYTES { file.body = Body::Decoded(image); } } /// Replaces `serial`'s body by `len` bytes built from it by `apply`, kept - /// within the budgets: a body that decodes costs its attributes, not its - /// bytes, and any other body stays in memory only while [`RESIDENT_BYTES`] - /// takes it. All of it or nothing: a body the budgets cannot take leaves - /// the companion exactly as it was. + /// within [`RESIDENT_BYTES`]: a body that decodes is counted as its + /// attributes, not as its bytes, and any other body stays in memory only + /// while the budget takes it. All of it or nothing: a body the budget + /// cannot take leaves the companion exactly as it was. fn edit_body( &mut self, serial: u64, len: usize, apply: impl FnOnce(&mut Vec), ) -> Result<(), Status> { - let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); let mut file = self.detach(serial).ok_or(Status::Stale)?; - let need = len.saturating_sub(file.resident_len()); + let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); let before_len = file.len; let original = std::mem::replace(&mut file.body, Body::Resident(Vec::new())); let mut bytes = match &original { @@ -182,9 +175,10 @@ impl Companions { file.body = Body::Resident(bytes); file.len = len; self.classify(&mut file); - if need > avail && !matches!(file.body, Body::Decoded(_)) { - // The body does not decode and the resident budget does not take - // it: the companion keeps what it had and the caller answers NOSPC. + if file.resident_cost() > avail { + // Neither as bytes nor as attributes does the body fit what the + // budget has left: the companion keeps what it had and the caller + // answers NOSPC. file.body = original; file.len = before_len; self.attach(serial, file); @@ -211,7 +205,7 @@ impl Companions { Holding { held: self.files.len(), decoded: self.decoded, - decoded_bytes: self.decoded_bytes, + resident_bytes: self.resident_bytes, } } } diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index f765a6177d..a333d56fb5 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -43,8 +43,8 @@ impl Kernel { fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { Released { companions: companions.held, + companion_bytes: companions.resident_bytes, companions_decoded: companions.decoded, - companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -77,10 +77,12 @@ pub struct Released { /// AppleDouble companions held in the export's index (see /// [`crate::apple_double`]). pub companions: usize, - /// Of the companions held, those kept decoded, and the bytes counted for - /// them. + /// Companion body bytes currently counted against the export's resident + /// budget: a body kept as written at its length, a decoded one at what its + /// attributes are counted as. + pub companion_bytes: usize, + /// Of the companions held, those kept decoded. pub companions_decoded: usize, - pub companion_decoded_bytes: usize, /// AppleDouble companions created, over the export's life. pub names_detached: u64, /// References collected beyond the bound, over the export's life. diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 7acd47a903..dea993d169 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -81,12 +81,21 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { c.write(&ad.handle, 50, &whole[50..]).unwrap(); assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); assert_eq!(server.held().companions_decoded, 1); + // The decoded form is memory too: it is counted against the same resident + // budget as a body kept as written, at what its attributes cost. + let decoded = Image::compact(&whole).expect("the client's image decodes"); + assert_eq!(server.held().companion_bytes, decoded.cost()); // A delete and rebuild starts empty and decodes the rewrite again. c.remove(&root, b"._seq").unwrap(); assert_eq!(c.getattr(&ad.handle), Err(STALE)); let again = c.touch(&root, b"._seq", 0o644).unwrap(); assert_eq!(again.attr.size, 0); + assert_eq!( + server.held().companion_bytes, + 0, + "the removed companion gave its bytes back" + ); assert_eq!(c.read_all(&again.handle, 4096), Vec::::new()); let rebuilt = image( [0x44; 32], @@ -97,6 +106,8 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { ); c.write(&again.handle, 0, &rebuilt).unwrap(); assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + let rebuilt_cost = Image::compact(&rebuilt).expect("decodes").cost(); + assert_eq!(server.held().companion_bytes, rebuilt_cost); // An edit that leaves the image not whole is served as written, and a // later edit that completes it decodes again: both are the client's own @@ -106,9 +117,15 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { c.write(&again.handle, 24, b"EDIT").unwrap(); assert_eq!(c.read_all(&again.handle, 128 * 1024), edited); assert_eq!(server.held().companions_decoded, 0); + assert_eq!( + server.held().companion_bytes, + edited.len(), + "a body kept as written counts its length" + ); c.write(&again.handle, 24, &rebuilt[24..28]).unwrap(); assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); assert_eq!(server.held().companions_decoded, 1); + assert_eq!(server.held().companion_bytes, rebuilt_cost); // Truncating below the image is served as the client's truncation, and // resizing back up serves zeros, as on any file. From e323c0eba773a2d2f50adac4b06ee78a370accfe Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:43:39 +0000 Subject: [PATCH 10/17] feat(nfs): spill a decoded AppleDouble body like any other body (lp73) With decoded images counted against `RESIDENT_BYTES`, a decoded body is memory like any other and has to leave memory like any other. `oldest_resident` now takes the least recently used companion whose `resident_cost` is not zero, which is a body kept as written or a decoded one, so eviction reaches decoded bodies. Writing a decoded body out needs nothing new: `spill_one` and `spill_gated` already encode it and write those bytes, which are exactly the image the client wrote. A whole image that does not fit the budget is therefore no longer refused (`NFS3ERR_NOSPC`) nor kept decoded beyond it: it goes to its spill file and is edited there, as any body does. Review: owner decision 3 (`DECODED_BYTES` rejected), second half (the spill). Tests: new `eviction_takes_the_decoded_body_before_the_written_ones` under a 4,096-byte budget: a decoded image of 213 bytes, then two 2,000-byte bodies. The decoded body is the least recently used memory, so it is the one spilled (`companions_decoded` 1 -> 0), the two written bodies stay resident (`4000` bytes), and the image reads back byte for byte from its file. Anti-proof: with `oldest_resident` filtered to bodies kept as written again, the test fails (`companions_decoded` stays 1 and the written body is evicted instead). Production LOC: 164340 -> 164337 (delta -3) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 7a9f20c33 (164340) and of the staged tree (164337). Engine -3. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 3 +- engine/crates/layerfs-nfs/src/apple_double.rs | 7 +-- .../layerfs-nfs/tests/apple_double_decode.rs | 56 +++++++++++++++++++ 3 files changed, 61 insertions(+), 5 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 49fcab020e..851e42441a 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -190,7 +190,8 @@ length, so no decoded image is memory the budget cannot see, and every READ synthesizes the same bytes again. Partial writes, resource forks and other layouts stay as the client wrote them. -Resident bodies exceeding `RESIDENT_BYTES` spill outside the companion lock to +Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` +together, spill outside the companion lock to `..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by rename to `` only if unchanged (`used` tick); spilled bodies are opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 02e0b433de..51ed13a495 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -259,13 +259,12 @@ impl Companions { self.attach(serial, file); Ok(true) } + /// The least recently used companion holding memory, a body kept as + /// written or a decoded one: the budget counts both, so both are evicted. fn oldest_resident(&self, skip: Option) -> Option { self.files .iter() - .filter(|(serial, file)| { - Some(**serial) != skip - && matches!(file.body, Body::Resident(ref b) if !b.is_empty()) - }) + .filter(|(serial, file)| Some(**serial) != skip && file.resident_cost() > 0) .min_by_key(|(_, file)| file.used) .map(|(serial, _)| *serial) } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 7dc65ecea1..25aedc1d59 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -157,6 +157,62 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn eviction_takes_the_decoded_body_before_the_written_ones() { + let base = temp("decoded-evict"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill")); + // Room for two 2,000-byte bodies and one decoded image of a few hundred + // bytes. + rig.companion_resident_bytes = 4096; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // A whole image, decoded: it costs its attributes, not its 4 KiB. + let whole = image( + [0x21; 32], + &[(b"com.apple.provenance", pattern(40, 40))], + ); + c.touch(&root, b"old", 0o644).unwrap(); + let old = c.touch(&root, b"._old", 0o644).unwrap(); + c.write(&old.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + let decoded_cost = server.held().companion_bytes; + assert!(decoded_cost < 4096, "the image is counted as its attributes"); + + // Two bodies kept as written fill the budget: the decoded body is the least + // recently used memory there is, so it is the one spilled, and its file + // holds the image the client wrote. + let first = pattern(41, 2000); + let second = pattern(42, 2000); + c.touch(&root, b"one", 0o644).unwrap(); + let one = c.touch(&root, b"._one", 0o644).unwrap(); + c.write(&one.handle, 0, &first).unwrap(); + c.touch(&root, b"two", 0o644).unwrap(); + let two = c.touch(&root, b"._two", 0o644).unwrap(); + c.write(&two.handle, 0, &second).unwrap(); + assert_eq!( + server.held().companions_decoded, + 0, + "the decoded body was the memory evicted" + ); + assert_eq!(server.held().companion_bytes, 4000); + assert_eq!(c.read_all(&old.handle, 64 * 1024), whole, "from its spill file"); + assert_eq!(c.read_all(&one.handle, 64 * 1024), first); + assert_eq!(c.read_all(&two.handle, 64 * 1024), second); + assert_eq!(c.getattr(&old.handle).unwrap().size as usize, whole.len()); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions_decoded, 0); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_decoded_companion_is_edited_under_a_full_resident_budget() { let base = temp("decoded-budget"); From 73f62efc2cfc09191a24b9e2118d912f2d0752cd Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:47:03 +0000 Subject: [PATCH 11/17] perf(nfs): keep companion bodies in an eviction order, not a scan (lp73) Eviction walked every companion to find the least recently used one, and `spill_for` repeated that walk up to `SPILL_ROUNDS` times, so one edit could scan the index under the companion lock several times. `Companions::by_use` is now a `BTreeSet<(used tick, serial)>` of the companions holding memory: `attach` inserts an entry when a body takes budget, `detach` removes it, and `set_used` (behind `use_serial`, the guest's last touch of the body) moves it. `oldest_resident` is the first entry, skipping the caller's own serial, so a round costs one step into the order (O(log n)) and no walk. `spill_for` no longer bounds its rounds by the number of companions: it takes the oldest body, and if that body changed under it the other call has already moved its entry to the newest end, so the next round looks at a different one; the rounds end when nothing holding memory is left. `SPILL_ROUNDS` goes away. The companion lock now does O(1) or O(log n) work per step with no I/O: `attach`/`detach`/`set_used` one set operation, `oldest_resident` one lookup, and the file written before the lock is taken and renamed after it is dropped. The kernel table lock is untouched by any of this. Review: blocking finding 2 (eviction is an O(n) scan under the lock, repeated). Tests: new `eviction_follows_the_order_of_use_not_the_shape_of_the_index`: 64 companions of 16 bytes under a 1,024-byte budget, three of them read again, then eight more; the spill directory holds exactly the serials of the eight least recently used ones, in that order, and the three read again stay resident. Anti-proof: with `oldest_resident` reversed the test fails, spilling `SERIALS+2, +64..+70` (the newest) instead of `SERIALS+3..+10`. Production LOC: 164337 -> 164342 (delta +5) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent e323c0eba (164337) and of the staged tree (164342). Engine +5. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 7 +- engine/crates/layerfs-nfs/src/apple_double.rs | 37 +++++++--- .../layerfs-nfs/src/apple_double/edit.rs | 42 ++++-------- .../layerfs-nfs/tests/apple_double_decode.rs | 68 +++++++++++++++++++ 4 files changed, 117 insertions(+), 37 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 851e42441a..b325d78a29 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -196,8 +196,11 @@ together, spill outside the companion lock to rename to `` only if unchanged (`used` tick); spilled bodies are opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), -recording length and bytes together and spilling its own body after bounded -eviction rounds (`SPILL_ROUNDS`) rather than failing with `NFS3ERR_IO`. +recording length and bytes together and spilling its own body rather than +failing with `NFS3ERR_IO`. Eviction follows `Companions::by_use`, the +`(used tick, serial)` order kept on attach, detach and every use: the victim is +the first entry (O(log n) per round, no walk of the index), and the rounds end +when no companion holding memory is left. `ExportServing::reclaim` and release delete `/.appledouble`. ## Mount (`mount.rs`, daemon `export.rs`) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 51ed13a495..5d6b172af0 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -42,7 +42,7 @@ use crate::{ use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; use layerfs_workspace::ViewStat; use std::{ - collections::HashMap, + collections::{BTreeSet, HashMap}, fs, path::{Path, PathBuf}, sync::{atomic::Ordering, Arc, Mutex}, @@ -117,6 +117,10 @@ pub(crate) struct Companions { tick: u64, files: HashMap, names: HashMap, + /// Every companion holding memory, oldest use first: (used tick, serial). + /// One tick is one touch and no serial takes two ticks, so the keys are + /// unique and the oldest entry is the first one. + by_use: BTreeSet<(u64, u64)>, resident_bytes: usize, decoded: usize, spill_dir: Option, @@ -129,6 +133,7 @@ impl Default for Companions { tick: 0, files: HashMap::new(), names: HashMap::new(), + by_use: BTreeSet::new(), resident_bytes: 0, decoded: 0, spill_dir: None, @@ -141,10 +146,22 @@ impl Companions { self.tick += 1; self.tick } + /// Marks `serial` as used now, which is the order eviction follows. Only a + /// companion holding memory is in the order: a spilled body has nothing to + /// give back. fn use_serial(&mut self, serial: u64) { let tick = self.tick(); - if let Some(file) = self.files.get_mut(&serial) { - file.used = tick; + self.set_used(serial, tick); + } + /// Moves `serial`'s index entry to `used`. + fn set_used(&mut self, serial: u64, used: u64) { + let Some(file) = self.files.get_mut(&serial) else { + return; + }; + let old = std::mem::replace(&mut file.used, used); + self.by_use.remove(&(old, serial)); + if file.resident_cost() > 0 { + self.by_use.insert((used, serial)); } } fn stat(serial: u64, file: &Companion) -> ViewStat { @@ -157,8 +174,11 @@ impl Companions { subdirs: 0, } } - /// Adds `file` to the index and to the byte counts. + /// Adds `file` to the index, the byte counts and the eviction order. fn attach(&mut self, serial: u64, file: Companion) { + if file.resident_cost() > 0 { + self.by_use.insert((file.used, serial)); + } self.resident_bytes += file.resident_cost(); self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); self.files.insert(serial, file); @@ -167,6 +187,7 @@ impl Companions { /// the caller to unindex. fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; + self.by_use.remove(&(file.used, serial)); self.resident_bytes -= file.resident_cost(); self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); Some(file) @@ -261,12 +282,12 @@ impl Companions { } /// The least recently used companion holding memory, a body kept as /// written or a decoded one: the budget counts both, so both are evicted. + /// One step into the eviction order, not a walk of every companion. fn oldest_resident(&self, skip: Option) -> Option { - self.files + self.by_use .iter() - .filter(|(serial, file)| Some(**serial) != skip && file.resident_cost() > 0) - .min_by_key(|(_, file)| file.used) - .map(|(serial, _)| *serial) + .find(|(_, serial)| Some(*serial) != skip) + .map(|(_, serial)| *serial) } fn holding(&self) -> Holding { Holding { diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 32a6ba9949..1bb272dc5a 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -29,12 +29,6 @@ use std::{ os::unix::fs::FileExt, }; -/// Rounds one edit takes to make room in the resident budget before it spills -/// its own body instead. Each round either spills the least recently touched -/// body or finds no body to spill; another call's spill can take the room a -/// round just made, which is why a round is retried at all. -const SPILL_ROUNDS: usize = 4; - impl Kernel { /// READ of a companion, at most `count` bytes from `offset`, appended to /// `out`; `eof` when the reply reaches the companion's end. @@ -134,9 +128,11 @@ impl Kernel { self.edit_companion(serial, Edit::Size(size as usize))?; } let mut companions = self.companions(); - let tick = companions.tick(); + if companions.files.get(&serial).is_none() { + return Err(Status::Stale); + } + companions.use_serial(serial); let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.used = tick; if let Some(mode) = sattr.mode { file.metadata.mode = mode & 0o777; } @@ -169,7 +165,7 @@ impl Kernel { // Held to the end: no other edit of this companion runs meanwhile. let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); let target = edit.target_len(); - for _ in 0..SPILL_ROUNDS { + loop { match self.edit_resident(serial, target, &edit)? { Room::Resident(stat) => return Ok(stat), Room::Spilled => break, @@ -261,22 +257,17 @@ impl Kernel { companions.attach(serial, file); Ok(stat) } - /// Spills the least recently used resident companions to disk (outside the - /// companion lock) until adding `need` bytes stays within `resident_budget`. - /// Returns `true` if `need` fits in resident memory afterwards. A victim - /// another call changed meanwhile is picked again on the next round; the - /// rounds are bounded by the index, and the caller then writes out its own - /// body, which needs no budget at all. + /// Spills the least recently used bodies to disk (outside the companion + /// lock) until adding `need` bytes stays within `resident_budget`. Returns + /// `true` if `need` fits in resident memory afterwards. Each round takes + /// the oldest entry of the eviction order, so a round costs one step into + /// it rather than a walk of every companion, and the rounds end when no + /// companion holding memory is left: a victim another call changed + /// meanwhile has moved to the newest end of the order, so it is not picked + /// twice, and the caller then writes out its own body, which needs no + /// budget at all. fn spill_for(&self, target: u64, need: usize) -> Result { - let mut rounds = { - let companions = self.companions(); - if companions.resident_bytes + need <= companions.resident_budget { - return Ok(true); - } - companions.files.len() - }; - while rounds > 0 { - rounds -= 1; + loop { let victim = { let companions = self.companions(); if companions.resident_bytes + need <= companions.resident_budget { @@ -287,11 +278,8 @@ impl Kernel { let Some(victim) = victim else { return Ok(false); }; - // A victim another call changed meanwhile leaves the next round to - // pick again; only a disk failure ends the loop. let _ = self.spill_one(victim, None)?; } - Ok(false) } /// Writes `serial`'s body out to the spill directory and switches it to /// that file, keeping at least `keep` bytes (all of them when `None`), diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 25aedc1d59..eaee250495 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -16,6 +16,7 @@ mod spy; #[path = "support/tree.rs"] mod tree; use client::{Client, Set, STALE}; +use layerfs_nfs::apple_double::SERIALS; use layerfs_nfs::apple_double_codec::{Attribute, Image}; use std::{ fs, @@ -51,6 +52,73 @@ fn image(finder: [u8; 32], attrs: &[(&[u8], Vec)]) -> Vec { .encode() } +/// The companions whose bodies the spill directory holds, by serial. +fn spill_serials(dir: &Path) -> Vec { + let mut serials: Vec = fs::read_dir(dir) + .map(|entries| { + entries + .flatten() + .filter_map(|entry| entry.file_name().to_str()?.parse().ok()) + .collect() + }) + .unwrap_or_default(); + serials.sort_unstable(); + serials +} + +#[test] +fn eviction_follows_the_order_of_use_not_the_shape_of_the_index() { + const HELD: usize = 64; + let base = temp("use-order"); + let tree = base.join("tree"); + source(&tree); + let spill = base.join("spill"); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(spill.clone()); + // Room for exactly 64 bodies of 16 bytes, so every body after the 64th + // takes the room of one other. + rig.companion_resident_bytes = 16 * HELD; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let body = pattern(50, 16); + let mut handles = Vec::with_capacity(HELD); + for n in 0..HELD { + c.touch(&root, format!("c{n}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._c{n}").as_bytes(), 0o644).unwrap(); + c.write(&ad.handle, 0, &body).unwrap(); + handles.push(ad.handle); + } + assert_eq!(server.held().companion_bytes, 16 * HELD); + assert!(spill_serials(&spill).is_empty(), "nothing is on disk yet"); + // Three bodies are read again, so they are the most recently used ones. + for n in [0, 1, 2] { + assert_eq!(c.read_all(&handles[n], 4096), body); + } + // Eight more bodies: the eight least recently used ones leave memory, in + // that order, and the three read again stay. + for n in HELD..HELD + 8 { + c.touch(&root, format!("c{n}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._c{n}").as_bytes(), 0o644).unwrap(); + c.write(&ad.handle, 0, &body).unwrap(); + } + let expected: Vec = (3..11).map(|n| SERIALS + n).collect(); + assert_eq!(spill_serials(&spill), expected); + assert_eq!(server.held().companion_bytes, 16 * HELD); + assert_eq!(server.held().companions, HELD + 8); + // The evicted bodies still hold their bytes, and the kept ones never left + // memory. + for n in [3, 7, 10, 0, 1, 2] { + assert_eq!(c.read_all(&handles[n], 4096), body, "companion {n}"); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn the_clients_write_sequence_is_served_byte_for_byte() { let base = temp("sequence"); From 0cbd34cd6509a451c696d61e6210a83bcdae615b Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:54:18 +0000 Subject: [PATCH 12/17] perf(nfs): adopt a spilled companion body without the rename under the lock (lp73) `Companions::adopt_spilled` ran `fs::rename` while holding the companion lock, so the module documentation's "file I/O never holds the companion lock" was not true of the step that puts the file in place. The adoption is now three steps with the lock dropped between them: `Companions::spill_target` (lock) answers the companion's own file and whether the body is still the one the file was written from, `fs::rename` runs outside the lock, and `Companions::commit_spilled` (lock) switches the body to `Body::Spilled` with its length. A reader keeps reading the body in memory until the rename is done, so no reader ever sees a half written or missing file. The exclusion the rename needs is the companion's own edit gate, which already means "one edit of this companion at a time": a gated edit holds it across its own adoption, and eviction now takes it with `try_lock`, skipping a companion another call is editing (it never waits for another call's I/O, so no two spills of one companion can meet at the file). `spill_for` therefore passes over a victim it could not spill instead of picking it again, and a companion that is gone is nothing to spill rather than an error. Review: finding 5 (disk I/O under the companion lock); the module docs of `edit.rs` and `apple_double_spill.rs` and `nfs.md` now state what the code does. Tests: `cargo test -p layerfs-nfs`: 48 passed, 0 failed (raw `test result` sum 49 with the child-process rerun of `spilled_companions_outnumber_the_open_file_limit`), including the spill, race and file-limit cases that adopt bodies. Production LOC: 164342 -> 164372 (delta +30) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 73f62efc2 (164342) and of the staged tree (164372). Engine +30. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 10 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 70 ++++++++--------- .../layerfs-nfs/src/apple_double/edit.rs | 75 ++++++++++++++++--- .../layerfs-nfs/src/apple_double_spill.rs | 6 +- 4 files changed, 111 insertions(+), 50 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index b325d78a29..5b110c5680 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -191,9 +191,13 @@ synthesizes the same bytes again. Partial writes, resource forks and other layouts stay as the client wrote them. Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` -together, spill outside the companion lock to -`..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by -rename to `` only if unchanged (`used` tick); spilled bodies are opened +together, are written to `..tmp` (`create_new`, dir `0700`, file +`0600`) and renamed to ``, all of it outside the companion lock; the +body is committed as spilled under the lock afterwards, so a reader reads the +body in memory until its file is whole. One writer per companion is the edit +gate (`Companion::editing`): an edit holds it, and an eviction takes it with +`try_lock`, skipping a companion someone is editing. A rename is dropped when +the body changed since the snapshot (`used` tick), and a spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), recording length and bytes together and spilling its own body rather than diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 5d6b172af0..b5c43c1455 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -34,7 +34,7 @@ //! which removes that directory too. use crate::{ apple_double_codec::Image, - apple_double_spill::{io_status, now, spill_path, touch, unlink_paths, Edit}, + apple_double_spill::{now, spill_path, touch, unlink_paths, Edit}, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, @@ -44,7 +44,7 @@ use layerfs_workspace::ViewStat; use std::{ collections::{BTreeSet, HashMap}, fs, - path::{Path, PathBuf}, + path::PathBuf, sync::{atomic::Ordering, Arc, Mutex}, }; @@ -243,50 +243,52 @@ impl Companions { Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), } } - /// Renames the temporary file `temp`, which holds `serial`'s body of `len` - /// bytes, to the companion's own name in the spill directory and switches - /// the companion to it. With `used`, the tick the snapshot was read at, - /// only a companion nothing touched since and whose body is still in memory - /// (resident or decoded) takes it: a body another call changed or already - /// spilled stays, `Ok(false)` then, and `temp` is the caller's to unlink. - /// `None` is an edit's own body written out while it holds the companion's - /// edit gate, so no other edit can have changed it. - fn adopt_spilled( - &mut self, - serial: u64, - used: Option, - temp: &Path, - len: usize, - ) -> Result { - let path = self - .spill_dir - .as_ref() - .map(|dir| spill_path(dir, serial)) - .ok_or(Status::NoSpc)?; - let Some(file) = self.files.get_mut(&serial) else { - return Err(Status::Stale); - }; + /// Where a body a spill wrote out replaces its companion: the companion's + /// own file, or `None` when another call changed the body since the + /// snapshot (`used` is the tick read then, and only a body still in memory + /// can be replaced). The caller renames its file to that path itself, + /// outside this lock, and then commits the body with + /// [`Self::commit_spilled`]. + fn spill_target(&self, serial: u64, used: Option) -> Result, Status> { + let file = self.files.get(&serial).ok_or(Status::Stale)?; if let Some(used) = used { if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { - return Ok(false); + return Ok(None); } } - fs::rename(temp, path).map_err(|e| io_status(&e))?; - let mut file = self.detach(serial).ok_or(Status::Stale)?; + let dir = self.spill_dir.as_ref().ok_or(Status::NoSpc)?; + Ok(Some(spill_path(dir, serial))) + } + /// Commits the body whose bytes now sit at the companion's spill file: it + /// holds them on disk from now on, `len` bytes of them, which were the + /// whole body the file was written from. `false` when the companion is gone + /// or already holds a file, and the file just renamed into place is the + /// caller's to drop. + /// + /// The caller holds the companion's edit gate and no other call writes this + /// companion's file, so a body that changed between the snapshot and here + /// cannot be the body this file was written from. + fn commit_spilled(&mut self, serial: u64, len: usize) -> bool { + let Some(mut file) = self.detach(serial) else { + return false; + }; + if matches!(file.body, Body::Spilled) { + self.attach(serial, file); + return false; + } file.body = Body::Spilled; - // A shorter file than the companion had described is not the body any - // more. file.len = file.len.max(len); self.attach(serial, file); - Ok(true) + true } /// The least recently used companion holding memory, a body kept as /// written or a decoded one: the budget counts both, so both are evicted. - /// One step into the eviction order, not a walk of every companion. - fn oldest_resident(&self, skip: Option) -> Option { + /// The companions the caller will not take are passed over, one step into + /// the eviction order rather than a walk of every companion. + fn oldest_resident(&self, skip: &BTreeSet) -> Option { self.by_use .iter() - .find(|(_, serial)| Some(*serial) != skip) + .find(|(_, serial)| !skip.contains(serial)) .map(|(_, serial)| *serial) } fn holding(&self) -> Holding { diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 1bb272dc5a..e30816bf74 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -12,8 +12,10 @@ //! A body that does not fit the resident budget is spilled first, least //! recently touched first; the body that still does not fit is written out //! itself and edited in its file, which needs no budget. The file I/O never -//! holds the companion lock, and no descriptor is kept for a spilled body: -//! each operation opens its file by path and closes it again. +//! holds the companion lock: the file is written from a body read under the +//! lock and renamed to the companion's own name outside it, before the body is +//! committed as spilled under the lock again. No descriptor is kept for a +//! spilled body: each operation opens its file by path and closes it again. use super::{edited_len, record, Body, Companions, DECODED_ENTRY_BYTES, FILE_BYTES}; use crate::{ apple_double_spill::{create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Room}, @@ -24,9 +26,11 @@ use crate::{ use layerfs_mount_ports::operations::write::Stamp; use layerfs_workspace::ViewStat; use std::{ - fs::{File, OpenOptions}, + collections::BTreeSet, + fs::{self, File, OpenOptions}, io, os::unix::fs::FileExt, + path::Path, }; impl Kernel { @@ -128,7 +132,7 @@ impl Kernel { self.edit_companion(serial, Edit::Size(size as usize))?; } let mut companions = self.companions(); - if companions.files.get(&serial).is_none() { + if !companions.files.contains_key(&serial) { return Err(Status::Stale); } companions.use_serial(serial); @@ -267,27 +271,45 @@ impl Kernel { /// twice, and the caller then writes out its own body, which needs no /// budget at all. fn spill_for(&self, target: u64, need: usize) -> Result { + let mut skip = BTreeSet::from([target]); loop { let victim = { let companions = self.companions(); if companions.resident_bytes + need <= companions.resident_budget { return Ok(true); } - companions.oldest_resident(Some(target)) + companions.oldest_resident(&skip) }; let Some(victim) = victim else { return Ok(false); }; - let _ = self.spill_one(victim, None)?; + if !self.spill_one(victim, None)? { + // The body changed under the file written from it, or the + // companion's own edit holds it: this call does not pick it + // again, and the next round looks at the body after it. + skip.insert(victim); + } } } /// Writes `serial`'s body out to the spill directory and switches it to /// that file, keeping at least `keep` bytes (all of them when `None`), /// with the disk I/O outside the companion lock. `Ok(false)` when another /// call changed the companion, or already spilled it, while the file was - /// written: that temporary file is dropped and the caller decides again on - /// the body it now finds. + /// written, or when the companion's own edit holds it: that temporary file + /// is dropped and the caller decides again on the body it now finds. fn spill_one(&self, serial: u64, keep: Option) -> Result { + let gate = { + let companions = self.companions(); + match companions.files.get(&serial) { + Some(file) => file.editing.clone(), + None => return Ok(true), + } + }; + // One writer of a companion's file at a time: an edit of this companion + // is writing to it, and a spill may not wait for another call's I/O. + let Ok(_editing) = gate.try_lock() else { + return Ok(false); + }; let (dir, bytes, size, used) = { let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; @@ -301,9 +323,7 @@ impl Kernel { (dir, bytes, size, file.used) }; let temp = create_spilled(&dir, serial, &bytes, size as u64)?; - let adopted = self - .companions() - .adopt_spilled(serial, Some(used), &temp, size); + let adopted = self.adopt_spilled(serial, Some(used), &temp, size); if matches!(adopted, Ok(true)) { return Ok(true); } @@ -327,12 +347,43 @@ impl Kernel { (dir, bytes, size) }; let temp = create_spilled(&dir, serial, &bytes, size as u64)?; - let adopted = self.companions().adopt_spilled(serial, None, &temp, size); + let adopted = self.adopt_spilled(serial, None, &temp, size); if !matches!(adopted, Ok(true)) { unlink_paths([temp]); } adopted.map(|_| ()) } + /// Renames `temp`, holding `serial`'s body written out, onto the + /// companion's own spill file and switches the companion to it. The + /// rename runs outside the companion lock: a reader keeps reading the + /// body in memory until the rename is done and the body is committed + /// under the lock again, and the file is never visible half written. The + /// caller holds the companion's edit gate for the whole adoption, so no + /// other call writes this companion's file. + fn adopt_spilled( + &self, + serial: u64, + used: Option, + temp: &Path, + len: usize, + ) -> Result { + let path = match self.companions().spill_target(serial, used) { + Ok(Some(path)) => path, + Ok(None) => return Ok(false), + Err(status) => return Err(status), + }; + if let Err(e) = fs::rename(temp, &path) { + // The temporary file is the caller's to drop: nothing was adopted. + return Err(io_status(&e)); + } + let committed = self.companions().commit_spilled(serial, len); + if !committed { + // The companion is gone or already holds a file: the file just put + // in place is this call's to drop. + unlink_paths([path]); + } + Ok(committed) + } /// The spill directory's file of `serial`, opened for one operation and /// closed again when the returned descriptor drops: the export holds no /// descriptor per spilled companion. A file or directory that is gone diff --git a/engine/crates/layerfs-nfs/src/apple_double_spill.rs b/engine/crates/layerfs-nfs/src/apple_double_spill.rs index 738bcc0268..dc00914dbc 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_spill.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_spill.rs @@ -5,7 +5,11 @@ //! `pread`/`pwrite` by an operation that opens it and closes it again: the //! export holds no descriptor per spilled body. A spill writes a temporary //! `..tmp` that only the call adopting it renames to ``, so -//! two calls spilling the same companion never share a file. The directory +//! two calls spilling the same companion never share a file; the rename runs +//! outside the companion lock, once the renaming call holds the companion's +//! edit gate, and the body is committed as spilled under the lock afterwards. +//! A reader therefore keeps reading the body in memory until the file is +//! whole, and never sees a partial one. The directory //! and its files are this user's alone; the modes are set here rather than //! left to the caller's umask. use crate::attributes::Status; From 485dd2f1aded43ca6cc6475d57f7ed08a6fbb3c8 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:56:32 +0000 Subject: [PATCH 13/17] fix(nfs): serve a READ that raced a truncation as a short read (lp73) `companion_read` took the companion's length under the companion lock and then read the spilled file outside it with `read_exact_at`. A truncation landing between the two made the file shorter than the window, and `read_exact_at` turned that into `NFS3ERR_IO` for a read of bytes the client had already been told were there. One `read_at` of that window is the whole reply: the bytes the file still holds, however many, are a short read at the truncation point, and `eof` still follows the length the lock saw. No retry, no second read. Review: finding 6 (spurious `NFS3ERR_IO` from READ). Tests: new `a_read_racing_a_truncation_is_a_short_read_not_an_io_error`, 512 rounds of one client reading a 64 KiB spilled body while another truncates it to zero: every reply is the body or a prefix of it, and the test client panics on any error status. Anti-proof: with `read_exact_at` back the test fails at round 0 (`panicked at tests/support/client.rs:248: self.read(...).unwrap()`). Production LOC: 164372 -> 164374 (delta +2) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 0cbd34cd6 (164372) and of the staged tree (164374). Engine +2. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/src/apple_double/edit.rs | 9 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 58 +++++++++++++++++++ 2 files changed, 65 insertions(+), 2 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index e30816bf74..8edb4be8f5 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -70,10 +70,15 @@ impl Kernel { (spilled, length, start, end) }; if spilled { + // One `pread` of the window the last lock saw, outside it: another + // call may have truncated the file since, and the bytes the file + // still holds are the reply - a short read, not an I/O error. let mut buf = vec![0u8; end - start]; - self.spill_file(serial, false)? - .read_exact_at(&mut buf, start as u64) + let read = self + .spill_file(serial, false)? + .read_at(&mut buf, start as u64) .map_err(|e| io_status(&e))?; + buf.truncate(read); out.extend_from_slice(&buf); } Ok(end as u64 >= length) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index eaee250495..3fa528a7ca 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -66,6 +66,64 @@ fn spill_serials(dir: &Path) -> Vec { serials } +#[test] +fn a_read_racing_a_truncation_is_a_short_read_not_an_io_error() { + let base = temp("read-truncate"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill")); + // Smaller than one body, so every read of the body is a `pread` of its file. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut reader = Client::connect(server.local_addr(), UID, GID); + let mut writer = Client::connect(server.local_addr(), UID, GID); + let root = reader.mnt("/"); + reader.touch(&root, b"raced", 0o644).unwrap(); + let ad = reader.touch(&root, b"._raced", 0o644).unwrap(); + let body = pattern(60, 64 * 1024); + reader.write(&ad.handle, 0, &body).unwrap(); + assert_eq!(server.held().companion_bytes, 0, "the body spilled"); + + // A length read under the companion lock and the bytes read outside it can + // disagree: the truncation below may land in between. The reply is then the + // bytes the file still holds, a short read, never `NFS3ERR_IO`. + let empty = Set { + size: Some(0), + ..Set::default() + }; + for round in 0..512 { + let start = std::sync::Barrier::new(2); + let (read, truncate) = std::thread::scope(|scope| { + let read = scope.spawn(|| { + start.wait(); + reader.read_all(&ad.handle, 64 * 1024) + }); + let truncate = scope.spawn(|| { + start.wait(); + writer.setattr(&ad.handle, empty, None) + }); + (read.join().unwrap(), truncate.join().unwrap()) + }); + truncate.unwrap(); + assert!( + body.starts_with(&read), + "round {round}: {} bytes read of the body or its truncation", + read.len() + ); + // The next round starts from the whole body again: nothing else runs + // while it is written back. + writer.write(&ad.handle, 0, &body).unwrap(); + assert_eq!(reader.getattr(&ad.handle).unwrap().size as usize, body.len()); + } + + drop((reader, writer)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn eviction_follows_the_order_of_use_not_the_shape_of_the_index() { const HELD: usize = 64; From e3e46ae06906e0e8a1fea442b76c41fd7b256bb7 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:57:27 +0000 Subject: [PATCH 14/17] docs(nfs): record the AppleDouble scratch area as a disposable area (lp73) Owner decision 2 approved `/.appledouble/` on condition that the architecture and the cleanup docs name it a new disposable area. nfs.md and the code already described it; the two remaining places did not. `docs/architecture/engine/daemon/README.md`: the "Starts NFS serving" row of the startup table now says the same reclaim that force-unmounts leftovers deletes `/.appledouble` (directories `0700`, files `0600`, no fsync, no space reserved ahead) and touches nothing else under the mount home. `docs/general/cleanup.md`: the classification table gains the scratch area as a disposable per-mount resource, with what it is and who deletes it. The test that says reclaim removes only `.appledouble` is still here: `startup_reclaim_clears_leftover_companion_spill_directories` puts a `kept/` file beside a leftover `.appledouble/7/stale`, and asserts the first survives and the second does not. Review: owner decision 2, condition "document it in the kernel routes, NFS and cleanup docs, and keep the reclaim test". Tests: `cargo test -p layerfs-nfs` at this commit: 49 passed, 0 failed (raw `test result` sum 50 with the child-process rerun of `spilled_companions_outnumber_the_open_file_limit`), including that daemon test. Production LOC: 164374 -> 164374 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 485dd2f1a (164374) and of the staged tree (164374, engine 75,739 in both). Docs and tests only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/daemon/README.md | 2 +- docs/general/cleanup.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/architecture/engine/daemon/README.md b/docs/architecture/engine/daemon/README.md index 4697766de6..3720ea868c 100644 --- a/docs/architecture/engine/daemon/README.md +++ b/docs/architecture/engine/daemon/README.md @@ -62,7 +62,7 @@ layerfs-daemon --config | Takes a fresh incarnation | `generate_keypair()`; the public half is `DaemonStatus.instance` | [`application/owner.rs`](../../../../engine/crates/layerfs-daemon/src/application/owner.rs) | | Opens the Store | An installed SQLite file with the `Disposable` profile, or PostgreSQL (feature `postgresql`); `Sqlite { install: None }` waits for an install | [`application/owner.rs`](../../../../engine/crates/layerfs-daemon/src/application/owner.rs), [`Cargo.toml`](../../../../engine/crates/layerfs-daemon/Cargo.toml) | | Starts FUSE serving (Linux) | `/dev/fuse` to `0600`, checks the mount home, mounts a private `fusectl` tree for abort controls; if that fails, writes `LAYERFS_DAEMON_ABORT_UNBOUND` and starts without forced unmount | [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs) | -| Starts NFS serving | `ExportServing`; force-unmounts client mounts a previous daemon left (`LAYERFS_NFS_RECLAIM` lines); helper overrides `LAYERFS_NFS_MOUNT`, `_UNMOUNT`, `_FORCE`, `_FLUSH` | [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs) | +| Starts NFS serving | `ExportServing`; force-unmounts client mounts a previous daemon left (`LAYERFS_NFS_RECLAIM` lines); the same reclaim deletes `/.appledouble`, the AppleDouble companions' disposable scratch area (directories `0700`, files `0600`, no fsync, no space reserved ahead), and touches nothing else under the mount home; helper overrides `LAYERFS_NFS_MOUNT`, `_UNMOUNT`, `_FORCE`, `_FLUSH` | [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | ### Phases and Hello diff --git a/docs/general/cleanup.md b/docs/general/cleanup.md index 0de4bdc7c1..da5558e14c 100644 --- a/docs/general/cleanup.md +++ b/docs/general/cleanup.md @@ -79,6 +79,7 @@ net change; do not attribute an unisolated change entirely to one removal. | Historical sample databases, exports, and payloads | Closed run, no current consumer, records preserved, disposal authorized | Remove selected payloads and record that they are unavailable for future proof reuse | | Prepared fixture masters, inventories, sealed Stores, binaries, and images | Current task, harness defaults, source identities, and reuse records | Keep resources selected for ongoing work or qualifying reuse | | Docker sample containers and volumes | Exact mapping to closed run records, current processes, consumers, and ownership | Stop and remove the identified resources after ownership is established | +| AppleDouble companion scratch area, `/.appledouble//` in a Sandbox's mount home | Disposable per-mount area: directories `0700`, files `0600`, no fsync and no space reserved ahead; the daemon deletes it at export release and its startup reclaim deletes any it finds, touching nothing else in the mount home | Remove it with the mount home or Sandbox it belongs to; it never holds Workspace, Commit or Store state, so no proof needs it kept | | Inactive agent transcripts and text records | No writer; no pinned file identity or current allocation requirement | Prefer verified transparent compression where supported | | Live application databases, WAL files, active logs, and session state | Owning application and current use | Preserve | | Download, installer, browser, and package caches | Current consumers, installation activity, and supported pruning behavior | Remove unused staging files or prune through the appropriate installed tool | From 428ffc34b9d2717a2e6e2d8970720f9a6beaaa47 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:45:48 +0000 Subject: [PATCH 15/17] chore(nfs): make the AppleDouble codec edits fmt- and clippy-clean (lp73) `cargo fmt --check` reported three files of this layer: the `emit` call rustfmt wraps in `Image::encode_range`, and two assertions of the new codec and decode tests. This is that pass and nothing else. The one remaining fmt report, `api/crates/layerfs-cli/tests/concurrent_reads.rs`, is not touched by this branch (`git log 8cfb6e273..HEAD -- ` is empty) and is left alone. Checks: `cargo +1.85.1 fmt --all -- --check` reports only that file; `cargo +1.85.1 clippy --locked -p layerfs-nfs --all-targets -- -D warnings` is clean; `cargo test -p layerfs-nfs` passes every binary. Production LOC: 163896 -> 163901 (delta +5) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 7ef50a034 (163896) and of the staged tree (163901). Engine +5: rustfmt splits the `emit` call, which the counter counts. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double_codec.rs | 7 ++++++- engine/crates/layerfs-nfs/tests/apple_double_codec.rs | 5 ++++- engine/crates/layerfs-nfs/tests/apple_double_decode.rs | 1 - 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs index 1e45130f78..459b507c96 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -238,7 +238,12 @@ impl Image { let name_end = name_at + attr.name.len(); emit(&mut out, start, name_at, &attr.name); let next = entry + entry_len(name_len); - emit(&mut out, start, name_end + 1, &attr.pad[..next - name_end - 1]); + emit( + &mut out, + start, + name_end + 1, + &attr.pad[..next - name_end - 1], + ); emit(&mut out, start, value_at, &attr.value); entry = next; value_at += attr.value.len(); diff --git a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs index b4d0c32098..548eeb87a9 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs @@ -96,7 +96,10 @@ fn any_window_of_the_image_encodes_to_that_window() { assert_eq!(built.encode_range(len + 10, len + 20), Vec::::new()); assert_eq!(built.encode_range(7, 3), Vec::::new()); assert_eq!(built.encode_range(0, len + 10), bytes); - assert_eq!(built.encode_range(len - 1, len + 10), bytes[len - 1..].to_vec()); + assert_eq!( + built.encode_range(len - 1, len + 10), + bytes[len - 1..].to_vec() + ); // The fork's own bytes are not all zero: a window inside it is served // from the fork, not from the zeroed layout. let fork_at = get32(&bytes, FORK_AT) as usize; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index dea993d169..73fe47c666 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -156,4 +156,3 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } - From ec17db8711d12b786daf8f666da78efe83c9163e Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:40:39 +0000 Subject: [PATCH 16/17] fix(nfs): keep an eviction victim's failure out of the writer's reply (lp73) `spill_for` passed a victim's error straight out with `?`. A victim another call had just removed answered `NFS3ERR_STALE`, and one whose spill file could not be written answered `NFS3ERR_NOSPC`/`NFS3ERR_IO`, so an unrelated WRITE failed on a companion it never named while its own body was still in memory. A victim that leaves nothing to give back, that another call changed under its file, that its own edit holds, or that cannot be written out is now passed over and the round looks at the body after it. The writer only answers its own error, from spilling its own body, which needs no budget; a writer that finds no room and cannot write out its own body still reports that. Review: finding P2-2 (an eviction victim's error reaching an unrelated writer). The report claimed this was already skipped; the code and the report now agree. Tests: new `an_eviction_victim_that_cannot_be_written_out_does_not_fail_the_writer`. Two resident bodies of 1,000 bytes in a 2,000-byte budget, the oldest one's spill path made a non-empty directory so its spill cannot be adopted, then a third 1,000-byte write: it lands, the oldest body stays in memory byte-identical, the second is on disk and reads back, and only that one file is in the spill directory. Anti-proof: with `?` back the third write answers `NFS3ERR_IO` (`Err value: 5`) and the test fails on it. Production LOC: 164379 -> 164379 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent bdb87afaa (164379) and of the staged tree (164379). Engine 0: the round's condition keeps one line and the rest is comment. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 4 +- .../layerfs-nfs/src/apple_double/edit.rs | 15 +++-- .../layerfs-nfs/tests/apple_double_decode.rs | 63 ++++++++++++++++++- 3 files changed, 76 insertions(+), 6 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 5b110c5680..f5d9a151f8 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -196,7 +196,9 @@ together, are written to `..tmp` (`create_new`, dir `0700`, file body is committed as spilled under the lock afterwards, so a reader reads the body in memory until its file is whole. One writer per companion is the edit gate (`Companion::editing`): an edit holds it, and an eviction takes it with -`try_lock`, skipping a companion someone is editing. A rename is dropped when +`try_lock`, skipping a companion someone is editing, one another call removed +and one whose file cannot be written out; only a call that finds no room and +then cannot write out its own body answers its own error. A rename is dropped when the body changed since the snapshot (`used` tick), and a spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 8edb4be8f5..8e24ffb9e8 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -275,6 +275,12 @@ impl Kernel { /// meanwhile has moved to the newest end of the order, so it is not picked /// twice, and the caller then writes out its own body, which needs no /// budget at all. + /// + /// A victim that cannot be written out is no failure of this call: one + /// another call removed has nothing left to give back, and one whose file + /// cannot be written keeps its body in memory, so the round passes over it + /// and looks at the body after it. Only a call that finds no room and then + /// cannot write out its own body reports that error, and it is its own. fn spill_for(&self, target: u64, need: usize) -> Result { let mut skip = BTreeSet::from([target]); loop { @@ -288,10 +294,11 @@ impl Kernel { let Some(victim) = victim else { return Ok(false); }; - if !self.spill_one(victim, None)? { - // The body changed under the file written from it, or the - // companion's own edit holds it: this call does not pick it - // again, and the next round looks at the body after it. + if self.spill_one(victim, None) != Ok(true) { + // The body changed under the file written from it, the + // companion's own edit holds it, or its file could not be + // written: this call does not pick it again, and the next + // round looks at the body after it. skip.insert(victim); } } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 5b2508abd5..4afab58a26 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -58,7 +58,10 @@ fn spill_serials(dir: &Path) -> Vec { .map(|entries| { entries .flatten() - .filter_map(|entry| entry.file_name().to_str()?.parse().ok()) + .filter_map(|entry| { + entry.file_type().ok().filter(std::fs::FileType::is_file)?; + entry.file_name().to_str()?.parse().ok() + }) .collect() }) .unwrap_or_default(); @@ -421,3 +424,61 @@ fn a_decoded_companion_is_edited_under_a_full_resident_budget() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn an_eviction_victim_that_cannot_be_written_out_does_not_fail_the_writer() { + let base = temp("victim-error"); + let tree = base.join("tree"); + source(&tree); + let spill = base.join("spill"); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(spill.clone()); + // Room for two bodies of 1,000 bytes: a third one makes the two oldest + // give their room back. + rig.companion_resident_bytes = 2000; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let mut bodies = Vec::new(); + for i in 0..2 { + c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._m{i}").as_bytes(), 0o644).unwrap(); + let body = pattern(60 + i, 1000); + c.write(&ad.handle, 0, &body).unwrap(); + bodies.push((ad.handle, body)); + } + assert_eq!(server.held().companion_bytes, 2000); + + // The oldest body's spill file is a directory with a file in it, so no + // file can be renamed onto it: evicting that body fails. + let oldest = format!("{SERIALS}"); + fs::create_dir_all(spill.join(&oldest)).unwrap(); + fs::write(spill.join(&oldest).join("kept"), b"not a spill file").unwrap(); + + // A third body needs room. The victim that cannot be written out is + // passed over, the next one gives its room back, and this call's own + // write lands: the failure belonged to a companion this writer never + // named. + c.touch(&root, b"m2", 0o644).unwrap(); + let third = c.touch(&root, b"._m2", 0o644).unwrap(); + let body = pattern(62, 1000); + c.write(&third.handle, 0, &body).unwrap(); + assert_eq!(c.read_all(&third.handle, 4096), body); + assert_eq!( + spill_serials(&spill), + vec![SERIALS + 1], + "the victim whose file cannot be written stays in memory" + ); + assert_eq!(server.held().companion_bytes, 2000); + // Both other bodies still read back byte for byte: the spilled one from + // its file, the passed-over one from memory. + for (handle, want) in &bodies { + assert_eq!(&c.read_all(handle, 4096), want); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From aec83af3a66c5fcd9f5dd6a5d2c34da6390719f2 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:41:48 +0000 Subject: [PATCH 17/17] fix(nfs): leave a failed disk edit's length where it was (lp73) Three edges of the spill path, none of them a behaviour the client can rely on today: - A body written out whole is spilled at the length the edit wanted, and `commit_spilled` records that longer length before the edit touches the file. A `write_all_at`/`set_len` that then fails (`NFS3ERR_NOSPC`, `NFS3ERR_IO`) answered the error but left the companion longer, zero-filled: a refused edit that had changed the body's size. `apply_edit` now keeps the length the companion had and puts it back when the file operation fails, so a failed WRITE/SETATTR leaves the length as it was, as a refused slot does. - `spill_one` took the victim's edit gate with `try_lock` and read every `Err` as "busy", `Poisoned` included: a companion whose edit panicked could never be evicted, so it held its body for the export's life. A poisoned gate is now taken anyway, as every other holder of it does. - A spilled READ's one `pread` answered `NFS3ERR_IO` when a signal interrupted it, although no byte of it had moved. It is asked again in that case only; the read is still one read of one window, and a short read is still the reply. Review: findings P3-2, P3-3 and P3-5. Tests: none new. The length restore only shows on a filesystem error after a successful spill (the file is already at the wanted length, so `RLIMIT_FSIZE` and a directory at the spill path fail before it), the poisoned gate needs a panicking edit, and `EINTR` needs a signal landing inside one `pread`; all three are timing- or filesystem-dependent, and the change is a guard each. `cargo test -p layerfs-nfs`: 51 passed, 0 failed (raw sum 52 with the child-process rerun). Production LOC: 164379 -> 164405 (delta +26) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent ec17db871 (164379) and of the staged tree (164405). Engine +26: the length snapshot and restore (8), the poisoned-gate match (5), the interrupted-read loop and its helper (11), and the two rewritten error paths. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 4 +- .../layerfs-nfs/src/apple_double/edit.rs | 55 +++++++++++++++---- 2 files changed, 48 insertions(+), 11 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index f5d9a151f8..308e1fd69e 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -203,7 +203,9 @@ the body changed since the snapshot (`used` tick), and a spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), recording length and bytes together and spilling its own body rather than -failing with `NFS3ERR_IO`. Eviction follows `Companions::by_use`, the +failing with `NFS3ERR_IO`. A file operation that fails after the spill put the +length the companion had back, so a refused write reports neither bytes nor the +longer file the spill made for it. Eviction follows `Companions::by_use`, the `(used tick, serial)` order kept on attach, detach and every use: the victim is the first entry (O(log n) per round, no walk of the index), and the rounds end when no companion holding memory is left. diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 8e24ffb9e8..f02eca56e0 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -33,6 +33,18 @@ use std::{ path::Path, }; +/// One `pread` of `buf` at `offset`: a short read is the answer, and a read a +/// signal interrupted is asked again, since no bytes of it moved. +fn read_window(file: &File, buf: &mut [u8], offset: u64) -> Result { + loop { + match file.read_at(buf, offset) { + Ok(read) => return Ok(read), + Err(e) if e.kind() == io::ErrorKind::Interrupted => {} + Err(e) => return Err(io_status(&e)), + } + } +} + impl Kernel { /// READ of a companion, at most `count` bytes from `offset`, appended to /// `out`; `eof` when the reply reaches the companion's end. @@ -74,10 +86,7 @@ impl Kernel { // call may have truncated the file since, and the bytes the file // still holds are the reply - a short read, not an I/O error. let mut buf = vec![0u8; end - start]; - let read = self - .spill_file(serial, false)? - .read_at(&mut buf, start as u64) - .map_err(|e| io_status(&e))?; + let read = read_window(&self.spill_file(serial, false)?, &mut buf, start as u64)?; buf.truncate(read); out.extend_from_slice(&buf); } @@ -188,11 +197,33 @@ impl Kernel { } } // The body still does not fit resident memory: write it out and edit - // its file, which needs no body budget. - self.spill_gated(serial, target)?; - edit.disk(&self.spill_file(serial, true)?)?; + // its file, which needs no body budget. A failed file operation leaves + // the length the companion had: the spill may have grown its file to + // the length this edit wanted, and a refused edit must not report it. + let before = self + .companions() + .files + .get(&serial) + .map(|file| file.len) + .ok_or(Status::Stale)?; + let written = self.spill_gated(serial, target).and_then(|()| { + let file = self.spill_file(serial, true)?; + edit.disk(&file) + }); + if let Err(status) = written { + self.restore_len(serial, before); + return Err(status); + } self.record_edit(serial, &edit) } + /// Puts back the length `serial` had before an edit whose file operation + /// failed. + fn restore_len(&self, serial: u64, len: usize) { + let mut companions = self.companions(); + if let Some(file) = companions.files.get_mut(&serial) { + file.len = len; + } + } /// Applies `edit` to `serial`'s body in memory while the budget holds it /// (a decoded body is encoded first), recording its length, recency and /// time and deciding again whether it is a whole image, under the same @@ -318,9 +349,13 @@ impl Kernel { } }; // One writer of a companion's file at a time: an edit of this companion - // is writing to it, and a spill may not wait for another call's I/O. - let Ok(_editing) = gate.try_lock() else { - return Ok(false); + // is writing to it, and a spill may not wait for another call's I/O. A + // gate poisoned by a panic is taken anyway, as every other holder of it + // does, so one panicked edit does not make its body undevictable. + let _editing = match gate.try_lock() { + Ok(editing) => editing, + Err(std::sync::TryLockError::Poisoned(poison)) => poison.into_inner(), + Err(std::sync::TryLockError::WouldBlock) => return Ok(false), }; let (dir, bytes, size, used) = { let companions = self.companions();