From 24fa1557d097fbb6b59dc71b03cfd43af14a3921 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 8 Nov 2026 20:26:54 +0800 Subject: [PATCH 01/16] fix(nfs): spill AppleDouble companion bodies to disk beyond resident budget (lp73) - Keep AppleDouble companion index entries in export memory (HELD = 65,536, FILE_BYTES = 1 MiB) and bound resident payload bytes at RESIDENT_BYTES (32 MiB); when a write or resize crosses the resident budget, spill least recently touched resident bodies to the export's scratch directory (/.appledouble//) and serve spilled reads/writes via pread/pwrite outside the companion lock, issuing 0 engine or SQLite owner jobs. - Drop the paired ._ companion (and unlink its spilled file) when a main file is removed, silly-renamed, or replaced by RENAME; when HELD is reached, reclaim orphan companions whose main file is absent from Table::by_name first and return NFS3ERR_ACCES only if all 65,536 slots belong to live files. - Clean any leftover companion spill directory on Attach/export start and remove the directory when the export stops. LayerFS production LOC: 143682 -> 144159 (delta +477) Production LOC: 143,682 -> 144,159 (delta +477) Scope: core 39,491 -> 39,491 (0), engine 66,277 -> 66,754 (+477), control 33,969 -> 33,969 (0), api 3,945 -> 3,945 (0); reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: python3 -B tools/production_loc.py (parent 716197c49 -> committed tree) --- docs/architecture/engine/kernel-routes/nfs.md | 27 +- .../layerfs-daemon/src/control/export.rs | 17 + engine/crates/layerfs-nfs/src/apple_double.rs | 630 +++++++++++++++--- engine/crates/layerfs-nfs/src/change.rs | 2 + engine/crates/layerfs-nfs/src/kernel.rs | 15 +- engine/crates/layerfs-nfs/src/server.rs | 32 +- engine/crates/layerfs-nfs/tests/daemon.rs | 11 + .../crates/layerfs-nfs/tests/support/rig.rs | 20 + engine/crates/layerfs-nfs/tests/write.rs | 234 +++++++ 9 files changed, 887 insertions(+), 101 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 7b64bf49ed..08f9d792d2 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -44,7 +44,7 @@ client mount it ([`export.rs`](../../../../engine/crates/layerfs-daemon/src/cont | Item | Meaning | Source | | --- | --- | --- | | `Server::start(listener, services, mount, config)` | 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`, `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.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.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 each file descriptor, 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) | @@ -180,8 +180,11 @@ Refresh after an install is covered in ```text CREATE "._name" (refuse_apple_double = true) - regular file --> Companions (export memory only) + regular file --> Companions (export index in memory; body resident or spilled) serial >= SERIALS = 1 << 62 + resident body <= RESIDENT_BYTES (32 MiB) in all; + older bodies spill to /.appledouble// + (pread/pwrite outside the companion lock) LOOKUP GETATTR ACCESS READ WRITE SETATTR COMMIT REMOVE, RENAME to another "._" name: served here READDIR: not listed; engine: never called @@ -190,15 +193,21 @@ Refresh after an install is covered in | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 4096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `FILE_BYTES` | 1 MiB per companion | WRITE `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `TOTAL_BYTES` | 64 MiB in all | WRITE `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 companion index entries | Reclaim orphan companions whose main file is not in `Table::by_name`; if still at the bound, CREATE answers `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 | 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), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | On NFSv3 the macOS client stores extended attributes and resource forks in -`._` files. Keeping them in export memory lets `cp`, `copyfile`, -`ditto` and `tar` succeed while nothing reaches the Workspace or a Commit. -Everything is dropped when the export is released. A name is AppleDouble when -it starts with `._` and has at least one more byte. +`._` files. Keeping their index in export memory and spilling excess +bodies to the export's scratch directory lets `cp`, `copyfile`, `ditto` and +`tar` succeed without losing companion bytes during the mount, while nothing +reaches the Workspace, SQLite overlay or a Commit. Removing, silly-renaming or +replacing a main file drops its paired `._` companion and unlinks any +spilled file at once. Companions remain mount-session state: releasing the +export removes the entire `/.appledouble/` directory +(and a fresh Attach cleans any leftover directory from a crashed daemon), so +remounts, daemon restarts and Commits do not retain them. A name is +AppleDouble when it starts with `._` and has at least one more byte. ## Mount diff --git a/engine/crates/layerfs-daemon/src/control/export.rs b/engine/crates/layerfs-daemon/src/control/export.rs index c92759b3b7..8c43bb7098 100644 --- a/engine/crates/layerfs-daemon/src/control/export.rs +++ b/engine/crates/layerfs-daemon/src/control/export.rs @@ -177,6 +177,12 @@ 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.config + .mounts + .join(".appledouble") + .join(token.namespace.to_string()) + } /// 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 @@ -485,6 +491,9 @@ impl Service { read_only: false, refuse_apple_double: config.refuse_apple_double, lookups_held: config.lookups_held, + companion_spill_dir: Some(serving.companion_spill_dir(token)), + companion_resident_bytes: layerfs_nfs::apple_double::RESIDENT_BYTES, + companions_held: layerfs_nfs::apple_double::HELD, }; let started = TcpListener::bind((config.listen, 0)).and_then(|listener| { Server::start( @@ -529,6 +538,9 @@ impl Service { Ran::Busy(detail) | Ran::Failed(detail) => { let released = server.stop(); drop(std::fs::remove_dir(&directory)); + drop(std::fs::remove_dir( + serving.config.mounts.join(".appledouble"), + )); return Err(self.unwind_export( workspace, mount, @@ -745,6 +757,11 @@ 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.config.mounts.join(".appledouble"), + )); + } 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/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 4f2e2eb4c8..b1a2978cb6 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 @@ -16,10 +16,16 @@ //! 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). +//! Every companion keeps its index entry in memory (at most [`HELD`] +//! companions, each of 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 (one file per companion serial, read and written with +//! `pread`/`pwrite` outside the companion lock). Removing or replacing a main +//! file drops its paired `._` companion and any spilled file with it; +//! when [`HELD`] is reached, orphan companions whose main file is no longer in +//! the export's name index are reclaimed first, and only if [`HELD`] live +//! companions still remain does `CREATE` answer `NFS3ERR_ACCES`. use crate::{ attributes::Status, change::{How, Sattr, Tickets, Wcc}, @@ -29,71 +35,181 @@ use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_le use layerfs_mount_ports::operations::write::Stamp; use layerfs_workspace::ViewStat; use std::{ - collections::HashMap, - sync::atomic::Ordering, + collections::{HashMap, HashSet}, + fs::{self, File, OpenOptions}, + io, + os::unix::fs::FileExt, + path::{Path, PathBuf}, + sync::{atomic::Ordering, Arc}, time::{SystemTime, UNIX_EPOCH}, }; /// 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. -pub const HELD: usize = 4096; +/// Companion index entries held at once. +pub const HELD: usize = 65_536; /// 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 spilling to disk. +pub const RESIDENT_BYTES: usize = 32 << 20; /// Mode of a companion created without one. const MODE: u32 = 0o644; +enum Body { + Resident(Vec), + Spilled(Arc), +} + struct Companion { named: (u64, Vec), - data: Vec, + len: usize, + body: Body, metadata: PortableMetadata, + used: u64, +} +impl Companion { + fn resident_len(&self) -> usize { + match &self.body { + Body::Resident(bytes) => bytes.len(), + Body::Spilled(_) => 0, + } + } } + /// The companions of one export. -#[derive(Default)] pub(crate) struct Companions { next: u64, + tick: u64, files: HashMap, names: HashMap<(u64, Vec), u64>, - bytes: usize, + resident_bytes: usize, + spill_dir: Option, + resident_budget: usize, + held_limit: usize, +} +impl Default for Companions { + fn default() -> Self { + Self { + next: 0, + tick: 0, + files: HashMap::new(), + names: HashMap::new(), + resident_bytes: 0, + spill_dir: None, + resident_budget: RESIDENT_BYTES, + held_limit: HELD, + } + } } impl Companions { pub(crate) fn len(&self) -> usize { self.files.len() } + pub(crate) fn spilled(&self) -> usize { + self.files + .values() + .filter(|file| matches!(file.body, Body::Spilled(_))) + .count() + } + 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 { serial, kind: InodeKind::RegularFile, metadata: file.metadata, namespace_refs: 1, - logical_len: file.data.len() as u64, + logical_len: file.len as u64, subdirs: 0, } } - fn drop_serial(&mut self, serial: u64) { - if let Some(file) = self.files.remove(&serial) { - self.names.remove(&file.named); - self.bytes -= file.data.len(); + fn spill_path(&self, serial: u64) -> Option { + self.spill_dir + .as_ref() + .map(|dir| dir.join(serial.to_string())) + } + fn take_serial(&mut self, serial: u64) -> Option { + let file = self.files.remove(&serial)?; + self.names.remove(&file.named); + self.resident_bytes -= file.resident_len(); + match file.body { + Body::Resident(_) => None, + Body::Spilled(_) => self.spill_path(serial), } } - /// 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); + 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) + } + /// Reclaims companions whose paired main file `(parent, name)` is not in + /// `live_names`. Returns any spilled file paths to unlink outside the lock. + fn reclaim_orphans(&mut self, live_names: &HashSet<(u64, Vec)>) -> Vec { + let orphans: Vec = self + .files + .iter() + .filter(|(_, file)| { + let (parent, ref name) = file.named; + name.strip_prefix(b"._") + .is_some_and(|main| !live_names.contains(&(parent, main.to_vec()))) + }) + .map(|(serial, _)| *serial) + .collect(); + orphans + .into_iter() + .filter_map(|serial| self.take_serial(serial)) + .collect() + } +} +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, + } +} +fn create_spilled(dir: &Path, serial: u64, bytes: &[u8], len: u64) -> Result, Status> { + fs::create_dir_all(dir).map_err(|e| io_status(&e))?; + let path = dir.join(serial.to_string()); + let file = OpenOptions::new() + .read(true) + .write(true) + .create(true) + .truncate(true) + .open(&path) + .map_err(|e| io_status(&e))?; + if !bytes.is_empty() { + if let Err(e) = file.write_all_at(bytes, 0) { + drop(file); + drop(fs::remove_file(&path)); + return Err(io_status(&e)); } - 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 { - return Err(Status::NoSpc); + } + if len > bytes.len() as u64 { + if let Err(e) = file.set_len(len) { + drop(file); + drop(fs::remove_file(&path)); + return Err(io_status(&e)); } - file.data.resize(new, 0); - self.bytes = self.bytes + new - old; - Ok(()) } + Ok(Arc::new(file)) } fn now() -> PortableMetadata { let elapsed = SystemTime::now() @@ -121,20 +237,132 @@ impl Kernel { .lock() .unwrap_or_else(|poison| poison.into_inner()) } + 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); + } + /// 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. + fn spill_for(&self, target: u64, need: usize) -> Result { + loop { + let (candidate, dir, bytes, used) = { + let companions = self.companions(); + if companions + .resident_bytes + .checked_add(need) + .is_some_and(|total| total <= companions.resident_budget) + { + return Ok(true); + } + let Some(dir) = companions.spill_dir.clone() else { + return Ok(false); + }; + let Some(victim) = companions.oldest_resident(Some(target)) else { + return Ok(false); + }; + let file = &companions.files[&victim]; + let Body::Resident(ref data) = file.body else { + continue; + }; + (victim, dir, data.clone(), file.used) + }; + let spilled = create_spilled(&dir, candidate, &bytes, bytes.len() as u64)?; + let mut unlink = None; + { + let mut companions = self.companions(); + match companions.files.get_mut(&candidate) { + Some(file) if file.used == used && matches!(file.body, Body::Resident(_)) => { + let old = file.resident_len(); + file.body = Body::Spilled(spilled); + companions.resident_bytes -= old; + } + _ => { + unlink = Some(dir.join(candidate.to_string())); + } + } + } + if let Some(path) = unlink { + drop(fs::remove_file(path)); + } + } + } + /// Transitions `serial` itself to a spilled file of length `new_len` + /// without holding the companion lock across disk I/O. + fn spill_self(&self, serial: u64, new_len: usize) -> Result, Status> { + let (dir, existing, old_len) = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + if let Body::Spilled(ref handle) = file.body { + return Ok(handle.clone()); + } + let dir = companions.spill_dir.clone().ok_or(Status::NoSpc)?; + let Body::Resident(ref data) = file.body else { + unreachable!() + }; + let copy = data.len().min(new_len); + (dir, data[..copy].to_vec(), file.len) + }; + let target_len = new_len.max(old_len) as u64; + let handle = create_spilled(&dir, serial, &existing, target_len)?; + let mut unlink = None; + let chosen = { + let mut companions = self.companions(); + match companions.files.get_mut(&serial) { + Some(file) => match &file.body { + Body::Resident(_) => { + let old_res = file.resident_len(); + file.body = Body::Spilled(handle.clone()); + if target_len as usize > file.len { + file.len = target_len as usize; + } + companions.resident_bytes -= old_res; + Ok(handle) + } + Body::Spilled(already) => { + unlink = Some(dir.join(serial.to_string())); + Ok(already.clone()) + } + }, + None => { + unlink = Some(dir.join(serial.to_string())); + Err(Status::Stale) + } + } + }; + if let Some(path) = unlink { + drop(fs::remove_file(path)); + } + chosen + } /// 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. 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 + let stat = companions .files .get(&serial) - .map(|file| Companions::stat(serial, file)) + .map(|file| Companions::stat(serial, file))?; + companions.use_serial(serial); + Some(stat) } /// CREATE of an AppleDouble name. pub(crate) fn companion_create( @@ -166,8 +394,23 @@ impl Kernel { if parent != self.root() && !self.table().parents.contains_key(&parent) { return Err(Status::NotDir); } + let at_limit = { + let companions = self.companions(); + companions.len() >= companions.held_limit + }; + let mut reclaimed = Vec::new(); + if at_limit { + let live: HashSet<(u64, Vec)> = self.table().by_name.keys().cloned().collect(); + let mut companions = self.companions(); + if companions.len() >= companions.held_limit { + reclaimed = companions.reclaim_orphans(&live); + } + } + for path in reclaimed { + drop(fs::remove_file(path)); + } let mut companions = self.companions(); - if companions.len() >= HELD { + if companions.len() >= companions.held_limit { drop(companions); self.names_refused.fetch_add(1, Ordering::Relaxed); return Err(Status::Access); @@ -180,14 +423,17 @@ impl Kernel { } let serial = SERIALS + companions.next; companions.next += 1; + let used = companions.tick(); let named = (parent, name.to_vec()); companions.names.insert(named.clone(), serial); companions.files.insert( serial, Companion { named, - data: Vec::new(), + len: 0, + body: Body::Resident(Vec::new()), metadata, + used, }, ); let file = &companions.files[&serial]; @@ -199,13 +445,41 @@ 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())).copied()?; - companions.drop_serial(serial); + companions.take_serial(serial) + }; + if let Some(path) = spilled { + drop(fs::remove_file(path)); } Some(self.directory_wcc(parent)) } + /// Drops the companion `._` paired with `name` in `parent`, if one + /// is held, when `name` itself is removed, silly-renamed or replaced by + /// `RENAME`. 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 spilled = { + let mut companions = self.companions(); + companions + .names + .get(&(parent, paired)) + .copied() + .and_then(|serial| companions.take_serial(serial)) + }; + if let Some(path) = spilled { + drop(fs::remove_file(path)); + } + } /// 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( @@ -215,21 +489,29 @@ 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); + 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)); + } + 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); + } + } + companions.names.remove(&(from, name.to_vec())); + companions.names.insert(target.clone(), serial); + let tick = companions.tick(); + if let Some(file) = companions.files.get_mut(&serial) { + file.named = target; + file.used = tick; } } - 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; + if let Some(path) = replaced_path { + drop(fs::remove_file(path)); } Some(Ok(())) } @@ -242,12 +524,32 @@ impl Kernel { count: u32, out: &mut Vec, ) -> Result { - let companions = self.companions(); - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let length = file.data.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]); + 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; + match &file.body { + Body::Resident(bytes) => { + out.extend_from_slice(&bytes[start..end]); + companions.use_serial(serial); + return Ok(end as u64 >= length); + } + Body::Spilled(handle) => { + let cloned = handle.clone(); + companions.use_serial(serial); + (cloned, length, start, end) + } + } + }; + let mut buf = vec![0u8; end - start]; + if !buf.is_empty() { + spilled + .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. @@ -257,21 +559,158 @@ 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)?; - let before = { + if end > FILE_BYTES { + return Err(Status::FBig); + } + let end_usize = end as usize; + let (before, spilled_handle, need_bytes) = { + let mut companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - Companions::stat(serial, file) + let before = Companions::stat(serial, file); + match &file.body { + Body::Spilled(handle) => (before, Some(handle.clone()), 0), + Body::Resident(bytes) => { + let add = end_usize.saturating_sub(bytes.len()); + if companions.resident_bytes + add <= companions.resident_budget { + let tick = companions.tick(); + if let Some(file) = companions.files.get_mut(&serial) { + if let Body::Resident(ref mut buf) = file.body { + if end_usize > buf.len() { + buf.resize(end_usize, 0); + } + buf[offset as usize..end_usize].copy_from_slice(data); + } + file.len = file.len.max(end_usize); + file.used = tick; + touch(&mut file.metadata); + } + companions.resident_bytes += add; + let after = Companions::stat(serial, &companions.files[&serial]); + return Ok((data.len() as u32, (Some(before), Some(after)))); + } + (before, None, add) + } + } }; - if end > before.logical_len { - companions.resize(serial, end)?; + if let Some(handle) = spilled_handle { + handle + .write_all_at(data, offset) + .map_err(|e| io_status(&e))?; + let mut companions = self.companions(); + let tick = companions.tick(); + let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; + file.len = file.len.max(end_usize); + file.used = tick; + touch(&mut file.metadata); + let after = Companions::stat(serial, file); + return Ok((data.len() as u32, (Some(before), Some(after)))); } + if self.spill_for(serial, need_bytes)? { + let mut companions = self.companions(); + let avail = companions + .resident_budget + .saturating_sub(companions.resident_bytes); + if let Some(file) = companions.files.get_mut(&serial) { + if let Body::Resident(ref mut buf) = file.body { + let add = end_usize.saturating_sub(buf.len()); + if add <= avail { + if end_usize > buf.len() { + buf.resize(end_usize, 0); + } + buf[offset as usize..end_usize].copy_from_slice(data); + file.len = file.len.max(end_usize); + touch(&mut file.metadata); + let after = Companions::stat(serial, file); + companions.resident_bytes += add; + companions.use_serial(serial); + return Ok((data.len() as u32, (Some(before), Some(after)))); + } + } + } + } + let handle = self.spill_self(serial, end_usize)?; + handle + .write_all_at(data, offset) + .map_err(|e| io_status(&e))?; + let mut companions = self.companions(); + let tick = companions.tick(); let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.data[offset as usize..end as usize].copy_from_slice(data); + file.len = file.len.max(end_usize); + file.used = tick; touch(&mut file.metadata); let after = Companions::stat(serial, file); Ok((data.len() as u32, (Some(before), Some(after)))) } + /// Resizes `serial` to `size` for SETATTR / UNCHECKED CREATE, spilling if + /// needed outside the companion lock. + fn companion_resize(&self, serial: u64, size: u64) -> Result<(), Status> { + if size > FILE_BYTES { + return Err(Status::FBig); + } + let new_len = size as usize; + let (spilled_handle, need_bytes) = { + let mut companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + match &file.body { + Body::Spilled(handle) => (Some(handle.clone()), 0), + Body::Resident(bytes) => { + if new_len <= bytes.len() { + let sub = bytes.len() - new_len; + let file = companions.files.get_mut(&serial).unwrap(); + if let Body::Resident(ref mut buf) = file.body { + buf.truncate(new_len); + } + file.len = new_len; + companions.resident_bytes -= sub; + return Ok(()); + } + let add = new_len - bytes.len(); + if companions.resident_bytes + add <= companions.resident_budget { + if let Some(file) = companions.files.get_mut(&serial) { + if let Body::Resident(ref mut buf) = file.body { + buf.resize(new_len, 0); + } + file.len = new_len; + } + companions.resident_bytes += add; + return Ok(()); + } + (None, add) + } + } + }; + if let Some(handle) = spilled_handle { + handle.set_len(size).map_err(|e| io_status(&e))?; + let mut companions = self.companions(); + let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; + file.len = new_len; + return Ok(()); + } + if self.spill_for(serial, need_bytes)? { + let mut companions = self.companions(); + let avail = companions + .resident_budget + .saturating_sub(companions.resident_bytes); + if let Some(file) = companions.files.get_mut(&serial) { + if let Body::Resident(ref mut buf) = file.body { + let add = new_len.saturating_sub(buf.len()); + if add <= avail { + buf.resize(new_len, 0); + file.len = new_len; + companions.resident_bytes += add; + return Ok(()); + } + } + } + } + let handle = self.spill_self(serial, new_len)?; + handle.set_len(size).map_err(|e| io_status(&e))?; + let mut companions = self.companions(); + let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; + file.len = new_len; + 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( @@ -287,20 +726,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)?; + self.companion_resize(serial, size)?; } + 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; } @@ -316,15 +759,30 @@ 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 { - let mut companions = self.companions(); - let held = companions.len(); - *companions = Companions::default(); - held + /// Drops every companion and removes the export's spill directory; returns + /// `(companions, companion_bytes, companions_spilled)`. + pub(crate) fn companions_release(&self) -> (usize, usize, usize) { + let (held, bytes, spilled, dir) = { + let mut companions = self.companions(); + let held = companions.len(); + let bytes = companions.resident_bytes; + let spilled = companions.spilled(); + let dir = companions.spill_dir.take(); + *companions = Companions::default(); + (held, bytes, spilled, dir) + }; + if let Some(dir) = dir { + drop(fs::remove_dir_all(dir)); + } + (held, bytes, spilled) } - /// Companions held now. - pub(crate) fn companions_held(&self) -> usize { - self.companions().len() + /// Companion holdings now: `(companions, companion_bytes, companions_spilled)`. + pub(crate) fn companions_held(&self) -> (usize, usize, usize) { + let companions = self.companions(); + ( + companions.len(), + companions.resident_bytes, + companions.spilled(), + ) } } diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 7932d219b5..bc3904342d 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -463,6 +463,7 @@ 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.companion_drop_for(parent, name); self.table().by_name.remove(&(parent, name.to_vec())); let Some(target) = detached else { return; @@ -572,6 +573,7 @@ impl Kernel { self.mutate(from, None, None, Expect::Nothing, tickets, |_| { Ok(MutationInput::Named(remove::unlink(from, source_name))) })?; + self.companion_drop_for(from, name); self.silly_renamed.fetch_add(1, Ordering::Relaxed); let replaced = { let mut table = self.table(); diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index dd03a6ab8f..8c95d209fd 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -781,9 +781,11 @@ impl Kernel { /// 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 (companions, companion_bytes, companions_spilled) = self.companions_release(); let released = Released { companions, + companion_bytes, + companions_spilled, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -816,8 +818,11 @@ impl Kernel { /// Current holdings, for diagnostics. pub fn held(&self) -> Released { let table = self.table(); + let (companions, companion_bytes, companions_spilled) = self.companions_held(); Released { - companions: self.companions_held(), + companions, + companion_bytes, + companions_spilled, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -920,8 +925,12 @@ 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, + /// AppleDouble companion payload bytes currently resident in memory. + pub companion_bytes: usize, + /// AppleDouble companions whose payload is spilled to disk. + pub companions_spilled: 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/server.rs b/engine/crates/layerfs-nfs/src/server.rs index 60add78dff..8eb035e3bd 100644 --- a/engine/crates/layerfs-nfs/src/server.rs +++ b/engine/crates/layerfs-nfs/src/server.rs @@ -43,6 +43,17 @@ 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, + /// 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 @@ -55,8 +66,17 @@ 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, + companions_held: crate::apple_double::HELD, } } + /// Sets the scratch directory where AppleDouble companion bodies spill + /// beyond [`Self::companion_resident_bytes`]. + pub fn with_companion_spill_dir(mut self, dir: impl Into) -> Self { + self.companion_spill_dir = Some(dir.into()); + self + } } /// Calls served and time spent, per procedure. @@ -137,10 +157,16 @@ 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, + config.companions_held, + ); 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(), diff --git a/engine/crates/layerfs-nfs/tests/daemon.rs b/engine/crates/layerfs-nfs/tests/daemon.rs index eacaf9e35b..336353f457 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); diff --git a/engine/crates/layerfs-nfs/tests/support/rig.rs b/engine/crates/layerfs-nfs/tests/support/rig.rs index f30ad75e95..a5a8cbc801 100644 --- a/engine/crates/layerfs-nfs/tests/support/rig.rs +++ b/engine/crates/layerfs-nfs/tests/support/rig.rs @@ -40,6 +40,12 @@ 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, + /// 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, } impl Rig { /// Initializes a Store from `source`, publishes Branch `main` at that @@ -142,8 +148,16 @@ impl Rig { branch, 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, } } + 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 +193,9 @@ 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, + companions_held: self.companions_held, }, ) .unwrap() @@ -247,6 +264,9 @@ 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, + 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 a6c94d0f74..ce83302fc0 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -531,6 +531,240 @@ 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!(server.held().companions_spilled, 1); + + 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!(server.held().companions_spilled > 0); + 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_ACCES`. + 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_ACCES`. + c2.touch(&root2, b"extra", 0o644).unwrap(); + assert_eq!(c2.touch(&root2, b"._extra", 0o644).map(|_| ()), Err(ACCES)); + assert_eq!(server2.held().names_refused, 1); + + 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 tickets_are_released_only_after_the_reply() { let base = temp("tickets"); From 9d580d8c02392a499ddea0dd407f5c6d2262caf9 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 8 Nov 2026 21:20:10 +0800 Subject: [PATCH 02/16] refactor(nfs): slim the AppleDouble spill path and keep a body written out under another call (lp73) - Close the window the review found: spill_self switched a companion to the file it wrote out without comparing the `used` tick, so a resident body another connection wrote to during the off-lock disk write could be replaced by the older snapshot. Both spill paths now go through spill_one -> Companions::adopt_spilled, which switches only when spill_applies(used, file.used, resident) holds and otherwise unlinks the file just written so the newer body stays and the caller decides again. - Fold the redundant state machines: spill_for and spill_self become one spill_one(serial, keep); companion_write and companion_resize share Edit (Write/Size), Room (Resident/Spilled/Grow), edit_resident (in the lock, within the resident budget), edit_companion (one off-lock disk pass, deciding again when another call changed the body) and record_edit; companion_resize is removed and SETATTR resizes through edit_companion. Unlink/removal boilerplate is shared by unlink_paths, companion_take and Kernel::holdings. - Remove ExportConfig::with_companion_spill_dir (no caller) and Released::companions_spilled (read only by tests), counting the spill directory in the tests instead. ExportConfig keeps companion_resident_bytes and companions_held, exactly as lookups_held already does, because both bounds have to be reachable cheaply from tests; deleting them needs a doc(hidden) setter and saves about four lines net. - Set the modes instead of relying on the daemon's umask: the scratch directory is created 0700 and each spilled file 0600. The daemon's startup reclaim now removes a leftover /.appledouble from a daemon that ended without unmounting, before it serves any export, and touches nothing else under the mount home. Tests: tests/write.rs asserts the scratch directory and spilled-file mode bits, and that a spill replaces a companion body only when no call changed it meanwhile; tests/daemon.rs asserts the startup reclaim clears the leftover spill tree and leaves its siblings alone. No test is deleted. LayerFS production LOC: 143682 -> 144039 (delta +357) Production LOC: 144159 -> 144039 (delta -120) for this commit (parent 24fa1557d); the +357 line above is the branch against its base 716197c49, as the task asked. Scope at the committed tree: core 39,491, engine 66,634, control 33,969, api 3,945 (this commit: apple_double.rs 715 -> 614, kernel.rs 796 -> 783, server.rs 300 -> 296, control/export.rs 841 -> 839); reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: python3 -B tools/production_loc.py --files at the parent 24fa1557d and the committed tree; first-party product source under core/engine/control/api, tests, docs and tools excluded. --- docs/architecture/engine/kernel-routes/nfs.md | 14 +- .../layerfs-daemon/src/control/export.rs | 58 +- engine/crates/layerfs-nfs/src/apple_double.rs | 539 ++++++++---------- engine/crates/layerfs-nfs/src/kernel.rs | 41 +- engine/crates/layerfs-nfs/src/server.rs | 6 - engine/crates/layerfs-nfs/tests/daemon.rs | 36 ++ engine/crates/layerfs-nfs/tests/write.rs | 38 +- 7 files changed, 366 insertions(+), 366 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 08f9d792d2..da89f2258b 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -184,7 +184,7 @@ Refresh after an install is covered in serial >= SERIALS = 1 << 62 resident body <= RESIDENT_BYTES (32 MiB) in all; older bodies spill to /.appledouble// - (pread/pwrite outside the companion lock) + (pread/pwrite outside the companion lock; dir 0700, file 0600) LOOKUP GETATTR ACCESS READ WRITE SETATTR COMMIT REMOVE, RENAME to another "._" name: served here READDIR: not listed; engine: never called @@ -209,6 +209,18 @@ export removes the entire `/.appledouble/` directory remounts, daemon restarts and Commits do not retain them. A name is AppleDouble when it starts with `._` and has at least one more byte. +A body is written out from a snapshot taken under the companion lock and is +switched to that file only if the companion is still the one the snapshot saw +(same `used` tick, still resident): a body another call wrote to while the file +was being written wins, and the file just written is dropped. Disk I/O therefore +never holds the lock, and no write of one call is overwritten by the older +snapshot of another. The scratch directory is created `0700` and each spilled +file `0600`, set explicitly rather than left to the process umask, so a caller +embedding this crate without the daemon's `umask(0o077)` still keeps companion +bytes to its own user. The daemon's startup `reclaim` removes whatever +`/.appledouble` a daemon that ended without unmounting left behind, +before it serves any export, and touches nothing else under the mount home. + ## Mount ```text diff --git a/engine/crates/layerfs-daemon/src/control/export.rs b/engine/crates/layerfs-daemon/src/control/export.rs index 8c43bb7098..9b25663ecb 100644 --- a/engine/crates/layerfs-daemon/src/control/export.rs +++ b/engine/crates/layerfs-daemon/src/control/export.rs @@ -178,32 +178,43 @@ impl ExportServing { self.config.mounts.join(token.namespace.to_string()) } fn companion_spill_dir(&self, token: WorkspaceToken) -> PathBuf { - self.config - .mounts - .join(".appledouble") - .join(token.namespace.to_string()) + 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: @@ -485,15 +496,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)), - companion_resident_bytes: layerfs_nfs::apple_double::RESIDENT_BYTES, - companions_held: layerfs_nfs::apple_double::HELD, + ..ExportConfig::writable(config.command_uid, config.command_gid) }; let started = TcpListener::bind((config.listen, 0)).and_then(|listener| { Server::start( @@ -538,9 +544,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.config.mounts.join(".appledouble"), - )); + drop(std::fs::remove_dir(serving.spill_root())); return Err(self.unwind_export( workspace, mount, @@ -758,9 +762,7 @@ impl Service { } drop(std::fs::remove_dir(&ready.directory)); if let Some(serving) = self.export.as_ref() { - drop(std::fs::remove_dir( - serving.config.mounts.join(".appledouble"), - )); + 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) { diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index b1a2978cb6..c6f40158a7 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -38,7 +38,7 @@ use std::{ collections::{HashMap, HashSet}, fs::{self, File, OpenOptions}, io, - os::unix::fs::FileExt, + os::unix::fs::{DirBuilderExt, FileExt, OpenOptionsExt}, path::{Path, PathBuf}, sync::{atomic::Ordering, Arc}, time::{SystemTime, UNIX_EPOCH}, @@ -103,15 +103,6 @@ impl Default for Companions { } } impl Companions { - pub(crate) fn len(&self) -> usize { - self.files.len() - } - pub(crate) fn spilled(&self) -> usize { - self.files - .values() - .filter(|file| matches!(file.body, Body::Spilled(_))) - .count() - } fn tick(&mut self) -> u64 { self.tick += 1; self.tick @@ -132,20 +123,38 @@ impl Companions { subdirs: 0, } } - fn spill_path(&self, serial: u64) -> Option { - self.spill_dir - .as_ref() - .map(|dir| dir.join(serial.to_string())) - } fn take_serial(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; self.names.remove(&file.named); self.resident_bytes -= file.resident_len(); match file.body { Body::Resident(_) => None, - Body::Spilled(_) => self.spill_path(serial), + Body::Spilled(_) => (self.spill_dir.as_ref()).map(|dir| dir.join(serial.to_string())), } } + /// Switches `serial` to the spilled `handle` of `len` bytes when nothing + /// touched it since `used` was read and its body is still resident. A body + /// another call changed or already spilled stays: `Ok(false)` then, and + /// the file just written is the caller's to unlink. + fn adopt_spilled( + &mut self, + serial: u64, + used: u64, + handle: Arc, + len: usize, + ) -> Result { + let Some(file) = self.files.get_mut(&serial) else { + return Err(Status::Stale); + }; + if !spill_applies(used, file.used, matches!(file.body, Body::Resident(_))) { + return Ok(false); + } + let old = file.resident_len(); + file.body = Body::Spilled(handle); + file.len = file.len.max(len); + self.resident_bytes -= old; + Ok(true) + } fn oldest_resident(&self, skip: Option) -> Option { self.files .iter() @@ -185,32 +194,38 @@ fn io_status(error: &io::Error) -> Status { _ => Status::Io, } } +/// Creates `dir` and the spilled file of `serial` in it, holding `bytes` and +/// extending it to `len` bytes. Only this user reads companion bodies, so the +/// modes are set here rather than left to the caller's umask. fn create_spilled(dir: &Path, serial: u64, bytes: &[u8], len: u64) -> Result, Status> { - fs::create_dir_all(dir).map_err(|e| io_status(&e))?; + let made = fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(dir); + made.map_err(|e| io_status(&e))?; let path = dir.join(serial.to_string()); let file = OpenOptions::new() .read(true) .write(true) .create(true) .truncate(true) + .mode(0o600) .open(&path) .map_err(|e| io_status(&e))?; - if !bytes.is_empty() { - if let Err(e) = file.write_all_at(bytes, 0) { - drop(file); - drop(fs::remove_file(&path)); - return Err(io_status(&e)); - } - } - if len > bytes.len() as u64 { - if let Err(e) = file.set_len(len) { - drop(file); - drop(fs::remove_file(&path)); - return Err(io_status(&e)); - } + let written = (file.write_all_at(bytes, 0)).and_then(|()| file.set_len(len)); + if let Err(e) = written { + drop(file); + drop(fs::remove_file(&path)); + return Err(io_status(&e)); } Ok(Arc::new(file)) } +/// Unlinks the spilled files a companion operation retired, outside the lock. +fn unlink_paths(paths: impl IntoIterator) { + for path in paths { + drop(fs::remove_file(path)); + } +} fn now() -> PortableMetadata { let elapsed = SystemTime::now() .duration_since(UNIX_EPOCH) @@ -222,9 +237,66 @@ fn now() -> PortableMetadata { } } fn touch(metadata: &mut PortableMetadata) { - let fresh = now(); - metadata.mtime_seconds = fresh.mtime_seconds; - metadata.mtime_nanoseconds = fresh.mtime_nanoseconds; + 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. +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. + 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`. + 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. + 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)), + } + } + /// Records the edit's length on `file`. + fn record(&self, file: &mut Companion) { + file.len = match self { + Edit::Write { .. } => file.len.max(self.target_len()), + Edit::Size(size) => *size, + }; + } +} +/// Where [`Kernel::edit_resident`] found a companion's body. +enum Room { + /// Applied to the resident body. + Resident, + /// On disk: finish with this handle outside the lock. + Spilled(Arc), + /// Resident, but growing it needs this many more budget bytes first. + Grow(usize), +} +/// 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 resident, 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 } /// A serial of the export's own companions. pub fn companion(serial: u64) -> bool { @@ -256,94 +328,50 @@ impl Kernel { /// Returns `true` if `need` fits in resident memory afterwards. fn spill_for(&self, target: u64, need: usize) -> Result { loop { - let (candidate, dir, bytes, used) = { + let victim = { let companions = self.companions(); - if companions - .resident_bytes - .checked_add(need) - .is_some_and(|total| total <= companions.resident_budget) - { + let fits = companions.resident_bytes + need <= companions.resident_budget; + if fits { return Ok(true); } - let Some(dir) = companions.spill_dir.clone() else { - return Ok(false); - }; - let Some(victim) = companions.oldest_resident(Some(target)) else { - return Ok(false); - }; - let file = &companions.files[&victim]; - let Body::Resident(ref data) = file.body else { - continue; - }; - (victim, dir, data.clone(), file.used) + companions.oldest_resident(Some(target)) }; - let spilled = create_spilled(&dir, candidate, &bytes, bytes.len() as u64)?; - let mut unlink = None; - { - let mut companions = self.companions(); - match companions.files.get_mut(&candidate) { - Some(file) if file.used == used && matches!(file.body, Body::Resident(_)) => { - let old = file.resident_len(); - file.body = Body::Spilled(spilled); - companions.resident_bytes -= old; - } - _ => { - unlink = Some(dir.join(candidate.to_string())); - } - } - } - if let Some(path) = unlink { - drop(fs::remove_file(path)); - } + 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)?; } } - /// Transitions `serial` itself to a spilled file of length `new_len` - /// without holding the companion lock across disk I/O. - fn spill_self(&self, serial: u64, new_len: usize) -> Result, Status> { - let (dir, existing, old_len) = { + /// 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(None)` when another + /// call changed the companion, or already spilled it, while the file was + /// written: that file is dropped and the caller decides again on the body + /// it now finds. + fn spill_one(&self, serial: u64, keep: Option) -> Result>, Status> { + let (dir, bytes, size, used) = { let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - if let Body::Spilled(ref handle) = file.body { - return Ok(handle.clone()); - } - let dir = companions.spill_dir.clone().ok_or(Status::NoSpc)?; - let Body::Resident(ref data) = file.body else { - unreachable!() + let bytes = match &file.body { + Body::Resident(bytes) => bytes.clone(), + Body::Spilled(handle) => return Ok(Some(handle.clone())), }; - let copy = data.len().min(new_len); - (dir, data[..copy].to_vec(), file.len) + 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 target_len = new_len.max(old_len) as u64; - let handle = create_spilled(&dir, serial, &existing, target_len)?; - let mut unlink = None; - let chosen = { + let handle = create_spilled(&dir, serial, &bytes, size as u64)?; + let adopted = { let mut companions = self.companions(); - match companions.files.get_mut(&serial) { - Some(file) => match &file.body { - Body::Resident(_) => { - let old_res = file.resident_len(); - file.body = Body::Spilled(handle.clone()); - if target_len as usize > file.len { - file.len = target_len as usize; - } - companions.resident_bytes -= old_res; - Ok(handle) - } - Body::Spilled(already) => { - unlink = Some(dir.join(serial.to_string())); - Ok(already.clone()) - } - }, - None => { - unlink = Some(dir.join(serial.to_string())); - Err(Status::Stale) - } - } + companions.adopt_spilled(serial, used, handle.clone(), size) }; - if let Some(path) = unlink { - drop(fs::remove_file(path)); + if matches!(adopted, Ok(true)) { + return Ok(Some(handle)); } - chosen + unlink_paths([dir.join(serial.to_string())]); + adopted.map(|_| None) } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { @@ -396,21 +424,19 @@ impl Kernel { } let at_limit = { let companions = self.companions(); - companions.len() >= companions.held_limit + companions.files.len() >= companions.held_limit }; let mut reclaimed = Vec::new(); if at_limit { let live: HashSet<(u64, Vec)> = self.table().by_name.keys().cloned().collect(); let mut companions = self.companions(); - if companions.len() >= companions.held_limit { + if companions.files.len() >= companions.held_limit { reclaimed = companions.reclaim_orphans(&live); } } - for path in reclaimed { - drop(fs::remove_file(path)); - } + unlink_paths(reclaimed); let mut companions = self.companions(); - if companions.len() >= companions.held_limit { + if companions.files.len() >= companions.held_limit { drop(companions); self.names_refused.fetch_add(1, Ordering::Relaxed); return Err(Status::Access); @@ -442,18 +468,24 @@ impl Kernel { 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 { + /// Takes the companion held under `(parent, name)` out of the index and + /// unlinks its spilled file; `true` when one was held. + fn companion_take(&self, parent: u64, name: &[u8]) -> bool { let spilled = { let mut companions = self.companions(); - let serial = companions.names.get(&(parent, name.to_vec())).copied()?; + let Some(serial) = companions.names.get(&(parent, name.to_vec())).copied() else { + return false; + }; companions.take_serial(serial) }; - if let Some(path) = spilled { - drop(fs::remove_file(path)); - } - Some(self.directory_wcc(parent)) + unlink_paths(spilled); + true + } + /// 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 { + self.companion_take(parent, name) + .then(|| self.directory_wcc(parent)) } /// Drops the companion `._` paired with `name` in `parent`, if one /// is held, when `name` itself is removed, silly-renamed or replaced by @@ -468,17 +500,7 @@ impl Kernel { let mut paired = Vec::with_capacity(2 + name.len()); paired.extend_from_slice(b"._"); paired.extend_from_slice(name); - let spilled = { - let mut companions = self.companions(); - companions - .names - .get(&(parent, paired)) - .copied() - .and_then(|serial| companions.take_serial(serial)) - }; - if let Some(path) = spilled { - drop(fs::remove_file(path)); - } + self.companion_take(parent, &paired); } /// RENAME of a companion name: only to another AppleDouble name, which /// it replaces when held. `None` when no companion has that name. @@ -510,9 +532,7 @@ impl Kernel { file.used = tick; } } - if let Some(path) = replaced_path { - drop(fs::remove_file(path)); - } + unlink_paths(replaced_path); Some(Ok(())) } /// READ of a companion, at most `count` bytes from `offset`, appended to @@ -530,21 +550,18 @@ impl Kernel { 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 { + let handle = match &file.body { Body::Resident(bytes) => { out.extend_from_slice(&bytes[start..end]); - companions.use_serial(serial); - return Ok(end as u64 >= length); - } - Body::Spilled(handle) => { - let cloned = handle.clone(); - companions.use_serial(serial); - (cloned, length, start, end) + None } - } + Body::Spilled(handle) => Some(handle.clone()), + }; + companions.use_serial(serial); + (handle, length, start, end) }; - let mut buf = vec![0u8; end - start]; - if !buf.is_empty() { + if let Some(spilled) = spilled { + let mut buf = vec![0u8; end - start]; spilled .read_exact_at(&mut buf, start as u64) .map_err(|e| io_status(&e))?; @@ -563,153 +580,76 @@ impl Kernel { if end > FILE_BYTES { return Err(Status::FBig); } - let end_usize = end as usize; - let (before, spilled_handle, need_bytes) = { - let mut companions = self.companions(); - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let before = Companions::stat(serial, file); - match &file.body { - Body::Spilled(handle) => (before, Some(handle.clone()), 0), - Body::Resident(bytes) => { - let add = end_usize.saturating_sub(bytes.len()); - if companions.resident_bytes + add <= companions.resident_budget { - let tick = companions.tick(); - if let Some(file) = companions.files.get_mut(&serial) { - if let Body::Resident(ref mut buf) = file.body { - if end_usize > buf.len() { - buf.resize(end_usize, 0); - } - buf[offset as usize..end_usize].copy_from_slice(data); - } - file.len = file.len.max(end_usize); - file.used = tick; - touch(&mut file.metadata); - } - companions.resident_bytes += add; - let after = Companions::stat(serial, &companions.files[&serial]); - return Ok((data.len() as u32, (Some(before), Some(after)))); + 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)))) + } + /// 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. + fn edit_companion(&self, serial: u64, edit: Edit<'_>) -> Result { + let target = edit.target_len(); + // A round ends in the body, or in another call having changed this + // companion while its body was written out, which decides again. + for _ in 0..3 { + let spilled = match self.edit_resident(serial, target, &edit)? { + Room::Resident => return self.record_edit(serial, &edit), + Room::Spilled(handle) => Some(handle), + Room::Grow(need) => { + if self.spill_for(serial, need)? { + continue; } - (before, None, add) + self.spill_one(serial, Some(target))? } + }; + if let Some(handle) = spilled { + edit.disk(&handle)?; + return self.record_edit(serial, &edit); } - }; - if let Some(handle) = spilled_handle { - handle - .write_all_at(data, offset) - .map_err(|e| io_status(&e))?; - let mut companions = self.companions(); - let tick = companions.tick(); - let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.len = file.len.max(end_usize); - file.used = tick; - touch(&mut file.metadata); - let after = Companions::stat(serial, file); - return Ok((data.len() as u32, (Some(before), Some(after)))); } - if self.spill_for(serial, need_bytes)? { - let mut companions = self.companions(); - let avail = companions - .resident_budget - .saturating_sub(companions.resident_bytes); - if let Some(file) = companions.files.get_mut(&serial) { - if let Body::Resident(ref mut buf) = file.body { - let add = end_usize.saturating_sub(buf.len()); - if add <= avail { - if end_usize > buf.len() { - buf.resize(end_usize, 0); - } - buf[offset as usize..end_usize].copy_from_slice(data); - file.len = file.len.max(end_usize); - touch(&mut file.metadata); - let after = Companions::stat(serial, file); - companions.resident_bytes += add; - companions.use_serial(serial); - return Ok((data.len() as u32, (Some(before), Some(after)))); + // Only other calls changing this companion in every round get here. + Err(Status::Io) + } + /// Applies `edit` to `serial`'s resident body while the budget holds it. + 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 (before, after) = { + let body = companions.files.get_mut(&serial).map(|file| &mut file.body); + match body { + None => return Err(Status::Stale), + Some(Body::Spilled(handle)) => return Ok(Room::Spilled(handle.clone())), + Some(Body::Resident(bytes)) => { + let need = target.saturating_sub(bytes.len()); + if need > avail { + return Ok(Room::Grow(need)); } + let before = bytes.len(); + edit.memory(bytes); + (before, bytes.len()) } } - } - let handle = self.spill_self(serial, end_usize)?; - handle - .write_all_at(data, offset) - .map_err(|e| io_status(&e))?; + }; + companions.resident_bytes = companions.resident_bytes - before + after; + Ok(Room::Resident) + } + /// Records an applied edit on `serial` and answers its stat. + fn record_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { let mut companions = self.companions(); let tick = companions.tick(); let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.len = file.len.max(end_usize); + edit.record(file); file.used = tick; touch(&mut file.metadata); - let after = Companions::stat(serial, file); - Ok((data.len() as u32, (Some(before), Some(after)))) - } - /// Resizes `serial` to `size` for SETATTR / UNCHECKED CREATE, spilling if - /// needed outside the companion lock. - fn companion_resize(&self, serial: u64, size: u64) -> Result<(), Status> { - if size > FILE_BYTES { - return Err(Status::FBig); - } - let new_len = size as usize; - let (spilled_handle, need_bytes) = { - let mut companions = self.companions(); - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - match &file.body { - Body::Spilled(handle) => (Some(handle.clone()), 0), - Body::Resident(bytes) => { - if new_len <= bytes.len() { - let sub = bytes.len() - new_len; - let file = companions.files.get_mut(&serial).unwrap(); - if let Body::Resident(ref mut buf) = file.body { - buf.truncate(new_len); - } - file.len = new_len; - companions.resident_bytes -= sub; - return Ok(()); - } - let add = new_len - bytes.len(); - if companions.resident_bytes + add <= companions.resident_budget { - if let Some(file) = companions.files.get_mut(&serial) { - if let Body::Resident(ref mut buf) = file.body { - buf.resize(new_len, 0); - } - file.len = new_len; - } - companions.resident_bytes += add; - return Ok(()); - } - (None, add) - } - } - }; - if let Some(handle) = spilled_handle { - handle.set_len(size).map_err(|e| io_status(&e))?; - let mut companions = self.companions(); - let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.len = new_len; - return Ok(()); - } - if self.spill_for(serial, need_bytes)? { - let mut companions = self.companions(); - let avail = companions - .resident_budget - .saturating_sub(companions.resident_bytes); - if let Some(file) = companions.files.get_mut(&serial) { - if let Body::Resident(ref mut buf) = file.body { - let add = new_len.saturating_sub(buf.len()); - if add <= avail { - buf.resize(new_len, 0); - file.len = new_len; - companions.resident_bytes += add; - return Ok(()); - } - } - } - } - let handle = self.spill_self(serial, new_len)?; - handle.set_len(size).map_err(|e| io_status(&e))?; - let mut companions = self.companions(); - let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.len = new_len; - Ok(()) + Ok(Companions::stat(serial, file)) } /// SETATTR of a companion: mode, size and modification time; the /// owner is the export's identity, as for every inode. @@ -721,9 +661,9 @@ impl Kernel { _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 { + 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 = { @@ -738,7 +678,10 @@ impl Kernel { before }; if let Some(size) = sattr.size { - self.companion_resize(serial, 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(); @@ -760,29 +703,21 @@ impl Kernel { Ok((after.clone(), (Some(before), Some(after)))) } /// Drops every companion and removes the export's spill directory; returns - /// `(companions, companion_bytes, companions_spilled)`. - pub(crate) fn companions_release(&self) -> (usize, usize, usize) { - let (held, bytes, spilled, dir) = { + /// how many companions it held and their resident payload bytes. + pub(crate) fn companions_release(&self) -> (usize, usize) { + let (held, dir) = { let mut companions = self.companions(); - let held = companions.len(); - let bytes = companions.resident_bytes; - let spilled = companions.spilled(); let dir = companions.spill_dir.take(); - *companions = Companions::default(); - (held, bytes, spilled, dir) + (std::mem::take(&mut *companions), dir) }; if let Some(dir) = dir { drop(fs::remove_dir_all(dir)); } - (held, bytes, spilled) + (held.files.len(), held.resident_bytes) } - /// Companion holdings now: `(companions, companion_bytes, companions_spilled)`. - pub(crate) fn companions_held(&self) -> (usize, usize, usize) { + /// Companions held now and their resident payload bytes. + pub(crate) fn companions_held(&self) -> (usize, usize) { let companions = self.companions(); - ( - companions.len(), - companions.resident_bytes, - companions.spilled(), - ) + (companions.files.len(), companions.resident_bytes) } } diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 8c95d209fd..85f82f4eb8 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -781,23 +781,8 @@ impl Kernel { /// 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, companion_bytes, companions_spilled) = self.companions_release(); - let released = Released { - companions, - companion_bytes, - companions_spilled, - 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 (companions, companion_bytes) = self.companions_release(); + let released = self.holdings(&table, companions, companion_bytes); for (serial, held) in table.files { self.close_file(serial, held.handle); } @@ -818,22 +803,26 @@ impl Kernel { /// Current holdings, for diagnostics. pub fn held(&self) -> Released { let table = self.table(); - let (companions, companion_bytes, companions_spilled) = self.companions_held(); + let (companions, companion_bytes) = self.companions_held(); + self.holdings(&table, companions, companion_bytes) + } + /// What this export holds now, as [`Released`] reports it. + fn holdings(&self, table: &Table, companions: usize, companion_bytes: usize) -> Released { + let count = |counter: &AtomicU64| counter.load(Ordering::Relaxed); Released { companions, companion_bytes, - companions_spilled, 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), + 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), } } /// Closes every implicit file descriptor that no silly name needs, so @@ -929,8 +918,6 @@ pub struct Released { pub companions: usize, /// AppleDouble companion payload bytes currently resident in memory. pub companion_bytes: usize, - /// AppleDouble companions whose payload is spilled to disk. - pub companions_spilled: 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/server.rs b/engine/crates/layerfs-nfs/src/server.rs index 8eb035e3bd..6a4599db4f 100644 --- a/engine/crates/layerfs-nfs/src/server.rs +++ b/engine/crates/layerfs-nfs/src/server.rs @@ -71,12 +71,6 @@ impl ExportConfig { companions_held: crate::apple_double::HELD, } } - /// Sets the scratch directory where AppleDouble companion bodies spill - /// beyond [`Self::companion_resident_bytes`]. - pub fn with_companion_spill_dir(mut self, dir: impl Into) -> Self { - self.companion_spill_dir = Some(dir.into()); - self - } } /// Calls served and time spent, per procedure. diff --git a/engine/crates/layerfs-nfs/tests/daemon.rs b/engine/crates/layerfs-nfs/tests/daemon.rs index 336353f457..2d831256bb 100644 --- a/engine/crates/layerfs-nfs/tests/daemon.rs +++ b/engine/crates/layerfs-nfs/tests/daemon.rs @@ -301,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/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index ce83302fc0..26168fde35 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -56,6 +56,14 @@ 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()) + .filter_map(|entry| entry.metadata().ok()) + .map(|metadata| metadata.len()) + .collect(); + (files.len(), files.iter().sum()) +} #[test] fn every_changing_procedure_and_its_statuses() { @@ -579,7 +587,17 @@ fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up "oldest companion body spilled to disk" ); assert!(server.held().companion_bytes <= budget); - assert_eq!(server.held().companions_spilled, 1); + 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!( @@ -641,7 +659,10 @@ fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up } assert_eq!(server.held().companions, TOTAL_COUNT); assert_eq!(server.held().names_refused, 0); - assert!(server.held().companions_spilled > 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. @@ -765,6 +786,19 @@ fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up 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)); +} + #[test] fn tickets_are_released_only_after_the_reply() { let base = temp("tickets"); From ca153a7f6156acfc4a5258c8f2aa0f88c8bb578f Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 8 Nov 2026 22:11:17 +0800 Subject: [PATCH 03/16] fix(nfs): hold no descriptor per spilled AppleDouble body and close two spill races (lp73) Every spilled companion body was held open in `Body::Spilled(Arc)`, so an export with more spilled companions than the process's own `RLIMIT_NOFILE` answered WRITE with `NFS3ERR_IO` (`openat EMFILE`): with Linux's default 1024, `write::apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up` failed after about a thousand companions. `Body::Spilled` now only marks a body as on disk, its path derived from the serial, and READ, WRITE and SETATTR open it for their own `pread`/`pwrite`/`set_len` and close it again, so descriptors follow concurrent operations instead of spilled bodies. No descriptor limit is raised to pass a test; nothing about the file format or directory layout changes. Two multi-connection windows are closed with it: - `edit_resident` records a body's bytes, length, recency tick and time under the same lock, so a call can no longer see new bytes with an old length (a READ could slice past the bytes and panic) or a stale `used` tick (a spill could take the older snapshot for the current body). `Room::Resident` carries the stat afterwards, so `record_edit` now only serves the disk half. READ clamps its slice to the bytes it holds instead of panicking. - A spill writes `..tmp` (`create_new`) and adoption renames it to `` under the lock, so two calls spilling the same companion never truncate each other's file, and the call whose file is not adopted unlinks only its own temporary file. New test `write::spilled_companions_outnumber_the_open_file_limit` lowers the soft `RLIMIT_NOFILE` (restored by a `Drop` guard, `panic` included) to at most 512 and creates four times as many spilled companions, then reads all of them byte for byte and writes and truncates one: `NFS3ERR_IO` before this change, all green after. `libc` becomes a dev-dependency of `layerfs-nfs` for `getrlimit`/ `setrlimit`; it is already in the workspace at 0.2.189, so the lock gains one dependency edge and no package. LayerFS production LOC: 144039 -> 144079 (delta +40) Scope and method: `python3 -B tools/production_loc.py` (combined total) on the first parent and the committed tree; only `engine/crates/layerfs-nfs/src/apple_double.rs` changed in production scope (614 -> 654 production lines, physical 723 -> 785, under the 999-line ceiling). Tests, the Cargo manifest/lock and `docs/architecture/engine/kernel-routes/nfs.md` are outside that count. --- Cargo.lock | 1 + docs/architecture/engine/kernel-routes/nfs.md | 31 ++- engine/crates/layerfs-nfs/Cargo.toml | 1 + engine/crates/layerfs-nfs/src/apple_double.rs | 216 +++++++++++------- engine/crates/layerfs-nfs/tests/write.rs | 124 ++++++++++ 5 files changed, 286 insertions(+), 87 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 70a2862295..bb45ad19bd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -871,6 +871,7 @@ dependencies = [ "layerfs-storage", "layerfs-telemetry", "layerfs-workspace", + "libc", ] [[package]] diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index da89f2258b..f1e78e226f 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -184,7 +184,9 @@ Refresh after an install is covered in serial >= SERIALS = 1 << 62 resident body <= RESIDENT_BYTES (32 MiB) in all; older bodies spill to /.appledouble// - (pread/pwrite outside the companion lock; dir 0700, file 0600) + (dir 0700, file 0600; written as ..tmp and + renamed on adoption; pread/pwrite outside the companion + lock, opened by path per call, never held open) LOOKUP GETATTR ACCESS READ WRITE SETATTR COMMIT REMOVE, RENAME to another "._" name: served here READDIR: not listed; engine: never called @@ -209,15 +211,24 @@ export removes the entire `/.appledouble/` directory remounts, daemon restarts and Commits do not retain them. A name is AppleDouble when it starts with `._` and has at least one more byte. -A body is written out from a snapshot taken under the companion lock and is -switched to that file only if the companion is still the one the snapshot saw -(same `used` tick, still resident): a body another call wrote to while the file -was being written wins, and the file just written is dropped. Disk I/O therefore -never holds the lock, and no write of one call is overwritten by the older -snapshot of another. The scratch directory is created `0700` and each spilled -file `0600`, set explicitly rather than left to the process umask, so a caller -embedding this crate without the daemon's `umask(0o077)` still keeps companion -bytes to its own user. The daemon's startup `reclaim` removes whatever +A body is written out from a snapshot taken under the companion lock, as a new +`..tmp` opened with `create_new`, and is switched to that file only +if the companion is still the one the snapshot saw (same `used` tick, still +resident): the adopting call renames its temporary file to ``, so two +calls spilling the same companion never write to or unlink each other's file, a +body another call wrote to while the file was being written wins, and the file +just written is dropped. Disk I/O therefore never holds the lock, and no write +of one call is overwritten by the older snapshot of another. No descriptor is +kept for a spilled body: READ, WRITE and SETATTR open `` for their own +`pread`/`pwrite`/`set_len` and close it again, so descriptors grow with +concurrent operations and not with the number of spilled companions, and a +companion count above the process's own `RLIMIT_NOFILE` still reads and writes. +An edit records a body's bytes, length, recency tick and time under one lock, so +no call sees a resident body and a length that disagree, and a reply never +slices past the bytes it holds. The scratch directory is created `0700` and each +spilled file `0600`, set explicitly rather than left to the process umask, so a +caller embedding this crate without the daemon's `umask(0o077)` still keeps +companion bytes to its own user. The daemon's startup `reclaim` removes whatever `/.appledouble` a daemon that ended without unmounting left behind, before it serves any export, and touches nothing else under the mount home. 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 c6f40158a7..b156bc0220 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -21,7 +21,12 @@ //! 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 (one file per companion serial, read and written with -//! `pread`/`pwrite` outside the companion lock). Removing or replacing a main +//! `pread`/`pwrite` outside the companion lock). 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, and no descriptor +//! is kept for a spilled body: an operation opens its file by path and closes +//! it again, so open descriptors grow with concurrent operations and not with +//! the number of spilled companions. Removing or replacing a main //! file drops its paired `._` companion and any spilled file with it; //! when [`HELD`] is reached, orphan companions whose main file is no longer in //! the export's name index are reclaimed first, and only if [`HELD`] live @@ -40,7 +45,7 @@ use std::{ io, os::unix::fs::{DirBuilderExt, FileExt, OpenOptionsExt}, path::{Path, PathBuf}, - sync::{atomic::Ordering, Arc}, + sync::atomic::{AtomicU64, Ordering}, time::{SystemTime, UNIX_EPOCH}, }; @@ -55,10 +60,16 @@ pub const FILE_BYTES: u64 = 1 << 20; pub const RESIDENT_BYTES: usize = 32 << 20; /// Mode of a companion created without one. 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); enum Body { Resident(Vec), - Spilled(Arc), + /// On disk in the spill directory, under the companion's own serial; each + /// operation opens it by path instead of holding it open. + Spilled, } struct Companion { @@ -72,7 +83,7 @@ impl Companion { fn resident_len(&self) -> usize { match &self.body { Body::Resident(bytes) => bytes.len(), - Body::Spilled(_) => 0, + Body::Spilled => 0, } } } @@ -129,28 +140,35 @@ impl Companions { self.resident_bytes -= file.resident_len(); match file.body { Body::Resident(_) => None, - Body::Spilled(_) => (self.spill_dir.as_ref()).map(|dir| dir.join(serial.to_string())), + Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), } } - /// Switches `serial` to the spilled `handle` of `len` bytes when nothing - /// touched it since `used` was read and its body is still resident. A body - /// another call changed or already spilled stays: `Ok(false)` then, and - /// the file just written is the caller's to unlink. + /// 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, when nothing touched it since `used` was read and + /// its body is still resident. A body another call changed or already + /// spilled stays: `Ok(false)` then, and `temp` is the caller's to unlink. fn adopt_spilled( &mut self, serial: u64, used: u64, - handle: Arc, + 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); }; if !spill_applies(used, file.used, matches!(file.body, Body::Resident(_))) { return Ok(false); } + fs::rename(temp, path).map_err(|e| io_status(&e))?; let old = file.resident_len(); - file.body = Body::Spilled(handle); + file.body = Body::Spilled; file.len = file.len.max(len); self.resident_bytes -= old; Ok(true) @@ -194,31 +212,46 @@ fn io_status(error: &io::Error) -> Status { _ => Status::Io, } } -/// Creates `dir` and the spilled file of `serial` in it, holding `bytes` and -/// extending it to `len` bytes. Only this user reads companion bodies, so the -/// modes are set here rather than left to the caller's umask. -fn create_spilled(dir: &Path, serial: u64, bytes: &[u8], len: u64) -> Result, Status> { +/// The spill directory's own file of `serial`. +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. Two calls spilling the same `serial` write different +/// temporary files, and only the call whose file is adopted renames it to the +/// companion's own name. Only this user reads companion bodies, so the modes +/// are set here rather than left to the caller's umask. +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))?; - let path = dir.join(serial.to_string()); - let file = OpenOptions::new() - .read(true) - .write(true) - .create(true) - .truncate(true) - .mode(0o600) - .open(&path) - .map_err(|e| io_status(&e))?; - let written = (file.write_all_at(bytes, 0)).and_then(|()| file.set_len(len)); - if let Err(e) = written { + 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); - drop(fs::remove_file(&path)); - return Err(io_status(&e)); + return match written { + Ok(()) => Ok(path), + Err(e) => { + drop(fs::remove_file(&path)); + Err(io_status(&e)) + } + }; } - Ok(Arc::new(file)) + Err(Status::Io) } /// Unlinks the spilled files a companion operation retired, outside the lock. fn unlink_paths(paths: impl IntoIterator) { @@ -285,10 +318,11 @@ impl Edit<'_> { } /// Where [`Kernel::edit_resident`] found a companion's body. enum Room { - /// Applied to the resident body. - Resident, - /// On disk: finish with this handle outside the lock. - Spilled(Arc), + /// Applied to the resident body, whose length, recency and time were + /// recorded under the same lock: this is the companion's stat afterwards. + Resident(ViewStat), + /// On disk: finish with its file outside the lock. + Spilled, /// Resident, but growing it needs this many more budget bytes first. Grow(usize), } @@ -346,32 +380,47 @@ impl Kernel { } /// 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(None)` when another + /// 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 file is dropped and the caller decides again on the body - /// it now finds. - fn spill_one(&self, serial: u64, keep: Option) -> Result>, Status> { + /// 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::Spilled(handle) => return Ok(Some(handle.clone())), + 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 handle = create_spilled(&dir, serial, &bytes, size as u64)?; - let adopted = { - let mut companions = self.companions(); - companions.adopt_spilled(serial, used, handle.clone(), size) - }; + let temp = create_spilled(&dir, serial, &bytes, size as u64)?; + let adopted = self.companions().adopt_spilled(serial, used, &temp, size); if matches!(adopted, Ok(true)) { - return Ok(Some(handle)); + return Ok(true); } - unlink_paths([dir.join(serial.to_string())]); - adopted.map(|_| None) + unlink_paths([temp]); + adopted.map(|_| false) + } + /// 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), + }) } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { @@ -550,19 +599,22 @@ impl Kernel { 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 handle = match &file.body { + let spilled = match &file.body { Body::Resident(bytes) => { - out.extend_from_slice(&bytes[start..end]); - None + // 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::Spilled(handle) => Some(handle.clone()), + Body::Spilled => true, }; companions.use_serial(serial); - (handle, length, start, end) + (spilled, length, start, end) }; - if let Some(spilled) = spilled { + if spilled { let mut buf = vec![0u8; end - start]; - spilled + self.spill_file(serial, false)? .read_exact_at(&mut buf, start as u64) .map_err(|e| io_status(&e))?; out.extend_from_slice(&buf); @@ -599,8 +651,8 @@ impl Kernel { // companion while its body was written out, which decides again. for _ in 0..3 { let spilled = match self.edit_resident(serial, target, &edit)? { - Room::Resident => return self.record_edit(serial, &edit), - Room::Spilled(handle) => Some(handle), + Room::Resident(stat) => return Ok(stat), + Room::Spilled => true, Room::Grow(need) => { if self.spill_for(serial, need)? { continue; @@ -608,38 +660,48 @@ impl Kernel { self.spill_one(serial, Some(target))? } }; - if let Some(handle) = spilled { - edit.disk(&handle)?; + if spilled { + edit.disk(&self.spill_file(serial, true)?)?; return self.record_edit(serial, &edit); } } // Only other calls changing this companion in every round get here. Err(Status::Io) } - /// Applies `edit` to `serial`'s resident body while the budget holds it. + /// Applies `edit` to `serial`'s resident body while the budget holds it, + /// recording its length, recency and time 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 (before, after) = { - let body = companions.files.get_mut(&serial).map(|file| &mut file.body); - match body { - None => return Err(Status::Stale), - Some(Body::Spilled(handle)) => return Ok(Room::Spilled(handle.clone())), - Some(Body::Resident(bytes)) => { - let need = target.saturating_sub(bytes.len()); - if need > avail { - return Ok(Room::Grow(need)); - } - let before = bytes.len(); - edit.memory(bytes); - (before, bytes.len()) + let mut guard = self.companions(); + let Companions { + files, + tick, + resident_bytes, + resident_budget, + .. + } = &mut *guard; + let avail = resident_budget.saturating_sub(*resident_bytes); + let Some(file) = files.get_mut(&serial) else { + return Err(Status::Stale); + }; + let before = match &mut file.body { + Body::Spilled => return Ok(Room::Spilled), + Body::Resident(bytes) => { + let need = target.saturating_sub(bytes.len()); + if need > avail { + return Ok(Room::Grow(need)); } + let before = bytes.len(); + edit.memory(bytes); + before } }; - companions.resident_bytes = companions.resident_bytes - before + after; - Ok(Room::Resident) + edit.record(file); + touch(&mut file.metadata); + *tick += 1; + file.used = *tick; + *resident_bytes = *resident_bytes - before + file.resident_len(); + Ok(Room::Resident(Companions::stat(serial, file))) } /// Records an applied edit on `serial` and answers its stat. fn record_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index 26168fde35..f3025bfffb 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -799,6 +799,130 @@ fn a_spill_replaces_a_companion_body_only_when_no_call_changed_it() { 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()) +} + +/// 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() { + 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. + // Lowering the soft limit while this binary runs its tests in threads + // leaves every one of them more than enough descriptors. + 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 79e378e4ff7d54fc5e23ae5407932a337ba6cf4b Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Mon, 9 Nov 2026 10:23:53 +0800 Subject: [PATCH 04/16] Fix AppleDouble companion creation and alias reclamation (LP73-ASK2-AB-FIX) Keep companion name lookup, capacity reclamation and serial insertion under one lock. Preserve previously observed hard-link names in by_name and remove every key for an inode when its synthetic custody is retired. Keep HELD at 65,536. Refuse an exhausted companion index with NFS3ERR_NOSPC, count each refusal and log export/namespace and capacity at most once per minute. Add concurrent CREATE and hard-link reclamation regressions; update nfs.md. Validation: layerfs-nfs fast tests 32 passed and slow test 1 passed; write under ulimit -n 1024: 13 passed; named_mount: 1 passed; Clippy all targets for layerfs-nfs/layerfs-daemon with -D warnings; rustfmt; product boundary guard and its 37 self-tests; release CLI/daemon build. Both new tests failed with their respective fixes temporarily reverted. No kernel mount testing, push, PR or issue. LayerFS production LOC: 144079 -> 144094 (delta +15) Scope: first-party core/engine/control/API production source and runtime SQL; tests, docs, tools and manifests excluded. Engine 66674 -> 66689; other production scopes unchanged. Relative to 716197c49 (143682): delta +412. Method: unchanged tools/production_loc.py at ca153a7f6, SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6; python3 -B tools/production_loc.py --root , identical source scope from git archives of first parent ca153a7f6 and final staged tree 86c9888203500d3086f02536169e44f5a3751f7e. The committed tree must match it. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 17 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 68 ++++++++---- engine/crates/layerfs-nfs/src/kernel.rs | 17 +-- engine/crates/layerfs-nfs/tests/write.rs | 103 +++++++++++++++++- 4 files changed, 167 insertions(+), 38 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index f1e78e226f..e552a4f577 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -195,7 +195,7 @@ Refresh after an install is covered in | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 65,536 companion index entries | Reclaim orphan companions whose main file is not in `Table::by_name`; if still at the bound, CREATE answers `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 companion index entries | Reclaim orphan companions whose main file is not in `Table::by_name`; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs the export/namespace, current count and limit at most once per 60 seconds 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), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | @@ -211,6 +211,21 @@ export removes the entire `/.appledouble/` directory remounts, daemon restarts and Commits do not retain them. A name is AppleDouble when it starts with `._` and has at least one more byte. +CREATE checks an existing companion name, checks the entry limit, reclaims +orphans and inserts a new serial under one companion-lock hold, so concurrent +GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. An +existing name is still usable when the table is full. `Table::by_name` keeps +every observed main-file name, including all seen hard-link aliases, rather +than only the latest name of an inode. Unlink and rename remove known vanished +names; retiring an inode removes all keys for its serial. Reclamation therefore +keeps a companion when a second name for its main file was observed. The index +remains an observation cache: retained names can delay reclamation. Its existing +`Table::names` admission bound is unchanged; a separate bound on `by_name` +(alias keys) remains future work. The companion entry limit stays 65,536; NOSPC +reports exhaustion of this export resource, not a permission failure or a +per-user quota. The first full-table refusal logs immediately, with later logs +at least 60 seconds apart; every refusal still increments `names_refused`. + A body is written out from a snapshot taken under the companion lock, as a new `..tmp` opened with `create_new`, and is switched to that file only if the companion is still the one the snapshot saw (same `used` tick, still diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index b156bc0220..b815495be5 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -30,7 +30,7 @@ //! file drops its paired `._` companion and any spilled file with it; //! when [`HELD`] is reached, orphan companions whose main file is no longer in //! the export's name index are reclaimed first, and only if [`HELD`] live -//! companions still remain does `CREATE` answer `NFS3ERR_ACCES`. +//! companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. use crate::{ attributes::Status, change::{How, Sattr, Tickets, Wcc}, @@ -46,7 +46,7 @@ use std::{ os::unix::fs::{DirBuilderExt, FileExt, OpenOptionsExt}, path::{Path, PathBuf}, sync::atomic::{AtomicU64, Ordering}, - time::{SystemTime, UNIX_EPOCH}, + time::{Duration, Instant, SystemTime, UNIX_EPOCH}, }; /// The first serial of the export's own companions, far above any serial the @@ -98,6 +98,7 @@ pub(crate) struct Companions { spill_dir: Option, resident_budget: usize, held_limit: usize, + last_refusal_log: Option, } impl Default for Companions { fn default() -> Self { @@ -110,6 +111,7 @@ impl Default for Companions { spill_dir: None, resident_budget: RESIDENT_BYTES, held_limit: HELD, + last_refusal_log: None, } } } @@ -450,7 +452,25 @@ impl Kernel { tickets: &mut Tickets, ) -> Result<(ViewStat, Wcc), Status> { let directory = self.directory_wcc(parent); - if let Some(stat) = self.companion_named(parent, name) { + if parent != self.root() && !self.table().parents.contains_key(&parent) { + return Err(Status::NotDir); + } + let mut companions = self.companions(); + // Never acquire the kernel table under the companion lock. If full, + // snapshot live names first, then recheck everything under one lock. + let live = if companions.files.len() >= companions.held_limit { + drop(companions); + let live = self.table().by_name.keys().cloned().collect::>(); + companions = self.companions(); + Some(live) + } else { + None + }; + let named = (parent, name.to_vec()); + if let Some(&serial) = companions.names.get(&named) { + let stat = Companions::stat(serial, &companions.files[&serial]); + companions.use_serial(serial); + drop(companions); // Opened again: UNCHECKED applies its size, as an open with // truncation would; GUARDED and EXCLUSIVE find it taken. let How::Unchecked(sattr) = how else { @@ -468,27 +488,31 @@ impl Kernel { None => Ok((stat, directory)), }; } - if parent != self.root() && !self.table().parents.contains_key(&parent) { - return Err(Status::NotDir); - } - let at_limit = { - let companions = self.companions(); - companions.files.len() >= companions.held_limit + let reclaimed = if companions.files.len() >= companions.held_limit { + companions.reclaim_orphans(live.as_ref().expect("full table has a live-name snapshot")) + } else { + Vec::new() }; - let mut reclaimed = Vec::new(); - if at_limit { - let live: HashSet<(u64, Vec)> = self.table().by_name.keys().cloned().collect(); - let mut companions = self.companions(); - if companions.files.len() >= companions.held_limit { - reclaimed = companions.reclaim_orphans(&live); - } - } - unlink_paths(reclaimed); - let mut companions = self.companions(); if companions.files.len() >= companions.held_limit { + let held = companions.files.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); - self.names_refused.fetch_add(1, Ordering::Relaxed); - return Err(Status::Access); + 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 { @@ -499,7 +523,6 @@ impl Kernel { let serial = SERIALS + companions.next; companions.next += 1; let used = companions.tick(); - let named = (parent, name.to_vec()); companions.names.insert(named.clone(), serial); companions.files.insert( serial, @@ -514,6 +537,7 @@ impl Kernel { let file = &companions.files[&serial]; let stat = Companions::stat(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/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 85f82f4eb8..b8b11cb7ca 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -106,7 +106,9 @@ 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 -> last use, for the collection order. pub used: HashMap, @@ -423,11 +425,7 @@ impl Kernel { table.used.insert(stat.serial, tick); 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); - } - } + table.names.insert(stat.serial, named.clone()); table.by_name.insert(named, stat.serial); } } @@ -486,11 +484,8 @@ 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.names.remove(&serial); + table.by_name.retain(|_, held| *held != serial); table.used.remove(&serial); table.verifiers.retain(|_, entry| entry.1 != serial); let directories: Vec = table diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index f3025bfffb..daa7419964 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"; @@ -722,7 +723,7 @@ fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up // 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_ACCES`. + // 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"); @@ -773,10 +774,23 @@ fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up } // Now all 8 slots belong to live main files: one more companion CREATE - // finds no orphans to reclaim and answers `NFS3ERR_ACCES`. + // 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(); - assert_eq!(c2.touch(&root2, b"._extra", 0o644).map(|_| ()), Err(ACCES)); - assert_eq!(server2.held().names_refused, 1); + 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(); @@ -786,6 +800,87 @@ fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up 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_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; From fac912440dae245a180aa08944dc118d17eb05df Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 10 Nov 2026 09:26:13 +0800 Subject: [PATCH 05/16] feat(nfs): decode AppleDouble companions into their inode's attributes (lp73) A `._name` companion the export creates while it knows its main file now belongs to that inode rather than to one name: every hard-link alias reaches it, RENAME of the main file keeps it reachable, unlink or a replacing RENAME only unbinds the paired `._` name, and the inode's last name (or its silly rename) drops it. Its FinderInfo and extended attributes are kept under that inode's serial, once per inode and not once per name. After every resident write, resize or rename of such a companion, the new codec (`apple_double_codec`) decides whether the body is a whole image in the client's own layout: an AppleDouble v2 header whose FinderInfo entry runs into the ATTR table, values packed in entry order, the client's empty resource fork or none, the whole length a number of 4 KiB units. It decodes the image and requires that encoding the decoded form gives back exactly the same bytes, so a synthesized READ is byte for byte what the client wrote. Each attribute entry keeps the alignment padding the client left after its name (it does not clear what a shorter name replaced), and nothing else. A whole image takes no slot of the 65,536-entry index bound, which is what keeps a tree's attribute copies from exhausting it; it is kept decoded while the decoded budget takes it (512 MiB in all, 128 KiB each), and otherwise keeps its bytes as written. Every state of the client's write sequence is served as written: a header, a delete and rebuild, an edit that leaves the layout incomplete, a truncation or a half-written image stay the client's own bytes, and only a whole image is replaced by its decoded form. A resource fork, another layout, a companion whose main file the export never saw, or an edit to a spilled body keeps the #636 stored-as-written path and its slot, with the bound, NOSPC, the rate-limited log and orphan reclamation unchanged. No attribute is dropped: provenance, quarantine, FinderInfo and user attributes are all kept. Persistence is unchanged: companions remain export-local and never reach the Store or a Commit. Released reports slotted/decoded companions, decoded bytes, and releasing an export with companions logs them. The spill-file helpers move unchanged into `apple_double_spill` to keep `apple_double.rs` under the file ceiling. Tests: new `tests/apple_double_codec.rs` (hand-built images, 0 B to 100 KiB values, many attributes, FinderInfo, resource forks, kept alignment padding, truncated, altered and foreign bytes) and `tests/apple_double_decode.rs` (the client's write sequence, whole images taking no slot, hard links, renames and replacements, the silly rename, the slot bound and the stored-as-written fallback). No test deleted. Production LOC: 156721 -> 157237 (delta +516); scope core/engine/control/api first-party product source; counted with tools/production_loc.py on git-archive snapshots of the parent commit 640a30483 and the staged tree; tests, docs and tools excluded. engine 73491 -> 74007. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 44 +- engine/crates/layerfs-nfs/src/apple_double.rs | 670 +++++++++++------- .../layerfs-nfs/src/apple_double_codec.rs | 342 +++++++++ .../layerfs-nfs/src/apple_double_spill.rs | 151 ++++ engine/crates/layerfs-nfs/src/change.rs | 4 + engine/crates/layerfs-nfs/src/kernel.rs | 31 +- engine/crates/layerfs-nfs/src/lib.rs | 2 + .../layerfs-nfs/tests/apple_double_codec.rs | 263 +++++++ .../layerfs-nfs/tests/apple_double_decode.rs | 425 +++++++++++ 9 files changed, 1659 insertions(+), 273 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/apple_double_codec.rs create mode 100644 engine/crates/layerfs-nfs/src/apple_double_spill.rs create mode 100644 engine/crates/layerfs-nfs/tests/apple_double_codec.rs create mode 100644 engine/crates/layerfs-nfs/tests/apple_double_decode.rs diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index e552a4f577..2809daea35 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -180,13 +180,20 @@ Refresh after an install is covered in ```text CREATE "._name" (refuse_apple_double = true) - regular file --> Companions (export index in memory; body resident or spilled) + regular file --> Companions (export index in memory; body resident, spilled or decoded) serial >= SERIALS = 1 << 62 + main inode known from Table::by_name --> that inode's companion: + any name of the inode reads it, RENAME follows the inode, + its last name drops it resident body <= RESIDENT_BYTES (32 MiB) in all; older bodies spill to /.appledouble// (dir 0700, file 0600; written as ..tmp and renamed on adoption; pread/pwrite outside the companion lock, opened by path per call, never held open) + a whole AppleDouble image decodes (apple_double_codec): + FinderInfo + attributes kept under the main inode's serial, + reads synthesize the client's own bytes, takes no HELD slot; + <= DECODED_BYTES in all, each <= DECODED_ENTRY_BYTES LOOKUP GETATTR ACCESS READ WRITE SETATTR COMMIT REMOVE, RENAME to another "._" name: served here READDIR: not listed; engine: never called @@ -195,15 +202,40 @@ Refresh after an install is covered in | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 65,536 companion index entries | Reclaim orphan companions whose main file is not in `Table::by_name`; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs the export/namespace, current count and limit at most once per 60 seconds per export | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 companion index entries not holding a whole image | Reclaim orphan companions whose main inode (or, for a companion whose main file the export never saw, whose main file) is no longer known; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs the export/namespace, current count and limit at most once per 60 seconds 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), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | +| `DECODED_BYTES` | 512 MiB counted over all decoded companions | A further whole image keeps its bytes as written, and still takes no slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB counted per decoded companion | That image keeps its bytes as written, and still takes no slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | On NFSv3 the macOS client stores extended attributes and resource forks in `._` files. Keeping their index in export memory and spilling excess bodies to the export's scratch directory lets `cp`, `copyfile`, `ditto` and `tar` succeed without losing companion bytes during the mount, while nothing -reaches the Workspace, SQLite overlay or a Commit. Removing, silly-renaming or +reaches the Workspace, SQLite overlay or a Commit. + +A companion whose main inode the export knows belongs to that inode rather than +to one name: every hard-link alias reaches it, RENAME of the main file keeps it +reachable under the new name, unlink or a replacing RENAME of the main file only +unbinds the paired `._` name, and the inode's last name (or its silly rename) +drops it. Its FinderInfo and extended attributes are therefore kept once per +inode, not once per name. When a write leaves such a companion holding a whole +AppleDouble image the client laid out itself (`apple_double_codec::Image`), the +body is decoded: the FinderInfo, every attribute name and value, the client's +alignment padding after a name, the tag and the resource-fork entry are kept, +and each READ encodes the image again. Decoding requires that the decoded form +encode back to the very same bytes, so a synthesized read is byte for byte what +the client wrote; a state the client is still writing (a header, a truncation, +an edit that leaves the layout incomplete) stays its own bytes, and an image +with a resource fork or another layout keeps the stored-as-written path. A +companion that is a whole image takes no slot of `HELD`, which is what keeps a +large tree's attribute copies from exhausting the index bound; the bound, its +`NFS3ERR_NOSPC`, its rate-limited log and orphan reclamation remain the fallback +for everything that is not a whole image. No attribute is dropped: +`com.apple.provenance`, `com.apple.quarantine`, `com.apple.FinderInfo` and user +attributes are all kept, and nothing here reaches the Store or a Commit. + +Removing, silly-renaming or replacing a main file drops its paired `._` companion and unlinks any spilled file at once. Companions remain mount-session state: releasing the export removes the entire `/.appledouble/` directory @@ -211,6 +243,12 @@ export removes the entire `/.appledouble/` directory remounts, daemon restarts and Commits do not retain them. A name is AppleDouble when it starts with `._` and has at least one more byte. +The image layout, the decoded form, and the requirement that a decoded image +encode back to exactly the bytes the client wrote, are in +[`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs); +the spill helpers are in +[`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs). + CREATE checks an existing companion name, checks the entry limit, reclaims orphans and inserts a new serial under one companion-lock hold, so concurrent GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. An diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index b815495be5..87eec3d0e9 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -16,22 +16,37 @@ //! directory it names, so its `wcc_data` answers both halves from the last //! facts the export saw for it (see [`Kernel::directory_wcc`]). //! -//! Every companion keeps its index entry in memory (at most [`HELD`] -//! companions, each of 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 (one file per companion serial, read and written with -//! `pread`/`pwrite` outside the companion lock). 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, and no descriptor -//! is kept for a spilled body: an operation opens its file by path and closes -//! it again, so open descriptors grow with concurrent operations and not with -//! the number of spilled companions. Removing or replacing a main -//! file drops its paired `._` companion and any spilled file with it; -//! when [`HELD`] is reached, orphan companions whose main file is no longer in -//! the export's name index are reclaimed first, and only if [`HELD`] live -//! companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. +//! 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. +//! +//! 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::{ + create_spilled, io_status, now, spill_path, touch, unlink_paths, Edit, Room, + }, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, @@ -43,37 +58,48 @@ use std::{ collections::{HashMap, HashSet}, fs::{self, File, OpenOptions}, io, - os::unix::fs::{DirBuilderExt, FileExt, OpenOptionsExt}, + os::unix::fs::FileExt, path::{Path, PathBuf}, - sync::atomic::{AtomicU64, Ordering}, - time::{Duration, Instant, SystemTime, UNIX_EPOCH}, + sync::atomic::Ordering, + time::{Duration, Instant}, }; /// 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. +/// 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. pub const RESIDENT_BYTES: usize = 32 << 20; -/// Mode of a companion created without one. -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); +/// 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; + +/// 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), } struct Companion { - named: (u64, Vec), + /// 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, @@ -83,9 +109,29 @@ impl Companion { fn resident_len(&self) -> usize { match &self.body { Body::Resident(bytes) => bytes.len(), - Body::Spilled => 0, + Body::Spilled | Body::Decoded(_) => 0, + } + } + fn decoded_cost(&self) -> usize { + match &self.body { + Body::Decoded(image) => image.cost(), + 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, } /// The companions of one export. @@ -93,8 +139,14 @@ pub(crate) struct Companions { next: u64, tick: u64, files: HashMap, - names: HashMap<(u64, Vec), u64>, + names: HashMap, + /// Main inode serial -> the companion holding its FinderInfo and + /// attributes. + inodes: HashMap, + slotted: usize, resident_bytes: usize, + decoded: usize, + decoded_bytes: usize, spill_dir: Option, resident_budget: usize, held_limit: usize, @@ -107,7 +159,11 @@ impl Default for Companions { tick: 0, files: HashMap::new(), names: HashMap::new(), + inodes: HashMap::new(), + slotted: 0, resident_bytes: 0, + decoded: 0, + decoded_bytes: 0, spill_dir: None, resident_budget: RESIDENT_BYTES, held_limit: HELD, @@ -136,12 +192,105 @@ impl Companions { subdirs: 0, } } - fn take_serial(&mut self, serial: u64) -> Option { + /// Adds `file` to the index and to the slot and byte counts. + fn attach(&mut self, serial: u64, file: Companion) { + self.slotted += usize::from(file.slotted()); + 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 keys stay for + /// the caller to unindex. + fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; - self.names.remove(&file.named); + self.slotted -= usize::from(file.slotted()); 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. + 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.whole = true; + file.used = tick; + touch(&mut file.metadata); + self.attach(serial, file); + true + } + /// Decides whether `file`'s body is a whole image: a decoded body always + /// is; a resident body of an inode's companion 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) { + file.whole = matches!(file.body, Body::Decoded(_)); + let (Some(_), Body::Resident(bytes)) = (file.inode, &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); + } + } + fn take_serial(&mut self, serial: u64) -> Option { + let file = self.detach(serial)?; + self.unindex(serial, &file); match file.body { - Body::Resident(_) => None, + Body::Resident(_) | Body::Decoded(_) => None, Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), } } @@ -169,10 +318,13 @@ impl Companions { return Ok(false); } fs::rename(temp, path).map_err(|e| io_status(&e))?; - let old = file.resident_len(); + let mut file = self.detach(serial).ok_or(Status::Stale)?; file.body = Body::Spilled; + // 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.resident_bytes -= old; + self.attach(serial, file); Ok(true) } fn oldest_resident(&self, skip: Option) -> Option { @@ -185,16 +337,25 @@ impl Companions { .min_by_key(|(_, file)| file.used) .map(|(serial, _)| *serial) } - /// Reclaims companions whose paired main file `(parent, name)` is not in - /// `live_names`. Returns any spilled file paths to unlink outside the lock. - fn reclaim_orphans(&mut self, live_names: &HashSet<(u64, Vec)>) -> Vec { + /// Reclaims companions whose main inode is not in `live_serials`, or whose + /// main file `(parent, name)` is not in `live_names` when the export never + /// knew its inode. Returns any spilled file paths to unlink outside the + /// lock. + fn reclaim_orphans( + &mut self, + live_names: &HashSet, + live_serials: &HashSet, + ) -> Vec { let orphans: Vec = self .files .iter() - .filter(|(_, file)| { - let (parent, ref name) = file.named; - name.strip_prefix(b"._") - .is_some_and(|main| !live_names.contains(&(parent, main.to_vec()))) + .filter(|(_, file)| match file.inode { + Some(inode) => !live_serials.contains(&inode), + None => { + let (parent, ref name) = file.named; + name.strip_prefix(b"._") + .is_some_and(|main| !live_names.contains(&(parent, main.to_vec()))) + } }) .map(|(serial, _)| *serial) .collect(); @@ -203,130 +364,15 @@ impl Companions { .filter_map(|serial| self.take_serial(serial)) .collect() } -} -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`. -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. Two calls spilling the same `serial` write different -/// temporary files, and only the call whose file is adopted renames it to the -/// companion's own name. Only this user reads companion bodies, so the modes -/// are set here rather than left to the caller's umask. -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. -fn unlink_paths(paths: impl IntoIterator) { - for path in paths { - drop(fs::remove_file(path)); - } -} -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(), - } -} -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. -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. - 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`. - 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. - 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)), + fn holding(&self) -> Holding { + Holding { + held: self.files.len(), + slotted: self.slotted, + resident_bytes: self.resident_bytes, + decoded: self.decoded, + decoded_bytes: self.decoded_bytes, } } - /// Records the edit's length on `file`. - fn record(&self, file: &mut Companion) { - file.len = match self { - Edit::Write { .. } => file.len.max(self.target_len()), - Edit::Size(size) => *size, - }; - } -} -/// Where [`Kernel::edit_resident`] found a companion's body. -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(ViewStat), - /// On disk: finish with its file outside the lock. - Spilled, - /// Resident, but growing it needs this many more budget bytes first. - Grow(usize), } /// 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 @@ -334,6 +380,17 @@ enum Room { 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, + } +} +/// 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 { serial >= SERIALS @@ -359,6 +416,13 @@ impl Kernel { 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() + } /// 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. @@ -392,6 +456,7 @@ impl Kernel { 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)?; @@ -432,14 +497,13 @@ impl Kernel { 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 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 stat = companions - .files - .get(&serial) - .map(|file| Companions::stat(serial, file))?; + let serial = companions.resolve(&(parent, name.to_vec()), main)?; + let stat = Companions::stat(serial, companions.files.get(&serial)?); companions.use_serial(serial); Some(stat) } @@ -455,19 +519,27 @@ impl Kernel { if parent != self.root() && !self.table().parents.contains_key(&parent) { return Err(Status::NotDir); } + let main = self.main_of(parent, name); let mut companions = self.companions(); - // Never acquire the kernel table under the companion lock. If full, - // snapshot live names first, then recheck everything under one lock. - let live = if companions.files.len() >= companions.held_limit { + // Never acquire the kernel table under the companion lock. If the + // index bound is reached, snapshot the live names and inodes first, + // then recheck everything under one lock. + let live = if companions.slotted >= companions.held_limit { drop(companions); - let live = self.table().by_name.keys().cloned().collect::>(); + let live = { + let table = self.table(); + ( + table.by_name.keys().cloned().collect::>(), + table.by_name.values().copied().collect::>(), + ) + }; companions = self.companions(); Some(live) } else { None }; let named = (parent, name.to_vec()); - if let Some(&serial) = companions.names.get(&named) { + if let Some(serial) = companions.resolve(&named, main) { let stat = Companions::stat(serial, &companions.files[&serial]); companions.use_serial(serial); drop(companions); @@ -488,13 +560,12 @@ impl Kernel { None => Ok((stat, directory)), }; } - let reclaimed = if companions.files.len() >= companions.held_limit { - companions.reclaim_orphans(live.as_ref().expect("full table has a live-name snapshot")) - } else { - Vec::new() + let reclaimed = match (&live, companions.slotted >= companions.held_limit) { + (Some((names, serials)), true) => companions.reclaim_orphans(names, serials), + _ => Vec::new(), }; - if companions.files.len() >= companions.held_limit { - let held = companions.files.len(); + if companions.slotted >= companions.held_limit { + let held = companions.slotted; let limit = companions.held_limit; let log = companions .last_refusal_log @@ -523,49 +594,43 @@ impl Kernel { let serial = SERIALS + companions.next; companions.next += 1; let used = companions.tick(); - companions.names.insert(named.clone(), serial); - companions.files.insert( - serial, - Companion { - named, - len: 0, - body: Body::Resident(Vec::new()), - metadata, - used, - }, - ); - let file = &companions.files[&serial]; - let stat = Companions::stat(serial, file); + let file = Companion { + named, + inode: main, + whole: false, + len: 0, + body: Body::Resident(Vec::new()), + metadata, + used, + }; + let stat = Companions::stat(serial, &file); + companions.index(serial, &file); + companions.attach(serial, file); drop(companions); unlink_paths(reclaimed); self.names_detached.fetch_add(1, Ordering::Relaxed); Ok((stat, directory)) } - /// Takes the companion held under `(parent, name)` out of the index and - /// unlinks its spilled file; `true` when one was held. - fn companion_take(&self, parent: u64, name: &[u8]) -> bool { + /// 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 Some(serial) = companions.names.get(&(parent, name.to_vec())).copied() else { - return false; - }; + let serial = companions.resolve(&(parent, name.to_vec()), main)?; companions.take_serial(serial) }; unlink_paths(spilled); - true - } - /// 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 { - self.companion_take(parent, name) - .then(|| self.directory_wcc(parent)) - } - /// Drops the companion `._` paired with `name` in `parent`, if one - /// is held, when `name` itself is removed, silly-renamed or replaced by - /// `RENAME`. 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. + 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; @@ -573,10 +638,39 @@ impl Kernel { let mut paired = Vec::with_capacity(2 + name.len()); paired.extend_from_slice(b"._"); paired.extend_from_slice(name); - self.companion_take(parent, &paired); + 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. + /// 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. pub(crate) fn companion_rename( &self, from: u64, @@ -584,26 +678,33 @@ 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); } } - companions.names.remove(&(from, name.to_vec())); - companions.names.insert(target.clone(), serial); let tick = companions.tick(); - if let Some(file) = companions.files.get_mut(&serial) { - file.named = target; - file.used = tick; + let mut file = companions.detach(serial)?; + companions.unindex(serial, &file); + file.named = target; + file.inode = to_main; + file.used = tick; + // A client may write a companion under another name first. + if matches!(file.body, Body::Resident(_) | Body::Decoded(_)) { + companions.classify(&mut file); } + companions.index(serial, &file); + companions.attach(serial, file); } unlink_paths(replaced_path); Some(Ok(())) @@ -631,6 +732,13 @@ impl Kernel { 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); @@ -692,50 +800,79 @@ impl Kernel { // Only other calls changing this companion in every round get here. Err(Status::Io) } - /// Applies `edit` to `serial`'s resident body while the budget holds it, - /// recording its length, recency and time under the same lock so no other - /// call ever sees a body and a length that disagree. + /// 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 guard = self.companions(); - let Companions { - files, - tick, - resident_bytes, - resident_budget, - .. - } = &mut *guard; - let avail = resident_budget.saturating_sub(*resident_bytes); - let Some(file) = files.get_mut(&serial) else { - return Err(Status::Stale); - }; - let before = match &mut file.body { + 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) => { - let need = target.saturating_sub(bytes.len()); - if need > avail { - return Ok(Room::Grow(need)); + Body::Resident(bytes) => target.saturating_sub(bytes.len()), + Body::Decoded(image) => target.max(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)); } - let before = bytes.len(); - edit.memory(bytes); - before + } + 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.record(file); + edit.memory(&mut bytes); + file.body = Body::Resident(bytes); + record(edit, &mut file); touch(&mut file.metadata); - *tick += 1; - file.used = *tick; - *resident_bytes = *resident_bytes - before + file.resident_len(); - Ok(Room::Resident(Companions::stat(serial, file))) + file.used = tick; + companions.classify(&mut file); + let stat = Companions::stat(serial, &file); + companions.attach(serial, file); + Ok(Room::Resident(stat)) } - /// Records an applied edit on `serial` and answers its stat. + /// Records an edit applied to `serial`'s spilled file and answers its + /// 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 file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - edit.record(file); + let mut file = companions.detach(serial).ok_or(Status::Stale)?; + record(edit, &mut file); file.used = tick; + file.whole = false; touch(&mut file.metadata); - Ok(Companions::stat(serial, file)) + let stat = Companions::stat(serial, &file); + companions.attach(serial, file); + Ok(stat) } /// SETATTR of a companion: mode, size and modification time; the /// owner is the export's identity, as for every inode. @@ -789,8 +926,8 @@ impl Kernel { Ok((after.clone(), (Some(before), Some(after)))) } /// Drops every companion and removes the export's spill directory; returns - /// how many companions it held and their resident payload bytes. - pub(crate) fn companions_release(&self) -> (usize, usize) { + /// 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(); @@ -799,11 +936,22 @@ impl Kernel { if let Some(dir) = dir { drop(fs::remove_dir_all(dir)); } - (held.files.len(), held.resident_bytes) + let holding = held.holding(); + if holding.held > 0 { + eprintln!( + "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 + ); + } + holding } - /// Companions held now and their resident payload bytes. - pub(crate) fn companions_held(&self) -> (usize, usize) { - let companions = self.companions(); - (companions.files.len(), companions.resident_bytes) + /// What the companion index holds now. + pub(crate) fn companions_held(&self) -> Holding { + self.companions().holding() } } 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/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/change.rs b/engine/crates/layerfs-nfs/src/change.rs index bc3904342d..eb0f144d53 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -574,6 +574,10 @@ impl Kernel { 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(); diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index b8b11cb7ca..d2e108f1b5 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -516,6 +516,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) { @@ -776,8 +778,8 @@ impl Kernel { /// 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, companion_bytes) = self.companions_release(); - let released = self.holdings(&table, companions, companion_bytes); + let companions = self.companions_release(); + let released = self.holdings(&table, companions); for (serial, held) in table.files { self.close_file(serial, held.handle); } @@ -798,15 +800,18 @@ impl Kernel { /// Current holdings, for diagnostics. pub fn held(&self) -> Released { let table = self.table(); - let (companions, companion_bytes) = self.companions_held(); - self.holdings(&table, companions, companion_bytes) + let companions = self.companions_held(); + self.holdings(&table, companions) } /// What this export holds now, as [`Released`] reports it. - fn holdings(&self, table: &Table, companions: usize, companion_bytes: usize) -> Released { + fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { let count = |counter: &AtomicU64| counter.load(Ordering::Relaxed); Released { - companions, - companion_bytes, + 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(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -909,10 +914,18 @@ 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 the export's index (see [`crate::apple_double`]). + /// AppleDouble companions held in the export's index (see + /// [`crate::apple_double`]), whole images included. pub companions: usize, - /// AppleDouble companion payload bytes currently resident in memory. + /// 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, + 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/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index f5cb633717..ca288a9089 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -17,6 +17,8 @@ #![forbid(unsafe_code)] 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/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); +} 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..9acdc1cdaf --- /dev/null +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -0,0 +1,425 @@ +//! 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; +#[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, NOENT, STALE}; +use layerfs_nfs::apple_double_codec::{Attribute, Image}; +use std::{ + fs, + net::TcpListener, + path::{Path, PathBuf}, + time::Duration, +}; + +const NOSPC: u32 = 28; +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 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"); + 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(); +} + +#[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(); +} From 0ecb4c578d9bc1220f2977a05d52216edbcbf91e Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 10 Nov 2026 11:27:08 +0800 Subject: [PATCH 06/16] fix(nfs): edit decoded companions, slot unknown mains, rename one name (lp73) Three review findings on fac912440: - `adopt_spilled` takes a decoded body too: an edit that leaves a whole image not whole (a mid-image write, a header rewrite) now spills the encoded image and applies the write to that file, instead of answering NFS3ERR_IO after three rounds. A decoded body's resident need is its edited length rather than its image length, so truncating it needs no room for the image and evicts no other body. - `keep_decoded` and `classify` hold `file.inode.is_some()`: a companion whose main file the export does not know is never a whole image. It keeps the client's bytes as written, takes a `HELD` slot and can be reclaimed as an orphan, including after a RENAME onto a name whose main file is unknown (a decoded body is written back out as the client's bytes there). - `Kernel::renamed` takes the source name as well and removes only `(from, name)` from `Table::by_name`, so an inode's other names, its hard links, keep reaching its companion after another name is renamed. Tests: three new cases in `tests/apple_double_decode.rs`: a decoded companion edited under a 1 KiB resident budget (mid-image write, truncation, rewrite, and an unrelated resident body that must not be evicted for it); a companion with no main file not decoded and reclaimed by the index bound; hard links a and b, RENAME a -> c, `._b` still LOOKUPs before and after c goes. Reverting each fix alone makes its test fail (NFS3ERR_IO; decoded=2/slotted=0; NFS3ERR_NOENT). No tests deleted. Docs: nfs.md records that a RENAME leaves the inode's other names reaching the companion and that a body which stops being decodable is written back out. Production LOC: 157237 -> 157253 (delta +16); scope core/crates, engine/crates, control/crates and api/crates product sources (src/ and shipped SQL) counted by tools/production_loc.py on the parent tree fac912440 and this committed tree; test, doc and tooling changes are excluded. --- docs/architecture/engine/kernel-routes/nfs.md | 7 +- engine/crates/layerfs-nfs/src/apple_double.rs | 48 +++-- engine/crates/layerfs-nfs/src/change.rs | 2 +- engine/crates/layerfs-nfs/src/kernel.rs | 17 +- .../layerfs-nfs/tests/apple_double_decode.rs | 198 ++++++++++++++++++ 5 files changed, 249 insertions(+), 23 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 2809daea35..8a2e3d9dcf 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -216,7 +216,8 @@ reaches the Workspace, SQLite overlay or a Commit. A companion whose main inode the export knows belongs to that inode rather than to one name: every hard-link alias reaches it, RENAME of the main file keeps it -reachable under the new name, unlink or a replacing RENAME of the main file only +reachable under the new name and leaves the inode's other names reaching it, +unlink or a replacing RENAME of the main file only unbinds the paired `._` name, and the inode's last name (or its silly rename) drops it. Its FinderInfo and extended attributes are therefore kept once per inode, not once per name. When a write leaves such a companion holding a whole @@ -227,7 +228,9 @@ and each READ encodes the image again. Decoding requires that the decoded form encode back to the very same bytes, so a synthesized read is byte for byte what the client wrote; a state the client is still writing (a header, a truncation, an edit that leaves the layout incomplete) stays its own bytes, and an image -with a resource fork or another layout keeps the stored-as-written path. A +with a resource fork, another layout or a main file the export does not know +keeps the stored-as-written path, and a body that becomes one of those is +written back out as the client's own bytes. A companion that is a whole image takes no slot of `HELD`, which is what keeps a large tree's attribute copies from exhausting the index bound; the bound, its `NFS3ERR_NOSPC`, its rate-limited log and orphan reclamation remain the fallback diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 87eec3d0e9..ea66da7515 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -241,10 +241,18 @@ impl Companions { 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; }; @@ -268,13 +276,26 @@ impl Companions { self.attach(serial, file); true } - /// Decides whether `file`'s body is a whole image: a decoded body always - /// is; a resident body of an inode's companion 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. `file` must be detached from the index. fn classify(&self, file: &mut Companion) { + if file.inode.is_none() { + let decoded = match &file.body { + Body::Decoded(image) => Some(image.encode()), + Body::Resident(_) | Body::Spilled => None, + }; + if let Some(bytes) = decoded { + file.body = Body::Resident(bytes); + } + file.whole = false; + return; + } file.whole = matches!(file.body, Body::Decoded(_)); - let (Some(_), Body::Resident(bytes)) = (file.inode, &file.body) else { + let Body::Resident(bytes) = &file.body else { return; }; let Some(image) = Image::compact(bytes) else { @@ -297,8 +318,9 @@ impl Companions { /// 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, when nothing touched it since `used` was read and - /// its body is still resident. A body another call changed or already - /// spilled stays: `Ok(false)` then, and `temp` is the caller's to unlink. + /// its body is still in memory (resident or decoded). A body another call + /// changed or already spilled stays: `Ok(false)` then, and `temp` is the + /// caller's to unlink. fn adopt_spilled( &mut self, serial: u64, @@ -314,7 +336,7 @@ impl Companions { let Some(file) = self.files.get_mut(&serial) else { return Err(Status::Stale); }; - if !spill_applies(used, file.used, matches!(file.body, Body::Resident(_))) { + if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { return Ok(false); } fs::rename(temp, path).map_err(|e| io_status(&e))?; @@ -376,7 +398,7 @@ impl Companions { } /// 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 resident, so no call wrote to it while the file was written. +/// 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 } @@ -813,7 +835,7 @@ impl Kernel { let need = match &file.body { Body::Spilled => return Ok(Room::Spilled), Body::Resident(bytes) => target.saturating_sub(bytes.len()), - Body::Decoded(image) => target.max(image.len()), + Body::Decoded(image) => edited_len(edit, image.len()), }; if need > avail { // The body does not fit the resident budget, but the edit may diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index eb0f144d53..bd249ec2f7 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -633,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 d2e108f1b5..51bfa017d8 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -447,15 +447,18 @@ 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()); + let named = (to, new_name.to_vec()); + let moved = (from, name.to_vec()); + if table.by_name.get(&moved) == Some(&serial) { + table.by_name.remove(&moved); + } 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); - } + *slot = named.clone(); table.by_name.insert(named, serial); } } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 9acdc1cdaf..4a06c92fe6 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -423,3 +423,201 @@ fn a_replaced_main_file_takes_its_companion_with_it() { 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"); + 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(); +} + +#[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_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(); +} From c0c83e3d36aefa5dcde98e4c222aeca2ecb9a849 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Tue, 10 Nov 2026 11:29:08 +0800 Subject: [PATCH 07/16] docs(nfs): reflow the companion paragraph after the rename wording (lp73) Docs only: rewraps the paragraph the previous commit extended, so its lines keep the file's ~80 column prose wrapping. No wording or behaviour change. Production LOC: 157253 -> 157253 (delta 0); docs only, counted with tools/production_loc.py on the parent tree and this tree. --- docs/architecture/engine/kernel-routes/nfs.md | 35 +++++++++---------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 8a2e3d9dcf..e3d9c5e314 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -217,24 +217,23 @@ reaches the Workspace, SQLite overlay or a Commit. A companion whose main inode the export knows belongs to that inode rather than to one name: every hard-link alias reaches it, RENAME of the main file keeps it reachable under the new name and leaves the inode's other names reaching it, -unlink or a replacing RENAME of the main file only -unbinds the paired `._` name, and the inode's last name (or its silly rename) -drops it. Its FinderInfo and extended attributes are therefore kept once per -inode, not once per name. When a write leaves such a companion holding a whole -AppleDouble image the client laid out itself (`apple_double_codec::Image`), the -body is decoded: the FinderInfo, every attribute name and value, the client's -alignment padding after a name, the tag and the resource-fork entry are kept, -and each READ encodes the image again. Decoding requires that the decoded form -encode back to the very same bytes, so a synthesized read is byte for byte what -the client wrote; a state the client is still writing (a header, a truncation, -an edit that leaves the layout incomplete) stays its own bytes, and an image -with a resource fork, another layout or a main file the export does not know -keeps the stored-as-written path, and a body that becomes one of those is -written back out as the client's own bytes. A -companion that is a whole image takes no slot of `HELD`, which is what keeps a -large tree's attribute copies from exhausting the index bound; the bound, its -`NFS3ERR_NOSPC`, its rate-limited log and orphan reclamation remain the fallback -for everything that is not a whole image. No attribute is dropped: +unlink or a replacing RENAME of the main file only unbinds the paired `._` name, +and the inode's last name (or its silly rename) drops it. Its FinderInfo and +extended attributes are therefore kept once per inode, not once per name. When a +write leaves such a companion holding a whole AppleDouble image the client laid +out itself (`apple_double_codec::Image`), the body is decoded: the FinderInfo, +every attribute name and value, the client's alignment padding after a name, the +tag and the resource-fork entry are kept, and each READ encodes the image again. +Decoding requires that the decoded form encode back to the very same bytes, so a +synthesized read is byte for byte what the client wrote; a state the client is +still writing (a header, a truncation, an edit that leaves the layout +incomplete) stays its own bytes, and an image with a resource fork, another +layout or a main file the export does not know keeps the stored-as-written path, +a body that becomes one of those being written back out as the client's own +bytes. A companion that is a whole image takes no slot of `HELD`, which is what +keeps a large tree's attribute copies from exhausting the index bound; the bound, +its `NFS3ERR_NOSPC`, its rate-limited log and orphan reclamation remain the +fallback for everything that is not a whole image. No attribute is dropped: `com.apple.provenance`, `com.apple.quarantine`, `com.apple.FinderInfo` and user attributes are all kept, and nothing here reaches the Store or a Commit. From 3ed05e4dadd2d2e0d8811cc7b6b9b15dfdf59cc5 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 02:39:40 +0000 Subject: [PATCH 08/16] docs(nfs): note the remaining ._ create overhead on macOS NFSv3 The AppleDouble section describes the companion machinery but not its remaining cost. State the known limitation: a create still pays extra `._` companion round-trips (about 5-6 RPCs per file) because macOS auto-tags new files with com.apple.provenance, and no server-side fix keeps xattr semantics. Production LOC: 160911 -> 160911 (delta 0) Scope: first-party product source in the four core, ten engine, eight control and four api crates; tests, docs, tools and third-party code excluded. Method: python3 tools/production_loc.py (files unchanged by this commit; a docs-only change keeps the combined total and its delta at 0). --- docs/architecture/engine/kernel-routes/nfs.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index e3d9c5e314..1ad46f34ef 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -314,6 +314,13 @@ elsewhere `vers=3,proto=tcp,port={port},mountport={port},mountproto=tcp,nolock,a Helper deadlines and teardown belong to the [daemon](../daemon/README.md). +## Known limitations + +On macOS over NFSv3, creating a file still incurs extra `._` AppleDouble +companion round-trips (about 5–6 RPCs per file) because the system auto-tags new +files with `com.apple.provenance`; there is currently no server-side fix that +preserves xattr semantics. + ## Related - [Ports](ports.md): the operations the export drives. From 5851b529a1b182adf6fbb9a39d3bf11d9f25574b Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 03:56:16 +0000 Subject: [PATCH 09/16] fix(nfs): drop a retired name's keys without scanning by_name (lp73) `Kernel::drop_unlinked` retired an inode's names by scanning the whole `Table::by_name` index (`retain(|_, held| *held != serial)`) under the table lock, and `entry_taken` never dropped a serial's previous name, so a name a lookup replaced stayed until the inode's last name went. `rm -rf` of N files therefore cost N x |by_name| -- up to the index's 4M names (LP636 review, blocking 1). - `Table::aliases` (serial -> names) remembers a hard-linked inode's names beyond `Table::names`, so `unbind_serial` drops exactly one serial's keys and nothing scans the index. - `entry_taken` retires the serial's old key at once when the engine reports one name (nlink 1): that inode cannot be reached under a second name. A hard-linked inode (nlink > 1) still keeps its aliases, which is why orphan reclamation keeps a companion when a second name of its main file was seen. - `renamed` and the failed resolution of a collected serial drop their key through the same helpers; `finish_unlink` unbinds through `Table::unbind_any` so the alias record goes with the name. The release counters and `Released` moved to `kernel/released.rs` (kernel.rs would otherwise pass the 999-line ceiling); the move changes no behavior. Tests: existing `layerfs-nfs` write/decode suites cover hard-link aliases, rename and reclamation (13 write + 9 decode cases, all pass). Production LOC: 160921 -> 160984 (delta +63) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 -B tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 3ab79db3d (160921) and this committed tree 900a8dc20 (160984). Engine 75363 -> 75426; other scopes unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/change.rs | 2 +- engine/crates/layerfs-nfs/src/kernel.rs | 200 +++++++++--------- .../crates/layerfs-nfs/src/kernel/released.rs | 97 +++++++++ 3 files changed, 193 insertions(+), 106 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/kernel/released.rs diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index bd249ec2f7..11f74ef414 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -464,7 +464,7 @@ impl Kernel { /// job itself retired skips the release jobs. fn finish_unlink(&self, parent: u64, name: &[u8], retire: Retire, detached: Option) { self.companion_drop_for(parent, name); - self.table().by_name.remove(&(parent, name.to_vec())); + self.table().unbind_any(&(parent, name.to_vec())); let Some(target) = detached else { return; }; diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 51bfa017d8..2852f2457c 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. @@ -110,6 +113,11 @@ pub(crate) struct Table { /// 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`]). @@ -130,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)] @@ -300,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) @@ -425,8 +478,29 @@ impl Kernel { table.used.insert(stat.serial, tick); if table.names.len() < NAMES_HELD || table.names.contains_key(&stat.serial) { let named = (parent, name.to_vec()); - table.names.insert(stat.serial, named.clone()); - table.by_name.insert(named, stat.serial); + if let Some(old) = table.names.insert(stat.serial, named.clone()) { + 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.bind_name(named, stat.serial); } } let extra = root || !table.lookups.insert(stat.serial); @@ -454,12 +528,16 @@ impl Kernel { let mut table = self.table(); let named = (to, new_name.to_vec()); let moved = (from, name.to_vec()); - if table.by_name.get(&moved) == Some(&serial) { - table.by_name.remove(&moved); - } - if let Some(slot) = table.names.get_mut(&serial) { - *slot = named.clone(); - table.by_name.insert(named, serial); + table.unbind_name(&moved, serial); + let remembered = match table.names.get_mut(&serial) { + Some(slot) => { + *slot = named.clone(); + true + } + None => false, + }; + if remembered { + table.bind_name(named, serial); } } pub(crate) fn forget(&self, serial: u64, count: u64) { @@ -487,8 +565,7 @@ impl Kernel { let mut table = self.table(); table.parents.remove(&serial); table.directory_stats.remove(&serial); - table.names.remove(&serial); - table.by_name.retain(|_, held| *held != serial); + table.unbind_serial(serial); table.used.remove(&serial); table.verifiers.retain(|_, entry| entry.1 != serial); let directories: Vec = table @@ -776,58 +853,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 = self.holdings(&table, companions); - 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(); - 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(), - directories: table.directories.len(), - lookups: table.lookups.len(), - silly: table.silly.len(), - retained: self.retained_count(), - 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), - } - } /// 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 { @@ -903,41 +928,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 the export's index (see - /// [`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, - 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. - 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..73a6321ee9 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -0,0 +1,97 @@ +//! 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, Table}; +use std::sync::atomic::{AtomicU64, 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 = self.holdings(&table, companions); + 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(); + 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(), + directories: table.directories.len(), + lookups: table.lookups.len(), + silly: table.silly.len(), + retained: self.retained_count(), + 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), + } + } +} + +/// 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 the export's index (see + /// [`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, + 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. + 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 b4d0222f169bc318011858cd3d86bbdaf12e0dd4 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 03:57:22 +0000 Subject: [PATCH 10/16] fix(nfs): edit a companion alone, reclaim without copying by_name (lp73) Four findings from the LP636 review of the AppleDouble companions, all in the export's own index. - Blocking 2. At the `HELD` bound every `._` CREATE copied all of `Table::by_name` into two HashSets (keys and values) -- a namespace-sized allocation on each refused create, taken under the table lock. Reclamation now walks the companion index instead: `Kernel::orphans` takes the table lock and, inside it, the companion lock (never the other order), asks each slotted companion whether its main inode still holds a name (O(1) through `Table::names`/`Table::aliases`, which the previous commit added) or, for one whose main file was never seen, whether its main name is still in `by_name`, and returns only the orphans. Work is bounded by the index, not the namespace. - A spilled whole image survived a RENAME onto a name whose main file is unknown as `inode=None, whole=true`, taking no slot and bypassing `HELD`. `companion_rename` classifies every body again under its destination, and `classify` keeps a body on disk's class only while the inode is known: an unknown destination makes it slotted. (A spilled body cannot be decoded there; that would read its file under the companion lock.) - `edit_companion` re-decided up to three optimistic rounds and then answered `NFS3ERR_IO` with no failure behind it, and `spill_for` looped with no bound. Each companion now carries its own edit gate (`Companion::editing`), held for the whole edit -- resident or disk -- so no other edit of that companion interleaves. `spill_for` bounds its rounds by the index and the caller writes out its own body (through `spill_gated`, which the gate makes authoritative) when it still does not fit, so no edit is refused for contention. - The spilled-edit length race (`ca153a7f6` fixed it for resident bodies): a concurrent truncate and WRITE left `len` at 10 with a 0-byte file, and every read then failed `NFS3ERR_IO`. With the gate, each edit's length is recorded with the bytes its own edit left, so the pair can only serialize. The body path (READ, WRITE, SETATTR, spill) moved to `apple_double/edit.rs`; `apple_double.rs` stays under the 999-line ceiling. New tests: - `apple_double_decode::a_spilled_body_renamed_off_its_inode_takes_its_slot` (spilled whole image renamed onto an unknown main must take its slot). - `write::a_spilled_companion_keeps_its_length_and_bytes_together` (a truncate and a write of one spilled companion, 64 rounds: the reported length always matches the bytes served). Docs: nfs.md records the reverse index, the per-companion edit gate, the bounded spill rounds and the RENAME reclassification. Tests: `layerfs-nfs` write 14 passed, decode 10 passed (nextest). Clippy `-p layerfs-nfs -p layerfs-daemon --all-targets -- -D warnings` clean; rustfmt clean for the changed files (the two upstream files listed in the LP636-CLOSE report still differ, unchanged here). Production LOC: 160984 -> 161033 (delta +49) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 -B tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 5851b529a (160984) and this committed tree 8dffa04d3 (161033). Engine 75426 -> 75475; other scopes unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 42 +- engine/crates/layerfs-nfs/src/apple_double.rs | 442 ++++-------------- .../layerfs-nfs/src/apple_double/edit.rs | 366 +++++++++++++++ 3 files changed, 484 insertions(+), 366 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/apple_double/edit.rs diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 1ad46f34ef..9026342d8c 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -233,7 +233,12 @@ a body that becomes one of those being written back out as the client's own bytes. A companion that is a whole image takes no slot of `HELD`, which is what keeps a large tree's attribute copies from exhausting the index bound; the bound, its `NFS3ERR_NOSPC`, its rate-limited log and orphan reclamation remain the -fallback for everything that is not a whole image. No attribute is dropped: +fallback for everything that is not a whole image. RENAME of a companion +classifies its body again under the destination: one moved onto a name whose +main file the export does not know is never a whole image and takes its slot, so +no move bypasses the index bound; a body on disk keeps the class the write that +spilled it left it, since decoding it would read its file under the companion +lock. No attribute is dropped: `com.apple.provenance`, `com.apple.quarantine`, `com.apple.FinderInfo` and user attributes are all kept, and nothing here reaches the Store or a Commit. @@ -256,12 +261,22 @@ orphans and inserts a new serial under one companion-lock hold, so concurrent GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. An existing name is still usable when the table is full. `Table::by_name` keeps every observed main-file name, including all seen hard-link aliases, rather -than only the latest name of an inode. Unlink and rename remove known vanished -names; retiring an inode removes all keys for its serial. Reclamation therefore -keeps a companion when a second name for its main file was observed. The index -remains an observation cache: retained names can delay reclamation. Its existing -`Table::names` admission bound is unchanged; a separate bound on `by_name` -(alias keys) remains future work. The companion entry limit stays 65,536; NOSPC +than only the latest name of an inode. Each serial's recalled name is in +`Table::names` and its other names, its hard-link aliases, in `Table::aliases` +(serial to names), so unlink, rename and the retirement of an inode drop exactly +that serial's keys without scanning the index. A name that changes while the +engine reports one link (nlink 1) is the inode's only name, so the previous key +is stale and leaves at once; only a hard-linked inode keeps its extra names, +which is why reclamation keeps a companion when a second name for its main file +was observed. The index remains an observation cache: retained names can delay +reclamation. Its existing `Table::names` admission bound is unchanged; a +separate bound on `by_name` (alias keys) remains future work. Reclamation itself +never copies the namespace: under the kernel table lock it walks the companion +index, whose size is the `HELD` bound, and asks, for each companion taking a +slot, whether its main inode still holds a name (or, for a companion whose main +file the export never saw, whether its main name is still in `by_name`), then +drops the orphans it found under the companion lock again. The companion entry +limit stays 65,536; NOSPC reports exhaustion of this export resource, not a permission failure or a per-user quota. The first full-table refusal logs immediately, with later logs at least 60 seconds apart; every refusal still increments `names_refused`. @@ -278,9 +293,16 @@ kept for a spilled body: READ, WRITE and SETATTR open `` for their own `pread`/`pwrite`/`set_len` and close it again, so descriptors grow with concurrent operations and not with the number of spilled companions, and a companion count above the process's own `RLIMIT_NOFILE` still reads and writes. -An edit records a body's bytes, length, recency tick and time under one lock, so -no call sees a resident body and a length that disagree, and a reply never -slices past the bytes it holds. The scratch directory is created `0700` and each +An edit of one companion runs alone under that companion's own gate, whether it +changes the resident bytes or the spilled file, and records the body's length +together with the bytes its own edit left: a truncate and a write of the same +companion therefore never leave a length the file does not have. A write that +does not fit the resident budget spills the least recently touched bodies first; +the rounds are bounded by the index, and a body that still does not fit is +written out itself (the spilling edit holds the companion's gate, so the file it +writes is the body it then edits) and edited in its file, which needs no body +budget, so no edit is answered `NFS3ERR_IO` for contention. A reply never slices +past the bytes it holds. The scratch directory is created `0700` and each spilled file `0600`, set explicitly rather than left to the process umask, so a caller embedding this crate without the daemon's `umask(0o077)` still keeps companion bytes to its own user. The daemon's startup `reclaim` removes whatever diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index ea66da7515..742141c038 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -44,26 +44,26 @@ //! live companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. use crate::{ apple_double_codec::Image, - apple_double_spill::{ - create_spilled, io_status, now, spill_path, touch, unlink_paths, Edit, Room, - }, + 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, HashSet}, - fs::{self, File, OpenOptions}, - io, - os::unix::fs::FileExt, + collections::HashMap, + fs, path::{Path, PathBuf}, - sync::atomic::Ordering, + sync::{ + atomic::Ordering, + Arc, Mutex, + }, time::{Duration, Instant}, }; +mod edit; + /// The first serial of the export's own companions, far above any serial the /// engine allocates. pub const SERIALS: u64 = 1 << 62; @@ -104,6 +104,11 @@ struct Companion { 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 { @@ -281,20 +286,25 @@ impl Companions { /// 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. `file` must be detached from 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() { - let decoded = match &file.body { - Body::Decoded(image) => Some(image.encode()), - Body::Resident(_) | Body::Spilled => None, - }; - if let Some(bytes) = decoded { - file.body = Body::Resident(bytes); + // 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; } - file.whole = matches!(file.body, Body::Decoded(_)); + // 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; }; @@ -317,14 +327,16 @@ impl Companions { } /// 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, when nothing touched it since `used` was read and - /// its body is still in memory (resident or decoded). A body another call - /// changed or already spilled stays: `Ok(false)` then, and `temp` is the - /// caller's to unlink. + /// 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: u64, + used: Option, temp: &Path, len: usize, ) -> Result { @@ -336,8 +348,10 @@ impl Companions { let Some(file) = self.files.get_mut(&serial) else { return Err(Status::Stale); }; - if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { - return Ok(false); + if let Some(used) = used { + if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { + return Ok(false); + } } fs::rename(temp, path).map_err(|e| io_status(&e))?; let mut file = self.detach(serial).ok_or(Status::Stale)?; @@ -359,33 +373,6 @@ impl Companions { .min_by_key(|(_, file)| file.used) .map(|(serial, _)| *serial) } - /// Reclaims companions whose main inode is not in `live_serials`, or whose - /// main file `(parent, name)` is not in `live_names` when the export never - /// knew its inode. Returns any spilled file paths to unlink outside the - /// lock. - fn reclaim_orphans( - &mut self, - live_names: &HashSet, - live_serials: &HashSet, - ) -> Vec { - let orphans: Vec = self - .files - .iter() - .filter(|(_, file)| match file.inode { - Some(inode) => !live_serials.contains(&inode), - None => { - let (parent, ref name) = file.named; - name.strip_prefix(b"._") - .is_some_and(|main| !live_names.contains(&(parent, main.to_vec()))) - } - }) - .map(|(serial, _)| *serial) - .collect(); - orphans - .into_iter() - .filter_map(|serial| self.take_serial(serial)) - .collect() - } fn holding(&self) -> Holding { Holding { held: self.files.len(), @@ -445,71 +432,30 @@ impl Kernel { let main = name.strip_prefix(b"._").filter(|main| !main.is_empty())?; self.table().by_name.get(&(parent, main.to_vec())).copied() } - /// 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. - fn spill_for(&self, target: u64, need: usize) -> Result { - loop { - let victim = { - let companions = self.companions(); - let fits = companions.resident_bytes + need <= companions.resident_budget; - if fits { - 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)?; - } - } - /// 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, used, &temp, size); - if matches!(adopted, Ok(true)) { - return Ok(true); - } - unlink_paths([temp]); - adopted.map(|_| false) - } - /// 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), + /// 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 + .files + .iter() + .filter(|(_, file)| file.slotted()) + .filter_map(|(serial, file)| { + 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 { @@ -543,23 +489,6 @@ impl Kernel { } let main = self.main_of(parent, name); let mut companions = self.companions(); - // Never acquire the kernel table under the companion lock. If the - // index bound is reached, snapshot the live names and inodes first, - // then recheck everything under one lock. - let live = if companions.slotted >= companions.held_limit { - drop(companions); - let live = { - let table = self.table(); - ( - table.by_name.keys().cloned().collect::>(), - table.by_name.values().copied().collect::>(), - ) - }; - companions = self.companions(); - Some(live) - } else { - None - }; let named = (parent, name.to_vec()); if let Some(serial) = companions.resolve(&named, main) { let stat = Companions::stat(serial, &companions.files[&serial]); @@ -582,10 +511,24 @@ impl Kernel { None => Ok((stat, directory)), }; } - let reclaimed = match (&live, companions.slotted >= companions.held_limit) { - (Some((names, serials)), true) => companions.reclaim_orphans(names, serials), - _ => Vec::new(), - }; + // 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.slotted >= companions.held_limit { + drop(companions); + let orphans = self.orphans(); + companions = self.companions(); + 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.slotted >= companions.held_limit { let held = companions.slotted; let limit = companions.held_limit; @@ -624,6 +567,7 @@ impl Kernel { body: Body::Resident(Vec::new()), metadata, used, + editing: Arc::new(Mutex::new(())), }; let stat = Companions::stat(serial, &file); companions.index(serial, &file); @@ -721,232 +665,18 @@ impl Kernel { file.named = target; file.inode = to_main; file.used = tick; - // A client may write a companion under another name first. - if matches!(file.body, Body::Resident(_) | Body::Decoded(_)) { - companions.classify(&mut file); - } + // 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); 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 (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)))) - } - /// 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. - fn edit_companion(&self, serial: u64, edit: Edit<'_>) -> Result { - let target = edit.target_len(); - // A round ends in the body, or in another call having changed this - // companion while its body was written out, which decides again. - for _ in 0..3 { - let spilled = match self.edit_resident(serial, target, &edit)? { - Room::Resident(stat) => return Ok(stat), - Room::Spilled => true, - Room::Grow(need) => { - if self.spill_for(serial, need)? { - continue; - } - self.spill_one(serial, Some(target))? - } - }; - if spilled { - edit.disk(&self.spill_file(serial, true)?)?; - return self.record_edit(serial, &edit); - } - } - // Only other calls changing this companion in every round get here. - Err(Status::Io) - } - /// 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. 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); - Ok(stat) - } - /// 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)))) - } /// Drops every companion and removes the export's spill directory; returns /// what the index held. pub(crate) fn companions_release(&self) -> Holding { 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..e76d43e457 --- /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 +//! [`Companion::editing`] gate: 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. 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); + 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), + }) + } +} From c7145b61b14a39a532422695d53acb7efb526733 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 03:57:32 +0000 Subject: [PATCH 11/16] test(nfs): run the companion fd-limit case in its own process (lp73) `spilled_companions_outnumber_the_open_file_limit` lowered the process-wide soft `RLIMIT_NOFILE` to 512 and asserted the process descriptor count while the other tests of the same binary ran in threads beside it: either assertion could flake (LP636 review). The test now re-executes its own binary with `--exact` for this one test in a child process (`LAYERFS_NFS_FD_LIMIT_CHILD` marks the child), so the limit and the descriptor count belong to a process running nothing else. The parent asserts the child's exit status. Libtest and nextest both start the same test binary, so the child is selected by name in either. Two regression tests for the companion fixes: - `a_spilled_body_renamed_off_its_inode_takes_its_slot`: a whole image kept as written (attribute above the decoded-entry bound), evicted to disk by another companion's body, then renamed onto a name whose main file the export never saw. Before the reclassification it kept `whole` and took no slot. - `a_spilled_companion_keeps_its_length_and_bytes_together`: a truncate and a write of one spilled companion start together 64 times; the length read back always matches the bytes served. Without the per-companion edit gate the length can be left at the write's size over a truncated file, and the read then answers NFS3ERR_IO. Tests: `layerfs-nfs` write 14 passed, decode 10 passed (nextest); the other layerfs-nfs binaries were run separately (31 passed). Production LOC: 161033 -> 161033 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 -B tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent b4d0222f1 and this committed tree; only test files changed. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/tests/apple_double_decode.rs | 61 ++++++++++++ engine/crates/layerfs-nfs/tests/write.rs | 93 ++++++++++++++++++- 2 files changed, 152 insertions(+), 2 deletions(-) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 4a06c92fe6..91991d678d 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -574,6 +574,67 @@ fn a_companion_without_a_main_file_takes_a_slot_and_is_reclaimed() { 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 a_rename_keeps_the_other_names_of_the_inode_companion() { let base = temp("aliases"); diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index daa7419964..b1ec3bc771 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -941,11 +941,101 @@ fn open_fds() -> Option { .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); @@ -959,8 +1049,7 @@ fn spilled_companions_outnumber_the_open_file_limit() { let root = c.mnt("/"); // Four times as many companions as the process may hold open at once. - // Lowering the soft limit while this binary runs its tests in threads - // leaves every one of them more than enough descriptors. + // 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; From a7b6ffd927e75c2ca5bed2be210af810c6ad1f82 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 04:14:59 +0000 Subject: [PATCH 12/16] docs(nfs): name the companion edit gate without a broken intra-doc link (lp73) `Companion` is not in the body module's scope, so the module documentation linked a private item that rustdoc cannot resolve there. The gate is named in the parent module anyway. Production LOC: 161033 -> 161033 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 -B tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6); only comment lines changed, so the count is unchanged. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double/edit.rs | 5 +++-- 1 file changed, 3 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 e76d43e457..f9c53ba068 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -1,8 +1,9 @@ //! 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 -//! [`Companion::editing`] gate: it applies to the resident bytes under the +//! 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 From f2dcd53d6ae329f5ee76dedbcc7b0ff7e09be7d7 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:36:16 +0000 Subject: [PATCH 13/16] fix(nfs): re-check a companion name at the index bound, keep renamed aliases (lp73) - N1: at the bound CREATE releases the companion lock to reclaim orphans; it now reads the name and its main file again and inserts under the lock it holds once more, so a concurrent GUARDED CREATE of one name yields one serial and one NFS3ERR_EXIST (before: a second serial for the same name, or a spurious NFS3ERR_NOSPC once the other call had inserted). - N2: renamed() records the recalled name it overwrites, when that name did not move and is still one of the inode's, as an alias, so retiring the serial drops every key of by_name it holds. - N3: reclamation walks Companions::slots, the companions that take a slot, instead of the whole index. A whole image takes no slot and its number is bounded by the decoded bytes, not by HELD, so it no longer sets the walk's cost. nfs.md's CREATE, alias and reclamation paragraphs now say that. - Tests: a_guarded_create_reclaims_the_last_slot_for_one_entry_only and a_renamed_hard_link_alias_keeps_the_inodes_recalled_name_bound fail on the unfixed code (round 20 answers NOSPC instead of EXIST; the companion is no longer found), whole_images_take_no_slot_and_the_bound_reclaims_ only_slots pins the slot accounting reclamation reads. Production LOC: 161033 -> 161046 (delta +13) Counting: tools/production_loc.py --root --json, SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6; scope core/engine/control/api src plus shipped SQL, tests, docs and tools excluded; parents a7b6ffd92 (161033) and the staged tree (161046); layerfs-nfs apple_double.rs 549 -> 562, kernel.rs 777 -> 777. reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 31 +++-- engine/crates/layerfs-nfs/src/apple_double.rs | 94 +++++++------ engine/crates/layerfs-nfs/src/kernel.rs | 17 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 81 +++++++++++- engine/crates/layerfs-nfs/tests/write.rs | 125 +++++++++++++++++- 5 files changed, 290 insertions(+), 58 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 9026342d8c..60f775d943 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -256,27 +256,34 @@ encode back to exactly the bytes the client wrote, are in the spill helpers are in [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs). -CREATE checks an existing companion name, checks the entry limit, reclaims -orphans and inserts a new serial under one companion-lock hold, so concurrent -GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. An -existing name is still usable when the table is full. `Table::by_name` keeps +CREATE checks an existing companion name and the entry limit under the +companion lock; over the limit it releases that lock to reclaim orphans, then +reads the name and its main file again before it inserts under the lock it holds +once more, so concurrent GUARDED creates of one name yield one serial and one +`NFS3ERR_EXIST`, whether or not either of them reclaimed. An existing name is +still usable when the table is full. `Table::by_name` keeps every observed main-file name, including all seen hard-link aliases, rather than only the latest name of an inode. Each serial's recalled name is in `Table::names` and its other names, its hard-link aliases, in `Table::aliases` (serial to names), so unlink, rename and the retirement of an inode drop exactly -that serial's keys without scanning the index. A name that changes while the -engine reports one link (nlink 1) is the inode's only name, so the previous key +that serial's keys without scanning the index. A rename that moves one of an +inode's other names keeps the name it was last recalled by as an alias too, so +the retirement still drops every key the serial holds. A name that changes +while the engine reports one link (nlink 1) is the inode's only name, so the +previous key is stale and leaves at once; only a hard-linked inode keeps its extra names, which is why reclamation keeps a companion when a second name for its main file was observed. The index remains an observation cache: retained names can delay reclamation. Its existing `Table::names` admission bound is unchanged; a separate bound on `by_name` (alias keys) remains future work. Reclamation itself -never copies the namespace: under the kernel table lock it walks the companion -index, whose size is the `HELD` bound, and asks, for each companion taking a -slot, whether its main inode still holds a name (or, for a companion whose main -file the export never saw, whether its main name is still in `by_name`), then -drops the orphans it found under the companion lock again. The companion entry -limit stays 65,536; NOSPC +never copies the namespace: under the kernel table lock it walks the companions +that take a slot (`Companions::slots`, at most the `HELD` bound) and never the +whole index, so the companions holding a whole image - which take no slot and +whose number the decoded bytes, not `HELD`, bound - add nothing to the walk. For +each of them it asks whether its main inode still holds a name (or, for a +companion whose main file the export never saw, whether its main name is still in +`by_name`), then drops the orphans it found under the companion lock again. The +companion entry limit stays 65,536; NOSPC reports exhaustion of this export resource, not a permission failure or a per-user quota. The first full-table refusal logs immediately, with later logs at least 60 seconds apart; every refusal still increments `names_refused`. diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 742141c038..da2a0feffa 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -52,13 +52,10 @@ 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, - }, + sync::{atomic::Ordering, Arc, Mutex}, time::{Duration, Instant}, }; @@ -148,7 +145,10 @@ pub(crate) struct Companions { /// Main inode serial -> the companion holding its FinderInfo and /// attributes. inodes: HashMap, - slotted: usize, + /// The serials taking a slot of the index bound, so reclamation walks the + /// slots rather than every companion: a whole image takes none, so its + /// number is bounded by the decoded bytes alone and not by [`HELD`]. + slots: HashSet, resident_bytes: usize, decoded: usize, decoded_bytes: usize, @@ -165,7 +165,7 @@ impl Default for Companions { files: HashMap::new(), names: HashMap::new(), inodes: HashMap::new(), - slotted: 0, + slots: HashSet::new(), resident_bytes: 0, decoded: 0, decoded_bytes: 0, @@ -199,7 +199,9 @@ impl Companions { } /// Adds `file` to the index and to the slot and byte counts. fn attach(&mut self, serial: u64, file: Companion) { - self.slotted += usize::from(file.slotted()); + 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(); @@ -209,7 +211,7 @@ impl Companions { /// the caller to unindex. fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; - self.slotted -= usize::from(file.slotted()); + 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(); @@ -376,7 +378,7 @@ impl Companions { fn holding(&self) -> Holding { Holding { held: self.files.len(), - slotted: self.slotted, + slotted: self.slots.len(), resident_bytes: self.resident_bytes, decoded: self.decoded, decoded_bytes: self.decoded_bytes, @@ -441,10 +443,10 @@ impl Kernel { let table = self.table(); let companions = self.companions(); companions - .files + .slots .iter() - .filter(|(_, file)| file.slotted()) - .filter_map(|(serial, file)| { + .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) @@ -475,6 +477,34 @@ impl Kernel { 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( &self, @@ -487,38 +517,28 @@ impl Kernel { if parent != self.root() && !self.table().parents.contains_key(&parent) { return Err(Status::NotDir); } - let main = self.main_of(parent, name); - let mut companions = self.companions(); 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 stat = Companions::stat(serial, &companions.files[&serial]); - companions.use_serial(serial); - drop(companions); - // 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)), - }; + 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.slotted >= companions.held_limit { + if companions.slots.len() >= companions.held_limit { drop(companions); 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 @@ -529,8 +549,8 @@ impl Kernel { } } } - if companions.slotted >= companions.held_limit { - let held = companions.slotted; + if companions.slots.len() >= companions.held_limit { + let held = companions.slots.len(); let limit = companions.held_limit; let log = companions .last_refusal_log diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 2852f2457c..a2e297e7fa 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -529,14 +529,17 @@ impl Kernel { let named = (to, new_name.to_vec()); let moved = (from, name.to_vec()); table.unbind_name(&moved, serial); - let remembered = match table.names.get_mut(&serial) { - Some(slot) => { - *slot = named.clone(); - true + 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); } - None => false, - }; - if remembered { table.bind_name(named, serial); } } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 91991d678d..7156b53da3 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -614,7 +614,11 @@ fn a_spilled_body_renamed_off_its_inode_takes_its_slot() { 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"); + 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 @@ -635,6 +639,81 @@ fn a_spilled_body_renamed_off_its_inode_takes_its_slot() { 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"); diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index b1ec3bc771..25b0351d87 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -849,6 +849,126 @@ fn two_guarded_creates_of_one_companion_name_leave_one_entry() { 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"); @@ -1033,7 +1153,10 @@ fn spilled_companions_outnumber_the_open_file_limit() { // 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"); + run_alone( + FD_LIMIT_CHILD, + "spilled_companions_outnumber_the_open_file_limit", + ); return; } let base = temp("appledouble-fd"); From 0a4dfdd37892b677997c8f4d3e76fec6c5248738 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:37:35 +0000 Subject: [PATCH 14/16] style(nfs): rustfmt the companion edit file this branch touches (lp73) cargo +1.85.1 fmt -p layerfs-nfs. The other files this branch changes were rustfmt'd in the commits that changed them; after this commit cargo fmt --all -- --check reports only the two upstream files (api/crates/layerfs-cli/tests/ concurrent_reads.rs, control/crates/layerfs-store/src/lease.rs), neither of which this branch touches. Production LOC: 161046 -> 161046 (delta 0) Counting: tools/production_loc.py --root --json, SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6; scope core/engine/control/api src plus shipped SQL, tests, docs and tools excluded; parents the previous commit's tree (161046) and the staged tree (161046); layerfs-nfs apple_double/edit.rs 298 -> 298 (physical lines 367). reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double/edit.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index f9c53ba068..a3ba16b691 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -16,9 +16,7 @@ //! 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, - }, + apple_double_spill::{create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Room}, attributes::Status, change::{Sattr, Tickets, Wcc}, kernel::Kernel, @@ -316,7 +314,9 @@ 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 + .companions() + .adopt_spilled(serial, Some(used), &temp, size); if matches!(adopted, Ok(true)) { return Ok(true); } From 778d83133547a110dc6727b629a6a321bb7ca397 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 11:01:21 +0000 Subject: [PATCH 15/16] docs(nfs): clarify whole-image bound in Companions::slots comment (lp73) Whole images exceeding DECODED_ENTRY_BYTES or DECODED_BYTES stay as written bytes rather than Body::Decoded, so DECODED_BYTES bounds only the decoded subset while all whole images stay outside HELD and Companions::slots. Production LOC: 161046 -> 161046 (delta 0) Counting: tools/production_loc.py --root --json, SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6; scope core/engine/control/api src plus shipped SQL, tests, docs and tools excluded; parents 0a4dfdd37 (161046) and the staged tree (161046); comment-only change in layerfs-nfs apple_double.rs. reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index da2a0feffa..e4db0a5782 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -145,9 +145,10 @@ pub(crate) struct Companions { /// Main inode serial -> the companion holding its FinderInfo and /// attributes. inodes: HashMap, - /// The serials taking a slot of the index bound, so reclamation walks the - /// slots rather than every companion: a whole image takes none, so its - /// number is bounded by the decoded bytes alone and not by [`HELD`]. + /// 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, From 2e09f0295f3afb502ea861db7ac6a1e933027d48 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 11:03:40 +0000 Subject: [PATCH 16/16] docs(nfs): port AppleDouble spill and decode updates into #671 nfs.md (lp73) Topics updated: engine/kernel-routes (nfs.md). Ports this branch's ExportConfig fields, companion wcc_data rule, and AppleDouble spill/decode/concurrency/reclamation bounds and behavior into the restructured #671 nfs.md layout, including the N3 clarification that whole images kept as written bytes above the decoded budget also take no HELD slot. Production LOC: 161046 -> 161046 (delta 0) Counting: tools/production_loc.py --root --json, SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6; scope core/engine/control/api src plus shipped SQL, tests, docs and tools excluded; parents 22b8df211 (161046) and the staged tree (161046); docs-only change. reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 59 +++++++++++++++---- 1 file changed, 47 insertions(+), 12 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 67e53bb052..4ffebd99fa 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`, `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) | @@ -126,7 +126,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) | @@ -152,22 +152,57 @@ 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/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 | -| --- | --- | --- | -| `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` | 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 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 +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`)