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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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/34] 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 dc2c54c0f0f38aa22685be715a55d0a2834b3b5f Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:48:30 +0000 Subject: [PATCH 08/34] feat(nfs): one companion per inode, beyond 4,096 per export (lp73) A companion created while the export knows its main file (`` in the same directory) now belongs to that inode: every name of the inode reaches it, so hard links share one, it follows the inode through RENAME and it goes with the inode's last name. Such a companion holding a complete AppleDouble image is `whole`: it takes no slot of the index bound, and `rename`/`silly rename`/ `remove` of the main file drop it through `Kernel::companion_drop_for` and `companion_drop_inode`. `HELD` rises from 4,096 companions to 65,536 slotted entries: at the bound, orphan slotted companions are reclaimed first, and only if 65,536 live ones remain does CREATE answer `NFS3ERR_NOSPC`, count `names_refused` and log at most once per 60 s per export. The name index is the other half of it. `Table::aliases` remembers a hard-linked inode's names beyond `Table::names`, so `entry_taken` (when the engine reports `nlink <= 1`), `renamed`, `finish_unlink` and retirement drop only their own serial's keys from `by_name` instead of scanning it; a name that was moving to another inode is dropped through `Table::unbind_any`. CREATE at the bound releases the companion lock to collect orphans, then re-reads the companion name and main file under the lock it now holds, so two GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. `Companions::slots` walks only slotted entries - whole images add nothing - and `classify` decides again under RENAME's destination, so a companion moved onto an unknown main takes its slot back while a spilled body keeps the class the write that spilled it left (a decode there would read its file under the lock). `Kernel::companions_release` reports `Holding`, and `Released` carries `companions_slotted` and `companions` counted over whole images too. This is the last layer of the AppleDouble split (LP636) and reproduces `2e09f0295`'s companion code; the review's open findings are handled in the next task. Tests: `cargo test -p layerfs-nfs` 60 passed, 0 failed (raw sum 61: the file-limit case re-runs itself in a child process): 16 write, 11 decode, 6 codec, 2 daemon cases. Production LOC: 164334 -> 164574 (delta +240) 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 8183f8969 (164334) and this tree (164574). Engine +240. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 333 +++++++++++++++--- .../layerfs-nfs/src/apple_double/edit.rs | 3 +- engine/crates/layerfs-nfs/src/change.rs | 10 +- engine/crates/layerfs-nfs/src/kernel.rs | 127 +++++-- .../crates/layerfs-nfs/src/kernel/released.rs | 24 +- engine/crates/layerfs-nfs/src/server.rs | 5 + 6 files changed, 418 insertions(+), 84 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 98fe0a665a..e4db0a5782 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -16,21 +16,32 @@ //! directory it names, so its `wcc_data` answers both halves from the last //! facts the export saw for it (see [`Kernel::directory_wcc`]). //! -//! 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. Any other body (a resource fork, -//! another layout, a half-written image) is kept as the client wrote it. +//! A companion created while the export knows its main file (`` in the +//! same directory) belongs to that inode: any name of the inode reaches it, so +//! hard links share one companion, it follows the inode through RENAME, and it +//! goes with the inode's last name rather than with one name. Its FinderInfo +//! and extended attributes are kept under that inode's serial, not under the +//! `._` name. Whenever a write leaves such 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. Such a whole image takes no slot of the index bound. Any other body +//! (a resource fork, another layout, a half-written image, or a companion whose +//! main file is unknown) is kept as the client wrote it and takes a slot: the +//! index bound, the refusal, its rate-limited log and orphan reclamation stay +//! the fallback for everything decoding does not compress. //! -//! 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`]. 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. +//! Every companion keeps its index entry in memory (at most [`HELD`] of them +//! not holding a whole image, each companion at most [`FILE_BYTES`]). Bodies up +//! to [`RESIDENT_BYTES`] in all stay in memory; when a write or resize crosses +//! that budget, the least recently touched resident bodies are spilled to the +//! export's own scratch directory (see [`crate::apple_double_spill`]). Removing +//! or replacing a main file drops its paired `._` companion, or only that +//! name when the companion is its inode's, which goes with the inode's last +//! name. When [`HELD`] is reached, orphan companions whose main inode or main +//! file the export no longer knows are reclaimed first, and only if [`HELD`] +//! live companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. use crate::{ apple_double_codec::Image, apple_double_spill::{io_status, now, spill_path, touch, unlink_paths, Edit}, @@ -41,10 +52,11 @@ use crate::{ use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; use layerfs_workspace::ViewStat; use std::{ - collections::HashMap, + collections::{HashMap, HashSet}, fs, path::{Path, PathBuf}, sync::{atomic::Ordering, Arc, Mutex}, + time::{Duration, Instant}, }; mod edit; @@ -52,8 +64,8 @@ mod edit; /// The first serial of the export's own companions, far above any serial the /// engine allocates. pub const SERIALS: u64 = 1 << 62; -/// Companion index entries held at once. -pub const HELD: usize = 4096; +/// Companion index entries not holding a whole image, held at once. +pub const HELD: usize = 65_536; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; /// Companion payload bytes kept resident in memory before spilling to disk. @@ -80,6 +92,11 @@ enum Body { struct Companion { /// The `._` name it was created or last renamed to. named: Named, + /// The main inode it belongs to, when the export knew it at creation. + inode: Option, + /// Its body is a whole image: any name of the inode reads it, and it takes + /// no slot of the index bound. + whole: bool, len: usize, body: Body, metadata: PortableMetadata, @@ -103,12 +120,17 @@ impl Companion { Body::Resident(_) | Body::Spilled => 0, } } + /// Whether it takes a slot of the index bound. + fn slotted(&self) -> bool { + !self.whole + } } /// What an export's companion index holds (see [`crate::kernel::Released`]). #[derive(Clone, Copy, Debug, Default)] pub(crate) struct Holding { pub held: usize, + pub slotted: usize, pub resident_bytes: usize, pub decoded: usize, pub decoded_bytes: usize, @@ -120,11 +142,21 @@ pub(crate) struct Companions { tick: u64, files: HashMap, names: HashMap, + /// Main inode serial -> the companion holding its FinderInfo and + /// attributes. + inodes: HashMap, + /// The serials taking a slot of the index bound, so reclamation walks only + /// the [`HELD`]-bounded slots rather than every companion: a whole image + /// takes no slot (whether decoded within [`DECODED_BYTES`] or kept as + /// written bytes above it), so whole images add nothing to the walk. + slots: HashSet, resident_bytes: usize, decoded: usize, decoded_bytes: usize, spill_dir: Option, resident_budget: usize, + held_limit: usize, + last_refusal_log: Option, } impl Default for Companions { fn default() -> Self { @@ -133,11 +165,15 @@ impl Default for Companions { tick: 0, files: HashMap::new(), names: HashMap::new(), + inodes: HashMap::new(), + slots: HashSet::new(), resident_bytes: 0, decoded: 0, decoded_bytes: 0, spill_dir: None, resident_budget: RESIDENT_BYTES, + held_limit: HELD, + last_refusal_log: None, } } } @@ -162,27 +198,69 @@ impl Companions { subdirs: 0, } } - /// Adds `file` to the index and to the byte counts. + /// Adds `file` to the index and to the slot and byte counts. fn attach(&mut self, serial: u64, file: Companion) { + if file.slotted() { + self.slots.insert(serial); + } 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 + /// Takes `serial` out of the index and the counts; its name keys stay for /// the caller to unindex. fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; + self.slots.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) } + /// Makes `file`'s name and main inode find `serial`. + fn index(&mut self, serial: u64, file: &Companion) { + self.names.insert(file.named.clone(), serial); + if let Some(inode) = file.inode { + self.inodes.insert(inode, serial); + } + } + /// Drops `file`'s name and inode keys that still find `serial`. + fn unindex(&mut self, serial: u64, file: &Companion) { + if self.names.get(&file.named) == Some(&serial) { + self.names.remove(&file.named); + } + if let Some(inode) = file.inode { + if self.inodes.get(&inode) == Some(&serial) { + self.inodes.remove(&inode); + } + } + } + /// The companion `named` reaches when its main file is `main`: the one + /// held under that name, unless it belongs to another inode than `main`, + /// else the one its main inode already has. + fn resolve(&self, named: &Named, main: Option) -> Option { + if let Some(&serial) = self.names.get(named) { + let inode = self.files.get(&serial).and_then(|file| file.inode); + if inode.is_none() || main.is_none() || inode == main { + return Some(serial); + } + } + main.and_then(|main| self.inodes.get(&main).copied()) + } /// 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. + /// edited body of `len` bytes, when the decoded budget takes it and the + /// export knows the companion's main inode. 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 { + // Only an inode's companion is decoded: one whose main file the export + // never saw keeps the client's bytes as written and a slot of the + // index bound, so that bound and orphan reclamation still reach it. + let inode = self.files.get(&serial).and_then(|file| file.inode); + if inode.is_none() { + return false; + } let Some(image) = Image::compact(bytes) else { return false; }; @@ -200,23 +278,43 @@ impl Companions { } file.len = len; file.body = Body::Decoded(image); + file.whole = true; file.used = tick; touch(&mut file.metadata); self.attach(serial, file); true } - /// 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. + /// Decides whether `file`'s body is a whole image: a decoded body of an + /// inode's companion always is; a resident body of one is decoded when it + /// parses back to the same bytes and the decoded budget takes it. A + /// companion whose main file the export does not know is never a whole + /// image: it keeps the client's bytes as written and a slot of the index + /// bound, so that bound and orphan reclamation still reach it. `file` must + /// be detached from the index. fn classify(&self, file: &mut Companion) { + if file.inode.is_none() { + // Only a decoded body has to become bytes again; a body on disk + // keeps its file and takes a slot. + if let Body::Decoded(image) = &file.body { + file.body = Body::Resident(image.encode()); + } + file.whole = false; + return; + } // 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. + file.whole = match &file.body { + Body::Decoded(_) => true, + Body::Spilled => file.whole, + Body::Resident(_) => false, + }; let Body::Resident(bytes) = &file.body else { return; }; let Some(image) = Image::compact(bytes) else { return; }; + file.whole = true; let cost = image.cost(); if cost <= DECODED_ENTRY_BYTES && self.decoded_bytes + cost <= DECODED_BYTES { file.body = Body::Decoded(image); @@ -224,7 +322,7 @@ impl Companions { } fn take_serial(&mut self, serial: u64) -> Option { let file = self.detach(serial)?; - self.names.remove(&file.named); + self.unindex(serial, &file); match file.body { Body::Resident(_) | Body::Decoded(_) => None, Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), @@ -261,8 +359,9 @@ impl Companions { 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. + // A body written out whole is still a whole image; a shorter file + // than the companion had described is not. + file.whole &= len <= file.len; file.len = file.len.max(len); self.attach(serial, file); Ok(true) @@ -280,6 +379,7 @@ impl Companions { fn holding(&self) -> Holding { Holding { held: self.files.len(), + slotted: self.slots.len(), resident_bytes: self.resident_bytes, decoded: self.decoded, decoded_bytes: self.decoded_bytes, @@ -314,13 +414,51 @@ impl Kernel { .lock() .unwrap_or_else(|poison| poison.into_inner()) } - pub(crate) fn configure_companions(&self, spill_dir: Option, resident_budget: usize) { + pub(crate) fn configure_companions( + &self, + spill_dir: Option, + resident_budget: usize, + held_limit: 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; + companions.held_limit = held_limit.max(1); + } + /// The main inode `._` in `parent` pairs with, as the export's own + /// name index knows it. Takes the kernel table: never call it under the + /// companion lock. + fn main_of(&self, parent: u64, name: &[u8]) -> Option { + let main = name.strip_prefix(b"._").filter(|main| !main.is_empty())?; + self.table().by_name.get(&(parent, main.to_vec())).copied() + } + /// The companions no name reaches any more: one whose main inode holds no + /// name in the kernel table, and one whose main file the export never + /// observed and does not know now. Taken under the kernel table lock and, + /// inside it, the companion lock, so nothing here copies the namespace; + /// the caller drops them by serial under the companion lock again. + fn orphans(&self) -> Vec<(u64, Option)> { + let table = self.table(); + let companions = self.companions(); + companions + .slots + .iter() + .filter_map(|serial| { + let file = companions.files.get(serial)?; + let live = match file.inode { + Some(inode) => { + table.names.contains_key(&inode) || table.aliases.contains_key(&inode) + } + None => file.named.1.strip_prefix(b"._").is_some_and(|main| { + table.by_name.contains_key(&(file.named.0, main.to_vec())) + }), + }; + (!live).then_some((*serial, file.inode)) + }) + .collect() } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { @@ -330,10 +468,12 @@ impl Kernel { companions.use_serial(serial); Ok(stat) } - /// LOOKUP of a companion name, if one is held for it. + /// LOOKUP of a companion name, if one is held for it or for its main + /// inode. pub(crate) fn companion_named(&self, parent: u64, name: &[u8]) -> Option { + let main = self.main_of(parent, name); let mut companions = self.companions(); - let serial = *companions.names.get(&(parent, name.to_vec()))?; + let serial = companions.resolve(&(parent, name.to_vec()), main)?; let stat = Companions::stat(serial, companions.files.get(&serial)?); companions.use_serial(serial); Some(stat) @@ -379,14 +519,57 @@ impl Kernel { return Err(Status::NotDir); } let named = (parent, name.to_vec()); + let mut main = self.main_of(parent, name); let mut companions = self.companions(); - if let Some(serial) = companions.names.get(&named).copied() { + if let Some(serial) = companions.resolve(&named, main) { return self.companion_open(serial, how, directory, companions, tickets); } - if companions.files.len() >= HELD { + // At the index bound, reclaim the companions no name reaches any more + // first: found under the kernel table and the companion index, one + // entry at a time, so nothing here copies the namespace. + let mut reclaimed = Vec::new(); + if companions.slots.len() >= companions.held_limit { drop(companions); - self.names_refused.fetch_add(1, Ordering::Relaxed); - return Err(Status::Access); + let orphans = self.orphans(); + // The reclaim held no companion lock, so another CREATE of this + // name may have inserted it meanwhile and the main file may have + // changed: both are read again, and the name is inserted under the + // lock this call now holds without releasing it again. + main = self.main_of(parent, name); + companions = self.companions(); + if let Some(serial) = companions.resolve(&named, main) { + return self.companion_open(serial, how, directory, companions, tickets); + } + for (serial, inode) in orphans { + let still_orphan = companions + .files + .get(&serial) + .is_some_and(|file| file.inode == inode && file.slotted()); + if still_orphan { + reclaimed.extend(companions.take_serial(serial)); + } + } + } + if companions.slots.len() >= companions.held_limit { + let held = companions.slots.len(); + let limit = companions.held_limit; + let log = companions + .last_refusal_log + .is_none_or(|last| last.elapsed() >= Duration::from_secs(60)); + let namespace = log.then(|| companions.spill_dir.clone()); + if log { + companions.last_refusal_log = Some(Instant::now()); + } + drop(companions); + unlink_paths(reclaimed); + let refused = self.names_refused.fetch_add(1, Ordering::Relaxed) + 1; + if let Some(namespace) = namespace { + eprintln!( + "layerfs-nfs: AppleDouble index full: export={:?} namespace={namespace:?} parent={parent} companions={held} limit={limit} names_refused={refused}; NFS3ERR_NOSPC", + self.mount() + ); + } + return Err(Status::NoSpc); } let mut metadata = now(); if let How::Unchecked(sattr) | How::Guarded(sattr) = how { @@ -398,7 +581,9 @@ impl Kernel { companions.next += 1; let used = companions.tick(); let file = Companion { - named: named.clone(), + named, + inode: main, + whole: false, len: 0, body: Body::Resident(Vec::new()), metadata, @@ -406,25 +591,73 @@ impl Kernel { editing: Arc::new(Mutex::new(())), }; let stat = Companions::stat(serial, &file); - companions.names.insert(named, serial); + companions.index(serial, &file); companions.attach(serial, file); drop(companions); + unlink_paths(reclaimed); self.names_detached.fetch_add(1, Ordering::Relaxed); Ok((stat, directory)) } /// 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 main = self.main_of(parent, name); let spilled = { let mut companions = self.companions(); - let serial = *companions.names.get(&(parent, name.to_vec()))?; + let serial = companions.resolve(&(parent, name.to_vec()), main)?; companions.take_serial(serial) }; unlink_paths(spilled); Some(self.directory_wcc(parent)) } + /// The main file `name` in `parent` was removed, silly-renamed or replaced + /// by `RENAME`: drops the companion held under `._`, or only that + /// name when the companion belongs to an inode, which goes with the + /// inode's last name instead (see [`Kernel::companion_drop_inode`]). A + /// plain non-replacing `RENAME` of a main file only cleans the destination + /// name `to/new_name` (via `finish_unlink`) and leaves `from/name` alone so + /// a client that renames `a -> b` and then renames `._a -> ._b` can still + /// move the companion across. + pub(crate) fn companion_drop_for(&self, parent: u64, name: &[u8]) { + if crate::names::apple_double(name) { + return; + } + let mut paired = Vec::with_capacity(2 + name.len()); + paired.extend_from_slice(b"._"); + paired.extend_from_slice(name); + let named = (parent, paired); + let spilled = { + let mut companions = self.companions(); + let Some(&serial) = companions.names.get(&named) else { + return; + }; + if companions + .files + .get(&serial) + .is_some_and(|file| file.inode.is_some()) + { + companions.names.remove(&named); + None + } else { + companions.take_serial(serial) + } + }; + unlink_paths(spilled); + } + /// Drops the companion of inode `main`, whose last name is gone. + pub(crate) fn companion_drop_inode(&self, main: u64) { + let spilled = { + let mut companions = self.companions(); + let Some(serial) = companions.inodes.get(&main).copied() else { + return; + }; + companions.take_serial(serial) + }; + unlink_paths(spilled); + } /// RENAME of a companion name: only to another AppleDouble name, which it - /// replaces when held. `None` when no companion has that name. + /// replaces when held. It then belongs to the destination's main inode, or + /// to none when that is unknown. `None` when no companion has that name. pub(crate) fn companion_rename( &self, from: u64, @@ -432,25 +665,34 @@ impl Kernel { to: u64, new_name: &[u8], ) -> Option> { + let from_main = self.main_of(from, name); + let to_main = self.main_of(to, new_name); let mut replaced_path = None; { let mut companions = self.companions(); - let serial = *companions.names.get(&(from, name.to_vec()))?; + let serial = companions.resolve(&(from, name.to_vec()), from_main)?; 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 let Some(replaced) = companions.resolve(&target, to_main) { 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(); + companions.unindex(serial, &file); + file.named = target; + file.inode = to_main; file.used = tick; - companions.names.insert(target, serial); + // A client may write a companion under another name first, and a + // name it moves onto may belong to another main inode, or to + // none: the body is classified again under the destination, so + // one whose main file is unknown takes its slot and none keeps a + // whole image's exemption. + companions.classify(&mut file); + companions.index(serial, &file); companions.attach(serial, file); } unlink_paths(replaced_path); @@ -470,9 +712,10 @@ impl Kernel { let holding = held.holding(); if holding.held > 0 { eprintln!( - "layerfs-nfs: AppleDouble companions released: export={:?} held={} decoded={} decoded_bytes={} resident_bytes={}", + "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} decoded_bytes={} resident_bytes={}", self.mount(), holding.held, + holding.slotted, holding.decoded, holding.decoded_bytes, holding.resident_bytes diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 555ffb1120..a3ba16b691 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -249,13 +249,14 @@ impl Kernel { Ok(Room::Resident(stat)) } /// Records an edit applied to `serial`'s spilled file and answers its - /// stat. + /// stat. A body changed on disk is no longer known to be a whole image. 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; + file.whole = false; touch(&mut file.metadata); let stat = Companions::stat(serial, &file); companions.attach(serial, file); diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 7932d219b5..11f74ef414 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -463,7 +463,8 @@ impl Kernel { /// export held for the inode it detached. Only the inode the publishing /// job itself retired skips the release jobs. fn finish_unlink(&self, parent: u64, name: &[u8], retire: Retire, detached: Option) { - self.table().by_name.remove(&(parent, name.to_vec())); + self.companion_drop_for(parent, name); + self.table().unbind_any(&(parent, name.to_vec())); let Some(target) = detached else { return; }; @@ -572,6 +573,11 @@ impl Kernel { self.mutate(from, None, None, Expect::Nothing, tickets, |_| { Ok(MutationInput::Named(remove::unlink(from, source_name))) })?; + self.companion_drop_for(from, name); + if source.namespace_refs <= 1 { + // The last name of the inode went with the silly rename. + self.companion_drop_inode(source.serial); + } self.silly_renamed.fetch_add(1, Ordering::Relaxed); let replaced = { let mut table = self.table(); @@ -627,7 +633,7 @@ impl Kernel { if directory { self.saw_directory(serial, to); } - self.renamed(serial, to, new_name); + self.renamed(serial, from, name, to, new_name); } /// LINK: one more name for `serial`. pub fn link( diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 43e17fda5c..a2e297e7fa 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -109,8 +109,15 @@ pub(crate) struct Table { /// Serial -> the name it was last reached by, kept after its reference /// is collected so a later handle can be resolved again. pub names: HashMap, - /// (directory, name) -> serial last seen under that name. + /// Every observed (directory, name) -> serial, including hard-link aliases. + /// A second name does not retire the first; unlink/rename remove known + /// vanished names, and retiring a serial removes all its keys. pub by_name: HashMap, + /// Serial -> the names it is reached by besides [`Table::names`]: the + /// hard-link aliases it was also observed under. Every key of + /// [`Table::by_name`] is one of the two, so dropping one record removes + /// exactly its own keys instead of scanning the whole index. + pub aliases: HashMap>, /// Serial -> last use, for the collection order. pub used: HashMap, /// Serials marked for a cache refresh, and when (see [`crate::refresh`]). @@ -131,6 +138,55 @@ impl Table { pub fn pinned(&self, serial: u64) -> bool { self.silly.values().any(|held| *held == serial) } + /// Records that `serial` is reached as `named`. + pub(crate) fn bind_name(&mut self, named: Named, serial: u64) { + self.by_name.insert(named, serial); + } + /// Remembers that `serial` is also reached as `named`, a name beyond its + /// remembered one, so dropping the serial needs no scan of `by_name`. + pub(crate) fn remember_alias(&mut self, serial: u64, named: &Named) { + let aliases = self.aliases.entry(serial).or_default(); + if !aliases.iter().any(|alias| alias == named) { + aliases.push(named.clone()); + } + } + /// Drops `named`, which `serial` no longer holds. Returns whether it did. + pub(crate) fn unbind_name(&mut self, named: &Named, serial: u64) -> bool { + if self.by_name.get(named) != Some(&serial) { + return false; + } + self.by_name.remove(named); + self.drop_alias(serial, named); + true + } + /// Drops `named` whatever serial holds it, and its alias record. + pub(crate) fn unbind_any(&mut self, named: &Named) -> Option { + let serial = self.by_name.remove(named)?; + self.drop_alias(serial, named); + Some(serial) + } + fn drop_alias(&mut self, serial: u64, named: &Named) { + let Some(aliases) = self.aliases.get_mut(&serial) else { + return; + }; + aliases.retain(|alias| alias != named); + if aliases.is_empty() { + self.aliases.remove(&serial); + } + } + /// Drops every key `serial` holds: its remembered name and its aliases. + pub(crate) fn unbind_serial(&mut self, serial: u64) { + if let Some(named) = self.names.remove(&serial) { + if self.by_name.get(&named) == Some(&serial) { + self.by_name.remove(&named); + } + } + for named in self.aliases.remove(&serial).unwrap_or_default() { + if self.by_name.get(&named) == Some(&serial) { + self.by_name.remove(&named); + } + } + } } /// One opened file as READ and WRITE need it. #[derive(Clone, Copy)] @@ -301,16 +357,12 @@ impl Kernel { Err(status) => return Err(status), } let mut table = self.table(); - if table + let remembered = table .names .get(&serial) - .is_some_and(|(p, n)| *p == parent && *n == name) - { - if let Some(old) = table.names.remove(&serial) { - if table.by_name.get(&old) == Some(&serial) { - table.by_name.remove(&old); - } - } + .is_some_and(|(p, n)| *p == parent && *n == name); + if remembered { + table.unbind_serial(serial); } self.unresolved.fetch_add(1, Ordering::Relaxed); Err(Status::Stale) @@ -427,11 +479,28 @@ impl Kernel { if table.names.len() < NAMES_HELD || table.names.contains_key(&stat.serial) { let named = (parent, name.to_vec()); if let Some(old) = table.names.insert(stat.serial, named.clone()) { - if table.by_name.get(&old) == Some(&stat.serial) { - table.by_name.remove(&old); + if old != named { + if stat.namespace_refs <= 1 { + // The inode has one name: every other name the + // index held for it is one it no longer has. + // (Its old keys stay a moment in a state whose + // nlink the engine last reported higher.) + table.unbind_name(&old, stat.serial); + for alias in table.aliases.remove(&stat.serial).unwrap_or_default() + { + if table.by_name.get(&alias) == Some(&stat.serial) { + table.by_name.remove(&alias); + } + } + } else { + // A hard link: the old name still reaches the + // inode, so it stays, remembered per serial so + // that retiring the serial drops no other name. + table.remember_alias(stat.serial, &old); + } } } - table.by_name.insert(named, stat.serial); + table.bind_name(named, stat.serial); } } let extra = root || !table.lookups.insert(stat.serial); @@ -452,16 +521,26 @@ impl Kernel { } self.observed(stat); } - /// Records that `serial` is now reached as `name` in `parent` (RENAME). - pub(crate) fn renamed(&self, serial: u64, parent: u64, name: &[u8]) { + /// Records that `serial` is now reached as `new_name` in `to` rather than as + /// `name` in `from` (RENAME). Only the name that moved leaves the index: + /// other names of the inode, its hard links, stay reachable as they were. + pub(crate) fn renamed(&self, serial: u64, from: u64, name: &[u8], to: u64, new_name: &[u8]) { let mut table = self.table(); - let named = (parent, name.to_vec()); - if let Some(slot) = table.names.get_mut(&serial) { - let old = std::mem::replace(slot, named.clone()); - if table.by_name.get(&old) == Some(&serial) { - table.by_name.remove(&old); + let named = (to, new_name.to_vec()); + let moved = (from, name.to_vec()); + table.unbind_name(&moved, serial); + let previous = table + .names + .get_mut(&serial) + .map(|slot| std::mem::replace(slot, named.clone())); + if let Some(previous) = previous { + // The name the inode was last recalled by did not move and is still + // one of its names: overwriting the remembered name keeps it only + // as an alias, which is what retiring the serial reads. + if previous != moved && previous != named { + table.remember_alias(serial, &previous); } - table.by_name.insert(named, serial); + table.bind_name(named, serial); } } pub(crate) fn forget(&self, serial: u64, count: u64) { @@ -489,11 +568,7 @@ impl Kernel { let mut table = self.table(); table.parents.remove(&serial); table.directory_stats.remove(&serial); - if let Some(old) = table.names.remove(&serial) { - if table.by_name.get(&old) == Some(&serial) { - table.by_name.remove(&old); - } - } + table.unbind_serial(serial); table.used.remove(&serial); table.verifiers.retain(|_, entry| entry.1 != serial); let directories: Vec = table @@ -524,6 +599,8 @@ impl Kernel { if held && !retired_in_job { self.forget(serial, 1); } + // An inode's last name is gone: so is its AppleDouble companion. + self.companion_drop_inode(serial); } /// Records the parent of a directory seen in a listing or moved by RENAME. pub fn saw_directory(&self, serial: u64, parent: u64) { diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index 3c37d964de..73a6321ee9 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -3,7 +3,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, Table}; -use std::sync::atomic::Ordering; +use std::sync::atomic::{AtomicU64, Ordering}; impl Kernel { /// Gives back everything the synthetic kernel holds: descriptors first, @@ -24,26 +24,25 @@ impl Kernel { } 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(); 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 { + let count = |counter: &AtomicU64| counter.load(Ordering::Relaxed); Released { companions: companions.held, companion_bytes: companions.resident_bytes, + companions_slotted: companions.slotted, companions_decoded: companions.decoded, companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), @@ -51,12 +50,12 @@ impl Kernel { 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), + silly_renamed: count(&self.silly_renamed), + names_refused: count(&self.names_refused), + names_detached: count(&self.names_detached), + collected: count(&self.collected), + resolved: count(&self.resolved), + unresolved: count(&self.unresolved), } } } @@ -76,10 +75,13 @@ pub struct Released { /// Creations refused for their AppleDouble name, over the export's life. pub names_refused: u64, /// AppleDouble companions held in the export's index (see - /// [`crate::apple_double`]). + /// [`crate::apple_double`]), whole images included. pub companions: usize, /// Companion payload bytes currently resident in memory. pub companion_bytes: usize, + /// Of the companions held, those taking a slot of the index bound: all but + /// the ones holding a whole image. + pub companions_slotted: 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/server.rs b/engine/crates/layerfs-nfs/src/server.rs index 3a3e2b6d65..8db26faf1f 100644 --- a/engine/crates/layerfs-nfs/src/server.rs +++ b/engine/crates/layerfs-nfs/src/server.rs @@ -51,6 +51,9 @@ pub struct ExportConfig { /// to [`Self::companion_spill_dir`]; [`crate::apple_double::RESIDENT_BYTES`] /// by default. pub companion_resident_bytes: usize, + /// Maximum AppleDouble companion index entries held at once; + /// [`crate::apple_double::HELD`] by default. + pub companions_held: usize, } impl ExportConfig { /// A writable export of "/" shown as `uid`:`gid`, refusing AppleDouble @@ -65,6 +68,7 @@ impl ExportConfig { lookups_held: crate::kernel::LOOKUPS_HELD, companion_spill_dir: None, companion_resident_bytes: crate::apple_double::RESIDENT_BYTES, + companions_held: crate::apple_double::HELD, } } } @@ -153,6 +157,7 @@ impl Server { kernel.configure_companions( config.companion_spill_dir.clone(), config.companion_resident_bytes, + config.companions_held, ); let shared = Arc::new(Shared { kernel, From 12f37b4c191e5119d3cb46a5479c8fb0ad481189 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:51:48 +0000 Subject: [PATCH 09/34] test(nfs): cover the companion index bound, aliases and reclamation (lp73) The remaining cases of the layer: a whole image takes no slot and is read back from every name of its inode; a resource fork, an unknown main and a companion moved off its inode keep the stored-as-written path and their slot; `HELD` is 65,536 and a small bound reclaims orphans instead of refusing; two GUARDED creates of one name, and two of them over the last free slot, leave one entry; a reclaimed companion never loses a live main file's attributes, including one that gained a hard link; a renamed hard-link alias keeps the inode's recalled name bound; and companions survive a main-file rename, silly rename and replacing rename exactly as the client expects. `apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up` is the long one: 4,160 companions past the old 4,096 count and a 64 KiB resident budget, every write read back byte for byte, the spill directory's modes, the unlinks a main-file removal or replacing RENAME performs, the `FILE_BYTES` refusal, and the `HELD` bound with orphan reclamation before `NFS3ERR_NOSPC`. The rig can set `companions_held` too. Production LOC: 164574 -> 164574 (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 dc2c54c0f (164574) and this tree (164574). Tests only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/tests/apple_double_decode.rs | 559 +++++++++++++++++- .../crates/layerfs-nfs/tests/support/rig.rs | 5 + engine/crates/layerfs-nfs/tests/write.rs | 464 ++++++++++++++- 3 files changed, 1021 insertions(+), 7 deletions(-) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 28f95320ba..7156b53da3 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1,8 +1,9 @@ -//! 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. +//! AppleDouble companions decoded into their main inode's own record: a +//! `._` the client writes is served byte for byte, takes no slot of the +//! index bound, is shared by every name of the inode, follows the inode +//! through RENAME and goes with its last name. A body that is not a whole +//! image (a resource fork, another layout, a half-written one) is stored as +//! the client wrote it, which is the #636 fallback. #[allow(dead_code)] #[path = "support/client.rs"] mod client; @@ -15,7 +16,7 @@ mod spy; #[allow(dead_code)] #[path = "support/tree.rs"] mod tree; -use client::{Client, Set, STALE}; +use client::{Client, Set, NOENT, STALE}; use layerfs_nfs::apple_double_codec::{Attribute, Image}; use std::{ fs, @@ -24,6 +25,7 @@ use std::{ time::Duration, }; +const NOSPC: u32 = 28; const UID: u32 = 501; const GID: u32 = 20; @@ -51,6 +53,85 @@ fn image(finder: [u8; 32], attrs: &[(&[u8], Vec)]) -> Vec { .encode() } +#[test] +fn a_whole_image_is_read_back_as_written_from_every_name_of_the_inode() { + let base = temp("decode"); + 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("/"); + + // What `cp` does: the data file, then its companion with the attributes. + let main = c.touch(&root, b"f", 0o644).unwrap(); + c.write(&main.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._f", 0o644).unwrap(); + let finder = [0x11; 32]; + let first = image( + finder, + &[ + (b"com.apple.provenance", pattern(1, 40)), + (b"com.apple.quarantine", pattern(2, 150)), + (b"com.apple.FinderInfo", finder.to_vec()), + (b"user.custom", pattern(3, 4096)), + ], + ); + c.write(&ad.handle, 0, &first).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, first.len() as u64); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), first); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (1, 1, 0), + "a whole image is decoded and takes no slot" + ); + assert!(held.companion_decoded_bytes >= 4096); + + // A second name of the same inode reads the same companion. + c.link(&main.handle, &root, b"g").unwrap(); + let (alias, attr) = c.lookup(&root, b"._g").unwrap(); + assert_eq!(alias, ad.handle, "hard links share one companion"); + assert_eq!(attr.size, first.len() as u64); + assert_eq!(c.read_all(&alias, 64 * 1024), first); + + // A write under the alias changes the inode's attributes for every name. + let second = image( + [0x22; 32], + &[ + (b"com.apple.provenance", pattern(4, 40)), + (b"user.custom", pattern(5, 100 * 1024)), + ], + ); + c.write(&alias, 0, &second).unwrap(); + assert_eq!(c.read_all(&ad.handle, 256 * 1024), second); + + // RENAME of the main file carries the companion to the new name. + c.rename(&root, b"f", &root, b"h").unwrap(); + let (renamed, _) = c.lookup(&root, b"._h").unwrap(); + assert_eq!(renamed, ad.handle); + assert_eq!(c.read_all(&renamed, 256 * 1024), second); + + // The companion goes with the inode's last name, not with one name. + c.remove(&root, b"h").unwrap(); + assert_eq!(server.held().companions, 1, "g still names the inode"); + assert_eq!(c.read_all(&alias, 256 * 1024), second); + c.remove(&root, b"g").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&alias), Err(STALE)); + assert_eq!(c.lookup(&root, b"._h").map(|_| ()), Err(NOENT)); + + 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"); @@ -140,6 +221,209 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_resource_fork_keeps_the_stored_as_written_fallback() { + let base = temp("fork"); + 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("/"); + + // A file with a resource fork: the fork's entry carries 286 bytes of the + // client's own, which the decoded form does not keep. + c.touch(&root, b"rf", 0o644).unwrap(); + let ad = c.touch(&root, b"._rf", 0o644).unwrap(); + let plain = image([0x55; 32], &[(b"com.apple.provenance", pattern(10, 40))]); + let mut forked = plain.clone(); + let fork = pattern(11, 286); + forked[plain.len() - 286..].copy_from_slice(&fork); + c.write(&ad.handle, 0, &forked).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), forked); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (1, 0, 1), + "a resource fork takes the stored-as-written path and its slot" + ); + // A companion whose main file the export never saw keeps that path too. + let _unknown = c.touch(&root, b"._no-main", 0o644).unwrap(); + let unknown = c.lookup(&root, b"._no-main").unwrap().0; + c.write(&unknown, 0, b"not an image").unwrap(); + assert_eq!(server.held().companions_slotted, 2); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions_decoded, 0); + assert_eq!(released.companions_slotted, 2); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn whole_images_take_no_slot_of_the_index_bound() { + let base = temp("slots"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // Two slots, and a body budget small enough that raw bodies spill. + rig.companions_held = 2; + 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("/"); + + // More whole images than slots: every one is accepted. + let mut images = Vec::new(); + for i in 0..5 { + let main = format!("live-{i}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let ad = c + .touch(&root, format!("._{main}").as_bytes(), 0o644) + .unwrap(); + let bytes = image( + [0; 32], + &[(b"user.value", format!("value-{i}").into_bytes())], + ); + c.write(&ad.handle, 0, &bytes).unwrap(); + images.push((ad.handle, bytes)); + } + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (5, 5, 0) + ); + assert_eq!(held.names_refused, 0); + + // Bodies that are not whole images do take slots: the bound still answers + // NOSPC once they fill it, and its rate-limited log is the same. + for i in 0..2 { + let main = format!("raw-{i}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let ad = c + .touch(&root, format!("._{main}").as_bytes(), 0o644) + .unwrap(); + c.write(&ad.handle, 0, b"stored as written").unwrap(); + } + assert_eq!(server.held().companions_slotted, 2); + c.touch(&root, b"raw-extra", 0o644).unwrap(); + assert_eq!( + c.touch(&root, b"._raw-extra", 0o644).map(|_| ()), + Err(NOSPC) + ); + assert_eq!(server.held().names_refused, 1); + // Removing a raw companion's main file frees its slot, and a new whole + // image is then accepted again without taking one. + c.remove(&root, b"raw-0").unwrap(); + assert_eq!(server.held().companions_slotted, 1); + c.touch(&root, b"new-image", 0o644).unwrap(); + let ad = c.touch(&root, b"._new-image", 0o644).unwrap(); + let fresh = image([1; 32], &[(b"user.fresh", pattern(20, 64))]); + c.write(&ad.handle, 0, &fresh).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + assert_eq!(server.held().names_refused, 1); + assert_eq!(c.read_all(&ad.handle, 4096), fresh); + // The refused raw companion now fits. + c.touch(&root, b"._raw-extra", 0o644).unwrap(); + assert_eq!(server.held().companions_slotted, 2); + // Every whole image still reads back byte for byte. + for (handle, bytes) in &images { + assert_eq!(&c.read_all(handle, 64 * 1024), bytes); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_decoded_companion_is_gone_once_its_inode_is_silly_renamed() { + let base = temp("silly"); + 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"open", 0o644).unwrap(); + c.write(&main.handle, 0, b"still open").unwrap(); + let ad = c.touch(&root, b"._open", 0o644).unwrap(); + let bytes = image([2; 32], &[(b"user.a", pattern(12, 32))]); + c.write(&ad.handle, 0, &bytes).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + // A client that unlinks a file it keeps open renames it to a silly name. + let silly: &[u8] = b".nfs.20051025.b896"; + c.rename(&root, b"open", &root, silly).unwrap(); + assert_eq!(server.held().companions, 0, "the last name went"); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + c.remove(&root, silly).unwrap(); + assert_eq!(c.lookup(&root, silly).map(|_| ()), Err(NOENT)); + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_replaced_main_file_takes_its_companion_with_it() { + let base = temp("replace"); + 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("/"); + c.touch(&root, b"dst", 0o644).unwrap(); + c.touch(&root, b"src", 0o644).unwrap(); + let dst = c.touch(&root, b"._dst", 0o644).unwrap(); + c.write( + &dst.handle, + 0, + &image([3; 32], &[(b"user.dst", pattern(13, 16))]), + ) + .unwrap(); + let src = c.touch(&root, b"._src", 0o644).unwrap(); + c.write( + &src.handle, + 0, + &image([4; 32], &[(b"user.src", pattern(14, 16))]), + ) + .unwrap(); + assert_eq!(server.held().companions_decoded, 2); + // RENAME over the destination detaches it as an unlink would. + c.rename(&root, b"src", &root, b"dst").unwrap(); + assert_eq!(c.getattr(&dst.handle), Err(STALE)); + assert_eq!(server.held().companions_decoded, 1, "only src's is left"); + // The client moves the source's companion to the destination's name. + c.rename(&root, b"._src", &root, b"._dst").unwrap(); + let (moved, _) = c.lookup(&root, b"._dst").unwrap(); + assert_eq!(moved, src.handle); + assert_eq!( + c.read_all(&moved, 4096), + image([4; 32], &[(b"user.src", pattern(14, 16))]) + ); + c.remove(&root, b"dst").unwrap(); + assert_eq!(server.held().companions, 0); + drop(c); + let released = server.stop(); + 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"); @@ -214,3 +498,266 @@ fn a_decoded_companion_is_edited_under_a_full_resident_budget() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_without_a_main_file_takes_a_slot_and_is_reclaimed() { + let base = temp("no-main"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 3; + // Too small for the image written below, so that write needs the spill path. + 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("/"); + + // A whole image under a name whose main file the export does not know is + // not decoded: it keeps the client's bytes and a slot of the index bound, + // both when it fits the resident budget and when it does not. + let small = image([0x88; 32], &[(b"user.small", pattern(32, 16))]); + c.touch(&root, b"._small", 0o644).unwrap(); + let fits = c.lookup(&root, b"._small").unwrap().0; + c.write(&fits, 0, &small).unwrap(); + assert_eq!(c.read_all(&fits, 4096), small); + let big = image([0x89; 32], &[(b"user.big", pattern(33, 4096))]); + c.touch(&root, b"._no-main", 0o644).unwrap(); + let spilled = c.lookup(&root, b"._no-main").unwrap().0; + c.write(&spilled, 0, &big).unwrap(); + assert_eq!(c.read_all(&spilled, 64 * 1024), big); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (2, 0, 2), + "a companion with no main file is stored as written and takes its slot" + ); + + // A decoded companion renamed onto a name whose main file is unknown is no + // longer an inode's: it keeps the bytes as written and takes its slot too. + let main = c.touch(&root, b"owned", 0o644).unwrap(); + c.write(&main.handle, 0, b"owned by an inode").unwrap(); + let owned = c.touch(&root, b"._owned", 0o644).unwrap(); + c.write(&owned.handle, 0, &small).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + c.rename(&root, b"._owned", &root, b"._gone").unwrap(); + assert_eq!(c.read_all(&owned.handle, 4096), small); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (3, 0, 3), + "a companion with no main file is never a whole image" + ); + + // The bound reclaims them as orphans instead of refusing the next CREATE. + c.touch(&root, b"next", 0o644).unwrap(); + c.touch(&root, b"._next", 0o644).unwrap(); + let held = server.held(); + assert_eq!( + (held.companions, held.companions_slotted, held.names_refused), + (1, 1, 0), + "the three companions with no main file were reclaimed" + ); + assert_eq!(c.getattr(&spilled), Err(STALE)); + assert_eq!(c.getattr(&owned.handle), Err(STALE)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_spilled_body_renamed_off_its_inode_takes_its_slot() { + let base = temp("spilled-rename"); + 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-rename")); + rig.companion_resident_bytes = 512 * 1024; + rig.companions_held = 4; + 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 with an attribute larger than the decoded-entry bound is + // kept as written, takes no slot, and fits the resident budget. + c.touch(&root, b"m", 0o644).unwrap(); + let ad = c.touch(&root, b"._m", 0o644).unwrap(); + let whole = image( + [0x5a; 32], + &[ + (b"com.apple.provenance", pattern(40, 40)), + (b"user.bulk", pattern(41, 200 * 1024)), + ], + ); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!( + ( + server.held().companions_decoded, + server.held().companions_slotted + ), + (0, 0), + "a whole image takes no slot even when it is kept as written" + ); + + // Another companion's larger body evicts it to disk, still whole. + c.touch(&root, b"other", 0o644).unwrap(); + let other = c.touch(&root, b"._other", 0o644).unwrap(); + let stored = pattern(42, 400 * 1024); + c.write(&other.handle, 0, &stored).unwrap(); + assert_eq!(server.held().companion_bytes, stored.len()); + assert_eq!( + server.held().companions_slotted, + 1, + "only ._other takes a slot" + ); + + // RENAME onto a name whose main file the export never saw: the body stops + // being an inode's companion, so it may not keep a whole image's + // exemption from the index bound, even on disk. + c.rename(&root, b"._m", &root, b"._gone").unwrap(); + let held = server.held(); + assert_eq!( + (held.companions_decoded, held.companions_slotted), + (0, 2), + "a spilled body renamed off its inode takes its slot" + ); + assert_eq!(c.read_all(&ad.handle, 256 * 1024), whole); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn whole_images_take_no_slot_and_the_bound_reclaims_only_slots() { + let base = temp("whole-images-bound"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 2; + 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("/"); + + // Two companions that decode into whole images: neither takes a slot, so a + // full table may hold any number of them. + let mut whole = Vec::new(); + for (main, seed) in [(b"a".as_slice(), 1u32), (b"b".as_slice(), 2u32)] { + let data = c.touch(&root, main, 0o644).unwrap(); + c.write(&data.handle, 0, b"data").unwrap(); + let mut name = b"._".to_vec(); + name.extend_from_slice(main); + let ad = c.touch(&root, &name, 0o644).unwrap(); + let bytes = image([seed as u8; 32], &[(b"user.small", pattern(seed, 16))]); + c.write(&ad.handle, 0, &bytes).unwrap(); + whole.push((ad.handle, bytes)); + } + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (2, 2, 0), + "whole images take no slot" + ); + + // Both slots go to companions whose main file the export knows, so there is + // no orphan to reclaim: the bound refuses instead of touching a whole image. + for index in 0..2 { + let main = format!("live-{index}"); + let companion = format!("._live-{index}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, companion.as_bytes(), 0o644).unwrap(); + c.write(&ad.handle, 0, &[b'L'; 64]).unwrap(); + } + c.touch(&root, b"next", 0o644).unwrap(); + assert_eq!(c.touch(&root, b"._next", 0o644).map(|_| ()), Err(NOSPC)); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted, + held.names_refused + ), + (4, 2, 2, 1), + "the refusal kept both whole images and both slots" + ); + for (handle, bytes) in &whole { + assert_eq!(c.read_all(handle, 4096), *bytes); + } + + // Freeing a slot, not a whole image, lets the next companion in. + c.remove(&root, b"._live-0").unwrap(); + c.touch(&root, b"._next", 0o644).unwrap(); + assert_eq!(server.held().companions_slotted, 2); + assert_eq!(server.held().companions, 4); + assert_eq!(server.held().companions_decoded, 2); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_rename_keeps_the_other_names_of_the_inode_companion() { + let base = temp("aliases"); + 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"a", 0o644).unwrap(); + c.write(&main.handle, 0, b"two names, one inode").unwrap(); + let ad = c.touch(&root, b"._a", 0o644).unwrap(); + let bytes = image([0x99; 32], &[(b"user.link", pattern(34, 64))]); + c.write(&ad.handle, 0, &bytes).unwrap(); + c.link(&main.handle, &root, b"b").unwrap(); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad.handle); + + // RENAME moves one name of the inode: every other name still reaches the + // companion, before and after the moved name goes. + c.rename(&root, b"a", &root, b"c").unwrap(); + assert_eq!( + c.lookup(&root, b"._b").unwrap().0, + ad.handle, + "b still names the inode" + ); + assert_eq!(c.lookup(&root, b"._c").unwrap().0, ad.handle); + assert_eq!(c.read_all(&ad.handle, 4096), bytes); + c.remove(&root, b"c").unwrap(); + assert_eq!( + c.lookup(&root, b"._b").unwrap().0, + ad.handle, + "b is the inode's last name" + ); + assert_eq!(c.read_all(&ad.handle, 4096), bytes); + + // The companion goes with the inode's last name. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + + 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/support/rig.rs b/engine/crates/layerfs-nfs/tests/support/rig.rs index 612b9a2a2f..a5a8cbc801 100644 --- a/engine/crates/layerfs-nfs/tests/support/rig.rs +++ b/engine/crates/layerfs-nfs/tests/support/rig.rs @@ -42,6 +42,8 @@ pub struct Rig { pub lookups_held: usize, /// Resident memory budget for AppleDouble companion bodies. pub companion_resident_bytes: usize, + /// Maximum AppleDouble companion index entries held at once. + pub companions_held: usize, /// Optional explicit spill directory override for AppleDouble companions. pub companion_spill_dir: Option, } @@ -147,6 +149,7 @@ impl Rig { entries: initialized.entries, lookups_held: layerfs_nfs::kernel::LOOKUPS_HELD, companion_resident_bytes: layerfs_nfs::apple_double::RESIDENT_BYTES, + companions_held: layerfs_nfs::apple_double::HELD, companion_spill_dir: None, } } @@ -192,6 +195,7 @@ impl Rig { lookups_held: self.lookups_held, companion_spill_dir: Some(self.spill_dir("export")), companion_resident_bytes: self.companion_resident_bytes, + companions_held: self.companions_held, }, ) .unwrap() @@ -262,6 +266,7 @@ impl Rig { 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, + companions_held: self.companions_held, }, ) .unwrap() diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index 0a5a9e596e..25b0351d87 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -33,6 +33,7 @@ use std::{ const UID: u32 = 501; const GID: u32 = 20; const FILE_SYNC: u32 = 2; +const NOSPC: u32 = 28; const LINUX_SILLY: &[u8] = b".nfs00000000000012ab00000001"; const MAC_SILLY: &[u8] = b".nfs.20051025.b896"; @@ -56,7 +57,6 @@ fn pattern(seed: u32, length: usize) -> Vec { .map(|n| (n as u32).wrapping_mul(31).wrapping_add(seed * 97) as u8) .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()) @@ -540,6 +540,467 @@ fn apple_double_files_stay_out_of_the_workspace() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up() { + use layerfs_nfs::apple_double::{FILE_BYTES, HELD}; + let base = temp("appledouble-spill"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + + // 1. Pre-populate a leftover file in the spill directory (simulating a + // crashed daemon) and configure a small resident budget (64 KiB) so + // spilling is exercised across both the old 4096 companion count and + // the memory budget. + let spill_dir = base.join("spill-export"); + fs::create_dir_all(&spill_dir).unwrap(); + let stale_residue = spill_dir.join("stale-from-crash"); + fs::write(&stale_residue, b"leftover").unwrap(); + assert!(stale_residue.exists()); + + let budget = 64 * 1024; + rig.companion_spill_dir = Some(spill_dir.clone()); + rig.companion_resident_bytes = budget; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + assert!( + !stale_residue.exists(), + "starting an export cleans any leftover spill directory from an earlier crash" + ); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // 2. Removing a main file, silly-renaming it, or replacing it with RENAME + // drops its paired `._` companion and deletes its spilled disk + // file at once. Plain non-replacing RENAME (`mv plain_a plain_b`) + // cleans only the destination side so the client can subsequently + // rename `._plain_a -> ._plain_b`. + let big_payload = pattern(11, 40 * 1024); + c.touch(&root, b"rm.txt", 0o644).unwrap(); + let rm_ad = c.touch(&root, b"._rm.txt", 0o644).unwrap(); + c.write(&rm_ad.handle, 0, &big_payload).unwrap(); + c.touch(&root, b"silly.txt", 0o644).unwrap(); + let silly_ad = c.touch(&root, b"._silly.txt", 0o644).unwrap(); + c.write(&silly_ad.handle, 0, &big_payload).unwrap(); + // Second 40 KiB write crosses the 64 KiB budget, spilling `._rm.txt`. + let rm_spill_file = spill_dir.join(rm_ad.attr.fileid.to_string()); + assert!( + rm_spill_file.is_file(), + "oldest companion body spilled to disk" + ); + assert!(server.held().companion_bytes <= budget); + assert_eq!(spilled(&spill_dir), (1, big_payload.len() as u64)); + // The scratch directory and its files are this user's alone, whatever the + // process umask is. + for (path, mode) in [(&spill_dir, 0o700), (&rm_spill_file, 0o600)] { + assert_eq!( + fs::metadata(path).unwrap().permissions().mode() & 0o777, + mode, + "{}", + path.display() + ); + } + + c.remove(&root, b"rm.txt").unwrap(); + assert!( + !rm_spill_file.exists(), + "removing the main file unlinks its spilled companion file" + ); + assert_eq!(c.lookup(&root, b"._rm.txt").map(|_| ()), Err(NOENT)); + assert_eq!(c.getattr(&rm_ad.handle), Err(STALE)); + + c.rename(&root, b"silly.txt", &root, MAC_SILLY).unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&silly_ad.handle), Err(STALE)); + c.remove(&root, MAC_SILLY).unwrap(); + + c.touch(&root, b"src.txt", 0o644).unwrap(); + c.touch(&root, b"dst.txt", 0o644).unwrap(); + let dst_ad = c.touch(&root, b"._dst.txt", 0o644).unwrap(); + c.write(&dst_ad.handle, 0, &big_payload).unwrap(); + let src_ad = c.touch(&root, b"._src.txt", 0o644).unwrap(); + c.write(&src_ad.handle, 0, &big_payload).unwrap(); + let dst_spill_file = spill_dir.join(dst_ad.attr.fileid.to_string()); + assert!(dst_spill_file.is_file()); + c.rename(&root, b"src.txt", &root, b"dst.txt").unwrap(); + assert!( + !dst_spill_file.exists(), + "replacing RENAME unlinks the destination's spilled companion" + ); + assert_eq!(c.getattr(&dst_ad.handle), Err(STALE)); + // Source companion `._src.txt` is still present so the client can rename + // it to `._dst.txt`, then remove `dst.txt`. + c.rename(&root, b"._src.txt", &root, b"._dst.txt").unwrap(); + assert_eq!(c.read_all(&src_ad.handle, 64 * 1024), big_payload); + c.remove(&root, b"dst.txt").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(server.held().companion_bytes, 0); + + // 3. Create and write > 4096 companions (4160), crossing both the old + // 4096 cap and the 64 KiB resident memory budget: every CREATE, WRITE + // and READ succeeds, resident bytes never exceed `budget`, spilled + // files exist on disk, and the earliest companions read back byte for + // byte (0 data loss). + const TOTAL_COUNT: usize = 4160; + let mut handles = Vec::with_capacity(TOTAL_COUNT); + for i in 0..TOTAL_COUNT { + let name = format!("._c-{i}"); + let made = c.touch(&root, name.as_bytes(), 0o644).unwrap(); + let payload = if i < 32 || i % 128 == 0 { + format!("companion-payload-{i:04}-{}", "x".repeat(2048)).into_bytes() + } else { + format!("short-{i:04}").into_bytes() + }; + c.write(&made.handle, 0, &payload).unwrap(); + assert!( + server.held().companion_bytes <= budget, + "resident bytes {} exceeded budget {budget} at {i}", + server.held().companion_bytes + ); + handles.push((made.handle, made.attr.fileid, payload)); + } + assert_eq!(server.held().companions, TOTAL_COUNT); + assert_eq!(server.held().names_refused, 0); + assert!( + spilled(&spill_dir).0 > 0, + "companions beyond the resident budget are on disk" + ); + assert!(spill_dir.join(handles[0].1.to_string()).is_file()); + + // Earliest, middle and latest companions all read back byte-for-byte. + for idx in [ + 0, + 1, + 2, + 15, + 31, + 128, + 1024, + 2048, + 4095, + 4096, + TOTAL_COUNT - 1, + ] { + let (ref handle, _, ref expected) = handles[idx]; + let name = format!("._c-{idx}"); + let (looked, attr) = c.lookup(&root, name.as_bytes()).unwrap(); + assert_eq!(&looked, handle); + assert_eq!(attr.size, expected.len() as u64); + assert_eq!( + c.read_all(handle, 64 * 1024), + *expected, + "companion {idx} content mismatch" + ); + } + + // Overwriting and truncating an already-spilled companion works via + // pread/pwrite/set_len and removes its disk file on explicit REMOVE. + let (ref h0, id0, _) = handles[0]; + c.write(h0, 0, b"updated-header").unwrap(); + let shrink = Set { + size: Some(14), + ..Set::default() + }; + c.setattr(h0, shrink, None).unwrap(); + assert_eq!(c.read_all(h0, 64), b"updated-header"); + c.remove(&root, b"._c-0").unwrap(); + assert!(!spill_dir.join(id0.to_string()).exists()); + + // Single-file limit `FILE_BYTES` (1 MiB) is still enforced (`NFS3ERR_FBIG`). + const FBIG: u32 = 27; + let (ref h_last, _, _) = handles[TOTAL_COUNT - 1]; + assert_eq!(c.write(h_last, FILE_BYTES, b"!").map(|_| ()), Err(FBIG)); + + // 4. Stopping the export removes the entire spill directory. + drop(c); + let released = server.stop(); + assert_eq!(released.companions, TOTAL_COUNT - 1); + assert!(released.companion_bytes <= budget); + assert!( + !spill_dir.exists(), + "export stop removes the spill directory" + ); + + // 5. At the index bound (`companions_held`; default `HELD` = 65_536): + // orphan companions (whose paired main file is not in `Table::by_name`) + // are reclaimed first so new creations succeed; when all slots are + // held by live main files, `CREATE` answers `NFS3ERR_NOSPC`. + assert_eq!(HELD, 65_536); + let small_cap = 8; + let cap_spill = base.join("spill-cap"); + rig.companion_spill_dir = Some(cap_spill.clone()); + rig.companions_held = small_cap; + rig.companion_resident_bytes = 1024; + let server2 = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c2 = Client::connect(server2.local_addr(), UID, GID); + let root2 = c2.mnt("/"); + + // Create 4 live pairs (main file + companion) and 4 orphan companions + // (no main file created), filling all 8 index slots and spilling some. + for i in 0..4 { + let main = format!("live-{i}"); + let comp = format!("._live-{i}"); + c2.touch(&root2, main.as_bytes(), 0o644).unwrap(); + let ad = c2.touch(&root2, comp.as_bytes(), 0o644).unwrap(); + c2.write(&ad.handle, 0, &[b'L'; 512]).unwrap(); + } + let mut orphan_handles = Vec::new(); + for i in 0..4 { + let comp = format!("._orphan-{i}"); + let ad = c2.touch(&root2, comp.as_bytes(), 0o644).unwrap(); + c2.write(&ad.handle, 0, &[b'O'; 512]).unwrap(); + orphan_handles.push((ad.handle, ad.attr.fileid)); + } + assert_eq!(server2.held().companions, small_cap); + + // Creating 4 more live pairs at the bound reclaims the 4 orphans (and + // unlinks their spilled files) while preserving the first 4 live pairs. + for i in 4..small_cap { + let main = format!("live-{i}"); + let comp = format!("._live-{i}"); + c2.touch(&root2, main.as_bytes(), 0o644).unwrap(); + let ad = c2.touch(&root2, comp.as_bytes(), 0o644).unwrap(); + c2.write(&ad.handle, 0, &[b'N'; 128]).unwrap(); + } + assert_eq!(server2.held().companions, small_cap); + assert_eq!(server2.held().names_refused, 0); + for (oh, oid) in &orphan_handles { + assert_eq!(c2.getattr(oh), Err(STALE)); + assert!(!cap_spill.join(oid.to_string()).exists()); + } + for i in 0..4 { + let comp = format!("._live-{i}"); + let (lh, _) = c2.lookup(&root2, comp.as_bytes()).unwrap(); + assert_eq!(c2.read_all(&lh, 1024), vec![b'L'; 512]); + } + + // Now all 8 slots belong to live main files: one more companion CREATE + // finds no orphans to reclaim and answers `NFS3ERR_NOSPC`. Repeated + // refusals count individually but log at most once per minute per export. + c2.touch(&root2, b"extra", 0o644).unwrap(); + for _ in 0..3 { + assert_eq!(c2.touch(&root2, b"._extra", 0o644).map(|_| ()), Err(NOSPC)); + } + assert_eq!(server2.held().names_refused, 3); + // Existing names still honor GUARDED / UNCHECKED when the table is full. + assert_eq!( + c2.create(&root2, b"._live-0", How::Guarded(Set::default())) + .map(|_| ()), + Err(EXIST) + ); + c2.touch(&root2, b"._live-0", 0o644).unwrap(); + c2.remove(&root2, b"live-7").unwrap(); + c2.touch(&root2, b"._extra", 0o644).unwrap(); + assert_eq!(server2.held().names_refused, 3); + + drop(c2); + let released2 = server2.stop(); + assert!(!cap_spill.exists()); + let (_, outstanding) = rig.stop(released2); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn two_guarded_creates_of_one_companion_name_leave_one_entry() { + let base = temp("appledouble-create-race"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 8; + 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("/"); + c.touch(&root, b"dup", 0o644).unwrap(); + + // Two actual connections start each CREATE together. Repeat the schedule + // with an empty companion table, so every round exercises first insertion. + for _ in 0..4096 { + let start = std::sync::Barrier::new(2); + let (a, b) = std::thread::scope(|scope| { + let a = scope.spawn(|| { + start.wait(); + c.create(&root, b"._dup", How::Guarded(Set::default())) + }); + let b = scope.spawn(|| { + start.wait(); + other.create(&root, b"._dup", How::Guarded(Set::default())) + }); + (a.join().unwrap(), b.join().unwrap()) + }); + let mut statuses = [ + a.as_ref().map(|_| OK).unwrap_or_else(|e| *e), + b.as_ref().map(|_| OK).unwrap_or_else(|e| *e), + ]; + statuses.sort(); + assert_eq!(statuses, [OK, EXIST]); + let made = a.or(b).unwrap(); + assert_eq!(server.held().companions, 1); + c.remove(&root, b"._dup").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&made.handle), Err(STALE)); + } + c.touch(&root, b"._dup", 0o644).unwrap(); + assert_eq!(server.held().names_refused, 0); + drop((c, other)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_guarded_create_reclaims_the_last_slot_for_one_entry_only() { + let base = temp("appledouble-create-race-bound"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 3; + 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("/"); + c.touch(&root, b"dup", 0o644).unwrap(); + // Two slots belong to live main files, which reclamation must keep. + for index in 0..2 { + let main = format!("live-{index}"); + let companion = format!("._live-{index}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let made = c.touch(&root, companion.as_bytes(), 0o644).unwrap(); + c.write(&made.handle, 0, &[b'L'; 64]).unwrap(); + } + assert_eq!(server.held().companions_slotted, 2); + // Every round fills the last slot with a companion whose main file does not + // exist, so both creates below are over the bound and one of them has to + // reclaim that orphan while it holds no companion lock. + for round in 0..256 { + let orphan = format!("._orphan-{round}"); + let made = c.touch(&root, orphan.as_bytes(), 0o644).unwrap(); + c.write(&made.handle, 0, &[b'O'; 64]).unwrap(); + assert_eq!(server.held().companions_slotted, 3, "round {round}"); + let start = std::sync::Barrier::new(2); + let (a, b) = std::thread::scope(|scope| { + let a = scope.spawn(|| { + start.wait(); + c.create(&root, b"._dup", How::Guarded(Set::default())) + }); + let b = scope.spawn(|| { + start.wait(); + other.create(&root, b"._dup", How::Guarded(Set::default())) + }); + (a.join().unwrap(), b.join().unwrap()) + }); + let mut statuses = [ + a.as_ref().map(|_| OK).unwrap_or_else(|status| *status), + b.as_ref().map(|_| OK).unwrap_or_else(|status| *status), + ]; + statuses.sort(); + assert_eq!(statuses, [OK, EXIST], "round {round}"); + // The two live pairs and the one name: the loser inserted no second + // serial for a name that is already taken. + assert_eq!(server.held().companions_slotted, 3, "round {round}"); + assert_eq!(server.held().companions, 3, "round {round}"); + assert_eq!(c.getattr(&made.handle), Err(STALE), "round {round}"); + c.remove(&root, b"._dup").unwrap(); + assert_eq!(server.held().companions_slotted, 2, "round {round}"); + } + assert_eq!(server.held().names_refused, 0); + drop((c, other)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_renamed_hard_link_alias_keeps_the_inodes_recalled_name_bound() { + let base = temp("appledouble-rename-alias"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // Two exports of one mount: the second one moves a name the first one does + // not observe, as another client of the same Workspace would. + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let second = 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 them = Client::connect(second.local_addr(), UID, GID); + let root = c.mnt("/"); + let their_root = them.mnt("/"); + + // One inode, three names: the export recalls it by `p` and holds `q` as an + // alias of it. + let main = c.touch(&root, b"p", 0o644).unwrap(); + c.link(&main.handle, &root, b"q").unwrap(); + assert_eq!(c.lookup(&root, b"p").unwrap().0, main.handle); + // RENAME of `q` to `r` keeps `p` as the recalled name; the next RENAME moves + // `p` itself, which is an alias, so `r` stops being the recalled name and + // is still one of the inode's names. + c.rename(&root, b"q", &root, b"r").unwrap(); + c.rename(&root, b"p", &root, b"s").unwrap(); + + // The other export moves and then removes `r`; this export removes `s`, + // which is the inode's last name: it retires the inode, and `r` must leave + // the name index with it. + them.rename(&their_root, b"r", &their_root, b"t").unwrap(); + them.remove(&their_root, b"t").unwrap(); + c.remove(&root, b"s").unwrap(); + + // A `._r` companion created while `r` is gone belongs to no inode. + c.touch(&root, b"._r", 0o644).unwrap(); + let companion = c.lookup(&root, b"._r").unwrap().0; + let payload = b"a companion of no inode"; + c.write(&companion, 0, payload).unwrap(); + + // A new file takes the name `r`; the companion is still reachable by name. + them.touch(&their_root, b"r", 0o644).unwrap(); + let (fresh, _) = c.lookup(&root, b"r").unwrap(); + assert_ne!(fresh, main.handle); + let (found, _) = c + .lookup(&root, b"._r") + .expect("the companion still belongs to no inode"); + assert_eq!(found, companion); + assert_eq!(c.read_all(&found, 64), payload); + + drop((c, them)); + let released = server.stop(); + second.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_companion_survives_reclaim_after_its_main_file_gains_a_second_name() { + let base = temp("appledouble-hardlink-reclaim"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 2; + 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"anchor", 0o644).unwrap(); + let companion = c.touch(&root, b"._anchor", 0o644).unwrap(); + let payload = b"held-cap-preserve-me"; + c.write(&companion.handle, 0, payload).unwrap(); + c.link(&main.handle, &root, b"anchor-alias").unwrap(); + let orphan = c.touch(&root, b"._orphan", 0o644).unwrap(); + assert_eq!(server.held().companions, 2); + c.touch(&root, b"other", 0o644).unwrap(); + c.touch(&root, b"._other", 0o644).unwrap(); + assert_eq!(c.read_all(&companion.handle, 1024), payload); + assert_eq!(c.lookup(&root, b"anchor").unwrap().0, main.handle); + assert_eq!(c.lookup(&root, b"anchor-alias").unwrap().0, main.handle); + assert_eq!(c.getattr(&orphan.handle), Err(STALE)); + assert_eq!(server.held().companions, 2); + assert_eq!(server.held().names_refused, 0); + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + 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; @@ -768,6 +1229,7 @@ fn spilled_companions_outnumber_the_open_file_limit() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + #[test] fn tickets_are_released_only_after_the_reply() { let base = temp("tickets"); From 6af05cd95e5a93e19fdc20a671420a3c9d0205fe Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:53:20 +0000 Subject: [PATCH 10/34] docs(nfs): document the companion index and the inode binding (lp73) The AppleDouble section now states what `HELD` (65,536 slotted entries) does at the bound - reclaim orphans, then `NFS3ERR_NOSPC` with one rate-limited log per export - and that a companion whose main inode the export knows belongs to that inode: hard links share it, RENAME keeps it under the new name and its aliases, and its last name or silly rename drops it. It records that a whole image takes no `HELD` slot, that `companion_rename` re-classifies under the destination, and how `Table::names`/`Table::aliases` keep unlink, `entry_taken`, `renamed` and retirement from scanning `by_name`, and how CREATE re-reads the name and main file after collecting orphans. Documentation only; it describes the layer as it stands. Production LOC: 164574 -> 164574 (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 2cc52c813 (164574) and this tree (164574). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 47 +++++++++++++------ 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index b8acc9f42e..94cb090ca2 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`, `companion_spill_dir`, `companion_resident_bytes`; `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`, `companions_held`; `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) | @@ -166,28 +166,45 @@ drawn once per export; it makes guessing costly and does not authenticate. ## 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 -one byte after `._`) lives in export memory only, at serial -`SERIALS` (2^62) and above: LOOKUP, GETATTR, ACCESS, READ, WRITE, SETATTR, +`._` files (at least one byte after `._`). With `refuse_apple_double`, a +regular `._` file lives in export state only (`Companions`, serials +`SERIALS` = 2^62 and above): LOOKUP, GETATTR, ACCESS, READ, WRITE, SETATTR, COMMIT, REMOVE and RENAME to another `._` name are served there, READDIR 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. +reaches the Workspace, SQLite overlay or a Commit; everything is dropped with +the export. | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 slotted companion entries | Reclaim orphan slotted companions; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs at most once per 60 s per export | [`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 | 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) | - -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. +| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written and still take no `HELD` slot | [`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 and still take no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | + +A companion whose main inode the export knows belongs to that inode rather than +to one name: hard links share it, main-file RENAME keeps it under the new name +and existing aliases, and only the inode's last name (or its silly rename) +drops it. When a write leaves an inode-bound companion holding a complete +AppleDouble image that encodes back to the exact bytes written +([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)), +it is marked whole and takes no `HELD` slot (decoded in memory within +`DECODED_BYTES` / `DECODED_ENTRY_BYTES`, or kept as written bytes above them); +partial writes, resource forks, other layouts and unknown-main companions stay +as written bytes and occupy a slot. `companion_rename` re-classifies under the +destination so moving onto an unknown main name takes a slot (a spilled body +keeps its prior class). + +`Table::names` and `Table::aliases` index each serial's names so unlink, +`entry_taken` (when `nlink <= 1`), `renamed` (keeping an overwritten recalled +name as an alias) and retirement drop only that serial's keys from `by_name` +without scanning it. At the `HELD` bound, CREATE releases the companion lock to +collect orphans from `Companions::slots` (walking only slotted entries under +the table and companion locks, never whole images or `by_name`), then re-acquires +the lock and re-reads the companion name and main file before inserting, so +concurrent GUARDED creates of one name yield one serial and one +`NFS3ERR_EXIST`. Resident bodies exceeding `RESIDENT_BYTES` spill outside the companion lock to `..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by 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 11/34] 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 12/34] 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 13/34] 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 14/34] 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 15/34] 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 16/34] 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 17/34] 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 e9f49fb64fab2cd64ac367ca0245aeb293545e71 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:20:53 +0000 Subject: [PATCH 18/34] fix(nfs): decide the AppleDouble slot bound in one place, before committing (lp73) The doc comment and `nfs.md` said the index was bounded by `HELD`, but `attach` inserted every slotted companion without a check: a WRITE that broke a whole image, a SETATTR or a RENAME onto an unknown main could grow `slots` past the bound with no `NFS3ERR_NOSPC`, and every `orphans()` walk then scaled with it. `Companions::admits(serial, slotted)` is now the single adjudication: a body that takes no slot is always admitted, a companion already holding one keeps it, and otherwise the bound decides. It is asked before anything is committed, so a refusal leaves the body, its length and its name exactly as they were: - CREATE asks it for a new companion, as before: reclaim the orphan slots once, re-read the name and its main file, then `NFS3ERR_NOSPC` with the counted and rate-limited log; - a WRITE, SETATTR or RENAME that needs a new slot asks it too. The body is edited to one side (`edit_resident` keeps the previous bytes only in this case) and put back if the slot is refused; a body that would be written out and edited on its file is refused before the file is touched, since such a body is no longer known to be a whole image. `edit_companion` then reclaims the orphans once, outside the companion lock, and applies the same edit once more; a second refusal is the whole edit's `NFS3ERR_NOSPC`. The orphan reclaim moves out of `companion_create` into `Kernel::reclaim_orphans` so both paths use the same one, and `nfs.md` records that `HELD` is the admission limit of this export-local shim (owner decision, option C, a scoped waiver, with option A deferred) and not a Workspace capacity. Review: blocking finding 1 and owner decisions D1/C, including the test the owner asked for on the write path. Tests: new `a_write_that_takes_the_last_slot_is_refused_by_the_bound`, which fills the bound through WRITE and not CREATE: three companions each created as a whole image (no slot), then broken by a write; the first two take the two slots, the third answers `NFS3ERR_NOSPC` and still reads back its image byte for byte, with all three companions and their two slots intact. Anti-proof: with `admits` off by one the new test fails at that assertion (`left: Ok(()), right: Err(28)`) and so do three index-bound tests. Production LOC: 164626 -> 164676 (delta +50) 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 76adb9e22 (164626) and of the staged tree (164676). Engine +50. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 9 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 65 ++++++++++++------- .../layerfs-nfs/src/apple_double/edit.rs | 58 +++++++++++++++-- .../layerfs-nfs/src/apple_double_spill.rs | 11 ++++ .../layerfs-nfs/tests/apple_double_decode.rs | 60 +++++++++++++++++ 5 files changed, 174 insertions(+), 29 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index eaa55c7152..a6536a3b91 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -177,7 +177,7 @@ the export. | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 65,536 slotted companion entries | Reclaim orphan slotted companions; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs at most once per 60 s per export | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export) | [`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 of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost` | Spill the least recently touched bodies, decoded ones included, 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_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | @@ -196,6 +196,13 @@ written bytes and occupy a slot. `companion_rename` re-classifies under the destination so moving onto an unknown main name takes a slot (a spilled body keeps its prior class). +`HELD` is the admission limit of this export-local shim, not a Workspace or +Sandbox capacity: the companions live for one mount, are deleted at release and +never reach the Workspace, the SQLite overlay or a Commit (owner decision, +2026-11-14, option C, a scoped waiver). Option A, a per-export SQLite index, is +deferred until `NFS3ERR_NOSPC` shows up in real use; it would add a `rusqlite` +dependency edge to `layerfs-nfs`, which the workspace already pins. + `Table::names` and `Table::aliases` index each serial's names so unlink, `entry_taken` (when `nlink <= 1`), `renamed` (keeping an overwritten recalled name as an alias) and retirement drop only that serial's keys from `by_name` diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index ac3420de31..f8f4824786 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -412,6 +412,14 @@ impl Companions { .find(|(_, serial)| !skip.contains(serial)) .map(|(_, serial)| *serial) } + /// Whether the index takes a companion that takes a slot of the bound: the + /// one place the bound is decided. A companion already holding a slot + /// keeps it, and a body that takes no slot is always admitted. + fn admits(&self, serial: Option, slotted: bool) -> bool { + !slotted + || serial.is_some_and(|serial| self.slots.contains(&serial)) + || self.slots.len() < self.held_limit + } fn holding(&self) -> Holding { Holding { held: self.files.len(), @@ -470,11 +478,12 @@ impl Kernel { let main = name.strip_prefix(b"._").filter(|main| !main.is_empty())?; self.table().by_name.get(&(parent, main.to_vec())).copied() } - /// The companions no name reaches any more: one whose main inode holds no - /// name in the kernel table, and one whose main file the export never - /// observed and does not know now. Taken under the kernel table lock and, - /// inside it, the companion lock, so nothing here copies the namespace; - /// the caller drops them by serial under the companion lock again. + /// The companion slots no name reaches any more: one whose main inode + /// holds no name in the kernel table, and one whose main file the export + /// never observed and does not know now. Taken under the kernel table lock + /// and, inside it, the companion lock, so nothing here copies the + /// namespace; the caller drops them by serial under the companion lock + /// again. fn orphans(&self) -> Vec<(u64, Option)> { let table = self.table(); let companions = self.companions(); @@ -495,6 +504,31 @@ impl Kernel { }) .collect() } + /// Drops the companion slots no name reaches any more and answers how many + /// it dropped. Takes the kernel table lock and, inside it, the companion + /// lock; the files it retires are unlinked afterwards, outside both. Never + /// call it under the companion lock. + fn reclaim_orphans(&self) -> usize { + let orphans = self.orphans(); + let (reclaimed, spilled) = { + let mut companions = self.companions(); + let mut spilled = Vec::new(); + let mut reclaimed = 0; + for (serial, inode) in orphans { + let still_orphan = companions + .files + .get(&serial) + .is_some_and(|file| file.inode == inode && file.slotted()); + if still_orphan { + reclaimed += 1; + spilled.extend(companions.take_serial(serial)); + } + } + (reclaimed, spilled) + }; + unlink_paths(spilled); + reclaimed + } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { let mut companions = self.companions(); @@ -560,12 +594,10 @@ impl Kernel { return self.companion_open(serial, how, directory, companions, tickets); } // At the index bound, reclaim the companions no name reaches any more - // first: found under the kernel table and the companion index, one - // entry at a time, so nothing here copies the namespace. - let mut reclaimed = Vec::new(); - if companions.slots.len() >= companions.held_limit { + // first, outside this lock. + if !companions.admits(None, true) { drop(companions); - let orphans = self.orphans(); + self.reclaim_orphans(); // The reclaim held no companion lock, so another CREATE of this // name may have inserted it meanwhile and the main file may have // changed: both are read again, and the name is inserted under the @@ -575,17 +607,8 @@ impl Kernel { if let Some(serial) = companions.resolve(&named, main) { return self.companion_open(serial, how, directory, companions, tickets); } - for (serial, inode) in orphans { - let still_orphan = companions - .files - .get(&serial) - .is_some_and(|file| file.inode == inode && file.slotted()); - if still_orphan { - reclaimed.extend(companions.take_serial(serial)); - } - } } - if companions.slots.len() >= companions.held_limit { + if !companions.admits(None, true) { let held = companions.slots.len(); let limit = companions.held_limit; let log = companions @@ -596,7 +619,6 @@ impl Kernel { companions.last_refusal_log = Some(Instant::now()); } drop(companions); - unlink_paths(reclaimed); let refused = self.names_refused.fetch_add(1, Ordering::Relaxed) + 1; if let Some(namespace) = namespace { eprintln!( @@ -629,7 +651,6 @@ impl Kernel { companions.index(serial, &file); companions.attach(serial, file); drop(companions); - unlink_paths(reclaimed); self.names_detached.fetch_add(1, Ordering::Relaxed); Ok((stat, directory)) } diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index dccabe7bca..05585b1526 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -18,7 +18,9 @@ //! spilled body: each operation opens its file by path and closes it again. use super::{edited_len, record, Body, Companions, Decoded, DECODED_ENTRY_BYTES, FILE_BYTES}; use crate::{ - apple_double_spill::{create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Room}, + apple_double_spill::{ + create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Edited, Room, + }, attributes::Status, change::{Sattr, Tickets, Wcc}, kernel::Kernel, @@ -173,10 +175,34 @@ 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()); + match self.apply_edit(serial, &edit)? { + Edited::Done(stat) => Ok(stat), + Edited::NoSlot => { + // A body that takes a slot of the index bound has none: + // reclaim the companions no name reaches any more, once, + // outside the companion lock, and apply the same edit again. + // A bound that still has no room refuses the whole edit, with + // the body, its length and its name as they were. + if self.reclaim_orphans() == 0 { + return Err(Status::NoSpc); + } + match self.apply_edit(serial, &edit)? { + Edited::Done(stat) => Ok(stat), + Edited::NoSlot => Err(Status::NoSpc), + } + } + } + } + /// Applies `edit` to `serial` once: in the resident body while the budget + /// holds it, else in its spilled file. It answers that a slot of the index + /// bound is missing rather than changing anything, so the caller can make + /// room and try again. + fn apply_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { let target = edit.target_len(); loop { - match self.edit_resident(serial, target, &edit)? { - Room::Resident(stat) => return Ok(stat), + match self.edit_resident(serial, target, edit)? { + Room::Resident(stat) => return Ok(Edited::Done(stat)), + Room::NoSlot => return Ok(Edited::NoSlot), Room::Spilled => break, Room::Grow(need) => { // No other call changes this body, so a round that finds @@ -188,10 +214,16 @@ impl Kernel { } } // The body still does not fit resident memory: write it out and edit - // its file, which needs no body budget. + // its file, which needs no body budget. A body edited on its file is no + // longer known to be a whole image, so it takes a slot of the index + // bound: decide that before the file is written, and leave the body, + // its file and its name as they were when the bound has none. + if !self.companions().admits(Some(serial), true) { + return Ok(Edited::NoSlot); + } self.spill_gated(serial, target)?; edit.disk(&self.spill_file(serial, true)?)?; - self.record_edit(serial, &edit) + self.record_edit(serial, edit).map(Edited::Done) } /// Applies `edit` to `serial`'s body in memory while the budget holds it /// (a decoded body is encoded first), recording its length, recency and @@ -250,12 +282,26 @@ impl Kernel { return Ok(Room::Spilled); } }; + // A companion holding no slot while the bound is full may take one with + // this edit, and only the edited body says whether it does: its bytes + // are kept when that is the case, so a refusal puts them back exactly. + let restore = (!file.slotted() && !companions.admits(Some(serial), true)) + .then(|| (bytes.clone(), file.whole, file.len)); edit.memory(&mut bytes); file.body = Body::Resident(bytes); record(edit, &mut file); + companions.classify(&mut file); + if let Some((bytes, whole, len)) = restore { + if !companions.admits(Some(serial), file.slotted()) { + file.body = Body::Resident(bytes); + file.whole = whole; + file.len = len; + companions.attach(serial, file); + return Ok(Room::NoSlot); + } + } 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)) diff --git a/engine/crates/layerfs-nfs/src/apple_double_spill.rs b/engine/crates/layerfs-nfs/src/apple_double_spill.rs index dc00914dbc..c55d520070 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_spill.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_spill.rs @@ -152,4 +152,15 @@ pub(crate) enum Room { Spilled, /// Resident, but growing it needs this many more budget bytes first. Grow(usize), + /// The body takes a slot of the index bound and the bound has none. + NoSlot, +} + +/// What one application of an edit made of a companion. +pub(crate) enum Edited { + /// It landed; this is the companion's stat afterwards. + Done(layerfs_workspace::ViewStat), + /// The body would take a slot of the index bound and none is free, so + /// nothing was changed. + NoSlot, } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 990a2395b7..547a6406f5 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -411,6 +411,66 @@ fn a_resource_fork_keeps_the_stored_as_written_fallback() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { + let base = temp("write-bound"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // Two slots, reached through WRITE and not through CREATE: each companion + // is created as a whole image, which takes none, and then broken by a write + // that leaves it not whole, which takes one. + rig.companions_held = 2; + 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 images = Vec::new(); + for i in 0..3 { + c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); + let ad = c + .touch(&root, format!("._m{i}").as_bytes(), 0o644) + .unwrap(); + let whole = image( + [i as u8 + 1; 32], + &[(b"user.value", pattern(70 + i, 512 + i as usize))], + ); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + images.push((ad.handle, whole)); + } + assert_eq!(server.held().companions, 3); + assert_eq!(server.held().companions_slotted, 0, "no companion takes a slot"); + // Two writes that break an image take the two slots. + for i in 0..2 { + c.write(&images[i].0, 24, b"EDIT").unwrap(); + assert_eq!(server.held().companions_slotted, i + 1); + } + // The third would take one more, and the bound has none: the whole write is + // refused, and no companion loses a byte. + assert_eq!(c.write(&images[2].0, 24, b"EDIT").map(|_| ()), Err(NOSPC)); + assert_eq!(server.held().companions, 3, "no companion was dropped"); + assert_eq!(server.held().companions_slotted, 2); + for (handle, whole) in &images { + assert_eq!(c.getattr(handle).unwrap().size as usize, whole.len()); + } + assert_eq!( + c.read_all(&images[2].0, 64 * 1024), + images[2].1, + "the refused companion still holds its image" + ); + for i in 0..2 { + let mut broken = images[i].1.clone(); + broken[24..28].copy_from_slice(b"EDIT"); + assert_eq!(c.read_all(&images[i].0, 64 * 1024), broken); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn whole_images_take_no_slot_of_the_index_bound() { let base = temp("slots"); From 812cb846438936c000679de97d244590f57bc183 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:26:00 +0000 Subject: [PATCH 19/34] fix(nfs): settle the resident budget on a companion RENAME (lp73) `Companion::classify` turns a decoded body back into the client's bytes when the companion is renamed onto a name whose main file the export does not know, and `companion_rename` attached it without looking at `RESIDENT_BYTES`: one rename could put a whole image (up to `FILE_BYTES`) of bytes into a budget it does not fit, and nothing evicted it afterwards. `companion_rename` now resolves the serial and validates the name under the lock, then hands over to `rename_companion`, which takes the companion's edit gate and decides before committing: - a decoded body moving onto an unknown main would cost its image; when that does not fit the budget it is written out first (`spill_gated`, with the file written and renamed outside the companion lock under the gate), so it takes no budget at all and the rename only records the new name and class; - a companion that needs a slot of the index bound asks `Companions::admits`, reclaims the orphan slots once and is refused with `NFS3ERR_NOSPC` rather than exceeding the bound, leaving it under its old name. Review: finding 3 (a rename can exceed the resident budget). Tests: new `a_rename_onto_an_unknown_main_keeps_the_resident_budget`: a decoded image (226 bytes counted) and a 700-byte written body under a 1,024-byte budget, then `._a` renamed to `._zzz`, whose main file does not exist. The resident count is 700 afterwards (the image left memory, `companions_decoded` 0), the new name reads the image back byte for byte and `._a` is gone. Anti-proof: without the write-out the test fails with 4,796 bytes resident against a 1,024-byte budget. Production LOC: 164676 -> 164709 (delta +33) 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 e9f49fb64 (164676) and of the staged tree (164709). Engine +33. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 5 +- engine/crates/layerfs-nfs/src/apple_double.rs | 69 ++++++++++++++++--- .../layerfs-nfs/src/apple_double/edit.rs | 2 +- .../layerfs-nfs/tests/apple_double_decode.rs | 46 +++++++++++++ 4 files changed, 110 insertions(+), 12 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index a6536a3b91..6b36a8febe 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -194,7 +194,10 @@ kept as written bytes, which take the same budget at their length; partial writes, resource forks, other layouts and unknown-main companions stay as written bytes and occupy a slot. `companion_rename` re-classifies under the destination so moving onto an unknown main name takes a slot (a spilled body -keeps its prior class). +keeps its prior class); a decoded body that would be the client's bytes again +and does not fit `RESIDENT_BYTES` is written out first, under the companion's +edit gate and outside the companion lock, so the rename never exceeds the +budget and only records the new name and class. `HELD` is the admission limit of this export-local shim, not a Workspace or Sandbox capacity: the companions live for one mount, are deleted at release and diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index f8f4824786..9dcebf4057 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -723,25 +723,74 @@ impl Kernel { ) -> Option> { let from_main = self.main_of(from, name); let to_main = self.main_of(to, new_name); + let serial = { + let companions = self.companions(); + companions.resolve(&(from, name.to_vec()), from_main)? + }; + if !crate::names::apple_double(new_name) || new_name.len() > 255 { + return Some(Err(Status::Access)); + } + Some(self.rename_companion(serial, (to, new_name.to_vec()), to_main)) + } + /// Moves `serial`'s companion to `target`, under `to_main`'s inode. + /// + /// The body is classified again under the destination, so a whole image + /// renamed onto an unknown main is the client's bytes again and takes a + /// slot: such a body no longer fits the resident budget as attributes, and + /// is written out first (outside the companion lock, with the companion's + /// edit gate held), so the rename itself only records a name and a class. + /// A companion that needs a new slot of the index bound takes the same + /// decision the edit path takes: the orphan slots are reclaimed once and + /// the rename is refused if the bound still has none. + fn rename_companion(&self, serial: u64, target: Named, to_main: Option) -> Result<(), Status> { + let gate = { + let companions = self.companions(); + companions.files.get(&serial).ok_or(Status::Stale)?.editing.clone() + }; + // Held to the end: the body written out below is the body renamed. + let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); + // A decoded body renamed onto an unknown main would cost its whole + // image of the resident budget: write it out instead, which costs none. + let leaves_memory = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + match &file.body { + Body::Decoded(image) if to_main.is_none() => { + let cost = image.len(); + companions + .resident_bytes + .saturating_sub(image.cost()) + .saturating_add(cost) + > companions.resident_budget + } + _ => false, + } + }; + if leaves_memory { + self.spill_gated(serial, 0)?; + } + // A companion moved onto an unknown main takes a slot; one already + // holding a slot keeps it, and one that stays a whole image keeps its + // exemption. + if !self.companions().admits(Some(serial), to_main.is_none()) { + self.reclaim_orphans(); + if !self.companions().admits(Some(serial), to_main.is_none()) { + return Err(Status::NoSpc); + } + } let mut replaced_path = None; { let mut companions = self.companions(); - let serial = companions.resolve(&(from, name.to_vec()), from_main)?; - if !crate::names::apple_double(new_name) || new_name.len() > 255 { - return Some(Err(Status::Access)); - } - let target = (to, new_name.to_vec()); + let mut file = companions.detach(serial).ok_or(Status::Stale)?; + companions.unindex(serial, &file); if let Some(replaced) = companions.resolve(&target, to_main) { if replaced != serial { replaced_path = companions.take_serial(replaced); } } - let tick = companions.tick(); - let mut file = companions.detach(serial)?; - companions.unindex(serial, &file); file.named = target; file.inode = to_main; - file.used = tick; + file.used = companions.tick(); // A client may write a companion under another name first, and a // name it moves onto may belong to another main inode, or to // none: the body is classified again under the destination, so @@ -752,7 +801,7 @@ impl Kernel { companions.attach(serial, file); } unlink_paths(replaced_path); - Some(Ok(())) + Ok(()) } /// Drops every companion and removes the export's spill directory; returns /// what the index held. diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 05585b1526..a63a4752ca 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -392,7 +392,7 @@ impl Kernel { /// 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> { + pub(super) 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)?; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 547a6406f5..6fc351a138 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -411,6 +411,52 @@ fn a_resource_fork_keeps_the_stored_as_written_fallback() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_rename_onto_an_unknown_main_keeps_the_resident_budget() { + let base = temp("rename-budget"); + 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")); + // Nearly full: a decoded image of a few hundred bytes and a written body + // of 700 bytes. + 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("/"); + c.touch(&root, b"a", 0o644).unwrap(); + let image_name = c.touch(&root, b"._a", 0o644).unwrap(); + let whole = image([0x31; 32], &[(b"user.small", pattern(80, 64))]); + c.write(&image_name.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + c.touch(&root, b"b", 0o644).unwrap(); + let other = c.touch(&root, b"._b", 0o644).unwrap(); + c.write(&other.handle, 0, &pattern(81, 700)).unwrap(); + let before = server.held(); + assert!(before.companion_bytes <= 1024, "{}", before.companion_bytes); + + // Onto a name whose main file the export does not know: the decoded body is + // the client's bytes again, which the budget does not take, so it leaves + // memory first and the rename still happens. + c.rename(&root, b"._a", &root, b"._zzz").unwrap(); + let after = server.held(); + assert_eq!( + after.companion_bytes, 700, + "only the written body takes the budget: the image left memory" + ); + assert_eq!(after.companions_decoded, 0); + let (moved, attr) = c.lookup(&root, b"._zzz").unwrap(); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&moved, 64 * 1024), whole); + assert_eq!(c.lookup(&root, b"._a").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let base = temp("write-bound"); From e9025300f7ccd023a282cedd05039c399a3fdab5 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:32:50 +0000 Subject: [PATCH 20/34] fix(nfs): confirm a companion's main file before reclaiming it (lp73) A companion created while its main name was missing from the export's name index got `inode: None`, and `orphans()` read that as "no main file": the name index is lossy (its own bound, a name the export never looked up, a rename on the client side), so a live companion could be reclaimed at the `HELD` bound and lose its attributes. `orphans()` now answers candidates, and `reclaim_orphans` decides on one whose main inode the export does not know with one read-only lookup of its main file in the engine (`Kernel::observe`), run outside the kernel table lock and the companion lock. A file that is there binds the companion back to that inode (`file.inode` and `Companions::inodes`), which keeps its attributes and makes every name of the inode reach it; only `NFS3ERR_NOENT` makes it an orphan; a lookup that cannot answer keeps it as it is. `Companions::slots` is unchanged, so a bound companion keeps the slot it took. Review: finding 4 (live data reclaimed as an orphan). Tests: new `a_companion_of_a_main_file_the_name_index_missed_is_kept`: the main file is part of the tree the export is initialized from and the export never looks its name up, so the companion created for it has no main inode, under a one-slot bound. The next CREATE reclaims, finds the main file, keeps the companion (`companions`/`companions_slotted` 1/1, `names_refused` 1), the image reads back byte for byte, and a hard link of the main file reaches the same companion. Anti-proof: reclaiming on the name index's word again drops it, and the test then fails when the refused CREATE succeeds instead. Production LOC: 164709 -> 164756 (delta +47) 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 812cb8464 (164709) and of the staged tree (164756). Engine +47. 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 | 104 +++++++++++++++--- engine/crates/layerfs-nfs/src/kernel.rs | 2 +- .../layerfs-nfs/tests/apple_double_decode.rs | 47 ++++++++ 4 files changed, 140 insertions(+), 20 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 6b36a8febe..d97d0bc841 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -214,7 +214,12 @@ collect orphans from `Companions::slots` (walking only slotted entries under the table and companion locks, never whole images or `by_name`), then re-acquires the lock and re-reads the companion name and main file before inserting, so concurrent GUARDED creates of one name yield one serial and one -`NFS3ERR_EXIST`. +`NFS3ERR_EXIST`. The name index is lossy (its own bound, a name never looked +up, a client-side rename), so a candidate whose main inode the export does not +know costs one read-only lookup of its main file in the engine, outside both +locks: a file that is there binds the companion back to that inode and keeps +its attributes, only `NFS3ERR_NOENT` makes it an orphan, and a lookup that +cannot answer leaves it alone. Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` together, are written to `..tmp` (`create_new`, dir `0700`, file diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 9dcebf4057..d03d69fc36 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -51,8 +51,11 @@ use crate::{ change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, }; -use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; -use layerfs_workspace::ViewStat; +use layerfs_content::{ + filesystem::{attributes::PortableMetadata, PathName}, + object::inode_leaf::InodeKind, +}; +use layerfs_workspace::{KernelReadOperation, ViewStat}; use std::{ collections::{BTreeSet, HashMap, HashSet}, fs, @@ -125,6 +128,18 @@ impl Companion { } } +/// A slot of the index the export's own name index cannot reach, and what the +/// reclaim needs to decide about it. +struct Orphan { + serial: u64, + /// The main inode the export knows for it; an inode holding no name in the + /// kernel table is gone. + inode: Option, + /// Its main file's directory and name when it has no inode: the name index + /// is lossy, so only the engine can say whether that file is there. + main: Option, +} + /// What [`Companions::keep_decoded`] made of an edited body. pub(crate) enum Decoded { /// The companion holds the body's decoded form. @@ -480,11 +495,11 @@ impl Kernel { } /// The companion slots no name reaches any more: one whose main inode /// holds no name in the kernel table, and one whose main file the export - /// never observed and does not know now. Taken under the kernel table lock - /// and, inside it, the companion lock, so nothing here copies the - /// namespace; the caller drops them by serial under the companion lock - /// again. - fn orphans(&self) -> Vec<(u64, Option)> { + /// never observed and whose name its name index does not hold. Taken under + /// the kernel table lock and, inside it, the companion lock, so nothing + /// here copies the namespace; the caller drops them by serial under the + /// companion lock again. + fn orphans(&self) -> Vec { let table = self.table(); let companions = self.companions(); companions @@ -492,15 +507,25 @@ impl Kernel { .iter() .filter_map(|serial| { let file = companions.files.get(serial)?; - let live = match file.inode { - Some(inode) => { - table.names.contains_key(&inode) || table.aliases.contains_key(&inode) - } - None => file.named.1.strip_prefix(b"._").is_some_and(|main| { - table.by_name.contains_key(&(file.named.0, main.to_vec())) - }), - }; - (!live).then_some((*serial, file.inode)) + if let Some(inode) = file.inode { + let live = + table.names.contains_key(&inode) || table.aliases.contains_key(&inode); + return (!live).then_some(Orphan { + serial: *serial, + inode: Some(inode), + main: None, + }); + } + let main = file.named.1.strip_prefix(b"._")?; + let main = (file.named.0, main.to_vec()); + // A name the index does hold reaches the companion; one it does + // not hold only makes it a candidate, since that index is + // lossy. + (!table.by_name.contains_key(&main)).then_some(Orphan { + serial: *serial, + inode: None, + main: Some(main), + }) }) .collect() } @@ -508,13 +533,56 @@ impl Kernel { /// it dropped. Takes the kernel table lock and, inside it, the companion /// lock; the files it retires are unlinked afterwards, outside both. Never /// call it under the companion lock. + /// + /// A companion whose main inode the export does not know is not dropped on + /// the name index's word: that index is lossy (its own bound, a name the + /// export never looked up, a rename on the client side), so each one costs + /// one read-only lookup of its main file in the engine, run outside both + /// locks. A main file that is there binds the companion back to its inode, + /// which keeps its attributes; only a lookup that answers "no such file" + /// makes it an orphan, and one that cannot answer leaves it as it is. fn reclaim_orphans(&self) -> usize { - let orphans = self.orphans(); + let (bound, dead) = self.orphans().into_iter().fold( + (Vec::new(), Vec::new()), + |(mut bound, mut dead), orphan| { + let Some((parent, main)) = orphan.main else { + dead.push((orphan.serial, orphan.inode)); + return (bound, dead); + }; + match PathName::from_bytes(&main) { + Ok(name) => { + let lookup = KernelReadOperation::Lookup { parent, name }; + match self.observe(parent, None, lookup) { + Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), + Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), + // Unknown: the companion keeps its custody. + Err(_) => {} + } + } + Err(_) => {} + } + (bound, dead) + }, + ); let (reclaimed, spilled) = { let mut companions = self.companions(); let mut spilled = Vec::new(); let mut reclaimed = 0; - for (serial, inode) in orphans { + for (serial, main) in bound { + let Some(mut file) = companions.detach(serial) else { + continue; + }; + if file.inode.is_some() || !file.slotted() { + companions.attach(serial, file); + continue; + } + // Bound back to the inode the engine found: it keeps the slot it + // took, and from here it follows that inode's names. + file.inode = Some(main); + companions.index(serial, &file); + companions.attach(serial, file); + } + for (serial, inode) in dead { let still_orphan = companions .files .get(&serial) diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index a2e297e7fa..3540cfefb3 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -371,7 +371,7 @@ impl Kernel { let services = self.services.request(&self.fence).map_err(failure)?; Ok((services, self.requests.fetch_add(1, Ordering::Relaxed))) } - fn observe( + pub(crate) fn observe( &self, protected: u64, handle: Option, diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 6fc351a138..b57f134db5 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -457,6 +457,53 @@ fn a_rename_onto_an_unknown_main_keeps_the_resident_budget() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_of_a_main_file_the_name_index_missed_is_kept() { + let base = temp("orphan-live"); + let tree = base.join("tree"); + source(&tree); + // The main file is part of the tree the export is initialized from, and + // this export never looks its name up, so its name index does not hold it: + // the companion created for it has no main inode, which the export's own + // index reads as an orphan. + fs::write(tree.join("live"), b"the data file").unwrap(); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // One slot, so the next CREATE has to reclaim before it can ask. + rig.companions_held = 1; + 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 ad = c.touch(&root, b"._live", 0o644).unwrap(); + let whole = image([0x51; 32], &[(b"user.kept", pattern(90, 128))]); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The bound is full, so the next CREATE reclaims the orphan slots first. + // The main file is there, so the lookup keeps the companion and binds it to + // that inode, and the CREATE is then refused. + c.touch(&root, b"other", 0o644).unwrap(); + assert_eq!(c.touch(&root, b"._other", 0o644).map(|_| ()), Err(NOSPC)); + let held = server.held(); + assert_eq!((held.companions, held.companions_slotted), (1, 1)); + assert_eq!(held.names_refused, 1); + assert_eq!(c.getattr(&ad.handle).unwrap().size as usize, whole.len()); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole, "attributes kept"); + + // It belongs to that inode now: another name of the inode reaches it. + let live = c.lookup(&root, b"live").unwrap().0; + c.link(&live, &root, b"alias").unwrap(); + let (shared, attr) = c.lookup(&root, b"._alias").unwrap(); + assert_eq!(shared, ad.handle, "hard links share one companion"); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&shared, 64 * 1024), whole); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let base = temp("write-bound"); From 3c3558f19aff6ad6290cadac4082699b56c33a8e Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:34:33 +0000 Subject: [PATCH 21/34] chore(nfs): make the AppleDouble companion edits fmt- and clippy-clean (lp73) `cargo fmt --check` reported four files of this branch and `cargo clippy --workspace --all-targets -D warnings` two lint findings in the new tests (`needless_range_loop`) and one in `reclaim_orphans` (`single_match`). This is that pass and nothing else: no behaviour changes. 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 --workspace --exclude layerfs-node --all-targets -- -D warnings` is clean; `python3 -B tools/check_product_boundary.py --skip-sdk` PASS, `python3 -B tools/check_fuser_integrity.py` no errors, `python3 -B -m unittest discover -s tools -p 'test_*.py'` 188 OK. `cargo test -p layerfs-nfs`: 67 passed, 0 failed (raw sum 68 with the child-process rerun). Production LOC: 164756 -> 164768 (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 e9025300f (164756) and of the staged tree (164768). Engine +12: rustfmt splits three long signatures and calls and the `if let` rewrites one match, which the counter counts. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 32 ++++++++------ .../layerfs-nfs/src/apple_double_codec.rs | 7 ++- .../layerfs-nfs/tests/apple_double_codec.rs | 5 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 43 +++++++++++-------- 4 files changed, 56 insertions(+), 31 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index d03d69fc36..07ecc66d51 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -549,17 +549,15 @@ impl Kernel { dead.push((orphan.serial, orphan.inode)); return (bound, dead); }; - match PathName::from_bytes(&main) { - Ok(name) => { - let lookup = KernelReadOperation::Lookup { parent, name }; - match self.observe(parent, None, lookup) { - Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), - Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), - // Unknown: the companion keeps its custody. - Err(_) => {} - } + // A name the engine cannot even take, or a lookup it cannot + // answer, leaves the companion as it is. + if let Ok(name) = PathName::from_bytes(&main) { + let lookup = KernelReadOperation::Lookup { parent, name }; + match self.observe(parent, None, lookup) { + Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), + Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), + Err(_) => {} } - Err(_) => {} } (bound, dead) }, @@ -810,10 +808,20 @@ impl Kernel { /// A companion that needs a new slot of the index bound takes the same /// decision the edit path takes: the orphan slots are reclaimed once and /// the rename is refused if the bound still has none. - fn rename_companion(&self, serial: u64, target: Named, to_main: Option) -> Result<(), Status> { + fn rename_companion( + &self, + serial: u64, + target: Named, + to_main: Option, + ) -> Result<(), Status> { let gate = { let companions = self.companions(); - companions.files.get(&serial).ok_or(Status::Stale)?.editing.clone() + companions + .files + .get(&serial) + .ok_or(Status::Stale)? + .editing + .clone() }; // Held to the end: the body written out below is the body renamed. let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); 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 b57f134db5..73a1c28db6 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -197,7 +197,10 @@ fn a_read_racing_a_truncation_is_a_short_read_not_an_io_error() { // 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()); + assert_eq!( + reader.getattr(&ad.handle).unwrap().size as usize, + body.len() + ); } drop((reader, writer)); @@ -520,9 +523,7 @@ fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let mut images = Vec::new(); for i in 0..3 { c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); - let ad = c - .touch(&root, format!("._m{i}").as_bytes(), 0o644) - .unwrap(); + let ad = c.touch(&root, format!("._m{i}").as_bytes(), 0o644).unwrap(); let whole = image( [i as u8 + 1; 32], &[(b"user.value", pattern(70 + i, 512 + i as usize))], @@ -532,11 +533,15 @@ fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { images.push((ad.handle, whole)); } assert_eq!(server.held().companions, 3); - assert_eq!(server.held().companions_slotted, 0, "no companion takes a slot"); + assert_eq!( + server.held().companions_slotted, + 0, + "no companion takes a slot" + ); // Two writes that break an image take the two slots. - for i in 0..2 { - c.write(&images[i].0, 24, b"EDIT").unwrap(); - assert_eq!(server.held().companions_slotted, i + 1); + for (taken, (handle, _)) in images.iter().take(2).enumerate() { + c.write(handle, 24, b"EDIT").unwrap(); + assert_eq!(server.held().companions_slotted, taken + 1); } // The third would take one more, and the bound has none: the whole write is // refused, and no companion loses a byte. @@ -551,10 +556,10 @@ fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { images[2].1, "the refused companion still holds its image" ); - for i in 0..2 { - let mut broken = images[i].1.clone(); + for (handle, whole) in images.iter().take(2) { + let mut broken = whole.clone(); broken[24..28].copy_from_slice(b"EDIT"); - assert_eq!(c.read_all(&images[i].0, 64 * 1024), broken); + assert_eq!(c.read_all(handle, 64 * 1024), broken); } drop(c); @@ -737,16 +742,16 @@ fn eviction_takes_the_decoded_body_before_the_written_ones() { 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))], - ); + 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"); + 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 @@ -765,7 +770,11 @@ fn eviction_takes_the_decoded_body_before_the_written_ones() { "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(&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()); 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 22/34] 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 23/34] 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 24/34] 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(); From f6cb67819ed36f4562d1d59980618ea2077eda81 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:54:57 +0000 Subject: [PATCH 25/34] fix(nfs): register the main file a reclamation's lookup found (lp73) A companion whose main inode the export did not know was, at the `HELD` bound, looked up in the engine and bound back to the inode that lookup found. The binding only set `Companion::inode`: the export's table never learned the name, so `orphans()` still read the companion as an inode holding no name at all, and the *next* reclamation dropped it and lost its attributes. The deciding visit also took one engine lookup reference that the export never recorded and never gave back, so every bound companion leaked one. The successful lookup now goes through `Kernel::entry_taken`, the same call `Kernel::lookup` and every creating mutation make: it remembers the name, takes the one reference the export keeps per serial (forgetting a second) and records the directory. The bound companion is then live for the next reclamation and its reference is given back with the rest in `Kernel::release`. Review: finding P1-1 (the fix for the reclamation lookup was incomplete and leaked a reference). Tests: new `a_companion_bound_back_to_its_main_file_survives_the_next_reclaim`: one slot, a companion for a main file in the initialized tree that this export never looks up, one reclamation that binds it (the export's lookup count grows by exactly one) and a second one with the bound still full, during which the companion keeps its slot, its bytes and its attributes and the export's count does not move; then the main file's last name goes and the companion with it. Anti-proof: without `entry_taken` the test fails at that count (`left: 1, right: 2`), and with the count assertions out of the way it fails on the second reclamation, which now succeeds because it dropped the live companion (`left: Ok(()), right: Err(28)`). Production LOC: 164794 -> 164797 (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 c94693a9a (164794) and of the staged tree (164797). Engine +3: the registration call and the comment block around it. 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 | 12 +++- .../layerfs-nfs/tests/apple_double_decode.rs | 58 ++++++++++++++++++- 3 files changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 0635334f59..1b7d78c8a1 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -219,7 +219,12 @@ up, a client-side rename), so a candidate whose main inode the export does not know costs one read-only lookup of its main file in the engine, outside both locks: a file that is there binds the companion back to that inode and keeps its attributes, only `NFS3ERR_NOENT` makes it an orphan, and a lookup that -cannot answer leaves it alone. +cannot answer leaves it alone. The lookup that finds the main file took one +engine reference on it, and the export keeps exactly one per serial, so the +visit registers the name it found the file under (`Kernel::entry_taken`, as +`Kernel::lookup` does) before the companion is bound: that name is what makes +the bound companion live for the next reclamation, and its reference is the one +the export later gives back. Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` together, are written to `..tmp` (`create_new`, dir `0700`, file diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 07ecc66d51..3b578429d3 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -541,6 +541,13 @@ impl Kernel { /// locks. A main file that is there binds the companion back to its inode, /// which keeps its attributes; only a lookup that answers "no such file" /// makes it an orphan, and one that cannot answer leaves it as it is. + /// + /// A lookup that finds the main file took one engine reference on it, and + /// the export keeps exactly one per serial: the visit is the entry's, so it + /// is registered as `Kernel::lookup` registers one (`entry_taken` remembers + /// the name and forgets a second reference). Without that the name reaches + /// the companion nowhere, and the next reclamation would read the bound one + /// as an inode holding no name and drop it. fn reclaim_orphans(&self) -> usize { let (bound, dead) = self.orphans().into_iter().fold( (Vec::new(), Vec::new()), @@ -554,7 +561,10 @@ impl Kernel { if let Ok(name) = PathName::from_bytes(&main) { let lookup = KernelReadOperation::Lookup { parent, name }; match self.observe(parent, None, lookup) { - Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), + Ok((stat, _, _)) => { + self.entry_taken(&stat, parent, &main); + bound.push((orphan.serial, stat.serial)); + } Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), Err(_) => {} } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index d754d8f12c..dc14f9e933 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -510,6 +510,63 @@ fn a_companion_of_a_main_file_the_name_index_missed_is_kept() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_bound_back_to_its_main_file_survives_the_next_reclaim() { + let base = temp("orphan-bound"); + let tree = base.join("tree"); + source(&tree); + // As in the test above: the main file is part of the tree the export was + // initialized from, and never looked up, so the companion starts with no + // main inode and takes the one slot. + fs::write(tree.join("live"), b"the data file").unwrap(); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 1; + 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 ad = c.touch(&root, b"._live", 0o644).unwrap(); + let whole = image([0x52; 32], &[(b"user.kept", pattern(91, 128))]); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The bound is full, so this CREATE reclaims first: the lookup finds the + // main file, the companion becomes that inode's, and the name the visit + // found is the export's one reference (not a second one it never gives + // back). The CREATE is then refused. + c.touch(&root, b"other", 0o644).unwrap(); + let lookups = server.held().lookups; + assert_eq!(c.touch(&root, b"._other", 0o644).map(|_| ()), Err(NOSPC)); + assert_eq!(server.held().lookups, lookups + 1, "one reference, kept"); + assert_eq!(server.held().companions_slotted, 1); + + // A second reclamation runs without the client ever looking the main file + // up: the bound companion holds a name in the export's table now, so it is + // not an orphan, and its attributes stay. + c.touch(&root, b"other2", 0o644).unwrap(); + let lookups = server.held().lookups; + assert_eq!(c.touch(&root, b"._other2", 0o644).map(|_| ()), Err(NOSPC)); + assert_eq!( + server.held().lookups, + lookups, + "the live name needs no visit" + ); + assert_eq!(server.held().companions, 1); + assert_eq!(server.held().companions_slotted, 1); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole, "attributes kept"); + + // It follows that inode: it goes with the inode's last name. + c.remove(&root, b"live").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + assert_eq!(c.lookup(&root, b"._live").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let base = temp("write-bound"); @@ -1123,7 +1180,6 @@ fn a_rename_keeps_the_other_names_of_the_inode_companion() { assert_eq!(server.held().companions, 0); assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); - drop(c); let released = server.stop(); let (_, outstanding) = rig.stop(released); From 45d090391aa63a7f9a5b978f31b345d1cf072b50 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:02:57 +0000 Subject: [PATCH 26/34] fix(nfs): keep a companion with the inode's other names, and link its names (lp73) macOS 27.2, build 525fcfb41, reproducible 20/20 and 5/5: a file carrying attributes, `ln a b`, then `rm a`, leaves `b` with no attributes at all and `._b` answering `NFS3ERR_NOENT`, while the companion is still in the export's index. The companion was the inode's, so nothing about the inode changed; what the client sent is what removed it. Reproduced in the rig with the client's sequence: `/bin/ln a b` links the main file, then the client drops the `._` name of the name it no longer uses with a REMOVE of `._a`, and REMOVE took the whole companion: `held().companions` 1 to 0, `._b` `NFS3ERR_NOENT`, the attributes gone. A client that carries the attributes to the new name also sends a LINK of the companion name (`._a` to `._b`), which this export refused with `NFS3ERR_ACCES`. - A companion now holds every `._` name of the inode it was linked under (`Companion::also`, indexed and unindexed with its own name, one name promoted when the recorded one goes). - `companion_link` serves LINK of a companion serial: another `._` name of the same companion, `NFS3ERR_EXIST` for a name already held or another companion's, `NFS3ERR_ACCES` for a name of the Workspace. - `companion_remove` drops one name while the companion holds another, or while its inode has another name the export knows (`Table::names` plus `Table::aliases`); only the last name of a one-name inode is the client clearing the attributes, which still takes the companion, as does any name of a companion no inode owns. Review: macOS re-test, finding 1 (hard link then remove the original name). This is the same rule the hard-link contract already stated, which the name scoped REMOVE broke. Tests: two new. `a_hard_link_keeps_the_companion_under_its_other_names`: main file and attributes, LINK, REMOVE `._a`, then REMOVE `a`; `._b` reads the same companion and bytes at every step and the companion goes with `b`. `a_linked_companion_name_is_another_name_of_the_same_companion`: LINK of the companion name succeeds and reads the same bytes, a held name answers `NFS3ERR_EXIST`, a plain name `NFS3ERR_ACCES`, REMOVE of `._a` keeps `._b`, and REMOVE of a one-name inode's only `._` name still removes the companion. Anti-proofs: with the keep rule forced off both tests fail (`left: 0, right: 1` companions, the attributes gone), and with LINK of a companion back to `NFS3ERR_ACCES` the second fails on that LINK. `cargo test -p layerfs-nfs`: 71 passed, 0 failed (raw sum 72 with the child-process rerun). Production LOC: 164797 -> 164884 (delta +87) 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 f6cb67819 (164797) and of the staged tree (164884). Engine +87: the companion's extra names and the three index operations on them, `companion_link`, the name-count rule in `companion_remove`, and the routed LINK. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 11 +- engine/crates/layerfs-nfs/src/apple_double.rs | 135 ++++++++++++++++-- engine/crates/layerfs-nfs/src/change.rs | 4 +- .../layerfs-nfs/tests/apple_double_decode.rs | 106 ++++++++++++++ 4 files changed, 245 insertions(+), 11 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 1b7d78c8a1..cee540a021 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -185,7 +185,16 @@ the export. A companion whose main inode the export knows belongs to that inode rather than to one name: hard links share it, main-file RENAME keeps it under the new name and existing aliases, and only the inode's last name (or its silly rename) -drops it. When a write leaves an inode-bound companion holding a complete +drops it. It can hold several of the inode's `._` names at once: a LINK of a +companion name (`._a` to `._b`, which a client that carries the attributes to +a new name sends) adds one, answering `NFS3ERR_EXIST` for a name already held +and `NFS3ERR_ACCES` for a name of the Workspace, and a REMOVE of one of those +names drops only that name while the companion holds another or its inode has +another name the export knows. The REMOVE of the last name of an inode with one +name is the client clearing the attributes, which takes the companion with it, +as does any name of a companion no main inode owns. + +When a write leaves an inode-bound companion holding a complete AppleDouble image that encodes back to the exact bytes written ([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)), it is marked whole and takes no `HELD` slot: decoded in memory (counted as diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 3b578429d3..77cf8988d3 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -4,7 +4,8 @@ //! 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, under its own serial range: LOOKUP, GETATTR, ACCESS, READ, -//! WRITE, SETATTR, COMMIT, REMOVE and a RENAME to another AppleDouble name +//! WRITE, SETATTR, COMMIT, REMOVE, a LINK to another AppleDouble name 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. @@ -21,7 +22,11 @@ //! hard links share one companion, it follows the inode through RENAME, and it //! goes with the inode's last name rather than with one name. Its FinderInfo //! and extended attributes are kept under that inode's serial, not under the -//! `._` name. Whenever a write leaves such a companion holding a whole +//! `._` name. It may hold several of the inode's `._` names at once (a LINK of +//! a companion name makes one, and a client that links a file keeps the +//! attributes aside under each name), and removing one of them leaves the +//! companion to the inode's other names: only its last name, on an inode with +//! no other name the export knows, is the client clearing the attributes. Whenever a write leaves such 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 (each at most [`DECODED_ENTRY_BYTES`] @@ -97,6 +102,10 @@ enum Body { struct Companion { /// The `._` name it was created or last renamed to. named: Named, + /// The other `._` names of the same companion, which a LINK made: a client + /// that links a file keeps its attributes aside under each of the file's + /// names, and every one of them is a name of this one companion. + also: Vec, /// The main inode it belongs to, when the export knew it at creation. inode: Option, /// Its body is a whole image: any name of the inode reads it, and it takes @@ -261,17 +270,22 @@ impl Companions { self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); Some(file) } - /// Makes `file`'s name and main inode find `serial`. + /// Makes every name of `file` and its main inode find `serial`. fn index(&mut self, serial: u64, file: &Companion) { self.names.insert(file.named.clone(), serial); + for named in &file.also { + self.names.insert(named.clone(), serial); + } if let Some(inode) = file.inode { self.inodes.insert(inode, serial); } } - /// Drops `file`'s name and inode keys that still find `serial`. + /// Drops every name of `file` and its inode key that still find `serial`. fn unindex(&mut self, serial: u64, file: &Companion) { - if self.names.get(&file.named) == Some(&serial) { - self.names.remove(&file.named); + for named in std::iter::once(&file.named).chain(&file.also) { + if self.names.get(named) == Some(&serial) { + self.names.remove(named); + } } if let Some(inode) = file.inode { if self.inodes.get(&inode) == Some(&serial) { @@ -279,6 +293,37 @@ impl Companions { } } } + /// Whether `serial` holds a name other than `named`. + fn holds_another(&self, serial: u64, named: &Named) -> bool { + self.files.get(&serial).is_some_and(|file| { + (file.named != *named && self.names.get(&file.named) == Some(&serial)) + || file.also.iter().any(|also| also != named) + }) + } + /// Drops `named`, one of `serial`'s names, and answers whether it held it. + /// A companion left with no name is still reached through its main inode, + /// so it keeps its record; another held name becomes the one its record + /// names, so a later `index` puts back only names it still holds. + fn drop_name(&mut self, serial: u64, named: &Named) -> bool { + let Some(file) = self.files.get_mut(&serial) else { + return false; + }; + let primary = file.named == *named; + if !primary && !file.also.iter().any(|also| also == named) { + return false; + } + if self.names.get(named) == Some(&serial) { + self.names.remove(named); + } + if primary { + if let Some(next) = file.also.pop() { + file.named = next; + } + } else { + file.also.retain(|also| also != named); + } + true + } /// The companion `named` reaches when its main file is `main`: the one /// held under that name, unless it belongs to another inode than `main`, /// else the one its main inode already has. @@ -715,6 +760,7 @@ impl Kernel { let used = companions.tick(); let file = Companion { named, + also: Vec::new(), inode: main, whole: false, len: 0, @@ -732,16 +778,49 @@ impl Kernel { } /// REMOVE of a companion name, with the directory's `wcc_data`; `None` /// when no companion has that name. + /// + /// A companion the export pairs with a main inode is the inode's, not one + /// name's: its FinderInfo and attributes belong to the file, so a client + /// that links the file (or removes one of its names) and drops the `._` + /// name it no longer uses leaves the companion to the inode's remaining + /// names. Only while this name is the companion's last one, and its inode + /// has no other name the export knows, is the REMOVE the client clearing + /// the attributes, which takes the companion with it. A companion no main + /// inode owns has nothing else to go with and always goes. pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { + let named = (parent, name.to_vec()); let main = self.main_of(parent, name); + let (serial, inode, one_name) = { + let companions = self.companions(); + let serial = companions.resolve(&named, main)?; + let file = companions.files.get(&serial)?; + ( + serial, + file.inode, + !companions.holds_another(serial, &named), + ) + }; + let kept = !one_name || inode.is_some_and(|inode| self.knows_another_name(inode)); let spilled = { let mut companions = self.companions(); - let serial = companions.resolve(&(parent, name.to_vec()), main)?; - companions.take_serial(serial) + if kept { + companions.drop_name(serial, &named); + Vec::new() + } else { + companions.take_serial(serial).into_iter().collect() + } }; unlink_paths(spilled); Some(self.directory_wcc(parent)) } + /// Whether the export's name index knows a name of `inode` beyond the one + /// it remembers: a hard link the client made, which the companion of an + /// inode follows. + fn knows_another_name(&self, inode: u64) -> bool { + let table = self.table(); + let remembered = usize::from(table.names.contains_key(&inode)); + remembered + table.aliases.get(&inode).map_or(0, Vec::len) > 1 + } /// The main file `name` in `parent` was removed, silly-renamed or replaced /// by `RENAME`: drops the companion held under `._`, or only that /// name when the companion belongs to an inode, which goes with the @@ -768,7 +847,7 @@ impl Kernel { .get(&serial) .is_some_and(|file| file.inode.is_some()) { - companions.names.remove(&named); + companions.drop_name(serial, &named); None } else { companions.take_serial(serial) @@ -787,6 +866,44 @@ impl Kernel { }; unlink_paths(spilled); } + /// LINK of a companion name: the same companion under another AppleDouble + /// name, as a client that links a file makes to carry its attributes to + /// the new name. The name it names must be free, and a name that is not + /// another companion name is refused, so a companion never becomes a file + /// of the Workspace. + pub(crate) fn companion_link( + &self, + serial: u64, + parent: u64, + name: &[u8], + ) -> Result<(ViewStat, Wcc), Status> { + if !crate::names::apple_double(name) || name.len() > 255 { + return Err(Status::Access); + } + if parent != self.root() && !self.table().parents.contains_key(&parent) { + return Err(Status::NotDir); + } + let named = (parent, name.to_vec()); + let directory = self.directory_wcc(parent); + let main = self.main_of(parent, name); + let mut companions = self.companions(); + if companions.names.contains_key(&named) + || companions + .resolve(&named, main) + .is_some_and(|other| other != serial) + { + return Err(Status::Exist); + } + let Some(mut file) = companions.detach(serial) else { + return Err(Status::Stale); + }; + file.also.push(named); + file.used = companions.tick(); + let stat = Companions::stat(serial, &file); + companions.index(serial, &file); + companions.attach(serial, file); + Ok((stat, directory)) + } /// RENAME of a companion name: only to another AppleDouble name, which it /// replaces when held. It then belongs to the destination's main inode, or /// to none when that is unknown. `None` when no companion has that name. diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 11f74ef414..81ebb40345 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -643,8 +643,10 @@ impl Kernel { name: &[u8], tickets: &mut Tickets, ) -> Result<(ViewStat, Wcc), Status> { + // A companion holds no engine inode, so its LINK is another `._` name + // of the same companion, decided in the export alone. if crate::apple_double::companion(serial) { - return Err(Status::Access); + return self.companion_link(serial, parent, name); } let checked = self.checked(name, true)?; let published = self.mutate( diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index dc14f9e933..38f9203130 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1244,3 +1244,109 @@ fn an_eviction_victim_that_cannot_be_written_out_does_not_fail_the_writer() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_hard_link_keeps_the_companion_under_its_other_names() { + let base = temp("hard-link"); + 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("/"); + // What `cp` leaves: the data file and its attributes alongside. + let a = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&a.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._a", 0o644).unwrap(); + let whole = image([0x61; 32], &[(b"user.kept", pattern(11, 64))]); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions, 1); + + // `ln a b`, and the client drops the `._` name of the old name it no + // longer uses: the attributes belong to the inode `b` still names, so the + // companion stays. + c.link(&a.handle, &root, b"b").unwrap(); + let (shared, attr) = c.lookup(&root, b"._b").unwrap(); + assert_eq!( + shared, ad.handle, + "the linked name reads the same companion" + ); + assert_eq!(attr.size as usize, whole.len()); + c.remove(&root, b"._a").unwrap(); + assert_eq!(server.held().companions, 1); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole, "attributes kept"); + + // `rm a`: one name of the inode goes, the companion stays with `b`. + c.remove(&root, b"a").unwrap(); + assert_eq!(server.held().companions, 1); + let (still, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(still, ad.handle); + assert_eq!(c.read_all(&still, 64 * 1024), whole); + + // The inode's last name takes it with it. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_linked_companion_name_is_another_name_of_the_same_companion() { + let base = temp("companion-link"); + 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 a = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&a.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._a", 0o644).unwrap(); + let whole = image([0x62; 32], &[(b"user.kept", pattern(12, 80))]); + c.write(&ad.handle, 0, &whole).unwrap(); + + // What a client that carries the attributes to the new name does: the + // main file first, then its companion, one companion behind both names. + c.link(&a.handle, &root, b"b").unwrap(); + let linked = c.link(&ad.handle, &root, b"._b").unwrap(); + assert_eq!(linked.fileid, ad.attr.fileid); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions, 1); + // A name already held is not linked again, and a companion is never + // linked onto a name of the Workspace. + assert_eq!(c.link(&ad.handle, &root, b"._b").map(|_| ()), Err(17)); + assert_eq!(c.link(&ad.handle, &root, b"plain").map(|_| ()), Err(13)); + + // The client drops the old name: the companion keeps the new one and its + // bytes, and reads through the inode as well. + c.remove(&root, b"._a").unwrap(); + assert_eq!(server.held().companions, 1); + let (kept, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(kept, ad.handle); + assert_eq!(c.read_all(&kept, 64 * 1024), whole); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + + // An inode with one name has only one `._` name: removing it is the client + // clearing its attributes, which takes the companion. + let alone = c.touch(&root, b"alone", 0o644).unwrap(); + c.write(&alone.handle, 0, b"data").unwrap(); + let one = c.touch(&root, b"._alone", 0o644).unwrap(); + c.write(&one.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions, 2); + c.remove(&root, b"._alone").unwrap(); + assert_eq!(server.held().companions, 1); + assert_eq!(c.getattr(&one.handle), Err(STALE)); + assert_eq!(c.lookup(&root, b"._alone").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From c96af5b19ffad8e830151b1eece26faf05914658 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:06:24 +0000 Subject: [PATCH 27/34] fix(nfs): report companions no name reaches when the export releases (lp73) macOS 27.2, build 525fcfb41: in one run of 600 files carrying ~100 KiB of attributes each, the first 507 in write order read back with no attributes at all while the export still held all 652 companions, 326 bodies stayed on disk, and two re-runs of the same recipe plus two controls were 100% correct. Nothing in the export's own counts had moved, so the loss was not an eviction: either those companions were still held but no name reached them, or the client never got them back for a reason of its own. The static review found no path that removes a companion's name keys and keeps the companion - every one of them takes the companion with it, or leaves it reachable through its inode - so the run could not be reproduced from the code, and a loss with the index intact has to be told apart from one where the index lost the entry. `Companions::unreachable` counts the companions neither their recorded name nor another name of their inode reaches, and the export's release line now carries it: `held= slotted= decoded= resident_bytes= unreachable=`. It runs once, over the companions held at release, so it costs nothing on the serving path. A non-zero count beside a client that lost attributes says the name, not the body, was lost; a zero says the body itself was gone. Documented with the release line in the nfs route's AppleDouble section. Review: macOS re-test, finding 2 (507 of 600 attributes lost, not reproduced). Tests: none new. The counter can only be non-zero through the very defect it reports, so an ordinary test would assert zero; the release path is covered by every test that stops an export (the line is printed with `held=`). Production LOC: 164884 -> 164900 (delta +16) 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 45d090391 (164884) and of the staged tree (164900). Engine +16: the counting method and the release line's field. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 8 ++++++ engine/crates/layerfs-nfs/src/apple_double.rs | 28 +++++++++++++++++-- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index cee540a021..c4acda2385 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -259,6 +259,14 @@ 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`. +Release logs one line per export that still holds companions: +`held= slotted= decoded= resident_bytes= unreachable=`. `unreachable` counts the +companions no name reaches - neither the name a companion records nor another +name of its inode finds it - which is the shape a lost attribute takes when the +body is still held but a client cannot ask for it; a zero beside a client that +lost attributes says the loss was a missing companion rather than a lost name. +It is counted once, at release, over the companions held. + ## Mount (`mount.rs`, daemon `export.rs`) ```text diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 77cf8988d3..4f415c5dcc 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -480,6 +480,27 @@ impl Companions { || serial.is_some_and(|serial| self.slots.contains(&serial)) || self.slots.len() < self.held_limit } + /// The companions no name of the export reaches: neither the name it + /// records nor another name of its inode finds it. Such a companion holds + /// its body with no way for a client to ask for it, which is one of the two + /// shapes a lost attribute takes (the other is no companion at all). It is + /// counted once, when the export releases, so a file of reports from a real + /// client can say which shape a loss had. + fn unreachable(&self) -> usize { + self.files + .iter() + .filter(|(serial, file)| { + self.names.get(&file.named) != Some(serial) + && !file + .also + .iter() + .any(|also| self.names.get(also) == Some(serial)) + && file + .inode + .is_none_or(|inode| self.inodes.get(&inode) != Some(serial)) + }) + .count() + } fn holding(&self) -> Holding { Holding { held: self.files.len(), @@ -1009,10 +1030,11 @@ impl Kernel { /// 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 (held, dir, unreachable) = { let mut companions = self.companions(); let dir = companions.spill_dir.take(); - (std::mem::take(&mut *companions), dir) + let unreachable = companions.unreachable(); + (std::mem::take(&mut *companions), dir, unreachable) }; if let Some(dir) = dir { drop(fs::remove_dir_all(dir)); @@ -1020,7 +1042,7 @@ impl Kernel { let holding = held.holding(); if holding.held > 0 { eprintln!( - "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={}", + "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={} unreachable={unreachable}", self.mount(), holding.held, holding.slotted, From 386c5b0e210124d61a912921b6a5812baafb5467 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:15:55 +0000 Subject: [PATCH 28/34] fix(nfs): hold the index slot a commit is still going to take (lp73) The `HELD` bound was decided in one place, but on the path that needs I/O between the decision and the commit - a WRITE, SETATTR or RENAME whose body spills and is then edited on its file - `admits` passed before `spill_gated` and the file write, and `record_edit`/`classify` took the slot afterwards without asking again. Two concurrent calls could both be told the last slot was free and both take one, so `slots.len()` could exceed `held_limit` by as much as the number of edits in flight, which contradicts "the bound holds". `Companions::reserve` decides and holds in one step under the companion lock (`Slot::Taken`/`Held`/`Full`); reservations count against the bound in `admits`, and a create or reclaim cannot steal one. The disk-edit path and `rename_companion` reserve before their I/O and give the reservation back if the edit does not land (`unreserve`, `take_serial`, the failure paths of `apply_edit`/`record_edit`/`rename_companion`), so a reservation can neither be held for good nor outlive its companion. CREATE and the in-memory edit decide and take the slot under one lock and keep using `admits`. Review: finding P2-1 (the bound could be exceeded under concurrency), and the route document's claim that the bound holds is now true as written. Tests: new `the_slot_bound_holds_when_writes_claim_the_last_slot_together`. Eight companions holding whole images (no slot), one slot, a body budget that cannot hold the broken body, and one breaking WRITE from each over its own connection after a barrier: exactly one writer takes the slot, the other seven answer `NFS3ERR_NOSPC`, `slotted` is 1, and every companion still reads back as its image or that edit. Anti-proof: with `admits` back in place of `reserve` the test failed 23 of 40 runs with two or three writers succeeding (`[Ok(()), Err(28), Ok(()), ...]`); with the reservation it passed 40 of 40. Production LOC: 164900 -> 164930 (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 c96af5b19 (164900) and of the staged tree (164930). Engine +30: the reservation set, `Slot`, `reserve`/`unreserve`, the two decision sites and the three release paths. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 2 +- engine/crates/layerfs-nfs/src/apple_double.rs | 56 ++++++++++-- .../layerfs-nfs/src/apple_double/edit.rs | 10 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 86 +++++++++++++++++++ 4 files changed, 144 insertions(+), 10 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index c4acda2385..7ff0d60f03 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -177,7 +177,7 @@ the export. | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export) | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export). A call whose commit needs I/O in between (`Companions::reserve`) holds the slot from the decision, so the bound holds when calls race for the last one | [`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 of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost` | Spill the least recently touched bodies, decoded ones included, 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_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 4f415c5dcc..6e99d2fb3d 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -149,6 +149,18 @@ struct Orphan { main: Option, } +/// What [`Companions::reserve`] made of a call's claim on a slot of the index +/// bound. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(crate) enum Slot { + /// It took the slot, which it gives back if its commit does not land. + Taken, + /// It already held a slot (or a reservation for one): nothing was taken. + Held, + /// The bound has none. + Full, +} + /// What [`Companions::keep_decoded`] made of an edited body. pub(crate) enum Decoded { /// The companion holds the body's decoded form. @@ -184,6 +196,10 @@ pub(crate) struct Companions { /// takes no slot, whether it is decoded or kept as written bytes, so whole /// images add nothing to the walk. slots: HashSet, + /// The serials holding a slot for a commit that is still on its way, whose + /// I/O runs outside this lock. A reserved slot counts against the bound, so + /// two calls cannot both be told the bound has room for one. + reserved: HashSet, /// 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. @@ -204,6 +220,7 @@ impl Default for Companions { names: HashMap::new(), inodes: HashMap::new(), slots: HashSet::new(), + reserved: HashSet::new(), by_use: BTreeSet::new(), resident_bytes: 0, decoded: 0, @@ -414,6 +431,7 @@ impl Companions { } } fn take_serial(&mut self, serial: u64) -> Option { + self.reserved.remove(&serial); let file = self.detach(serial)?; self.unindex(serial, &file); match file.body { @@ -477,8 +495,29 @@ impl Companions { /// keeps it, and a body that takes no slot is always admitted. fn admits(&self, serial: Option, slotted: bool) -> bool { !slotted - || serial.is_some_and(|serial| self.slots.contains(&serial)) - || self.slots.len() < self.held_limit + || serial.is_some_and(|serial| { + self.slots.contains(&serial) || self.reserved.contains(&serial) + }) + || self.slots.len() + self.reserved.len() < self.held_limit + } + /// Decides whether `serial` may take a slot of the bound and holds it when + /// it may, in one step under this lock: a call that needs I/O before its + /// commit keeps the slot for the commit, so two calls cannot both be told + /// the bound has room for one. [`Slot::Held`] means it already has one + /// (or a reservation) and nothing was taken. + fn reserve(&mut self, serial: u64) -> Slot { + if self.slots.contains(&serial) || self.reserved.contains(&serial) { + return Slot::Held; + } + if self.slots.len() + self.reserved.len() >= self.held_limit { + return Slot::Full; + } + self.reserved.insert(serial); + Slot::Taken + } + /// Gives back a slot reserved for a commit that did not land. + fn unreserve(&mut self, serial: u64) { + self.reserved.remove(&serial); } /// The companions no name of the export reaches: neither the name it /// records nor another name of its inode finds it. Such a companion holds @@ -995,17 +1034,21 @@ impl Kernel { } // A companion moved onto an unknown main takes a slot; one already // holding a slot keeps it, and one that stays a whole image keeps its - // exemption. - if !self.companions().admits(Some(serial), to_main.is_none()) { + // exemption. The slot is held from here, so the commit below cannot + // find another call took the last one while this rename waited. + if to_main.is_none() && self.companions().reserve(serial) == Slot::Full { self.reclaim_orphans(); - if !self.companions().admits(Some(serial), to_main.is_none()) { + if self.companions().reserve(serial) == Slot::Full { return Err(Status::NoSpc); } } let mut replaced_path = None; { let mut companions = self.companions(); - let mut file = companions.detach(serial).ok_or(Status::Stale)?; + let Some(mut file) = companions.detach(serial) else { + companions.unreserve(serial); + return Err(Status::Stale); + }; companions.unindex(serial, &file); if let Some(replaced) = companions.resolve(&target, to_main) { if replaced != serial { @@ -1023,6 +1066,7 @@ impl Kernel { companions.classify(&mut file); companions.index(serial, &file); companions.attach(serial, file); + companions.unreserve(serial); } unlink_paths(replaced_path); Ok(()) diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 283ee6740e..eac3c6670e 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -16,7 +16,7 @@ //! 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, DECODED_ENTRY_BYTES, FILE_BYTES}; +use super::{edited_len, record, Body, Companions, Decoded, Slot, DECODED_ENTRY_BYTES, FILE_BYTES}; use crate::{ apple_double_spill::{ create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Edited, Room, @@ -226,8 +226,10 @@ impl Kernel { // its file, which needs no body budget. A body edited on its file is no // longer known to be a whole image, so it takes a slot of the index // bound: decide that before the file is written, and leave the body, - // its file and its name as they were when the bound has none. - if !self.companions().admits(Some(serial), true) { + // its file and its name as they were when the bound has none. The slot + // is held from the decision, not taken by the commit after the I/O, so + // another call cannot be told the same last slot is free. + if self.companions().reserve(serial) == Slot::Full { return Ok(Edited::NoSlot); } // A failed file operation leaves the length the companion had: the @@ -245,6 +247,7 @@ impl Kernel { }); if let Err(status) = written { self.restore_len(serial, before); + self.companions().unreserve(serial); return Err(status); } self.record_edit(serial, edit).map(Edited::Done) @@ -350,6 +353,7 @@ impl Kernel { touch(&mut file.metadata); let stat = Companions::stat(serial, &file); companions.attach(serial, file); + companions.unreserve(serial); Ok(stat) } /// Spills the least recently used bodies to disk (outside the companion diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 38f9203130..a74a3c94b5 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1350,3 +1350,89 @@ fn a_linked_companion_name_is_another_name_of_the_same_companion() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn the_slot_bound_holds_when_writes_claim_the_last_slot_together() { + const WRITERS: usize = 8; + let base = temp("slot-race"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // One slot, and a body budget smaller than the images below, so each + // breaking write spills its body and needs the slot after I/O. + rig.companions_held = 1; + rig.companion_resident_bytes = 1024; + rig.companion_spill_dir = Some(base.join("spill")); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let address = server.local_addr(); + let mut c = Client::connect(address, UID, GID); + let root = c.mnt("/"); + let mut images = Vec::new(); + for i in 0..WRITERS { + c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._m{i}").as_bytes(), 0o644).unwrap(); + // A whole image is 4,096 bytes however small its attributes are: it + // costs a few dozen bytes of the budget and is broken by one byte of + // its header, which leaves 4,096 bytes that cannot stay resident here. + let whole = image( + [i as u8 + 7; 32], + &[(b"user.value", pattern(70 + i as u32, 64))], + ); + assert_eq!(whole.len(), 4096); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + images.push((ad.handle.clone(), whole)); + } + assert_eq!(server.held().companions, WRITERS); + assert_eq!( + server.held().companions_slotted, + 0, + "a whole image takes no slot" + ); + + // Every companion is broken at once, each on its own connection: one slot + // is free, so exactly one may take it. A bound decided before the I/O and + // taken after it lets more than one through. + let barrier = std::sync::Arc::new(std::sync::Barrier::new(WRITERS + 1)); + let writers: Vec<_> = images + .iter() + .map(|(handle, _)| { + let (barrier, mut writer) = (barrier.clone(), Client::connect(address, UID, GID)); + let handle = handle.clone(); + std::thread::spawn(move || { + barrier.wait(); + writer.write(&handle, 0, b"X").map(|_| ()) + }) + }) + .collect(); + barrier.wait(); + let results: Vec> = writers + .into_iter() + .map(|writer| writer.join().unwrap()) + .collect(); + assert_eq!( + results.iter().filter(|result| result.is_ok()).count(), + 1, + "one slot, one writer: {results:?}" + ); + assert_eq!(server.held().companions_slotted, 1, "{results:?}"); + assert_eq!(server.held().companions, WRITERS); + // The refused ones kept their image, the taken one holds the edit. + let refused = results.iter().filter(|result| result.is_err()).count(); + assert_eq!(refused, WRITERS - 1); + for (handle, whole) in &images { + let bytes = c.read_all(handle, 64 * 1024); + let mut edited = whole.clone(); + edited[0] = b'X'; + assert!( + bytes == *whole || bytes == edited, + "every companion is its image or the edit" + ); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From 0b877168b20207756d27e2d0830c650db41d7e16 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:20:19 +0000 Subject: [PATCH 29/34] fix(nfs): reclaim a companion whose main directory is gone (lp73) Reclamation asks the engine about a candidate's main file before dropping it, and treated only "no such file" as dead. A main file whose directory the client had removed cannot answer "no such file": the engine has no such parent, so the lookup answers `NFS3ERR_STALE` (`NFS3ERR_NOTDIR` for a parent that is a file), and the candidate was kept for the export's life. Its slot stayed taken, every later CREATE at the bound repeated the same failing lookup, and the bound could stay full until release. `NFS3ERR_STALE` and `NFS3ERR_NOTDIR` now count as "the main file is not there either" and the candidate is reclaimed, which is what a removed parent means for its entries. Any other answer still leaves the companion alone, and the per-name engine lookup and the slot walk are unchanged. Review: finding P2-3 (a candidate whose main file's directory is gone is never reclaimed). Tests: new `a_companion_of_a_removed_directory_is_reclaimed`: one slot, a companion inside a directory whose main file `x` never existed (so `inode: None` and the slot), the client removes the directory (`rmdir` succeeds - nothing in it is visible to the engine), then a CREATE at the bound: its reclamation's lookup answers `NFS3ERR_STALE`, the companion is dropped and the CREATE lands with one companion and one slot. Anti-proof: with only `NFS3ERR_NOENT` counted the same CREATE answers `NFS3ERR_NOSPC` (`Err value: 28`) and the test fails there, so the lookup really answers a stale parent rather than a missing entry. Production LOC: 164930 -> 164932 (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 386c5b0e2 (164930) and of the staged tree (164932). Engine +2: the extra answers in the reclaim's match. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 6 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 16 +++++-- .../layerfs-nfs/tests/apple_double_decode.rs | 42 +++++++++++++++++++ 3 files changed, 59 insertions(+), 5 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 7ff0d60f03..624eebbfe2 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -227,8 +227,10 @@ concurrent GUARDED creates of one name yield one serial and one up, a client-side rename), so a candidate whose main inode the export does not know costs one read-only lookup of its main file in the engine, outside both locks: a file that is there binds the companion back to that inode and keeps -its attributes, only `NFS3ERR_NOENT` makes it an orphan, and a lookup that -cannot answer leaves it alone. The lookup that finds the main file took one +its attributes, `NFS3ERR_NOENT` - or `NFS3ERR_STALE`/`NFS3ERR_NOTDIR`, a main +file whose directory the engine no longer has, which cannot hold it either - +makes it an orphan, and a lookup that cannot answer any other way leaves it +alone. The lookup that finds the main file took one engine reference on it, and the export keeps exactly one per serial, so the visit registers the name it found the file under (`Kernel::entry_taken`, as `Kernel::lookup` does) before the companion is bound: that name is what makes diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 6e99d2fb3d..61bc0559f2 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -644,8 +644,10 @@ impl Kernel { /// export never looked up, a rename on the client side), so each one costs /// one read-only lookup of its main file in the engine, run outside both /// locks. A main file that is there binds the companion back to its inode, - /// which keeps its attributes; only a lookup that answers "no such file" - /// makes it an orphan, and one that cannot answer leaves it as it is. + /// which keeps its attributes; only a lookup that answers "no such file", + /// or whose parent directory the engine no longer has (so the file cannot + /// be there either), makes it an orphan, and one that cannot answer leaves + /// it as it is. /// /// A lookup that finds the main file took one engine reference on it, and /// the export keeps exactly one per serial: the visit is the entry's, so it @@ -670,7 +672,15 @@ impl Kernel { self.entry_taken(&stat, parent, &main); bound.push((orphan.serial, stat.serial)); } - Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), + // A parent directory the engine no longer has cannot + // hold the main file: the companion is an orphan as + // much as one whose file answers "no such file". + // A parent directory the engine no longer has cannot + // hold the main file: the companion is an orphan as + // much as one whose file answers "no such file". + Err(Status::NoEnt | Status::Stale | Status::NotDir) => { + dead.push((orphan.serial, orphan.inode)) + } Err(_) => {} } } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index a74a3c94b5..17323fd518 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1436,3 +1436,45 @@ fn the_slot_bound_holds_when_writes_claim_the_last_slot_together() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_companion_of_a_removed_directory_is_reclaimed() { + let base = temp("orphan-dir-gone"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // One slot, and both companions below take one: a whole image whose main + // file the export never saw stays as the client wrote it. + rig.companions_held = 1; + 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("/"); + c.mkdir(&root, b"gone", 0o755).unwrap(); + let gone = c.lookup(&root, b"gone").unwrap().0; + let held = c.touch(&gone, b"._x", 0o644).unwrap(); + c.write(&held.handle, 0, &pattern(80, 64)).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The client removes the directory: nothing the engine can see is in it, + // so the removal succeeds and leaves the companion it never listed behind, + // with a main file whose parent the engine no longer has. + c.rmdir(&root, b"gone").unwrap(); + assert_eq!(server.held().companions, 1); + + // The next CREATE at the bound reclaims first. The lookup of the vanished + // main file answers `NFS3ERR_STALE` (its parent is gone), which is as much + // "there is no such file" as `NFS3ERR_NOENT`, so the slot comes free and + // this CREATE lands instead of the bound staying full for good. + let made = c.touch(&root, b"._y", 0o644).unwrap(); + assert_eq!(server.held().companions, 1); + assert_eq!(server.held().companions_slotted, 1); + assert_eq!(c.getattr(&held.handle), Err(STALE)); + c.write(&made.handle, 0, &pattern(81, 32)).unwrap(); + assert_eq!(c.read_all(&made.handle, 4096), pattern(81, 32)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From d114c133dc2b52c876862272192d3c41cb7b9529 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:21:40 +0000 Subject: [PATCH 30/34] docs(nfs): state what one decoded body is charged, and the one-body overshoot (lp73) Two statements about the resident budget were wrong in the direction of claiming more than the code does. A decoded image's `Image::cost` against `RESIDENT_BYTES` is a cap on what one decoded body is charged, not a limit on what a companion may store: an image costing more than `DECODED_ENTRY_BYTES` is kept as the client wrote it and charged at its length. And an edit that leaves a body whole decodes it as it records it rather than asking for room first, so the pool may stand one decoded body over the budget until the next edit needs room - "never memory the budget cannot see" was too strong. The module documentation, the `DECODED_ENTRY_BYTES` item and the `RESIDENT_BYTES` row of the nfs route now say that. The `DECODED_ENTRY_BYTES` value stays 128 KiB: with the images a macOS client lays out it is what keeps a many-attribute image from being charged a whole 4 KiB unit's worth of body for a few dozen bytes of attributes. Review: finding P3-1 (the wording of the un-budgeted decode) and the D3 note on `DECODED_ENTRY_BYTES` (owner confirmation is asked for in the pull request). Tests: none (documentation only). `cargo test -p layerfs-nfs`: 73 passed, 0 failed (raw sum 74 with the child-process rerun). Production LOC: 164932 -> 164932 (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 0b877168b (164932) and of the staged tree (164932). Engine 0: documentation comments only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 4 ++-- engine/crates/layerfs-nfs/src/apple_double.rs | 16 ++++++++++------ 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 624eebbfe2..bb95925ee9 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -179,8 +179,8 @@ the export. | --- | --- | --- | --- | | `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export). A call whose commit needs I/O in between (`Companions::reserve`) holds the slot from the decision, so the bound holds when calls race for the last one | [`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 of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost` | Spill the least recently touched bodies, decoded ones included, 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_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost`; an edit that leaves a body whole decodes it as it records it, so the count may stand one decoded body over until the next edit needs room | Spill the least recently touched bodies, decoded ones included, 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_ENTRY_BYTES` | 128 KiB counted for one decoded companion: a cap on what one decoded body is charged, not on what a companion may store | A whole image costing more keeps its bytes as written, is charged at their length and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | A companion whose main inode the export knows belongs to that inode rather than to one name: hard links share it, main-file RENAME keeps it under the new name diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 61bc0559f2..db4110e3d3 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -41,9 +41,11 @@ //! not holding a whole image, each companion at most [`FILE_BYTES`]). Bodies up //! to [`RESIDENT_BYTES`] in all stay in memory, 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; when a write or resize crosses that -//! budget, the least recently touched bodies are spilled to the export's own -//! scratch directory (see [`crate::apple_double_spill`]). Removing +//! memory the budget sees. An edit that leaves a body whole decodes it as it +//! records it rather than asking for room first, so the pool may stand one +//! decoded body over until the next write or resize needs room; that one then +//! spills the least recently touched bodies, decoded ones included, to the +//! export's own scratch directory (see [`crate::apple_double_spill`]). Removing //! or replacing a main file drops its paired `._` companion, or only that //! name when the companion is its inode's, which goes with the inode's last //! name. When [`HELD`] is reached, orphan companions whose main inode or main @@ -81,9 +83,11 @@ pub const FILE_BYTES: u64 = 1 << 20; /// Companion body bytes kept resident in memory before spilling to disk: a /// body kept as written counts its length, a decoded one [`Image::cost`]. pub const RESIDENT_BYTES: usize = 32 << 20; -/// 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. +/// Most bytes counted for one decoded companion, [`Image::cost`]: a cap on +/// what one decoded body is charged to [`RESIDENT_BYTES`], not on what a +/// companion may store. A whole image costing more keeps its bytes as written +/// and is charged at their length, so one companion cannot take the whole +/// budget. pub const DECODED_ENTRY_BYTES: usize = 128 << 10; /// A name in one directory: (directory serial, name bytes). From 54b9c1b6c6fc324cebeebbbff6cc730b6725ae16 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 15 Nov 2026 03:05:56 +0000 Subject: [PATCH 31/34] fix(nfs): let any name of a companion keep it out of reclamation (lp73) A companion can hold several `._` names of its inode (a LINK of a companion name adds one), but reclamation's candidate test read only the name a companion records. A companion the client never paired with a main inode (`inode: None`) that was then linked under a second name was therefore proposed as an orphan on the strength of the first name alone: the export looked up that name's main file, answered "no such file", and dropped a companion that its other name - whose main file the export does know - still reached. One linked name lost the attributes of the other. `orphans()` now walks every name a companion holds: one whose main file a name of the index holds keeps the companion, and only a companion none of whose names the index knows becomes a candidate, for the lookup of the first such name. The slot walk, the engine lookup and the decision that follows are unchanged. Tests: new `a_companion_reached_by_one_of_its_names_is_not_an_orphan`: one slot, a companion created in a directory for a main file that does not exist (`inode: None`), LINKed under a second `._` name, then the main file of that second name created; a CREATE at the bound reclaims, finds the companion reachable through the linked name and leaves it, so the CREATE is refused and the companion still reads back. Anti-proof: with the recorded name alone the same CREATE lands (`left: Ok(()), right: Err(28)`) because the live companion was reclaimed. `cargo test -p layerfs-nfs`: 74 passed, 0 failed (raw sum 75 with the child-process rerun). Production LOC: 164932 -> 164941 (delta +9) 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 d114c133d (164932) and of the staged tree (164941). Engine +9: the loop over a companion's names in `orphans`. 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 | 23 +++++++--- .../layerfs-nfs/tests/apple_double_decode.rs | 44 +++++++++++++++++++ 3 files changed, 63 insertions(+), 7 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index bb95925ee9..f42c23cc0a 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -226,7 +226,8 @@ concurrent GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. The name index is lossy (its own bound, a name never looked up, a client-side rename), so a candidate whose main inode the export does not know costs one read-only lookup of its main file in the engine, outside both -locks: a file that is there binds the companion back to that inode and keeps +locks - and a companion it holds several names of is reached by any of them, so +one whose name the index holds is no candidate at all: a file that is there binds the companion back to that inode and keeps its attributes, `NFS3ERR_NOENT` - or `NFS3ERR_STALE`/`NFS3ERR_NOTDIR`, a main file whose directory the engine no longer has, which cannot hold it either - makes it an orphan, and a lookup that cannot answer any other way leaves it diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index db4110e3d3..9a0a6a10bb 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -625,12 +625,23 @@ impl Kernel { main: None, }); } - let main = file.named.1.strip_prefix(b"._")?; - let main = (file.named.0, main.to_vec()); - // A name the index does hold reaches the companion; one it does - // not hold only makes it a candidate, since that index is - // lossy. - (!table.by_name.contains_key(&main)).then_some(Orphan { + // A name the index does hold reaches the companion; one it + // does not hold only makes it a candidate, since that index is + // lossy. Any of the names it holds reaches it, so one whose + // main file the export knows keeps it, and the first name whose + // main it does not know is the one the lookup asks about. + let mut candidate = None; + for named in std::iter::once(&file.named).chain(&file.also) { + let Some(main) = named.1.strip_prefix(b"._") else { + continue; + }; + let main = (named.0, main.to_vec()); + if table.by_name.contains_key(&main) { + return None; + } + candidate.get_or_insert(main); + } + candidate.map(|main| Orphan { serial: *serial, inode: None, main: Some(main), diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 17323fd518..9d54b4a148 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1478,3 +1478,47 @@ fn a_companion_of_a_removed_directory_is_reclaimed() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_companion_reached_by_one_of_its_names_is_not_an_orphan() { + let base = temp("orphan-alias"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 1; + 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("/"); + c.mkdir(&root, b"d", 0o755).unwrap(); + let d = c.lookup(&root, b"d").unwrap().0; + // Nothing names `ghost`, so this companion starts with no main inode and + // takes the one slot. + let ghost = c.touch(&d, b"._ghost", 0o644).unwrap(); + let body = pattern(82, 64); + c.write(&ghost.handle, 0, &body).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The client links the companion name, then creates the main file of the + // linked name: one of the companion's names now has a main file the export + // knows. + c.link(&ghost.handle, &d, b"._kept").unwrap(); + c.touch(&d, b"kept", 0o644).unwrap(); + assert_eq!(c.read_all(&ghost.handle, 4096), body); + + // A CREATE at the bound reclaims first. The companion is reached by + // `._kept`, whose main file the export knows, so it is no orphan: nothing + // is dropped and the CREATE is refused. + c.touch(&root, b"y", 0o644).unwrap(); + assert_eq!(c.touch(&root, b"._y", 0o644).map(|_| ()), Err(NOSPC)); + assert_eq!(server.held().companions, 1); + assert_eq!(c.read_all(&ghost.handle, 4096), body); + let (kept, attr) = c.lookup(&d, b"._kept").unwrap(); + assert_eq!(kept, ghost.handle); + assert_eq!(attr.size as usize, body.len()); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From 70c55da33328e21cd5af9f9631bfa049b5ca6453 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 15 Nov 2026 06:39:57 +0000 Subject: [PATCH 32/34] fix(nfs): trace the AppleDouble names one client asks about (lp73) A macOS client that cannot read a companion's attributes looks the same from the export whatever happened: a name it never asked for, a name the export's index could not resolve, and an answer its own caches then dropped all leave no trace behind. A run of the real client is the only way to tell them apart, so this adds an opt-in trace of exactly those requests. `LAYERFS_NFS_TRACE=1` (read once per process, off unless it is exactly `1`) prints one line per request that names an AppleDouble companion - the `._` names themselves and the main file names of the inodes that hold one - to the daemon's standard error: layerfs-nfs trace: op=LOOKUP dir=6 name="._b" main=Some(9) route=inode companion=Some(4611686018427387904) status=Ok `main` is the main inode the export's name index gave the name (or `None`), and `route` says which part of the companion index answered - the companion's own name key, the main inode, or neither - so a name no companion answers is distinguishable from one whose main file the index forgot. A CREATE that finds the companion already held reports whether it would truncate it, a SETATTR of a `._` file is traced by handle with its size, `BIND` reports a main name the kernel table re-attributed to an inode with a companion (`alias` while the inode keeps several names, `unbound` when the one it held is all it has), `UNPAIR` reports a main name whose paired `._` name the export dropped, and `RENAME`/`LINK`/`REMOVE`/`CREATE` report the companion they decided. Nothing else changes: no state is touched, and every hook costs one `OnceLock` load while the trace is off. Tests: no new test - the trace changes no behaviour and the hooks are on paths `cargo test -p layerfs-nfs` (74 passed, 0 failed, raw sum 75) already drives; checked by hand against a LINK'd companion's `._` names, where the lines above are the actual output. `lf-ci.sh` fast: 2017 passed, 0 failed. clippy -p layerfs-nfs --all-targets: no warning. Production LOC: 164941 -> 165152 (delta +211) 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 the first parent 54b9c1b6c (164941) and on the staged tree (165152). Engine +211: `trace.rs` and its hooks in `apple_double.rs`, `edit.rs`, `kernel.rs` and `change.rs`. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 18 ++ engine/crates/layerfs-nfs/src/apple_double.rs | 163 ++++++++++++++++-- .../layerfs-nfs/src/apple_double/edit.rs | 3 + engine/crates/layerfs-nfs/src/change.rs | 4 + engine/crates/layerfs-nfs/src/kernel.rs | 13 ++ engine/crates/layerfs-nfs/src/lib.rs | 1 + engine/crates/layerfs-nfs/src/trace.rs | 119 +++++++++++++ 7 files changed, 302 insertions(+), 19 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/trace.rs diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index f42c23cc0a..79c3a43a09 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -270,6 +270,24 @@ body is still held but a client cannot ask for it; a zero beside a client that lost attributes says the loss was a missing companion rather than a lost name. It is counted once, at release, over the companions held. +The requests one real client makes can be read from an optional trace +([`trace.rs`](../../../../engine/crates/layerfs-nfs/src/trace.rs)): with +`LAYERFS_NFS_TRACE=1` the export prints, to the daemon's standard error, one +line for each request that names an AppleDouble companion - the `._` names +themselves and the main file names of the inodes that hold one - carrying the +directory serial, the name, the main inode the export's name index gave the +name, which part of the companion index answered it (`route=name` for the +companion's own name key, `route=inode` for the main inode, `route=none` when +neither did), the companion serial a reply carries as its fileid, and the +status the client is answered. A CREATE that finds the companion already held +says whether it would truncate it (`existing-truncate`), a SETATTR of a `._` +file is traced by handle, `BIND` shows a main name the kernel table +re-attributed to an inode that has a companion (`alias` while that inode keeps +several names, `unbound` when the one it held is all it has), and `UNPAIR` +shows a main name whose paired `._` name the export dropped. It is off unless +the variable is exactly `1`, is read once per process, and changes no state; +the lines are written under the lock the request already holds. + ## Mount (`mount.rs`, daemon `export.rs`) ```text diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 9a0a6a10bb..f8cc7ab090 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -57,6 +57,7 @@ use crate::{ attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, + trace::{self, Route as Trace}, }; use layerfs_content::{ filesystem::{attributes::PortableMetadata, PathName}, @@ -349,13 +350,20 @@ impl Companions { /// held under that name, unless it belongs to another inode than `main`, /// else the one its main inode already has. fn resolve(&self, named: &Named, main: Option) -> Option { + self.resolve_route(named, main).0 + } + /// [`Self::resolve`], and which part of the index answered, for the trace. + fn resolve_route(&self, named: &Named, main: Option) -> (Option, Trace) { if let Some(&serial) = self.names.get(named) { let inode = self.files.get(&serial).and_then(|file| file.inode); if inode.is_none() || main.is_none() || inode == main { - return Some(serial); + return (Some(serial), Trace::Name); } } - main.and_then(|main| self.inodes.get(&main).copied()) + match main.and_then(|main| self.inodes.get(&main).copied()) { + Some(serial) => (Some(serial), Trace::Inode), + None => (None, Trace::None), + } } /// Replaces `serial`'s body by the decoded form of `bytes`, the caller's /// edited body of `len` bytes, while the resident budget takes it and the @@ -553,6 +561,16 @@ impl Companions { } } } +/// How a CREATE that found the companion already held is traced: an UNCHECKED +/// create with an explicit size truncates the body every name of the inode +/// shares, and a GUARDED or EXCLUSIVE one is answered `NFS3ERR_EXIST`. +fn opening(how: &How) -> &'static str { + match how { + How::Unchecked(sattr) if sattr.size.is_some() => "existing-truncate", + How::Unchecked(_) | How::Guarded(_) => "existing", + How::Exclusive(_) => "existing-exclusive", + } +} /// 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. @@ -748,9 +766,23 @@ impl Kernel { pub(crate) fn companion_named(&self, parent: u64, name: &[u8]) -> Option { let main = self.main_of(parent, name); let mut companions = self.companions(); - let serial = companions.resolve(&(parent, name.to_vec()), main)?; - let stat = Companions::stat(serial, companions.files.get(&serial)?); - companions.use_serial(serial); + let (serial, route) = companions.resolve_route(&(parent, name.to_vec()), main); + if crate::names::apple_double(name) { + trace::companion( + "LOOKUP", + parent, + name, + main, + route, + serial, + match serial { + Some(_) => "Ok", + None => "NoEnt", + }, + ); + } + 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, @@ -796,7 +828,9 @@ impl Kernel { let named = (parent, name.to_vec()); let mut main = self.main_of(parent, name); let mut companions = self.companions(); - if let Some(serial) = companions.resolve(&named, main) { + let (held, route) = companions.resolve_route(&named, main); + if let Some(serial) = held { + trace::companion("CREATE", parent, name, main, route, held, opening(&how)); return self.companion_open(serial, how, directory, companions, tickets); } // At the index bound, reclaim the companions no name reaches any more @@ -810,7 +844,9 @@ impl Kernel { // lock this call now holds without releasing it again. main = self.main_of(parent, name); companions = self.companions(); - if let Some(serial) = companions.resolve(&named, main) { + let (held, route) = companions.resolve_route(&named, main); + if let Some(serial) = held { + trace::companion("CREATE", parent, name, main, route, held, opening(&how)); return self.companion_open(serial, how, directory, companions, tickets); } } @@ -824,6 +860,7 @@ impl Kernel { if log { companions.last_refusal_log = Some(Instant::now()); } + trace::companion("CREATE", parent, name, main, Trace::None, None, "NoSpc"); drop(companions); let refused = self.names_refused.fetch_add(1, Ordering::Relaxed) + 1; if let Some(namespace) = namespace { @@ -855,6 +892,15 @@ impl Kernel { editing: Arc::new(Mutex::new(())), }; let stat = Companions::stat(serial, &file); + trace::companion( + "CREATE", + parent, + name, + main, + Trace::None, + Some(serial), + "Ok", + ); companions.index(serial, &file); companions.attach(serial, file); drop(companions); @@ -875,17 +921,38 @@ impl Kernel { pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { let named = (parent, name.to_vec()); let main = self.main_of(parent, name); - let (serial, inode, one_name) = { + let resolved = { let companions = self.companions(); - let serial = companions.resolve(&named, main)?; - let file = companions.files.get(&serial)?; - ( - serial, - file.inode, - !companions.holds_another(serial, &named), - ) + let (serial, route) = companions.resolve_route(&named, main); + serial.and_then(|serial| { + let file = companions.files.get(&serial)?; + Some(( + serial, + route, + file.inode, + !companions.holds_another(serial, &named), + )) + }) + }; + let Some((serial, route, inode, one_name)) = resolved else { + if crate::names::apple_double(name) { + trace::companion("REMOVE", parent, name, main, Trace::None, None, "NoEnt"); + } + return None; }; let kept = !one_name || inode.is_some_and(|inode| self.knows_another_name(inode)); + trace::companion( + "REMOVE", + parent, + name, + main, + route, + Some(serial), + match kept { + true => "name-dropped", + false => "companion-dropped", + }, + ); let spilled = { let mut companions = self.companions(); if kept { @@ -927,11 +994,23 @@ impl Kernel { let Some(&serial) = companions.names.get(&named) else { return; }; - if companions + let of_inode = companions .files .get(&serial) - .is_some_and(|file| file.inode.is_some()) - { + .is_some_and(|file| file.inode.is_some()); + trace::companion( + "UNPAIR", + parent, + name, + companions.files.get(&serial).and_then(|file| file.inode), + Trace::Name, + Some(serial), + match of_inode { + true => "name-dropped", + false => "companion-dropped", + }, + ); + if of_inode { companions.drop_name(serial, &named); None } else { @@ -977,6 +1056,7 @@ impl Kernel { .resolve(&named, main) .is_some_and(|other| other != serial) { + trace::companion("LINK", parent, name, main, Trace::Name, None, "Exist"); return Err(Status::Exist); } let Some(mut file) = companions.detach(serial) else { @@ -985,6 +1065,7 @@ impl Kernel { file.also.push(named); file.used = companions.tick(); let stat = Companions::stat(serial, &file); + trace::companion("LINK", parent, name, main, Trace::None, Some(serial), "Ok"); companions.index(serial, &file); companions.attach(serial, file); Ok((stat, directory)) @@ -1008,7 +1089,20 @@ impl Kernel { if !crate::names::apple_double(new_name) || new_name.len() > 255 { return Some(Err(Status::Access)); } - Some(self.rename_companion(serial, (to, new_name.to_vec()), to_main)) + let renamed = self.rename_companion(serial, (to, new_name.to_vec()), to_main); + trace::companion( + "RENAME", + to, + new_name, + to_main, + Trace::None, + Some(serial), + match &renamed { + Ok(()) => "Ok", + Err(status) => trace::status(*status), + }, + ); + Some(renamed) } /// Moves `serial`'s companion to `target`, under `to_main`'s inode. /// @@ -1125,4 +1219,35 @@ impl Kernel { pub(crate) fn companions_held(&self) -> Holding { self.companions().holding() } + /// Traces a request about a main file (`op`, its directory and name) when + /// the export holds a companion for that inode: these are the requests + /// that make a `._` name resolvable (see [`crate::trace`]). + pub(crate) fn trace_main_file( + &self, + op: &str, + parent: u64, + name: &[u8], + inode: u64, + status: &str, + ) { + if !trace::enabled() { + return; + } + let companion = self.companions().inodes.get(&inode).copied(); + if companion.is_some() { + trace::main_file(op, parent, name, Some(inode), companion, status); + } + } + /// Traces a name the export's kernel table bound to `inode` (`alias`: kept + /// as another name of it) or dropped from it (`unbound`), when the inode + /// has a companion: a `._` name resolves through those names. + pub(crate) fn trace_bind(&self, parent: u64, name: &[u8], inode: u64, status: &str) { + if !trace::enabled() { + return; + } + let companion = self.companions().inodes.get(&inode).copied(); + if companion.is_some() { + trace::main_file("BIND", parent, name, Some(inode), companion, status); + } + } } diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index eac3c6670e..dc49f336a5 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -145,6 +145,9 @@ impl Kernel { if size > FILE_BYTES { return Err(Status::FBig); } + if crate::trace::enabled() { + crate::trace::handle("SETATTR", serial, &format!("size={size}")); + } self.edit_companion(serial, Edit::Size(size as usize))?; } let mut companions = self.companions(); diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 81ebb40345..14a59dc31c 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -500,6 +500,9 @@ impl Kernel { tickets, |_| Ok(MutationInput::Named(remove::unlink(parent, checked))), )?; + if let Some(detached) = &published.detached { + self.trace_main_file("REMOVE", parent, name, detached.serial, "Ok"); + } self.finish_unlink(parent, name, retire, published.detached); Ok(published.wcc[0].clone()) } @@ -660,6 +663,7 @@ impl Kernel { let stat = published.stat.ok_or(Status::ServerFault)?; // The engine took one more lookup reference; the export holds one. self.entry_taken(&stat, parent, name); + self.trace_main_file("LINK", parent, name, stat.serial, "Ok"); Ok((stat, published.wcc[0].clone())) } /// SETATTR. `guard` is the client's expected ctime (seconds, diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 3540cfefb3..b50c8f3498 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -460,6 +460,7 @@ impl Kernel { )?; // The deciding visit took one engine reference; keep exactly one. self.entry_taken(&stat, parent, name); + self.trace_main_file("LOOKUP", parent, name, stat.serial, "Ok"); Ok(stat) } /// A visit or mutation that decided `stat` as the entry `name` of @@ -498,6 +499,18 @@ impl Kernel { // that retiring the serial drops no other name. table.remember_alias(stat.serial, &old); } + // Held here: the table lock, and inside it the + // companion lock as everywhere else. Off unless the + // trace is on. + self.trace_bind( + parent, + name, + stat.serial, + match stat.namespace_refs <= 1 { + true => "unbound", + false => "alias", + }, + ); } } table.bind_name(named, stat.serial); diff --git a/engine/crates/layerfs-nfs/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index ca288a9089..a884bdc80d 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -32,6 +32,7 @@ mod nfs; pub mod refresh; pub mod rpc; mod server; +mod trace; pub mod xdr; pub use kernel::Released; diff --git a/engine/crates/layerfs-nfs/src/trace.rs b/engine/crates/layerfs-nfs/src/trace.rs new file mode 100644 index 0000000000..19cddd97e6 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/trace.rs @@ -0,0 +1,119 @@ +//! An optional trace of the AppleDouble names one client asks about. +//! +//! On a real client the export sees only the requests that arrive: whether a +//! companion a client cannot read was never asked for, was asked for under a +//! name the export cannot resolve, or was answered and then dropped by the +//! client, is invisible from the outside. This module prints one line for each +//! request that names an AppleDouble (`._`) companion - the `._` names +//! themselves and the main file names of the inodes that have one - with the +//! directory it named them in, the name, the companion the export resolved, +//! which part of its index found it (the companion's own name key or the main +//! inode) or that neither did, and the answer the client gets. A run of a real +//! client with this on is the only way to read its sequence; see +//! `docs/architecture/engine/kernel-routes/nfs.md`. +//! +//! `LAYERFS_NFS_TRACE=1` turns it on; anything else, and no variable at all, +//! leaves it off. It is read once per process and changes no state, so when it +//! is off every hook costs one `OnceLock` load. Lines go to the daemon's +//! standard error, like the release line, and are written under whatever lock +//! the request already holds. +use crate::attributes::Status; +use std::sync::OnceLock; + +static ENABLED: OnceLock = OnceLock::new(); + +/// Whether this process traces AppleDouble names. +pub fn enabled() -> bool { + *ENABLED.get_or_init(|| std::env::var("LAYERFS_NFS_TRACE").as_deref() == Ok("1")) +} + +/// Which part of the export's index found a companion for a `._` name. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum Route { + /// The companion's own name key (`Companions::names`). + Name, + /// The main inode the name's main file has (`Companions::inodes`). + Inode, + /// Neither: no companion answers that name. + None, +} +impl Route { + const fn named(self) -> &'static str { + match self { + Route::Name => "name", + Route::Inode => "inode", + Route::None => "none", + } + } +} + +/// How a status is traced: the RFC's own name for it (`Ok`, `NoEnt`, `Exist`, +/// ...), for the answers a companion request gives. +pub fn status(status: Status) -> &'static str { + match status { + Status::Ok => "Ok", + Status::NoEnt => "NoEnt", + Status::Exist => "Exist", + Status::Access => "Access", + Status::Stale => "Stale", + Status::NotDir => "NotDir", + Status::NoSpc => "NoSpc", + Status::Inval => "Inval", + Status::Perm => "Perm", + Status::Io => "Io", + Status::NotSync => "NotSync", + Status::FBig => "FBig", + _ => "other", + } +} + +/// One request about a `._` name: `main` is the main inode the export's name +/// index gave it (`None` when it does not know the main file), `found` the +/// companion it resolved, and `route` which key found it. +pub fn companion( + op: &str, + directory: u64, + name: &[u8], + main: Option, + route: Route, + found: Option, + status: &str, +) { + if !enabled() { + return; + } + eprintln!( + "layerfs-nfs trace: op={op} dir={directory} name={:?} main={main:?} route={} companion={found:?} status={status}", + String::from_utf8_lossy(name), + route.named() + ); +} + +/// One request about a companion by handle only, where the client named no +/// name: a SETATTR of a `._` file it already holds, which can truncate the +/// body shared by every name of the inode. +pub fn handle(op: &str, companion: u64, detail: &str) { + if !enabled() { + return; + } + eprintln!("layerfs-nfs trace: op={op} companion={companion} {detail}"); +} + +/// One request about a main file whose inode has a companion, which is where +/// the export learns (or forgets) the names a `._` name resolves through. +pub fn main_file( + op: &str, + directory: u64, + name: &[u8], + inode: Option, + companion: Option, + status: &str, +) { + if !enabled() { + return; + } + eprintln!( + "layerfs-nfs trace: op={op} dir={directory} name={:?} inode={inode:?} companion={companion:?} status={status}", + String::from_utf8_lossy(name) + ); +} From 6da07ef6eda3e5b78d45e0f2530e51a8af87837a Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 15 Nov 2026 07:43:40 +0000 Subject: [PATCH 33/34] fix(nfs): keep an inode's `._` name when its main name goes (lp73) `Kernel::companion_drop_for` dropped the `._` key when a main file name was removed, so `rm a` of a file `b` still named answered `._a` with NFS3ERR_NOENT although the inode and its companion were alive (a macOS 27.2 trace showed the shape three times in one matrix). A companion that belongs to an inode now keeps that `._` name until the inode's last name, which already takes the companion with every `._` name it holds (`companion_drop_inode` -> `take_serial` -> `unindex`); a companion no main inode owns goes as before. A new file under the freed name reaches the old companion nowhere: `Companions::resolve` takes a name key only for the inode its companion belongs to. `Holding` and `Released::companions_unreachable` carry the release count, so a status read reports the same number as the release line. Tests (tests/apple_double_decode.rs): the matrix's g2/g3/g5 orders (`ln`, `rm` before and after one read of the linked name), a new file under the removed name, and the inode's last name reclaiming the companion and every `._` name key, with `._a`/`._b` reading one whole image. The three order tests failed on the parent with `._a` = NFS3ERR_NOENT. Docs: nfs.md states the hard-link rule, `UNPAIR name-kept`, the native route's `env_clear` trace wrapper and the live `unreachable` count. Production LOC: 165152 -> 165155 (delta +3); scope: first-party product source under core|engine|control|api, tools/production_loc.py on the parent tree and the staged tree; reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 27 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 69 +++--- .../crates/layerfs-nfs/src/kernel/released.rs | 7 + engine/crates/layerfs-nfs/src/trace.rs | 5 + .../layerfs-nfs/tests/apple_double_decode.rs | 212 ++++++++++++++++++ 5 files changed, 292 insertions(+), 28 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 79c3a43a09..b7d76c09ed 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -185,7 +185,14 @@ the export. A companion whose main inode the export knows belongs to that inode rather than to one name: hard links share it, main-file RENAME keeps it under the new name and existing aliases, and only the inode's last name (or its silly rename) -drops it. It can hold several of the inode's `._` names at once: a LINK of a +drops it. A name of the inode that goes does not take its `._` name with it: +after `rm a` of a file that `b` still names, `._a` still answers the inode's +companion, because the `._` name key stays until the inode's last name (a +client whose `actimeo` expired may ask either name). A new file that takes the +freed name reaches the old companion nowhere: `Companions::resolve` takes a +name key only for the inode its companion belongs to, so `._a` answers that new +inode's companion, or `NFS3ERR_NOENT` while it has none. It can hold several of +the inode's `._` names at once: a LINK of a companion name (`._a` to `._b`, which a client that carries the attributes to a new name sends) adds one, answering `NFS3ERR_EXIST` for a name already held and `NFS3ERR_ACCES` for a name of the Workspace, and a REMOVE of one of those @@ -268,7 +275,10 @@ companions no name reaches - neither the name a companion records nor another name of its inode finds it - which is the shape a lost attribute takes when the body is still held but a client cannot ask for it; a zero beside a client that lost attributes says the loss was a missing companion rather than a lost name. -It is counted once, at release, over the companions held. +The same count is in the holdings a status read reports +(`Released::companions_unreachable`), so the two never disagree; it walks the +companion index, like the release line and the reclamation walk, and only those +diagnostics read it. The requests one real client makes can be read from an optional trace ([`trace.rs`](../../../../engine/crates/layerfs-nfs/src/trace.rs)): with @@ -284,10 +294,21 @@ says whether it would truncate it (`existing-truncate`), a SETATTR of a `._` file is traced by handle, `BIND` shows a main name the kernel table re-attributed to an inode that has a companion (`alias` while that inode keeps several names, `unbound` when the one it held is all it has), and `UNPAIR` -shows a main name whose paired `._` name the export dropped. It is off unless +shows what a main name that went left behind: `name-kept` when the companion +belongs to its inode and keeps the `._` name, `companion-dropped` when the +companion goes with it. It is off unless the variable is exactly `1`, is read once per process, and changes no state; the lines are written under the lock the request already holds. +On the `native` route the daemon is started with `env_clear` and an empty +environment (`control/crates/layerfs-sandbox-backend/src/local/create.rs`), so +it does not inherit `LAYERFS_NFS_TRACE=1` from the shell that created the +Sandbox: a trace run there needs `machine update native --daemon` pointed at a +wrapper that exports the variable and `exec`s the real daemon (measured on +macOS 27.2 for #636, where the plain variable gave 0 trace lines and the wrapper +55 and 77 on the two matrices). Other routes start the daemon through a worker +or container, where the environment is passed differently. + ## Mount (`mount.rs`, daemon `export.rs`) ```text diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index f8cc7ab090..2230d37f17 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -46,9 +46,11 @@ //! decoded body over until the next write or resize needs room; that one then //! spills the least recently touched bodies, decoded ones included, to the //! export's own scratch directory (see [`crate::apple_double_spill`]). Removing -//! or replacing a main file drops its paired `._` companion, or only that -//! name when the companion is its inode's, which goes with the inode's last -//! name. When [`HELD`] is reached, orphan companions whose main inode or main +//! or replacing a main file drops its paired `._` companion when no main +//! inode owns it; a companion that belongs to an inode goes with the inode, so +//! `._` still answers for that inode after the name went, and only the +//! inode's last name takes the companion and every `._` name it holds. When +//! [`HELD`] is reached, orphan companions whose main inode or main //! file the export no longer knows are reclaimed first, and only if [`HELD`] //! live companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. use crate::{ @@ -185,6 +187,9 @@ pub(crate) struct Holding { pub slotted: usize, pub resident_bytes: usize, pub decoded: usize, + /// The companions no name reaches, so that a status read and the release + /// line report the same number. + pub unreachable: usize, } /// The companions of one export. @@ -534,9 +539,12 @@ impl Companions { /// The companions no name of the export reaches: neither the name it /// records nor another name of its inode finds it. Such a companion holds /// its body with no way for a client to ask for it, which is one of the two - /// shapes a lost attribute takes (the other is no companion at all). It is - /// counted once, when the export releases, so a file of reports from a real - /// client can say which shape a loss had. + /// shapes a lost attribute takes (the other is no companion at all). A + /// companion reached only through its main inode - one whose `._` name the + /// client removed, or whose main file went under that name - is reachable, + /// which is why a name key kept for an inode's companion is not a leak. + /// Counted with the other holdings, by who reports them: the release line + /// says which shape a loss had, and a status read says so while serving. fn unreachable(&self) -> usize { self.files .iter() @@ -558,6 +566,7 @@ impl Companions { slotted: self.slots.len(), resident_bytes: self.resident_bytes, decoded: self.decoded, + unreachable: self.unreachable(), } } } @@ -974,13 +983,24 @@ impl Kernel { remembered + table.aliases.get(&inode).map_or(0, Vec::len) > 1 } /// The main file `name` in `parent` was removed, silly-renamed or replaced - /// by `RENAME`: drops the companion held under `._`, or only that - /// name when the companion belongs to an inode, which goes with the - /// inode's last name instead (see [`Kernel::companion_drop_inode`]). A - /// plain non-replacing `RENAME` of a main file only cleans the destination - /// name `to/new_name` (via `finish_unlink`) and leaves `from/name` alone so - /// a client that renames `a -> b` and then renames `._a -> ._b` can still - /// move the companion across. + /// by `RENAME`: drops the companion held under `._` when no main + /// inode owns it, and leaves an inode's companion to the inode - it goes + /// with the inode's last name instead (see + /// [`Kernel::companion_drop_inode`]), which is also where the `._` names it + /// held go (`Companions::unindex`). A plain non-replacing `RENAME` of a + /// main file only cleans the destination name `to/new_name` (via + /// `finish_unlink`) and leaves `from/name` alone so a client that renames + /// `a -> b` and then renames `._a -> ._b` can still move the companion + /// across. + /// + /// The `._` name stays after its main name for as long as the inode does, + /// because the inode's FinderInfo and attributes are the file's: `/rm a` + /// on a file `b` still names leaves `._a` answering the companion of the + /// inode, rather than reporting attributes that the file `b` still has as + /// gone. A new file under that name reaches the old companion nowhere: + /// [`Companions::resolve`] takes a name key only for the inode its + /// companion belongs to, so the answer falls back to that inode's + /// companion, which a new file does not have. pub(crate) fn companion_drop_for(&self, parent: u64, name: &[u8]) { if crate::names::apple_double(name) { return; @@ -1006,15 +1026,13 @@ impl Kernel { Trace::Name, Some(serial), match of_inode { - true => "name-dropped", + true => "name-kept", false => "companion-dropped", }, ); - if of_inode { - companions.drop_name(serial, &named); - None - } else { - companions.take_serial(serial) + match of_inode { + true => None, + false => companions.take_serial(serial), } }; unlink_paths(spilled); @@ -1193,24 +1211,25 @@ impl Kernel { /// 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, unreachable) = { + let (holding, dir) = { let mut companions = self.companions(); + let holding = companions.holding(); let dir = companions.spill_dir.take(); - let unreachable = companions.unreachable(); - (std::mem::take(&mut *companions), dir, unreachable) + drop(std::mem::take(&mut *companions)); + (holding, dir) }; if let Some(dir) = dir { drop(fs::remove_dir_all(dir)); } - let holding = held.holding(); if holding.held > 0 { eprintln!( - "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={} unreachable={unreachable}", + "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={} unreachable={}", self.mount(), holding.held, holding.slotted, holding.decoded, - holding.resident_bytes + holding.resident_bytes, + holding.unreachable ); } holding diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index 3fc13af3c0..51a4d08db5 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -44,6 +44,7 @@ impl Kernel { companion_bytes: companions.resident_bytes, companions_slotted: companions.slotted, companions_decoded: companions.decoded, + companions_unreachable: companions.unreachable, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -85,6 +86,12 @@ pub struct Released { pub companions_slotted: usize, /// Of the companions held, those kept decoded. pub companions_decoded: usize, + /// Of the companions held, those no name reaches: neither the name a + /// companion records nor another name of its inode finds it. It is what a + /// status read and the release line both report, so a client that lost + /// attributes can be told whether the export still held the body with no + /// way to ask for it. + pub companions_unreachable: 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/src/trace.rs b/engine/crates/layerfs-nfs/src/trace.rs index 19cddd97e6..c8759dcf1f 100644 --- a/engine/crates/layerfs-nfs/src/trace.rs +++ b/engine/crates/layerfs-nfs/src/trace.rs @@ -17,6 +17,11 @@ //! is off every hook costs one `OnceLock` load. Lines go to the daemon's //! standard error, like the release line, and are written under whatever lock //! the request already holds. +//! +//! A `native` Sandbox's daemon is spawned after `env_clear`, so it does not +//! inherit this variable from the shell that created the Sandbox; tracing one +//! means pointing the machine's daemon at a wrapper that exports it and +//! `exec`s the real daemon (see `docs/architecture/engine/kernel-routes/nfs.md`). use crate::attributes::Status; use std::sync::OnceLock; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 9d54b4a148..5d11c9b490 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1296,6 +1296,218 @@ fn a_hard_link_keeps_the_companion_under_its_other_names() { fs::remove_dir_all(base).unwrap(); } +/// `name` and its `._` companion holding a whole image, as `cp` leaves +/// them: the main file's handle, the companion's, and the bytes written. +fn pair(c: &mut Client, root: &[u8], name: &[u8], seed: u32) -> (Vec, Vec, Vec) { + let main = c.touch(root, name, 0o644).unwrap(); + c.write(&main.handle, 0, b"the data file").unwrap(); + let mut paired = b"._".to_vec(); + paired.extend_from_slice(name); + let ad = c.touch(root, &paired, 0o644).unwrap(); + let whole = image([seed as u8; 32], &[(b"user.kept", pattern(seed, 64))]); + c.write(&ad.handle, 0, &whole).unwrap(); + (main.handle, ad.handle, whole) +} + +#[test] +fn a_removed_name_still_reaches_the_companion_of_its_inode() { + let base = temp("removed-name"); + 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("/"); + // `cp a`, then `ln a b`: one inode behind two names, the attributes under + // `._a`. This is the matrix's g2 order: `ln`, `rm` of the original before + // the linked name was read once. + let (a, ad, whole) = pair(&mut c, &root, b"a", 13); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + assert_eq!(server.held().companions, 1, "b still names the inode"); + assert_eq!(c.lookup(&root, b"a").map(|_| ()), Err(NOENT)); + + // The name is gone, the inode is not: `._a` is still the attributes of the + // file `b` names. A client that still holds `._a`, or asks for it again + // once its `actimeo` expired, reads them there instead of finding nothing. + let (named, attr) = c.lookup(&root, b"._a").unwrap(); + assert_eq!( + named, ad, + "a name of the inode that is gone still answers its `._` name" + ); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&named, 64 * 1024), whole); + assert_eq!( + server.held().companions_unreachable, + 0, + "the name key reaches it" + ); + let (linked, attr) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(linked, ad, "the surviving name answers it too"); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&linked, 64 * 1024), whole); + assert_eq!(server.held().companions, 1); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions, 1, "the last name stays to the export"); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_name_the_link_read_before_its_removal_keeps_its_companion_name() { + let base = temp("removed-name-read"); + 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("/"); + // The matrix's g3 order: `ln`, one read of the linked name and of its `._` + // name, then `rm` of the original. + let (a, ad, whole) = pair(&mut c, &root, b"a", 14); + c.link(&a, &root, b"b").unwrap(); + let (read, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(read, ad, "the linked name reaches the inode's companion"); + assert_eq!(c.lookup(&root, b"b").unwrap().0, a); + c.remove(&root, b"a").unwrap(); + + // Every name of the inode keeps answering, the removed one included. + let (named, _) = c.lookup(&root, b"._a").unwrap(); + assert_eq!(named, ad); + assert_eq!(c.read_all(&named, 64 * 1024), whole); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_name_asked_right_after_its_removal_still_reaches_the_companion() { + let base = temp("removed-name-after"); + 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("/"); + // The matrix's g5 order: `ln`, `rm` of the original, the linked name read + // right after, and then the removed name's `._` name. + let (a, ad, whole) = pair(&mut c, &root, b"a", 15); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + let (linked, _) = c.lookup(&root, b"b").unwrap(); + assert_eq!(linked, a, "b is the inode's remaining name"); + let (named, _) = c.lookup(&root, b"._a").unwrap(); + assert_eq!(named, ad); + assert_eq!(c.read_all(&named, 64 * 1024), whole); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_new_file_under_a_removed_name_does_not_reach_the_old_companion() { + let base = temp("removed-name-reused"); + 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 (a, ad, whole) = pair(&mut c, &root, b"a", 16); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + + // Another inode takes the freed name. The `._a` name the old companion + // still holds is the one the inode that had it answers, not this file `a` + // is now: `Companions::resolve` takes a name key only for the inode the + // companion belongs to. + let fresh = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&fresh.handle, 0, b"the new data file").unwrap(); + assert_eq!( + c.lookup(&root, b"._a").map(|_| ()), + Err(NOENT), + "the new file `a` has no attributes yet" + ); + // The old attributes are still the file `b` names, and the old body is + // untouched by the file that took the name. + let (kept, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(kept, ad); + assert_eq!(c.read_all(&kept, 64 * 1024), whole); + + // A companion created under the name is the new inode's: it starts empty + // and never reads the old body. + let new_ad = c.touch(&root, b"._a", 0o644).unwrap(); + assert_ne!(new_ad.handle, ad, "another companion for another inode"); + assert_eq!(c.getattr(&new_ad.handle).unwrap().size, 0); + let fresh_whole = image([0x17; 32], &[(b"user.new", pattern(17, 32))]); + c.write(&new_ad.handle, 0, &fresh_whole).unwrap(); + assert_eq!(c.read_all(&new_ad.handle, 64 * 1024), fresh_whole); + assert_eq!(server.held().companions, 2); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad); + assert_eq!(c.read_all(&ad, 64 * 1024), whole); + + // The old inode's last name takes only the old companion and the `._a` + // name it held, so the new file's attributes stay. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 1, "only the new file's companion"); + assert_eq!(c.getattr(&ad), Err(STALE)); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + assert_eq!(c.lookup(&root, b"._a").unwrap().0, new_ad.handle); + assert_eq!(c.read_all(&new_ad.handle, 64 * 1024), fresh_whole); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn the_last_name_of_a_hard_link_reclaims_its_companion_and_every_name_key() { + let base = temp("removed-name-last"); + 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 (a, ad, whole) = pair(&mut c, &root, b"a", 18); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + assert_eq!(c.lookup(&root, b"._a").unwrap().0, ad); + assert_eq!(c.read_all(&ad, 64 * 1024), whole); + + // The inode's last name goes: the companion goes with it, and so does the + // `._a` name key it kept for the name that went first. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(server.held().companions_unreachable, 0); + assert_eq!(c.getattr(&ad), Err(STALE)); + assert_eq!(c.lookup(&root, b"._a").map(|_| ()), Err(NOENT)); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + assert_eq!( + (released.companions, released.companions_unreachable), + (0, 0) + ); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_linked_companion_name_is_another_name_of_the_same_companion() { let base = temp("companion-link"); From 46550ff30bf1e16ffe22d6ac4c70d7f1db8474a1 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:47:22 +0800 Subject: [PATCH 34/34] fix(nfs): mount macOS exports with nordirplus The macOS NFS client answers a `._` name that is absent from a directory's cached READDIRPLUS listing with "not found" without ever asking the server (the skipdu path in nfs_vnop_lookup), and this export serves AppleDouble companions without listing them, so a hard-linked file's extended attributes could read back empty. Turning READDIRPLUS off makes every `._` name arrive as a LOOKUP. Nothing else about the mount or the listing changes. Production LOC: 165155 -> 165155 (delta 0); core/engine/control/api production source only (api/crates/layerfs-*/src, api/python/src/layerfs, api JS packages), counted with tools/production_loc.py at the parent and the committed tree; comments, tests and docs excluded. --- docs/architecture/engine/kernel-routes/nfs.md | 6 +++++- engine/crates/layerfs-daemon/src/control/export.rs | 8 ++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index b7d76c09ed..5205d22d6a 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -328,10 +328,14 @@ or container, where the environment is passed differently. | 2 `DUMP`; 3 `UMNT`; 5 `EXPORT` | Empty list; success; one export with no groups | Client options are the daemon's `Mounter::host`. macOS: -`vers=3,tcp,port={port},mountport={port},locallocks,nfc,noatime,actimeo=60,rsize=262144,wsize=262144,soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse` +`vers=3,tcp,port={port},mountport={port},locallocks,nfc,noatime,actimeo=60,rsize=262144,wsize=262144,soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse,nordirplus` (`rsize`/`wsize` are `TRANSFER_WINDOW`); elsewhere `vers=3,proto=tcp,port={port},mountport={port},mountproto=tcp,nolock,actimeo=60` ([`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs)). +`nordirplus` turns READDIRPLUS off: a macOS client holding a directory's +complete READDIRPLUS listing answers a `._` name absent from it with ENOENT +and never asks the server, and this export serves AppleDouble companions +without listing them, so every `._` name has to arrive as a LOOKUP. An NFS ready receipt has `abi_major == 0` and its `mount_id` is the port. ## Application SQLite databases on the NFS route diff --git a/engine/crates/layerfs-daemon/src/control/export.rs b/engine/crates/layerfs-daemon/src/control/export.rs index 2128e08893..bffb08e420 100644 --- a/engine/crates/layerfs-daemon/src/control/export.rs +++ b/engine/crates/layerfs-daemon/src/control/export.rs @@ -97,14 +97,18 @@ impl Mounter { /// access time: this export keeps one timestamp and shows it as atime, /// mtime and ctime alike, and `layerfs-nfs` decodes and drops a SETATTR's /// access time, so the update would cost one SETATTR per file a read or a - /// scan touches and change nothing. + /// scan touches and change nothing. `nordirplus` turns READDIRPLUS off: + /// a client holding a directory's complete READDIRPLUS listing answers a + /// `._` name absent from it with "not found" and never asks the server, + /// and this export never lists the AppleDouble companions it serves, so + /// every `._` name has to arrive as a LOOKUP. pub fn host() -> Self { let helper = |words: &[&str]| Helper(words.iter().map(|w| (*w).to_owned()).collect()); if cfg!(target_os = "macos") { // `rsize`/`wsize` ask for the window FSINFO declares; the client // clamps to the smaller of the two. let options = format!( - "vers=3,tcp,port={{port}},mountport={{port}},locallocks,nfc,noatime,actimeo=60,rsize={WINDOW},wsize={WINDOW},soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse" + "vers=3,tcp,port={{port}},mountport={{port}},locallocks,nfc,noatime,actimeo=60,rsize={WINDOW},wsize={WINDOW},soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse,nordirplus" ); Self { mount: helper(&["/sbin/mount_nfs", "-o", &options, "127.0.0.1:/", "{dir}"]),