From d0e21d073f14c132c1679dcc87d48f8323b7d3f7 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 03:51:07 +0000 Subject: [PATCH 01/53] feat(nfs): read a READDIRPLUS window's facts in batches A READDIRPLUS entry carries its attributes and its handle. On the macOS NFSv3 client an entry without them builds no vnode, so a cold traversal of a committed tree falls back to one synchronous LOOKUP per listed name (diagnostic numbers only; see the pull request's measurement section). What the reply pays is bounded per window instead of per entry wherever the base has a batch port. The reading visit answers from memory what it holds: the window's local inode rows, whose kinds and facts come from the one statement that listed the names, and any inherited inode whose value, metadata, remembered length and remembered child-directory count are resident. Only a window memory left undecided takes the one Store reader, and it then reads the window's inherited serials in one `lookup_many` and its ordinary file lengths in one `provide_lengths`, so 8 and 200 names cost the same inode and length batches. What stays per entry, as before this change: a distinct non-inline metadata root is read once, a listed subdirectory's child-directory count lists that subdirectory, and a symlink entry reads its target. A window of ordinary files with inline metadata therefore costs exactly the two batches; a window naming those entries costs more, growing with them and not with the number of names. LOOKUP is one owner job (B4): the job that resolves a name has already read the directory's row, so it reports both. Deliberate change: a failed LOOKUP, `.`, `..` and the export's silly names answer the directory facts this export last observed for it, or no attributes when it has never seen the directory, instead of a fresh GETATTR of the parent. RFC 1813 keeps those attributes optional, so both forms are legal; the answer is now at most one observation old. The listed directory's own `dir_attributes` are its local row or the facts the export last observed in OPENDIR, never a read of its own, and the publishing visit takes one kernel lookup reference per handed-out handle in the job that makes its offset valid. Tests: layerfs-workspace 184 passed, layerfs-nfs 28 passed, layerfs-overlay 79 passed (1 skipped), layerfs-mount-ports 0 tests; clippy -D warnings clean over the changed crates. Deleted tests: none. The workspace test asserts one batch length demand, no single-key length demand, the same object batch count at 8 and 200 names, facts for every entry including a subdirectory, and no Store reader for a window of local rows; the export test asserts attributes and handles on every listed name, one owner visit for the whole enumeration, at most one Store reader per reply and none for a local directory; the daemon's Linux mount observer forwards the new `attributes` argument, which the previous version of this change missed on every target that is not macOS. Production LOC: 159977 -> 160158 (delta +181) Scope and method: `python3 -B tools/production_loc.py` over first-party product Rust/SQL/JavaScript only, at upstream/layerfs_v2_0_0 (af2ad92bc) and at this tree; tests, docs and tools are excluded, and the v0.1.6 reference scope is absent (retired R9c). --- docs/architecture/engine/kernel-routes/nfs.md | 16 +- .../engine/kernel-routes/ports.md | 3 +- .../src/service/filesystem_port.rs | 10 +- .../tests/mounted_sqlite_full.rs | 2 +- .../src/operations/directory.rs | 26 +- .../src/operations/lookup.rs | 5 +- .../crates/layerfs-mount-ports/src/ports.rs | 7 +- engine/crates/layerfs-nfs/src/change.rs | 2 +- engine/crates/layerfs-nfs/src/directory.rs | 13 +- engine/crates/layerfs-nfs/src/kernel.rs | 72 ++-- engine/crates/layerfs-nfs/src/nfs.rs | 41 ++- engine/crates/layerfs-nfs/tests/export.rs | 173 ++++++++++ .../crates/layerfs-nfs/tests/support/spy.rs | 11 +- engine/crates/layerfs-nfs/tests/write.rs | 12 +- engine/crates/layerfs-workspace/src/lib.rs | 7 +- .../src/operations/kernel_directory.rs | 321 +++++++++++++----- .../src/operations/kernel_read.rs | 50 ++- .../layerfs-workspace/tests/common/mod.rs | 21 ++ .../tests/directory_links.rs | 15 +- .../tests/kernel_directory.rs | 230 ++++++++++++- .../layerfs-workspace/tests/kernel_visit.rs | 6 +- 21 files changed, 874 insertions(+), 169 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 7b64bf49ed..83d521f80b 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -122,7 +122,7 @@ itself ([`attributes.rs`](../../../../engine/crates/layerfs-nfs/src/attributes.r ## Directories ```text - READDIR / READDIRPLUS (handle, cookie, cookieverf, budget) + READDIR / READDIRPLUS (handle, cookie, cookieverf, maxcount) cookie 0 -----> open_directory: fresh descriptor; verifier = its id cookie > 0 ---> directory(serial, verifier) still open? no -> NFS3ERR_BAD_COOKIE (client lists from 0) @@ -137,8 +137,12 @@ itself ([`attributes.rs`](../../../../engine/crates/layerfs-nfs/src/attributes.r | --- | --- | | The NFS cookie is the engine's kernel offset on one implicit directory descriptor named by `cookieverf`. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | An offset a rewind retired is `NFS3ERR_BAD_COOKIE`. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | -| A READDIRPLUS entry carries the facts its listing already read (a local inode's current row, or an inherited inode's immutable base stat) and the handle of its serial, so the client needs no LOOKUP per name. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | +| A READDIRPLUS entry carries the facts its window read — a local inode's current row, or an inherited inode's immutable base stat — and the handle of its serial, so the client needs no LOOKUP per name. Both are optional in RFC 1813 and this export sends both for every named entry whose offsets the reply publishes. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | +| A cold window's facts cost two demands whatever its size: its inherited serials in one batch inode demand (`lookup_many`) and its ordinary file lengths in one batch length demand (`provide_lengths`). The entries memory already answers — a local row, or an inherited inode whose value, metadata, length and child-directory count are resident — cost the request no Store reader at all. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | +| Those two batches are not everything an entry costs, and this route changes none of the rest: an inherited inode whose metadata is not inline reports one portable-metadata demand per distinct metadata root, a listed subdirectory one listing of that subdirectory for its child-directory count, and a symlink entry one read of its target. A window of only ordinary files with inline metadata therefore costs exactly the two batches; a window naming those entries costs more, growing with them and not with the names. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`view.rs`](../../../../engine/crates/layerfs-workspace/src/base/view.rs), [`links.rs`](../../../../engine/crates/layerfs-workspace/src/base/links.rs) | | Every handle a READDIRPLUS reply hands out takes its one kernel lookup reference in the publishing visit that makes its offset valid; a reply reusing an already published offset range hands out none. | [`kernel_cookie.rs`](../../../../engine/crates/layerfs-overlay/src/lifetime/kernel_cookie.rs) | +| READDIR has one count, which bounds the whole reply. READDIRPLUS sends the entries' own count (`dircount`) before it; only `maxcount` bounds this reply, the count the client sized its buffer by. | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | +| A reply's `dir_attributes` are the facts of the listed directory this window read, or the ones the export last observed for it (its OPENDIR visit read them): either way the reply costs no extra read. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | `.` and `..` carry no attributes: both name an object whose handle the client already holds. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | `..` comes from the parent recorded when a directory was looked up, created, moved or listed; the engine resolves names only downward. | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | Silly names and AppleDouble companions are never listed. | [`names.rs`](../../../../engine/crates/layerfs-nfs/src/names.rs), [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | @@ -176,6 +180,14 @@ itself ([`attributes.rs`](../../../../engine/crates/layerfs-nfs/src/attributes.r Refresh after an install is covered in [Coherence: Invalidation](coherence.md#invalidation). +## LOOKUP and GETATTR + +| Rule | Source | +| --- | --- | +| One owner visit answers a LOOKUP: the job that resolves a name has already read the directory's own row, so the reply's `dir_attributes` cost no second visit. | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | +| Deliberate change from this route's base: a LOOKUP that fails (`NFS3ERR_NOENT`), and `.`, `..` and the export's silly names, answer the directory facts this export last published or observed for it, or no `dir_attributes` when it has never seen the directory, where they used to make a fresh GETATTR of the parent. RFC 1813 makes the failure's attributes optional, so both answers are legal; the cost is that those attributes are at most one observation old, the gain that no LOOKUP spends a second job. | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | +| An export remembers the facts it last published for a directory (a LOOKUP, a GETATTR, a listing's OPENDIR) and answers later `dir_attributes` and `wcc_data` from them, so a name-only question costs no read. | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | + ## AppleDouble files ```text diff --git a/docs/architecture/engine/kernel-routes/ports.md b/docs/architecture/engine/kernel-routes/ports.md index 9ac3e032ba..4c97179547 100644 --- a/docs/architecture/engine/kernel-routes/ports.md +++ b/docs/architecture/engine/kernel-routes/ports.md @@ -67,7 +67,8 @@ it holds. LOOKUP / GETATTR / OPEN / OPENDIR KernelRead::prepare loop: observe_visit(facts) ---- owner job, records no request source - Value(inode) -> answer (OPEN/OPENDIR wrote a descriptor) + Value(Decided) -> answer (OPEN/OPENDIR wrote a descriptor; + a LOOKUP also carries the directory it named) Refused(r) -> refusal Needs(n) -> drop receipt; base(); facts.supply(n); repeat diff --git a/engine/crates/layerfs-daemon/src/service/filesystem_port.rs b/engine/crates/layerfs-daemon/src/service/filesystem_port.rs index 173c851221..c2ec044c5a 100644 --- a/engine/crates/layerfs-daemon/src/service/filesystem_port.rs +++ b/engine/crates/layerfs-daemon/src/service/filesystem_port.rs @@ -10,7 +10,7 @@ use layerfs_mount_ports::ports::{ }; use layerfs_overlay::{KernelCookieOffer, KernelMount, Publication}; use layerfs_workspace::{ - BaseView, CanonicalClient, JobOutcome, KernelDirectoryWindow, KernelInput, + BaseView, CanonicalClient, JobOutcome, KernelDirectoryRead, KernelDirectoryWindow, KernelInput, KernelMutationOutcome, KernelReadOperation, KernelReadOutcome, KernelVisitRequest, KernelWindow, Recognition, RecognizeWork, VisitFacts, WorkspaceError, WriteData, RECOGNIZE_BYTES, @@ -106,6 +106,7 @@ impl RequestServices for FilesystemPort { handle: u64, offset: u64, after: Option>, + attributes: bool, ) -> ServiceFuture<'_, ServiceReply>> { // A stopped mount refuses before anything about the request is read. if let Err(fenced) = self.fenced(true) { @@ -116,8 +117,11 @@ impl RequestServices for FilesystemPort { mount, serial, handle, - offset, - after, + KernelDirectoryRead { + offset, + after, + attributes, + }, ); match visit { Ok(visit) => self.call( diff --git a/engine/crates/layerfs-daemon/tests/mounted_sqlite_full.rs b/engine/crates/layerfs-daemon/tests/mounted_sqlite_full.rs index d60ac12e34..2b718a38f2 100644 --- a/engine/crates/layerfs-daemon/tests/mounted_sqlite_full.rs +++ b/engine/crates/layerfs-daemon/tests/mounted_sqlite_full.rs @@ -68,7 +68,7 @@ macro_rules! forward { } impl RequestServices for ObserveRequest { forward! { - directory_visit(mount:KernelMount,serial:u64,handle:u64,offset:u64,after:Option>) -> ServiceReply>; + directory_visit(mount:KernelMount,serial:u64,handle:u64,offset:u64,after:Option>,attributes:bool) -> ServiceReply>; publish_cookies(offer:KernelCookieOffer,names:Vec>) -> ServiceReply<()>; close_directory(mount:KernelMount,serial:u64,handle:u64) -> ServiceReply<()>; read_visit(mount:KernelMount,serial:u64,handle:Option,offset:u64,length:u32) -> ServiceReply>; diff --git a/engine/crates/layerfs-mount-ports/src/operations/directory.rs b/engine/crates/layerfs-mount-ports/src/operations/directory.rs index 874c7bb002..61c8732d82 100644 --- a/engine/crates/layerfs-mount-ports/src/operations/directory.rs +++ b/engine/crates/layerfs-mount-ports/src/operations/directory.rs @@ -20,8 +20,7 @@ pub struct DirectoryStream { offset: u64, parent: Option, window: Option, - /// The reply shows every entry's facts, as READDIRPLUS does: the listing - /// then reads them from the authoritative base, outside the owner. + /// The reply shows each entry's facts (READDIRPLUS). attributes: bool, ended: bool, } @@ -183,7 +182,14 @@ impl DirectoryStream { let started = std::time::Instant::now(); let reply = self .services - .directory_visit(self.mount, self.serial, self.handle, self.offset, after) + .directory_visit( + self.mount, + self.serial, + self.handle, + self.offset, + after, + self.attributes, + ) .await; crate::phase::charge(crate::phase::Phase::DirectoryVisit, started); let reply = reply?; @@ -223,11 +229,12 @@ impl DirectoryStream { let Some(window) = self.window.take().filter(|_| !self.ended) else { return Ok(None); }; - // Only a window whose inherited names or kinds memory did not - // hold leaves the receive loop and takes one Store reader; a - // reply that shows facts needs that reader even when it does. + // Only a window whose inherited names, kinds or facts memory did + // not hold leaves the receive loop and takes one Store reader: a + // local directory, and a window whose inherited entries are all + // resident, are answered without it. let started = std::time::Instant::now(); - let base = if self.attributes || window.listing.is_none() { + let base = if window.needs_base(self.attributes) { // Provider reads never run on the loop that received the request. Some(self.services.base().await?) } else { @@ -277,9 +284,8 @@ impl DirectoryBatch { } /// Records the entries whose handles this reply hands out, so the /// publishing visit takes their kernel references with the offsets. - /// `accepted` is the prefix the reply buffer took; only published - /// offsets can make a handle's fence answer, so a reused reply adopts - /// nothing. + /// `accepted` is the prefix the reply buffer took; only published offsets + /// can make a handle's fence answer, so a reused reply adopts nothing. pub fn adopt(&mut self, accepted: usize) { let entries: Vec<(u64, bool)> = self.batch.entries[..accepted] .iter() diff --git a/engine/crates/layerfs-mount-ports/src/operations/lookup.rs b/engine/crates/layerfs-mount-ports/src/operations/lookup.rs index 5cebfc3bb0..fb1e1b3c94 100644 --- a/engine/crates/layerfs-mount-ports/src/operations/lookup.rs +++ b/engine/crates/layerfs-mount-ports/src/operations/lookup.rs @@ -189,11 +189,12 @@ impl Custody { let receipt = receipt?; let original = receipt.get().clone(); let needs = match (&original.result, &original.decision) { - (Ok(None), Some(KernelReadDecision::Value(inode))) => { - let stat = inode.clone().into(); + (Ok(None), Some(KernelReadDecision::Value(decided))) => { + let stat = decided.inode.clone().into(); self.receipt = Some(receipt); return Ok(Ok(KernelReadValue { stat, + parent: decided.parent.clone().map(Into::into), file: original.open_candidate, directory: original.directory_candidate, original, diff --git a/engine/crates/layerfs-mount-ports/src/ports.rs b/engine/crates/layerfs-mount-ports/src/ports.rs index f7c6f1c789..1bfd63ba81 100644 --- a/engine/crates/layerfs-mount-ports/src/ports.rs +++ b/engine/crates/layerfs-mount-ports/src/ports.rs @@ -161,8 +161,10 @@ pub trait RequestServices: Send + Sync { /// READDIR's reading visit as one read-only owner job on the open /// directory `handle`: the position of the kernel `offset`, one window /// of current names (after `after` when it continues an earlier window - /// of the same request) and the offsets the reply may hand out. It - /// records nothing, so its request holds nothing afterwards. + /// of the same request) and the offsets the reply may hand out. When + /// `attributes` is set (READDIRPLUS), the visit also answers what memory + /// already holds of each entry's facts. It records nothing, so its + /// request holds nothing afterwards. fn directory_visit( &self, mount: KernelMount, @@ -170,6 +172,7 @@ pub trait RequestServices: Send + Sync { handle: u64, offset: u64, after: Option>, + attributes: bool, ) -> ServiceFuture<'_, ServiceReply>>; /// READDIR's publishing visit, before the reply is sent: exactly the /// names the reply buffer accepted become valid offsets, in one diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 7932d219b5..229e3e36bd 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -261,7 +261,7 @@ impl Kernel { /// The entry a name binds now, or none. fn existing(&self, parent: u64, name: &[u8]) -> Result, Status> { match self.lookup(parent, name) { - Ok(stat) => Ok(Some(stat)), + Ok((stat, _)) => Ok(Some(stat)), Err(Status::NoEnt) => Ok(None), Err(status) => Err(status), } diff --git a/engine/crates/layerfs-nfs/src/directory.rs b/engine/crates/layerfs-nfs/src/directory.rs index 5842d6c6dd..f5f5d2b204 100644 --- a/engine/crates/layerfs-nfs/src/directory.rs +++ b/engine/crates/layerfs-nfs/src/directory.rs @@ -12,10 +12,11 @@ //! directory's end, so the same reply says so; any other reply's next call //! resumes after the last accepted cookie. //! -//! A READDIRPLUS entry carries the attributes the listing already read — the -//! local inode row of the name, or the inherited inode's own immutable facts -//! — and the handle of the entry's serial. Both are optional in RFC 1813; -//! here they are present for every named entry whose offsets this request +//! A READDIRPLUS entry carries the attributes the listing read — the local +//! inode row of the name, or the inherited inode's immutable facts, read for +//! the whole window in one batch demand each for inodes and file lengths — +//! and the handle of the entry's serial. Both are optional in RFC 1813; here +//! they are present for every named entry whose offsets this request //! publishes, and the publishing visit takes one kernel lookup reference per //! handed-out handle in that same job, so nothing is looked up twice and no //! entry is left without the reference its handle presents. @@ -210,6 +211,10 @@ pub fn list(kernel: &Kernel, request: Listing) -> Result, Status> { (at_end, directory) } }; + // An inherited directory has no local row in this window: its attributes + // are the facts this export last observed or published for it (its + // OPENDIR read them), so the reply carries them without a read of its own. + let directory = directory.or_else(|| kernel.directory_wcc(request.serial).0); finish(entries, directory.as_ref(), handle, eof) } diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index dd03a6ab8f..2714e80cbe 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -136,6 +136,16 @@ pub(crate) struct OpenFile { pub size: u64, } +/// One kernel read's answer, as this export uses it. +struct Answer { + stat: ViewStat, + /// The directory a LOOKUP named the inode in: the same visit read it, so + /// the reply's directory attributes cost no second owner job. + parent: Option, + file: Option, + directory: Option, +} + /// One kernel mount served over NFS: its ports and its synthetic kernel state. pub struct Kernel { services: Arc, @@ -287,9 +297,9 @@ impl Kernel { ) }); match found { - Ok((stat, _, _)) => { - self.entry_taken(&stat, parent, &name); - if stat.serial == serial { + Ok(answer) => { + self.entry_taken(&answer.stat, parent, &name); + if answer.stat.serial == serial { self.resolved.fetch_add(1, Ordering::Relaxed); return Ok(()); } @@ -321,18 +331,17 @@ impl Kernel { protected: u64, handle: Option, operation: KernelReadOperation, - ) -> Result<(ViewStat, Option, Option), Status> { + ) -> Result { let (services, request) = self.request()?; let found = wait(KernelRead::prepare( services, self.mount, request, protected, handle, operation, )) .map_err(read_failure)?; - let answer = found.value().map(|value| { - ( - value.stat.clone(), - value.file.map(|file| file.owner_id()), - value.directory.map(|directory| directory.owner_id()), - ) + let answer = found.value().map(|value| Answer { + stat: value.stat.clone(), + parent: value.parent.clone(), + file: value.file.map(|file| file.owner_id()), + directory: value.directory.map(|directory| directory.owner_id()), }); wait(found.dispose()).map_err(read_failure)?; answer.map_err(refusal) @@ -354,7 +363,7 @@ impl Kernel { }; let stat = self .observe(serial, handle, KernelReadOperation::Getattr { serial }) - .map(|(stat, _, _)| stat) + .map(|answer| answer.stat) .map_err(|status| { if status == Status::NoEnt { Status::Stale @@ -366,11 +375,17 @@ impl Kernel { Ok(stat) } /// LOOKUP of `name` in directory `parent`, including `.`, `..` and the - /// export's own silly names. - pub fn lookup(&self, parent: u64, name: &[u8]) -> Result { + /// export's own silly names. One owner job answers both the entry and, + /// when the name resolved, the directory itself: the same job had to read + /// the directory's row to resolve it, so the reply's directory attributes + /// cost nothing more. The second half is `None` for `.`, `..`, a silly + /// name and every failure, whose answers carry the facts + /// [`Kernel::directory_wcc`] holds instead of a fresh GETATTR: a deliberate + /// change, and RFC 1813 makes those attributes optional. + pub fn lookup(&self, parent: u64, name: &[u8]) -> Result<(ViewStat, Option), Status> { match name { b"" => return Err(Status::NoEnt), - b"." => return self.getattr(parent), + b"." => return self.getattr(parent).map(|stat| (stat, None)), b".." => { let up = if parent == self.root() { parent @@ -379,13 +394,13 @@ impl Kernel { known.ok_or(Status::NoEnt)? }; self.held_reference(up)?; - return self.getattr(up); + return self.getattr(up).map(|stat| (stat, None)); } _ if name.len() > 255 => return Err(Status::NameTooLong), _ => {} } if let Some(stat) = self.companion_named(parent, name) { - return Ok(stat); + return Ok((stat, self.directory_wcc(parent).0)); } if self.refuses_apple_double() && crate::names::apple_double(name) { if parent != self.root() && !self.table().parents.contains_key(&parent) { @@ -395,17 +410,20 @@ impl Kernel { } let silly = self.table().silly.get(&(parent, name.to_vec())).copied(); if let Some(serial) = silly { - return self.getattr(serial); + return self.getattr(serial).map(|stat| (stat, None)); } let path = PathName::from_bytes(name).map_err(|_| Status::Inval)?; - let (stat, _, _) = self.observe( + let answer = self.observe( parent, None, KernelReadOperation::Lookup { parent, name: path }, )?; + if let Some(directory) = &answer.parent { + self.observed(directory); + } // The deciding visit took one engine reference; keep exactly one. - self.entry_taken(&stat, parent, name); - Ok(stat) + self.entry_taken(&answer.stat, parent, name); + Ok((answer.stat, answer.parent)) } /// A visit or mutation that decided `stat` as the entry `name` of /// `parent` took one engine lookup reference on it: the export keeps @@ -611,9 +629,9 @@ impl Kernel { } } let operation = KernelReadOperation::Open { serial, writable }; - let (stat, file, _) = self.observe(serial, None, operation)?; - let handle = file.ok_or(Status::ServerFault)?; - Ok(self.file_taken(serial, handle, &stat, writable)) + let answer = self.observe(serial, None, operation)?; + let handle = answer.file.ok_or(Status::ServerFault)?; + Ok(self.file_taken(serial, handle, &answer.stat, writable)) } /// Records an open file descriptor (from `OPEN` or `CREATE`), evicting /// the oldest unpinned descriptor when the bound is reached. @@ -730,9 +748,11 @@ impl Kernel { if crate::apple_double::companion(serial) { return Err(Status::NotDir); } - let (_, _, directory) = - self.observe(serial, None, KernelReadOperation::Opendir { serial })?; - let handle = directory.ok_or(Status::ServerFault)?; + let answer = self.observe(serial, None, KernelReadOperation::Opendir { serial })?; + let handle = answer.directory.ok_or(Status::ServerFault)?; + // The visit read the directory's own row: remember it, so a LOOKUP in + // this directory answers its `dir_attributes` from memory. + self.observed(&answer.stat); let evicted = { let mut table = self.table(); let tick = table.tick(); diff --git a/engine/crates/layerfs-nfs/src/nfs.rs b/engine/crates/layerfs-nfs/src/nfs.rs index ecffcda5f0..526a436c71 100644 --- a/engine/crates/layerfs-nfs/src/nfs.rs +++ b/engine/crates/layerfs-nfs/src/nfs.rs @@ -107,15 +107,32 @@ pub fn call( 3 => { let parent = handle(kernel, arguments).map_err(garbage)?; let name = arguments.opaque(NAME_LIMIT).map_err(garbage)?; - // Both answers carry the directory's attributes (RFC 1813 - // LOOKUP3resok and LOOKUP3resfail), so the client keeps its - // cached view of the directory without a GETATTR of its own. - let directory = parent - .as_ref() - .ok() - .and_then(|parent| kernel.getattr(*parent).ok()); - match parent.and_then(|parent| kernel.lookup(parent, name)) { - Ok(stat) => { + // One owner job answers the entry and the directory it was named + // in (RFC 1813 LOOKUP3resok's `obj_attributes` and + // `dir_attributes`, and the failure's). The job had to read the + // directory's own row to resolve the name, so its attributes cost + // no second job. Deliberate change from the route before this: a + // failure (`NFS3ERR_NOENT` included), `.`, `..` and a silly name + // answer the directory facts this export last published or + // observed for it, and none when it never saw the directory, + // where each of them used to make a fresh GETATTR of the parent. + // RFC 1813 keeps those attributes optional, so both are legal; + // the answer is now at most one observation old. + let (parent, found) = match parent { + Ok(parent) => (parent, kernel.lookup(parent, name)), + Err(status) => { + out.u32(status.code()); + post_op_maybe(kernel.identity(), out, None); + return Ok(()); + } + }; + let directory = match &found { + Ok((_, directory)) => directory.clone(), + Err(_) => None, + } + .or_else(|| kernel.directory_wcc(parent).0); + match found { + Ok((stat, _)) => { out.u32(Status::Ok.code()); out.opaque(&kernel.encode(stat.serial)); kernel.identity().post_op(out, &stat); @@ -188,8 +205,10 @@ pub fn call( let verifier = arguments.fixed(8).map_err(garbage)?; let mut budget = arguments.u32().map_err(garbage)?; if plus { - // dircount bounds the names alone; maxcount the whole reply. - let _dircount = budget; + // A READDIRPLUS request carries the entries' own count + // (`dircount`) before the reply's (`maxcount`). Only the + // reply's bounds what this export sends: the client sized its + // buffer by it, and names alone are never what fills a reply. budget = arguments.u32().map_err(garbage)?; } let mut word = [0; 8]; diff --git a/engine/crates/layerfs-nfs/tests/export.rs b/engine/crates/layerfs-nfs/tests/export.rs index e14ea03528..087397c779 100644 --- a/engine/crates/layerfs-nfs/tests/export.rs +++ b/engine/crates/layerfs-nfs/tests/export.rs @@ -9,6 +9,9 @@ mod client; #[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::{Attr, Client, BADHANDLE, BAD_COOKIE, NOENT, ROFS, STALE}; @@ -19,6 +22,7 @@ use std::{ net::TcpListener, os::unix::fs::{MetadataExt, PermissionsExt}, path::{Path, PathBuf}, + sync::{atomic::Ordering, Arc}, time::Duration, }; use tree::{oracle, walk, Node}; @@ -374,3 +378,172 @@ fn cookies_refusals_and_stale_handles() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_lookup_spends_one_owner_visit() { + let base = temp("lookup"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let watch = Arc::new(spy::Watch::default()); + let services = Arc::new(spy::Spy { + inner: Arc::new(layerfs_daemon::Mounted(rig.bound.clone())), + watch: watch.clone(), + }); + let server = rig.export_services( + TcpListener::bind("127.0.0.1:0").unwrap(), + services, + UID, + GID, + false, + ); + let mut client = Client::connect(server.local_addr(), UID, GID); + let root = client.mnt("/"); + + // RFC 1813 answers the entry's attributes and its directory's: the one + // visit that resolved the name had to read the directory's row too. The + // names are looked up once first, so the visit below is the steady state + // and not the mount's first read of a base name. + client.lookup(&root, b"src").unwrap(); + assert_eq!(client.lookup(&root, b"absent").map(|_| ()), Err(NOENT)); + let root_attr: Attr = client.getattr(&root).unwrap(); + + let visits = watch.visits.load(Ordering::Acquire); + let (status, found, directory) = client.lookup_with_directory(&root, b"src"); + assert_eq!(status, 0); + let (_, src_attr) = found.clone().expect("the directory's own name"); + assert_eq!( + watch.visits.load(Ordering::Acquire) - visits, + 1, + "one owner visit for a LOOKUP and its directory" + ); + assert_eq!( + directory, + Some(root_attr.clone()), + "the directory it was named in" + ); + + // A missing name is one visit as well, and answers the directory facts + // the export already published for it. + let visits = watch.visits.load(Ordering::Acquire); + let (status, found, directory) = client.lookup_with_directory(&root, b"absent"); + assert_eq!((status, found), (NOENT, None)); + assert_eq!( + watch.visits.load(Ordering::Acquire) - visits, + 1, + "one owner visit for a failing LOOKUP" + ); + assert_eq!(directory, Some(root_attr)); + + // The name resolved to the same inode a later LOOKUP reports, and the + // directory half of the reply is the directory's own facts. + let (_, again) = client.lookup(&root, b"src").unwrap(); + assert_eq!(again.fileid, src_attr.fileid, "the same inode"); + drop(client); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_listing_spends_one_owner_visit_and_reads_its_window_in_batches() { + let base = temp("listing"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let watch = Arc::new(spy::Watch::default()); + let services = Arc::new(spy::Spy { + inner: Arc::new(layerfs_daemon::Mounted(rig.bound.clone())), + watch: watch.clone(), + }); + let server = rig.export_services( + TcpListener::bind("127.0.0.1:0").unwrap(), + services, + UID, + GID, + false, + ); + let mut client = Client::connect(server.local_addr(), UID, GID); + let root = client.mnt("/"); + let (many, _) = client.lookup(&root, b"many").unwrap(); + + // A directory of 700 inherited names over several replies: one OPENDIR + // visit for the whole enumeration, at most one Store reader per reply, + // and never one per listed name — the window's names, kinds and facts + // are read in batches outside the owner. + let (visits, bases) = ( + watch.visits.load(Ordering::Acquire), + watch.bases.load(Ordering::Acquire), + ); + let (entries, calls) = client.list(&many, 64 * 1024, true); + assert!(calls > 1, "a budget spreads one directory over replies"); + assert_eq!(entries.len(), MANY + 2, "every name, once"); + for entry in entries + .iter() + .filter(|entry| entry.name != b"." && entry.name != b"..") + { + // Every inherited name arrives with both optional fields, so the + // client needs no LOOKUP per name on a cold tree. + assert!( + entry.attr.is_some(), + "READDIRPLUS attributes: {:?}", + entry.name + ); + assert!( + entry.handle.is_some(), + "READDIRPLUS handle: {:?}", + entry.name + ); + } + assert_eq!( + watch.visits.load(Ordering::Acquire) - visits, + 1, + "one owner visit for the whole enumeration" + ); + assert!( + watch.bases.load(Ordering::Acquire) - bases <= calls, + "at most one Store reader per reply, never one per name" + ); + // Each handed-out handle holds one reference, and an identical reply + // reuses the published offsets instead of taking more. + let held = server.held().lookups; + assert_eq!(held, 1 + MANY, "the directory and one reference per entry"); + let (again, _) = client.list(&many, 64 * 1024, true); + assert_eq!(again.len(), entries.len(), "the same names again"); + assert_eq!( + server.held().lookups, + held, + "no second reference for a listed name" + ); + + // A directory this export created is answered from the rows its visit + // already read: its listing takes no Store reader at all. + client.mkdir(&root, b"local", 0o755).unwrap(); + let (local, _) = client.lookup(&root, b"local").unwrap(); + client.touch(&local, b"a", 0o644).unwrap(); + let bases = watch.bases.load(Ordering::Acquire); + let (entries, _, _) = client + .readdir(&local, 0, 0, 4096, true) + .map(|(entries, _, eof)| (entries, eof, ())) + .unwrap(); + let created = entries + .iter() + .find(|entry| entry.name == b"a") + .expect("the created name"); + assert!( + created.attr.is_some() && created.handle.is_some(), + "a local row carries its facts and its handle" + ); + assert_eq!( + watch.bases.load(Ordering::Acquire), + bases, + "a local listing takes no Store reader" + ); + + drop(client); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} diff --git a/engine/crates/layerfs-nfs/tests/support/spy.rs b/engine/crates/layerfs-nfs/tests/support/spy.rs index ea761166d9..c96973dafb 100644 --- a/engine/crates/layerfs-nfs/tests/support/spy.rs +++ b/engine/crates/layerfs-nfs/tests/support/spy.rs @@ -42,6 +42,12 @@ pub struct Watch { /// Each engine read window the export asked for: offset and length. One /// call may fill its whole transfer from several of them. pub reads: Mutex>, + /// Owner read visits (`observe_visit`): the jobs a LOOKUP, GETATTR or + /// OPEN spends. One LOOKUP spends exactly one. + pub visits: AtomicU64, + /// Store readers a request took for a base demand: at most one per reply, + /// never one per listed name. + pub bases: AtomicU64, } pub struct Spy { pub inner: Arc, @@ -70,9 +76,10 @@ impl RequestServices for Request { handle: u64, offset: u64, after: Option>, + attributes: bool, ) -> ServiceFuture<'_, ServiceReply>> { self.inner - .directory_visit(mount, serial, handle, offset, after) + .directory_visit(mount, serial, handle, offset, after, attributes) } fn publish_cookies( &self, @@ -123,10 +130,12 @@ impl RequestServices for Request { operation: KernelReadOperation, facts: Arc, ) -> ServiceFuture<'_, ServiceReply>> { + self.watch.visits.fetch_add(1, Ordering::AcqRel); self.inner .observe_visit(mount, request, serial, handle, operation, facts) } fn base(&self) -> ServiceFuture<'_, BaseView> { + self.watch.bases.fetch_add(1, Ordering::AcqRel); self.inner.base() } fn mutate_visit( diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index a6c94d0f74..8d93ae59a2 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -831,12 +831,13 @@ impl layerfs_mount_ports::ports::RequestServices for CountingRequest { handle: u64, offset: u64, after: Option>, + attributes: bool, ) -> layerfs_mount_ports::ports::ServiceFuture< '_, layerfs_mount_ports::ports::ServiceReply>, > { self.inner - .directory_visit(mount, serial, handle, offset, after) + .directory_visit(mount, serial, handle, offset, after, attributes) } fn publish_cookies( &self, @@ -1014,8 +1015,9 @@ fn create_write_remove_and_apple_double_avoid_redundant_owner_jobs_and_orphans() // 4. AppleDouble companion changing lifecycle (CREATE, WRITE, SETATTR, // REMOVE) issues 0 SQLite owner jobs (0 observe_visit, 0 mutate_visit), - // and LOOKUP of an absent companion issues 0 lookup observe_visit - // (only the 1 parent getattr in nfs.rs proc 3). + // and LOOKUP of an absent companion issues none either: the export + // refuses the name before any visit, and the reply's directory + // attributes come from the facts it already published. let before = counts.snapshot(); let ad = c.touch(&root, b"._single.txt", 0o644).unwrap(); // The directory's wcc_data is not a hole: a companion changes nothing in @@ -1055,8 +1057,8 @@ fn create_write_remove_and_apple_double_avoid_redundant_owner_jobs_and_orphans() assert_eq!(c.lookup(&root, b"._single.txt").map(|_| ()), Err(NOENT)); assert_eq!( counts.snapshot(), - (before.0 + 1, before.1, before.2, before.3), - "AppleDouble LOOKUP avoids the target lookup visit" + before, + "an absent AppleDouble LOOKUP issues no owner job at all" ); // 5. REMOVE drops the last link and retires the synthetic kernel's file diff --git a/engine/crates/layerfs-workspace/src/lib.rs b/engine/crates/layerfs-workspace/src/lib.rs index 323588aa04..dd93212f7e 100644 --- a/engine/crates/layerfs-workspace/src/lib.rs +++ b/engine/crates/layerfs-workspace/src/lib.rs @@ -55,12 +55,13 @@ pub use operations::file::recognize::{ }; pub use operations::kernel_data::{KernelDataVisit, KernelWindow}; pub use operations::kernel_directory::{ - KernelDirectoryBatch, KernelDirectoryEntry, KernelDirectoryListing, KernelDirectoryVisit, - KernelDirectoryWindow, + KernelDirectoryBatch, KernelDirectoryEntry, KernelDirectoryListing, KernelDirectoryRead, + KernelDirectoryVisit, KernelDirectoryWindow, }; pub use operations::kernel_mutation::KernelMutationOutcome; pub use operations::kernel_read::{ - KernelReadDecision, KernelReadFailure, KernelReadOperation, KernelReadOutcome, KernelReadValue, + Decided, KernelReadDecision, KernelReadFailure, KernelReadOperation, KernelReadOutcome, + KernelReadValue, }; pub use operations::kernel_visit::{ KernelInput, KernelMutationVisit, KernelReadVisit, KernelVisitRequest, diff --git a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs index c6a9d54b63..faf107337f 100644 --- a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs @@ -3,16 +3,25 @@ //! kernel offset, and one window of current local names with their kinds. //! Inherited names and kinds are merged inside the job when the canonical //! cache holds them; otherwise the request merges them outside the owner -//! over one Store reader, at the base root the visit named. The request then -//! fills its reply and a publishing visit records exactly the accepted -//! names. Nothing is held between the two visits or after the reply. +//! over one Store reader, at the base root the visit named. A reply that +//! shows each entry's facts (READDIRPLUS) takes them from the same memory +//! first, and reads what is left in one batch inode demand and one batch +//! length demand for the whole window, whatever its size. What those batches +//! do not cover is per entry and unchanged here: a non-inline metadata root, +//! a listed subdirectory's child-directory count, and a symlink's target are +//! still read once for each entry that needs them. The request then fills its +//! reply and a publishing visit records exactly the accepted names. Nothing +//! is held between the two visits or after the reply. use crate::{BaseView, SourceView, ViewStat, Workspace, WorkspaceResult}; -use layerfs_content::{object::inode_leaf::InodeKind, ContentError}; +use layerfs_content::filesystem::inode::{lookup_many, InodeReadWork}; +use layerfs_content::filesystem::Resolved; +use layerfs_content::object::inode_leaf::{InodeKind, InodeValue}; +use layerfs_content::{ContentError, ObjectId}; use layerfs_overlay::{ KernelCookieOffer, KernelDirectoryCursor, KernelDirectoryPage, KernelMount, Overlay, OverlayError, OverlayResult, PAGE_ROWS, }; -use std::{fmt, sync::Arc}; +use std::{collections::BTreeMap, collections::BTreeSet, fmt, sync::Arc}; #[derive(Clone, Debug, Eq, PartialEq)] pub struct KernelDirectoryEntry { @@ -30,6 +39,16 @@ pub struct KernelDirectoryListing { pub continuation: Option>, pub visited: usize, } +/// Where one enumeration request reads and what its reply shows. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct KernelDirectoryRead { + /// The kernel offset this request resumes at. + pub offset: u64, + /// The name it continues after, when it continues an earlier window. + pub after: Option>, + /// The reply shows each entry's facts (READDIRPLUS). + pub attributes: bool, +} /// One READDIR reading visit as one read-only owner job. #[derive(Clone)] pub struct KernelDirectoryVisit { @@ -39,20 +58,23 @@ pub struct KernelDirectoryVisit { offset: u64, after: Option>, resident: BaseView, + /// The reply shows each entry's facts (READDIRPLUS): this visit answers + /// from memory what it holds, and the request reads only what it left. + attributes: bool, } /// What the reading visit found, as plain values its request owns. #[derive(Clone, Debug)] pub struct KernelDirectoryWindow { pub page: KernelDirectoryPage, /// The merged names of the window, when memory answered every inherited - /// name and kind inside the job. + /// name and kind inside the job; a reply that shows facts also takes + /// from here every fact memory held. pub listing: Option, /// The offsets the reply may hand out. Absent when the job decided that /// the window lists no name. pub offer: Option, /// The facts of the directory being listed, when the visit read its own - /// local row and the reply shows them: a READDIRPLUS reply's - /// `dir_attributes` then costs no further read. + /// local row: a reply's `dir_attributes` then costs no further read. pub directory: Option, } /// The entries one reply may offer, in order, with their offsets. @@ -87,17 +109,22 @@ impl fmt::Debug for KernelDirectoryVisit { } } impl Workspace { - /// `resident` answers from memory only. No I/O here. `after` continues - /// an earlier window of the same request past names that listed nothing. + /// `resident` answers from memory only. No I/O here. `read` names the + /// position (continuing past names that listed nothing) and whether the + /// reply shows each entry's facts. pub fn kernel_directory_visit( &self, resident: Arc, mount: KernelMount, serial: u64, handle: u64, - offset: u64, - after: Option>, + read: KernelDirectoryRead, ) -> WorkspaceResult { + let KernelDirectoryRead { + offset, + after, + attributes, + } = read; let base = self.base()?; if mount.engine() != self.route().engine() || mount.root_serial() != base.root().root_inode().serial() @@ -111,6 +138,7 @@ impl Workspace { offset, after, resident: base.with_client(resident), + attributes, }) } } @@ -145,7 +173,18 @@ impl KernelDirectoryVisit { } let listing = (self.resident.identity().0.to_bytes() == page.source().root()) .then(|| listing(&self.resident, &page).ok()) - .flatten(); + .flatten() + .map(|mut listing| { + // A reply that shows facts takes the local rows this window + // already read and whatever else memory answers, so only the + // names memory left undecided take the one Store read. + if self.attributes { + for entry in &mut listing.entries { + entry.stat = memory_stat(&self.resident, &page, entry.serial); + } + } + listing + }); let offer = match &listing { Some(listing) if listing.entries.is_empty() => None, _ => Some(db.offer_kernel_cookies(&page)?), @@ -169,6 +208,16 @@ impl KernelDirectoryWindow { pub fn rewound(&self) -> bool { *self.page.cursor() == KernelDirectoryCursor::Rewound } + /// Whether this reply needs the Store reader at all: the visit left the + /// merge undone, or the reply shows facts of a name memory did not hold. + /// A local directory, and a window whose inherited entries are all + /// resident, take no reader and issue no Store read. + pub fn needs_base(&self, attributes: bool) -> bool { + match &self.listing { + None => true, + Some(listing) => attributes && listing.entries.iter().any(|entry| entry.stat.is_none()), + } + } /// The entries this window may offer and their offsets. `base` is the /// Workspace's base over an admitted Store reader and is required when /// the visit left the merge undone; it is read at the root the visit @@ -180,14 +229,19 @@ impl KernelDirectoryWindow { /// the offer's fresh range. /// /// A plain READDIR reply shows no entry's facts, so this reads no - /// portable metadata and no file length. + /// portable metadata and no file length for one: only the names, their + /// kinds and their offsets. pub fn finish(self, base: Option<&BaseView>) -> WorkspaceResult { self.finish_with(base, false) } /// The same for a reply that also shows what each accepted entry is, as - /// READDIRPLUS does: every entry's facts and the directory's own are read - /// here, outside the owner, from the authoritative base — a local entry's - /// facts are its current row, an inherited one's its immutable inode. + /// READDIRPLUS does. The reading visit already said what memory held; the + /// names it left undecided are read here in one batch inode demand and + /// one batch length demand for the whole window, so the number of names + /// adds no demand. Those two batches are not the whole cost of an entry: + /// [`base_facts`] still reads an inherited inode's non-inline metadata + /// root, a listed subdirectory's child-directory count and a symlink's + /// target once per entry that needs them, as the base route always did. pub fn finish_with( self, base: Option<&BaseView>, @@ -199,14 +253,19 @@ impl KernelDirectoryWindow { offer, directory, } = self; - // A reply that shows an entry's facts reads the authoritative base, - // not the resident one the reading visit merged with. + // The authoritative base is read at the root the visit named, and + // only when memory did not answer the window's names or its facts. + let undecided = attributes + && merged + .as_ref() + .is_none_or(|listing| listing.entries.iter().any(|entry| entry.stat.is_none())); let base = match base { - Some(base) if attributes || merged.is_none() => Some(base.at(page.source().root())?), + Some(base) if merged.is_none() || undecided => Some(base.at(page.source().root())?), _ => None, }; let listing = match (merged, base.as_deref()) { - (Some(listing), _) if !attributes => listing, + (Some(listing), _) => listing, + (_, Some(base)) if attributes => listing_with_facts(base, &page)?, (_, Some(base)) => listing(base, &page)?, (_, None) => { return Err( @@ -238,15 +297,11 @@ impl KernelDirectoryWindow { _ => (offer.first(), Some(offer)), }, }; - // Only the names this reply actually offers are read, and only a - // reply that shows facts reads anything at all. - let (directory, entries) = match base.as_deref() { - Some(base) if attributes => ( - directory.or_else(|| base_stat(base, page.directory().serial()).ok()), - facts(base, &page, entries)?, - ), - _ => (None, entries), - }; + if attributes { + if let Some(base) = base.as_deref() { + facts(base, &page, &mut entries)?; + } + } let exhausted = !truncated && listing.continuation.is_none(); Ok(KernelDirectoryBatch { entries, @@ -258,33 +313,117 @@ impl KernelDirectoryWindow { }) } } -/// One listing's entries with the facts a reply shows for each: a local -/// serial's current row, or an inherited one's immutable base inode. +/// Fills the facts a reply shows for the entries that still lack them: the +/// window's inherited serials in one batch inode demand, and the lengths of +/// its regular files in one batch length demand, so listing more names costs +/// no more of either. A local serial's facts are its current row. What +/// [`base_facts`] still reads once per entry is not batched here. fn facts( base: &BaseView, page: &KernelDirectoryPage, - entries: Vec, -) -> WorkspaceResult> { - entries + entries: &mut [KernelDirectoryEntry], +) -> WorkspaceResult<()> { + let inherited: Vec = entries + .iter() + .filter(|entry| entry.stat.is_none() && local_row(page, entry.serial).is_none()) + .map(|entry| entry.serial) + .collect::>() .into_iter() - .map(|mut entry| { - entry.stat = Some( - match page - .local_inodes - .binary_search_by_key(&entry.serial, |row| row.0) - { - Ok(index) => ViewStat::from(page.local_inodes[index].1.clone()), - Err(_) => base_stat(base, entry.serial)?, - }, - ); - Ok(entry) - }) - .collect() + .collect(); + let found = inherited_values(base, &inherited)?; + for entry in entries.iter_mut().filter(|entry| entry.stat.is_none()) { + entry.stat = Some(match local_row(page, entry.serial) { + Some(row) => ViewStat::from(row.clone()), + None => { + let value = *found.get(&entry.serial).ok_or(ContentError::PathNotFound)?; + base_facts(base, entry.serial, value)? + } + }); + } + Ok(()) +} +/// The base value of every inherited serial in one batch inode demand, after +/// one length demand has remembered the window's ordinary file lengths. +fn inherited_values( + base: &BaseView, + serials: &[u64], +) -> WorkspaceResult> { + if serials.is_empty() { + return Ok(BTreeMap::new()); + } + let values = lookup_many( + base.client().as_ref(), + base.table(), + serials, + &mut InodeReadWork::default(), + )?; + // Every ordinary file's length, from the one demand this window makes. + let roots: Vec = values + .iter() + .flatten() + .filter(|value| value.kind == InodeKind::RegularFile) + .map(|value| value.content_root) + .collect(); + if !roots.is_empty() { + base.client().provide_lengths(&roots)?; + } + Ok(serials + .iter() + .copied() + .zip(values) + .filter_map(|(serial, value)| Some((serial, value?))) + .collect()) +} +/// The facts of one inherited name: its base inode, the metadata every +/// attribute carries, its content length and, for a directory, the count its +/// POSIX link count is derived from. The metadata root, a directory's child +/// directory count and a symlink's target are read here one entry at a time: +/// the base has no batch port for them, and this route adds none. +fn base_facts(base: &BaseView, serial: u64, value: InodeValue) -> WorkspaceResult { + let stat = + base.stat_resolved_with_lengths(Resolved { serial, value }, base.client().as_ref())?; + let subdirs = match stat.value.kind { + InodeKind::Directory => base.subdirs(stat.value)?, + _ => 0, + }; + Ok(ViewStat::of_base(stat, subdirs)) +} +/// The local row of one listed serial at this window's view, when it has one. +fn local_row(page: &KernelDirectoryPage, serial: u64) -> Option<&layerfs_overlay::Inode> { + page.local_inodes + .binary_search_by_key(&serial, |row| row.0) + .ok() + .map(|index| &page.local_inodes[index].1) +} +/// The content kind of a local row's kind. +const fn kind_of(kind: layerfs_overlay::InodeKind) -> InodeKind { + match kind { + layerfs_overlay::InodeKind::File => InodeKind::RegularFile, + layerfs_overlay::InodeKind::Directory => InodeKind::Directory, + layerfs_overlay::InodeKind::Symlink => InodeKind::Symlink, + } +} +/// The facts of one entry as far as memory alone answers them: a local row, +/// or an inherited inode whose value, metadata, length and child-directory +/// count this daemon's caches already hold. Anything else is absent here, and +/// the request's one Store read supplies it. +fn memory_stat(base: &BaseView, page: &KernelDirectoryPage, serial: u64) -> Option { + if let Some(row) = local_row(page, serial) { + return Some(ViewStat::from(row.clone())); + } + let value = base.inode(serial).ok()?.value; + base_facts(base, serial, value).ok() +} +/// One window's listed names over `base`, before their kinds and facts. +struct MergedNames { + names: Vec<(Vec, u64)>, + continuation: Option>, + visited: usize, } /// One window's merged names over `base`, which must be the page's own base /// root. This issues no SQL and acquires no kernel lookup reference. An /// empty result with a continuation needs another window of the same request. -fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult { +fn merge(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult { let view = SourceView { base: base.clone(), source: page.source(), @@ -306,8 +445,8 @@ fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult WorkspaceResult match page.local_inodes[index].1.kind { - layerfs_overlay::InodeKind::File => InodeKind::RegularFile, - layerfs_overlay::InodeKind::Directory => InodeKind::Directory, - layerfs_overlay::InodeKind::Symlink => InodeKind::Symlink, - }, - Err(_) => view.base().inode(serial)?.value.kind, + Ok(MergedNames { + names: listing.entries, + continuation: listing.continuation, + visited: listing.visited, + }) +} +/// The same window with the facts a reply shows for every entry: a local +/// row, or an inherited inode read in one batch demand for the whole window. +fn listing_with_facts( + base: &BaseView, + page: &KernelDirectoryPage, +) -> WorkspaceResult { + let merged = merge(base, page)?; + let inherited: Vec = merged + .names + .iter() + .map(|(_, serial)| *serial) + .filter(|serial| local_row(page, *serial).is_none()) + .collect::>() + .into_iter() + .collect(); + let found = inherited_values(base, &inherited)?; + let mut entries = Vec::with_capacity(merged.names.len()); + for (name, serial) in merged.names { + let (kind, stat) = match local_row(page, serial) { + Some(row) => (kind_of(row.kind), ViewStat::from(row.clone())), + None => { + let value = *found.get(&serial).ok_or(ContentError::PathNotFound)?; + (value.kind, base_facts(base, serial, value)?) + } }; entries.push(KernelDirectoryEntry { name, serial, kind, - stat: None, + stat: Some(stat), }); } Ok(KernelDirectoryListing { entries, - continuation: listing.continuation, - visited: listing.visited, + continuation: merged.continuation, + visited: merged.visited, }) } -/// The effective facts of one inherited name: its base inode, the metadata -/// every attribute carries, its content length and, for a directory, the -/// child-directory count its POSIX link count is derived from. -fn base_stat(base: &BaseView, serial: u64) -> WorkspaceResult { - let stat = base.stat(serial)?; - let subdirs = match stat.value.kind { - InodeKind::Directory => base.subdirs(stat.value)?, - _ => 0, - }; - Ok(ViewStat::of_base(stat, subdirs)) +/// One window's merged names over `base` with their kinds, read from memory +/// alone: a local row, or an inherited inode the canonical cache answers. +fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult { + let merged = merge(base, page)?; + let mut entries = Vec::with_capacity(merged.names.len()); + for (name, serial) in merged.names { + let kind = match local_row(page, serial) { + Some(row) => kind_of(row.kind), + None => base.inode(serial)?.value.kind, + }; + entries.push(KernelDirectoryEntry { + name, + serial, + kind, + stat: None, + }); + } + Ok(KernelDirectoryListing { + entries, + continuation: merged.continuation, + visited: merged.visited, + }) } diff --git a/engine/crates/layerfs-workspace/src/operations/kernel_read.rs b/engine/crates/layerfs-workspace/src/operations/kernel_read.rs index a0bfea566e..45b0f3205f 100644 --- a/engine/crates/layerfs-workspace/src/operations/kernel_read.rs +++ b/engine/crates/layerfs-workspace/src/operations/kernel_read.rs @@ -32,15 +32,26 @@ pub enum KernelReadOperation { #[derive(Debug)] pub enum KernelReadDecision { Needs(Vec), - Value(Inode), + Value(Decided), Refused(Refusal), Failed(WorkspaceError), } +/// What a read decided: the inode it names and, for a LOOKUP, the directory +/// it named it in. That job read the directory's own row to resolve the name, +/// so a reply that shows the directory's attributes needs no second visit. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct Decided { + pub inode: Inode, + pub parent: Option, +} pub type KernelReadOutcome = KernelObservation; #[derive(Debug)] pub struct KernelReadValue { pub stat: ViewStat, + /// The directory a LOOKUP named the inode in, from the same job: a reply + /// that carries the directory's attributes reads nothing more for them. + pub parent: Option, pub file: Option, pub directory: Option, pub original: Arc, @@ -91,7 +102,7 @@ pub(crate) fn decide_read( needs: Vec::new(), }; let decision = match decide(operation, &mut eval) { - Ok(Some(inode)) => KernelReadDecision::Value(inode), + Ok(Some(decided)) => KernelReadDecision::Value(decided), Ok(None) if !eval.needs.is_empty() => KernelReadDecision::Needs(eval.needs), Ok(None) => KernelReadDecision::Failed( ContentError::InvalidRecord("empty kernel read needs").into(), @@ -102,8 +113,8 @@ pub(crate) fn decide_read( }; Ok(match decision { KernelReadDecision::Needs(_) => KernelDecision::Needs(decision), - KernelReadDecision::Value(ref inode) => KernelDecision::Finished { - inode: Some(inode.clone()), + KernelReadDecision::Value(ref decided) => KernelDecision::Finished { + inode: Some(decided.inode.clone()), value: decision, }, _ => KernelDecision::Finished { @@ -112,20 +123,34 @@ pub(crate) fn decide_read( }, }) } -fn decide(operation: &KernelReadOperation, eval: &mut Eval<'_>) -> WorkspaceResult> { +fn decide( + operation: &KernelReadOperation, + eval: &mut Eval<'_>, +) -> WorkspaceResult> { match operation { // The source's independent read reference permits removed metadata. KernelReadOperation::Getattr { serial } | KernelReadOperation::Data { serial } => { - eval.target(*serial) + Ok(eval.target(*serial)?.map(|inode| Decided { + inode, + parent: None, + })) + } + KernelReadOperation::Opendir { serial } => { + Ok(eval.directory(*serial)?.map(|inode| Decided { + inode, + parent: None, + })) } - KernelReadOperation::Opendir { serial } => eval.directory(*serial), // The kernel names an inode it still references. A file whose // last name is gone stays openable under that reference, so a // path open racing an unlink or replacement gets the old file. KernelReadOperation::Open { serial, .. } => { let inode = eval.target(*serial)?; match inode { - Some(inode) if inode.kind == InodeKind::File => Ok(Some(inode)), + Some(inode) if inode.kind == InodeKind::File => Ok(Some(Decided { + inode, + parent: None, + })), Some(inode) if inode.kind == InodeKind::Directory => { Err(WorkspaceError::Refused(Refusal::IsDirectory)) } @@ -137,11 +162,16 @@ fn decide(operation: &KernelReadOperation, eval: &mut Eval<'_>) -> WorkspaceResu let directory = eval.directory(*parent)?; let layers = eval.layers(*parent, name)?; let bound = eval.bound(*parent, directory.as_ref(), name, layers); - let (Some(_), Some(bound)) = (directory, bound) else { + let (Some(directory), Some(bound)) = (directory, bound) else { return Ok(None); }; let serial = bound.ok_or(WorkspaceError::Refused(Refusal::Missing))?; - eval.target(serial) + // The name resolved, so the reply also says what the directory + // is: the same job read its row, and no second visit is needed. + Ok(eval.target(serial)?.map(|inode| Decided { + inode, + parent: Some(directory), + })) } } } diff --git a/engine/crates/layerfs-workspace/tests/common/mod.rs b/engine/crates/layerfs-workspace/tests/common/mod.rs index 83fbcbb5d5..702bfffdb6 100644 --- a/engine/crates/layerfs-workspace/tests/common/mod.rs +++ b/engine/crates/layerfs-workspace/tests/common/mod.rs @@ -28,10 +28,18 @@ pub struct Store { pub lengths: Arc>>, /// Canonical bytes served upstream, to tell metadata demand from payload. pub served: Arc, + /// Object batch demands: one per `read_canonical_batch` call, whatever + /// the number of objects it names. A window's SQL batches, not its rows. + pub batches: Arc, + /// Length demands that asked for several ids in one call. + pub length_batches: Arc, + /// Length demands that asked for one id at a time. + pub length_demands: Arc, } impl AuthenticatedObjects for Store { fn read_canonical_batch(&self, ids: &[ObjectId]) -> ContentResult>> { self.demand.fetch_add(ids.len() as u64, Ordering::Relaxed); + self.batches.fetch_add(1, Ordering::Relaxed); let objects = self.objects.lock().unwrap(); ids.iter() .map(|id| { @@ -47,6 +55,7 @@ impl AuthenticatedObjects for Store { } impl layerfs_workspace::FileLengths for Store { fn file_length(&self, id: ObjectId) -> layerfs_workspace::WorkspaceResult { + self.length_demands.fetch_add(1, Ordering::Relaxed); self.lengths .lock() .unwrap() @@ -54,6 +63,18 @@ impl layerfs_workspace::FileLengths for Store { .copied() .ok_or(ContentError::MissingObject.into()) } + fn file_lengths(&self, ids: &[ObjectId]) -> layerfs_workspace::WorkspaceResult> { + self.length_batches.fetch_add(1, Ordering::Relaxed); + let lengths = self.lengths.lock().unwrap(); + ids.iter() + .map(|id| { + lengths + .get(id) + .copied() + .ok_or(ContentError::MissingObject.into()) + }) + .collect() + } } impl FinalizedConsumer for Store { fn accept(&mut self, object: FinalizedObject) -> ContentResult<()> { diff --git a/engine/crates/layerfs-workspace/tests/directory_links.rs b/engine/crates/layerfs-workspace/tests/directory_links.rs index 2940c31d30..59c278ad5d 100644 --- a/engine/crates/layerfs-workspace/tests/directory_links.rs +++ b/engine/crates/layerfs-workspace/tests/directory_links.rs @@ -575,7 +575,12 @@ fn a_visit_that_misses_the_count_is_undecided_writes_nothing_and_decides_once_su panic!("the supplied facts did not decide the lookup") }; assert_eq!( - (found.serial, found.entries, found.subdirs, found.nlink), + ( + found.inode.serial, + found.inode.entries, + found.inode.subdirs, + found.inode.nlink + ), (MIXED, 5, 2, 1) ); // Another request, carrying nothing, decides in its one visit: the @@ -688,7 +693,13 @@ fn remembered_counts_are_bounded_and_an_evicted_one_is_derived_again() { let Some(KernelReadDecision::Value(found)) = observe(&b, mount, "d00000", &facts) else { panic!("the carried facts did not decide the lookup") }; - assert_eq!((found.serial, found.entries, found.subdirs), (100, 3, 2)); + assert_eq!( + (found.inode.serial, found.inode.entries, found.inode.subdirs), + (100, 3, 2) + ); + // The same job answered the directory the name was looked up in, so a + // reply that shows the directory's attributes pays no second visit. + assert_eq!(found.parent.expect("the lookup's directory").serial, 1); assert_eq!(work().directory_count_scans, capacity + 3); // Both were evicted: each is derived again, correctly, and remembered diff --git a/engine/crates/layerfs-workspace/tests/kernel_directory.rs b/engine/crates/layerfs-workspace/tests/kernel_directory.rs index 2f1e4f4438..ddc577f1ce 100644 --- a/engine/crates/layerfs-workspace/tests/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/tests/kernel_directory.rs @@ -4,14 +4,16 @@ mod harness; use harness::{create, mkdir, path, rename, rmdir, unlink, Bench, T1, T2}; use layerfs_content::{ filesystem::{ - update_filesystem, DirectoryUpdate, FilesystemInput, FilesystemObjects, FilesystemResources, + attributes::PortableMetadata, build_filesystem, scope_for_seed, update_filesystem, + DirectoryUpdate, FilesystemInput, FilesystemObjects, FilesystemResources, InodeUpdate, }, - object::inode_leaf::InodeKind, + object::inode_leaf::{InodeKind, InodeMetadata, InodeValue}, + ObjectId, }; use layerfs_overlay::{KernelDirectory, KernelMount, OverlayError, PAGE_ROWS}; use layerfs_workspace::{ - CanonicalCache, CanonicalClient, KernelDirectoryBatch, KernelDirectoryWindow, - KernelReadDecision, KernelReadOperation, VisitFacts, + CanonicalCache, CanonicalClient, KernelDirectoryBatch, KernelDirectoryRead, + KernelDirectoryWindow, KernelReadDecision, KernelReadOperation, VisitFacts, }; use std::sync::Arc; /// A memory-only client over a cache that holds nothing. @@ -69,6 +71,16 @@ fn visit( directory: KernelDirectory, offset: u64, after: Option>, +) -> Result { + visit_with(b, directory, offset, after, false) +} +/// The same, for a reply that shows each entry's facts (READDIRPLUS). +fn visit_with( + b: &Bench, + directory: KernelDirectory, + offset: u64, + after: Option>, + attributes: bool, ) -> Result { let visit = b .workspace @@ -77,8 +89,11 @@ fn visit( directory.mount(), directory.serial(), directory.owner_id(), - offset, - after, + KernelDirectoryRead { + offset, + after, + attributes, + }, ) .unwrap(); let before = b.demand(); @@ -316,3 +331,206 @@ fn next_directory_read_observes_parent_moved_by_the_atomic_namespace_job() { .unwrap(); b.overlay.revoke_kernel_mount(mount).unwrap(); } +/// A root holding `files` inherited regular files, each with its own content, +/// and one inherited subdirectory with a file of its own: a window whose +/// names, kinds, lengths and child-directory count all come from the base. +fn window_fixture(files: u64) -> common::Fixture { + let store = common::Store::default(); + let scope = scope_for_seed([21; 32]); + let directory = InodeMetadata::Inline(PortableMetadata { + mode: 0o755, + mtime_seconds: 7, + mtime_nanoseconds: 3, + }); + let regular = InodeMetadata::Inline(PortableMetadata { + mode: 0o644, + mtime_seconds: 7, + mtime_nanoseconds: 3, + }); + let mut inodes = Vec::new(); + for serial in 1..=2 { + inodes.push(InodeUpdate { + serial, + value: InodeValue { + kind: InodeKind::Directory, + content_root: ObjectId::for_bytes(&[serial as u8; 8]), + metadata_root: directory, + namespace_ref_count: 0, + }, + }); + } + let mut changes = Vec::new(); + for n in 0..files { + let root = common::file(&store, format!("file {n} of the window").as_bytes()); + inodes.push(InodeUpdate { + serial: 3 + n, + value: InodeValue { + kind: InodeKind::RegularFile, + content_root: root, + metadata_root: regular, + namespace_ref_count: 0, + }, + }); + changes.push((common::name(&format!("f{n:04}")), Some(3 + n))); + } + // Names bind in byte order: the subdirectory follows the files. + changes.push((common::name("sub"), Some(2))); + let inner = common::file(&store, b"the subdirectory's only name"); + inodes.push(InodeUpdate { + serial: 3 + files, + value: InodeValue { + kind: InodeKind::RegularFile, + content_root: inner, + metadata_root: regular, + namespace_ref_count: 0, + }, + }); + let directories = vec![ + DirectoryUpdate { parent: 1, changes }, + DirectoryUpdate { + parent: 2, + changes: vec![(common::name("only"), Some(3 + files))], + }, + ]; + let new: Vec = (1..=3 + files).collect(); + let mut sink = store.clone(); + let mut objects = FilesystemObjects::new(&store, &mut sink); + let input = FilesystemInput { + base: None, + scope, + root_serial: 1, + directories: &directories, + inodes: &inodes, + new_inodes: &new, + resources: FilesystemResources::default(), + }; + let root = build_filesystem(&mut objects, &input, None).unwrap().root; + common::Fixture { + store, + root, + scope, + bytes: Vec::new(), + } +} +/// One cold window over `files` inherited names, as a reply that shows each +/// entry's facts reads it: (object batches, length batches, single length +/// demands, entries listed). +fn window_reads(files: u64) -> (u64, u64, u64, usize) { + use std::sync::atomic::Ordering; + let b = Bench::over( + &format!("kernel-directory-facts-{files}"), + window_fixture(files), + 4 << 20, + ); + let mount = b.overlay.create_kernel_mount(1).unwrap(); + let directory = open(&b, mount, 1, 1); + // Nothing of the base is resident: the window's names come from the + // Store, and so do the facts this reply shows. + let window = visit_with(&b, directory, 2, None, true).unwrap(); + assert!(window.listing.is_none() && window.needs_base(true)); + let store = &b.fixture.store; + let before = ( + store.batches.load(Ordering::Relaxed), + store.length_batches.load(Ordering::Relaxed), + store.length_demands.load(Ordering::Relaxed), + ); + let base = b.workspace.base().unwrap(); + let listed = window.finish_with(Some(&base), true).unwrap(); + let after = ( + store.batches.load(Ordering::Relaxed), + store.length_batches.load(Ordering::Relaxed), + store.length_demands.load(Ordering::Relaxed), + ); + // Every inherited name, the subdirectory included, carries its facts. + for entry in &listed.entries { + assert!(entry.stat.is_some(), "facts of {:?}", entry.name); + } + let sub = listed + .entries + .iter() + .find(|entry| entry.name == b"sub") + .expect("the subdirectory"); + let sub = sub.stat.as_ref().unwrap(); + assert_eq!((sub.kind, sub.subdirs), (InodeKind::Directory, 0)); + assert_eq!(listed.entries.len() as u64, files + 1); + ( + after.0 - before.0, + after.1 - before.1, + after.2 - before.2, + listed.entries.len(), + ) +} +#[test] +fn a_window_that_shows_facts_reads_it_in_batches() { + let small = window_reads(8); + let large = window_reads(200); + assert_eq!((small.3, large.3), (9, 201), "every inherited name"); + // One length demand for the whole window, and it is a batch: no entry + // asks the provider for its own length. + assert_eq!((small.1, large.1), (1, 1), "one batch length demand"); + assert_eq!((small.2, large.2), (0, 0), "no single length demand"); + // The window's object batches do not grow with the names it lists: the + // inherited serials come from one batch inode demand, not one read per + // name. (Measured: one batch for the window at both sizes.) This fixture + // keeps every metadata root inline and builds its subdirectory's child + // count during construction, so neither costs a demand here; a tree whose + // metadata roots are objects, or a subdirectory counted by a scan, pays + // one read per entry that needs it, as before. + assert_eq!( + small.0, large.0, + "the same object batches for 8 and 200 names" + ); + assert!(large.0 < 3, "{} object batches", large.0); +} +#[test] +fn a_local_window_shows_its_rows_without_a_store_reader() { + use std::sync::atomic::Ordering; + let b = Bench::new("kernel-directory-local-facts"); + let made = b.applied(mkdir(1, "all-local"), T1).unwrap().serial; + let mount = b.overlay.create_kernel_mount(1).unwrap(); + // The kernel's own first LOOKUP of the name records the directory's + // parent, which its OPENDIR reads. + let lookup = b + .workspace + .kernel_read_visit( + empty(), + mount, + 1, + None, + KernelReadOperation::Lookup { + parent: 1, + name: common::name("all-local"), + }, + Arc::new(VisitFacts::default()), + ) + .unwrap(); + assert!(lookup.perform(&b.overlay).result.is_ok()); + let directory = open(&b, mount, 2, made); + b.applied(create(made, "one"), T1); + b.applied(create(made, "two"), T2); + let store = &b.fixture.store; + let before = ( + store.batches.load(Ordering::Relaxed), + store.length_demands.load(Ordering::Relaxed), + ); + // Every name of this window is a local row the visit already read: the + // reply shows all their facts, and the request takes no Store reader. + let window = visit_with(&b, directory, 2, None, true).unwrap(); + assert!(window.listing.is_some()); + assert!(!window.needs_base(true), "memory answered every fact"); + let listed = window.finish_with(None, true).unwrap(); + assert_eq!(listed.entries.len(), 2); + assert!(listed.entries.iter().all(|entry| entry.stat.is_some())); + assert_eq!( + ( + store.batches.load(Ordering::Relaxed), + store.length_demands.load(Ordering::Relaxed) + ), + before, + "a local window reads nothing" + ); + b.overlay + .close_kernel_directory(directory.mount(), directory.serial(), directory.owner_id()) + .unwrap(); + b.overlay.revoke_kernel_mount(mount).unwrap(); +} diff --git a/engine/crates/layerfs-workspace/tests/kernel_visit.rs b/engine/crates/layerfs-workspace/tests/kernel_visit.rs index 6aea36ab7e..0045cfa6a7 100644 --- a/engine/crates/layerfs-workspace/tests/kernel_visit.rs +++ b/engine/crates/layerfs-workspace/tests/kernel_visit.rs @@ -93,7 +93,7 @@ fn observe( assert!(outcome.directory_candidate.is_none()); match outcome.decision { Some(KernelReadDecision::Needs(needs)) => Seen::Needs(needs), - Some(KernelReadDecision::Value(inode)) => Seen::Value(inode), + Some(KernelReadDecision::Value(decided)) => Seen::Value(decided.inode), Some(KernelReadDecision::Refused(refusal)) => Seen::Refused(refusal), other => panic!("undecided read visit: {other:?}"), } @@ -127,7 +127,7 @@ fn open( assert!(outcome.directory_candidate.is_none()); let seen = match outcome.decision { Some(KernelReadDecision::Needs(needs)) => Seen::Needs(needs), - Some(KernelReadDecision::Value(inode)) => Seen::Value(inode), + Some(KernelReadDecision::Value(decided)) => Seen::Value(decided.inode), Some(KernelReadDecision::Refused(refusal)) => Seen::Refused(refusal), other => panic!("undecided open visit: {other:?}"), }; @@ -962,7 +962,7 @@ fn a_visit_through_a_read_only_descriptor_is_refused_and_changes_nothing() { .perform(&b.overlay); assert!(matches!( stat.decision, - Some(KernelReadDecision::Value(ref inode)) if inode.serial == serial + Some(KernelReadDecision::Value(ref decided)) if decided.inode.serial == serial )); b.overlay .kernel_close_file(mount, serial, file.owner_id()) From f2973a6c18903baeb0bcbb706e993208441d3d05 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 03:52:10 +0000 Subject: [PATCH 02/53] test(store): a PostgreSQL Store reads a READDIRPLUS window's facts in batches The batched-window tests read an in-memory fixture store, so they say nothing about the Store a mounted Workspace actually reads. This adds one test-only file: it mounts a Workspace on a real PostgreSQL Store and on a real SQLite Store over the same tree, lists the root over READDIRPLUS through the product's mount path (OPENDIR, the reading visit, the window's facts outside the owner), and counts the port demands the window itself makes. Both Stores spend one batch inode demand and one batch length demand for the whole window, and the number of names does not change either count: `object_batches`/`length_batches` are exactly 1/1 at 8, 40 and 200 inherited names, and the one length demand names each file once (8, 200 and 40 ids). The assertions are equalities, not bounds, and the test says why they hold: this fixture keeps every metadata root inline and builds its subdirectory's child-directory count with the Commit, so no entry here pays a read of its own. An entry whose metadata root is an object, a subdirectory counted by a scan and a symlink's target are still read one at a time. Every entry's facts are compared field by field with a per-name LOOKUP of the same serial and with the bytes the fixture wrote, and the reply's offsets are published, reused unchanged and resumed. Needs LAYERFS_TEST_POSTGRES_URL; without it the two PostgreSQL cases report NOT_RUN and assert nothing, while the SQLite cases still run. The whole file is behind `#![cfg(feature = "postgresql")]`, so a build without that feature runs none of it. Production LOC: 160158 -> 160158 (delta 0) Scope and method: `python3 -B tools/production_loc.py` over first-party product Rust/SQL/JavaScript only, at d0e21d073 and at this tree; this change adds one test file, which is not counted. --- .../tests/postgresql_readdirplus_window.rs | 607 ++++++++++++++++++ 1 file changed, 607 insertions(+) create mode 100644 engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs diff --git a/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs b/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs new file mode 100644 index 0000000000..b01d15f854 --- /dev/null +++ b/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs @@ -0,0 +1,607 @@ +//! LP73 Ask 1-B on a PostgreSQL Store: a cold READDIRPLUS window reads its +//! inherited facts in batches — one batch inode demand and one batch length +//! demand for the whole window, whatever its size — as a SQLite Store does, +//! and answers the facts a per-name LOOKUP answers. +//! +//! The window is driven through the product's mount path, not a fixture store: +//! a Workspace bound on the Store, OPENDIR, the reading visit, and the window's +//! facts read outside the owner over the Workspace's own base. Those are the +//! calls `layerfs-mount-ports`' `DirectoryStream` makes for a READDIRPLUS +//! reply. `Store::work()` counts the port demands themselves, so a PostgreSQL +//! and a SQLite Store are compared on the same counters. +//! +//! Needs a PostgreSQL server: set `LAYERFS_TEST_POSTGRES_URL` (for example +//! `host=127.0.0.1 port=5432 user=layerfs password=… dbname=layerfs_test +//! sslmode=disable`). Without it the two PostgreSQL cases report NOT_RUN and +//! assert nothing, while the SQLite cases still run. The whole file is behind +//! `#![cfg(feature = "postgresql")]`, so a build without that feature runs +//! none of them. +#![cfg(feature = "postgresql")] +#[path = "support/installed_store.rs"] +#[allow(dead_code)] +mod installed; + +use layerfs_content::filesystem::attributes::PortableMetadata; +use layerfs_content::object::inode_leaf::InodeKind; +use layerfs_history::{ + BranchId, ForkRequest, ForkSource, HistoryCatalog, HistoryCatalogConfig, HistoryName, + LayerStackId, WorkspaceId, +}; +use layerfs_persistence::{PostgresHandles, PostgresSelection, StoreSelection}; +use layerfs_project::{init, InitRequest}; +use layerfs_storage::{ReservationBlocks, Storage, StoragePolicy}; +use layerfs_store_service::bootstrap::open_store_observed; +use layerfs_store_service::store::{BindRequest, StoreWork}; +use layerfs_store_service::{Owner, OwnerConfig, StoreService}; +use layerfs_telemetry::timer::Timing; +use layerfs_workspace::{ + CanonicalCache, CanonicalClient, KernelDirectoryRead, KernelDirectoryWindow, + KernelReadDecision, VisitFacts, +}; +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; +use std::sync::Arc; +use std::time::{Duration, Instant}; + +const BINDING: &[u8] = b"readdirplus-window-batches"; +const CURSOR: [u8; 32] = [73; 32]; +const PROJECT: &str = "window"; +const BRANCH_NAME: &str = "work"; +/// The daemon's Store object cache. +const CACHE_BYTES: usize = 64 * 1024 * 1024; +/// Most OPENDIR rounds one undecided visit gets before the test fails. +const ROUNDS: usize = 4; +/// The branch the SQLite fixture's installed Store already holds: stack +/// `[23; 16]`, branch `[24; 16]`, named `main` under the project `installed`. +const INSTALLED_BRANCH: [u8; 16] = [24; 16]; + +/// The names below the root: `files` regular files of known bytes, and one +/// subdirectory holding one file of its own. +fn tree(files: usize) -> Vec<(String, Vec)> { + (0..files) + .map(|n| { + let name = format!("f{n:04}"); + let bytes = vec![(n % 251) as u8; 16 + n % 97]; + (name, bytes) + }) + .collect() +} + +fn build(source: &Path, files: usize) { + for (name, bytes) in tree(files) { + std::fs::write(source.join(name), bytes).unwrap(); + } + let sub = source.join("sub"); + std::fs::create_dir(&sub).unwrap(); + std::fs::write(sub.join("inner"), b"the subdirectory's only file\n").unwrap(); +} + +/// The port demands one window's facts made. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +struct Counts { + object_batches: u64, + object_ids: u64, + length_batches: u64, + length_ids: u64, +} +impl Counts { + fn between(before: StoreWork, after: StoreWork) -> Self { + Self { + object_batches: after.object_batches - before.object_batches, + object_ids: after.object_ids - before.object_ids, + length_batches: after.length_batches - before.length_batches, + length_ids: after.length_ids - before.length_ids, + } + } +} +/// One entry's facts as the reply showed them. +#[derive(Clone, Debug, Eq, PartialEq)] +struct Fact { + name: String, + kind: InodeKind, + metadata: PortableMetadata, + logical_len: u64, + subdirs: u64, +} +impl Fact { + /// What two Stores must answer identically: name, kind, permission bits, + /// length and child-directory count. The mtime is the source tree's, and + /// each test builds its own. + fn shape(&self) -> (&str, InodeKind, u32, u64, u64) { + ( + &self.name, + self.kind, + self.metadata.mode, + self.logical_len, + self.subdirs, + ) + } +} + +/// What one cold READDIRPLUS window answered and what it cost. +struct Measured { + counts: Counts, + facts: Vec, + exhausted: bool, +} + +/// One cold READDIRPLUS window of `branch`'s root, driven as a mount drives +/// it: OPENDIR, the reading visit, one Store reader for the window's facts, +/// and the reply's offsets published and then reused. +fn measure( + service: &StoreService, + owner: &Owner, + files: usize, + tag: &str, + branch: BranchId, +) -> Measured { + let bound = service + .store + .bind( + owner.client(), + BindRequest { + workspace: WorkspaceId::from_authority([91; 32]).unwrap(), + branch, + }, + ) + .unwrap_or_else(|refusal| panic!("{tag}: bind refused: {refusal:?}")) + .workspace; + let operation = bound.operation().unwrap(); + let route = bound.route(); + let jobs = operation.overlay(); + let workspace = operation.workspace(); + let base = workspace.base().unwrap(); + let root = base.root().root_inode().serial(); + let mount = jobs.kernel_mount(route, root).unwrap(); + // Nothing of the base is resident: this is the cold window a fresh mount + // serves, the arm whose facts the request must read from the Store. + let resident = Arc::new(CanonicalClient::resident(Arc::new(CanonicalCache::new( + 1 << 20, + )))); + + // OPENDIR: owner jobs that ask the Store nothing, and the facts they name + // read outside them. + let mut facts = VisitFacts::default(); + let mut directory = None; + for _ in 0..ROUNDS { + let visit = workspace + .kernel_opendir_visit(resident.clone(), mount, 1, root, Arc::new(facts.clone())) + .unwrap(); + let before = service.store.work(); + let outcome = jobs.kernel_observe_visit(route, Box::new(visit)).unwrap(); + assert_eq!( + service.store.work(), + before, + "{tag}: an owner job made a Store demand" + ); + match &outcome.decision { + Some(KernelReadDecision::Needs(needs)) => facts + .supply(&workspace.base().unwrap(), needs, None) + .unwrap(), + Some(KernelReadDecision::Value(_)) => { + directory = outcome.directory_candidate; + break; + } + other => panic!("{tag}: undecided OPENDIR: {other:?}"), + } + } + let directory = directory.unwrap_or_else(|| panic!("{tag}: an open directory")); + + // The reading visit: one read-only owner job that makes no Store demand. + let visit = workspace + .kernel_directory_visit( + resident.clone(), + mount, + root, + directory.owner_id(), + KernelDirectoryRead { + offset: 2, + after: None, + attributes: true, + }, + ) + .unwrap(); + let before_visit = service.store.work(); + let reply = jobs.kernel_directory_visit(route, visit).unwrap(); + assert_eq!( + service.store.work(), + before_visit, + "{tag}: the reading visit made a Store demand" + ); + let window = KernelDirectoryWindow::clone(&reply); + drop(reply); + assert!( + window.needs_base(true), + "{tag}: a cold window leaves its facts to the Store" + ); + + // The window's facts, outside the owner, over the Workspace's reader: one + // batch inode demand and one batch length demand for the whole window. + let before = service.store.work(); + let batch = window.finish_with(Some(&base), true).unwrap(); + let after = service.store.work(); + let counts = Counts::between(before, after); + eprintln!("{tag}: port demands of one window: {counts:?}"); + + let names: Vec> = batch + .entries + .iter() + .map(|entry| entry.name.clone()) + .collect(); + let mut shown = Vec::with_capacity(batch.entries.len()); + for entry in &batch.entries { + let name = String::from_utf8(entry.name.clone()).unwrap(); + let stat = entry + .stat + .as_ref() + .unwrap_or_else(|| panic!("{tag}: no facts for {name}")); + assert_eq!(stat.kind, entry.kind, "{tag}: kind of {name}"); + // A per-name LOOKUP answers the same facts, field for field: the + // window's batch read and the single demand agree. + let lookup = base.stat(entry.serial).unwrap(); + assert_eq!(stat.kind, lookup.value.kind, "{tag}: LOOKUP kind of {name}"); + assert_eq!( + stat.metadata, lookup.metadata, + "{tag}: LOOKUP metadata of {name}" + ); + assert_eq!( + stat.logical_len, lookup.logical_len, + "{tag}: LOOKUP length of {name}" + ); + shown.push(Fact { + name, + kind: stat.kind, + metadata: stat.metadata, + logical_len: stat.logical_len, + subdirs: stat.subdirs, + }); + } + // Every inherited name and the subdirectory, exactly once, with the bytes + // the fixture wrote. + let expected: BTreeMap = tree(files) + .into_iter() + .map(|(name, bytes)| (name, bytes.len())) + .collect(); + assert_eq!(shown.len(), files + 1, "{tag}: every name of the window"); + for fact in &shown { + if let Some(len) = expected.get(&fact.name) { + assert_eq!( + fact.kind, + InodeKind::RegularFile, + "{tag}: kind {}", + fact.name + ); + assert_eq!(fact.logical_len, *len as u64, "{tag}: length {}", fact.name); + } else { + assert_eq!(fact.name, "sub", "{tag}: the subdirectory"); + assert_eq!(fact.kind, InodeKind::Directory, "{tag}: kind sub"); + assert_eq!(fact.subdirs, 0, "{tag}: sub holds no directory"); + assert_eq!(fact.logical_len, 0, "{tag}: a directory has no length"); + } + } + + // The reply's offsets are published once, and a request inside that reply + // is answered at them instead of recording them again: the handles a + // READDIRPLUS reply hands out follow these offsets. + let first = batch.first; + let exhausted = batch.exhausted; + assert!(exhausted, "{tag}: one window lists the root"); + let offer = batch + .publish + .clone() + .unwrap_or_else(|| panic!("{tag}: a fresh reply publishes its names")); + jobs.kernel_directory_publish(route, offer, names.clone()) + .unwrap(); + let reuse = workspace + .kernel_directory_visit( + resident.clone(), + mount, + root, + directory.owner_id(), + KernelDirectoryRead { + offset: 2, + after: None, + attributes: true, + }, + ) + .unwrap(); + let reply = jobs.kernel_directory_visit(route, reuse).unwrap(); + let window = KernelDirectoryWindow::clone(&reply); + drop(reply); + let reused = window.finish_with(Some(&base), true).unwrap(); + assert_eq!( + reused + .entries + .iter() + .map(|entry| entry.name.clone()) + .collect::>(), + names, + "{tag}: the published reply is answered at its offsets" + ); + assert_eq!(reused.first, first, "{tag}: at the published offsets"); + assert!( + reused.publish.is_none(), + "{tag}: a reused reply records nothing again" + ); + // A seek inside the published reply resumes strictly after its name, and + // hands out a fresh range for what follows it. + let seek = workspace + .kernel_directory_visit( + resident, + mount, + root, + directory.owner_id(), + KernelDirectoryRead { + offset: first + names.len() as u64 - 2, + after: None, + attributes: true, + }, + ) + .unwrap(); + let reply = jobs.kernel_directory_visit(route, seek).unwrap(); + let window = KernelDirectoryWindow::clone(&reply); + drop(reply); + let next = window.finish_with(Some(&base), true).unwrap(); + assert_eq!( + next.entries + .iter() + .map(|entry| entry.name.clone()) + .collect::>(), + names[names.len() - 1..], + "{tag}: the offset resumes strictly after its name" + ); + assert!( + next.entries.iter().all(|entry| entry.stat.is_some()), + "{tag}: the resumed window's facts too" + ); + + jobs.kernel_directory_close(route, mount, root, directory.owner_id()) + .unwrap(); + jobs.kernel_revoke(route, mount).unwrap(); + bound.close().unwrap(); + owner.client().retire_namespace(route.namespace()).unwrap(); + Measured { + counts, + facts: shown, + exhausted, + } +} + +fn catalog() -> HistoryCatalogConfig { + HistoryCatalogConfig { + binding_key: BINDING.to_vec(), + cursor_key: CURSOR, + incarnation: 1, + } +} + +fn url() -> Option { + let url = std::env::var("LAYERFS_TEST_POSTGRES_URL").ok(); + if url.is_none() { + eprintln!("NOT_RUN: LAYERFS_TEST_POSTGRES_URL is unset"); + } + url +} + +/// The test's own PostgreSQL schema and source tree, dropped when it ends, +/// pass or fail. +struct Postgres { + url: String, + schema: String, + directory: PathBuf, + stack: LayerStackId, +} +impl Postgres { + fn new(tag: &str, url: &str, files: usize, stack: [u8; 16]) -> Self { + let directory = + std::env::temp_dir().join(format!("lfs73-window-{tag}-{}", std::process::id())); + std::fs::create_dir_all(&directory).unwrap(); + let schema = format!("lfs73_window_{tag}_{}", std::process::id()); + let source = directory.join("source"); + std::fs::create_dir(&source).unwrap(); + build(&source, files); + Self { + url: url.to_owned(), + schema, + directory, + stack: LayerStackId::from_authority(stack), + } + } + /// One PostgreSQL Store holding the fixture's tree on one Branch. + fn open(&self) -> (Owner, StoreService) { + let selection = PostgresSelection::new(&self.url, &self.schema); + let created = + PostgresHandles::create(&selection, StoragePolicy::frozen_default(), &catalog()) + .unwrap(); + let storage = Storage::new(created.storage.clone()).unwrap(); + let initialized = Timing::disabled("init", |timing| { + init( + &storage, + &created.history, + InitRequest { + source: &self.directory.join("source"), + acquisition: &created.acquisition, + stack: self.stack, + name: HistoryName::new(PROJECT).unwrap(), + scope_seed: [75; 32], + deadline: Instant::now() + Duration::from_secs(120), + }, + timing, + ) + }) + .0 + .unwrap(); + created + .history + .fork(&ForkRequest { + stack: initialized.stack.id, + branch: pg_branch(self.stack), + name: HistoryName::new(BRANCH_NAME).unwrap(), + source: ForkSource::Layer(initialized.stack.head_layer), + }) + .unwrap(); + drop(storage); + drop(created); + let config = OwnerConfig::default(); + let opened = open_store_observed( + StoreSelection::Postgres(selection), + BINDING, + CURSOR, + config.namespaces, + CACHE_BYTES, + ReservationBlocks::default(), + ) + .unwrap(); + let owner = Owner::start( + &self.directory.join("overlay.sqlite"), + layerfs_overlay::ProfileConfig::default(), + config, + ) + .unwrap(); + let service = StoreService::new(opened, &owner); + (owner, service) + } +} +impl Drop for Postgres { + fn drop(&mut self) { + if let Ok(mut client) = postgres::Client::connect(&self.url, postgres::NoTls) { + let _ = client.batch_execute(&format!("DROP SCHEMA IF EXISTS {} CASCADE", self.schema)); + } + let _ = std::fs::remove_dir_all(&self.directory); + } +} + +/// The Branch this test's PostgreSQL fixtures fork. +fn pg_branch(stack: LayerStackId) -> BranchId { + BranchId::named(stack, &HistoryName::new(BRANCH_NAME).unwrap()) +} + +/// One cold READDIRPLUS window over an Init'd PostgreSQL Store's root. +fn postgres_window(url: &str, files: usize, tag: &str, stack: [u8; 16]) -> Measured { + let fixture = Postgres::new(tag, url, files, stack); + let (owner, service) = fixture.open(); + let measured = measure(&service, &owner, files, tag, pg_branch(fixture.stack)); + drop(service); + owner.stop().unwrap(); + measured +} + +/// The same window over a SQLite Store built from the same tree, through the +/// installed-Store fixture the Store's own tests use. +fn sqlite_window(files: usize, tag: &str) -> Measured { + let host = installed::Fixture::built(tag, |source| { + build(source, files); + files + 2 + }); + let config = OwnerConfig::default(); + let opened = open_store_observed( + host.config.clone(), + installed::BINDING, + installed::CURSOR, + config.namespaces, + CACHE_BYTES, + ReservationBlocks::default(), + ) + .unwrap(); + let owner = Owner::start( + &host.directory.join("overlay.sqlite"), + layerfs_overlay::ProfileConfig::default(), + config, + ) + .unwrap(); + let service = StoreService::new(opened, &owner); + let measured = measure( + &service, + &owner, + files, + tag, + BranchId::from_authority(INSTALLED_BRANCH), + ); + drop(service); + owner.stop().unwrap(); + host.cleanup(); + measured +} + +#[test] +fn a_postgresql_window_reads_its_facts_in_batches() { + let Some(url) = url() else { + return; + }; + let small = postgres_window(&url, 8, "small", [81; 16]); + let large = postgres_window(&url, 200, "large", [82; 16]); + // One length demand carries the whole window, and it names each ordinary + // file once: no entry asks the provider for its own length. + for (measured, files) in [(&small, 8u64), (&large, 200)] { + assert_eq!(measured.counts.length_batches, 1, "one length demand"); + assert_eq!( + measured.counts.length_ids, files, + "the one length demand names each file once" + ); + } + // The window's object demands and length demands do not grow with the + // names it lists: one batch inode demand carries the whole window's + // inherited serials and one batch length demand its ordinary files. This + // tree's metadata roots are inline and its subdirectory's child count was + // built with the Commit, so no entry here costs a read of its own; an + // entry whose metadata root is an object, a subdirectory counted by a scan + // and a symlink's target are still read one at a time. + assert_eq!( + large.counts.object_batches, small.counts.object_batches, + "8 names: {:?}, 200 names: {:?}", + small.counts, large.counts + ); + for (measured, files) in [(&small, 8u64), (&large, 200)] { + assert_eq!( + measured.counts.object_batches, 1, + "{files} names: one batch inode demand" + ); + } + assert_eq!(small.facts.len(), 9); + assert_eq!(large.facts.len(), 201); + assert!(small.exhausted && large.exhausted); +} + +#[test] +fn a_sqlite_window_makes_the_same_batches_and_answers_the_same_facts() { + let sqlite = sqlite_window(40, "sqlite"); + assert_eq!( + (sqlite.counts.object_batches, sqlite.counts.length_batches), + (1, 1), + "one batch inode demand and one length demand: {:?}", + sqlite.counts + ); + assert_eq!(sqlite.counts.length_ids, 40); + assert_eq!(sqlite.facts.len(), 41); + let Some(url) = url() else { + return; + }; + // The same tree on a PostgreSQL Store, mounted and listed the same way. + let postgres = postgres_window(&url, 40, "compare", [83; 16]); + assert_eq!( + ( + postgres.counts.object_batches, + postgres.counts.length_batches, + postgres.counts.length_ids + ), + ( + sqlite.counts.object_batches, + sqlite.counts.length_batches, + sqlite.counts.length_ids + ), + "the same demands on both Stores: PostgreSQL {:?}, SQLite {:?}", + postgres.counts, + sqlite.counts + ); + // What both Stores must answer identically. The mtime of each fixture's + // own source tree differs between the two runs; it is compared there with + // that tree's own LOOKUP, not across Stores. + assert_eq!( + postgres.facts.iter().map(Fact::shape).collect::>(), + sqlite.facts.iter().map(Fact::shape).collect::>(), + "the same facts on both Stores" + ); + // The offset a reply starts at is the handle's own counter, not a cross + // Store contract; that it lists the whole directory in one window is. + assert!(postgres.exhausted && sqlite.exhausted); +} From 64ad98b5ef6ee65f234207b7060af2e691d68d87 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:09:14 +0000 Subject: [PATCH 03/53] docs(nfs): count a READDIRPLUS window's inode demand per tree level The batching this route adds is real but the count was still overstated: `lookup_many` walks the inode table level by level and reads each level's pages in one batch demand, so a window pays one batch inode demand for each level the cache does not already answer, not one for the window. The number of names adds no demand and a deeper tree adds one. The windows the tests count are also not a fresh mount's first window: the visits before them read the inode table's upper level into the same cache, so only the levels they left cost a demand. Both places now say so, and `nfs.md` no longer calls the cost "two demands whatever its size"; it states the per-level rule and what the earlier visits make resident. No behaviour changes: comments and documentation only, and the two PostgreSQL assertions and the workspace assertions are untouched. Production LOC: 160158 -> 160158 (delta 0) Scope and method: `python3 -B tools/production_loc.py` over first-party product Rust/SQL/JavaScript only, at f2973a6c1 and at this tree; this change touches comments and documentation only. --- docs/architecture/engine/kernel-routes/nfs.md | 2 +- engine/crates/layerfs-nfs/src/directory.rs | 3 +- .../tests/postgresql_readdirplus_window.rs | 36 ++++++++++++------- .../src/operations/kernel_directory.rs | 27 ++++++++------ .../tests/kernel_directory.rs | 9 +++-- 5 files changed, 49 insertions(+), 28 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 83d521f80b..e91559a20b 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -138,7 +138,7 @@ itself ([`attributes.rs`](../../../../engine/crates/layerfs-nfs/src/attributes.r | The NFS cookie is the engine's kernel offset on one implicit directory descriptor named by `cookieverf`. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | An offset a rewind retired is `NFS3ERR_BAD_COOKIE`. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | A READDIRPLUS entry carries the facts its window read — a local inode's current row, or an inherited inode's immutable base stat — and the handle of its serial, so the client needs no LOOKUP per name. Both are optional in RFC 1813 and this export sends both for every named entry whose offsets the reply publishes. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | -| A cold window's facts cost two demands whatever its size: its inherited serials in one batch inode demand (`lookup_many`) and its ordinary file lengths in one batch length demand (`provide_lengths`). The entries memory already answers — a local row, or an inherited inode whose value, metadata, length and child-directory count are resident — cost the request no Store reader at all. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | +| A window's inherited inode values cost one batch inode demand for each level of the inode tree the cache does not already answer — `lookup_many` reads a level's pages in one `read_canonical_batch`, and a level whose every page is resident costs none — and its ordinary file lengths one batch length demand (`provide_lengths`). Those counts follow the tree's depth, not the number of names. The counts the tests below report are not a fresh mount's first window: the visits that precede the window read the pages it names into the same cache, so only the levels they left unread cost a demand. The entries memory already answers — a local row, or an inherited inode whose value, metadata, length and child-directory count are resident — cost the request no Store reader at all. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | | Those two batches are not everything an entry costs, and this route changes none of the rest: an inherited inode whose metadata is not inline reports one portable-metadata demand per distinct metadata root, a listed subdirectory one listing of that subdirectory for its child-directory count, and a symlink entry one read of its target. A window of only ordinary files with inline metadata therefore costs exactly the two batches; a window naming those entries costs more, growing with them and not with the names. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`view.rs`](../../../../engine/crates/layerfs-workspace/src/base/view.rs), [`links.rs`](../../../../engine/crates/layerfs-workspace/src/base/links.rs) | | Every handle a READDIRPLUS reply hands out takes its one kernel lookup reference in the publishing visit that makes its offset valid; a reply reusing an already published offset range hands out none. | [`kernel_cookie.rs`](../../../../engine/crates/layerfs-overlay/src/lifetime/kernel_cookie.rs) | | READDIR has one count, which bounds the whole reply. READDIRPLUS sends the entries' own count (`dircount`) before it; only `maxcount` bounds this reply, the count the client sized its buffer by. | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | diff --git a/engine/crates/layerfs-nfs/src/directory.rs b/engine/crates/layerfs-nfs/src/directory.rs index f5f5d2b204..56cd620e07 100644 --- a/engine/crates/layerfs-nfs/src/directory.rs +++ b/engine/crates/layerfs-nfs/src/directory.rs @@ -14,7 +14,8 @@ //! //! A READDIRPLUS entry carries the attributes the listing read — the local //! inode row of the name, or the inherited inode's immutable facts, read for -//! the whole window in one batch demand each for inodes and file lengths — +//! the window in one batch demand for file lengths and one inode batch per +//! level of the inode tree the cache does not already answer — //! and the handle of the entry's serial. Both are optional in RFC 1813; here //! they are present for every named entry whose offsets this request //! publishes, and the publishing visit takes one kernel lookup reference per diff --git a/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs b/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs index b01d15f854..1fdd58a3eb 100644 --- a/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs +++ b/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs @@ -1,7 +1,10 @@ -//! LP73 Ask 1-B on a PostgreSQL Store: a cold READDIRPLUS window reads its -//! inherited facts in batches — one batch inode demand and one batch length -//! demand for the whole window, whatever its size — as a SQLite Store does, -//! and answers the facts a per-name LOOKUP answers. +//! LP73 Ask 1-B on a PostgreSQL Store: a READDIRPLUS window reads its +//! inherited facts in batches — one batch length demand for the window and +//! one batch inode demand for each level of the inode tree the cache does not +//! already answer — as a SQLite Store does, and answers the facts a per-name +//! LOOKUP answers. What it counts is a partly warm window: the visits before +//! it read the inode table's upper level into the same cache, so its batches +//! are not a fresh mount's first window's. //! //! The window is driven through the product's mount path, not a fixture store: //! a Workspace bound on the Store, OPENDIR, the reading visit, and the window's @@ -118,14 +121,14 @@ impl Fact { } } -/// What one cold READDIRPLUS window answered and what it cost. +/// What one READDIRPLUS window answered and what it cost. struct Measured { counts: Counts, facts: Vec, exhausted: bool, } -/// One cold READDIRPLUS window of `branch`'s root, driven as a mount drives +/// One READDIRPLUS window of `branch`'s root, driven as a mount drives /// it: OPENDIR, the reading visit, one Store reader for the window's facts, /// and the reply's offsets published and then reused. fn measure( @@ -153,8 +156,10 @@ fn measure( let base = workspace.base().unwrap(); let root = base.root().root_inode().serial(); let mount = jobs.kernel_mount(route, root).unwrap(); - // Nothing of the base is resident: this is the cold window a fresh mount - // serves, the arm whose facts the request must read from the Store. + // The cache starts empty, so every fact this window shows is the Store's + // to read. The OPENDIR below and the facts it supplies fill it with the + // inode table's upper level, so the window that follows is not a fresh + // mount's first one. let resident = Arc::new(CanonicalClient::resident(Arc::new(CanonicalCache::new( 1 << 20, )))); @@ -212,11 +217,12 @@ fn measure( drop(reply); assert!( window.needs_base(true), - "{tag}: a cold window leaves its facts to the Store" + "{tag}: the window leaves its facts to the Store" ); // The window's facts, outside the owner, over the Workspace's reader: one - // batch inode demand and one batch length demand for the whole window. + // batch length demand for the window and one batch inode demand per tree + // level the OPENDIR left unread. let before = service.store.work(); let batch = window.finish_with(Some(&base), true).unwrap(); let after = service.store.work(); @@ -476,7 +482,7 @@ fn pg_branch(stack: LayerStackId) -> BranchId { BranchId::named(stack, &HistoryName::new(BRANCH_NAME).unwrap()) } -/// One cold READDIRPLUS window over an Init'd PostgreSQL Store's root. +/// One READDIRPLUS window over an Init'd PostgreSQL Store's root. fn postgres_window(url: &str, files: usize, tag: &str, stack: [u8; 16]) -> Measured { let fixture = Postgres::new(tag, url, files, stack); let (owner, service) = fixture.open(); @@ -540,8 +546,12 @@ fn a_postgresql_window_reads_its_facts_in_batches() { ); } // The window's object demands and length demands do not grow with the - // names it lists: one batch inode demand carries the whole window's - // inherited serials and one batch length demand its ordinary files. This + // names it lists: one batch length demand carries the window's ordinary + // files, and one batch inode demand carries its inherited serials for each + // tree level the cache does not already hold, so the names add no batch + // while a deeper tree adds one. Here the visits before the window read the + // tree's upper level into the same cache, leaving one level: these are not + // a fully cold window's counts. This // tree's metadata roots are inline and its subdirectory's child count was // built with the Commit, so no entry here costs a read of its own; an // entry whose metadata root is an object, a subdirectory counted by a scan diff --git a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs index faf107337f..b9b3fe5d30 100644 --- a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs @@ -5,8 +5,10 @@ //! cache holds them; otherwise the request merges them outside the owner //! over one Store reader, at the base root the visit named. A reply that //! shows each entry's facts (READDIRPLUS) takes them from the same memory -//! first, and reads what is left in one batch inode demand and one batch -//! length demand for the whole window, whatever its size. What those batches +//! first, and reads what is left in one batch length demand for the window +//! and one batch inode demand for each level of the inode tree the cache does +//! not already answer, so those counts follow the tree's depth and not the +//! number of names. What those batches //! do not cover is per entry and unchanged here: a non-inline metadata root, //! a listed subdirectory's child-directory count, and a symlink's target are //! still read once for each entry that needs them. The request then fills its @@ -236,9 +238,11 @@ impl KernelDirectoryWindow { } /// The same for a reply that also shows what each accepted entry is, as /// READDIRPLUS does. The reading visit already said what memory held; the - /// names it left undecided are read here in one batch inode demand and - /// one batch length demand for the whole window, so the number of names - /// adds no demand. Those two batches are not the whole cost of an entry: + /// names it left undecided are read here in one batch length demand for + /// the window and one batch inode demand for each level of the inode tree + /// the cache does not already answer, so the number of names adds no + /// demand while a deeper tree adds one. Those batches are not the whole + /// cost of an entry: /// [`base_facts`] still reads an inherited inode's non-inline metadata /// root, a listed subdirectory's child-directory count and a symlink's /// target once per entry that needs them, as the base route always did. @@ -314,9 +318,11 @@ impl KernelDirectoryWindow { } } /// Fills the facts a reply shows for the entries that still lack them: the -/// window's inherited serials in one batch inode demand, and the lengths of -/// its regular files in one batch length demand, so listing more names costs -/// no more of either. A local serial's facts are its current row. What +/// window's inherited serials in one batch inode demand for each level of the +/// inode tree the cache does not already answer, and the lengths of its +/// regular files in one batch length demand, so listing more names costs no +/// more of either while a deeper tree costs one more inode batch per level. A +/// local serial's facts are its current row. What /// [`base_facts`] still reads once per entry is not batched here. fn facts( base: &BaseView, @@ -342,8 +348,9 @@ fn facts( } Ok(()) } -/// The base value of every inherited serial in one batch inode demand, after -/// one length demand has remembered the window's ordinary file lengths. +/// The base values of the window's inherited serials, in one batch inode +/// demand for each level of the inode tree the cache does not already answer, +/// after one length demand remembered the window's ordinary file lengths. fn inherited_values( base: &BaseView, serials: &[u64], diff --git a/engine/crates/layerfs-workspace/tests/kernel_directory.rs b/engine/crates/layerfs-workspace/tests/kernel_directory.rs index ddc577f1ce..f77b00f805 100644 --- a/engine/crates/layerfs-workspace/tests/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/tests/kernel_directory.rs @@ -469,9 +469,12 @@ fn a_window_that_shows_facts_reads_it_in_batches() { // asks the provider for its own length. assert_eq!((small.1, large.1), (1, 1), "one batch length demand"); assert_eq!((small.2, large.2), (0, 0), "no single length demand"); - // The window's object batches do not grow with the names it lists: the - // inherited serials come from one batch inode demand, not one read per - // name. (Measured: one batch for the window at both sizes.) This fixture + // The window's object batches do not grow with the names it lists: an + // inode tree level whose pages are resident costs no demand, and the rest + // come one batch per level, not one read per name. (Measured: one batch at + // both sizes, because the visits before the window read the tree's upper + // level into the same cache and only its leaf level was left — this is not + // a fully cold window's count.) This fixture // keeps every metadata root inline and builds its subdirectory's child // count during construction, so neither costs a demand here; a tree whose // metadata roots are objects, or a subdirectory counted by a scan, pays From 71606c185116bcf0d83c36ec47b9869e7e90f294 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:11:53 +0000 Subject: [PATCH 04/53] docs(nfs): say when the window's one length demand still holds The length batch pays only while the cache can remember what it answers: `remember_length` stores nothing when the allowance is smaller than one entry, and `file_length` then asks the provider for each file in turn. The row that promises one length demand now says so. Documentation only. Production LOC: 160158 -> 160158 (delta 0) Scope and method: `python3 -B tools/production_loc.py` over first-party product Rust/SQL/JavaScript only, at 64ad98b5e and at this tree; this change touches one documentation row only. --- docs/architecture/engine/kernel-routes/nfs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index e91559a20b..612365accd 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -138,7 +138,7 @@ itself ([`attributes.rs`](../../../../engine/crates/layerfs-nfs/src/attributes.r | The NFS cookie is the engine's kernel offset on one implicit directory descriptor named by `cookieverf`. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | An offset a rewind retired is `NFS3ERR_BAD_COOKIE`. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | A READDIRPLUS entry carries the facts its window read — a local inode's current row, or an inherited inode's immutable base stat — and the handle of its serial, so the client needs no LOOKUP per name. Both are optional in RFC 1813 and this export sends both for every named entry whose offsets the reply publishes. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | -| A window's inherited inode values cost one batch inode demand for each level of the inode tree the cache does not already answer — `lookup_many` reads a level's pages in one `read_canonical_batch`, and a level whose every page is resident costs none — and its ordinary file lengths one batch length demand (`provide_lengths`). Those counts follow the tree's depth, not the number of names. The counts the tests below report are not a fresh mount's first window: the visits that precede the window read the pages it names into the same cache, so only the levels they left unread cost a demand. The entries memory already answers — a local row, or an inherited inode whose value, metadata, length and child-directory count are resident — cost the request no Store reader at all. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | +| A window's inherited inode values cost one batch inode demand for each level of the inode tree the cache does not already answer — `lookup_many` reads a level's pages in one `read_canonical_batch`, and a level whose every page is resident costs none — and its ordinary file lengths one batch length demand (`provide_lengths`). Those counts follow the tree's depth, not the number of names, and the one length demand pays only while the cache can remember the lengths it answers: one too small for a single entry remembers nothing, and each file then asks for its own length. The counts the tests below report are not a fresh mount's first window: the visits that precede the window read the pages it names into the same cache, so only the levels they left unread cost a demand. The entries memory already answers — a local row, or an inherited inode whose value, metadata, length and child-directory count are resident — cost the request no Store reader at all. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | | Those two batches are not everything an entry costs, and this route changes none of the rest: an inherited inode whose metadata is not inline reports one portable-metadata demand per distinct metadata root, a listed subdirectory one listing of that subdirectory for its child-directory count, and a symlink entry one read of its target. A window of only ordinary files with inline metadata therefore costs exactly the two batches; a window naming those entries costs more, growing with them and not with the names. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`view.rs`](../../../../engine/crates/layerfs-workspace/src/base/view.rs), [`links.rs`](../../../../engine/crates/layerfs-workspace/src/base/links.rs) | | Every handle a READDIRPLUS reply hands out takes its one kernel lookup reference in the publishing visit that makes its offset valid; a reply reusing an already published offset range hands out none. | [`kernel_cookie.rs`](../../../../engine/crates/layerfs-overlay/src/lifetime/kernel_cookie.rs) | | READDIR has one count, which bounds the whole reply. READDIRPLUS sends the entries' own count (`dircount`) before it; only `maxcount` bounds this reply, the count the client sized its buffer by. | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | From f87d032b292200c0729e05eac7bd3e164cc16a9d Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:34:00 +0000 Subject: [PATCH 05/53] test(workspace): state what the window's batch count depends on The comment above the batch assertion named a measured count. The test asserts the two sizes agree and stay below three, and what a run sees depends on the inode tree levels the visits before the window left unread, so the comment now says that instead of fixing a number. Comments only; assertions unchanged. Production LOC: 160158 -> 160158 (delta 0) Scope and method: `python3 -B tools/production_loc.py` over first-party product Rust/SQL/JavaScript only, at 71606c185 and at this tree; test comments are outside that scope. --- engine/crates/layerfs-workspace/tests/kernel_directory.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/engine/crates/layerfs-workspace/tests/kernel_directory.rs b/engine/crates/layerfs-workspace/tests/kernel_directory.rs index f77b00f805..d6b8d622d4 100644 --- a/engine/crates/layerfs-workspace/tests/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/tests/kernel_directory.rs @@ -471,10 +471,10 @@ fn a_window_that_shows_facts_reads_it_in_batches() { assert_eq!((small.2, large.2), (0, 0), "no single length demand"); // The window's object batches do not grow with the names it lists: an // inode tree level whose pages are resident costs no demand, and the rest - // come one batch per level, not one read per name. (Measured: one batch at - // both sizes, because the visits before the window read the tree's upper - // level into the same cache and only its leaf level was left — this is not - // a fully cold window's count.) This fixture + // come one batch per level, not one read per name. (What the count is + // here depends on the levels the visits before the window left unread: in + // this fixture they read the tree's upper level into the same cache, so + // this is not a fully cold window's count.) This fixture // keeps every metadata root inline and builds its subdirectory's child // count during construction, so neither costs a demand here; a tree whose // metadata roots are objects, or a subdirectory counted by a scan, pays From 871fb04ed7e995362dd4dbef04acd0ea96f2cd03 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 10:03:18 +0000 Subject: [PATCH 06/53] docs(nfs): align remaining two-batch and cold-window wording Update the follow-on row in nfs.md so it no longer says a window of ordinary files with inline metadata costs "exactly the two batches" (inode demands scale per unread tree level, and length batching requires cache capacity), and clarify in kernel_directory::window_reads that OPENDIR and the reading visit fill the upper inode tree level before the window's reads are counted. Production LOC: 160158 -> 160158 (delta 0) Scope and method: python3 -B tools/production_loc.py over first-party product Rust/SQL/JavaScript only (reference absent, retired R9c), at f87d032b2 and at this tree; this change touches docs and test comments only. --- docs/architecture/engine/kernel-routes/nfs.md | 2 +- engine/crates/layerfs-workspace/tests/kernel_directory.rs | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 612365accd..648e75d332 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -139,7 +139,7 @@ itself ([`attributes.rs`](../../../../engine/crates/layerfs-nfs/src/attributes.r | An offset a rewind retired is `NFS3ERR_BAD_COOKIE`. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | A READDIRPLUS entry carries the facts its window read — a local inode's current row, or an inherited inode's immutable base stat — and the handle of its serial, so the client needs no LOOKUP per name. Both are optional in RFC 1813 and this export sends both for every named entry whose offsets the reply publishes. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | | A window's inherited inode values cost one batch inode demand for each level of the inode tree the cache does not already answer — `lookup_many` reads a level's pages in one `read_canonical_batch`, and a level whose every page is resident costs none — and its ordinary file lengths one batch length demand (`provide_lengths`). Those counts follow the tree's depth, not the number of names, and the one length demand pays only while the cache can remember the lengths it answers: one too small for a single entry remembers nothing, and each file then asks for its own length. The counts the tests below report are not a fresh mount's first window: the visits that precede the window read the pages it names into the same cache, so only the levels they left unread cost a demand. The entries memory already answers — a local row, or an inherited inode whose value, metadata, length and child-directory count are resident — cost the request no Store reader at all. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | -| Those two batches are not everything an entry costs, and this route changes none of the rest: an inherited inode whose metadata is not inline reports one portable-metadata demand per distinct metadata root, a listed subdirectory one listing of that subdirectory for its child-directory count, and a symlink entry one read of its target. A window of only ordinary files with inline metadata therefore costs exactly the two batches; a window naming those entries costs more, growing with them and not with the names. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`view.rs`](../../../../engine/crates/layerfs-workspace/src/base/view.rs), [`links.rs`](../../../../engine/crates/layerfs-workspace/src/base/links.rs) | +| Those batches (the per-level inode reads and the length read) are not everything an entry costs, and this route changes none of the rest: an inherited inode whose metadata is not inline reports one portable-metadata demand per distinct metadata root, a listed subdirectory one listing of that subdirectory for its child-directory count, and a symlink entry one read of its target. A window of only ordinary files with inline metadata therefore pays only those batches (when the cache remembers lengths); a window naming those entries costs more, growing with them and not with the names. | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`view.rs`](../../../../engine/crates/layerfs-workspace/src/base/view.rs), [`links.rs`](../../../../engine/crates/layerfs-workspace/src/base/links.rs) | | Every handle a READDIRPLUS reply hands out takes its one kernel lookup reference in the publishing visit that makes its offset valid; a reply reusing an already published offset range hands out none. | [`kernel_cookie.rs`](../../../../engine/crates/layerfs-overlay/src/lifetime/kernel_cookie.rs) | | READDIR has one count, which bounds the whole reply. READDIRPLUS sends the entries' own count (`dircount`) before it; only `maxcount` bounds this reply, the count the client sized its buffer by. | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | | A reply's `dir_attributes` are the facts of the listed directory this window read, or the ones the export last observed for it (its OPENDIR visit read them): either way the reply costs no extra read. | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | diff --git a/engine/crates/layerfs-workspace/tests/kernel_directory.rs b/engine/crates/layerfs-workspace/tests/kernel_directory.rs index d6b8d622d4..f8c264c2d9 100644 --- a/engine/crates/layerfs-workspace/tests/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/tests/kernel_directory.rs @@ -412,7 +412,7 @@ fn window_fixture(files: u64) -> common::Fixture { bytes: Vec::new(), } } -/// One cold window over `files` inherited names, as a reply that shows each +/// One READDIRPLUS window over `files` inherited names, as a reply that shows each /// entry's facts reads it: (object batches, length batches, single length /// demands, entries listed). fn window_reads(files: u64) -> (u64, u64, u64, usize) { @@ -424,8 +424,9 @@ fn window_reads(files: u64) -> (u64, u64, u64, usize) { ); let mount = b.overlay.create_kernel_mount(1).unwrap(); let directory = open(&b, mount, 1, 1); - // Nothing of the base is resident: the window's names come from the - // Store, and so do the facts this reply shows. + // The cache starts empty, so the window's names and facts come from the + // Store; the OPENDIR and reading visit below fill the inode table's upper + // level into the same cache before the window's own reads are counted. let window = visit_with(&b, directory, 2, None, true).unwrap(); assert!(window.listing.is_none() && window.needs_base(true)); let store = &b.fixture.store; From 67559fdfe036de38cac08da686d976fc74f848f0 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Fri, 13 Nov 2026 10:07:41 +0000 Subject: [PATCH 07/53] docs(kernel-routes): port Decided/LOOKUP note from deleted ports.md Port the KernelRead::prepare Value(Decided) and LOOKUP parent-directory note from the removed docs/architecture/engine/kernel-routes/ports.md into docs/architecture/engine/kernel-routes/README.md. Production LOC: 160158 -> 160158 (delta 0) Scope and method: python3 -B tools/production_loc.py over first-party product Rust/SQL/JavaScript only (reference absent, retired R9c), at 4fa8381a4 and at this tree; documentation only. --- docs/architecture/engine/kernel-routes/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/README.md b/docs/architecture/engine/kernel-routes/README.md index da57b59e01..7bb37eefd7 100644 --- a/docs/architecture/engine/kernel-routes/README.md +++ b/docs/architecture/engine/kernel-routes/README.md @@ -73,7 +73,7 @@ stops: a stopped mount starts nothing new and still gives back what it holds. ```text LOOKUP/GETATTR/OPEN/OPENDIR KernelRead::prepare - loop: observe_visit -> Value | Refused | Needs(n): base(); supply; repeat + loop: observe_visit -> Value(Decided) | Refused | Needs(n): base(); supply; repeat READ/READLINK KernelData::read read_visit -> local window; base() only for inherited bytes mutation KernelMutation::perform @@ -85,7 +85,7 @@ stops: a stopped mount starts nothing new and still gives back what it holds. | Type or module | Kernel requests | Source | | --- | --- | --- | -| `KernelRead` | LOOKUP, GETATTR, OPEN, OPENDIR; holds nothing after its visits | [`lookup.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/lookup.rs) | +| `KernelRead` | LOOKUP, GETATTR, OPEN, OPENDIR; holds nothing after its visits (a LOOKUP also carries the directory it named) | [`lookup.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/lookup.rs) | | `KernelData` | READ, READLINK | [`read.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/read.rs) | | `KernelMutation` | Every changing request; holds one `Publication` ticket until `replied` | [`mutation.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/mutation.rs) | | `DirectoryStream` | READDIR; only accepted names become valid offsets | [`directory.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/directory.rs) | From 0b9c9e590a25349acbc74e0831ec32f264a742d0 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:18:59 +0000 Subject: [PATCH 08/53] fix(nfs): a failed LOOKUP answers its job's directory row, never a stale one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A refused LOOKUP answered `.or_else(|| kernel.directory_wcc(parent).0)`: `directory_stats`, the last stat this export observed for the directory. Nothing ages that entry — it is replaced only when the export observes the directory again and removed only on unlink — so the comment claiming "at most one observation old" was not a time bound. An install that changes a directory and is not observed, or any other writer to the same Workspace, left every negative LOOKUP in it answering the directory's old mtime/ctime; a macOS client loads those lookup post-op attributes, restarts `actimeo` and keeps the stale listing and name cache indefinitely. The deciding job already reads the parent's row, so its refusal now carries it: `KernelReadDecision::Refused { refusal, directory }` sends the fresh Inode from `decide` (a name that binds nothing) through `KernelRead`, and `nfs.rs` answers the failure's `dir_attributes` from it — one owner visit, fresh facts, no second job. `.`, `..`, silly names and refusals decided before any visit read no directory row and answer `None`, so the client falls back to its own `actimeo` instead of restarting the timer on facts nothing refreshes. `directory_wcc` now serves AppleDouble companions only, which is what its own comment describes, and the false time-bound comments are gone. `Kernel::lookup` now returns `Refused { status, directory }`; `Kernel`, `mount-ports` and the workspace decision type carry the new payload. The refusal types, the answer type and the port-failure mapping move from `kernel.rs` to the new `read.rs` so no file exceeds 999 lines (kernel.rs 989 -> 987, read.rs 79). Tests: `export.rs::a_failed_lookup_answers_fresh_directory_facts_never_a_stale_observation` adds a name to a directory from a second engine mount of the same Workspace, which the first export does not observe, and requires the failed LOOKUP's `dir_attributes` to be the directory's current facts (nlink 3, current mtime) and never the pre-change ones (nlink 2), plus `None` for `.`, `..` and a silly name; it fails against the previous behaviour (nlink 2 and the old mtime). `kernel_visit.rs::a_refused_lookup_answers_the_directory_its_job_read` pins the decision payload to the directory's current row. Production LOC: 160802 -> 160869 (delta +67) Scope and method: python3 -B tools/production_loc.py over first-party product Rust/SQL/JavaScript only (reference absent, retired R9c), at the merge tree 877a1aafd and at the committed tree of this commit. Co-Authored-By: Claude Opus 5 --- .../src/operations/lookup.rs | 18 +- engine/crates/layerfs-nfs/src/change.rs | 8 +- engine/crates/layerfs-nfs/src/directory.rs | 3 +- engine/crates/layerfs-nfs/src/kernel.rs | 160 +++++++++--------- engine/crates/layerfs-nfs/src/lib.rs | 1 + engine/crates/layerfs-nfs/src/nfs.rs | 33 ++-- engine/crates/layerfs-nfs/src/read.rs | 79 +++++++++ engine/crates/layerfs-nfs/tests/export.rs | 70 ++++++++ .../tests/refresh_lookups.rs | 2 +- .../src/operations/kernel_read.rs | 30 +++- .../layerfs-workspace/tests/kernel_visit.rs | 56 +++++- 11 files changed, 348 insertions(+), 112 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/read.rs diff --git a/engine/crates/layerfs-mount-ports/src/operations/lookup.rs b/engine/crates/layerfs-mount-ports/src/operations/lookup.rs index fb1e1b3c94..0a77df6119 100644 --- a/engine/crates/layerfs-mount-ports/src/operations/lookup.rs +++ b/engine/crates/layerfs-mount-ports/src/operations/lookup.rs @@ -3,7 +3,7 @@ use crate::ports::{BaseDemandFailed, Fenced, RequestServices, ServiceError, Serv use layerfs_overlay::KernelMount; use layerfs_workspace::{ KernelReadDecision, KernelReadFailure, KernelReadOperation, KernelReadOutcome, KernelReadValue, - Refusal, VisitFacts, + Refusal, ViewStat, VisitFacts, }; use std::{fmt, sync::Arc}; @@ -17,6 +17,9 @@ pub(super) struct Custody { pub data_input: Option, // Retain the engine receipt through every cloned outcome consumer. pub receipt: Option>>, + /// The directory row a refused LOOKUP read in the same job, fresh from + /// that job (see [`KernelRead::refused_directory`]). + pub refused_directory: Option, } /// A deciding answer and the receipt of the visit that decided it. /// The request holds nothing else in the engine; the kernel's lookup, open @@ -126,6 +129,13 @@ impl KernelRead { pub fn value(&self) -> Result<&KernelReadValue, Refusal> { self.value.as_ref().map_err(|refusal| *refusal) } + /// The directory row a refused LOOKUP read in its own job, when it read + /// one: the fresh facts its reply's directory attributes are made of. + /// `None` for every other refusal and for every other operation, none of + /// which read a directory row. + pub fn refused_directory(&self) -> Option<&ViewStat> { + self.custody.refused_directory.as_ref() + } /// Preserve a successfully decided request when kernel reply conversion or /// another downstream invariant fails before consumer disposal. pub fn retain(self, reason: ServiceError) -> ReadFailure { @@ -160,6 +170,7 @@ impl Custody { operation, data_input: None, receipt: None, + refused_directory: None, } } pub(super) const fn target(&self) -> (KernelMount, u64, Option) { @@ -200,7 +211,10 @@ impl Custody { original, })); } - (Ok(None), Some(KernelReadDecision::Refused(refusal))) => return Ok(Err(*refusal)), + (Ok(None), Some(KernelReadDecision::Refused { refusal, directory })) => { + self.refused_directory = directory.clone().map(Into::into); + return Ok(Err(*refusal)); + } (Ok(None), Some(KernelReadDecision::Needs(needs))) if !needs.is_empty() => needs, _ => { self.receipt = Some(receipt); diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 229e3e36bd..0f567d8f94 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -183,7 +183,7 @@ impl Kernel { let mutation = match wait(KernelMutation::perform(services, request)) { Ok(mutation) => mutation, Err(failure) => { - let status = if crate::kernel::failure_is_stale(&failure.reason) { + let status = if crate::read::failure_is_stale(&failure.reason) { Status::Stale } else { Status::Io @@ -262,8 +262,10 @@ impl Kernel { fn existing(&self, parent: u64, name: &[u8]) -> Result, Status> { match self.lookup(parent, name) { Ok((stat, _)) => Ok(Some(stat)), - Err(Status::NoEnt) => Ok(None), - Err(status) => Err(status), + Err(refused) => match refused.status { + Status::NoEnt => Ok(None), + status => Err(status), + }, } } /// CREATE of a regular file. diff --git a/engine/crates/layerfs-nfs/src/directory.rs b/engine/crates/layerfs-nfs/src/directory.rs index 56cd620e07..166757922c 100644 --- a/engine/crates/layerfs-nfs/src/directory.rs +++ b/engine/crates/layerfs-nfs/src/directory.rs @@ -25,7 +25,8 @@ use crate::{ attributes::{post_op_maybe, Identity, Status}, block::wait, handle::HANDLE_BYTES, - kernel::{failure, Kernel}, + kernel::Kernel, + read::failure, xdr::{opaque_size, Writer}, }; use layerfs_content::object::inode_leaf::InodeKind; diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 2714e80cbe..86c0834636 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -40,13 +40,14 @@ use crate::{ block::wait, change::Wcc, handle::{HandleError, SqliteHandles}, + read::{failure, read_failure, Answer, Refused}, }; use layerfs_content::{filesystem::PathName, object::inode_leaf::InodeKind}; use layerfs_mount_ports::{ - operations::{KernelData, KernelRead, MutationFailure, ReadDataInput, ReadFailure}, - ports::{Fence, MountServices, RequestServices, ServiceError}, + operations::{KernelData, KernelRead, MutationFailure, ReadDataInput}, + ports::{Fence, MountServices, RequestServices}, }; -use layerfs_overlay::{KernelMount, OverlayError, READ_WINDOW}; +use layerfs_overlay::{KernelMount, READ_WINDOW}; use layerfs_workspace::{KernelReadOperation, ViewStat}; use std::{ collections::{HashMap, HashSet}, @@ -135,17 +136,6 @@ pub(crate) struct OpenFile { pub handle: u64, pub size: u64, } - -/// One kernel read's answer, as this export uses it. -struct Answer { - stat: ViewStat, - /// The directory a LOOKUP named the inode in: the same visit read it, so - /// the reply's directory attributes cost no second owner job. - parent: Option, - file: Option, - directory: Option, -} - /// One kernel mount served over NFS: its ports and its synthetic kernel state. pub struct Kernel { services: Arc, @@ -295,6 +285,7 @@ impl Kernel { None, KernelReadOperation::Lookup { parent, name: path }, ) + .map_err(|refused| refused.status) }); match found { Ok(answer) => { @@ -331,20 +322,37 @@ impl Kernel { protected: u64, handle: Option, operation: KernelReadOperation, - ) -> Result { - let (services, request) = self.request()?; + ) -> Result { + let (services, request) = self.request().map_err(|status| Refused { + status, + directory: None, + })?; let found = wait(KernelRead::prepare( services, self.mount, request, protected, handle, operation, )) - .map_err(read_failure)?; - let answer = found.value().map(|value| Answer { - stat: value.stat.clone(), - parent: value.parent.clone(), - file: value.file.map(|file| file.owner_id()), - directory: value.directory.map(|directory| directory.owner_id()), - }); - wait(found.dispose()).map_err(read_failure)?; - answer.map_err(refusal) + .map_err(|failure| Refused { + status: read_failure(failure), + directory: None, + })?; + let answer = match found.value() { + Ok(value) => Ok(Answer { + stat: value.stat.clone(), + parent: value.parent.clone(), + file: value.file.map(|file| file.owner_id()), + directory: value.directory.map(|directory| directory.owner_id()), + }), + // A refusal still carries the directory row its job read, when it + // read one: fresh facts, not this export's last observation. + Err(status) => Err(Refused { + status: refusal(status), + directory: found.refused_directory().cloned(), + }), + }; + wait(found.dispose()).map_err(|failure| Refused { + status: read_failure(failure), + directory: None, + })?; + answer } /// GETATTR. An inode that lost its last name while a silly name keeps it /// is observed through its descriptor; any other inode no name reaches @@ -364,12 +372,9 @@ impl Kernel { let stat = self .observe(serial, handle, KernelReadOperation::Getattr { serial }) .map(|answer| answer.stat) - .map_err(|status| { - if status == Status::NoEnt { - Status::Stale - } else { - status - } + .map_err(|refused| match refused.status { + Status::NoEnt => Status::Stale, + status => status, })?; self.observed(&stat); Ok(stat) @@ -378,41 +383,63 @@ impl Kernel { /// export's own silly names. One owner job answers both the entry and, /// when the name resolved, the directory itself: the same job had to read /// the directory's row to resolve it, so the reply's directory attributes - /// cost nothing more. The second half is `None` for `.`, `..`, a silly - /// name and every failure, whose answers carry the facts - /// [`Kernel::directory_wcc`] holds instead of a fresh GETATTR: a deliberate - /// change, and RFC 1813 makes those attributes optional. - pub fn lookup(&self, parent: u64, name: &[u8]) -> Result<(ViewStat, Option), Status> { + /// cost nothing more. + /// + /// A failure answers the directory's own fresh facts only when the job + /// that failed read its row, which is every name this export looked up: + /// a name that binds nothing still read the parent's row. `.`, `..`, a + /// silly name and a refusal decided before any visit read no directory + /// row and answer `None`, so the client falls back to its own `actimeo` + /// instead of restarting its timer on facts nothing refreshes. + pub fn lookup( + &self, + parent: u64, + name: &[u8], + ) -> Result<(ViewStat, Option), Refused> { match name { - b"" => return Err(Status::NoEnt), - b"." => return self.getattr(parent).map(|stat| (stat, None)), + b"" => return Err(Refused::plain(Status::NoEnt)), + b"." => { + return self + .getattr(parent) + .map(|stat| (stat, None)) + .map_err(Refused::plain) + } b".." => { let up = if parent == self.root() { parent } else { let known = self.table().parents.get(&parent).copied(); - known.ok_or(Status::NoEnt)? + known.ok_or(Refused::plain(Status::NoEnt))? }; - self.held_reference(up)?; - return self.getattr(up).map(|stat| (stat, None)); + self.held_reference(up).map_err(Refused::plain)?; + return self + .getattr(up) + .map(|stat| (stat, None)) + .map_err(Refused::plain); } - _ if name.len() > 255 => return Err(Status::NameTooLong), + _ if name.len() > 255 => return Err(Refused::plain(Status::NameTooLong)), _ => {} } + // An AppleDouble companion lives in the export alone, so its reply's + // directory half is the facts this export last answered for the + // directory: a companion change never touches it. if let Some(stat) = self.companion_named(parent, name) { return Ok((stat, self.directory_wcc(parent).0)); } if self.refuses_apple_double() && crate::names::apple_double(name) { if parent != self.root() && !self.table().parents.contains_key(&parent) { - return Err(Status::NotDir); + return Err(Refused::plain(Status::NotDir)); } - return Err(Status::NoEnt); + return Err(Refused::plain(Status::NoEnt)); } let silly = self.table().silly.get(&(parent, name.to_vec())).copied(); if let Some(serial) = silly { - return self.getattr(serial).map(|stat| (stat, None)); + return self + .getattr(serial) + .map(|stat| (stat, None)) + .map_err(Refused::plain); } - let path = PathName::from_bytes(name).map_err(|_| Status::Inval)?; + let path = PathName::from_bytes(name).map_err(|_| Refused::plain(Status::Inval))?; let answer = self.observe( parent, None, @@ -629,7 +656,9 @@ impl Kernel { } } let operation = KernelReadOperation::Open { serial, writable }; - let answer = self.observe(serial, None, operation)?; + let answer = self + .observe(serial, None, operation) + .map_err(|refused| refused.status)?; let handle = answer.file.ok_or(Status::ServerFault)?; Ok(self.file_taken(serial, handle, &answer.stat, writable)) } @@ -748,7 +777,9 @@ impl Kernel { if crate::apple_double::companion(serial) { return Err(Status::NotDir); } - let answer = self.observe(serial, None, KernelReadOperation::Opendir { serial })?; + let answer = self + .observe(serial, None, KernelReadOperation::Opendir { serial }) + .map_err(|refused| refused.status)?; let handle = answer.directory.ok_or(Status::ServerFault)?; // The visit read the directory's own row: remember it, so a LOOKUP in // this directory answers its `dir_attributes` from memory. @@ -954,36 +985,3 @@ pub struct Released { fn oldest(entries: impl Iterator) -> Option { entries.min_by_key(|(_, tick)| *tick).map(|(key, _)| key) } -fn stale(error: &(dyn std::error::Error + 'static)) -> bool { - let mut current = Some(error); - while let Some(error) = current { - if matches!( - error.downcast_ref::(), - Some(OverlayError::Stale) - ) { - return true; - } - current = error.source(); - } - false -} -/// Whether a failed step's cause chain holds an engine `Stale`. -pub(crate) fn failure_is_stale(error: &ServiceError) -> bool { - stale(error.as_ref()) -} -/// A failed port step: an engine `Stale` is the client's stale handle; any -/// other failure is an I/O error of this request alone. -pub fn failure(error: ServiceError) -> Status { - if stale(error.as_ref()) { - Status::Stale - } else { - Status::Io - } -} -fn read_failure(failure: ReadFailure) -> Status { - if stale(failure.reason.as_ref()) { - Status::Stale - } else { - Status::Io - } -} diff --git a/engine/crates/layerfs-nfs/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index f5cb633717..665eedf8a3 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -27,6 +27,7 @@ pub mod kernel; mod mount; pub mod names; mod nfs; +pub mod read; pub mod refresh; pub mod rpc; mod server; diff --git a/engine/crates/layerfs-nfs/src/nfs.rs b/engine/crates/layerfs-nfs/src/nfs.rs index 526a436c71..1b05fc15de 100644 --- a/engine/crates/layerfs-nfs/src/nfs.rs +++ b/engine/crates/layerfs-nfs/src/nfs.rs @@ -111,36 +111,33 @@ pub fn call( // in (RFC 1813 LOOKUP3resok's `obj_attributes` and // `dir_attributes`, and the failure's). The job had to read the // directory's own row to resolve the name, so its attributes cost - // no second job. Deliberate change from the route before this: a - // failure (`NFS3ERR_NOENT` included), `.`, `..` and a silly name - // answer the directory facts this export last published or - // observed for it, and none when it never saw the directory, - // where each of them used to make a fresh GETATTR of the parent. - // RFC 1813 keeps those attributes optional, so both are legal; - // the answer is now at most one observation old. - let (parent, found) = match parent { - Ok(parent) => (parent, kernel.lookup(parent, name)), + // no second job, and a name that binds nothing still read that row: + // the failed answer carries the same fresh facts. + // + // Every answer that read no directory row says so instead of + // repeating this export's last observation: `.`, `..`, a silly + // name and a refusal decided before the job. Stale attributes are + // worse than none here — the client would load them into its + // attribute cache, restart `actimeo` and keep a listing nothing + // refreshes — and RFC 1813 keeps both fields optional. + let found = match parent { + Ok(parent) => kernel.lookup(parent, name), Err(status) => { out.u32(status.code()); post_op_maybe(kernel.identity(), out, None); return Ok(()); } }; - let directory = match &found { - Ok((_, directory)) => directory.clone(), - Err(_) => None, - } - .or_else(|| kernel.directory_wcc(parent).0); match found { - Ok((stat, _)) => { + Ok((stat, directory)) => { out.u32(Status::Ok.code()); out.opaque(&kernel.encode(stat.serial)); kernel.identity().post_op(out, &stat); post_op_maybe(kernel.identity(), out, directory.as_ref()); } - Err(status) => { - out.u32(status.code()); - post_op_maybe(kernel.identity(), out, directory.as_ref()); + Err(refused) => { + out.u32(refused.status.code()); + post_op_maybe(kernel.identity(), out, refused.directory.as_ref()); } } Ok(()) diff --git a/engine/crates/layerfs-nfs/src/read.rs b/engine/crates/layerfs-nfs/src/read.rs new file mode 100644 index 0000000000..4b0e31e027 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/read.rs @@ -0,0 +1,79 @@ +//! What one kernel read answers this export, and what a failed one means. +//! +//! A read is served by one owner job (see [`crate::kernel`]). Its answer is +//! the entry it names and, for a LOOKUP, the directory it was named in, which +//! that job had to read anyway. A refusal keeps the directory row its own job +//! read, when it read one, so a reply's `dir_attributes` are current facts and +//! never this export's last observation: nothing ages such an observation, so +//! a client that loaded it would restart its own `actimeo` on facts that do +//! not change until the export happens to observe the directory again. +use crate::attributes::Status; +use layerfs_mount_ports::{operations::ReadFailure, ports::ServiceError}; +use layerfs_overlay::OverlayError; +use layerfs_workspace::ViewStat; + +/// One kernel read's answer, as this export uses it. +pub(crate) struct Answer { + pub stat: ViewStat, + /// The directory a LOOKUP named the inode in: the same visit read it, so + /// the reply's directory attributes cost no second owner job. + pub parent: Option, + pub file: Option, + pub directory: Option, +} + +/// A read this export refused: the status its reply answers, and the fresh +/// directory facts the refusing job read, when it read one. A LOOKUP that +/// binds no name read its parent's row in the same job, so the failure's +/// `dir_attributes` are those facts and never a last observation that no +/// time bound ages (see [`crate::kernel::Kernel::lookup`]). +pub struct Refused { + pub status: Status, + pub directory: Option, +} +impl Refused { + /// A refusal no visit decided: no job read a directory row for it. + pub(crate) const fn plain(status: Status) -> Self { + Self { + status, + directory: None, + } + } +} + +fn stale(error: &(dyn std::error::Error + 'static)) -> bool { + let mut current = Some(error); + while let Some(error) = current { + if matches!( + error.downcast_ref::(), + Some(OverlayError::Stale) + ) { + return true; + } + current = error.source(); + } + false +} + +/// Whether a failed step's cause chain holds an engine `Stale`. +pub(crate) fn failure_is_stale(error: &ServiceError) -> bool { + stale(error.as_ref()) +} + +/// A failed port step: an engine `Stale` is the client's stale handle; any +/// other failure is an I/O error of this request alone. +pub fn failure(error: ServiceError) -> Status { + if stale(error.as_ref()) { + Status::Stale + } else { + Status::Io + } +} + +pub(crate) fn read_failure(failure: ReadFailure) -> Status { + if stale(failure.reason.as_ref()) { + Status::Stale + } else { + Status::Io + } +} diff --git a/engine/crates/layerfs-nfs/tests/export.rs b/engine/crates/layerfs-nfs/tests/export.rs index 087397c779..414d4d9b41 100644 --- a/engine/crates/layerfs-nfs/tests/export.rs +++ b/engine/crates/layerfs-nfs/tests/export.rs @@ -547,3 +547,73 @@ fn a_listing_spends_one_owner_visit_and_reads_its_window_in_batches() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_failed_lookup_answers_fresh_directory_facts_never_a_stale_observation() { + let base = temp("lookup-directory"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let first = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut client = Client::connect(first.local_addr(), UID, GID); + let root = client.mnt("/"); + let made = client.mkdir(&root, b"watched", 0o755).unwrap(); + let before = client.getattr(&made.handle).unwrap(); + assert_eq!(before.nlink, 2, "an empty directory"); + + // A second engine mount of the same Workspace adds a name to the + // directory this export watches. This export observes no publication for + // it, which is the install and other-writer case: its last observation of + // the directory is now older than the directory's own row. + let second = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut other = Client::connect(second.local_addr(), UID, GID); + let other_root = other.mnt("/"); + let (target, _) = other.lookup(&other_root, b"watched").unwrap(); + other.mkdir(&target, b"child", 0o755).unwrap(); + + // The failed LOOKUP answers the directory's current facts: the job that + // found no name read the directory's row in the same visit. Nothing may + // answer the last observation instead, which no time bound ages. + let (status, found, directory) = client.lookup_with_directory(&made.handle, b"absent"); + assert_eq!((status, found), (NOENT, None)); + let fresh = client.getattr(&made.handle).unwrap(); + assert_eq!(fresh.nlink, 3, "the directory gained a child directory"); + assert_eq!(directory, Some(fresh.clone()), "the current facts"); + assert_ne!(directory, Some(before), "never the last observation"); + + // A name this export decides without an owner job reads no directory row + // and answers no directory attributes, so a client falls back to its own + // `actimeo` rather than restarting it on facts nothing refreshes. + let (status, found, directory) = client.lookup_with_directory(&made.handle, b"."); + assert_eq!(status, 0); + assert!(found.is_some()); + assert_eq!(directory, None, "no attributes for `.`"); + let (status, found, directory) = client.lookup_with_directory(&made.handle, b".."); + assert_eq!(status, 0); + assert!(found.is_some()); + assert_eq!(directory, None, "no attributes for `..`"); + + // A silly name is kept by this export alone; its reply names none either. + let open = client.touch(&made.handle, b"open", 0o644).unwrap(); + client + .rename( + &made.handle, + b"open", + &made.handle, + b".nfs00000000000012ab00000001", + ) + .unwrap(); + let (status, found, directory) = + client.lookup_with_directory(&made.handle, b".nfs00000000000012ab00000001"); + assert_eq!(status, 0); + assert_eq!(found.map(|(handle, _)| handle), Some(open.handle)); + assert_eq!(directory, None, "no attributes for a silly name"); + + drop(client); + drop(other); + let released = first.stop(); + second.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} diff --git a/engine/crates/layerfs-store-service/tests/refresh_lookups.rs b/engine/crates/layerfs-store-service/tests/refresh_lookups.rs index d0c21d221e..0874986666 100644 --- a/engine/crates/layerfs-store-service/tests/refresh_lookups.rs +++ b/engine/crates/layerfs-store-service/tests/refresh_lookups.rs @@ -208,7 +208,7 @@ fn refresh_lookups() { visits += 1; match &outcome.decision { Some(KernelReadDecision::Value(_)) => break, - Some(KernelReadDecision::Refused(_)) => { + Some(KernelReadDecision::Refused { .. }) => { missing += 1; break; } diff --git a/engine/crates/layerfs-workspace/src/operations/kernel_read.rs b/engine/crates/layerfs-workspace/src/operations/kernel_read.rs index 45b0f3205f..ad457daa71 100644 --- a/engine/crates/layerfs-workspace/src/operations/kernel_read.rs +++ b/engine/crates/layerfs-workspace/src/operations/kernel_read.rs @@ -33,7 +33,15 @@ pub enum KernelReadOperation { pub enum KernelReadDecision { Needs(Vec), Value(Decided), - Refused(Refusal), + /// A refusal and, when the refusing job read it, the directory that job + /// read: a LOOKUP that binds no name still read its parent's row, so the + /// failure's directory attributes are those fresh facts and cost no + /// second visit. `None` when no job read a directory (a refusal decided + /// before the visit, or one about the name itself). + Refused { + refusal: Refusal, + directory: Option, + }, Failed(WorkspaceError), } /// What a read decided: the inode it names and, for a LOOKUP, the directory @@ -101,14 +109,19 @@ pub(crate) fn decide_read( kernel: None, needs: Vec::new(), }; - let decision = match decide(operation, &mut eval) { + // The directory a refusing decision read, when it read one. + let mut refused_directory = None; + let decision = match decide(operation, &mut eval, &mut refused_directory) { Ok(Some(decided)) => KernelReadDecision::Value(decided), Ok(None) if !eval.needs.is_empty() => KernelReadDecision::Needs(eval.needs), Ok(None) => KernelReadDecision::Failed( ContentError::InvalidRecord("empty kernel read needs").into(), ), Err(WorkspaceError::Overlay(error)) => return Err(error), - Err(WorkspaceError::Refused(refusal)) => KernelReadDecision::Refused(refusal), + Err(WorkspaceError::Refused(refusal)) => KernelReadDecision::Refused { + refusal, + directory: refused_directory, + }, Err(error) => KernelReadDecision::Failed(error), }; Ok(match decision { @@ -123,9 +136,12 @@ pub(crate) fn decide_read( }, }) } +/// One read's decision. `refused` receives the directory row a refusal read, +/// when the refused operation read one (LOOKUP of a name that binds nothing). fn decide( operation: &KernelReadOperation, eval: &mut Eval<'_>, + refused: &mut Option, ) -> WorkspaceResult> { match operation { // The source's independent read reference permits removed metadata. @@ -165,7 +181,13 @@ fn decide( let (Some(directory), Some(bound)) = (directory, bound) else { return Ok(None); }; - let serial = bound.ok_or(WorkspaceError::Refused(Refusal::Missing))?; + let Some(serial) = bound else { + // The name binds nothing. This job still read the directory's + // own row, so its fresh facts answer the failure's directory + // attributes without a second visit. + *refused = Some(directory); + return Err(WorkspaceError::Refused(Refusal::Missing)); + }; // The name resolved, so the reply also says what the directory // is: the same job read its row, and no second visit is needed. Ok(eval.target(serial)?.map(|inode| Decided { diff --git a/engine/crates/layerfs-workspace/tests/kernel_visit.rs b/engine/crates/layerfs-workspace/tests/kernel_visit.rs index 0045cfa6a7..42b80d892e 100644 --- a/engine/crates/layerfs-workspace/tests/kernel_visit.rs +++ b/engine/crates/layerfs-workspace/tests/kernel_visit.rs @@ -94,7 +94,7 @@ fn observe( match outcome.decision { Some(KernelReadDecision::Needs(needs)) => Seen::Needs(needs), Some(KernelReadDecision::Value(decided)) => Seen::Value(decided.inode), - Some(KernelReadDecision::Refused(refusal)) => Seen::Refused(refusal), + Some(KernelReadDecision::Refused { refusal, .. }) => Seen::Refused(refusal), other => panic!("undecided read visit: {other:?}"), } } @@ -128,7 +128,7 @@ fn open( let seen = match outcome.decision { Some(KernelReadDecision::Needs(needs)) => Seen::Needs(needs), Some(KernelReadDecision::Value(decided)) => Seen::Value(decided.inode), - Some(KernelReadDecision::Refused(refusal)) => Seen::Refused(refusal), + Some(KernelReadDecision::Refused { refusal, .. }) => Seen::Refused(refusal), other => panic!("undecided open visit: {other:?}"), }; assert_eq!( @@ -1079,3 +1079,55 @@ fn a_resident_client_answers_only_from_memory_and_only_small_objects() { ); assert_eq!(memory.read_canonical_batch(&[absent]).unwrap().len(), 1); } + +#[test] +fn a_refused_lookup_answers_the_directory_its_job_read() { + let b = Bench::new("kernel-read-refused-directory"); + let mount = b.overlay.create_kernel_mount(1).unwrap(); + let mut facts = VisitFacts::default(); + // The name binds nothing: the job still read the root's own row, and its + // refusal carries that row, so a reply's directory attributes need no + // second visit and are never a stale observation. + for _ in 0..4 { + let visit = b + .workspace + .kernel_read_visit( + empty(), + mount, + 1, + None, + lookup(1, "absent"), + Arc::new(facts.clone()), + ) + .unwrap(); + let demand = b.demand(); + let outcome = visit.perform(&b.overlay); + assert_eq!(b.demand(), demand, "an owner visit asked the provider"); + match outcome.decision { + Some(KernelReadDecision::Needs(needs)) => facts + .supply(&b.workspace.base().unwrap(), &needs, None) + .unwrap(), + Some(KernelReadDecision::Refused { refusal, directory }) => { + assert_eq!(refusal, Refusal::Missing); + let directory = directory.expect("the directory the job read"); + let fresh = b.stat(1).unwrap(); + assert_eq!( + directory.serial, fresh.serial, + "the directory the name was in" + ); + assert_eq!( + (directory.mtime_seconds, directory.mtime_nanoseconds), + ( + fresh.metadata.mtime_seconds, + fresh.metadata.mtime_nanoseconds + ), + "the directory's own current row" + ); + assert_eq!(directory.nlink, fresh.namespace_refs, "its reference count"); + return; + } + other => panic!("undecided read visit: {other:?}"), + } + } + panic!("the missing lookup was not decided in four visits"); +} From fdf673e602470f5c64d39dd4d20ff45562c86b1e Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:25:41 +0000 Subject: [PATCH 09/53] perf(readdirplus): truncate to the published names before reading facts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `KernelDirectoryWindow::finish_with` called `listing_with_facts` for the whole window — up to PAGE_ROWS = 1024 names — and only then truncated it to the names `offer.existing()` publishes. A re-sent reply, which is exactly the truncated case, read the facts of every name in the window and sent a few: one batch length demand and the per-level inode batches for all of them. The base route read facts after truncation. Names and kinds now come first: `listing` merges the window and reads the inherited kinds in one batch inode demand per inode-tree level (no length demand, which belongs to facts), so both the reading visit and the request keep their bounded per-level count. The offer truncates that window, and `facts` then reads only the entries the reply sends. `listing_with_facts` is gone; `inherited_values` keeps its one length demand and `inode_values` is the kinds-only form it now splits into. Test: `kernel_directory.rs::a_re_sent_reply_reads_no_fact_of_a_name_it_does_not_send` publishes a two-name reply over a nine-name window and requires the re-sent READDIRPLUS to remember exactly two lengths (`file_lengths`); reading facts before truncation read eight. Production LOC: 160869 -> 160847 (delta -22) Scope and method: python3 -B tools/production_loc.py over first-party product Rust/SQL/JavaScript only (reference absent, retired R9c), at 917e554e6 and at the staged tree of this commit. Co-Authored-By: Claude Opus 5 --- .../src/operations/kernel_directory.rs | 97 ++++++++----------- .../tests/kernel_directory.rs | 43 ++++++++ 2 files changed, 85 insertions(+), 55 deletions(-) diff --git a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs index b9b3fe5d30..8ece38671a 100644 --- a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs @@ -5,10 +5,12 @@ //! cache holds them; otherwise the request merges them outside the owner //! over one Store reader, at the base root the visit named. A reply that //! shows each entry's facts (READDIRPLUS) takes them from the same memory -//! first, and reads what is left in one batch length demand for the window -//! and one batch inode demand for each level of the inode tree the cache does -//! not already answer, so those counts follow the tree's depth and not the -//! number of names. What those batches +//! first; what is left is read outside the owner once the reply's published +//! names are known: one batch length demand and one batch inode demand for +//! each level of the inode tree the cache does not already answer, for the +//! names that reply sends and not for the rest of the window, so those counts +//! follow the tree's depth and the reply's size and not the number of listed +//! names. What those batches //! do not cover is per entry and unchanged here: a non-inline metadata root, //! a listed subdirectory's child-directory count, and a symlink's target are //! still read once for each entry that needs them. The request then fills its @@ -237,11 +239,13 @@ impl KernelDirectoryWindow { self.finish_with(base, false) } /// The same for a reply that also shows what each accepted entry is, as - /// READDIRPLUS does. The reading visit already said what memory held; the - /// names it left undecided are read here in one batch length demand for - /// the window and one batch inode demand for each level of the inode tree - /// the cache does not already answer, so the number of names adds no - /// demand while a deeper tree adds one. Those batches are not the whole + /// READDIRPLUS does. Names and kinds come first — from memory in the + /// reading visit, else here in one batch inode demand for each level of the + /// inode tree the cache does not already answer — and the offer then + /// truncates that window to the names this reply publishes, so only those + /// names' facts are read: one batch length demand for them and the same + /// per-level batches. A re-sent reply therefore reads nothing for a name it + /// will not send. Those batches are not the whole /// cost of an entry: /// [`base_facts`] still reads an inherited inode's non-inline metadata /// root, a listed subdirectory's child-directory count and a symlink's @@ -269,7 +273,9 @@ impl KernelDirectoryWindow { }; let listing = match (merged, base.as_deref()) { (Some(listing), _) => listing, - (_, Some(base)) if attributes => listing_with_facts(base, &page)?, + // Names and kinds only: a re-sent reply that publishes fewer + // names than this window lists reads no fact of one it will not + // send. `facts` reads what the truncated reply does send. (_, Some(base)) => listing(base, &page)?, (_, None) => { return Err( @@ -349,12 +355,8 @@ fn facts( Ok(()) } /// The base values of the window's inherited serials, in one batch inode -/// demand for each level of the inode tree the cache does not already answer, -/// after one length demand remembered the window's ordinary file lengths. -fn inherited_values( - base: &BaseView, - serials: &[u64], -) -> WorkspaceResult> { +/// demand for each level of the inode tree the cache does not already answer. +fn inode_values(base: &BaseView, serials: &[u64]) -> WorkspaceResult> { if serials.is_empty() { return Ok(BTreeMap::new()); } @@ -364,22 +366,31 @@ fn inherited_values( serials, &mut InodeReadWork::default(), )?; + Ok(serials + .iter() + .copied() + .zip(values) + .filter_map(|(serial, value)| Some((serial, value?))) + .collect()) +} +/// The base values of the window's inherited serials, in one batch inode +/// demand for each level of the inode tree the cache does not already answer, +/// after one length demand remembered the window's ordinary file lengths. +fn inherited_values( + base: &BaseView, + serials: &[u64], +) -> WorkspaceResult> { + let values = inode_values(base, serials)?; // Every ordinary file's length, from the one demand this window makes. let roots: Vec = values - .iter() - .flatten() + .values() .filter(|value| value.kind == InodeKind::RegularFile) .map(|value| value.content_root) .collect(); if !roots.is_empty() { base.client().provide_lengths(&roots)?; } - Ok(serials - .iter() - .copied() - .zip(values) - .filter_map(|(serial, value)| Some((serial, value?))) - .collect()) + Ok(values) } /// The facts of one inherited name: its base inode, the metadata every /// attribute carries, its content length and, for a directory, the count its @@ -469,11 +480,10 @@ fn merge(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult WorkspaceResult { +fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult { let merged = merge(base, page)?; + // The window's inherited serials come in one batch inode demand for each + // level the cache does not already answer: kinds alone cost no length. let inherited: Vec = merged .names .iter() @@ -482,39 +492,16 @@ fn listing_with_facts( .collect::>() .into_iter() .collect(); - let found = inherited_values(base, &inherited)?; + let found = inode_values(base, &inherited)?; let mut entries = Vec::with_capacity(merged.names.len()); for (name, serial) in merged.names { - let (kind, stat) = match local_row(page, serial) { - Some(row) => (kind_of(row.kind), ViewStat::from(row.clone())), + let kind = match local_row(page, serial) { + Some(row) => kind_of(row.kind), None => { let value = *found.get(&serial).ok_or(ContentError::PathNotFound)?; - (value.kind, base_facts(base, serial, value)?) + value.kind } }; - entries.push(KernelDirectoryEntry { - name, - serial, - kind, - stat: Some(stat), - }); - } - Ok(KernelDirectoryListing { - entries, - continuation: merged.continuation, - visited: merged.visited, - }) -} -/// One window's merged names over `base` with their kinds, read from memory -/// alone: a local row, or an inherited inode the canonical cache answers. -fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult { - let merged = merge(base, page)?; - let mut entries = Vec::with_capacity(merged.names.len()); - for (name, serial) in merged.names { - let kind = match local_row(page, serial) { - Some(row) => kind_of(row.kind), - None => base.inode(serial)?.value.kind, - }; entries.push(KernelDirectoryEntry { name, serial, diff --git a/engine/crates/layerfs-workspace/tests/kernel_directory.rs b/engine/crates/layerfs-workspace/tests/kernel_directory.rs index f8c264c2d9..48c9b2153b 100644 --- a/engine/crates/layerfs-workspace/tests/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/tests/kernel_directory.rs @@ -331,6 +331,49 @@ fn next_directory_read_observes_parent_moved_by_the_atomic_namespace_job() { .unwrap(); b.overlay.revoke_kernel_mount(mount).unwrap(); } +#[test] +fn a_re_sent_reply_reads_no_fact_of_a_name_it_does_not_send() { + let b = Bench::over("kernel-directory-resend", window_fixture(8), 4 << 20); + let mount = b.overlay.create_kernel_mount(1).unwrap(); + let directory = open(&b, mount, 1, 1); + let first = batch(&b, visit(&b, directory, 2, None).unwrap()); + assert_eq!(first.entries.len(), 9, "eight names and the subdirectory"); + // Publish only the first two names, as a reply with a smaller budget does: + // a later reply at the same offset reuses that range and sends no name + // beyond it. + let names: Vec<_> = first + .entries + .iter() + .map(|entry| entry.name.clone()) + .collect(); + let offer = first.publish.as_ref().expect("a fresh reply to publish"); + b.overlay + .publish_kernel_cookies(offer, &names[..2]) + .unwrap(); + assert_eq!( + b.cache.diagnostics().unwrap().file_lengths, + 0, + "a plain listing reads no length" + ); + // Only the two names this reply sends have their facts read: seven names + // of the same window are read nothing, so only two lengths are demanded + // and remembered. + let window = visit_with(&b, directory, 2, None, true).unwrap(); + let listed = window + .finish_with(Some(&b.workspace.base().unwrap()), true) + .unwrap(); + assert_eq!(listed.entries.len(), 2); + assert!(listed.entries.iter().all(|entry| entry.stat.is_some())); + assert_eq!( + b.cache.diagnostics().unwrap().file_lengths, + 2, + "two names sent, two lengths read" + ); + b.overlay + .close_kernel_directory(directory.mount(), directory.serial(), directory.owner_id()) + .unwrap(); + b.overlay.revoke_kernel_mount(mount).unwrap(); +} /// A root holding `files` inherited regular files, each with its own content, /// and one inherited subdirectory with a file of its own: a window whose /// names, kinds, lengths and child-directory count all come from the base. From 261cb22926508ad9d9de1bcb6d0d1c271974eb38 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:31:13 +0000 Subject: [PATCH 10/53] perf(readdirplus): one inode read per listed name in the reading visit `memory_stat` repeated the `base.inode(serial)` lookup `listing` had just done for every name of a READDIRPLUS window, inside the owner visit. It is bounded and reads no Store (`resident` answers memory only), but it is the same page walk twice per name. `listing` now returns those base values with the listing it built (`Kinds { listing, values }`), and `memory_stat` takes the value by reference, so the visit reads each inherited inode once. The cold path keeps `Kinds.values` unused: `facts` reads the names the reply sends, after the offer truncates the window. No new test: the duplicate was an in-memory lookup with no observable I/O, and `kernel_directory.rs`'s window tests cover both paths. Production LOC: 160847 -> 160864 (delta +17) Scope and method: python3 -B tools/production_loc.py over first-party product Rust/SQL/JavaScript only (reference absent, retired R9c), at 272fa823c and at the staged tree of this commit. Co-Authored-By: Claude Opus 5 --- .../src/operations/kernel_directory.rs | 66 ++++++++++++------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs index 8ece38671a..10764718f2 100644 --- a/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs +++ b/engine/crates/layerfs-workspace/src/operations/kernel_directory.rs @@ -178,13 +178,20 @@ impl KernelDirectoryVisit { let listing = (self.resident.identity().0.to_bytes() == page.source().root()) .then(|| listing(&self.resident, &page).ok()) .flatten() - .map(|mut listing| { + .map(|Kinds { listing, values }| { + let mut listing = listing; // A reply that shows facts takes the local rows this window - // already read and whatever else memory answers, so only the - // names memory left undecided take the one Store read. + // already read and whatever else memory answers, from the base + // values the kinds came from: no inode is read twice here, so + // only the names memory left undecided take the one Store read. if self.attributes { for entry in &mut listing.entries { - entry.stat = memory_stat(&self.resident, &page, entry.serial); + entry.stat = memory_stat( + &self.resident, + &page, + entry.serial, + values.get(&entry.serial), + ); } } listing @@ -276,7 +283,7 @@ impl KernelDirectoryWindow { // Names and kinds only: a re-sent reply that publishes fewer // names than this window lists reads no fact of one it will not // send. `facts` reads what the truncated reply does send. - (_, Some(base)) => listing(base, &page)?, + (_, Some(base)) => listing(base, &page)?.listing, (_, None) => { return Err( ContentError::InvalidRecord("kernel directory window without its base").into(), @@ -422,15 +429,19 @@ const fn kind_of(kind: layerfs_overlay::InodeKind) -> InodeKind { } } /// The facts of one entry as far as memory alone answers them: a local row, -/// or an inherited inode whose value, metadata, length and child-directory -/// count this daemon's caches already hold. Anything else is absent here, and -/// the request's one Store read supplies it. -fn memory_stat(base: &BaseView, page: &KernelDirectoryPage, serial: u64) -> Option { +/// or an inherited inode whose value this window's listing already read, with +/// the metadata, length and child-directory count this daemon's caches hold. +/// Anything else is absent here, and the request's one Store read supplies it. +fn memory_stat( + base: &BaseView, + page: &KernelDirectoryPage, + serial: u64, + value: Option<&InodeValue>, +) -> Option { if let Some(row) = local_row(page, serial) { return Some(ViewStat::from(row.clone())); } - let value = base.inode(serial).ok()?.value; - base_facts(base, serial, value).ok() + base_facts(base, serial, *value?).ok() } /// One window's listed names over `base`, before their kinds and facts. struct MergedNames { @@ -478,12 +489,20 @@ fn merge(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult WorkspaceResult { +/// One window's merged names over `base` with their kinds, and the base +/// values those inherited kinds came from: a reply that shows facts takes them +/// from here, so no inode this listing read is read again. +struct Kinds { + listing: KernelDirectoryListing, + /// Base values of the inherited names, by serial. + values: BTreeMap, +} +/// One window's merged names over `base` with their kinds: a local row answers +/// its own kind, and the window's inherited serials come in one batch inode +/// demand for each level of the inode tree the cache does not already answer. +/// Kinds alone cost no length demand, which belongs to a reply's facts. +fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult { let merged = merge(base, page)?; - // The window's inherited serials come in one batch inode demand for each - // level the cache does not already answer: kinds alone cost no length. let inherited: Vec = merged .names .iter() @@ -492,13 +511,13 @@ fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult>() .into_iter() .collect(); - let found = inode_values(base, &inherited)?; + let values = inode_values(base, &inherited)?; let mut entries = Vec::with_capacity(merged.names.len()); for (name, serial) in merged.names { let kind = match local_row(page, serial) { Some(row) => kind_of(row.kind), None => { - let value = *found.get(&serial).ok_or(ContentError::PathNotFound)?; + let value = *values.get(&serial).ok_or(ContentError::PathNotFound)?; value.kind } }; @@ -509,9 +528,12 @@ fn listing(base: &BaseView, page: &KernelDirectoryPage) -> WorkspaceResult Date: Sat, 14 Nov 2026 09:34:21 +0000 Subject: [PATCH 11/53] docs(kernel-routes): LOOKUP failures answer fresh directory facts The NFS guide still described the retired behaviour: a failed LOOKUP, `.`, `..` and a silly name answered the directory facts the export last published or observed, "trading up to one observation period of staleness". Nothing ages that observation, so there is no such period; the export answered it until it happened to observe the directory again. Now the guide says what the source does: - a LOOKUP that fails answers the directory's own fresh row whenever its job read that row, which every looked-up name does; - `.`, `..`, a silly name and a refusal decided before any visit send no `dir_attributes`, so the client falls back to its own `actimeo`; - no LOOKUP answer repeats the export's last observation; - the remembered directory facts now serve only the AppleDouble companion `wcc_data` and a listed inherited directory's `dir_attributes`; - READDIRPLUS reads names and kinds first and only the sent names' facts. `read.rs` is added to the source list and its LOOKUP row, and the ports guide says a refused LOOKUP carries the directory row its job read. Production LOC: 160864 -> 160864 (delta 0) Scope and method: python3 -B tools/production_loc.py over first-party product Rust/SQL/JavaScript only (reference absent, retired R9c); documentation only. Co-Authored-By: Claude Opus 5 --- docs/architecture/engine/kernel-routes/README.md | 2 +- docs/architecture/engine/kernel-routes/nfs.md | 11 ++++++----- docs/architecture/engine/workspace/operations.md | 1 + 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/README.md b/docs/architecture/engine/kernel-routes/README.md index 6c4bcca997..744bfe1358 100644 --- a/docs/architecture/engine/kernel-routes/README.md +++ b/docs/architecture/engine/kernel-routes/README.md @@ -85,7 +85,7 @@ stops: a stopped mount starts nothing new and still gives back what it holds. | Type or module | Kernel requests | Source | | --- | --- | --- | -| `KernelRead` | LOOKUP, GETATTR, OPEN, OPENDIR; holds nothing after its visits (a LOOKUP also carries the directory it named) | [`lookup.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/lookup.rs) | +| `KernelRead` | LOOKUP, GETATTR, OPEN, OPENDIR; holds nothing after its visits (a LOOKUP also carries the directory it named, and a refused LOOKUP the directory row its own job read) | [`lookup.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/lookup.rs) | | `KernelData` | READ, READLINK | [`read.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/read.rs) | | `KernelMutation` | Every changing request; holds one `Publication` ticket until `replied` | [`mutation.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/mutation.rs) | | `DirectoryStream` | READDIR; only accepted names become valid offsets | [`directory.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/directory.rs) | diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index f9de8542ce..6e49ff3edc 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -14,7 +14,7 @@ and MOUNT are written over `std::net` with no third-party dependency and no platform `cfg` ([`lib.rs`](../../../../engine/crates/layerfs-nfs/src/lib.rs)). The daemon starts it and has the host's own NFS client mount it. -## Server (`server.rs`, `kernel.rs`, `block.rs`) +## Server (`server.rs`, `kernel.rs`, `read.rs`, `block.rs`) ```text host NFS client (mount_nfs on macOS) @@ -120,10 +120,10 @@ drawn once per export; it makes guessing costly and does not authenticate. | --- | --- | | The cookie is the engine's kernel offset on one implicit directory descriptor named by `cookieverf`; a retired offset or a listing continued after an install is `NFS3ERR_BAD_COOKIE`, and the client lists again | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | A READDIRPLUS entry carries the facts its window read — a local inode's current row, or an inherited inode's immutable base stat — and the handle of its serial, so the client needs no LOOKUP per name; both are optional in RFC 1813 and this export sends both for every named entry whose offsets the reply publishes, each handle taking its one lookup reference in the publishing visit (reused offset ranges take none) | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`kernel_cookie.rs`](../../../../engine/crates/layerfs-overlay/src/lifetime/kernel_cookie.rs) | -| A window's inherited inode values cost one batch inode demand for each level of the inode tree the cache does not already answer (`lookup_many` reads a level's pages in one `read_canonical_batch`, resident levels cost none) and its ordinary file lengths one batch length demand (`provide_lengths`) while the cache can remember them (too small for one entry remembers nothing, so each file asks for its own length); entries memory already answers cost no Store reader. Test counts where earlier visits warmed upper levels are not a fresh mount's first window | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | +| A window's inherited inode values cost one batch inode demand for each level of the inode tree the cache does not already answer (`lookup_many` reads a level's pages in one `read_canonical_batch`, resident levels cost none) and its ordinary file lengths one batch length demand (`provide_lengths`) while the cache can remember them (too small for one entry remembers nothing, so each file asks for its own length); entries memory already answers cost no Store reader. Names and kinds come first, the offer then truncates the window to the names the reply publishes, and only those names' facts are read, so a re-sent reply reads nothing for a name it does not send. Test counts where earlier visits warmed upper levels are not a fresh mount's first window | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | | Those batches are not everything an entry costs, and this route changes none of the rest: an inherited inode whose metadata is not inline reports one portable-metadata demand per distinct metadata root, a listed subdirectory one listing of that subdirectory for its child-directory count, and a symlink entry one read of its target; only ordinary files with inline metadata pay only those batches (when the cache remembers lengths) | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`view.rs`](../../../../engine/crates/layerfs-workspace/src/base/view.rs), [`links.rs`](../../../../engine/crates/layerfs-workspace/src/base/links.rs) | | READDIR has one count, which bounds the whole reply; READDIRPLUS sends `dircount` before it, and only `maxcount` bounds this reply | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | -| A reply's `dir_attributes` are the facts of the listed directory this window read, or the ones the export last observed for it (its OPENDIR visit read them), costing no extra read | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | +| A reply's `dir_attributes` are the facts of the listed directory this window read, or — for an inherited directory whose row the window does not hold — the ones the export last observed for it (its OPENDIR visit read them), costing no extra read | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | `.` and `..` carry no attributes; `..` comes from the parent recorded at lookup, create, move or listing | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | Silly names and AppleDouble companions are never listed | [`names.rs`](../../../../engine/crates/layerfs-nfs/src/names.rs), [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | @@ -154,8 +154,9 @@ drawn once per export; it makes guessing costly and does not authenticate. | Rule | Source | | --- | --- | | One owner visit answers a LOOKUP: the job that resolves a name has already read the directory's own row, so the reply's `dir_attributes` cost no second visit | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | -| Deliberate change from this route's base: a LOOKUP that fails (`NFS3ERR_NOENT`), and `.`, `..` and the export's silly names, answer the directory facts this export last published or observed for it (or none when never seen), where they used to make a fresh GETATTR of the parent; RFC 1813 makes those attributes optional, trading up to one observation period of staleness for no second job | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | -| An export remembers the facts it last published for a directory (LOOKUP, GETATTR, OPENDIR) and answers later `dir_attributes` and `wcc_data` from them, so a name-only question costs no read | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | +| A LOOKUP that fails answers the directory's own fresh facts whenever the job that failed read its row, which is every name this export looks up: a name that binds nothing still read its parent's row in the same visit. `.`, `..`, a silly name and a refusal decided before any visit read no directory row and send no `dir_attributes`, so the client falls back to its own `actimeo`; RFC 1813 makes both fields optional. No LOOKUP answer repeats the export's last observation of the directory, which nothing ages | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | +| `read.rs` holds what a read answers: the entry, its directory and its descriptors, and the refusal with its status (`NFS3ERR_STALE` for an engine `Stale`, else `NFS3ERR_IO`) and the directory row the job read | [`read.rs`](../../../../engine/crates/layerfs-nfs/src/read.rs) | +| An export remembers the facts it last published or observed for a directory (LOOKUP, GETATTR, OPENDIR, a publishing change) and answers from them only where no job reads that directory: an AppleDouble companion's `wcc_data`, whose change never touches it, and a listed inherited directory's `dir_attributes` | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | ## Refresh after install (`refresh.rs`, daemon `export.rs`, `invalidate.rs`) diff --git a/docs/architecture/engine/workspace/operations.md b/docs/architecture/engine/workspace/operations.md index 480d5e7a02..5c7e1d8fdc 100644 --- a/docs/architecture/engine/workspace/operations.md +++ b/docs/architecture/engine/workspace/operations.md @@ -167,6 +167,7 @@ job. | --- | --- | --- | | Offset from before the handle was last listed from 0 | `rewound()`: lists nothing | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | | Window of whiteouts only | Empty with a continuation; the request reads the next window | same | +| READDIRPLUS reply | Names and kinds come first (batched per inode-tree level), the reply's offer truncates the window to the names it publishes, and only those names' facts are read outside the owner: a re-sent reply reads nothing for a name it does not send | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | | Names the kernel buffer accepted | Become resume cookies; nothing is held between the two visits or after the reply | same | ## Kernel mutations From e12c5cfda7df94b3660ac030fd4e5b8d2c6dd1fd Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 10:29:15 +0000 Subject: [PATCH 12/53] fix(nfs): a listing answers only the row its own window read MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit READDIR and READDIRPLUS answered an inherited directory's `post_op_attr` from `.or_else(|| kernel.directory_wcc(serial).0)`: `directory_stats`, the facts this export last observed for that directory, which its OPENDIR visit read whenever the descriptor was opened. Nothing ages that entry — it is replaced only when the export observes the directory again — so a directory whose facts moved on after the open was answered as it was then, for as long as the descriptor lived: the client loads those reply attributes, restarts `actimeo` and keeps its listing and name cache. The upstream base has no such fallback; this PR introduced it while changing LOOKUP. A reply's `dir_attributes` are now exactly the row its listing window read: fresh facts from that visit, costing no further read. An inherited directory has no local row, so its window reads none and the reply carries no attributes at all — RFC 1813 makes the field optional — which leaves the client's own `actimeo` in charge instead of restarting it on an observation nothing refreshes. `directory_wcc` now serves the AppleDouble companion `wcc_data` alone, which is all its own comment describes. Tests: `export.rs::an_inherited_directorys_listing_never_answers_a_stale_observation` adds a name to an inherited directory from a second export of the same Workspace after this export's OPENDIR observed it, and requires the first reply's directory attributes to be absent and the continued reply's to be the current facts (nlink 3) and never the pre-change ones (nlink 2); it fails against the previous behaviour, which answered the observed nlink 2. `export.rs::readdirplus_lists_a_directory_with_attributes_and_handles` now expects no `dir_attributes` for its inherited `src`. The NFS guide's directories table says the same, and the remembered-directory-facts row no longer lists a listing as one of their readers. Production LOC: 160864 -> 160863 (delta -1) Scope and method: python3 -B tools/production_loc.py over first-party product Rust/SQL/JavaScript only (reference absent, retired R9c), at the parent tree 2fc186e51 and at this commit's staged tree. The four comment lines and the guide rows are not production code; the net -1 is the removed fallback line. --- docs/architecture/engine/kernel-routes/nfs.md | 4 +- engine/crates/layerfs-nfs/src/directory.rs | 13 +++- engine/crates/layerfs-nfs/tests/export.rs | 75 ++++++++++++++++++- 3 files changed, 82 insertions(+), 10 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 6e49ff3edc..b97660ab33 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -123,7 +123,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | A window's inherited inode values cost one batch inode demand for each level of the inode tree the cache does not already answer (`lookup_many` reads a level's pages in one `read_canonical_batch`, resident levels cost none) and its ordinary file lengths one batch length demand (`provide_lengths`) while the cache can remember them (too small for one entry remembers nothing, so each file asks for its own length); entries memory already answers cost no Store reader. Names and kinds come first, the offer then truncates the window to the names the reply publishes, and only those names' facts are read, so a re-sent reply reads nothing for a name it does not send. Test counts where earlier visits warmed upper levels are not a fresh mount's first window | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`client.rs`](../../../../engine/crates/layerfs-workspace/src/base/client.rs) | | Those batches are not everything an entry costs, and this route changes none of the rest: an inherited inode whose metadata is not inline reports one portable-metadata demand per distinct metadata root, a listed subdirectory one listing of that subdirectory for its child-directory count, and a symlink entry one read of its target; only ordinary files with inline metadata pay only those batches (when the cache remembers lengths) | [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs), [`view.rs`](../../../../engine/crates/layerfs-workspace/src/base/view.rs), [`links.rs`](../../../../engine/crates/layerfs-workspace/src/base/links.rs) | | READDIR has one count, which bounds the whole reply; READDIRPLUS sends `dircount` before it, and only `maxcount` bounds this reply | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | -| A reply's `dir_attributes` are the facts of the listed directory this window read, or — for an inherited directory whose row the window does not hold — the ones the export last observed for it (its OPENDIR visit read them), costing no extra read | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | +| A reply's `dir_attributes` are the facts of the listed directory its window read — a local row, fresh from that visit, costing no extra read. An inherited directory has no local row, so its window reads none and the reply carries no attributes; the client then falls back to its own `actimeo` rather than restarting it on facts nothing refreshes | [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs), [`kernel_directory.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_directory.rs) | | `.` and `..` carry no attributes; `..` comes from the parent recorded at lookup, create, move or listing | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | Silly names and AppleDouble companions are never listed | [`names.rs`](../../../../engine/crates/layerfs-nfs/src/names.rs), [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | @@ -156,7 +156,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | One owner visit answers a LOOKUP: the job that resolves a name has already read the directory's own row, so the reply's `dir_attributes` cost no second visit | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | | A LOOKUP that fails answers the directory's own fresh facts whenever the job that failed read its row, which is every name this export looks up: a name that binds nothing still read its parent's row in the same visit. `.`, `..`, a silly name and a refusal decided before any visit read no directory row and send no `dir_attributes`, so the client falls back to its own `actimeo`; RFC 1813 makes both fields optional. No LOOKUP answer repeats the export's last observation of the directory, which nothing ages | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | | `read.rs` holds what a read answers: the entry, its directory and its descriptors, and the refusal with its status (`NFS3ERR_STALE` for an engine `Stale`, else `NFS3ERR_IO`) and the directory row the job read | [`read.rs`](../../../../engine/crates/layerfs-nfs/src/read.rs) | -| An export remembers the facts it last published or observed for a directory (LOOKUP, GETATTR, OPENDIR, a publishing change) and answers from them only where no job reads that directory: an AppleDouble companion's `wcc_data`, whose change never touches it, and a listed inherited directory's `dir_attributes` | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`directory.rs`](../../../../engine/crates/layerfs-nfs/src/directory.rs) | +| An export remembers the facts it last published or observed for a directory (LOOKUP, GETATTR, OPENDIR, a publishing change) and answers from them only where no job reads that directory: an AppleDouble companion's `wcc_data`, whose change never touches it. A directory listing is not such a place: its reply says only what its own window read | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | ## Refresh after install (`refresh.rs`, daemon `export.rs`, `invalidate.rs`) diff --git a/engine/crates/layerfs-nfs/src/directory.rs b/engine/crates/layerfs-nfs/src/directory.rs index 166757922c..7f7e00fb19 100644 --- a/engine/crates/layerfs-nfs/src/directory.rs +++ b/engine/crates/layerfs-nfs/src/directory.rs @@ -213,10 +213,15 @@ pub fn list(kernel: &Kernel, request: Listing) -> Result, Status> { (at_end, directory) } }; - // An inherited directory has no local row in this window: its attributes - // are the facts this export last observed or published for it (its - // OPENDIR read them), so the reply carries them without a read of its own. - let directory = directory.or_else(|| kernel.directory_wcc(request.serial).0); + // A window that read the listed directory's own row answers it: the + // reply's `post_op_attr` is those fresh facts and no further read. An + // inherited directory has no local row, so its window reads none. + // Answering the facts this export last observed for it instead — what its + // OPENDIR visit read, whenever the descriptor was opened — restarts the + // client's `actimeo` on a snapshot that nothing ages, so a directory + // whose facts moved on since is answered as it was then, for as long as + // the descriptor lives. RFC 1813 makes the field optional, so such a + // reply says nothing and the client falls back to its own timer. finish(entries, directory.as_ref(), handle, eof) } diff --git a/engine/crates/layerfs-nfs/tests/export.rs b/engine/crates/layerfs-nfs/tests/export.rs index 414d4d9b41..2f7fb6181e 100644 --- a/engine/crates/layerfs-nfs/tests/export.rs +++ b/engine/crates/layerfs-nfs/tests/export.rs @@ -118,7 +118,7 @@ fn readdirplus_lists_a_directory_with_attributes_and_handles() { let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, true); let mut client = Client::connect(server.local_addr(), UID, GID); let root = client.mnt("/"); - let (src, src_attr) = client.lookup(&root, b"src").unwrap(); + let (src, _) = client.lookup(&root, b"src").unwrap(); let held = server.held().lookups; // One reply lists the whole directory: the window that lists its last @@ -129,10 +129,12 @@ fn readdirplus_lists_a_directory_with_attributes_and_handles() { .unwrap(); assert_eq!(client.calls - calls, 1, "one READDIRPLUS for the directory"); assert!(eof, "the reply that lists the last name is the end"); + // `src` is inherited from the committed base: the window reads no local + // row of it, so the reply says nothing about the directory rather than + // repeating the facts this export last observed for it. assert_eq!( - directory, - Some(src_attr), - "dir_attributes of the listed directory" + directory, None, + "no dir_attributes for an inherited directory" ); let names: BTreeSet> = entries.iter().map(|entry| entry.name.clone()).collect(); assert_eq!( @@ -251,6 +253,71 @@ fn readdirplus_reports_a_local_directorys_own_rows() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn an_inherited_directorys_listing_never_answers_a_stale_observation() { + let base = temp("inherited"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let first = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut client = Client::connect(first.local_addr(), UID, GID); + let root = client.mnt("/"); + // `many` comes from the committed base: the overlay holds no local row of + // it, so no listing visit reads the directory's own row. + let (many, _) = client.lookup(&root, b"many").unwrap(); + let before = client.getattr(&many).unwrap(); + assert_eq!(before.nlink, 2, "the directory has no child directory"); + + // The first reply lists the two dots only, so the descriptor stays open + // across the change below and the next reply continues this enumeration. + // Its window read no row of `many`, so it carries no attributes of it + // rather than the facts the OPENDIR visit observed. + let (dots, verifier, eof, directory) = client + .readdir_with_directory(&many, 0, 0, 300, true) + .unwrap(); + assert!(!eof, "the enumeration continues after the dots"); + assert_eq!( + directory, None, + "an inherited directory's window reads no row to answer" + ); + let cookie = dots.last().expect("the dots").cookie; + + // A second export of the same Workspace adds a child directory to + // `many`, which this export does not observe: its last observation of the + // directory is now older than the directory's own row, and nothing ages + // it. + let second = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut other = Client::connect(second.local_addr(), UID, GID); + let other_root = other.mnt("/"); + let (target, _) = other.lookup(&other_root, b"many").unwrap(); + other.mkdir(&target, b"child", 0o755).unwrap(); + + // The continued reply says the directory's current facts or nothing at + // all; it never repeats the pre-change observation. + let (_, _, _, directory) = client + .readdir_with_directory(&many, cookie, verifier, 4096, true) + .unwrap(); + let fresh = client.getattr(&many).unwrap(); + assert_eq!(fresh.nlink, 3, "the directory gained a child directory"); + assert_ne!( + directory, + Some(before), + "never the last observation of the directory" + ); + assert!( + directory.is_none() || directory == Some(fresh), + "the current facts or no attributes at all: {directory:?}" + ); + + drop(client); + drop(other); + let released = first.stop(); + second.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_large_directory_keeps_its_names_and_its_references() { let base = temp("large"); From 1810b4e3d7f490ace518ace60104e4612cbbf3cd Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:09:45 +0000 Subject: [PATCH 13/53] refactor(nfs): move Released and Kernel::release into kernel/released.rs (lp73) Relocation only, no behavior change: `Kernel::release`, `Kernel::held`, `retained_count` and the `Released` struct move out of `kernel.rs` into `kernel/released.rs` verbatim, and `pub use released::Released` keeps every existing path working. This is the first commit of the AppleDouble split (LP636): `kernel.rs` would otherwise cross the 999-line ceiling once the companion work lands. No test or documentation change; the moved functions are the same text in a new module. Production LOC: 163505 -> 163511 (delta +6) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 8cfb6e273 (163505) and this tree (163511). The +6 is the new module's own two `use` lines, its `impl Kernel` block and the `mod released;` / `pub use released::Released;` declaration in kernel.rs. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/kernel.rs | 83 +---------------- .../crates/layerfs-nfs/src/kernel/released.rs | 92 +++++++++++++++++++ 2 files changed, 95 insertions(+), 80 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/kernel/released.rs diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index dd03a6ab8f..43e17fda5c 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -56,6 +56,9 @@ use std::{ }, }; +mod released; +pub use released::Released; + /// Implicit file descriptors kept open at once. pub const FILES_HELD: usize = 1024; /// Implicit directory descriptors (enumerations) kept open at once. @@ -776,61 +779,6 @@ impl Kernel { drop(wait(services.close_directory(self.mount, serial, handle))); } } - /// Gives back everything the synthetic kernel holds: descriptors first, - /// then lookup references. Run once, before the engine mount is revoked. - /// Retained mutation failures keep their custody and are only counted. - pub fn release(&self) -> Released { - let table = std::mem::take(&mut *self.table()); - let companions = self.companions_release(); - let released = Released { - companions, - files: table.files.len(), - directories: table.directories.len(), - lookups: table.lookups.len(), - silly: table.silly.len(), - retained: self.retained_count(), - silly_renamed: self.silly_renamed.load(Ordering::Relaxed), - names_refused: self.names_refused.load(Ordering::Relaxed), - names_detached: self.names_detached.load(Ordering::Relaxed), - collected: self.collected.load(Ordering::Relaxed), - resolved: self.resolved.load(Ordering::Relaxed), - unresolved: self.unresolved.load(Ordering::Relaxed), - }; - for (serial, held) in table.files { - self.close_file(serial, held.handle); - } - for (handle, (serial, _)) in table.directories { - self.close_directory(serial, handle); - } - for serial in table.lookups { - self.forget(serial, 1); - } - released - } - fn retained_count(&self) -> usize { - self.retained - .lock() - .unwrap_or_else(|poison| poison.into_inner()) - .len() - } - /// Current holdings, for diagnostics. - pub fn held(&self) -> Released { - let table = self.table(); - Released { - companions: self.companions_held(), - files: table.files.len(), - directories: table.directories.len(), - lookups: table.lookups.len(), - silly: table.silly.len(), - retained: self.retained_count(), - silly_renamed: self.silly_renamed.load(Ordering::Relaxed), - names_refused: self.names_refused.load(Ordering::Relaxed), - names_detached: self.names_detached.load(Ordering::Relaxed), - collected: self.collected.load(Ordering::Relaxed), - resolved: self.resolved.load(Ordering::Relaxed), - unresolved: self.unresolved.load(Ordering::Relaxed), - } - } /// Closes every implicit file descriptor that no silly name needs, so /// nothing the export opened is held across a Commit. Returns how many. pub fn close_files(&self) -> usize { @@ -906,31 +854,6 @@ fn collectable(table: &mut Table, keep: usize) -> Vec { } candidates.into_iter().map(|(_, serial)| serial).collect() } -/// What [`Kernel::release`] gave back. -#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] -pub struct Released { - pub files: usize, - pub directories: usize, - pub lookups: usize, - /// Silly names whose inode was kept alive until release. - pub silly: usize, - /// Failed mutations still holding engine custody. - pub retained: usize, - /// Client silly renames served as unlinks, over the export's life. - pub silly_renamed: u64, - /// Creations refused for their AppleDouble name, over the export's life. - pub names_refused: u64, - /// AppleDouble companions held in memory (see [`crate::apple_double`]). - pub companions: usize, - /// AppleDouble companions created, over the export's life. - pub names_detached: u64, - /// References collected beyond the bound, over the export's life. - pub collected: u64, - /// SqliteHandles of collected serials resolved again by their name. - pub resolved: u64, - /// SqliteHandles of collected serials whose name no longer reaches them. - pub unresolved: u64, -} fn oldest(entries: impl Iterator) -> Option { entries.min_by_key(|(_, tick)| *tick).map(|(key, _)| key) } diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs new file mode 100644 index 0000000000..5259b14be9 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -0,0 +1,92 @@ +//! What the synthetic kernel gives back, counted. +//! +//! [`Kernel::release`] runs once, before the engine mount is revoked; [`Kernel::held`] +//! reports the same counts while the export serves, for diagnostics. +use super::Kernel; +use std::sync::atomic::Ordering; + +impl Kernel { + /// Gives back everything the synthetic kernel holds: descriptors first, + /// then lookup references. Run once, before the engine mount is revoked. + /// Retained mutation failures keep their custody and are only counted. + pub fn release(&self) -> Released { + let table = std::mem::take(&mut *self.table()); + let companions = self.companions_release(); + let released = Released { + companions, + files: table.files.len(), + directories: table.directories.len(), + lookups: table.lookups.len(), + silly: table.silly.len(), + retained: self.retained_count(), + silly_renamed: self.silly_renamed.load(Ordering::Relaxed), + names_refused: self.names_refused.load(Ordering::Relaxed), + names_detached: self.names_detached.load(Ordering::Relaxed), + collected: self.collected.load(Ordering::Relaxed), + resolved: self.resolved.load(Ordering::Relaxed), + unresolved: self.unresolved.load(Ordering::Relaxed), + }; + for (serial, held) in table.files { + self.close_file(serial, held.handle); + } + for (handle, (serial, _)) in table.directories { + self.close_directory(serial, handle); + } + for serial in table.lookups { + self.forget(serial, 1); + } + released + } + + fn retained_count(&self) -> usize { + self.retained + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .len() + } + + /// Current holdings, for diagnostics. + pub fn held(&self) -> Released { + let table = self.table(); + Released { + companions: self.companions_held(), + files: table.files.len(), + directories: table.directories.len(), + lookups: table.lookups.len(), + silly: table.silly.len(), + retained: self.retained_count(), + silly_renamed: self.silly_renamed.load(Ordering::Relaxed), + names_refused: self.names_refused.load(Ordering::Relaxed), + names_detached: self.names_detached.load(Ordering::Relaxed), + collected: self.collected.load(Ordering::Relaxed), + resolved: self.resolved.load(Ordering::Relaxed), + unresolved: self.unresolved.load(Ordering::Relaxed), + } + } +} + +/// What [`Kernel::release`] gave back. +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] +pub struct Released { + pub files: usize, + pub directories: usize, + pub lookups: usize, + /// Silly names whose inode was kept alive until release. + pub silly: usize, + /// Failed mutations still holding engine custody. + pub retained: usize, + /// Client silly renames served as unlinks, over the export's life. + pub silly_renamed: u64, + /// Creations refused for their AppleDouble name, over the export's life. + pub names_refused: u64, + /// AppleDouble companions held in memory (see [`crate::apple_double`]). + pub companions: usize, + /// AppleDouble companions created, over the export's life. + pub names_detached: u64, + /// References collected beyond the bound, over the export's life. + pub collected: u64, + /// SqliteHandles of collected serials resolved again by their name. + pub resolved: u64, + /// SqliteHandles of collected serials whose name no longer reaches them. + pub unresolved: u64, +} From 210d5f8abc8f4909737cd8f6cfcea81c383259fd Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:17:47 +0000 Subject: [PATCH 14/53] feat(nfs): decode the AppleDouble image a macOS client writes (lp73) The client lays a `._` companion out as an AppleDouble v2 image: a header, a FinderInfo entry that runs into an `ATTR` table of extended attributes, and a resource-fork entry at the end. `apple_double_codec` reads those fields (`Image::parse`) and, when the fields encode back to the very bytes the client wrote (`Image::compact`), keeps them as its own record, so no attribute, value or byte the layout carries is dropped, and one attribute's alignment padding survives a shorter name replacing a longer one. `Image::new`/`Image::encode` lay an image out as the client does, which is what makes the round trip exact and what the macOS evidence compares against. Malformed, truncated or differently laid-out images, and a resource fork with data, parse to `None` and are left as the client wrote them. This is the first layer of the AppleDouble split (LP636): the codec alone, with its own unit tests; the companion that holds its decoded form comes next. Tests: new `tests/apple_double_codec.rs`, 6 cases (byte-exact round trip for every value size, many attributes, alignment padding, whole units, a resource fork, and malformed images that must not decode), all pass. Production LOC: 163511 -> 163792 (delta +281) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 1810b4e3d (163511) and this tree (163792). Engine +281 (`apple_double_codec.rs` +280, `lib.rs` +1). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/src/apple_double_codec.rs | 342 ++++++++++++++++++ engine/crates/layerfs-nfs/src/lib.rs | 1 + .../layerfs-nfs/tests/apple_double_codec.rs | 263 ++++++++++++++ 3 files changed, 606 insertions(+) create mode 100644 engine/crates/layerfs-nfs/src/apple_double_codec.rs create mode 100644 engine/crates/layerfs-nfs/tests/apple_double_codec.rs diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs new file mode 100644 index 0000000000..1d01edabf3 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -0,0 +1,342 @@ +//! The AppleDouble image a macOS NFSv3 client writes as `._`, and its +//! decoded form. +//! +//! The client lays an image out as an AppleDouble v2 header with two entries: +//! the FinderInfo, whose entry runs on into an `ATTR` table of extended +//! attributes (each name with its NUL, padded to four bytes, in entry order; +//! the values packed in the same order), and a resource fork at the end of +//! the image. The image length is a whole number of [`IMAGE_UNIT`] bytes, and +//! the bytes the layout leaves unused are zero. +//! +//! [`Image::parse`] reads those fields. [`Image::compact`] additionally +//! requires that [`Image::encode`] gives back the very same bytes, so a +//! companion held as an [`Image`] encodes again to exactly the image its +//! client wrote: no attribute, value or byte the layout carries is dropped. +//! Each attribute entry keeps the alignment padding the client left after its +//! name, because the client does not clear the bytes a shorter name replaced. +//! +//! Anything else - a resource fork with data, still another layout, a +//! half-written image - yields `None` and is stored as the client wrote it. + +use std::fmt; + +const MAGIC: u32 = 0x0005_1607; +const VERSION: u32 = 0x0002_0000; +const FILLER: &[u8; 16] = b"Mac OS X "; +const FINDER_TAG: u32 = 9; +const FORK_TAG: u32 = 2; +/// Bytes of FinderInfo. +pub const FINDER_INFO: usize = 32; +/// The FinderInfo's offset: after the header, the entry count and two entries. +const FINDER_AT: usize = 50; +/// The `ATTR` header: the FinderInfo and two bytes of padding follow the +/// header of the image. +const ATTR_AT: usize = FINDER_AT + FINDER_INFO + 2; +const ATTR_MAGIC: u32 = 0x4154_5452; +/// The first attribute entry, after the 36-byte `ATTR` header. +const ENTRIES_AT: usize = ATTR_AT + 36; +/// An attribute entry before its name: value offset, value length, flags, +/// name length in bytes including the NUL. +const ENTRY_FIXED: usize = 11; +/// The step an image grows by. +pub const IMAGE_UNIT: usize = 4096; +/// The empty resource fork the client writes at the end of an image. +const BLANK_FORK: usize = 286; +const BLANK_FORK_TAG: &[u8] = b"This resource fork intentionally left blank "; +/// Index bytes counted for one decoded image, besides its names and values. +const IMAGE_OVERHEAD: usize = 96; +/// Index bytes counted for one decoded attribute, besides its name and value. +const ATTR_OVERHEAD: usize = 56; + +/// One extended attribute of a decoded image. +#[derive(Clone, Eq, PartialEq)] +pub struct Attribute { + pub name: Vec, + pub value: Vec, + /// The bytes the client left between the name's NUL and the next entry. + pad: [u8; 3], +} +impl Attribute { + /// An attribute the client would write with a cleared pad. + pub fn new(name: &[u8], value: &[u8]) -> Self { + Self { + name: name.to_vec(), + value: value.to_vec(), + pad: [0; 3], + } + } +} +impl fmt::Debug for Attribute { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("Attribute") + .field("name", &String::from_utf8_lossy(&self.name)) + .field("bytes", &self.value.len()) + .field("pad", &self.pad) + .finish() + } +} + +/// The resource-fork entry of an image that has no resource-fork data. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum Fork { + /// A zero-length entry at the end of the image. + None, + /// The client's own empty resource fork, [`BLANK_FORK`] bytes. + Blank, +} +impl Fork { + fn len(self) -> usize { + match self { + Fork::None => 0, + Fork::Blank => BLANK_FORK, + } + } +} + +/// A decoded image: its FinderInfo, tag, extended attributes in entry order +/// and resource-fork entry, at its image length. +#[derive(Clone, Eq, PartialEq)] +pub struct Image { + finder: [u8; FINDER_INFO], + tag: u32, + attrs: Vec, + fork: Fork, + len: usize, +} +impl fmt::Debug for Image { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("Image") + .field("tag", &self.tag) + .field("attrs", &self.attrs) + .field("fork", &self.fork) + .field("len", &self.len) + .finish() + } +} +impl Image { + /// The image a client would write for these attributes from scratch: the + /// smallest whole number of [`IMAGE_UNIT`] bytes with its empty resource + /// fork, and cleared padding. `None` for an empty name, a name holding a + /// NUL, a name an entry cannot describe, or more attributes than an entry + /// count can say. + pub fn new(finder: [u8; FINDER_INFO], tag: u32, attrs: Vec) -> Option { + let named = |name: &Vec| !name.is_empty() && name.len() < 255 && !name.contains(&0); + if attrs.len() > usize::from(u16::MAX) || !attrs.iter().all(|attr| named(&attr.name)) { + return None; + } + let mut image = Self { + finder, + tag, + attrs, + fork: Fork::Blank, + len: 0, + }; + let used = image.data_start() + image.data_len() + BLANK_FORK; + image.len = used.div_ceil(IMAGE_UNIT) * IMAGE_UNIT; + u32::try_from(image.len).ok()?; + Some(image) + } + /// Its FinderInfo. + pub fn finder_info(&self) -> [u8; FINDER_INFO] { + self.finder + } + /// Its attributes. + pub fn attributes(&self) -> &[Attribute] { + &self.attrs + } + /// Its resource-fork entry. + pub fn fork(&self) -> Fork { + self.fork + } + /// The image length the client wrote, in bytes. + pub fn len(&self) -> usize { + self.len + } + /// Whether no image has an empty length; here for `len`'s sake only. + pub fn is_empty(&self) -> bool { + self.len == 0 + } + /// Index bytes this decoded form is counted for. + pub fn cost(&self) -> usize { + IMAGE_OVERHEAD + + self + .attrs + .iter() + .map(|attr| attr.name.len() + attr.value.len() + ATTR_OVERHEAD) + .sum::() + } + fn entry_end(&self, at: usize) -> usize { + ENTRIES_AT + + self + .attrs + .iter() + .take(at) + .map(|attr| entry_len(attr.name.len() + 1)) + .sum::() + } + fn data_start(&self) -> usize { + self.entry_end(self.attrs.len()) + } + fn data_len(&self) -> usize { + self.attrs.iter().map(|attr| attr.value.len()).sum() + } + /// The image these fields describe, as the client lays one out. + pub fn encode(&self) -> Vec { + let mut out = vec![0u8; self.len]; + let fork_at = self.len - self.fork.len(); + let data_start = self.data_start(); + put32(&mut out, 0, MAGIC); + put32(&mut out, 4, VERSION); + out[8..24].copy_from_slice(FILLER); + put16(&mut out, 24, 2); + put32(&mut out, 26, FINDER_TAG); + put32(&mut out, 30, FINDER_AT as u32); + put32(&mut out, 34, (fork_at - FINDER_AT) as u32); + put32(&mut out, 38, FORK_TAG); + put32(&mut out, 42, fork_at as u32); + put32(&mut out, 46, self.fork.len() as u32); + out[FINDER_AT..FINDER_AT + FINDER_INFO].copy_from_slice(&self.finder); + put32(&mut out, ATTR_AT, ATTR_MAGIC); + put32(&mut out, ATTR_AT + 4, self.tag); + put32(&mut out, ATTR_AT + 8, fork_at as u32); + put32(&mut out, ATTR_AT + 12, data_start as u32); + put32(&mut out, ATTR_AT + 16, self.data_len() as u32); + put16(&mut out, ATTR_AT + 34, self.attrs.len() as u16); + let (mut entry, mut value_at) = (ENTRIES_AT, data_start); + for attr in &self.attrs { + put32(&mut out, entry, value_at as u32); + put32(&mut out, entry + 4, attr.value.len() as u32); + out[entry + 10] = (attr.name.len() + 1) as u8; + let name_at = entry + ENTRY_FIXED; + let name_end = name_at + attr.name.len(); + out[name_at..name_end].copy_from_slice(&attr.name); + let next = entry + entry_len(attr.name.len() + 1); + out[name_end + 1..next].copy_from_slice(&attr.pad[..next - name_end - 1]); + out[value_at..value_at + attr.value.len()].copy_from_slice(&attr.value); + entry = next; + value_at += attr.value.len(); + } + if self.fork == Fork::Blank { + out[fork_at..].copy_from_slice(&blank_fork()); + } + out + } + /// The fields of `image`, laid out as the client writes one; [`Self::compact`] + /// also requires that they encode back to the same bytes. + pub fn parse(image: &[u8]) -> Option { + let len = image.len(); + u32::try_from(len).ok()?; + if len < ENTRIES_AT + || get32(image, 0)? != MAGIC + || get32(image, 4)? != VERSION + || image[8..24] != FILLER[..] + || get16(image, 24)? != 2 + || get32(image, 26)? != FINDER_TAG + || get32(image, 30)? as usize != FINDER_AT + || get32(image, 38)? != FORK_TAG + { + return None; + } + let fork = match get32(image, 46)? as usize { + 0 => Fork::None, + BLANK_FORK => Fork::Blank, + _ => return None, + }; + let fork_at = get32(image, 42)? as usize; + if fork_at.checked_add(fork.len())? != len + || fork_at < ENTRIES_AT + || get32(image, 34)? as usize != fork_at - FINDER_AT + || get32(image, ATTR_AT)? != ATTR_MAGIC + || get32(image, ATTR_AT + 8)? as usize != fork_at + { + return None; + } + let tag = get32(image, ATTR_AT + 4)?; + let data_start = get32(image, ATTR_AT + 12)? as usize; + let data_len = get32(image, ATTR_AT + 16)? as usize; + let count = get16(image, ATTR_AT + 34)?; + let (mut entry, mut value_at) = (ENTRIES_AT, data_start); + let mut attrs = Vec::with_capacity(usize::from(count)); + for _ in 0..count { + let value_len = get32(image, entry + 4)? as usize; + let name_len = usize::from(*image.get(entry + 10)?); + let name_at = entry + ENTRY_FIXED; + let name_end = entry + ENTRY_FIXED + name_len; + let name = image.get(name_at..name_end)?; + let (last, name) = name.split_last()?; + if get32(image, entry)? as usize != value_at || *last != 0 || name.is_empty() { + return None; + } + let value = image.get(value_at..value_at.checked_add(value_len)?)?; + let next = entry + entry_len(name_len); + let mut pad = [0u8; 3]; + pad[..next - name_end].copy_from_slice(image.get(name_end..next)?); + attrs.push(Attribute { + name: name.to_vec(), + value: value.to_vec(), + pad, + }); + entry = next; + value_at += value_len; + } + if entry != data_start + || value_at != data_start.checked_add(data_len)? + || value_at > fork_at + { + return None; + } + let mut finder = [0u8; FINDER_INFO]; + finder.copy_from_slice(image.get(FINDER_AT..FINDER_AT + FINDER_INFO)?); + Some(Self { + finder, + tag, + attrs, + fork, + len, + }) + } + /// The decoded form of `image` when it encodes back to exactly `image`. + pub fn compact(image: &[u8]) -> Option { + let decoded = Self::parse(image)?; + (decoded.encode() == image).then_some(decoded) + } +} + +/// An attribute entry's bytes for a name of `name_len` bytes with its NUL, +/// rounded up to four. +fn entry_len(name_len: usize) -> usize { + (ENTRY_FIXED + name_len + 3) & !3 +} +/// The empty resource fork: a resource map with no types, after the tag. +fn blank_fork() -> [u8; BLANK_FORK] { + let mut fork = [0u8; BLANK_FORK]; + for (at, value) in [ + (0, 0x100), + (4, 0x100), + (12, 0x1e), + (256, 0x100), + (260, 0x100), + ] { + put32(&mut fork, at, value); + } + put32(&mut fork, 268, 0x1e); + put16(&mut fork, 280, 0x1c); + put16(&mut fork, 282, 0x1e); + put16(&mut fork, 284, 0xffff); + fork[16..16 + BLANK_FORK_TAG.len()].copy_from_slice(BLANK_FORK_TAG); + fork +} +fn put32(out: &mut [u8], at: usize, value: u32) { + out[at..at + 4].copy_from_slice(&value.to_be_bytes()); +} +fn put16(out: &mut [u8], at: usize, value: u16) { + out[at..at + 2].copy_from_slice(&value.to_be_bytes()); +} +fn get32(bytes: &[u8], at: usize) -> Option { + Some(u32::from_be_bytes(bytes.get(at..at + 4)?.try_into().ok()?)) +} +fn get16(bytes: &[u8], at: usize) -> Option { + Some(u16::from_be_bytes(bytes.get(at..at + 2)?.try_into().ok()?)) +} diff --git a/engine/crates/layerfs-nfs/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index f5cb633717..84154c19c1 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -17,6 +17,7 @@ #![forbid(unsafe_code)] pub mod apple_double; +pub mod apple_double_codec; pub mod attributes; mod block; pub mod change; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs new file mode 100644 index 0000000000..8bbfc57412 --- /dev/null +++ b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs @@ -0,0 +1,263 @@ +//! The AppleDouble image codec on its own: what a macOS client's images +//! decode to, and that a decoded one encodes back to the very same bytes. +use layerfs_nfs::apple_double_codec::{Attribute, Fork, Image, IMAGE_UNIT}; + +const FILLER_AT: usize = 8; +const COUNT_AT: usize = 24; +const FINDER_TAG_AT: usize = 26; +const FINDER_ENTRY_AT: usize = 30; +const FINDER_ENTRY_LEN_AT: usize = 34; +const FORK_TAG_AT: usize = 38; +const FORK_AT: usize = 42; +const FORK_LEN_AT: usize = 46; +const FINDER_AT: usize = 50; +const ATTR_AT: usize = 84; +const ATTR_TAG_AT: usize = ATTR_AT + 4; +const ATTR_FORK_AT: usize = ATTR_AT + 8; +const ATTR_DATA_AT: usize = ATTR_AT + 12; +const ATTR_DATA_LEN_AT: usize = ATTR_AT + 16; +const ATTR_COUNT_AT: usize = ATTR_AT + 34; +const ENTRIES_AT: usize = ATTR_AT + 36; + +fn pattern(seed: u32, length: usize) -> Vec { + (0..length) + .map(|n| (n as u32).wrapping_mul(31).wrapping_add(seed * 97) as u8) + .collect() +} +fn image(finder: [u8; 32], tag: u32, attrs: &[(&[u8], Vec)]) -> Image { + let attrs = attrs + .iter() + .map(|(name, value)| Attribute::new(name, value)) + .collect(); + Image::new(finder, tag, attrs).expect("attributes an entry can describe") +} +fn get32(bytes: &[u8], at: usize) -> u32 { + u32::from_be_bytes(bytes[at..at + 4].try_into().unwrap()) +} +fn put32(bytes: &mut [u8], at: usize, value: u32) { + bytes[at..at + 4].copy_from_slice(&value.to_be_bytes()); +} +fn get16(bytes: &[u8], at: usize) -> u16 { + u16::from_be_bytes(bytes[at..at + 2].try_into().unwrap()) +} +/// The decoded form of `image`, required to encode back to the same bytes. +fn whole(image: &Image) -> Vec { + let bytes = image.encode(); + let decoded = Image::compact(&bytes).expect("a whole image decodes"); + assert_eq!(decoded.encode(), bytes, "decoded form re-encodes the image"); + assert_eq!(decoded.finder_info(), image.finder_info()); + assert_eq!(decoded.fork(), image.fork()); + assert_eq!(decoded.len(), bytes.len()); + bytes +} +/// Where the first attribute entry's name ends: its NUL byte. +fn first_name_end(name_len: usize) -> usize { + ENTRIES_AT + 11 + name_len +} + +#[test] +fn values_of_every_size_round_trip() { + for size in [0, 1, 4096, 64 * 1024, 100 * 1024] { + let value = pattern(3, size); + let name = format!("user.size-{size}"); + let attrs: &[(&[u8], Vec)] = &[(name.as_bytes(), value)]; + let built = image([1; 32], 0, attrs); + let bytes = whole(&built); + assert_eq!( + bytes.len() % IMAGE_UNIT, + 0, + "an image is whole {IMAGE_UNIT}-byte units" + ); + assert!(bytes.len() >= size); + let decoded = Image::compact(&bytes).unwrap(); + assert_eq!(decoded.attributes()[0].value.len(), size); + assert_eq!(&decoded.attributes()[0].value, &attrs[0].1); + assert_eq!(&decoded.attributes()[0].name, &attrs[0].0); + assert!(decoded.cost() >= size); + } +} + +#[test] +fn many_attributes_and_finder_info_round_trip() { + let finder = [9u8; 32]; + let attrs: Vec<(Vec, Vec)> = (0..12) + .map(|n| { + ( + format!("user.attr-{n:02}").into_bytes(), + pattern(n, 7 + 13 * n as usize), + ) + }) + .collect(); + let mut with_std = vec![ + (b"com.apple.provenance".to_vec(), pattern(21, 40)), + (b"com.apple.quarantine".to_vec(), pattern(22, 150)), + (b"com.apple.FinderInfo".to_vec(), finder.to_vec()), + ]; + with_std.extend(attrs); + let borrowed: Vec<(&[u8], Vec)> = with_std + .iter() + .map(|(name, value)| (name.as_slice(), value.clone())) + .collect(); + let built = image(finder, 0x2a2a_2a2a, &borrowed); + let bytes = whole(&built); + let decoded = Image::compact(&bytes).unwrap(); + assert_eq!(decoded.finder_info(), finder); + let names: Vec> = decoded + .attributes() + .iter() + .map(|attr| attr.name.clone()) + .collect(); + let expected: Vec> = with_std.iter().map(|(name, _)| name.clone()).collect(); + assert_eq!(names, expected, "entry order is kept"); + for (attr, (_, value)) in decoded.attributes().iter().zip(&with_std) { + assert_eq!(&attr.value, value); + } +} + +#[test] +fn the_clients_alignment_padding_is_kept() { + // A client that rewrote a shorter name does not clear what the longer one + // left behind: the bytes after the NUL stay, and the image must still + // decode to itself. + let attrs: &[(&[u8], Vec)] = &[ + (b"com.example.k4", pattern(5, 32)), + (b"user.other", pattern(6, 8)), + ]; + let mut bytes = image([2; 32], 0, attrs).encode(); + let name_end = first_name_end(b"com.example.k4".len()); + bytes[name_end + 1] = 0x5c; + bytes[name_end + 2] = 0x00; + let decoded = Image::compact(&bytes).expect("kept padding still decodes"); + assert_eq!( + decoded.encode(), + bytes, + "the padding is part of the decoded image" + ); + // A byte the layout leaves unused is not: such an image stays as written. + let mut foreign = bytes.clone(); + let fork_at = get32(&foreign, FORK_AT) as usize; + let data_len = get32(&foreign, ATTR_DATA_LEN_AT) as usize; + let data_start = get32(&foreign, ATTR_DATA_AT) as usize; + foreign[data_start + data_len..fork_at].fill(0x7f); + assert!( + Image::compact(&foreign).is_none(), + "a byte the decoded form does not keep is not claimed" + ); + assert!( + Image::parse(&foreign).is_some(), + "the fields still parse, only the round trip does not hold" + ); +} + +#[test] +fn a_resource_fork_is_left_as_the_client_wrote_it() { + // The client's own empty fork is part of the layout and decodes. + let built = image([3; 32], 0, &[(b"user.a", pattern(7, 16))]); + let bytes = whole(&built); + assert_eq!(Image::compact(&bytes).unwrap().fork(), Fork::Blank); + // The same entry holding other bytes is a real resource fork: the body is + // kept as written, so no fork byte is lost. + let mut fork_data = bytes.clone(); + fork_data[bytes.len() - 286..].fill(0x5a); + assert!(Image::parse(&fork_data).is_some()); + assert!(Image::compact(&fork_data).is_none()); + // A fork of another length is not the layout this codec describes. + let mut longer = bytes.clone(); + put32(&mut longer, FORK_LEN_AT, 300); + assert!(Image::parse(&longer).is_none()); + // An image with a zero-length fork entry decodes too. + let fork_at = get32(&bytes, FORK_AT) as usize; + let mut bare = bytes[..fork_at].to_vec(); + put32(&mut bare, FORK_LEN_AT, 0); + let decoded = Image::compact(&bare).expect("a fork-free image decodes"); + assert_eq!(decoded.fork(), Fork::None); + assert_eq!(decoded.encode(), bare); +} + +#[test] +fn malformed_images_are_not_decoded() { + let good = image( + [4; 32], + 0, + &[(b"user.a", pattern(8, 32)), (b"user.b", pattern(9, 4))], + ) + .encode(); + let fork_at = get32(&good, FORK_AT) as usize; + let data_start = get32(&good, ATTR_DATA_AT) as usize; + let mut cases: Vec<(&str, Vec)> = vec![ + ("empty", Vec::new()), + ("one byte", vec![0]), + ("a truncated header", good[..ENTRIES_AT - 1].to_vec()), + ("a truncated value", good[..data_start + 4].to_vec()), + ("a truncated image", good[..good.len() - 1].to_vec()), + ("an extended image", [good.clone(), vec![0]].concat()), + ]; + let mut each = |name: &'static str, at: usize, value: u32| { + let mut bytes = good.clone(); + put32(&mut bytes, at, value); + cases.push((name, bytes)); + }; + each("another magic", 0, 0x0005_1608); + each("another version", 4, 0x0003_0000); + each("another entry count", COUNT_AT, 3); + each("another FinderInfo tag", FINDER_TAG_AT, 8); + each("another FinderInfo offset", FINDER_ENTRY_AT, 51); + each("another FinderInfo length", FINDER_ENTRY_LEN_AT, 32); + each("another fork tag", FORK_TAG_AT, 1); + each( + "a fork before the entries", + FORK_AT, + (ENTRIES_AT - 1) as u32, + ); + each("a fork past the image", FORK_AT, (good.len() + 1) as u32); + each("another fork length", FORK_LEN_AT, 285); + each("another ATTR magic", ATTR_AT, 0x4154_5453); + each("another ATTR fork", ATTR_FORK_AT, (fork_at - 1) as u32); + each( + "a data start past the fork", + ATTR_DATA_AT, + (fork_at + 1) as u32, + ); + each("a longer data length", ATTR_DATA_LEN_AT, 1024); + each("another entry count", ATTR_COUNT_AT, 3); + each("another value offset", ENTRIES_AT, (data_start + 1) as u32); + let mut filler = good.clone(); + filler[FILLER_AT..FILLER_AT + 16].copy_from_slice(b"Mac OS "); + cases.push(("another filler", filler)); + let mut unterminated = good.clone(); + *unterminated + .get_mut(first_name_end(b"user.a".len())) + .unwrap() = b'X'; + cases.push(("a name without its NUL", unterminated)); + let mut nameless = good.clone(); + let name_len_at = ENTRIES_AT + 10; + assert_eq!(nameless[name_len_at], (b"user.a".len() + 1) as u8); + nameless[name_len_at] = 1; + cases.push(("an empty name", nameless)); + for (name, bytes) in cases { + assert!( + Image::compact(&bytes).is_none(), + "{name} is not claimed as a whole image" + ); + } +} + +#[test] +fn an_image_the_client_would_write_has_whole_units() { + let built = image([6; 32], 0, &[]); + let bytes = built.encode(); + assert_eq!(bytes.len() % IMAGE_UNIT, 0); + assert_eq!(bytes.len(), IMAGE_UNIT, "the smallest image is one unit"); + assert_eq!(get16(&bytes, COUNT_AT), 2); + assert_eq!(get32(&bytes, ATTR_TAG_AT), 0); + assert_eq!( + get32(&bytes, ATTR_DATA_AT) as usize, + ENTRIES_AT, + "no attribute, no entry" + ); + assert_eq!(bytes[FINDER_AT..FINDER_AT + 32], [6; 32]); + // An image whose FinderInfo the client filled and whose tag is its own. + let tagged = image([7; 32], 0x1234_5678, &[]); + let bytes = whole(&tagged); + assert_eq!(get32(&bytes, ATTR_TAG_AT), 0x1234_5678); +} From fa5dd34b5ff99a48aac38133deeac8573ca8e9e1 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:19:28 +0000 Subject: [PATCH 15/53] feat(nfs): hold a whole AppleDouble image as its own attributes (lp73) A macOS client writes each companion once, in full, and reads it back unchanged. A body is therefore classified whenever a write or a resize leaves it: one that parses back to the very bytes the companion holds (`Image::compact`) and fits `DECODED_ENTRY_BYTES` is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` instead of its image, and every READ synthesizes the same bytes again. Anything else - a resource fork, another layout, a half-written image - is stored as the client wrote it. This replaces `TOTAL_BYTES` with two budgets that say what they bound: `RESIDENT_BYTES` (32 MiB) of written bodies kept in memory, and `DECODED_BYTES` (512 MiB) of decoded ones counted as `Image::cost`. A write or resize that neither decodes nor fits the resident budget answers `NFS3ERR_NOSPC` and leaves the companion exactly as it was; the next layer spills those bodies to disk instead of refusing them. `Released` now reports `companions_decoded` and `companion_decoded_bytes`, and `companions_release`/`companions_held` answer the `Holding` record the counters live in. Second layer of the AppleDouble split (LP636), on top of the codec. Tests: new `tests/apple_double_decode.rs` with the client's own write sequence (a half-written header, the rest, an edit that breaks the image and one that completes it again, truncate below and resize back up), read back byte for byte. Full `layerfs-nfs` suite: 41 passed, 0 failed. Production LOC: 163792 -> 163886 (delta +94) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 210d5f8ab (163792) and this tree (163886). Engine +94. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 249 ++++++++++++++---- .../crates/layerfs-nfs/src/kernel/released.rs | 34 +-- .../layerfs-nfs/tests/apple_double_decode.rs | 142 ++++++++++ 3 files changed, 351 insertions(+), 74 deletions(-) create mode 100644 engine/crates/layerfs-nfs/tests/apple_double_decode.rs diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 4f2e2eb4c8..c96d1c8b6a 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -16,11 +16,19 @@ //! directory it names, so its `wcc_data` answers both halves from the last //! facts the export saw for it (see [`Kernel::directory_wcc`]). //! -//! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] -//! each and [`TOTAL_BYTES`] in all. Beyond the count a creation is refused -//! (`NFS3ERR_ACCES`, as before this module), beyond the bytes a write -//! (`NFS3ERR_FBIG` per file, `NFS3ERR_NOSPC` in all). +//! Whenever a write leaves a companion holding a whole AppleDouble image the +//! client laid out itself (see [`crate::apple_double_codec`]), it is decoded: a +//! small one keeps only its FinderInfo and attributes in memory (at most +//! [`DECODED_BYTES`] in all, each at most [`DECODED_ENTRY_BYTES`]), and every +//! read synthesizes the same bytes again. +//! +//! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] each, +//! [`RESIDENT_BYTES`] of written bodies and [`DECODED_BYTES`] of decoded ones +//! counted as [`Image::cost`]. Beyond the count a creation is refused +//! (`NFS3ERR_ACCES`, as before this module), beyond a file's bytes a write +//! (`NFS3ERR_FBIG`), beyond the resident body budget a write (`NFS3ERR_NOSPC`). use crate::{ + apple_double_codec::Image, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, @@ -41,23 +49,62 @@ pub const SERIALS: u64 = 1 << 62; pub const HELD: usize = 4096; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; -/// Bytes kept over all companions. -pub const TOTAL_BYTES: usize = 64 << 20; +/// Companion payload bytes kept resident in memory before a write is refused. +pub const RESIDENT_BYTES: usize = 32 << 20; +/// Bytes counted for all decoded companions (see [`Image::cost`]). +pub const DECODED_BYTES: usize = 512 << 20; +/// Bytes counted for one decoded companion; a larger whole image keeps its +/// bytes as written. +pub const DECODED_ENTRY_BYTES: usize = 128 << 10; /// Mode of a companion created without one. const MODE: u32 = 0o644; +enum Body { + Resident(Vec), + /// A whole image kept as its FinderInfo and attributes; a read encodes the + /// image again, byte for byte as the client wrote it. + Decoded(Image), +} + struct Companion { + /// The `._` name it was created or last renamed to. named: (u64, Vec), - data: Vec, + len: usize, + body: Body, metadata: PortableMetadata, } +impl Companion { + fn resident_len(&self) -> usize { + match &self.body { + Body::Resident(bytes) => bytes.len(), + Body::Decoded(_) => 0, + } + } + fn decoded_cost(&self) -> usize { + match &self.body { + Body::Decoded(image) => image.cost(), + Body::Resident(_) => 0, + } + } +} + +/// What an export's companion index holds (see [`crate::kernel::Released`]). +#[derive(Clone, Copy, Debug, Default)] +pub(crate) struct Holding { + pub held: usize, + pub decoded: usize, + pub decoded_bytes: usize, +} + /// The companions of one export. #[derive(Default)] pub(crate) struct Companions { next: u64, files: HashMap, names: HashMap<(u64, Vec), u64>, - bytes: usize, + resident_bytes: usize, + decoded: usize, + decoded_bytes: usize, } impl Companions { pub(crate) fn len(&self) -> usize { @@ -69,31 +116,104 @@ impl Companions { kind: InodeKind::RegularFile, metadata: file.metadata, namespace_refs: 1, - logical_len: file.data.len() as u64, + logical_len: file.len as u64, subdirs: 0, } } + /// Adds `file` to the index and to the byte counts. + fn attach(&mut self, serial: u64, file: Companion) { + self.resident_bytes += file.resident_len(); + self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); + self.decoded_bytes += file.decoded_cost(); + self.files.insert(serial, file); + } + /// Takes `serial` out of the index and the counts; its name key stays for + /// the caller to unindex. + fn detach(&mut self, serial: u64) -> Option { + let file = self.files.remove(&serial)?; + self.resident_bytes -= file.resident_len(); + self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); + self.decoded_bytes -= file.decoded_cost(); + Some(file) + } + /// Drops `serial` and its name key. fn drop_serial(&mut self, serial: u64) { - if let Some(file) = self.files.remove(&serial) { + if let Some(file) = self.detach(serial) { self.names.remove(&file.named); - self.bytes -= file.data.len(); } } - /// Resizes `serial` to `size`, within the bounds. - fn resize(&mut self, serial: u64, size: u64) -> Result<(), Status> { - if size > FILE_BYTES { - return Err(Status::FBig); + /// Decides whether `file`'s body is a whole image: one that parses back to + /// the same bytes and that the decoded budget takes. `file` must be + /// detached from the index. + fn classify(&self, file: &mut Companion) { + let Body::Resident(bytes) = &file.body else { + return; + }; + let Some(image) = Image::compact(bytes) else { + return; + }; + let cost = image.cost(); + if cost <= DECODED_ENTRY_BYTES && self.decoded_bytes + cost <= DECODED_BYTES { + file.body = Body::Decoded(image); } - let file = self.files.get_mut(&serial).ok_or(Status::Stale)?; - let old = file.data.len(); - let new = size as usize; - if new > old && self.bytes + (new - old) > TOTAL_BYTES { + } + /// Replaces `serial`'s body by `len` bytes built from it by `apply`, kept + /// within the budgets: a body that decodes costs its attributes, not its + /// bytes, and any other body stays in memory only while [`RESIDENT_BYTES`] + /// takes it. All of it or nothing: a body the budgets cannot take leaves + /// the companion exactly as it was. + fn edit_body( + &mut self, + serial: u64, + len: usize, + apply: impl FnOnce(&mut Vec), + ) -> Result<(), Status> { + let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); + let mut file = self.detach(serial).ok_or(Status::Stale)?; + let need = len.saturating_sub(file.resident_len()); + let before_len = file.len; + let original = std::mem::replace(&mut file.body, Body::Resident(Vec::new())); + let mut bytes = match &original { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + }; + bytes.resize(len, 0); + apply(&mut bytes); + file.body = Body::Resident(bytes); + file.len = len; + self.classify(&mut file); + if need > avail && !matches!(file.body, Body::Decoded(_)) { + // The body does not decode and the resident budget does not take + // it: the companion keeps what it had and the caller answers NOSPC. + file.body = original; + file.len = before_len; + self.attach(serial, file); return Err(Status::NoSpc); } - file.data.resize(new, 0); - self.bytes = self.bytes + new - old; + touch(&mut file.metadata); + self.attach(serial, file); Ok(()) } + /// Applies a write to `serial`'s body; a write keeps what the body held + /// beyond its end. + fn write(&mut self, serial: u64, offset: usize, data: &[u8]) -> Result<(), Status> { + let file = self.files.get(&serial).ok_or(Status::Stale)?; + let len = file.len.max(offset + data.len()); + self.edit_body(serial, len, |bytes| { + bytes[offset..offset + data.len()].copy_from_slice(data); + }) + } + /// Resizes `serial` to `size`, within the bounds. + fn resize(&mut self, serial: u64, size: usize) -> Result<(), Status> { + self.edit_body(serial, size, |_| {}) + } + fn holding(&self) -> Holding { + Holding { + held: self.files.len(), + decoded: self.decoded, + decoded_bytes: self.decoded_bytes, + } + } } fn now() -> PortableMetadata { let elapsed = SystemTime::now() @@ -181,17 +301,15 @@ impl Kernel { let serial = SERIALS + companions.next; companions.next += 1; let named = (parent, name.to_vec()); - companions.names.insert(named.clone(), serial); - companions.files.insert( - serial, - Companion { - named, - data: Vec::new(), - metadata, - }, - ); - let file = &companions.files[&serial]; - let stat = Companions::stat(serial, file); + let file = Companion { + named, + len: 0, + body: Body::Resident(Vec::new()), + metadata, + }; + let stat = Companions::stat(serial, &file); + companions.names.insert(file.named.clone(), serial); + companions.attach(serial, file); drop(companions); self.names_detached.fetch_add(1, Ordering::Relaxed); Ok((stat, directory)) @@ -201,7 +319,7 @@ impl Kernel { pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { { let mut companions = self.companions(); - let serial = companions.names.get(&(parent, name.to_vec())).copied()?; + let serial = *companions.names.get(&(parent, name.to_vec()))?; companions.drop_serial(serial); } Some(self.directory_wcc(parent)) @@ -244,10 +362,23 @@ impl Kernel { ) -> Result { let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let length = file.data.len() as u64; + let length = file.len as u64; let start = offset.min(length) as usize; let end = offset.saturating_add(u64::from(count)).min(length) as usize; - out.extend_from_slice(&file.data[start..end]); + match &file.body { + Body::Resident(bytes) => { + // A body and its length are recorded under one lock; clamp + // anyway so no reply slices past the bytes it holds. + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + } + Body::Decoded(image) => { + // The image the client wrote, synthesized again. + let bytes = image.encode(); + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + } + } Ok(end as u64 >= length) } /// WRITE to a companion: all of it or nothing. @@ -257,18 +388,17 @@ impl Kernel { offset: u64, data: &[u8], ) -> Result<(u32, Wcc), Status> { - let mut companions = self.companions(); let end = offset.checked_add(data.len() as u64).ok_or(Status::FBig)?; + if end > FILE_BYTES { + return Err(Status::FBig); + } + let mut companions = self.companions(); let before = { let file = companions.files.get(&serial).ok_or(Status::Stale)?; Companions::stat(serial, file) }; - if end > before.logical_len { - companions.resize(serial, end)?; - } - let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.data[offset as usize..end as usize].copy_from_slice(data); - touch(&mut file.metadata); + companions.write(serial, offset as usize, data)?; + let file = companions.files.get(&serial).ok_or(Status::Stale)?; let after = Companions::stat(serial, file); Ok((data.len() as u32, (Some(before), Some(after)))) } @@ -287,19 +417,24 @@ impl Kernel { if foreign { return Err(Status::Perm); } - let mut companions = self.companions(); let before = { + let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - Companions::stat(serial, file) - }; - if let Some(expected) = guard { - if crate::attributes::ctime(&before) != expected { - return Err(Status::NotSync); + let before = Companions::stat(serial, file); + if let Some(expected) = guard { + if crate::attributes::ctime(&before) != expected { + return Err(Status::NotSync); + } } - } + before + }; if let Some(size) = sattr.size { - companions.resize(serial, size)?; + if size > FILE_BYTES { + return Err(Status::FBig); + } + self.companions().resize(serial, size as usize)?; } + let mut companions = self.companions(); let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; if let Some(mode) = sattr.mode { file.metadata.mode = mode & 0o777; @@ -316,15 +451,15 @@ impl Kernel { let after = Companions::stat(serial, file); Ok((after.clone(), (Some(before), Some(after)))) } - /// Drops every companion; their count. - pub(crate) fn companions_release(&self) -> usize { + /// Drops every companion; what the index held. + pub(crate) fn companions_release(&self) -> Holding { let mut companions = self.companions(); - let held = companions.len(); + let holding = companions.holding(); *companions = Companions::default(); - held + holding } - /// Companions held now. - pub(crate) fn companions_held(&self) -> usize { - self.companions().len() + /// What the companion index holds now. + pub(crate) fn companions_held(&self) -> Holding { + self.companions().holding() } } diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index 5259b14be9..f765a6177d 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -2,7 +2,7 @@ //! //! [`Kernel::release`] runs once, before the engine mount is revoked; [`Kernel::held`] //! reports the same counts while the export serves, for diagnostics. -use super::Kernel; +use super::{Kernel, Table}; use std::sync::atomic::Ordering; impl Kernel { @@ -12,20 +12,7 @@ impl Kernel { pub fn release(&self) -> Released { let table = std::mem::take(&mut *self.table()); let companions = self.companions_release(); - let released = Released { - companions, - files: table.files.len(), - directories: table.directories.len(), - lookups: table.lookups.len(), - silly: table.silly.len(), - retained: self.retained_count(), - silly_renamed: self.silly_renamed.load(Ordering::Relaxed), - names_refused: self.names_refused.load(Ordering::Relaxed), - names_detached: self.names_detached.load(Ordering::Relaxed), - collected: self.collected.load(Ordering::Relaxed), - resolved: self.resolved.load(Ordering::Relaxed), - unresolved: self.unresolved.load(Ordering::Relaxed), - }; + let released = self.holdings(&table, companions); for (serial, held) in table.files { self.close_file(serial, held.handle); } @@ -48,8 +35,16 @@ impl Kernel { /// Current holdings, for diagnostics. pub fn held(&self) -> Released { let table = self.table(); + let companions = self.companions_held(); + self.holdings(&table, companions) + } + + /// What this export holds now, as [`Released`] reports it. + fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { Released { - companions: self.companions_held(), + companions: companions.held, + companions_decoded: companions.decoded, + companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -79,8 +74,13 @@ pub struct Released { pub silly_renamed: u64, /// Creations refused for their AppleDouble name, over the export's life. pub names_refused: u64, - /// AppleDouble companions held in memory (see [`crate::apple_double`]). + /// AppleDouble companions held in the export's index (see + /// [`crate::apple_double`]). pub companions: usize, + /// Of the companions held, those kept decoded, and the bytes counted for + /// them. + pub companions_decoded: usize, + pub companion_decoded_bytes: usize, /// AppleDouble companions created, over the export's life. pub names_detached: u64, /// References collected beyond the bound, over the export's life. diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs new file mode 100644 index 0000000000..7acd47a903 --- /dev/null +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -0,0 +1,142 @@ +//! AppleDouble companions decoded into their attributes: a `._` a macOS +//! client writes as a whole image is kept as its FinderInfo and extended +//! attributes, and every read synthesizes the very bytes the client wrote. A +//! body that is not a whole image (a resource fork, another layout, a +//! half-written one) is stored as the client wrote it. +#[allow(dead_code)] +#[path = "support/client.rs"] +mod client; +#[allow(dead_code)] +#[path = "support/rig.rs"] +mod rig; +#[allow(dead_code)] +#[path = "support/spy.rs"] +mod spy; +#[allow(dead_code)] +#[path = "support/tree.rs"] +mod tree; +use client::{Client, Set, STALE}; +use layerfs_nfs::apple_double_codec::{Attribute, Image}; +use std::{ + fs, + net::TcpListener, + path::{Path, PathBuf}, + time::Duration, +}; + +const UID: u32 = 501; +const GID: u32 = 20; + +fn temp(label: &str) -> PathBuf { + std::env::temp_dir().join(format!("layerfs-nfs-ad{}-{label}", std::process::id())) +} +fn source(root: &Path) { + fs::create_dir_all(root.join("docs")).unwrap(); + fs::write(root.join("README.md"), b"# fixture\nhello nfs\n").unwrap(); + fs::write(root.join("docs/guide.md"), b"guide\n").unwrap(); +} +fn pattern(seed: u32, length: usize) -> Vec { + (0..length) + .map(|n| (n as u32).wrapping_mul(31).wrapping_add(seed * 97) as u8) + .collect() +} +/// The image a macOS client writes for these attributes. +fn image(finder: [u8; 32], attrs: &[(&[u8], Vec)]) -> Vec { + let attrs = attrs + .iter() + .map(|(name, value)| Attribute::new(name, value)) + .collect(); + Image::new(finder, 0, attrs) + .expect("an entry can describe these attributes") + .encode() +} + +#[test] +fn the_clients_write_sequence_is_served_byte_for_byte() { + let base = temp("sequence"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + let main = c.touch(&root, b"seq", 0o644).unwrap(); + c.write(&main.handle, 0, b"data").unwrap(); + let ad = c.touch(&root, b"._seq", 0o644).unwrap(); + let whole = image( + [0x33; 32], + &[ + (b"com.apple.provenance", pattern(6, 40)), + (b"user.big", pattern(7, 4096)), + ], + ); + // The client writes the header first: a half-written image is served + // exactly as written and never claimed as a whole one. + c.write(&ad.handle, 0, &whole[..50]).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, 50); + assert_eq!(c.read_all(&ad.handle, 4096), whole[..50]); + assert_eq!(server.held().companions_decoded, 0); + // The rest arrives: the image is whole now and reads synthesize it. + c.write(&ad.handle, 50, &whole[50..]).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions_decoded, 1); + + // A delete and rebuild starts empty and decodes the rewrite again. + c.remove(&root, b"._seq").unwrap(); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + let again = c.touch(&root, b"._seq", 0o644).unwrap(); + assert_eq!(again.attr.size, 0); + assert_eq!(c.read_all(&again.handle, 4096), Vec::::new()); + let rebuilt = image( + [0x44; 32], + &[ + (b"com.apple.provenance", pattern(8, 40)), + (b"user.other", pattern(9, 64 * 1024)), + ], + ); + c.write(&again.handle, 0, &rebuilt).unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + + // An edit that leaves the image not whole is served as written, and a + // later edit that completes it decodes again: both are the client's own + // bytes. + let mut edited = rebuilt.clone(); + edited[24..28].copy_from_slice(b"EDIT"); + c.write(&again.handle, 24, b"EDIT").unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), edited); + assert_eq!(server.held().companions_decoded, 0); + c.write(&again.handle, 24, &rebuilt[24..28]).unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + assert_eq!(server.held().companions_decoded, 1); + + // Truncating below the image is served as the client's truncation, and + // resizing back up serves zeros, as on any file. + let shrink = Set { + size: Some(64), + ..Set::default() + }; + c.setattr(&again.handle, shrink, None).unwrap(); + assert_eq!(c.read_all(&again.handle, 4096), rebuilt[..64]); + let grow = Set { + size: Some(rebuilt.len() as u64), + ..Set::default() + }; + c.setattr(&again.handle, grow, None).unwrap(); + let mut zeros = rebuilt[..64].to_vec(); + zeros.resize(rebuilt.len(), 0); + assert_eq!(c.read_all(&again.handle, 128 * 1024), zeros); + c.write(&again.handle, 0, &rebuilt).unwrap(); + assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + + // The companion never reaches the Workspace. + let (entries, _) = c.list(&root, 64 * 1024, true); + assert!(entries.iter().all(|entry| !entry.name.starts_with(b"._"))); + drop(c); + let released = server.stop(); + assert_eq!(released.companions_decoded, 1); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + From 584cc3e66f34f749d82b85b922520f3abc347ff2 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:21:27 +0000 Subject: [PATCH 16/53] docs(nfs): document the decoded AppleDouble companion (lp73) The NFS route guide now names `apple_double_codec.rs` and states what each bound actually holds: `RESIDENT_BYTES` for written bodies and `DECODED_BYTES` / `DECODED_ENTRY_BYTES` for the decoded form, replacing the `TOTAL_BYTES` row the code no longer has. The paragraph after the table says which bodies decode (complete images that encode back to the same bytes) and which stay as written. Documentation only; it describes the codec layer as it stands. Production LOC: 163886 -> 163886 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent fa5dd34b5 (163886) and this tree (163886). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 4c8f4e0325..3b2db39e69 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -163,7 +163,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | The refresh never writes into the Workspace and never reverts a mode the install changed | [`refresh.rs`](../../../../engine/crates/layerfs-nfs/src/refresh.rs) | | `LAYERFS_NFS_REFRESH=0` leaves the client to `actimeo` and close-to-open | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -## AppleDouble files (`apple_double.rs`) +## AppleDouble files (`apple_double.rs`, `apple_double_codec.rs`) On NFSv3 the macOS client keeps extended attributes and resource forks in `._` files. With `refuse_apple_double`, a regular `._` file (at least @@ -174,11 +174,20 @@ never lists it and the engine is never called. Any other kind is `NFS3ERR_ACCES`. `cp`, `copyfile`, `ditto` and `tar` succeed while nothing reaches the Workspace or a Commit; everything is dropped with the export. -| Bound | Value | Over the bound | -| --- | --- | --- | -| `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | -| `FILE_BYTES` | 1 MiB per companion | WRITE `NFS3ERR_FBIG` | -| `TOTAL_BYTES` | 64 MiB in all | WRITE `NFS3ERR_NOSPC` | +| Bound | Value | Over the bound | Source | +| --- | --- | --- | --- | +| `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB resident bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | + +A body a write or resize leaves as a complete AppleDouble image that encodes +back to the exact bytes the companion holds +([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)) +is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` +rather than its image, and every READ synthesizes the same bytes again. Partial +writes, resource forks and other layouts stay as the client wrote them. ## Mount (`mount.rs`, daemon `export.rs`) From 7b38dadc92b37558464e03d31665c7af551d35ee Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:36:30 +0000 Subject: [PATCH 17/53] feat(nfs): spill AppleDouble companion bodies beyond the resident budget (lp73) A client's companion body no longer has to fit in memory and no longer takes memory from every other export. Bodies beyond `RESIDENT_BYTES` (32 MiB) are spilled, least recently touched first, to a scratch directory of the export's own (`/.appledouble//`), and a write that still does not fit the budget after bounded eviction rounds is written out itself and edited in its file, which needs no budget at all. - `apple_double_spill.rs` owns the scratch files: one per companion serial, directory `0700` and files `0600` whatever the umask, written through a `..tmp` that only the adopting call renames to ``, no fsync and no space reserved ahead. A spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open, so companions far outnumbering the process's file limit all work. A failed file operation is answered with the NFS status its errno means (`ENOSPC`/`EDQUOT`, `EFBIG`, `EACCES`, `EPERM`, `EROFS`, else `NFS3ERR_IO`). - `apple_double/edit.rs` holds READ, WRITE and SETATTR and the eviction: one edit of a companion at a time under that companion's own gate, so a truncate and a write can never leave a length its file does not have, and the file I/O never holds the companion lock. - `ExportConfig` gains `companion_spill_dir` and `companion_resident_bytes`. The daemon gives each export `/.appledouble/`, removes it at startup before any Attach, at release and when a failed Attach unwinds, and touches nothing else under the mount home. - `Released` reports `companion_bytes`. Third layer of the AppleDouble split (LP636), on top of the codec; `HELD` and the name index are the layer after this one. Production LOC: 163886 -> 164334 (delta +448) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 584cc3e66 (163886) and this tree (164334). Engine +448, the daemon's `export.rs` share included. Tests for the layer follow in the next commit. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- Cargo.lock | 1 + .../layerfs-daemon/src/control/export.rs | 51 +- engine/crates/layerfs-nfs/Cargo.toml | 1 + engine/crates/layerfs-nfs/src/apple_double.rs | 492 +++++++++--------- .../layerfs-nfs/src/apple_double/edit.rs | 366 +++++++++++++ .../layerfs-nfs/src/apple_double_spill.rs | 151 ++++++ .../crates/layerfs-nfs/src/kernel/released.rs | 3 + engine/crates/layerfs-nfs/src/lib.rs | 1 + engine/crates/layerfs-nfs/src/server.rs | 21 +- 9 files changed, 833 insertions(+), 254 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/apple_double/edit.rs create mode 100644 engine/crates/layerfs-nfs/src/apple_double_spill.rs diff --git a/Cargo.lock b/Cargo.lock index df7846f28a..4a063b0316 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -871,6 +871,7 @@ dependencies = [ "layerfs-storage", "layerfs-telemetry", "layerfs-workspace", + "libc", ] [[package]] diff --git a/engine/crates/layerfs-daemon/src/control/export.rs b/engine/crates/layerfs-daemon/src/control/export.rs index ead80216dd..2128e08893 100644 --- a/engine/crates/layerfs-daemon/src/control/export.rs +++ b/engine/crates/layerfs-daemon/src/control/export.rs @@ -179,27 +179,44 @@ impl ExportServing { fn directory(&self, token: WorkspaceToken) -> PathBuf { self.config.mounts.join(token.namespace.to_string()) } + fn companion_spill_dir(&self, token: WorkspaceToken) -> PathBuf { + self.spill_root().join(token.namespace.to_string()) + } + /// Every companion's scratch directory lives below this one, outside the + /// mount home's mounts. + fn spill_root(&self) -> PathBuf { + self.config.mounts.join(".appledouble") + } /// At startup, before any Attach: every mount the host still has at or /// under the mount home is one a daemon that ended without unmounting /// left (its export is gone, so the client would hang on it). Each is /// forced off once with the force helper; one line per mount says what - /// happened. Nothing is retried. + /// happened. Nothing is retried. The companions' scratch directories of + /// that daemon belong to exports that are gone too, so they go as well; + /// nothing else under the mount home is touched. pub fn reclaim(&self) -> Vec { + let mut lines = Vec::new(); + let spill = self.spill_root(); + if std::fs::remove_dir_all(&spill).is_ok() { + lines.push(format!("removed leftovers under {}", spill.display())); + } let points = match mounted_under(&self.config.mounts) { Ok(points) => points, - Err(error) => return vec![format!("mount table unreadable: {error}")], + Err(error) => { + lines.push(format!("mount table unreadable: {error}")); + return lines; + } }; - (points.into_iter()) - .map(|point| { - let text = point.display().to_string(); - match self.helpers.run(&self.config.mounter.force, 0, &text) { - Ran::Done => format!("forced off {text}"), - Ran::Busy(detail) | Ran::Failed(detail) | Ran::Interrupted(detail) => { - format!("left {text}: {detail}") - } + lines.extend((points.into_iter()).map(|point| { + let text = point.display().to_string(); + match self.helpers.run(&self.config.mounter.force, 0, &text) { + Ran::Done => format!("forced off {text}"), + Ran::Busy(detail) | Ran::Failed(detail) | Ran::Interrupted(detail) => { + format!("left {text}: {detail}") } - }) - .collect() + } + })); + lines } } /// Mount points at or under `home`, deepest first, from the host's table: @@ -481,12 +498,10 @@ impl Service { } }; let export = ExportConfig { - path: "/".into(), - uid: config.command_uid, - gid: config.command_gid, - read_only: false, refuse_apple_double: config.refuse_apple_double, lookups_held: config.lookups_held, + companion_spill_dir: Some(serving.companion_spill_dir(token)), + ..ExportConfig::writable(config.command_uid, config.command_gid) }; let started = TcpListener::bind((config.listen, 0)).and_then(|listener| { Server::start( @@ -531,6 +546,7 @@ impl Service { Ran::Busy(detail) | Ran::Failed(detail) => { let released = server.stop(); drop(std::fs::remove_dir(&directory)); + drop(std::fs::remove_dir(serving.spill_root())); return Err(self.unwind_export( workspace, mount, @@ -751,6 +767,9 @@ impl Service { return Err(Failure::Retained(Box::new(reply))); } drop(std::fs::remove_dir(&ready.directory)); + if let Some(serving) = self.export.as_ref() { + drop(std::fs::remove_dir(serving.spill_root())); + } if let Ok(mut entries) = self.entries.lock() { if let Ok(binding) = bound_mut(&mut entries, token) { binding.kernel = Kernel::Unattached; diff --git a/engine/crates/layerfs-nfs/Cargo.toml b/engine/crates/layerfs-nfs/Cargo.toml index 63bb04f3d1..309e571a94 100644 --- a/engine/crates/layerfs-nfs/Cargo.toml +++ b/engine/crates/layerfs-nfs/Cargo.toml @@ -20,3 +20,4 @@ layerfs-persistence = { path = "../layerfs-persistence" } layerfs-project = { path = "../layerfs-project" } layerfs-storage = { path = "../../../core/crates/layerfs-storage" } layerfs-telemetry = { path = "../../../core/crates/layerfs-telemetry" } +libc = "=0.2.189" diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index c96d1c8b6a..98fe0a665a 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -3,11 +3,11 @@ //! On NFSv3 the macOS client keeps a file's extended attributes and resource //! fork in a `._` companion file (see [`crate::names`]). When the export //! keeps such names out of the Workspace, a CREATE of one makes a file that -//! lives only here, in memory, under its own serial range: LOOKUP, GETATTR, -//! ACCESS, READ, WRITE, SETATTR, COMMIT, REMOVE and a RENAME to another -//! AppleDouble name work on it, READDIR does not list it, and no mutation of -//! it ever reaches the engine, so the Workspace stays clean and no Commit can -//! capture it. Everything is dropped when the export is released. +//! lives only here, under its own serial range: LOOKUP, GETATTR, ACCESS, READ, +//! WRITE, SETATTR, COMMIT, REMOVE and a RENAME to another AppleDouble name +//! work on it, READDIR does not list it, and no mutation of it ever reaches +//! the engine, so the Workspace stays clean and no Commit can capture it. +//! Everything is dropped when the export is released. //! //! The tree is not consulted for such a name: while this mode is on, a //! LOOKUP of a `._` name answers `NFS3ERR_NOENT` unless the export holds that @@ -20,47 +20,58 @@ //! client laid out itself (see [`crate::apple_double_codec`]), it is decoded: a //! small one keeps only its FinderInfo and attributes in memory (at most //! [`DECODED_BYTES`] in all, each at most [`DECODED_ENTRY_BYTES`]), and every -//! read synthesizes the same bytes again. +//! read synthesizes the same bytes again. Any other body (a resource fork, +//! another layout, a half-written image) is kept as the client wrote it. //! //! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] each, //! [`RESIDENT_BYTES`] of written bodies and [`DECODED_BYTES`] of decoded ones -//! counted as [`Image::cost`]. Beyond the count a creation is refused -//! (`NFS3ERR_ACCES`, as before this module), beyond a file's bytes a write -//! (`NFS3ERR_FBIG`), beyond the resident body budget a write (`NFS3ERR_NOSPC`). +//! counted as [`Image::cost`]. Bodies up to that budget stay in memory; when a +//! write or resize crosses it, the least recently touched resident bodies are +//! spilled to the export's own scratch directory (see +//! [`crate::apple_double_spill`]), and a body that still does not fit is +//! written out itself. Everything is dropped when the export is released, +//! which removes that directory too. use crate::{ apple_double_codec::Image, + apple_double_spill::{io_status, now, spill_path, touch, unlink_paths, Edit}, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, }; use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; -use layerfs_mount_ports::operations::write::Stamp; use layerfs_workspace::ViewStat; use std::{ collections::HashMap, - sync::atomic::Ordering, - time::{SystemTime, UNIX_EPOCH}, + fs, + path::{Path, PathBuf}, + sync::{atomic::Ordering, Arc, Mutex}, }; +mod edit; + /// The first serial of the export's own companions, far above any serial the /// engine allocates. pub const SERIALS: u64 = 1 << 62; -/// Companions held at once. +/// Companion index entries held at once. pub const HELD: usize = 4096; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; -/// Companion payload bytes kept resident in memory before a write is refused. +/// Companion payload bytes kept resident in memory before spilling to disk. pub const RESIDENT_BYTES: usize = 32 << 20; /// Bytes counted for all decoded companions (see [`Image::cost`]). pub const DECODED_BYTES: usize = 512 << 20; /// Bytes counted for one decoded companion; a larger whole image keeps its /// bytes as written. pub const DECODED_ENTRY_BYTES: usize = 128 << 10; -/// Mode of a companion created without one. -const MODE: u32 = 0o644; + +/// A name in one directory: (directory serial, name bytes). +type Named = (u64, Vec); enum Body { Resident(Vec), + /// On disk in the spill directory, under the companion's own serial; each + /// operation opens it by path instead of holding it open. + Spilled, /// A whole image kept as its FinderInfo and attributes; a read encodes the /// image again, byte for byte as the client wrote it. Decoded(Image), @@ -68,22 +79,28 @@ enum Body { struct Companion { /// The `._` name it was created or last renamed to. - named: (u64, Vec), + named: Named, len: usize, body: Body, metadata: PortableMetadata, + used: u64, + /// One edit of this companion at a time: its body's bytes, its length and + /// its spilled file change together, so a truncate and a write can never + /// leave a length its file does not have, and no round has to decide + /// again on a body another call changed under it. + editing: Arc>, } impl Companion { fn resident_len(&self) -> usize { match &self.body { Body::Resident(bytes) => bytes.len(), - Body::Decoded(_) => 0, + Body::Spilled | Body::Decoded(_) => 0, } } fn decoded_cost(&self) -> usize { match &self.body { Body::Decoded(image) => image.cost(), - Body::Resident(_) => 0, + Body::Resident(_) | Body::Spilled => 0, } } } @@ -92,23 +109,48 @@ impl Companion { #[derive(Clone, Copy, Debug, Default)] pub(crate) struct Holding { pub held: usize, + pub resident_bytes: usize, pub decoded: usize, pub decoded_bytes: usize, } /// The companions of one export. -#[derive(Default)] pub(crate) struct Companions { next: u64, + tick: u64, files: HashMap, - names: HashMap<(u64, Vec), u64>, + names: HashMap, resident_bytes: usize, decoded: usize, decoded_bytes: usize, + spill_dir: Option, + resident_budget: usize, +} +impl Default for Companions { + fn default() -> Self { + Self { + next: 0, + tick: 0, + files: HashMap::new(), + names: HashMap::new(), + resident_bytes: 0, + decoded: 0, + decoded_bytes: 0, + spill_dir: None, + resident_budget: RESIDENT_BYTES, + } + } } impl Companions { - pub(crate) fn len(&self) -> usize { - self.files.len() + fn tick(&mut self) -> u64 { + self.tick += 1; + self.tick + } + fn use_serial(&mut self, serial: u64) { + let tick = self.tick(); + if let Some(file) = self.files.get_mut(&serial) { + file.used = tick; + } } fn stat(serial: u64, file: &Companion) -> ViewStat { ViewStat { @@ -136,16 +178,39 @@ impl Companions { self.decoded_bytes -= file.decoded_cost(); Some(file) } - /// Drops `serial` and its name key. - fn drop_serial(&mut self, serial: u64) { - if let Some(file) = self.detach(serial) { - self.names.remove(&file.named); + /// Replaces `serial`'s body by the decoded form of `bytes`, the caller's + /// edited body of `len` bytes, when the decoded budget takes it. The + /// decoded form costs its attributes rather than its image, so a body that + /// decodes needs no resident budget at all. + fn keep_decoded(&mut self, serial: u64, bytes: &[u8], len: usize) -> bool { + let Some(image) = Image::compact(bytes) else { + return false; + }; + if image.cost() > DECODED_ENTRY_BYTES { + return false; + } + let cost = image.cost(); + let tick = self.tick(); + let Some(mut file) = self.detach(serial) else { + return false; + }; + if self.decoded_bytes + cost > DECODED_BYTES { + self.attach(serial, file); + return false; } + file.len = len; + file.body = Body::Decoded(image); + file.used = tick; + touch(&mut file.metadata); + self.attach(serial, file); + true } - /// Decides whether `file`'s body is a whole image: one that parses back to - /// the same bytes and that the decoded budget takes. `file` must be - /// detached from the index. + /// Decides whether `file`'s body is a whole image: a resident one is + /// decoded when it parses back to the same bytes and the decoded budget + /// takes it. `file` must be detached from the index. fn classify(&self, file: &mut Companion) { + // A body on disk cannot be decoded here (that reads its file under + // this lock): it keeps the class the write that spilled it left it. let Body::Resident(bytes) = &file.body else { return; }; @@ -157,78 +222,86 @@ impl Companions { file.body = Body::Decoded(image); } } - /// Replaces `serial`'s body by `len` bytes built from it by `apply`, kept - /// within the budgets: a body that decodes costs its attributes, not its - /// bytes, and any other body stays in memory only while [`RESIDENT_BYTES`] - /// takes it. All of it or nothing: a body the budgets cannot take leaves - /// the companion exactly as it was. - fn edit_body( + fn take_serial(&mut self, serial: u64) -> Option { + let file = self.detach(serial)?; + self.names.remove(&file.named); + match file.body { + Body::Resident(_) | Body::Decoded(_) => None, + Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), + } + } + /// Renames the temporary file `temp`, which holds `serial`'s body of `len` + /// bytes, to the companion's own name in the spill directory and switches + /// the companion to it. With `used`, the tick the snapshot was read at, + /// only a companion nothing touched since and whose body is still in memory + /// (resident or decoded) takes it: a body another call changed or already + /// spilled stays, `Ok(false)` then, and `temp` is the caller's to unlink. + /// `None` is an edit's own body written out while it holds the companion's + /// edit gate, so no other edit can have changed it. + fn adopt_spilled( &mut self, serial: u64, + used: Option, + temp: &Path, len: usize, - apply: impl FnOnce(&mut Vec), - ) -> Result<(), Status> { - let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); - let mut file = self.detach(serial).ok_or(Status::Stale)?; - let need = len.saturating_sub(file.resident_len()); - let before_len = file.len; - let original = std::mem::replace(&mut file.body, Body::Resident(Vec::new())); - let mut bytes = match &original { - Body::Resident(bytes) => bytes.clone(), - Body::Decoded(image) => image.encode(), + ) -> Result { + let path = self + .spill_dir + .as_ref() + .map(|dir| spill_path(dir, serial)) + .ok_or(Status::NoSpc)?; + let Some(file) = self.files.get_mut(&serial) else { + return Err(Status::Stale); }; - bytes.resize(len, 0); - apply(&mut bytes); - file.body = Body::Resident(bytes); - file.len = len; - self.classify(&mut file); - if need > avail && !matches!(file.body, Body::Decoded(_)) { - // The body does not decode and the resident budget does not take - // it: the companion keeps what it had and the caller answers NOSPC. - file.body = original; - file.len = before_len; - self.attach(serial, file); - return Err(Status::NoSpc); + if let Some(used) = used { + if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { + return Ok(false); + } } - touch(&mut file.metadata); + fs::rename(temp, path).map_err(|e| io_status(&e))?; + let mut file = self.detach(serial).ok_or(Status::Stale)?; + file.body = Body::Spilled; + // A shorter file than the companion had described is not the body any + // more. + file.len = file.len.max(len); self.attach(serial, file); - Ok(()) + Ok(true) } - /// Applies a write to `serial`'s body; a write keeps what the body held - /// beyond its end. - fn write(&mut self, serial: u64, offset: usize, data: &[u8]) -> Result<(), Status> { - let file = self.files.get(&serial).ok_or(Status::Stale)?; - let len = file.len.max(offset + data.len()); - self.edit_body(serial, len, |bytes| { - bytes[offset..offset + data.len()].copy_from_slice(data); - }) - } - /// Resizes `serial` to `size`, within the bounds. - fn resize(&mut self, serial: u64, size: usize) -> Result<(), Status> { - self.edit_body(serial, size, |_| {}) + fn oldest_resident(&self, skip: Option) -> Option { + self.files + .iter() + .filter(|(serial, file)| { + Some(**serial) != skip + && matches!(file.body, Body::Resident(ref b) if !b.is_empty()) + }) + .min_by_key(|(_, file)| file.used) + .map(|(serial, _)| *serial) } fn holding(&self) -> Holding { Holding { held: self.files.len(), + resident_bytes: self.resident_bytes, decoded: self.decoded, decoded_bytes: self.decoded_bytes, } } } -fn now() -> PortableMetadata { - let elapsed = SystemTime::now() - .duration_since(UNIX_EPOCH) - .unwrap_or_default(); - PortableMetadata { - mode: MODE, - mtime_seconds: i64::try_from(elapsed.as_secs()).unwrap_or(i64::MAX), - mtime_nanoseconds: elapsed.subsec_nanos(), +/// Whether a body a spill wrote out still replaces its companion: only when the +/// companion is the one the snapshot saw (`used` is the tick read then) and its +/// body is still in memory, so no call wrote to it while the file was written. +pub fn spill_applies(used: u64, file_used: u64, resident: bool) -> bool { + used == file_used && resident +} +/// The body length `edit` leaves on a body that had `len` bytes. +fn edited_len(edit: &Edit<'_>, len: usize) -> usize { + match edit { + Edit::Write { .. } => len.max(edit.target_len()), + Edit::Size(size) => *size, } } -fn touch(metadata: &mut PortableMetadata) { - let fresh = now(); - metadata.mtime_seconds = fresh.mtime_seconds; - metadata.mtime_nanoseconds = fresh.mtime_nanoseconds; +/// Records the length `edit` leaves on `file`. +fn record(edit: &Edit<'_>, file: &mut Companion) { + file.len = edited_len(edit, file.len); } /// A serial of the export's own companions. pub fn companion(serial: u64) -> bool { @@ -241,20 +314,57 @@ impl Kernel { .lock() .unwrap_or_else(|poison| poison.into_inner()) } + pub(crate) fn configure_companions(&self, spill_dir: Option, resident_budget: usize) { + if let Some(dir) = &spill_dir { + drop(fs::remove_dir_all(dir)); + } + let mut companions = self.companions(); + companions.spill_dir = spill_dir; + companions.resident_budget = resident_budget; + } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { - let companions = self.companions(); + let mut companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; - Ok(Companions::stat(serial, file)) + let stat = Companions::stat(serial, file); + companions.use_serial(serial); + Ok(stat) } - /// LOOKUP of a companion name, if one is held. + /// LOOKUP of a companion name, if one is held for it. pub(crate) fn companion_named(&self, parent: u64, name: &[u8]) -> Option { - let companions = self.companions(); + let mut companions = self.companions(); let serial = *companions.names.get(&(parent, name.to_vec()))?; - companions - .files - .get(&serial) - .map(|file| Companions::stat(serial, file)) + let stat = Companions::stat(serial, companions.files.get(&serial)?); + companions.use_serial(serial); + Some(stat) + } + /// CREATE of an already-held companion name: UNCHECKED applies its size, + /// as an open with truncation would; GUARDED and EXCLUSIVE find it taken. + fn companion_open( + &self, + serial: u64, + how: How, + directory: Wcc, + mut companions: std::sync::MutexGuard<'_, Companions>, + tickets: &mut Tickets, + ) -> Result<(ViewStat, Wcc), Status> { + let stat = Companions::stat(serial, &companions.files[&serial]); + companions.use_serial(serial); + drop(companions); + let How::Unchecked(sattr) = how else { + return Err(Status::Exist); + }; + match sattr.size { + Some(size) => { + let sized = Sattr { + size: Some(size), + ..Sattr::default() + }; + let (stat, _) = self.companion_setattr(stat.serial, sized, None, tickets)?; + Ok((stat, directory)) + } + None => Ok((stat, directory)), + } } /// CREATE of an AppleDouble name. pub(crate) fn companion_create( @@ -265,29 +375,15 @@ impl Kernel { tickets: &mut Tickets, ) -> Result<(ViewStat, Wcc), Status> { let directory = self.directory_wcc(parent); - if let Some(stat) = self.companion_named(parent, name) { - // Opened again: UNCHECKED applies its size, as an open with - // truncation would; GUARDED and EXCLUSIVE find it taken. - let How::Unchecked(sattr) = how else { - return Err(Status::Exist); - }; - return match sattr.size { - Some(size) => { - let sized = Sattr { - size: Some(size), - ..Sattr::default() - }; - let (stat, _) = self.companion_setattr(stat.serial, sized, None, tickets)?; - Ok((stat, directory)) - } - None => Ok((stat, directory)), - }; - } if parent != self.root() && !self.table().parents.contains_key(&parent) { return Err(Status::NotDir); } + let named = (parent, name.to_vec()); let mut companions = self.companions(); - if companions.len() >= HELD { + if let Some(serial) = companions.names.get(&named).copied() { + return self.companion_open(serial, how, directory, companions, tickets); + } + if companions.files.len() >= HELD { drop(companions); self.names_refused.fetch_add(1, Ordering::Relaxed); return Err(Status::Access); @@ -300,15 +396,17 @@ impl Kernel { } let serial = SERIALS + companions.next; companions.next += 1; - let named = (parent, name.to_vec()); + let used = companions.tick(); let file = Companion { - named, + named: named.clone(), len: 0, body: Body::Resident(Vec::new()), metadata, + used, + editing: Arc::new(Mutex::new(())), }; let stat = Companions::stat(serial, &file); - companions.names.insert(file.named.clone(), serial); + companions.names.insert(named, serial); companions.attach(serial, file); drop(companions); self.names_detached.fetch_add(1, Ordering::Relaxed); @@ -317,15 +415,16 @@ impl Kernel { /// REMOVE of a companion name, with the directory's `wcc_data`; `None` /// when no companion has that name. pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { - { + let spilled = { let mut companions = self.companions(); let serial = *companions.names.get(&(parent, name.to_vec()))?; - companions.drop_serial(serial); - } + companions.take_serial(serial) + }; + unlink_paths(spilled); Some(self.directory_wcc(parent)) } - /// RENAME of a companion name: only to another AppleDouble name, which - /// it replaces when held. `None` when no companion has that name. + /// RENAME of a companion name: only to another AppleDouble name, which it + /// replaces when held. `None` when no companion has that name. pub(crate) fn companion_rename( &self, from: u64, @@ -333,129 +432,52 @@ impl Kernel { to: u64, new_name: &[u8], ) -> Option> { - let mut companions = self.companions(); - let serial = *companions.names.get(&(from, name.to_vec()))?; - if !crate::names::apple_double(new_name) || new_name.len() > 255 { - return Some(Err(Status::Access)); - } - let target = (to, new_name.to_vec()); - if let Some(replaced) = companions.names.get(&target).copied() { - if replaced != serial { - companions.drop_serial(replaced); - } - } - companions.names.remove(&(from, name.to_vec())); - companions.names.insert(target.clone(), serial); - if let Some(file) = companions.files.get_mut(&serial) { - file.named = target; - } - Some(Ok(())) - } - /// READ of a companion, at most `count` bytes from `offset`, appended to - /// `out`; `eof` when the reply reaches the companion's end. - pub(crate) fn companion_read( - &self, - serial: u64, - offset: u64, - count: u32, - out: &mut Vec, - ) -> Result { - let companions = self.companions(); - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let length = file.len as u64; - let start = offset.min(length) as usize; - let end = offset.saturating_add(u64::from(count)).min(length) as usize; - match &file.body { - Body::Resident(bytes) => { - // A body and its length are recorded under one lock; clamp - // anyway so no reply slices past the bytes it holds. - let stop = end.min(bytes.len()); - out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + let mut replaced_path = None; + { + let mut companions = self.companions(); + let serial = *companions.names.get(&(from, name.to_vec()))?; + if !crate::names::apple_double(new_name) || new_name.len() > 255 { + return Some(Err(Status::Access)); } - Body::Decoded(image) => { - // The image the client wrote, synthesized again. - let bytes = image.encode(); - let stop = end.min(bytes.len()); - out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + let target = (to, new_name.to_vec()); + if let Some(replaced) = companions.names.get(&target).copied() { + if replaced != serial { + replaced_path = companions.take_serial(replaced); + } } + let tick = companions.tick(); + let mut file = companions.detach(serial)?; + companions.names.remove(&file.named); + file.named = target.clone(); + file.used = tick; + companions.names.insert(target, serial); + companions.attach(serial, file); } - Ok(end as u64 >= length) - } - /// WRITE to a companion: all of it or nothing. - pub(crate) fn companion_write( - &self, - serial: u64, - offset: u64, - data: &[u8], - ) -> Result<(u32, Wcc), Status> { - let end = offset.checked_add(data.len() as u64).ok_or(Status::FBig)?; - if end > FILE_BYTES { - return Err(Status::FBig); - } - let mut companions = self.companions(); - let before = { - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - Companions::stat(serial, file) - }; - companions.write(serial, offset as usize, data)?; - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let after = Companions::stat(serial, file); - Ok((data.len() as u32, (Some(before), Some(after)))) + unlink_paths(replaced_path); + Some(Ok(())) } - /// SETATTR of a companion: mode, size and modification time; the - /// owner is the export's identity, as for every inode. - pub(crate) fn companion_setattr( - &self, - serial: u64, - sattr: Sattr, - guard: Option<(u32, u32)>, - _tickets: &mut Tickets, - ) -> Result<(ViewStat, Wcc), Status> { - let identity = self.identity(); - let foreign = sattr.uid.is_some_and(|uid| uid != identity.uid) - || sattr.gid.is_some_and(|gid| gid != identity.gid); - if foreign { - return Err(Status::Perm); - } - let before = { - let companions = self.companions(); - let file = companions.files.get(&serial).ok_or(Status::Stale)?; - let before = Companions::stat(serial, file); - if let Some(expected) = guard { - if crate::attributes::ctime(&before) != expected { - return Err(Status::NotSync); - } - } - before + /// Drops every companion and removes the export's spill directory; returns + /// what the index held. + pub(crate) fn companions_release(&self) -> Holding { + let (held, dir) = { + let mut companions = self.companions(); + let dir = companions.spill_dir.take(); + (std::mem::take(&mut *companions), dir) }; - if let Some(size) = sattr.size { - if size > FILE_BYTES { - return Err(Status::FBig); - } - self.companions().resize(serial, size as usize)?; - } - let mut companions = self.companions(); - let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - if let Some(mode) = sattr.mode { - file.metadata.mode = mode & 0o777; + if let Some(dir) = dir { + drop(fs::remove_dir_all(dir)); } - match sattr.mtime { - Some(Stamp::At(time)) => { - file.metadata.mtime_seconds = time.seconds; - file.metadata.mtime_nanoseconds = time.nanoseconds; - } - Some(Stamp::Processing) => touch(&mut file.metadata), - None if sattr.size.is_some() => touch(&mut file.metadata), - None => {} + let holding = held.holding(); + if holding.held > 0 { + eprintln!( + "layerfs-nfs: AppleDouble companions released: export={:?} held={} decoded={} decoded_bytes={} resident_bytes={}", + self.mount(), + holding.held, + holding.decoded, + holding.decoded_bytes, + holding.resident_bytes + ); } - let after = Companions::stat(serial, file); - Ok((after.clone(), (Some(before), Some(after)))) - } - /// Drops every companion; what the index held. - pub(crate) fn companions_release(&self) -> Holding { - let mut companions = self.companions(); - let holding = companions.holding(); - *companions = Companions::default(); holding } /// What the companion index holds now. diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs new file mode 100644 index 0000000000..555ffb1120 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -0,0 +1,366 @@ +//! Companion bodies: READ, WRITE and SETATTR, and the spill that moves a body +//! from memory to the export's scratch directory. +//! +//! One edit of a companion runs at a time, under that companion's own edit +//! gate (`Companion::editing` in the parent module): it applies to the resident +//! bytes under the +//! companion lock or to the spilled file outside it, and records the length +//! its own bytes leave, so a truncate and a write of the same companion can +//! never leave a length its file does not have and no round has to decide +//! again on a body another call changed under it. +//! +//! A body that does not fit the resident budget is spilled first, least +//! recently touched first; the body that still does not fit is written out +//! itself and edited in its file, which needs no budget. The file I/O never +//! holds the companion lock, and no descriptor is kept for a spilled body: +//! each operation opens its file by path and closes it again. +use super::{edited_len, record, Body, Companions, DECODED_ENTRY_BYTES, FILE_BYTES}; +use crate::{ + apple_double_spill::{create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Room}, + attributes::Status, + change::{Sattr, Tickets, Wcc}, + kernel::Kernel, +}; +use layerfs_mount_ports::operations::write::Stamp; +use layerfs_workspace::ViewStat; +use std::{ + fs::{File, OpenOptions}, + io, + os::unix::fs::FileExt, +}; + +/// Rounds one edit takes to make room in the resident budget before it spills +/// its own body instead. Each round either spills the least recently touched +/// body or finds no body to spill; another call's spill can take the room a +/// round just made, which is why a round is retried at all. +const SPILL_ROUNDS: usize = 4; + +impl Kernel { + /// READ of a companion, at most `count` bytes from `offset`, appended to + /// `out`; `eof` when the reply reaches the companion's end. + pub(crate) fn companion_read( + &self, + serial: u64, + offset: u64, + count: u32, + out: &mut Vec, + ) -> Result { + let (spilled, length, start, end) = { + let mut companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let length = file.len as u64; + let start = offset.min(length) as usize; + let end = offset.saturating_add(u64::from(count)).min(length) as usize; + let spilled = match &file.body { + Body::Resident(bytes) => { + // A body and its length are recorded under one lock; clamp + // anyway so no reply slices past the bytes it holds. + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + false + } + Body::Decoded(image) => { + // The image the client wrote, synthesized again. + let bytes = image.encode(); + let stop = end.min(bytes.len()); + out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + false + } + Body::Spilled => true, + }; + companions.use_serial(serial); + (spilled, length, start, end) + }; + if spilled { + let mut buf = vec![0u8; end - start]; + self.spill_file(serial, false)? + .read_exact_at(&mut buf, start as u64) + .map_err(|e| io_status(&e))?; + out.extend_from_slice(&buf); + } + Ok(end as u64 >= length) + } + /// WRITE to a companion: all of it or nothing. + pub(crate) fn companion_write( + &self, + serial: u64, + offset: u64, + data: &[u8], + ) -> Result<(u32, Wcc), Status> { + let end = offset.checked_add(data.len() as u64).ok_or(Status::FBig)?; + if end > FILE_BYTES { + return Err(Status::FBig); + } + let before = self.companion_stat(serial)?; + let after = self.edit_companion( + serial, + Edit::Write { + offset: offset as usize, + data, + }, + )?; + Ok((data.len() as u32, (Some(before), Some(after)))) + } + /// SETATTR of a companion: mode, size and modification time; the + /// owner is the export's identity, as for every inode. + pub(crate) fn companion_setattr( + &self, + serial: u64, + sattr: Sattr, + guard: Option<(u32, u32)>, + _tickets: &mut Tickets, + ) -> Result<(ViewStat, Wcc), Status> { + let identity = self.identity(); + if sattr.uid.is_some_and(|uid| uid != identity.uid) + || sattr.gid.is_some_and(|gid| gid != identity.gid) + { + return Err(Status::Perm); + } + let before = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let before = Companions::stat(serial, file); + if let Some(expected) = guard { + if crate::attributes::ctime(&before) != expected { + return Err(Status::NotSync); + } + } + before + }; + if let Some(size) = sattr.size { + if size > FILE_BYTES { + return Err(Status::FBig); + } + self.edit_companion(serial, Edit::Size(size as usize))?; + } + let mut companions = self.companions(); + let tick = companions.tick(); + let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; + file.used = tick; + if let Some(mode) = sattr.mode { + file.metadata.mode = mode & 0o777; + } + match sattr.mtime { + Some(Stamp::At(time)) => { + file.metadata.mtime_seconds = time.seconds; + file.metadata.mtime_nanoseconds = time.nanoseconds; + } + Some(Stamp::Processing) => touch(&mut file.metadata), + None if sattr.size.is_some() => touch(&mut file.metadata), + None => {} + } + let after = Companions::stat(serial, file); + Ok((after.clone(), (Some(before), Some(after)))) + } + /// Applies `edit` to `serial` and answers its stat afterwards: in the + /// resident body while the budget holds it, else in its spilled file + /// outside the companion lock. This companion's gate makes the edit run + /// alone, so the length recorded is the one its own bytes leave. + fn edit_companion(&self, serial: u64, edit: Edit<'_>) -> Result { + let gate = { + let companions = self.companions(); + companions + .files + .get(&serial) + .ok_or(Status::Stale)? + .editing + .clone() + }; + // Held to the end: no other edit of this companion runs meanwhile. + let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); + let target = edit.target_len(); + for _ in 0..SPILL_ROUNDS { + match self.edit_resident(serial, target, &edit)? { + Room::Resident(stat) => return Ok(stat), + Room::Spilled => break, + Room::Grow(need) => { + // No other call changes this body, so a round that finds + // room leaves the next edit in it. + if !self.spill_for(serial, need)? { + break; + } + } + } + } + // The body still does not fit resident memory: write it out and edit + // its file, which needs no body budget. + self.spill_gated(serial, target)?; + edit.disk(&self.spill_file(serial, true)?)?; + self.record_edit(serial, &edit) + } + /// Applies `edit` to `serial`'s body in memory while the budget holds it + /// (a decoded body is encoded first), recording its length, recency and + /// time and deciding again whether it is a whole image, under the same + /// lock, so no other call ever sees a body and a length that disagree. + fn edit_resident(&self, serial: u64, target: usize, edit: &Edit<'_>) -> Result { + let mut companions = self.companions(); + let avail = companions + .resident_budget + .saturating_sub(companions.resident_bytes); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let need = match &file.body { + Body::Spilled => return Ok(Room::Spilled), + Body::Resident(bytes) => target.saturating_sub(bytes.len()), + Body::Decoded(image) => edited_len(edit, image.len()), + }; + if need > avail { + // The body does not fit the resident budget, but the edit may + // complete a whole image, whose decoded form costs its attributes + // and no body budget. Only a body small enough to decode is tried. + if target > DECODED_ENTRY_BYTES + crate::apple_double_codec::IMAGE_UNIT { + return Ok(Room::Grow(need)); + } + let mut bytes = match &file.body { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + Body::Spilled => return Ok(Room::Spilled), + }; + let len = edited_len(edit, file.len); + edit.memory(&mut bytes); + if companions.keep_decoded(serial, &bytes, len) { + let stat = companions + .files + .get(&serial) + .map(|file| Companions::stat(serial, file)); + if let Some(stat) = stat { + return Ok(Room::Resident(stat)); + } + } + return Ok(Room::Grow(need)); + } + let tick = companions.tick(); + let mut file = companions.detach(serial).ok_or(Status::Stale)?; + let mut bytes = match std::mem::replace(&mut file.body, Body::Spilled) { + Body::Resident(bytes) => bytes, + Body::Decoded(image) => image.encode(), + Body::Spilled => { + companions.attach(serial, file); + return Ok(Room::Spilled); + } + }; + edit.memory(&mut bytes); + file.body = Body::Resident(bytes); + record(edit, &mut file); + touch(&mut file.metadata); + file.used = tick; + companions.classify(&mut file); + let stat = Companions::stat(serial, &file); + companions.attach(serial, file); + Ok(Room::Resident(stat)) + } + /// Records an edit applied to `serial`'s spilled file and answers its + /// stat. + fn record_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { + let mut companions = self.companions(); + let tick = companions.tick(); + let mut file = companions.detach(serial).ok_or(Status::Stale)?; + record(edit, &mut file); + file.used = tick; + touch(&mut file.metadata); + let stat = Companions::stat(serial, &file); + companions.attach(serial, file); + Ok(stat) + } + /// Spills the least recently used resident companions to disk (outside the + /// companion lock) until adding `need` bytes stays within `resident_budget`. + /// Returns `true` if `need` fits in resident memory afterwards. A victim + /// another call changed meanwhile is picked again on the next round; the + /// rounds are bounded by the index, and the caller then writes out its own + /// body, which needs no budget at all. + fn spill_for(&self, target: u64, need: usize) -> Result { + let mut rounds = { + let companions = self.companions(); + if companions.resident_bytes + need <= companions.resident_budget { + return Ok(true); + } + companions.files.len() + }; + while rounds > 0 { + rounds -= 1; + let victim = { + let companions = self.companions(); + if companions.resident_bytes + need <= companions.resident_budget { + return Ok(true); + } + companions.oldest_resident(Some(target)) + }; + let Some(victim) = victim else { + return Ok(false); + }; + // A victim another call changed meanwhile leaves the next round to + // pick again; only a disk failure ends the loop. + let _ = self.spill_one(victim, None)?; + } + Ok(false) + } + /// Writes `serial`'s body out to the spill directory and switches it to + /// that file, keeping at least `keep` bytes (all of them when `None`), + /// with the disk I/O outside the companion lock. `Ok(false)` when another + /// call changed the companion, or already spilled it, while the file was + /// written: that temporary file is dropped and the caller decides again on + /// the body it now finds. + fn spill_one(&self, serial: u64, keep: Option) -> Result { + let (dir, bytes, size, used) = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let bytes = match &file.body { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + Body::Spilled => return Ok(true), + }; + let dir = companions.spill_dir.clone().ok_or(Status::NoSpc)?; + let size = keep.unwrap_or(0).max(bytes.len()); + (dir, bytes, size, file.used) + }; + let temp = create_spilled(&dir, serial, &bytes, size as u64)?; + let adopted = self + .companions() + .adopt_spilled(serial, Some(used), &temp, size); + if matches!(adopted, Ok(true)) { + return Ok(true); + } + unlink_paths([temp]); + adopted.map(|_| false) + } + /// Writes `serial`'s body out while its own edit runs alone, keeping + /// `size` bytes: no other edit can change the body, so the file written is + /// the body this edit then applies to. + fn spill_gated(&self, serial: u64, size: usize) -> Result<(), Status> { + let (dir, bytes, size) = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + let bytes = match &file.body { + Body::Resident(bytes) => bytes.clone(), + Body::Decoded(image) => image.encode(), + Body::Spilled => return Ok(()), + }; + let dir = companions.spill_dir.clone().ok_or(Status::NoSpc)?; + let size = size.max(bytes.len()); + (dir, bytes, size) + }; + let temp = create_spilled(&dir, serial, &bytes, size as u64)?; + let adopted = self.companions().adopt_spilled(serial, None, &temp, size); + if !matches!(adopted, Ok(true)) { + unlink_paths([temp]); + } + adopted.map(|_| ()) + } + /// The spill directory's file of `serial`, opened for one operation and + /// closed again when the returned descriptor drops: the export holds no + /// descriptor per spilled companion. A file or directory that is gone + /// means the companion itself is gone. + fn spill_file(&self, serial: u64, write: bool) -> Result { + let dir = { + let companions = self.companions(); + companions.spill_dir.clone().ok_or(Status::Stale)? + }; + OpenOptions::new() + .read(true) + .write(write) + .open(spill_path(&dir, serial)) + .map_err(|e| match e.kind() { + io::ErrorKind::NotFound => Status::Stale, + _ => io_status(&e), + }) + } +} diff --git a/engine/crates/layerfs-nfs/src/apple_double_spill.rs b/engine/crates/layerfs-nfs/src/apple_double_spill.rs new file mode 100644 index 0000000000..738bcc0268 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double_spill.rs @@ -0,0 +1,151 @@ +//! The export's own scratch files for AppleDouble companion bodies. +//! +//! A companion body beyond the resident budget lives in one file per +//! companion serial under the export's spill directory, read and written with +//! `pread`/`pwrite` by an operation that opens it and closes it again: the +//! export holds no descriptor per spilled body. A spill writes a temporary +//! `..tmp` that only the call adopting it renames to ``, so +//! two calls spilling the same companion never share a file. The directory +//! and its files are this user's alone; the modes are set here rather than +//! left to the caller's umask. +use crate::attributes::Status; +use layerfs_content::filesystem::attributes::PortableMetadata; +use std::{ + fs::{self, File, OpenOptions}, + io, + os::unix::fs::{DirBuilderExt, FileExt, OpenOptionsExt}, + path::{Path, PathBuf}, + sync::atomic::{AtomicU64, Ordering}, + time::{SystemTime, UNIX_EPOCH}, +}; + +/// Mode of a companion created without one. +pub(crate) const MODE: u32 = 0o644; +/// Temporary names tried for one spilled body before the spill gives up. +const SPILL_TEMP_TRIES: u32 = 64; +/// Counter behind the distinct temporary name of each spilled body. +static SPILL_TEMP: AtomicU64 = AtomicU64::new(0); + +/// A failed file operation as the client sees it. +pub(crate) fn io_status(error: &io::Error) -> Status { + match (error.kind(), error.raw_os_error()) { + (io::ErrorKind::StorageFull, _) | (_, Some(28 | 69 | 122)) => Status::NoSpc, + (_, Some(27)) => Status::FBig, + (_, Some(1)) => Status::Perm, + (io::ErrorKind::PermissionDenied, _) | (_, Some(13)) => Status::Access, + (io::ErrorKind::ReadOnlyFilesystem, _) | (_, Some(30)) => Status::RoFs, + _ => Status::Io, + } +} +/// The spill directory's own file of `serial`. +pub(crate) fn spill_path(dir: &Path, serial: u64) -> PathBuf { + dir.join(serial.to_string()) +} +/// Creates `dir` and a temporary file in it holding `bytes` extended to `len` +/// bytes, then closes it: the caller adopts it by renaming it to the +/// companion's own name. +pub(crate) fn create_spilled( + dir: &Path, + serial: u64, + bytes: &[u8], + len: u64, +) -> Result { + let made = fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(dir); + made.map_err(|e| io_status(&e))?; + for _ in 0..SPILL_TEMP_TRIES { + let name = SPILL_TEMP.fetch_add(1, Ordering::Relaxed); + let path = dir.join(format!("{serial}.{name}.tmp")); + let file = match OpenOptions::new() + .read(true) + .write(true) + .create_new(true) + .mode(0o600) + .open(&path) + { + Ok(file) => file, + Err(e) if e.kind() == io::ErrorKind::AlreadyExists => continue, + Err(e) => return Err(io_status(&e)), + }; + let written = (file.write_all_at(bytes, 0)).and_then(|()| file.set_len(len)); + drop(file); + return match written { + Ok(()) => Ok(path), + Err(e) => { + drop(fs::remove_file(&path)); + Err(io_status(&e)) + } + }; + } + Err(Status::Io) +} +/// Unlinks the spilled files a companion operation retired, outside the lock. +pub(crate) fn unlink_paths(paths: impl IntoIterator) { + for path in paths { + drop(fs::remove_file(path)); + } +} +/// The facts of a companion body created now. +pub(crate) fn now() -> PortableMetadata { + let elapsed = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default(); + PortableMetadata { + mode: MODE, + mtime_seconds: i64::try_from(elapsed.as_secs()).unwrap_or(i64::MAX), + mtime_nanoseconds: elapsed.subsec_nanos(), + } +} +/// Records a change of a companion body's time, keeping its mode. +pub(crate) fn touch(metadata: &mut PortableMetadata) { + let mode = metadata.mode; + *metadata = now(); + metadata.mode = mode; +} +/// One change to a companion body, applied to the resident bytes under the +/// lock or to the spilled file outside it. +pub(crate) enum Edit<'a> { + Write { offset: usize, data: &'a [u8] }, + Size(usize), +} +impl Edit<'_> { + /// The body length this edit needs; a write keeps what the body had beyond + /// its end. + pub(crate) fn target_len(&self) -> usize { + match self { + Edit::Write { offset, data } => offset + data.len(), + Edit::Size(size) => *size, + } + } + /// Applies the edit to resident bytes, which already hold `target_len`. + pub(crate) fn memory(&self, bytes: &mut Vec) { + match self { + Edit::Write { offset, data } => { + bytes.resize(bytes.len().max(offset + data.len()), 0); + bytes[*offset..*offset + data.len()].copy_from_slice(data); + } + Edit::Size(size) => bytes.resize(*size, 0), + } + } + /// Applies the edit to a spilled file, outside the companion lock. + pub(crate) fn disk(&self, file: &File) -> Result<(), Status> { + match self { + Edit::Write { offset, data } => { + (file.write_all_at(data, *offset as u64)).map_err(|e| io_status(&e)) + } + Edit::Size(size) => (file.set_len(*size as u64)).map_err(|e| io_status(&e)), + } + } +} +/// Where [`crate::apple_double`] found a companion's body. +pub(crate) enum Room { + /// Applied to the resident body, whose length, recency and time were + /// recorded under the same lock: this is the companion's stat afterwards. + Resident(layerfs_workspace::ViewStat), + /// On disk: finish with its file outside the lock. + Spilled, + /// Resident, but growing it needs this many more budget bytes first. + Grow(usize), +} diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index f765a6177d..3c37d964de 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -43,6 +43,7 @@ impl Kernel { fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { Released { companions: companions.held, + companion_bytes: companions.resident_bytes, companions_decoded: companions.decoded, companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), @@ -77,6 +78,8 @@ pub struct Released { /// AppleDouble companions held in the export's index (see /// [`crate::apple_double`]). pub companions: usize, + /// Companion payload bytes currently resident in memory. + pub companion_bytes: usize, /// Of the companions held, those kept decoded, and the bytes counted for /// them. pub companions_decoded: usize, diff --git a/engine/crates/layerfs-nfs/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index 84154c19c1..ca288a9089 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -18,6 +18,7 @@ pub mod apple_double; pub mod apple_double_codec; +mod apple_double_spill; pub mod attributes; mod block; pub mod change; diff --git a/engine/crates/layerfs-nfs/src/server.rs b/engine/crates/layerfs-nfs/src/server.rs index 798282c7eb..3a3e2b6d65 100644 --- a/engine/crates/layerfs-nfs/src/server.rs +++ b/engine/crates/layerfs-nfs/src/server.rs @@ -43,6 +43,14 @@ pub struct ExportConfig { /// Lookup references kept before the least recently used are collected /// (see [`crate::kernel`]); [`crate::kernel::LOOKUPS_HELD`] by default. pub lookups_held: usize, + /// Scratch directory where AppleDouble companion bodies spill when resident + /// bytes exceed [`Self::companion_resident_bytes`]. Removed when set and + /// when the export releases. + pub companion_spill_dir: Option, + /// Resident memory budget for AppleDouble companion bodies before spilling + /// to [`Self::companion_spill_dir`]; [`crate::apple_double::RESIDENT_BYTES`] + /// by default. + pub companion_resident_bytes: usize, } impl ExportConfig { /// A writable export of "/" shown as `uid`:`gid`, refusing AppleDouble @@ -55,6 +63,8 @@ impl ExportConfig { read_only: false, refuse_apple_double: true, lookups_held: crate::kernel::LOOKUPS_HELD, + companion_spill_dir: None, + companion_resident_bytes: crate::apple_double::RESIDENT_BYTES, } } } @@ -137,10 +147,15 @@ impl Server { config: ExportConfig, ) -> io::Result { let address = listener.local_addr()?; + let kernel = Kernel::new(services, mount, config.uid, config.gid) + .refusing_apple_double(config.refuse_apple_double) + .holding(config.lookups_held); + kernel.configure_companions( + config.companion_spill_dir.clone(), + config.companion_resident_bytes, + ); let shared = Arc::new(Shared { - kernel: Kernel::new(services, mount, config.uid, config.gid) - .refusing_apple_double(config.refuse_apple_double) - .holding(config.lookups_held), + kernel, verifier: fresh_verifier(), config, counters: Counters::default(), From 91434f93e7d4d74539159402121a85beb508a204 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:38:06 +0000 Subject: [PATCH 18/53] test(nfs): cover the companion spill, its files and its cleanup (lp73) The rig can now set the resident budget and an explicit spill directory, and the cases exercise the layer end to end: - a body smaller than the budget stays resident and a larger one spills; the spilled file carries the bytes and the length the client wrote; - an edit that leaves a decoded image not whole spills it instead of growing memory, while a truncate of a decoded body needs no room at all; - a spill only replaces a companion no other call changed meanwhile (`spill_applies`); - a truncate and a write of one spilled companion start together, round after round, and the length a reply reports is always the length its file holds; - companions four times the process's own `RLIMIT_NOFILE` all read and write, because a spilled body is opened by path per operation: that case lowers a process-wide limit and counts the process's descriptors, so it re-runs itself in its own process (`run_alone`); - Attach cleans a leftover `.appledouble` of a daemon that died, release and unmount remove it, and startup reclamation removes it while keeping every other entry under the mount home. `libc` is a new dev-dependency of `layerfs-nfs`, only for the file-limit case. Tests: `cargo test -p layerfs-nfs` 46 passed, 0 failed (the raw sum reads 47 because the file-limit case runs itself once in a child process). Production LOC: 164334 -> 164334 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 7b38dadc9 (164334) and this tree (164334). Tests only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/tests/apple_double_decode.rs | 74 ++++++ engine/crates/layerfs-nfs/tests/daemon.rs | 47 ++++ .../crates/layerfs-nfs/tests/support/rig.rs | 15 ++ engine/crates/layerfs-nfs/tests/write.rs | 237 ++++++++++++++++++ 4 files changed, 373 insertions(+) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 7acd47a903..28f95320ba 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -140,3 +140,77 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_decoded_companion_is_edited_under_a_full_resident_budget() { + let base = temp("decoded-budget"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // A body budget smaller than one encoded image: an edit that leaves the + // image not whole has to spill rather than grow memory. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + let main = c.touch(&root, b"full", 0o644).unwrap(); + c.write(&main.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._full", 0o644).unwrap(); + let whole = image( + [0x77; 32], + &[ + (b"com.apple.provenance", pattern(30, 40)), + (b"user.big", pattern(31, 4096)), + ], + ); + // Another companion's body stays in memory; truncating a decoded body needs + // no room for its image, so that body must not be evicted for it. + c.touch(&root, b"other", 0o644).unwrap(); + let other = c.touch(&root, b"._other", 0o644).unwrap(); + c.write(&other.handle, 0, &pattern(35, 100)).unwrap(); + assert_eq!(server.held().companion_bytes, 100); + + // A whole image costs its attributes, not its bytes: it is decoded. + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions_decoded, 1); + + // Truncating a decoded body to nothing is the client's truncation, with no + // resident room for its image, and a rewrite decodes again. + let empty = Set { + size: Some(0), + ..Set::default() + }; + c.setattr(&ad.handle, empty, None).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, 0); + assert_eq!(c.read_all(&ad.handle, 4096), Vec::::new()); + assert_eq!(server.held().companions_decoded, 0); + assert_eq!( + server.held().companion_bytes, + 100, + "the image was never resident, so nothing had to be evicted for it" + ); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions_decoded, 1); + + // An edit that leaves the image not whole cannot grow memory: the decoded + // body is spilled and the write applied to its file, not refused. + let mut edited = whole.clone(); + edited[24..28].copy_from_slice(b"EDIT"); + c.write(&ad.handle, 24, b"EDIT").unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), edited); + assert_eq!(server.held().companions_decoded, 0); + + // Truncating the spilled body is the client's truncation. + c.setattr(&ad.handle, empty, None).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, 0); + assert_eq!(c.read_all(&ad.handle, 4096), Vec::::new()); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + diff --git a/engine/crates/layerfs-nfs/tests/daemon.rs b/engine/crates/layerfs-nfs/tests/daemon.rs index eacaf9e35b..2d831256bb 100644 --- a/engine/crates/layerfs-nfs/tests/daemon.rs +++ b/engine/crates/layerfs-nfs/tests/daemon.rs @@ -136,8 +136,18 @@ fn workspace_control_over_the_nfs_route() { // Mount + Attach: Ready with an NFS receipt; the helper mounted it. let token = bind(&service, 31, rig.branch); + let spill_dir = mounts + .join(".appledouble") + .join(token.namespace.to_string()); + fs::create_dir_all(&spill_dir).unwrap(); + let stale_spill = spill_dir.join("stale-from-crashed-daemon"); + fs::write(&stale_spill, b"stale").unwrap(); assert_eq!(phase(&service, token), MountPhase::Unattached); let ready = attach(&service, token); + assert!( + !stale_spill.exists(), + "Attach cleans any leftover companion spill directory" + ); assert_eq!(ready.receipt.abi_major, 0); assert_eq!( ready.directory, @@ -242,6 +252,7 @@ fn workspace_control_over_the_nfs_route() { Reply::Unmounted(token) ); assert!(!Path::new(&ready.directory).exists()); + assert!(!spill_dir.exists()); let released = service.export_released(token).unwrap(); assert_eq!(released.lookups, held.lookups); assert_eq!(released.retained, 0); @@ -290,3 +301,39 @@ fn workspace_control_over_the_nfs_route() { } fs::remove_file(&log).unwrap(); } + +/// A daemon that ended without unmounting leaves the companions' scratch +/// directories behind. Its successor clears them before serving anything, and +/// touches nothing else under the mount home. +#[test] +fn startup_reclaim_clears_leftover_companion_spill_directories() { + let mounts = temp("reclaim-mounts"); + let log = temp("reclaim-helpers.log"); + drop(fs::remove_dir_all(&mounts)); + drop(fs::remove_file(&log)); + fs::create_dir_all(mounts.join(".appledouble/7")).unwrap(); + fs::write(mounts.join(".appledouble/7/stale"), b"stale").unwrap(); + fs::create_dir_all(mounts.join("kept")).unwrap(); + fs::write(mounts.join("kept/note"), b"keep").unwrap(); + let export = ExportServing::start(ExportServingConfig::new( + mounts.clone(), + UID, + GID, + Mounter { + mount: recording("mount", &log, None), + unmount: recording("unmount", &log, None), + force: recording("force", &log, None), + flush: None, + }, + )); + let lines = export.reclaim(); + assert_eq!(lines.len(), 1, "{lines:?}"); + assert!( + lines[0].starts_with("removed leftovers under "), + "{lines:?}" + ); + assert!(!mounts.join(".appledouble").exists()); + assert_eq!(fs::read(mounts.join("kept/note")).unwrap(), b"keep"); + drop(fs::remove_dir_all(&mounts)); + drop(fs::remove_file(&log)); +} diff --git a/engine/crates/layerfs-nfs/tests/support/rig.rs b/engine/crates/layerfs-nfs/tests/support/rig.rs index f30ad75e95..612b9a2a2f 100644 --- a/engine/crates/layerfs-nfs/tests/support/rig.rs +++ b/engine/crates/layerfs-nfs/tests/support/rig.rs @@ -40,6 +40,10 @@ pub struct Rig { pub entries: u64, /// The reference bound exports of this rig are configured with. pub lookups_held: usize, + /// Resident memory budget for AppleDouble companion bodies. + pub companion_resident_bytes: usize, + /// Optional explicit spill directory override for AppleDouble companions. + pub companion_spill_dir: Option, } impl Rig { /// Initializes a Store from `source`, publishes Branch `main` at that @@ -142,8 +146,15 @@ impl Rig { branch, entries: initialized.entries, lookups_held: layerfs_nfs::kernel::LOOKUPS_HELD, + companion_resident_bytes: layerfs_nfs::apple_double::RESIDENT_BYTES, + companion_spill_dir: None, } } + fn spill_dir(&self, sub: &str) -> PathBuf { + self.companion_spill_dir + .clone() + .unwrap_or_else(|| self.directory.join("tmp").join("appledouble").join(sub)) + } /// Serves this rig's engine mount read-only on `listener`. pub fn serve(&self, listener: TcpListener, uid: u32, gid: u32) -> Server { self.export(listener, uid, gid, true) @@ -179,6 +190,8 @@ impl Rig { read_only, refuse_apple_double: true, lookups_held: self.lookups_held, + companion_spill_dir: Some(self.spill_dir("export")), + companion_resident_bytes: self.companion_resident_bytes, }, ) .unwrap() @@ -247,6 +260,8 @@ impl Rig { read_only: true, refuse_apple_double: true, lookups_held: self.lookups_held, + companion_spill_dir: Some(self.spill_dir(&format!("view-{}", view.1.owner_id()))), + companion_resident_bytes: self.companion_resident_bytes, }, ) .unwrap() diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index a6c94d0f74..0a5a9e596e 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -57,6 +57,15 @@ fn pattern(seed: u32, length: usize) -> Vec { .collect() } +/// The files an export spilled into `dir`, and their bytes. +fn spilled(dir: &Path) -> (usize, u64) { + let files: Vec = (fs::read_dir(dir).into_iter().flatten().flatten()) + .filter_map(|entry| entry.metadata().ok()) + .map(|metadata| metadata.len()) + .collect(); + (files.len(), files.iter().sum()) +} + #[test] fn every_changing_procedure_and_its_statuses() { let base = temp("procedures"); @@ -531,6 +540,234 @@ fn apple_double_files_stay_out_of_the_workspace() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_spill_replaces_a_companion_body_only_when_no_call_changed_it() { + use layerfs_nfs::apple_double::spill_applies; + // The companion the body was written from, still resident and untouched: + // the spilled file replaces it. + assert!(spill_applies(7, 7, true)); + // Another call wrote to the companion while its body was being written out: + // that newer body stays and the file just written is dropped. + assert!(!spill_applies(7, 8, true)); + // Another call spilled the body first: its file stays. + assert!(!spill_applies(7, 7, false)); +} + +/// The process's soft and hard `RLIMIT_NOFILE`. +fn nofile_limits() -> (libc::rlim_t, libc::rlim_t) { + let mut limit = libc::rlimit { + rlim_cur: 0, + rlim_max: 0, + }; + // SAFETY: `getrlimit` only fills the limit structure it is given. + let asked = unsafe { libc::getrlimit(libc::RLIMIT_NOFILE, &mut limit) }; + assert_eq!(asked, 0, "RLIMIT_NOFILE is readable"); + (limit.rlim_cur, limit.rlim_max) +} + +/// Sets the process's soft `RLIMIT_NOFILE`, leaving the hard limit alone. +fn set_nofile_soft(soft: libc::rlim_t) { + let (_, hard) = nofile_limits(); + let limit = libc::rlimit { + rlim_cur: soft, + rlim_max: hard, + }; + // SAFETY: a soft limit at or below the hard limit is always allowed. + let set = unsafe { libc::setrlimit(libc::RLIMIT_NOFILE, &limit) }; + assert_eq!(set, 0, "soft RLIMIT_NOFILE is settable"); +} + +/// Puts the process's soft `RLIMIT_NOFILE` back when it drops, `panic` included. +struct SoftNofile(libc::rlim_t); +impl SoftNofile { + fn lower(soft: libc::rlim_t) -> Self { + let (was, _) = nofile_limits(); + set_nofile_soft(soft); + Self(was) + } +} +impl Drop for SoftNofile { + fn drop(&mut self) { + set_nofile_soft(self.0); + } +} + +/// The descriptors this process holds, counted from the kernel's own view. +fn open_fds() -> Option { + ["/dev/fd", "/proc/self/fd"] + .into_iter() + .find_map(|dir| fs::read_dir(dir).ok()) + .map(|entries| entries.flatten().count()) +} + +#[test] +fn a_spilled_companion_keeps_its_length_and_bytes_together() { + let base = temp("appledouble-spilled-race"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill-race")); + // Smaller than the body below, which therefore lives on disk. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let mut other = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let name = b"._raced".as_slice(); + let made = c.touch(&root, b"raced", 0o644).unwrap(); + let ad = c.touch(&root, name, 0o644).unwrap(); + let payload = pattern(29, 2048); + c.write(&ad.handle, 0, &payload).unwrap(); + assert_eq!(made.handle, c.lookup(&root, b"raced").unwrap().0); + assert_eq!(server.held().companion_bytes, 0, "the body spilled"); + + // A truncate and a write of this companion start together, round after + // round: each runs to completion under the companion's own gate, so the + // length a reply reports is always the length its file holds, and a read + // never asks for bytes the file does not have (NFS3ERR_IO). + for round in 0..64 { + let start = std::sync::Barrier::new(2); + let empty = Set { + size: Some(0), + ..Set::default() + }; + let (a, b) = std::thread::scope(|scope| { + let a = scope.spawn(|| { + start.wait(); + c.setattr(&ad.handle, empty, None) + }); + let b = scope.spawn(|| { + start.wait(); + other.write(&ad.handle, 0, &payload) + }); + (a.join().unwrap(), b.join().unwrap()) + }); + a.unwrap(); + b.unwrap(); + let size = c.getattr(&ad.handle).unwrap().size as usize; + assert!( + size == 0 || size == payload.len(), + "round {round}: length {size} of a truncate or a write" + ); + assert_eq!( + c.read_all(&ad.handle, 4096).len(), + size, + "round {round}: the bytes served match the length" + ); + } + + drop((c, other)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +/// Set in the child process [`run_alone`] starts, so it runs the body of the one +/// test it was started for. +const FD_LIMIT_CHILD: &str = "LAYERFS_NFS_FD_LIMIT_CHILD"; + +/// Re-runs one test of this binary in its own process, so a change of +/// process-wide state (a soft `RLIMIT_NOFILE`, the descriptors this process +/// holds) can neither reach nor be reached by the tests running in parallel in +/// this one. `name` is selected with `--exact`, so exactly that test runs. +fn run_alone(marker: &str, name: &str) { + let exe = std::env::current_exe().expect("the test binary's own path"); + let status = std::process::Command::new(exe) + .arg("--exact") + .arg(name) + .arg("--test-threads=1") + .env(marker, "1") + .status() + .expect("the test binary starts again"); + assert!(status.success(), "{name} failed in its own process"); +} + +/// The export opens a spilled body by path for one operation and closes it +/// again, so companions far outnumbering the process's own file limit all +/// read and write: a descriptor per spilled body would end in `EMFILE` here. +#[test] +fn spilled_companions_outnumber_the_open_file_limit() { + // The soft limit is process-wide and the descriptor count is the whole + // process's: both are set and asserted in a process running this test + // alone, never next to the tests this binary runs in parallel. + if std::env::var_os(FD_LIMIT_CHILD).is_none() { + run_alone( + FD_LIMIT_CHILD, + "spilled_companions_outnumber_the_open_file_limit", + ); + return; + } + let base = temp("appledouble-fd"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let spill_dir = base.join("spill-fd"); + rig.companion_spill_dir = Some(spill_dir.clone()); + rig.companion_resident_bytes = 1024; + let budget = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // Four times as many companions as the process may hold open at once. + // This process runs no other test: the limit and the count are its own. + let (soft, hard) = nofile_limits(); + let limit = soft.min(hard).min(512); + let count = limit as usize * 4; + let payload = pattern(29, 600); + let mut handles = Vec::with_capacity(count); + { + let _restored = SoftNofile::lower(limit); + assert_eq!(nofile_limits().0, limit); + for i in 0..count { + let name = format!("._fd-{i}"); + let made = c.touch(&root, name.as_bytes(), 0o644).unwrap(); + c.write(&made.handle, 0, &payload).unwrap(); + handles.push((made.handle, made.attr.fileid)); + } + assert!(server.held().companion_bytes <= budget); + let (on_disk, _) = spilled(&spill_dir); + assert_eq!(on_disk, count - 1, "all but the newest body spilled"); + if let Some(fds) = open_fds() { + assert!( + fds < count / 4, + "{fds} descriptors open for {count} companions" + ); + } + for (i, (handle, fileid)) in handles.iter().enumerate() { + assert_eq!(c.read_all(handle, 64 * 1024), payload, "companion {i}"); + // The newest body is still resident; every older one is on disk. + assert_eq!( + spill_dir.join(fileid.to_string()).is_file(), + i + 1 < count, + "companion {i}" + ); + } + // The disk half still writes and truncates through its own open. + let (ref h0, _) = handles[0]; + c.write(h0, 0, b"opened by path").unwrap(); + let shrink = Set { + size: Some(14), + ..Set::default() + }; + c.setattr(h0, shrink, None).unwrap(); + assert_eq!(c.read_all(h0, 64), b"opened by path"); + } + assert_eq!(nofile_limits().0, soft, "the soft limit is put back"); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions, count); + assert!(released.companion_bytes <= budget); + assert!( + !spill_dir.exists(), + "export stop removes the spill directory" + ); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} #[test] fn tickets_are_released_only_after_the_reply() { let base = temp("tickets"); From 8183f8969997884b5f50343207f24093a6602307 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:40:11 +0000 Subject: [PATCH 19/53] docs(nfs): document the companion spill area and its cleanup (lp73) The guide names `edit.rs` and `apple_double_spill.rs`, describes what the `RESIDENT_BYTES` row does now (spill to `companion_spill_dir`, and which status each host errno maps to), and records the scratch file's own rules: one file per companion serial under `/.appledouble/`, `0700`/`0600`, written as a temporary and adopted by rename only when no call changed the body, opened by path per operation and never held open, deleted by startup reclamation and by release. `ExportConfig` lists the two new fields, and the `wcc_data` row now says a companion mutation answers from `directory_stats`. Documentation only; it describes the spill layer as it stands. Production LOC: 164334 -> 164334 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 91434f93e (164334) and this tree (164334). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 3b2db39e69..b8acc9f42e 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -35,7 +35,7 @@ The daemon starts it and has the host's own NFS client mount it. | Item | Meaning | Source | | --- | --- | --- | | `Server::start` | Starts the accept thread; one connection serves one call at a time, in arrival order | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | -| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | +| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`, `companion_spill_dir`, `companion_resident_bytes`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | `Server::stop` | Stop accepting, shut down and join every connection, then `Kernel::release`: descriptors first, then lookup references. The engine mount stays with the caller | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | `Kernel` | What a FUSE kernel would hold for a stateless client: one lookup reference per handed-out serial, implicit file and directory descriptors with the facts last published through them, a parent index for `..` | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | Verifier | One WRITE/COMMIT verifier per export, from the clock and process id under a random key | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | @@ -137,7 +137,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | --- | --- | | A publication ticket is released only after the reply's one send attempt, whether or not it reached the client | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | A WRITE is split into `WRITE_WINDOW` (256 KiB) windows, each one publication; a failure after the first is a short write of the windows already published. WRITE answers `FILE_SYNC`: published, not durable | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs), [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs) | -| `wcc_data` pre- and post-op attributes come from the publishing job's own inode state, RENAME included; no reply reads an attribute outside the job | [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs), [`kernel_visit.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_visit.rs) | +| `wcc_data` pre- and post-op attributes come from the publishing job's own inode state, RENAME included; no reply reads an attribute outside the job. An AppleDouble companion's CREATE, REMOVE or RENAME publishes no engine job and answers both halves from `Table::directory_stats` (or absent when unseen) | [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs), [`kernel_visit.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_visit.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | RENAME looks nothing up first; a detached (`nlink == 0`) destination's reference and descriptor are retired inside that job | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs) | | COMMIT answers the attributes last published or observed through the implicit descriptor, so `fsync` costs no owner job | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs) | | A client silly rename (`.nfs` + 24 hex on Linux; `.nfs.` + 8 hex + `.` + 4 hex on macOS) is served as an UNLINK; the export keeps the inode until the final REMOVE | [`names.rs`](../../../../engine/crates/layerfs-nfs/src/names.rs) | @@ -163,7 +163,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | The refresh never writes into the Workspace and never reverts a mode the install changed | [`refresh.rs`](../../../../engine/crates/layerfs-nfs/src/refresh.rs) | | `LAYERFS_NFS_REFRESH=0` leaves the client to `actimeo` and close-to-open | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -## AppleDouble files (`apple_double.rs`, `apple_double_codec.rs`) +## AppleDouble files (`apple_double.rs`, `apple_double/edit.rs`, `apple_double_codec.rs`, `apple_double_spill.rs`) On NFSv3 the macOS client keeps extended attributes and resource forks in `._` files. With `refuse_apple_double`, a regular `._` file (at least @@ -178,7 +178,7 @@ reaches the Workspace or a Commit; everything is dropped with the export. | --- | --- | --- | --- | | `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `RESIDENT_BYTES` | 32 MiB resident bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB resident bodies in all | Spill least recently touched resident bodies to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | | `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | @@ -189,6 +189,15 @@ is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` rather than its image, and every READ synthesizes the same bytes again. Partial writes, resource forks and other layouts stay as the client wrote them. +Resident bodies exceeding `RESIDENT_BYTES` spill outside the companion lock to +`..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by +rename to `` only if unchanged (`used` tick); spilled bodies are opened +by path per `pread`/`pwrite`/`set_len` and never held open. One edit per +companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), +recording length and bytes together and spilling its own body after bounded +eviction rounds (`SPILL_ROUNDS`) rather than failing with `NFS3ERR_IO`. +`ExportServing::reclaim` and release delete `/.appledouble`. + ## Mount (`mount.rs`, daemon `export.rs`) ```text From dc2c54c0f0f38aa22685be715a55d0a2834b3b5f Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:48:30 +0000 Subject: [PATCH 20/53] feat(nfs): one companion per inode, beyond 4,096 per export (lp73) A companion created while the export knows its main file (`` in the same directory) now belongs to that inode: every name of the inode reaches it, so hard links share one, it follows the inode through RENAME and it goes with the inode's last name. Such a companion holding a complete AppleDouble image is `whole`: it takes no slot of the index bound, and `rename`/`silly rename`/ `remove` of the main file drop it through `Kernel::companion_drop_for` and `companion_drop_inode`. `HELD` rises from 4,096 companions to 65,536 slotted entries: at the bound, orphan slotted companions are reclaimed first, and only if 65,536 live ones remain does CREATE answer `NFS3ERR_NOSPC`, count `names_refused` and log at most once per 60 s per export. The name index is the other half of it. `Table::aliases` remembers a hard-linked inode's names beyond `Table::names`, so `entry_taken` (when the engine reports `nlink <= 1`), `renamed`, `finish_unlink` and retirement drop only their own serial's keys from `by_name` instead of scanning it; a name that was moving to another inode is dropped through `Table::unbind_any`. CREATE at the bound releases the companion lock to collect orphans, then re-reads the companion name and main file under the lock it now holds, so two GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. `Companions::slots` walks only slotted entries - whole images add nothing - and `classify` decides again under RENAME's destination, so a companion moved onto an unknown main takes its slot back while a spilled body keeps the class the write that spilled it left (a decode there would read its file under the lock). `Kernel::companions_release` reports `Holding`, and `Released` carries `companions_slotted` and `companions` counted over whole images too. This is the last layer of the AppleDouble split (LP636) and reproduces `2e09f0295`'s companion code; the review's open findings are handled in the next task. Tests: `cargo test -p layerfs-nfs` 60 passed, 0 failed (raw sum 61: the file-limit case re-runs itself in a child process): 16 write, 11 decode, 6 codec, 2 daemon cases. Production LOC: 164334 -> 164574 (delta +240) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 8183f8969 (164334) and this tree (164574). Engine +240. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 333 +++++++++++++++--- .../layerfs-nfs/src/apple_double/edit.rs | 3 +- engine/crates/layerfs-nfs/src/change.rs | 10 +- engine/crates/layerfs-nfs/src/kernel.rs | 127 +++++-- .../crates/layerfs-nfs/src/kernel/released.rs | 24 +- engine/crates/layerfs-nfs/src/server.rs | 5 + 6 files changed, 418 insertions(+), 84 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 98fe0a665a..e4db0a5782 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -16,21 +16,32 @@ //! directory it names, so its `wcc_data` answers both halves from the last //! facts the export saw for it (see [`Kernel::directory_wcc`]). //! -//! Whenever a write leaves a companion holding a whole AppleDouble image the -//! client laid out itself (see [`crate::apple_double_codec`]), it is decoded: a -//! small one keeps only its FinderInfo and attributes in memory (at most -//! [`DECODED_BYTES`] in all, each at most [`DECODED_ENTRY_BYTES`]), and every -//! read synthesizes the same bytes again. Any other body (a resource fork, -//! another layout, a half-written image) is kept as the client wrote it. +//! A companion created while the export knows its main file (`` in the +//! same directory) belongs to that inode: any name of the inode reaches it, so +//! hard links share one companion, it follows the inode through RENAME, and it +//! goes with the inode's last name rather than with one name. Its FinderInfo +//! and extended attributes are kept under that inode's serial, not under the +//! `._` name. Whenever a write leaves such a companion holding a whole +//! AppleDouble image the client laid out itself (see +//! [`crate::apple_double_codec`]), it is decoded: a small one keeps only its +//! FinderInfo and attributes in memory (at most [`DECODED_BYTES`] in all, each +//! at most [`DECODED_ENTRY_BYTES`]), and every read synthesizes the same bytes +//! again. Such a whole image takes no slot of the index bound. Any other body +//! (a resource fork, another layout, a half-written image, or a companion whose +//! main file is unknown) is kept as the client wrote it and takes a slot: the +//! index bound, the refusal, its rate-limited log and orphan reclamation stay +//! the fallback for everything decoding does not compress. //! -//! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] each, -//! [`RESIDENT_BYTES`] of written bodies and [`DECODED_BYTES`] of decoded ones -//! counted as [`Image::cost`]. Bodies up to that budget stay in memory; when a -//! write or resize crosses it, the least recently touched resident bodies are -//! spilled to the export's own scratch directory (see -//! [`crate::apple_double_spill`]), and a body that still does not fit is -//! written out itself. Everything is dropped when the export is released, -//! which removes that directory too. +//! Every companion keeps its index entry in memory (at most [`HELD`] of them +//! not holding a whole image, each companion at most [`FILE_BYTES`]). Bodies up +//! to [`RESIDENT_BYTES`] in all stay in memory; when a write or resize crosses +//! that budget, the least recently touched resident bodies are spilled to the +//! export's own scratch directory (see [`crate::apple_double_spill`]). Removing +//! or replacing a main file drops its paired `._` companion, or only that +//! name when the companion is its inode's, which goes with the inode's last +//! name. When [`HELD`] is reached, orphan companions whose main inode or main +//! file the export no longer knows are reclaimed first, and only if [`HELD`] +//! live companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. use crate::{ apple_double_codec::Image, apple_double_spill::{io_status, now, spill_path, touch, unlink_paths, Edit}, @@ -41,10 +52,11 @@ use crate::{ use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; use layerfs_workspace::ViewStat; use std::{ - collections::HashMap, + collections::{HashMap, HashSet}, fs, path::{Path, PathBuf}, sync::{atomic::Ordering, Arc, Mutex}, + time::{Duration, Instant}, }; mod edit; @@ -52,8 +64,8 @@ mod edit; /// The first serial of the export's own companions, far above any serial the /// engine allocates. pub const SERIALS: u64 = 1 << 62; -/// Companion index entries held at once. -pub const HELD: usize = 4096; +/// Companion index entries not holding a whole image, held at once. +pub const HELD: usize = 65_536; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; /// Companion payload bytes kept resident in memory before spilling to disk. @@ -80,6 +92,11 @@ enum Body { struct Companion { /// The `._` name it was created or last renamed to. named: Named, + /// The main inode it belongs to, when the export knew it at creation. + inode: Option, + /// Its body is a whole image: any name of the inode reads it, and it takes + /// no slot of the index bound. + whole: bool, len: usize, body: Body, metadata: PortableMetadata, @@ -103,12 +120,17 @@ impl Companion { Body::Resident(_) | Body::Spilled => 0, } } + /// Whether it takes a slot of the index bound. + fn slotted(&self) -> bool { + !self.whole + } } /// What an export's companion index holds (see [`crate::kernel::Released`]). #[derive(Clone, Copy, Debug, Default)] pub(crate) struct Holding { pub held: usize, + pub slotted: usize, pub resident_bytes: usize, pub decoded: usize, pub decoded_bytes: usize, @@ -120,11 +142,21 @@ pub(crate) struct Companions { tick: u64, files: HashMap, names: HashMap, + /// Main inode serial -> the companion holding its FinderInfo and + /// attributes. + inodes: HashMap, + /// The serials taking a slot of the index bound, so reclamation walks only + /// the [`HELD`]-bounded slots rather than every companion: a whole image + /// takes no slot (whether decoded within [`DECODED_BYTES`] or kept as + /// written bytes above it), so whole images add nothing to the walk. + slots: HashSet, resident_bytes: usize, decoded: usize, decoded_bytes: usize, spill_dir: Option, resident_budget: usize, + held_limit: usize, + last_refusal_log: Option, } impl Default for Companions { fn default() -> Self { @@ -133,11 +165,15 @@ impl Default for Companions { tick: 0, files: HashMap::new(), names: HashMap::new(), + inodes: HashMap::new(), + slots: HashSet::new(), resident_bytes: 0, decoded: 0, decoded_bytes: 0, spill_dir: None, resident_budget: RESIDENT_BYTES, + held_limit: HELD, + last_refusal_log: None, } } } @@ -162,27 +198,69 @@ impl Companions { subdirs: 0, } } - /// Adds `file` to the index and to the byte counts. + /// Adds `file` to the index and to the slot and byte counts. fn attach(&mut self, serial: u64, file: Companion) { + if file.slotted() { + self.slots.insert(serial); + } self.resident_bytes += file.resident_len(); self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); self.decoded_bytes += file.decoded_cost(); self.files.insert(serial, file); } - /// Takes `serial` out of the index and the counts; its name key stays for + /// Takes `serial` out of the index and the counts; its name keys stay for /// the caller to unindex. fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; + self.slots.remove(&serial); self.resident_bytes -= file.resident_len(); self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); self.decoded_bytes -= file.decoded_cost(); Some(file) } + /// Makes `file`'s name and main inode find `serial`. + fn index(&mut self, serial: u64, file: &Companion) { + self.names.insert(file.named.clone(), serial); + if let Some(inode) = file.inode { + self.inodes.insert(inode, serial); + } + } + /// Drops `file`'s name and inode keys that still find `serial`. + fn unindex(&mut self, serial: u64, file: &Companion) { + if self.names.get(&file.named) == Some(&serial) { + self.names.remove(&file.named); + } + if let Some(inode) = file.inode { + if self.inodes.get(&inode) == Some(&serial) { + self.inodes.remove(&inode); + } + } + } + /// The companion `named` reaches when its main file is `main`: the one + /// held under that name, unless it belongs to another inode than `main`, + /// else the one its main inode already has. + fn resolve(&self, named: &Named, main: Option) -> Option { + if let Some(&serial) = self.names.get(named) { + let inode = self.files.get(&serial).and_then(|file| file.inode); + if inode.is_none() || main.is_none() || inode == main { + return Some(serial); + } + } + main.and_then(|main| self.inodes.get(&main).copied()) + } /// Replaces `serial`'s body by the decoded form of `bytes`, the caller's - /// edited body of `len` bytes, when the decoded budget takes it. The - /// decoded form costs its attributes rather than its image, so a body that - /// decodes needs no resident budget at all. + /// edited body of `len` bytes, when the decoded budget takes it and the + /// export knows the companion's main inode. The decoded form costs its + /// attributes rather than its image, so a body that decodes needs no + /// resident budget at all. fn keep_decoded(&mut self, serial: u64, bytes: &[u8], len: usize) -> bool { + // Only an inode's companion is decoded: one whose main file the export + // never saw keeps the client's bytes as written and a slot of the + // index bound, so that bound and orphan reclamation still reach it. + let inode = self.files.get(&serial).and_then(|file| file.inode); + if inode.is_none() { + return false; + } let Some(image) = Image::compact(bytes) else { return false; }; @@ -200,23 +278,43 @@ impl Companions { } file.len = len; file.body = Body::Decoded(image); + file.whole = true; file.used = tick; touch(&mut file.metadata); self.attach(serial, file); true } - /// Decides whether `file`'s body is a whole image: a resident one is - /// decoded when it parses back to the same bytes and the decoded budget - /// takes it. `file` must be detached from the index. + /// Decides whether `file`'s body is a whole image: a decoded body of an + /// inode's companion always is; a resident body of one is decoded when it + /// parses back to the same bytes and the decoded budget takes it. A + /// companion whose main file the export does not know is never a whole + /// image: it keeps the client's bytes as written and a slot of the index + /// bound, so that bound and orphan reclamation still reach it. `file` must + /// be detached from the index. fn classify(&self, file: &mut Companion) { + if file.inode.is_none() { + // Only a decoded body has to become bytes again; a body on disk + // keeps its file and takes a slot. + if let Body::Decoded(image) = &file.body { + file.body = Body::Resident(image.encode()); + } + file.whole = false; + return; + } // A body on disk cannot be decoded here (that reads its file under // this lock): it keeps the class the write that spilled it left it. + file.whole = match &file.body { + Body::Decoded(_) => true, + Body::Spilled => file.whole, + Body::Resident(_) => false, + }; let Body::Resident(bytes) = &file.body else { return; }; let Some(image) = Image::compact(bytes) else { return; }; + file.whole = true; let cost = image.cost(); if cost <= DECODED_ENTRY_BYTES && self.decoded_bytes + cost <= DECODED_BYTES { file.body = Body::Decoded(image); @@ -224,7 +322,7 @@ impl Companions { } fn take_serial(&mut self, serial: u64) -> Option { let file = self.detach(serial)?; - self.names.remove(&file.named); + self.unindex(serial, &file); match file.body { Body::Resident(_) | Body::Decoded(_) => None, Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), @@ -261,8 +359,9 @@ impl Companions { fs::rename(temp, path).map_err(|e| io_status(&e))?; let mut file = self.detach(serial).ok_or(Status::Stale)?; file.body = Body::Spilled; - // A shorter file than the companion had described is not the body any - // more. + // A body written out whole is still a whole image; a shorter file + // than the companion had described is not. + file.whole &= len <= file.len; file.len = file.len.max(len); self.attach(serial, file); Ok(true) @@ -280,6 +379,7 @@ impl Companions { fn holding(&self) -> Holding { Holding { held: self.files.len(), + slotted: self.slots.len(), resident_bytes: self.resident_bytes, decoded: self.decoded, decoded_bytes: self.decoded_bytes, @@ -314,13 +414,51 @@ impl Kernel { .lock() .unwrap_or_else(|poison| poison.into_inner()) } - pub(crate) fn configure_companions(&self, spill_dir: Option, resident_budget: usize) { + pub(crate) fn configure_companions( + &self, + spill_dir: Option, + resident_budget: usize, + held_limit: usize, + ) { if let Some(dir) = &spill_dir { drop(fs::remove_dir_all(dir)); } let mut companions = self.companions(); companions.spill_dir = spill_dir; companions.resident_budget = resident_budget; + companions.held_limit = held_limit.max(1); + } + /// The main inode `._` in `parent` pairs with, as the export's own + /// name index knows it. Takes the kernel table: never call it under the + /// companion lock. + fn main_of(&self, parent: u64, name: &[u8]) -> Option { + let main = name.strip_prefix(b"._").filter(|main| !main.is_empty())?; + self.table().by_name.get(&(parent, main.to_vec())).copied() + } + /// The companions no name reaches any more: one whose main inode holds no + /// name in the kernel table, and one whose main file the export never + /// observed and does not know now. Taken under the kernel table lock and, + /// inside it, the companion lock, so nothing here copies the namespace; + /// the caller drops them by serial under the companion lock again. + fn orphans(&self) -> Vec<(u64, Option)> { + let table = self.table(); + let companions = self.companions(); + companions + .slots + .iter() + .filter_map(|serial| { + let file = companions.files.get(serial)?; + let live = match file.inode { + Some(inode) => { + table.names.contains_key(&inode) || table.aliases.contains_key(&inode) + } + None => file.named.1.strip_prefix(b"._").is_some_and(|main| { + table.by_name.contains_key(&(file.named.0, main.to_vec())) + }), + }; + (!live).then_some((*serial, file.inode)) + }) + .collect() } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { @@ -330,10 +468,12 @@ impl Kernel { companions.use_serial(serial); Ok(stat) } - /// LOOKUP of a companion name, if one is held for it. + /// LOOKUP of a companion name, if one is held for it or for its main + /// inode. pub(crate) fn companion_named(&self, parent: u64, name: &[u8]) -> Option { + let main = self.main_of(parent, name); let mut companions = self.companions(); - let serial = *companions.names.get(&(parent, name.to_vec()))?; + let serial = companions.resolve(&(parent, name.to_vec()), main)?; let stat = Companions::stat(serial, companions.files.get(&serial)?); companions.use_serial(serial); Some(stat) @@ -379,14 +519,57 @@ impl Kernel { return Err(Status::NotDir); } let named = (parent, name.to_vec()); + let mut main = self.main_of(parent, name); let mut companions = self.companions(); - if let Some(serial) = companions.names.get(&named).copied() { + if let Some(serial) = companions.resolve(&named, main) { return self.companion_open(serial, how, directory, companions, tickets); } - if companions.files.len() >= HELD { + // At the index bound, reclaim the companions no name reaches any more + // first: found under the kernel table and the companion index, one + // entry at a time, so nothing here copies the namespace. + let mut reclaimed = Vec::new(); + if companions.slots.len() >= companions.held_limit { drop(companions); - self.names_refused.fetch_add(1, Ordering::Relaxed); - return Err(Status::Access); + let orphans = self.orphans(); + // The reclaim held no companion lock, so another CREATE of this + // name may have inserted it meanwhile and the main file may have + // changed: both are read again, and the name is inserted under the + // lock this call now holds without releasing it again. + main = self.main_of(parent, name); + companions = self.companions(); + if let Some(serial) = companions.resolve(&named, main) { + return self.companion_open(serial, how, directory, companions, tickets); + } + for (serial, inode) in orphans { + let still_orphan = companions + .files + .get(&serial) + .is_some_and(|file| file.inode == inode && file.slotted()); + if still_orphan { + reclaimed.extend(companions.take_serial(serial)); + } + } + } + if companions.slots.len() >= companions.held_limit { + let held = companions.slots.len(); + let limit = companions.held_limit; + let log = companions + .last_refusal_log + .is_none_or(|last| last.elapsed() >= Duration::from_secs(60)); + let namespace = log.then(|| companions.spill_dir.clone()); + if log { + companions.last_refusal_log = Some(Instant::now()); + } + drop(companions); + unlink_paths(reclaimed); + let refused = self.names_refused.fetch_add(1, Ordering::Relaxed) + 1; + if let Some(namespace) = namespace { + eprintln!( + "layerfs-nfs: AppleDouble index full: export={:?} namespace={namespace:?} parent={parent} companions={held} limit={limit} names_refused={refused}; NFS3ERR_NOSPC", + self.mount() + ); + } + return Err(Status::NoSpc); } let mut metadata = now(); if let How::Unchecked(sattr) | How::Guarded(sattr) = how { @@ -398,7 +581,9 @@ impl Kernel { companions.next += 1; let used = companions.tick(); let file = Companion { - named: named.clone(), + named, + inode: main, + whole: false, len: 0, body: Body::Resident(Vec::new()), metadata, @@ -406,25 +591,73 @@ impl Kernel { editing: Arc::new(Mutex::new(())), }; let stat = Companions::stat(serial, &file); - companions.names.insert(named, serial); + companions.index(serial, &file); companions.attach(serial, file); drop(companions); + unlink_paths(reclaimed); self.names_detached.fetch_add(1, Ordering::Relaxed); Ok((stat, directory)) } /// REMOVE of a companion name, with the directory's `wcc_data`; `None` /// when no companion has that name. pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { + let main = self.main_of(parent, name); let spilled = { let mut companions = self.companions(); - let serial = *companions.names.get(&(parent, name.to_vec()))?; + let serial = companions.resolve(&(parent, name.to_vec()), main)?; companions.take_serial(serial) }; unlink_paths(spilled); Some(self.directory_wcc(parent)) } + /// The main file `name` in `parent` was removed, silly-renamed or replaced + /// by `RENAME`: drops the companion held under `._`, or only that + /// name when the companion belongs to an inode, which goes with the + /// inode's last name instead (see [`Kernel::companion_drop_inode`]). A + /// plain non-replacing `RENAME` of a main file only cleans the destination + /// name `to/new_name` (via `finish_unlink`) and leaves `from/name` alone so + /// a client that renames `a -> b` and then renames `._a -> ._b` can still + /// move the companion across. + pub(crate) fn companion_drop_for(&self, parent: u64, name: &[u8]) { + if crate::names::apple_double(name) { + return; + } + let mut paired = Vec::with_capacity(2 + name.len()); + paired.extend_from_slice(b"._"); + paired.extend_from_slice(name); + let named = (parent, paired); + let spilled = { + let mut companions = self.companions(); + let Some(&serial) = companions.names.get(&named) else { + return; + }; + if companions + .files + .get(&serial) + .is_some_and(|file| file.inode.is_some()) + { + companions.names.remove(&named); + None + } else { + companions.take_serial(serial) + } + }; + unlink_paths(spilled); + } + /// Drops the companion of inode `main`, whose last name is gone. + pub(crate) fn companion_drop_inode(&self, main: u64) { + let spilled = { + let mut companions = self.companions(); + let Some(serial) = companions.inodes.get(&main).copied() else { + return; + }; + companions.take_serial(serial) + }; + unlink_paths(spilled); + } /// RENAME of a companion name: only to another AppleDouble name, which it - /// replaces when held. `None` when no companion has that name. + /// replaces when held. It then belongs to the destination's main inode, or + /// to none when that is unknown. `None` when no companion has that name. pub(crate) fn companion_rename( &self, from: u64, @@ -432,25 +665,34 @@ impl Kernel { to: u64, new_name: &[u8], ) -> Option> { + let from_main = self.main_of(from, name); + let to_main = self.main_of(to, new_name); let mut replaced_path = None; { let mut companions = self.companions(); - let serial = *companions.names.get(&(from, name.to_vec()))?; + let serial = companions.resolve(&(from, name.to_vec()), from_main)?; if !crate::names::apple_double(new_name) || new_name.len() > 255 { return Some(Err(Status::Access)); } let target = (to, new_name.to_vec()); - if let Some(replaced) = companions.names.get(&target).copied() { + if let Some(replaced) = companions.resolve(&target, to_main) { if replaced != serial { replaced_path = companions.take_serial(replaced); } } let tick = companions.tick(); let mut file = companions.detach(serial)?; - companions.names.remove(&file.named); - file.named = target.clone(); + companions.unindex(serial, &file); + file.named = target; + file.inode = to_main; file.used = tick; - companions.names.insert(target, serial); + // A client may write a companion under another name first, and a + // name it moves onto may belong to another main inode, or to + // none: the body is classified again under the destination, so + // one whose main file is unknown takes its slot and none keeps a + // whole image's exemption. + companions.classify(&mut file); + companions.index(serial, &file); companions.attach(serial, file); } unlink_paths(replaced_path); @@ -470,9 +712,10 @@ impl Kernel { let holding = held.holding(); if holding.held > 0 { eprintln!( - "layerfs-nfs: AppleDouble companions released: export={:?} held={} decoded={} decoded_bytes={} resident_bytes={}", + "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} decoded_bytes={} resident_bytes={}", self.mount(), holding.held, + holding.slotted, holding.decoded, holding.decoded_bytes, holding.resident_bytes diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 555ffb1120..a3ba16b691 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -249,13 +249,14 @@ impl Kernel { Ok(Room::Resident(stat)) } /// Records an edit applied to `serial`'s spilled file and answers its - /// stat. + /// stat. A body changed on disk is no longer known to be a whole image. fn record_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { let mut companions = self.companions(); let tick = companions.tick(); let mut file = companions.detach(serial).ok_or(Status::Stale)?; record(edit, &mut file); file.used = tick; + file.whole = false; touch(&mut file.metadata); let stat = Companions::stat(serial, &file); companions.attach(serial, file); diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 7932d219b5..11f74ef414 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -463,7 +463,8 @@ impl Kernel { /// export held for the inode it detached. Only the inode the publishing /// job itself retired skips the release jobs. fn finish_unlink(&self, parent: u64, name: &[u8], retire: Retire, detached: Option) { - self.table().by_name.remove(&(parent, name.to_vec())); + self.companion_drop_for(parent, name); + self.table().unbind_any(&(parent, name.to_vec())); let Some(target) = detached else { return; }; @@ -572,6 +573,11 @@ impl Kernel { self.mutate(from, None, None, Expect::Nothing, tickets, |_| { Ok(MutationInput::Named(remove::unlink(from, source_name))) })?; + self.companion_drop_for(from, name); + if source.namespace_refs <= 1 { + // The last name of the inode went with the silly rename. + self.companion_drop_inode(source.serial); + } self.silly_renamed.fetch_add(1, Ordering::Relaxed); let replaced = { let mut table = self.table(); @@ -627,7 +633,7 @@ impl Kernel { if directory { self.saw_directory(serial, to); } - self.renamed(serial, to, new_name); + self.renamed(serial, from, name, to, new_name); } /// LINK: one more name for `serial`. pub fn link( diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 43e17fda5c..a2e297e7fa 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -109,8 +109,15 @@ pub(crate) struct Table { /// Serial -> the name it was last reached by, kept after its reference /// is collected so a later handle can be resolved again. pub names: HashMap, - /// (directory, name) -> serial last seen under that name. + /// Every observed (directory, name) -> serial, including hard-link aliases. + /// A second name does not retire the first; unlink/rename remove known + /// vanished names, and retiring a serial removes all its keys. pub by_name: HashMap, + /// Serial -> the names it is reached by besides [`Table::names`]: the + /// hard-link aliases it was also observed under. Every key of + /// [`Table::by_name`] is one of the two, so dropping one record removes + /// exactly its own keys instead of scanning the whole index. + pub aliases: HashMap>, /// Serial -> last use, for the collection order. pub used: HashMap, /// Serials marked for a cache refresh, and when (see [`crate::refresh`]). @@ -131,6 +138,55 @@ impl Table { pub fn pinned(&self, serial: u64) -> bool { self.silly.values().any(|held| *held == serial) } + /// Records that `serial` is reached as `named`. + pub(crate) fn bind_name(&mut self, named: Named, serial: u64) { + self.by_name.insert(named, serial); + } + /// Remembers that `serial` is also reached as `named`, a name beyond its + /// remembered one, so dropping the serial needs no scan of `by_name`. + pub(crate) fn remember_alias(&mut self, serial: u64, named: &Named) { + let aliases = self.aliases.entry(serial).or_default(); + if !aliases.iter().any(|alias| alias == named) { + aliases.push(named.clone()); + } + } + /// Drops `named`, which `serial` no longer holds. Returns whether it did. + pub(crate) fn unbind_name(&mut self, named: &Named, serial: u64) -> bool { + if self.by_name.get(named) != Some(&serial) { + return false; + } + self.by_name.remove(named); + self.drop_alias(serial, named); + true + } + /// Drops `named` whatever serial holds it, and its alias record. + pub(crate) fn unbind_any(&mut self, named: &Named) -> Option { + let serial = self.by_name.remove(named)?; + self.drop_alias(serial, named); + Some(serial) + } + fn drop_alias(&mut self, serial: u64, named: &Named) { + let Some(aliases) = self.aliases.get_mut(&serial) else { + return; + }; + aliases.retain(|alias| alias != named); + if aliases.is_empty() { + self.aliases.remove(&serial); + } + } + /// Drops every key `serial` holds: its remembered name and its aliases. + pub(crate) fn unbind_serial(&mut self, serial: u64) { + if let Some(named) = self.names.remove(&serial) { + if self.by_name.get(&named) == Some(&serial) { + self.by_name.remove(&named); + } + } + for named in self.aliases.remove(&serial).unwrap_or_default() { + if self.by_name.get(&named) == Some(&serial) { + self.by_name.remove(&named); + } + } + } } /// One opened file as READ and WRITE need it. #[derive(Clone, Copy)] @@ -301,16 +357,12 @@ impl Kernel { Err(status) => return Err(status), } let mut table = self.table(); - if table + let remembered = table .names .get(&serial) - .is_some_and(|(p, n)| *p == parent && *n == name) - { - if let Some(old) = table.names.remove(&serial) { - if table.by_name.get(&old) == Some(&serial) { - table.by_name.remove(&old); - } - } + .is_some_and(|(p, n)| *p == parent && *n == name); + if remembered { + table.unbind_serial(serial); } self.unresolved.fetch_add(1, Ordering::Relaxed); Err(Status::Stale) @@ -427,11 +479,28 @@ impl Kernel { if table.names.len() < NAMES_HELD || table.names.contains_key(&stat.serial) { let named = (parent, name.to_vec()); if let Some(old) = table.names.insert(stat.serial, named.clone()) { - if table.by_name.get(&old) == Some(&stat.serial) { - table.by_name.remove(&old); + if old != named { + if stat.namespace_refs <= 1 { + // The inode has one name: every other name the + // index held for it is one it no longer has. + // (Its old keys stay a moment in a state whose + // nlink the engine last reported higher.) + table.unbind_name(&old, stat.serial); + for alias in table.aliases.remove(&stat.serial).unwrap_or_default() + { + if table.by_name.get(&alias) == Some(&stat.serial) { + table.by_name.remove(&alias); + } + } + } else { + // A hard link: the old name still reaches the + // inode, so it stays, remembered per serial so + // that retiring the serial drops no other name. + table.remember_alias(stat.serial, &old); + } } } - table.by_name.insert(named, stat.serial); + table.bind_name(named, stat.serial); } } let extra = root || !table.lookups.insert(stat.serial); @@ -452,16 +521,26 @@ impl Kernel { } self.observed(stat); } - /// Records that `serial` is now reached as `name` in `parent` (RENAME). - pub(crate) fn renamed(&self, serial: u64, parent: u64, name: &[u8]) { + /// Records that `serial` is now reached as `new_name` in `to` rather than as + /// `name` in `from` (RENAME). Only the name that moved leaves the index: + /// other names of the inode, its hard links, stay reachable as they were. + pub(crate) fn renamed(&self, serial: u64, from: u64, name: &[u8], to: u64, new_name: &[u8]) { let mut table = self.table(); - let named = (parent, name.to_vec()); - if let Some(slot) = table.names.get_mut(&serial) { - let old = std::mem::replace(slot, named.clone()); - if table.by_name.get(&old) == Some(&serial) { - table.by_name.remove(&old); + let named = (to, new_name.to_vec()); + let moved = (from, name.to_vec()); + table.unbind_name(&moved, serial); + let previous = table + .names + .get_mut(&serial) + .map(|slot| std::mem::replace(slot, named.clone())); + if let Some(previous) = previous { + // The name the inode was last recalled by did not move and is still + // one of its names: overwriting the remembered name keeps it only + // as an alias, which is what retiring the serial reads. + if previous != moved && previous != named { + table.remember_alias(serial, &previous); } - table.by_name.insert(named, serial); + table.bind_name(named, serial); } } pub(crate) fn forget(&self, serial: u64, count: u64) { @@ -489,11 +568,7 @@ impl Kernel { let mut table = self.table(); table.parents.remove(&serial); table.directory_stats.remove(&serial); - if let Some(old) = table.names.remove(&serial) { - if table.by_name.get(&old) == Some(&serial) { - table.by_name.remove(&old); - } - } + table.unbind_serial(serial); table.used.remove(&serial); table.verifiers.retain(|_, entry| entry.1 != serial); let directories: Vec = table @@ -524,6 +599,8 @@ impl Kernel { if held && !retired_in_job { self.forget(serial, 1); } + // An inode's last name is gone: so is its AppleDouble companion. + self.companion_drop_inode(serial); } /// Records the parent of a directory seen in a listing or moved by RENAME. pub fn saw_directory(&self, serial: u64, parent: u64) { diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index 3c37d964de..73a6321ee9 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -3,7 +3,7 @@ //! [`Kernel::release`] runs once, before the engine mount is revoked; [`Kernel::held`] //! reports the same counts while the export serves, for diagnostics. use super::{Kernel, Table}; -use std::sync::atomic::Ordering; +use std::sync::atomic::{AtomicU64, Ordering}; impl Kernel { /// Gives back everything the synthetic kernel holds: descriptors first, @@ -24,26 +24,25 @@ impl Kernel { } released } - fn retained_count(&self) -> usize { self.retained .lock() .unwrap_or_else(|poison| poison.into_inner()) .len() } - /// Current holdings, for diagnostics. pub fn held(&self) -> Released { let table = self.table(); let companions = self.companions_held(); self.holdings(&table, companions) } - /// What this export holds now, as [`Released`] reports it. fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { + let count = |counter: &AtomicU64| counter.load(Ordering::Relaxed); Released { companions: companions.held, companion_bytes: companions.resident_bytes, + companions_slotted: companions.slotted, companions_decoded: companions.decoded, companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), @@ -51,12 +50,12 @@ impl Kernel { lookups: table.lookups.len(), silly: table.silly.len(), retained: self.retained_count(), - silly_renamed: self.silly_renamed.load(Ordering::Relaxed), - names_refused: self.names_refused.load(Ordering::Relaxed), - names_detached: self.names_detached.load(Ordering::Relaxed), - collected: self.collected.load(Ordering::Relaxed), - resolved: self.resolved.load(Ordering::Relaxed), - unresolved: self.unresolved.load(Ordering::Relaxed), + silly_renamed: count(&self.silly_renamed), + names_refused: count(&self.names_refused), + names_detached: count(&self.names_detached), + collected: count(&self.collected), + resolved: count(&self.resolved), + unresolved: count(&self.unresolved), } } } @@ -76,10 +75,13 @@ pub struct Released { /// Creations refused for their AppleDouble name, over the export's life. pub names_refused: u64, /// AppleDouble companions held in the export's index (see - /// [`crate::apple_double`]). + /// [`crate::apple_double`]), whole images included. pub companions: usize, /// Companion payload bytes currently resident in memory. pub companion_bytes: usize, + /// Of the companions held, those taking a slot of the index bound: all but + /// the ones holding a whole image. + pub companions_slotted: usize, /// Of the companions held, those kept decoded, and the bytes counted for /// them. pub companions_decoded: usize, diff --git a/engine/crates/layerfs-nfs/src/server.rs b/engine/crates/layerfs-nfs/src/server.rs index 3a3e2b6d65..8db26faf1f 100644 --- a/engine/crates/layerfs-nfs/src/server.rs +++ b/engine/crates/layerfs-nfs/src/server.rs @@ -51,6 +51,9 @@ pub struct ExportConfig { /// to [`Self::companion_spill_dir`]; [`crate::apple_double::RESIDENT_BYTES`] /// by default. pub companion_resident_bytes: usize, + /// Maximum AppleDouble companion index entries held at once; + /// [`crate::apple_double::HELD`] by default. + pub companions_held: usize, } impl ExportConfig { /// A writable export of "/" shown as `uid`:`gid`, refusing AppleDouble @@ -65,6 +68,7 @@ impl ExportConfig { lookups_held: crate::kernel::LOOKUPS_HELD, companion_spill_dir: None, companion_resident_bytes: crate::apple_double::RESIDENT_BYTES, + companions_held: crate::apple_double::HELD, } } } @@ -153,6 +157,7 @@ impl Server { kernel.configure_companions( config.companion_spill_dir.clone(), config.companion_resident_bytes, + config.companions_held, ); let shared = Arc::new(Shared { kernel, From 12f37b4c191e5119d3cb46a5479c8fb0ad481189 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:51:48 +0000 Subject: [PATCH 21/53] test(nfs): cover the companion index bound, aliases and reclamation (lp73) The remaining cases of the layer: a whole image takes no slot and is read back from every name of its inode; a resource fork, an unknown main and a companion moved off its inode keep the stored-as-written path and their slot; `HELD` is 65,536 and a small bound reclaims orphans instead of refusing; two GUARDED creates of one name, and two of them over the last free slot, leave one entry; a reclaimed companion never loses a live main file's attributes, including one that gained a hard link; a renamed hard-link alias keeps the inode's recalled name bound; and companions survive a main-file rename, silly rename and replacing rename exactly as the client expects. `apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up` is the long one: 4,160 companions past the old 4,096 count and a 64 KiB resident budget, every write read back byte for byte, the spill directory's modes, the unlinks a main-file removal or replacing RENAME performs, the `FILE_BYTES` refusal, and the `HELD` bound with orphan reclamation before `NFS3ERR_NOSPC`. The rig can set `companions_held` too. Production LOC: 164574 -> 164574 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent dc2c54c0f (164574) and this tree (164574). Tests only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/tests/apple_double_decode.rs | 559 +++++++++++++++++- .../crates/layerfs-nfs/tests/support/rig.rs | 5 + engine/crates/layerfs-nfs/tests/write.rs | 464 ++++++++++++++- 3 files changed, 1021 insertions(+), 7 deletions(-) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 28f95320ba..7156b53da3 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1,8 +1,9 @@ -//! AppleDouble companions decoded into their attributes: a `._` a macOS -//! client writes as a whole image is kept as its FinderInfo and extended -//! attributes, and every read synthesizes the very bytes the client wrote. A -//! body that is not a whole image (a resource fork, another layout, a -//! half-written one) is stored as the client wrote it. +//! AppleDouble companions decoded into their main inode's own record: a +//! `._` the client writes is served byte for byte, takes no slot of the +//! index bound, is shared by every name of the inode, follows the inode +//! through RENAME and goes with its last name. A body that is not a whole +//! image (a resource fork, another layout, a half-written one) is stored as +//! the client wrote it, which is the #636 fallback. #[allow(dead_code)] #[path = "support/client.rs"] mod client; @@ -15,7 +16,7 @@ mod spy; #[allow(dead_code)] #[path = "support/tree.rs"] mod tree; -use client::{Client, Set, STALE}; +use client::{Client, Set, NOENT, STALE}; use layerfs_nfs::apple_double_codec::{Attribute, Image}; use std::{ fs, @@ -24,6 +25,7 @@ use std::{ time::Duration, }; +const NOSPC: u32 = 28; const UID: u32 = 501; const GID: u32 = 20; @@ -51,6 +53,85 @@ fn image(finder: [u8; 32], attrs: &[(&[u8], Vec)]) -> Vec { .encode() } +#[test] +fn a_whole_image_is_read_back_as_written_from_every_name_of_the_inode() { + let base = temp("decode"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // What `cp` does: the data file, then its companion with the attributes. + let main = c.touch(&root, b"f", 0o644).unwrap(); + c.write(&main.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._f", 0o644).unwrap(); + let finder = [0x11; 32]; + let first = image( + finder, + &[ + (b"com.apple.provenance", pattern(1, 40)), + (b"com.apple.quarantine", pattern(2, 150)), + (b"com.apple.FinderInfo", finder.to_vec()), + (b"user.custom", pattern(3, 4096)), + ], + ); + c.write(&ad.handle, 0, &first).unwrap(); + assert_eq!(c.getattr(&ad.handle).unwrap().size, first.len() as u64); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), first); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (1, 1, 0), + "a whole image is decoded and takes no slot" + ); + assert!(held.companion_decoded_bytes >= 4096); + + // A second name of the same inode reads the same companion. + c.link(&main.handle, &root, b"g").unwrap(); + let (alias, attr) = c.lookup(&root, b"._g").unwrap(); + assert_eq!(alias, ad.handle, "hard links share one companion"); + assert_eq!(attr.size, first.len() as u64); + assert_eq!(c.read_all(&alias, 64 * 1024), first); + + // A write under the alias changes the inode's attributes for every name. + let second = image( + [0x22; 32], + &[ + (b"com.apple.provenance", pattern(4, 40)), + (b"user.custom", pattern(5, 100 * 1024)), + ], + ); + c.write(&alias, 0, &second).unwrap(); + assert_eq!(c.read_all(&ad.handle, 256 * 1024), second); + + // RENAME of the main file carries the companion to the new name. + c.rename(&root, b"f", &root, b"h").unwrap(); + let (renamed, _) = c.lookup(&root, b"._h").unwrap(); + assert_eq!(renamed, ad.handle); + assert_eq!(c.read_all(&renamed, 256 * 1024), second); + + // The companion goes with the inode's last name, not with one name. + c.remove(&root, b"h").unwrap(); + assert_eq!(server.held().companions, 1, "g still names the inode"); + assert_eq!(c.read_all(&alias, 256 * 1024), second); + c.remove(&root, b"g").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&alias), Err(STALE)); + assert_eq!(c.lookup(&root, b"._h").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn the_clients_write_sequence_is_served_byte_for_byte() { let base = temp("sequence"); @@ -140,6 +221,209 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_resource_fork_keeps_the_stored_as_written_fallback() { + let base = temp("fork"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // A file with a resource fork: the fork's entry carries 286 bytes of the + // client's own, which the decoded form does not keep. + c.touch(&root, b"rf", 0o644).unwrap(); + let ad = c.touch(&root, b"._rf", 0o644).unwrap(); + let plain = image([0x55; 32], &[(b"com.apple.provenance", pattern(10, 40))]); + let mut forked = plain.clone(); + let fork = pattern(11, 286); + forked[plain.len() - 286..].copy_from_slice(&fork); + c.write(&ad.handle, 0, &forked).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), forked); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (1, 0, 1), + "a resource fork takes the stored-as-written path and its slot" + ); + // A companion whose main file the export never saw keeps that path too. + let _unknown = c.touch(&root, b"._no-main", 0o644).unwrap(); + let unknown = c.lookup(&root, b"._no-main").unwrap().0; + c.write(&unknown, 0, b"not an image").unwrap(); + assert_eq!(server.held().companions_slotted, 2); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions_decoded, 0); + assert_eq!(released.companions_slotted, 2); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn whole_images_take_no_slot_of_the_index_bound() { + let base = temp("slots"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // Two slots, and a body budget small enough that raw bodies spill. + rig.companions_held = 2; + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // More whole images than slots: every one is accepted. + let mut images = Vec::new(); + for i in 0..5 { + let main = format!("live-{i}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let ad = c + .touch(&root, format!("._{main}").as_bytes(), 0o644) + .unwrap(); + let bytes = image( + [0; 32], + &[(b"user.value", format!("value-{i}").into_bytes())], + ); + c.write(&ad.handle, 0, &bytes).unwrap(); + images.push((ad.handle, bytes)); + } + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (5, 5, 0) + ); + assert_eq!(held.names_refused, 0); + + // Bodies that are not whole images do take slots: the bound still answers + // NOSPC once they fill it, and its rate-limited log is the same. + for i in 0..2 { + let main = format!("raw-{i}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let ad = c + .touch(&root, format!("._{main}").as_bytes(), 0o644) + .unwrap(); + c.write(&ad.handle, 0, b"stored as written").unwrap(); + } + assert_eq!(server.held().companions_slotted, 2); + c.touch(&root, b"raw-extra", 0o644).unwrap(); + assert_eq!( + c.touch(&root, b"._raw-extra", 0o644).map(|_| ()), + Err(NOSPC) + ); + assert_eq!(server.held().names_refused, 1); + // Removing a raw companion's main file frees its slot, and a new whole + // image is then accepted again without taking one. + c.remove(&root, b"raw-0").unwrap(); + assert_eq!(server.held().companions_slotted, 1); + c.touch(&root, b"new-image", 0o644).unwrap(); + let ad = c.touch(&root, b"._new-image", 0o644).unwrap(); + let fresh = image([1; 32], &[(b"user.fresh", pattern(20, 64))]); + c.write(&ad.handle, 0, &fresh).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + assert_eq!(server.held().names_refused, 1); + assert_eq!(c.read_all(&ad.handle, 4096), fresh); + // The refused raw companion now fits. + c.touch(&root, b"._raw-extra", 0o644).unwrap(); + assert_eq!(server.held().companions_slotted, 2); + // Every whole image still reads back byte for byte. + for (handle, bytes) in &images { + assert_eq!(&c.read_all(handle, 64 * 1024), bytes); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_decoded_companion_is_gone_once_its_inode_is_silly_renamed() { + let base = temp("silly"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let main = c.touch(&root, b"open", 0o644).unwrap(); + c.write(&main.handle, 0, b"still open").unwrap(); + let ad = c.touch(&root, b"._open", 0o644).unwrap(); + let bytes = image([2; 32], &[(b"user.a", pattern(12, 32))]); + c.write(&ad.handle, 0, &bytes).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + // A client that unlinks a file it keeps open renames it to a silly name. + let silly: &[u8] = b".nfs.20051025.b896"; + c.rename(&root, b"open", &root, silly).unwrap(); + assert_eq!(server.held().companions, 0, "the last name went"); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + c.remove(&root, silly).unwrap(); + assert_eq!(c.lookup(&root, silly).map(|_| ()), Err(NOENT)); + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_replaced_main_file_takes_its_companion_with_it() { + let base = temp("replace"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + c.touch(&root, b"dst", 0o644).unwrap(); + c.touch(&root, b"src", 0o644).unwrap(); + let dst = c.touch(&root, b"._dst", 0o644).unwrap(); + c.write( + &dst.handle, + 0, + &image([3; 32], &[(b"user.dst", pattern(13, 16))]), + ) + .unwrap(); + let src = c.touch(&root, b"._src", 0o644).unwrap(); + c.write( + &src.handle, + 0, + &image([4; 32], &[(b"user.src", pattern(14, 16))]), + ) + .unwrap(); + assert_eq!(server.held().companions_decoded, 2); + // RENAME over the destination detaches it as an unlink would. + c.rename(&root, b"src", &root, b"dst").unwrap(); + assert_eq!(c.getattr(&dst.handle), Err(STALE)); + assert_eq!(server.held().companions_decoded, 1, "only src's is left"); + // The client moves the source's companion to the destination's name. + c.rename(&root, b"._src", &root, b"._dst").unwrap(); + let (moved, _) = c.lookup(&root, b"._dst").unwrap(); + assert_eq!(moved, src.handle); + assert_eq!( + c.read_all(&moved, 4096), + image([4; 32], &[(b"user.src", pattern(14, 16))]) + ); + c.remove(&root, b"dst").unwrap(); + assert_eq!(server.held().companions, 0); + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_decoded_companion_is_edited_under_a_full_resident_budget() { let base = temp("decoded-budget"); @@ -214,3 +498,266 @@ fn a_decoded_companion_is_edited_under_a_full_resident_budget() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_without_a_main_file_takes_a_slot_and_is_reclaimed() { + let base = temp("no-main"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 3; + // Too small for the image written below, so that write needs the spill path. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // A whole image under a name whose main file the export does not know is + // not decoded: it keeps the client's bytes and a slot of the index bound, + // both when it fits the resident budget and when it does not. + let small = image([0x88; 32], &[(b"user.small", pattern(32, 16))]); + c.touch(&root, b"._small", 0o644).unwrap(); + let fits = c.lookup(&root, b"._small").unwrap().0; + c.write(&fits, 0, &small).unwrap(); + assert_eq!(c.read_all(&fits, 4096), small); + let big = image([0x89; 32], &[(b"user.big", pattern(33, 4096))]); + c.touch(&root, b"._no-main", 0o644).unwrap(); + let spilled = c.lookup(&root, b"._no-main").unwrap().0; + c.write(&spilled, 0, &big).unwrap(); + assert_eq!(c.read_all(&spilled, 64 * 1024), big); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (2, 0, 2), + "a companion with no main file is stored as written and takes its slot" + ); + + // A decoded companion renamed onto a name whose main file is unknown is no + // longer an inode's: it keeps the bytes as written and takes its slot too. + let main = c.touch(&root, b"owned", 0o644).unwrap(); + c.write(&main.handle, 0, b"owned by an inode").unwrap(); + let owned = c.touch(&root, b"._owned", 0o644).unwrap(); + c.write(&owned.handle, 0, &small).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + c.rename(&root, b"._owned", &root, b"._gone").unwrap(); + assert_eq!(c.read_all(&owned.handle, 4096), small); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (3, 0, 3), + "a companion with no main file is never a whole image" + ); + + // The bound reclaims them as orphans instead of refusing the next CREATE. + c.touch(&root, b"next", 0o644).unwrap(); + c.touch(&root, b"._next", 0o644).unwrap(); + let held = server.held(); + assert_eq!( + (held.companions, held.companions_slotted, held.names_refused), + (1, 1, 0), + "the three companions with no main file were reclaimed" + ); + assert_eq!(c.getattr(&spilled), Err(STALE)); + assert_eq!(c.getattr(&owned.handle), Err(STALE)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_spilled_body_renamed_off_its_inode_takes_its_slot() { + let base = temp("spilled-rename"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill-rename")); + rig.companion_resident_bytes = 512 * 1024; + rig.companions_held = 4; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // A whole image with an attribute larger than the decoded-entry bound is + // kept as written, takes no slot, and fits the resident budget. + c.touch(&root, b"m", 0o644).unwrap(); + let ad = c.touch(&root, b"._m", 0o644).unwrap(); + let whole = image( + [0x5a; 32], + &[ + (b"com.apple.provenance", pattern(40, 40)), + (b"user.bulk", pattern(41, 200 * 1024)), + ], + ); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!( + ( + server.held().companions_decoded, + server.held().companions_slotted + ), + (0, 0), + "a whole image takes no slot even when it is kept as written" + ); + + // Another companion's larger body evicts it to disk, still whole. + c.touch(&root, b"other", 0o644).unwrap(); + let other = c.touch(&root, b"._other", 0o644).unwrap(); + let stored = pattern(42, 400 * 1024); + c.write(&other.handle, 0, &stored).unwrap(); + assert_eq!(server.held().companion_bytes, stored.len()); + assert_eq!( + server.held().companions_slotted, + 1, + "only ._other takes a slot" + ); + + // RENAME onto a name whose main file the export never saw: the body stops + // being an inode's companion, so it may not keep a whole image's + // exemption from the index bound, even on disk. + c.rename(&root, b"._m", &root, b"._gone").unwrap(); + let held = server.held(); + assert_eq!( + (held.companions_decoded, held.companions_slotted), + (0, 2), + "a spilled body renamed off its inode takes its slot" + ); + assert_eq!(c.read_all(&ad.handle, 256 * 1024), whole); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn whole_images_take_no_slot_and_the_bound_reclaims_only_slots() { + let base = temp("whole-images-bound"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 2; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // Two companions that decode into whole images: neither takes a slot, so a + // full table may hold any number of them. + let mut whole = Vec::new(); + for (main, seed) in [(b"a".as_slice(), 1u32), (b"b".as_slice(), 2u32)] { + let data = c.touch(&root, main, 0o644).unwrap(); + c.write(&data.handle, 0, b"data").unwrap(); + let mut name = b"._".to_vec(); + name.extend_from_slice(main); + let ad = c.touch(&root, &name, 0o644).unwrap(); + let bytes = image([seed as u8; 32], &[(b"user.small", pattern(seed, 16))]); + c.write(&ad.handle, 0, &bytes).unwrap(); + whole.push((ad.handle, bytes)); + } + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted + ), + (2, 2, 0), + "whole images take no slot" + ); + + // Both slots go to companions whose main file the export knows, so there is + // no orphan to reclaim: the bound refuses instead of touching a whole image. + for index in 0..2 { + let main = format!("live-{index}"); + let companion = format!("._live-{index}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, companion.as_bytes(), 0o644).unwrap(); + c.write(&ad.handle, 0, &[b'L'; 64]).unwrap(); + } + c.touch(&root, b"next", 0o644).unwrap(); + assert_eq!(c.touch(&root, b"._next", 0o644).map(|_| ()), Err(NOSPC)); + let held = server.held(); + assert_eq!( + ( + held.companions, + held.companions_decoded, + held.companions_slotted, + held.names_refused + ), + (4, 2, 2, 1), + "the refusal kept both whole images and both slots" + ); + for (handle, bytes) in &whole { + assert_eq!(c.read_all(handle, 4096), *bytes); + } + + // Freeing a slot, not a whole image, lets the next companion in. + c.remove(&root, b"._live-0").unwrap(); + c.touch(&root, b"._next", 0o644).unwrap(); + assert_eq!(server.held().companions_slotted, 2); + assert_eq!(server.held().companions, 4); + assert_eq!(server.held().companions_decoded, 2); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_rename_keeps_the_other_names_of_the_inode_companion() { + let base = temp("aliases"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + let main = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&main.handle, 0, b"two names, one inode").unwrap(); + let ad = c.touch(&root, b"._a", 0o644).unwrap(); + let bytes = image([0x99; 32], &[(b"user.link", pattern(34, 64))]); + c.write(&ad.handle, 0, &bytes).unwrap(); + c.link(&main.handle, &root, b"b").unwrap(); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad.handle); + + // RENAME moves one name of the inode: every other name still reaches the + // companion, before and after the moved name goes. + c.rename(&root, b"a", &root, b"c").unwrap(); + assert_eq!( + c.lookup(&root, b"._b").unwrap().0, + ad.handle, + "b still names the inode" + ); + assert_eq!(c.lookup(&root, b"._c").unwrap().0, ad.handle); + assert_eq!(c.read_all(&ad.handle, 4096), bytes); + c.remove(&root, b"c").unwrap(); + assert_eq!( + c.lookup(&root, b"._b").unwrap().0, + ad.handle, + "b is the inode's last name" + ); + assert_eq!(c.read_all(&ad.handle, 4096), bytes); + + // The companion goes with the inode's last name. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} diff --git a/engine/crates/layerfs-nfs/tests/support/rig.rs b/engine/crates/layerfs-nfs/tests/support/rig.rs index 612b9a2a2f..a5a8cbc801 100644 --- a/engine/crates/layerfs-nfs/tests/support/rig.rs +++ b/engine/crates/layerfs-nfs/tests/support/rig.rs @@ -42,6 +42,8 @@ pub struct Rig { pub lookups_held: usize, /// Resident memory budget for AppleDouble companion bodies. pub companion_resident_bytes: usize, + /// Maximum AppleDouble companion index entries held at once. + pub companions_held: usize, /// Optional explicit spill directory override for AppleDouble companions. pub companion_spill_dir: Option, } @@ -147,6 +149,7 @@ impl Rig { entries: initialized.entries, lookups_held: layerfs_nfs::kernel::LOOKUPS_HELD, companion_resident_bytes: layerfs_nfs::apple_double::RESIDENT_BYTES, + companions_held: layerfs_nfs::apple_double::HELD, companion_spill_dir: None, } } @@ -192,6 +195,7 @@ impl Rig { lookups_held: self.lookups_held, companion_spill_dir: Some(self.spill_dir("export")), companion_resident_bytes: self.companion_resident_bytes, + companions_held: self.companions_held, }, ) .unwrap() @@ -262,6 +266,7 @@ impl Rig { lookups_held: self.lookups_held, companion_spill_dir: Some(self.spill_dir(&format!("view-{}", view.1.owner_id()))), companion_resident_bytes: self.companion_resident_bytes, + companions_held: self.companions_held, }, ) .unwrap() diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index 0a5a9e596e..25b0351d87 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -33,6 +33,7 @@ use std::{ const UID: u32 = 501; const GID: u32 = 20; const FILE_SYNC: u32 = 2; +const NOSPC: u32 = 28; const LINUX_SILLY: &[u8] = b".nfs00000000000012ab00000001"; const MAC_SILLY: &[u8] = b".nfs.20051025.b896"; @@ -56,7 +57,6 @@ fn pattern(seed: u32, length: usize) -> Vec { .map(|n| (n as u32).wrapping_mul(31).wrapping_add(seed * 97) as u8) .collect() } - /// The files an export spilled into `dir`, and their bytes. fn spilled(dir: &Path) -> (usize, u64) { let files: Vec = (fs::read_dir(dir).into_iter().flatten().flatten()) @@ -540,6 +540,467 @@ fn apple_double_files_stay_out_of_the_workspace() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn apple_double_companions_spill_preserve_all_bytes_reclaim_orphans_and_clean_up() { + use layerfs_nfs::apple_double::{FILE_BYTES, HELD}; + let base = temp("appledouble-spill"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + + // 1. Pre-populate a leftover file in the spill directory (simulating a + // crashed daemon) and configure a small resident budget (64 KiB) so + // spilling is exercised across both the old 4096 companion count and + // the memory budget. + let spill_dir = base.join("spill-export"); + fs::create_dir_all(&spill_dir).unwrap(); + let stale_residue = spill_dir.join("stale-from-crash"); + fs::write(&stale_residue, b"leftover").unwrap(); + assert!(stale_residue.exists()); + + let budget = 64 * 1024; + rig.companion_spill_dir = Some(spill_dir.clone()); + rig.companion_resident_bytes = budget; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + assert!( + !stale_residue.exists(), + "starting an export cleans any leftover spill directory from an earlier crash" + ); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // 2. Removing a main file, silly-renaming it, or replacing it with RENAME + // drops its paired `._` companion and deletes its spilled disk + // file at once. Plain non-replacing RENAME (`mv plain_a plain_b`) + // cleans only the destination side so the client can subsequently + // rename `._plain_a -> ._plain_b`. + let big_payload = pattern(11, 40 * 1024); + c.touch(&root, b"rm.txt", 0o644).unwrap(); + let rm_ad = c.touch(&root, b"._rm.txt", 0o644).unwrap(); + c.write(&rm_ad.handle, 0, &big_payload).unwrap(); + c.touch(&root, b"silly.txt", 0o644).unwrap(); + let silly_ad = c.touch(&root, b"._silly.txt", 0o644).unwrap(); + c.write(&silly_ad.handle, 0, &big_payload).unwrap(); + // Second 40 KiB write crosses the 64 KiB budget, spilling `._rm.txt`. + let rm_spill_file = spill_dir.join(rm_ad.attr.fileid.to_string()); + assert!( + rm_spill_file.is_file(), + "oldest companion body spilled to disk" + ); + assert!(server.held().companion_bytes <= budget); + assert_eq!(spilled(&spill_dir), (1, big_payload.len() as u64)); + // The scratch directory and its files are this user's alone, whatever the + // process umask is. + for (path, mode) in [(&spill_dir, 0o700), (&rm_spill_file, 0o600)] { + assert_eq!( + fs::metadata(path).unwrap().permissions().mode() & 0o777, + mode, + "{}", + path.display() + ); + } + + c.remove(&root, b"rm.txt").unwrap(); + assert!( + !rm_spill_file.exists(), + "removing the main file unlinks its spilled companion file" + ); + assert_eq!(c.lookup(&root, b"._rm.txt").map(|_| ()), Err(NOENT)); + assert_eq!(c.getattr(&rm_ad.handle), Err(STALE)); + + c.rename(&root, b"silly.txt", &root, MAC_SILLY).unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&silly_ad.handle), Err(STALE)); + c.remove(&root, MAC_SILLY).unwrap(); + + c.touch(&root, b"src.txt", 0o644).unwrap(); + c.touch(&root, b"dst.txt", 0o644).unwrap(); + let dst_ad = c.touch(&root, b"._dst.txt", 0o644).unwrap(); + c.write(&dst_ad.handle, 0, &big_payload).unwrap(); + let src_ad = c.touch(&root, b"._src.txt", 0o644).unwrap(); + c.write(&src_ad.handle, 0, &big_payload).unwrap(); + let dst_spill_file = spill_dir.join(dst_ad.attr.fileid.to_string()); + assert!(dst_spill_file.is_file()); + c.rename(&root, b"src.txt", &root, b"dst.txt").unwrap(); + assert!( + !dst_spill_file.exists(), + "replacing RENAME unlinks the destination's spilled companion" + ); + assert_eq!(c.getattr(&dst_ad.handle), Err(STALE)); + // Source companion `._src.txt` is still present so the client can rename + // it to `._dst.txt`, then remove `dst.txt`. + c.rename(&root, b"._src.txt", &root, b"._dst.txt").unwrap(); + assert_eq!(c.read_all(&src_ad.handle, 64 * 1024), big_payload); + c.remove(&root, b"dst.txt").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(server.held().companion_bytes, 0); + + // 3. Create and write > 4096 companions (4160), crossing both the old + // 4096 cap and the 64 KiB resident memory budget: every CREATE, WRITE + // and READ succeeds, resident bytes never exceed `budget`, spilled + // files exist on disk, and the earliest companions read back byte for + // byte (0 data loss). + const TOTAL_COUNT: usize = 4160; + let mut handles = Vec::with_capacity(TOTAL_COUNT); + for i in 0..TOTAL_COUNT { + let name = format!("._c-{i}"); + let made = c.touch(&root, name.as_bytes(), 0o644).unwrap(); + let payload = if i < 32 || i % 128 == 0 { + format!("companion-payload-{i:04}-{}", "x".repeat(2048)).into_bytes() + } else { + format!("short-{i:04}").into_bytes() + }; + c.write(&made.handle, 0, &payload).unwrap(); + assert!( + server.held().companion_bytes <= budget, + "resident bytes {} exceeded budget {budget} at {i}", + server.held().companion_bytes + ); + handles.push((made.handle, made.attr.fileid, payload)); + } + assert_eq!(server.held().companions, TOTAL_COUNT); + assert_eq!(server.held().names_refused, 0); + assert!( + spilled(&spill_dir).0 > 0, + "companions beyond the resident budget are on disk" + ); + assert!(spill_dir.join(handles[0].1.to_string()).is_file()); + + // Earliest, middle and latest companions all read back byte-for-byte. + for idx in [ + 0, + 1, + 2, + 15, + 31, + 128, + 1024, + 2048, + 4095, + 4096, + TOTAL_COUNT - 1, + ] { + let (ref handle, _, ref expected) = handles[idx]; + let name = format!("._c-{idx}"); + let (looked, attr) = c.lookup(&root, name.as_bytes()).unwrap(); + assert_eq!(&looked, handle); + assert_eq!(attr.size, expected.len() as u64); + assert_eq!( + c.read_all(handle, 64 * 1024), + *expected, + "companion {idx} content mismatch" + ); + } + + // Overwriting and truncating an already-spilled companion works via + // pread/pwrite/set_len and removes its disk file on explicit REMOVE. + let (ref h0, id0, _) = handles[0]; + c.write(h0, 0, b"updated-header").unwrap(); + let shrink = Set { + size: Some(14), + ..Set::default() + }; + c.setattr(h0, shrink, None).unwrap(); + assert_eq!(c.read_all(h0, 64), b"updated-header"); + c.remove(&root, b"._c-0").unwrap(); + assert!(!spill_dir.join(id0.to_string()).exists()); + + // Single-file limit `FILE_BYTES` (1 MiB) is still enforced (`NFS3ERR_FBIG`). + const FBIG: u32 = 27; + let (ref h_last, _, _) = handles[TOTAL_COUNT - 1]; + assert_eq!(c.write(h_last, FILE_BYTES, b"!").map(|_| ()), Err(FBIG)); + + // 4. Stopping the export removes the entire spill directory. + drop(c); + let released = server.stop(); + assert_eq!(released.companions, TOTAL_COUNT - 1); + assert!(released.companion_bytes <= budget); + assert!( + !spill_dir.exists(), + "export stop removes the spill directory" + ); + + // 5. At the index bound (`companions_held`; default `HELD` = 65_536): + // orphan companions (whose paired main file is not in `Table::by_name`) + // are reclaimed first so new creations succeed; when all slots are + // held by live main files, `CREATE` answers `NFS3ERR_NOSPC`. + assert_eq!(HELD, 65_536); + let small_cap = 8; + let cap_spill = base.join("spill-cap"); + rig.companion_spill_dir = Some(cap_spill.clone()); + rig.companions_held = small_cap; + rig.companion_resident_bytes = 1024; + let server2 = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c2 = Client::connect(server2.local_addr(), UID, GID); + let root2 = c2.mnt("/"); + + // Create 4 live pairs (main file + companion) and 4 orphan companions + // (no main file created), filling all 8 index slots and spilling some. + for i in 0..4 { + let main = format!("live-{i}"); + let comp = format!("._live-{i}"); + c2.touch(&root2, main.as_bytes(), 0o644).unwrap(); + let ad = c2.touch(&root2, comp.as_bytes(), 0o644).unwrap(); + c2.write(&ad.handle, 0, &[b'L'; 512]).unwrap(); + } + let mut orphan_handles = Vec::new(); + for i in 0..4 { + let comp = format!("._orphan-{i}"); + let ad = c2.touch(&root2, comp.as_bytes(), 0o644).unwrap(); + c2.write(&ad.handle, 0, &[b'O'; 512]).unwrap(); + orphan_handles.push((ad.handle, ad.attr.fileid)); + } + assert_eq!(server2.held().companions, small_cap); + + // Creating 4 more live pairs at the bound reclaims the 4 orphans (and + // unlinks their spilled files) while preserving the first 4 live pairs. + for i in 4..small_cap { + let main = format!("live-{i}"); + let comp = format!("._live-{i}"); + c2.touch(&root2, main.as_bytes(), 0o644).unwrap(); + let ad = c2.touch(&root2, comp.as_bytes(), 0o644).unwrap(); + c2.write(&ad.handle, 0, &[b'N'; 128]).unwrap(); + } + assert_eq!(server2.held().companions, small_cap); + assert_eq!(server2.held().names_refused, 0); + for (oh, oid) in &orphan_handles { + assert_eq!(c2.getattr(oh), Err(STALE)); + assert!(!cap_spill.join(oid.to_string()).exists()); + } + for i in 0..4 { + let comp = format!("._live-{i}"); + let (lh, _) = c2.lookup(&root2, comp.as_bytes()).unwrap(); + assert_eq!(c2.read_all(&lh, 1024), vec![b'L'; 512]); + } + + // Now all 8 slots belong to live main files: one more companion CREATE + // finds no orphans to reclaim and answers `NFS3ERR_NOSPC`. Repeated + // refusals count individually but log at most once per minute per export. + c2.touch(&root2, b"extra", 0o644).unwrap(); + for _ in 0..3 { + assert_eq!(c2.touch(&root2, b"._extra", 0o644).map(|_| ()), Err(NOSPC)); + } + assert_eq!(server2.held().names_refused, 3); + // Existing names still honor GUARDED / UNCHECKED when the table is full. + assert_eq!( + c2.create(&root2, b"._live-0", How::Guarded(Set::default())) + .map(|_| ()), + Err(EXIST) + ); + c2.touch(&root2, b"._live-0", 0o644).unwrap(); + c2.remove(&root2, b"live-7").unwrap(); + c2.touch(&root2, b"._extra", 0o644).unwrap(); + assert_eq!(server2.held().names_refused, 3); + + drop(c2); + let released2 = server2.stop(); + assert!(!cap_spill.exists()); + let (_, outstanding) = rig.stop(released2); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn two_guarded_creates_of_one_companion_name_leave_one_entry() { + let base = temp("appledouble-create-race"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 8; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let mut other = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + c.touch(&root, b"dup", 0o644).unwrap(); + + // Two actual connections start each CREATE together. Repeat the schedule + // with an empty companion table, so every round exercises first insertion. + for _ in 0..4096 { + let start = std::sync::Barrier::new(2); + let (a, b) = std::thread::scope(|scope| { + let a = scope.spawn(|| { + start.wait(); + c.create(&root, b"._dup", How::Guarded(Set::default())) + }); + let b = scope.spawn(|| { + start.wait(); + other.create(&root, b"._dup", How::Guarded(Set::default())) + }); + (a.join().unwrap(), b.join().unwrap()) + }); + let mut statuses = [ + a.as_ref().map(|_| OK).unwrap_or_else(|e| *e), + b.as_ref().map(|_| OK).unwrap_or_else(|e| *e), + ]; + statuses.sort(); + assert_eq!(statuses, [OK, EXIST]); + let made = a.or(b).unwrap(); + assert_eq!(server.held().companions, 1); + c.remove(&root, b"._dup").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&made.handle), Err(STALE)); + } + c.touch(&root, b"._dup", 0o644).unwrap(); + assert_eq!(server.held().names_refused, 0); + drop((c, other)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_guarded_create_reclaims_the_last_slot_for_one_entry_only() { + let base = temp("appledouble-create-race-bound"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 3; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let mut other = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + c.touch(&root, b"dup", 0o644).unwrap(); + // Two slots belong to live main files, which reclamation must keep. + for index in 0..2 { + let main = format!("live-{index}"); + let companion = format!("._live-{index}"); + c.touch(&root, main.as_bytes(), 0o644).unwrap(); + let made = c.touch(&root, companion.as_bytes(), 0o644).unwrap(); + c.write(&made.handle, 0, &[b'L'; 64]).unwrap(); + } + assert_eq!(server.held().companions_slotted, 2); + // Every round fills the last slot with a companion whose main file does not + // exist, so both creates below are over the bound and one of them has to + // reclaim that orphan while it holds no companion lock. + for round in 0..256 { + let orphan = format!("._orphan-{round}"); + let made = c.touch(&root, orphan.as_bytes(), 0o644).unwrap(); + c.write(&made.handle, 0, &[b'O'; 64]).unwrap(); + assert_eq!(server.held().companions_slotted, 3, "round {round}"); + let start = std::sync::Barrier::new(2); + let (a, b) = std::thread::scope(|scope| { + let a = scope.spawn(|| { + start.wait(); + c.create(&root, b"._dup", How::Guarded(Set::default())) + }); + let b = scope.spawn(|| { + start.wait(); + other.create(&root, b"._dup", How::Guarded(Set::default())) + }); + (a.join().unwrap(), b.join().unwrap()) + }); + let mut statuses = [ + a.as_ref().map(|_| OK).unwrap_or_else(|status| *status), + b.as_ref().map(|_| OK).unwrap_or_else(|status| *status), + ]; + statuses.sort(); + assert_eq!(statuses, [OK, EXIST], "round {round}"); + // The two live pairs and the one name: the loser inserted no second + // serial for a name that is already taken. + assert_eq!(server.held().companions_slotted, 3, "round {round}"); + assert_eq!(server.held().companions, 3, "round {round}"); + assert_eq!(c.getattr(&made.handle), Err(STALE), "round {round}"); + c.remove(&root, b"._dup").unwrap(); + assert_eq!(server.held().companions_slotted, 2, "round {round}"); + } + assert_eq!(server.held().names_refused, 0); + drop((c, other)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_renamed_hard_link_alias_keeps_the_inodes_recalled_name_bound() { + let base = temp("appledouble-rename-alias"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // Two exports of one mount: the second one moves a name the first one does + // not observe, as another client of the same Workspace would. + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let second = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let mut them = Client::connect(second.local_addr(), UID, GID); + let root = c.mnt("/"); + let their_root = them.mnt("/"); + + // One inode, three names: the export recalls it by `p` and holds `q` as an + // alias of it. + let main = c.touch(&root, b"p", 0o644).unwrap(); + c.link(&main.handle, &root, b"q").unwrap(); + assert_eq!(c.lookup(&root, b"p").unwrap().0, main.handle); + // RENAME of `q` to `r` keeps `p` as the recalled name; the next RENAME moves + // `p` itself, which is an alias, so `r` stops being the recalled name and + // is still one of the inode's names. + c.rename(&root, b"q", &root, b"r").unwrap(); + c.rename(&root, b"p", &root, b"s").unwrap(); + + // The other export moves and then removes `r`; this export removes `s`, + // which is the inode's last name: it retires the inode, and `r` must leave + // the name index with it. + them.rename(&their_root, b"r", &their_root, b"t").unwrap(); + them.remove(&their_root, b"t").unwrap(); + c.remove(&root, b"s").unwrap(); + + // A `._r` companion created while `r` is gone belongs to no inode. + c.touch(&root, b"._r", 0o644).unwrap(); + let companion = c.lookup(&root, b"._r").unwrap().0; + let payload = b"a companion of no inode"; + c.write(&companion, 0, payload).unwrap(); + + // A new file takes the name `r`; the companion is still reachable by name. + them.touch(&their_root, b"r", 0o644).unwrap(); + let (fresh, _) = c.lookup(&root, b"r").unwrap(); + assert_ne!(fresh, main.handle); + let (found, _) = c + .lookup(&root, b"._r") + .expect("the companion still belongs to no inode"); + assert_eq!(found, companion); + assert_eq!(c.read_all(&found, 64), payload); + + drop((c, them)); + let released = server.stop(); + second.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_companion_survives_reclaim_after_its_main_file_gains_a_second_name() { + let base = temp("appledouble-hardlink-reclaim"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 2; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let main = c.touch(&root, b"anchor", 0o644).unwrap(); + let companion = c.touch(&root, b"._anchor", 0o644).unwrap(); + let payload = b"held-cap-preserve-me"; + c.write(&companion.handle, 0, payload).unwrap(); + c.link(&main.handle, &root, b"anchor-alias").unwrap(); + let orphan = c.touch(&root, b"._orphan", 0o644).unwrap(); + assert_eq!(server.held().companions, 2); + c.touch(&root, b"other", 0o644).unwrap(); + c.touch(&root, b"._other", 0o644).unwrap(); + assert_eq!(c.read_all(&companion.handle, 1024), payload); + assert_eq!(c.lookup(&root, b"anchor").unwrap().0, main.handle); + assert_eq!(c.lookup(&root, b"anchor-alias").unwrap().0, main.handle); + assert_eq!(c.getattr(&orphan.handle), Err(STALE)); + assert_eq!(server.held().companions, 2); + assert_eq!(server.held().names_refused, 0); + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_spill_replaces_a_companion_body_only_when_no_call_changed_it() { use layerfs_nfs::apple_double::spill_applies; @@ -768,6 +1229,7 @@ fn spilled_companions_outnumber_the_open_file_limit() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + #[test] fn tickets_are_released_only_after_the_reply() { let base = temp("tickets"); From 6af05cd95e5a93e19fdc20a671420a3c9d0205fe Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:53:20 +0000 Subject: [PATCH 22/53] docs(nfs): document the companion index and the inode binding (lp73) The AppleDouble section now states what `HELD` (65,536 slotted entries) does at the bound - reclaim orphans, then `NFS3ERR_NOSPC` with one rate-limited log per export - and that a companion whose main inode the export knows belongs to that inode: hard links share it, RENAME keeps it under the new name and its aliases, and its last name or silly rename drops it. It records that a whole image takes no `HELD` slot, that `companion_rename` re-classifies under the destination, and how `Table::names`/`Table::aliases` keep unlink, `entry_taken`, `renamed` and retirement from scanning `by_name`, and how CREATE re-reads the name and main file after collecting orphans. Documentation only; it describes the layer as it stands. Production LOC: 164574 -> 164574 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 2cc52c813 (164574) and this tree (164574). Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 47 +++++++++++++------ 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index b8acc9f42e..94cb090ca2 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -35,7 +35,7 @@ The daemon starts it and has the host's own NFS client mount it. | Item | Meaning | Source | | --- | --- | --- | | `Server::start` | Starts the accept thread; one connection serves one call at a time, in arrival order | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | -| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`, `companion_spill_dir`, `companion_resident_bytes`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | +| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`, `companion_spill_dir`, `companion_resident_bytes`, `companions_held`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | `Server::stop` | Stop accepting, shut down and join every connection, then `Kernel::release`: descriptors first, then lookup references. The engine mount stays with the caller | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | | `Kernel` | What a FUSE kernel would hold for a stateless client: one lookup reference per handed-out serial, implicit file and directory descriptors with the facts last published through them, a parent index for `..` | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) | | Verifier | One WRITE/COMMIT verifier per export, from the clock and process id under a random key | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) | @@ -166,28 +166,45 @@ drawn once per export; it makes guessing costly and does not authenticate. ## AppleDouble files (`apple_double.rs`, `apple_double/edit.rs`, `apple_double_codec.rs`, `apple_double_spill.rs`) On NFSv3 the macOS client keeps extended attributes and resource forks in -`._` files. With `refuse_apple_double`, a regular `._` file (at least -one byte after `._`) lives in export memory only, at serial -`SERIALS` (2^62) and above: LOOKUP, GETATTR, ACCESS, READ, WRITE, SETATTR, +`._` files (at least one byte after `._`). With `refuse_apple_double`, a +regular `._` file lives in export state only (`Companions`, serials +`SERIALS` = 2^62 and above): LOOKUP, GETATTR, ACCESS, READ, WRITE, SETATTR, COMMIT, REMOVE and RENAME to another `._` name are served there, READDIR never lists it and the engine is never called. Any other kind is `NFS3ERR_ACCES`. `cp`, `copyfile`, `ditto` and `tar` succeed while nothing -reaches the Workspace or a Commit; everything is dropped with the export. +reaches the Workspace, SQLite overlay or a Commit; everything is dropped with +the export. | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 slotted companion entries | Reclaim orphan slotted companions; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs at most once per 60 s per export | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `RESIDENT_BYTES` | 32 MiB resident bodies in all | Spill least recently touched resident bodies to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | - -A body a write or resize leaves as a complete AppleDouble image that encodes -back to the exact bytes the companion holds -([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)) -is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` -rather than its image, and every READ synthesizes the same bytes again. Partial -writes, resource forks and other layouts stay as the client wrote them. +| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written and still take no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written and still take no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | + +A companion whose main inode the export knows belongs to that inode rather than +to one name: hard links share it, main-file RENAME keeps it under the new name +and existing aliases, and only the inode's last name (or its silly rename) +drops it. When a write leaves an inode-bound companion holding a complete +AppleDouble image that encodes back to the exact bytes written +([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)), +it is marked whole and takes no `HELD` slot (decoded in memory within +`DECODED_BYTES` / `DECODED_ENTRY_BYTES`, or kept as written bytes above them); +partial writes, resource forks, other layouts and unknown-main companions stay +as written bytes and occupy a slot. `companion_rename` re-classifies under the +destination so moving onto an unknown main name takes a slot (a spilled body +keeps its prior class). + +`Table::names` and `Table::aliases` index each serial's names so unlink, +`entry_taken` (when `nlink <= 1`), `renamed` (keeping an overwritten recalled +name as an alias) and retirement drop only that serial's keys from `by_name` +without scanning it. At the `HELD` bound, CREATE releases the companion lock to +collect orphans from `Companions::slots` (walking only slotted entries under +the table and companion locks, never whole images or `by_name`), then re-acquires +the lock and re-reads the companion name and main file before inserting, so +concurrent GUARDED creates of one name yield one serial and one +`NFS3ERR_EXIST`. Resident bodies exceeding `RESIDENT_BYTES` spill outside the companion lock to `..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by From b01e805988941d28e31eff3b6e652fdbea04e5ae Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:24:33 +0000 Subject: [PATCH 23/53] feat(nfs): encode only the window of the AppleDouble image a READ asks for (lp73) A decoded companion was re-encoded in full under the companion lock on every READ: up to `FILE_BYTES` (1 MiB) allocated and copied to serve a reply of at most `TRANSFER_WINDOW` (256 KiB) bytes, and often far less. `Image::encode_range` lays the image out and fills only `[start, end)`, so a READ pays for the bytes it answers with; `Image::encode` is that same layout over the whole image, so there is one implementation of the layout rather than two that can drift. `edit.rs`'s spill and `edit_resident` still need the whole image and keep calling `encode()`. Whether a READ is served from a window or from the whole image is not observable: the reply bytes are the same either way. Review: finding 7 (full re-encode on every READ). Tests: new `any_window_of_the_image_encodes_to_that_window` compares every window of an image (a padding byte the client left behind, values of several sizes, the empty resource fork) with the same slice of `encode()`, including empty windows, a window past the image and one that starts after it ends. `cargo test -p layerfs-nfs --test apple_double_codec --test apple_double_decode`: 7 + 1 passed, 0 failed. Anti-proof: with `encode_range` clamped to start at 0 again the window test fails (`left` starts at image offset 0 while the expected window starts mid-image). Production LOC: 163886 -> 163908 (delta +22) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 584cc3e66 (163886) and of the staged tree 20b10a3487 (163908). Engine +22. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 8 +- .../layerfs-nfs/src/apple_double_codec.rs | 86 +++++++++++++------ .../layerfs-nfs/tests/apple_double_codec.rs | 53 ++++++++++++ 3 files changed, 117 insertions(+), 30 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index c96d1c8b6a..7aa38ae4e2 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -373,10 +373,10 @@ impl Kernel { out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); } Body::Decoded(image) => { - // The image the client wrote, synthesized again. - let bytes = image.encode(); - let stop = end.min(bytes.len()); - out.extend_from_slice(bytes.get(start..stop).unwrap_or_default()); + // The image the client wrote, synthesized again over the + // window this reply asks for rather than in full. + let stop = end.min(image.len()); + out.extend_from_slice(&image.encode_range(start, stop)); } } Ok(end as u64 >= length) diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs index 1d01edabf3..1e45130f78 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -14,6 +14,8 @@ //! client wrote: no attribute, value or byte the layout carries is dropped. //! Each attribute entry keeps the alignment padding the client left after its //! name, because the client does not clear the bytes a shorter name replaced. +//! [`Image::encode_range`] gives back any window of the image, so a READ serves +//! the bytes it asked for without laying out the whole image first. //! //! Anything else - a resource fork with data, still another layout, a //! half-written image - yields `None` and is stored as the client wrote it. @@ -184,42 +186,65 @@ impl Image { } /// The image these fields describe, as the client lays one out. pub fn encode(&self) -> Vec { - let mut out = vec![0u8; self.len]; + self.encode_range(0, self.len) + } + /// The bytes of the encoded image in `[start, end)`, both clamped to its + /// length: a READ of one window pays for that window, not for the whole + /// image, and gives back the same bytes [`Self::encode`] would. + pub fn encode_range(&self, start: usize, end: usize) -> Vec { + let start = start.min(self.len); + let end = end.max(start).min(self.len); + let mut out = vec![0u8; end - start]; let fork_at = self.len - self.fork.len(); let data_start = self.data_start(); - put32(&mut out, 0, MAGIC); - put32(&mut out, 4, VERSION); - out[8..24].copy_from_slice(FILLER); - put16(&mut out, 24, 2); - put32(&mut out, 26, FINDER_TAG); - put32(&mut out, 30, FINDER_AT as u32); - put32(&mut out, 34, (fork_at - FINDER_AT) as u32); - put32(&mut out, 38, FORK_TAG); - put32(&mut out, 42, fork_at as u32); - put32(&mut out, 46, self.fork.len() as u32); - out[FINDER_AT..FINDER_AT + FINDER_INFO].copy_from_slice(&self.finder); - put32(&mut out, ATTR_AT, ATTR_MAGIC); - put32(&mut out, ATTR_AT + 4, self.tag); - put32(&mut out, ATTR_AT + 8, fork_at as u32); - put32(&mut out, ATTR_AT + 12, data_start as u32); - put32(&mut out, ATTR_AT + 16, self.data_len() as u32); - put16(&mut out, ATTR_AT + 34, self.attrs.len() as u16); + // The fixed part of the image, whose offsets are absolute and known + // without walking the entries. + let mut head = [0u8; ENTRIES_AT]; + put32(&mut head, 0, MAGIC); + put32(&mut head, 4, VERSION); + head[8..24].copy_from_slice(FILLER); + put16(&mut head, 24, 2); + put32(&mut head, 26, FINDER_TAG); + put32(&mut head, 30, FINDER_AT as u32); + put32(&mut head, 34, (fork_at - FINDER_AT) as u32); + put32(&mut head, 38, FORK_TAG); + put32(&mut head, 42, fork_at as u32); + put32(&mut head, 46, self.fork.len() as u32); + head[FINDER_AT..FINDER_AT + FINDER_INFO].copy_from_slice(&self.finder); + put32(&mut head, ATTR_AT, ATTR_MAGIC); + put32(&mut head, ATTR_AT + 4, self.tag); + put32(&mut head, ATTR_AT + 8, fork_at as u32); + put32(&mut head, ATTR_AT + 12, data_start as u32); + put32(&mut head, ATTR_AT + 16, self.data_len() as u32); + put16(&mut head, ATTR_AT + 34, self.attrs.len() as u16); + emit(&mut out, start, 0, &head); let (mut entry, mut value_at) = (ENTRIES_AT, data_start); for attr in &self.attrs { - put32(&mut out, entry, value_at as u32); - put32(&mut out, entry + 4, attr.value.len() as u32); - out[entry + 10] = (attr.name.len() + 1) as u8; + // Entries and values only grow, and the fork sits past both: once + // neither of this one's is in the window, no later one is either. + if entry >= end && value_at >= end { + break; + } + let name_len = attr.name.len() + 1; + emit(&mut out, start, entry, &(value_at as u32).to_be_bytes()); + emit( + &mut out, + start, + entry + 4, + &(attr.value.len() as u32).to_be_bytes(), + ); + emit(&mut out, start, entry + 10, &[name_len as u8]); let name_at = entry + ENTRY_FIXED; let name_end = name_at + attr.name.len(); - out[name_at..name_end].copy_from_slice(&attr.name); - let next = entry + entry_len(attr.name.len() + 1); - out[name_end + 1..next].copy_from_slice(&attr.pad[..next - name_end - 1]); - out[value_at..value_at + attr.value.len()].copy_from_slice(&attr.value); + emit(&mut out, start, name_at, &attr.name); + let next = entry + entry_len(name_len); + emit(&mut out, start, name_end + 1, &attr.pad[..next - name_end - 1]); + emit(&mut out, start, value_at, &attr.value); entry = next; value_at += attr.value.len(); } if self.fork == Fork::Blank { - out[fork_at..].copy_from_slice(&blank_fork()); + emit(&mut out, start, fork_at, &blank_fork()); } out } @@ -328,6 +353,15 @@ fn blank_fork() -> [u8; BLANK_FORK] { fork[16..16 + BLANK_FORK_TAG.len()].copy_from_slice(BLANK_FORK_TAG); fork } +/// Copies the `bytes` that sit at `at` in the image into `out`, which holds +/// the image from `start` to its end. +fn emit(out: &mut [u8], start: usize, at: usize, bytes: &[u8]) { + let from = at.max(start); + let until = (at + bytes.len()).min(start + out.len()); + if from < until { + out[from - start..until - start].copy_from_slice(&bytes[from - at..until - at]); + } +} fn put32(out: &mut [u8], at: usize, value: u32) { out[at..at + 4].copy_from_slice(&value.to_be_bytes()); } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs index 8bbfc57412..b4d0c32098 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs @@ -55,6 +55,59 @@ fn first_name_end(name_len: usize) -> usize { ENTRIES_AT + 11 + name_len } +#[test] +fn any_window_of_the_image_encodes_to_that_window() { + // An image the client would write and decode: attributes whose names end + // on every alignment, values of several sizes, a padding byte the client + // left behind and its own empty resource fork. + let attrs: &[(&[u8], Vec)] = &[ + (b"user.a", pattern(11, 1)), + (b"com.example.long-name", pattern(12, 300)), + (b"user.c", pattern(13, 0)), + (b"com.apple.provenance", pattern(14, 40)), + (b"user.tail", pattern(15, 1000)), + ]; + let mut bytes = image([0x5a; 32], 0x0123_4567, attrs).encode(); + bytes[first_name_end(b"user.a".len()) + 1] = 0x3d; + let built = Image::compact(&bytes).expect("the image decodes"); + assert_eq!(built.encode(), bytes, "the whole image is unchanged"); + let len = bytes.len(); + let window = |start: usize, end: usize| { + let start = start.min(len); + let end = end.max(start).min(len); + bytes[start..end].to_vec() + }; + // Every window, in and past the image, byte for byte the same as the + // whole encoding: the header, each entry's offset, length and name, the + // padding after a name, each value, and the fork. + for start in (0..=len + 1).step_by(37) { + assert_eq!(built.encode_range(start, len + 1), window(start, len + 1)); + for end in (start..=len + 1).step_by(41) { + assert_eq!( + built.encode_range(start, end), + window(start, end), + "window {start}..{end} of {len} bytes" + ); + } + } + // An empty window, and a window that starts past the image. + assert_eq!(built.encode_range(0, 0), Vec::::new()); + assert_eq!(built.encode_range(len / 2, len / 2), Vec::::new()); + assert_eq!(built.encode_range(len + 10, len + 20), Vec::::new()); + assert_eq!(built.encode_range(7, 3), Vec::::new()); + assert_eq!(built.encode_range(0, len + 10), bytes); + assert_eq!(built.encode_range(len - 1, len + 10), bytes[len - 1..].to_vec()); + // The fork's own bytes are not all zero: a window inside it is served + // from the fork, not from the zeroed layout. + let fork_at = get32(&bytes, FORK_AT) as usize; + assert!(bytes[fork_at..].iter().any(|byte| *byte != 0)); + assert_eq!( + built.encode_range(fork_at, len), + bytes[fork_at..].to_vec(), + "the empty resource fork is part of the window" + ); +} + #[test] fn values_of_every_size_round_trip() { for size in [0, 1, 4096, 64 * 1024, 100 * 1024] { From 7ef50a034d87556b7cbe2bb17b5bcb7d6df2dcf1 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:28:43 +0000 Subject: [PATCH 24/53] refactor(nfs): count decoded AppleDouble images in the resident budget (lp73) `DECODED_BYTES` (512 MiB per export) was memory nothing could evict: many Workspaces can be mounted at once, so a per-export budget that is never paid back does not fit. Decoded images now take the same `RESIDENT_BYTES` (32 MiB) as bodies kept as written, a body at its length and a decoded one as `Image::cost`, so the budget sees every byte the export holds. `Companion::resident_cost` is that one number; `attach`, `detach` and `edit_body` count it, `edit_body` decides with it (a body either fits or the whole edit answers `NFS3ERR_NOSPC` and leaves the companion as it was), and `classify` no longer consults a second budget. `DECODED_ENTRY_BYTES` stays, now as the most `Image::cost` one decoded companion may be counted for: a whole image costing more keeps the client's bytes, so one companion cannot take the whole pool. This layer has no disk to spill to, so a body the budget does not take is still refused; the next layer spills it. `Released` reports the merged pool as `companion_bytes` and keeps `companions_decoded` as a count, instead of `companion_decoded_bytes` beside a separate resident total. Review: owner decision 3 (`DECODED_BYTES` rejected), first half (the budget and the counts); the spill half is the next layer. Tests: `the_clients_write_sequence_is_served_byte_for_byte` now asserts the merged pool: the decoded image's `Image::cost()` after the image arrives, the written body's length while it does not decode, the cost again once it does, and zero after the companion is removed. `cargo test -p layerfs-nfs`: 42 passed, 0 failed. Anti-proof: with a decoded body counted as zero again the test fails at the first assertion (`left: 0, right: 4372`). Production LOC: 163908 -> 163896 (delta -12) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent b01e80598 (163908) and of the staged tree bfc489bb4e (163896). Engine -12. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 14 ++-- engine/crates/layerfs-nfs/src/apple_double.rs | 68 +++++++++---------- .../crates/layerfs-nfs/src/kernel/released.rs | 10 +-- .../layerfs-nfs/tests/apple_double_decode.rs | 17 +++++ 4 files changed, 62 insertions(+), 47 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 3b2db39e69..22ebe232a6 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -178,16 +178,18 @@ reaches the Workspace or a Commit; everything is dropped with the export. | --- | --- | --- | --- | | `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `RESIDENT_BYTES` | 32 MiB resident bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB of companion bodies in all | WRITE / SETATTR `NFS3ERR_NOSPC` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | A body a write or resize leaves as a complete AppleDouble image that encodes back to the exact bytes the companion holds ([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)) -is kept as its FinderInfo and attributes and counted against `DECODED_BYTES` -rather than its image, and every READ synthesizes the same bytes again. Partial -writes, resource forks and other layouts stay as the client wrote them. +is kept as its FinderInfo and attributes, and every READ synthesizes the same +bytes again. It takes the same `RESIDENT_BYTES` budget as a body kept as +written, counted as `Image::cost` (its names and values, not its image), so no +decoded image is memory the budget cannot see. Partial writes, resource forks +and other layouts stay as the client wrote them, and a body the budget does not +take leaves the companion as it was. ## Mount (`mount.rs`, daemon `export.rs`) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 7aa38ae4e2..3aff737e07 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -18,15 +18,17 @@ //! //! Whenever a write leaves a companion holding a whole AppleDouble image the //! client laid out itself (see [`crate::apple_double_codec`]), it is decoded: a -//! small one keeps only its FinderInfo and attributes in memory (at most -//! [`DECODED_BYTES`] in all, each at most [`DECODED_ENTRY_BYTES`]), and every -//! read synthesizes the same bytes again. +//! small one keeps only its FinderInfo and attributes in memory (each at most +//! [`DECODED_ENTRY_BYTES`] counted), and every read synthesizes the same bytes +//! again. //! //! The memory is bounded: [`HELD`] companions of at most [`FILE_BYTES`] each, -//! [`RESIDENT_BYTES`] of written bodies and [`DECODED_BYTES`] of decoded ones -//! counted as [`Image::cost`]. Beyond the count a creation is refused +//! and [`RESIDENT_BYTES`] of bodies in all, a body kept as written counted at +//! its length and a decoded one as [`Image::cost`], so a decoded image is never +//! memory the budget cannot see. Beyond the count a creation is refused //! (`NFS3ERR_ACCES`, as before this module), beyond a file's bytes a write -//! (`NFS3ERR_FBIG`), beyond the resident body budget a write (`NFS3ERR_NOSPC`). +//! (`NFS3ERR_FBIG`), beyond the body budget a write (`NFS3ERR_NOSPC`), which +//! leaves the companion exactly as it was. use crate::{ apple_double_codec::Image, attributes::Status, @@ -49,12 +51,12 @@ pub const SERIALS: u64 = 1 << 62; pub const HELD: usize = 4096; /// Largest companion kept. pub const FILE_BYTES: u64 = 1 << 20; -/// Companion payload bytes kept resident in memory before a write is refused. +/// Companion payload bytes kept resident in memory before a write is refused: +/// a body kept as written counts its length, a decoded one [`Image::cost`]. pub const RESIDENT_BYTES: usize = 32 << 20; -/// Bytes counted for all decoded companions (see [`Image::cost`]). -pub const DECODED_BYTES: usize = 512 << 20; -/// Bytes counted for one decoded companion; a larger whole image keeps its -/// bytes as written. +/// Most bytes counted for one decoded companion, [`Image::cost`]; a whole +/// image costing more keeps its bytes as written, so one companion cannot take +/// the whole budget. pub const DECODED_ENTRY_BYTES: usize = 128 << 10; /// Mode of a companion created without one. const MODE: u32 = 0o644; @@ -74,16 +76,12 @@ struct Companion { metadata: PortableMetadata, } impl Companion { - fn resident_len(&self) -> usize { + /// The bytes it takes of [`RESIDENT_BYTES`]: its body as written, or what + /// its decoded form is counted as. + fn resident_cost(&self) -> usize { match &self.body { Body::Resident(bytes) => bytes.len(), - Body::Decoded(_) => 0, - } - } - fn decoded_cost(&self) -> usize { - match &self.body { Body::Decoded(image) => image.cost(), - Body::Resident(_) => 0, } } } @@ -93,7 +91,7 @@ impl Companion { pub(crate) struct Holding { pub held: usize, pub decoded: usize, - pub decoded_bytes: usize, + pub resident_bytes: usize, } /// The companions of one export. @@ -104,7 +102,6 @@ pub(crate) struct Companions { names: HashMap<(u64, Vec), u64>, resident_bytes: usize, decoded: usize, - decoded_bytes: usize, } impl Companions { pub(crate) fn len(&self) -> usize { @@ -122,18 +119,16 @@ impl Companions { } /// Adds `file` to the index and to the byte counts. fn attach(&mut self, serial: u64, file: Companion) { - self.resident_bytes += file.resident_len(); + self.resident_bytes += file.resident_cost(); self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); - self.decoded_bytes += file.decoded_cost(); self.files.insert(serial, file); } /// Takes `serial` out of the index and the counts; its name key stays for /// the caller to unindex. fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; - self.resident_bytes -= file.resident_len(); + self.resident_bytes -= file.resident_cost(); self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); - self.decoded_bytes -= file.decoded_cost(); Some(file) } /// Drops `serial` and its name key. @@ -143,7 +138,7 @@ impl Companions { } } /// Decides whether `file`'s body is a whole image: one that parses back to - /// the same bytes and that the decoded budget takes. `file` must be + /// the same bytes and that [`DECODED_ENTRY_BYTES`] takes. `file` must be /// detached from the index. fn classify(&self, file: &mut Companion) { let Body::Resident(bytes) = &file.body else { @@ -152,25 +147,23 @@ impl Companions { let Some(image) = Image::compact(bytes) else { return; }; - let cost = image.cost(); - if cost <= DECODED_ENTRY_BYTES && self.decoded_bytes + cost <= DECODED_BYTES { + if image.cost() <= DECODED_ENTRY_BYTES { file.body = Body::Decoded(image); } } /// Replaces `serial`'s body by `len` bytes built from it by `apply`, kept - /// within the budgets: a body that decodes costs its attributes, not its - /// bytes, and any other body stays in memory only while [`RESIDENT_BYTES`] - /// takes it. All of it or nothing: a body the budgets cannot take leaves - /// the companion exactly as it was. + /// within [`RESIDENT_BYTES`]: a body that decodes is counted as its + /// attributes, not as its bytes, and any other body stays in memory only + /// while the budget takes it. All of it or nothing: a body the budget + /// cannot take leaves the companion exactly as it was. fn edit_body( &mut self, serial: u64, len: usize, apply: impl FnOnce(&mut Vec), ) -> Result<(), Status> { - let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); let mut file = self.detach(serial).ok_or(Status::Stale)?; - let need = len.saturating_sub(file.resident_len()); + let avail = RESIDENT_BYTES.saturating_sub(self.resident_bytes); let before_len = file.len; let original = std::mem::replace(&mut file.body, Body::Resident(Vec::new())); let mut bytes = match &original { @@ -182,9 +175,10 @@ impl Companions { file.body = Body::Resident(bytes); file.len = len; self.classify(&mut file); - if need > avail && !matches!(file.body, Body::Decoded(_)) { - // The body does not decode and the resident budget does not take - // it: the companion keeps what it had and the caller answers NOSPC. + if file.resident_cost() > avail { + // Neither as bytes nor as attributes does the body fit what the + // budget has left: the companion keeps what it had and the caller + // answers NOSPC. file.body = original; file.len = before_len; self.attach(serial, file); @@ -211,7 +205,7 @@ impl Companions { Holding { held: self.files.len(), decoded: self.decoded, - decoded_bytes: self.decoded_bytes, + resident_bytes: self.resident_bytes, } } } diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index f765a6177d..a333d56fb5 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -43,8 +43,8 @@ impl Kernel { fn holdings(&self, table: &Table, companions: crate::apple_double::Holding) -> Released { Released { companions: companions.held, + companion_bytes: companions.resident_bytes, companions_decoded: companions.decoded, - companion_decoded_bytes: companions.decoded_bytes, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -77,10 +77,12 @@ pub struct Released { /// AppleDouble companions held in the export's index (see /// [`crate::apple_double`]). pub companions: usize, - /// Of the companions held, those kept decoded, and the bytes counted for - /// them. + /// Companion body bytes currently counted against the export's resident + /// budget: a body kept as written at its length, a decoded one at what its + /// attributes are counted as. + pub companion_bytes: usize, + /// Of the companions held, those kept decoded. pub companions_decoded: usize, - pub companion_decoded_bytes: usize, /// AppleDouble companions created, over the export's life. pub names_detached: u64, /// References collected beyond the bound, over the export's life. diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 7acd47a903..dea993d169 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -81,12 +81,21 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { c.write(&ad.handle, 50, &whole[50..]).unwrap(); assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); assert_eq!(server.held().companions_decoded, 1); + // The decoded form is memory too: it is counted against the same resident + // budget as a body kept as written, at what its attributes cost. + let decoded = Image::compact(&whole).expect("the client's image decodes"); + assert_eq!(server.held().companion_bytes, decoded.cost()); // A delete and rebuild starts empty and decodes the rewrite again. c.remove(&root, b"._seq").unwrap(); assert_eq!(c.getattr(&ad.handle), Err(STALE)); let again = c.touch(&root, b"._seq", 0o644).unwrap(); assert_eq!(again.attr.size, 0); + assert_eq!( + server.held().companion_bytes, + 0, + "the removed companion gave its bytes back" + ); assert_eq!(c.read_all(&again.handle, 4096), Vec::::new()); let rebuilt = image( [0x44; 32], @@ -97,6 +106,8 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { ); c.write(&again.handle, 0, &rebuilt).unwrap(); assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); + let rebuilt_cost = Image::compact(&rebuilt).expect("decodes").cost(); + assert_eq!(server.held().companion_bytes, rebuilt_cost); // An edit that leaves the image not whole is served as written, and a // later edit that completes it decodes again: both are the client's own @@ -106,9 +117,15 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { c.write(&again.handle, 24, b"EDIT").unwrap(); assert_eq!(c.read_all(&again.handle, 128 * 1024), edited); assert_eq!(server.held().companions_decoded, 0); + assert_eq!( + server.held().companion_bytes, + edited.len(), + "a body kept as written counts its length" + ); c.write(&again.handle, 24, &rebuilt[24..28]).unwrap(); assert_eq!(c.read_all(&again.handle, 128 * 1024), rebuilt); assert_eq!(server.held().companions_decoded, 1); + assert_eq!(server.held().companion_bytes, rebuilt_cost); // Truncating below the image is served as the client's truncation, and // resizing back up serves zeros, as on any file. From e323c0eba773a2d2f50adac4b06ee78a370accfe Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:43:39 +0000 Subject: [PATCH 25/53] feat(nfs): spill a decoded AppleDouble body like any other body (lp73) With decoded images counted against `RESIDENT_BYTES`, a decoded body is memory like any other and has to leave memory like any other. `oldest_resident` now takes the least recently used companion whose `resident_cost` is not zero, which is a body kept as written or a decoded one, so eviction reaches decoded bodies. Writing a decoded body out needs nothing new: `spill_one` and `spill_gated` already encode it and write those bytes, which are exactly the image the client wrote. A whole image that does not fit the budget is therefore no longer refused (`NFS3ERR_NOSPC`) nor kept decoded beyond it: it goes to its spill file and is edited there, as any body does. Review: owner decision 3 (`DECODED_BYTES` rejected), second half (the spill). Tests: new `eviction_takes_the_decoded_body_before_the_written_ones` under a 4,096-byte budget: a decoded image of 213 bytes, then two 2,000-byte bodies. The decoded body is the least recently used memory, so it is the one spilled (`companions_decoded` 1 -> 0), the two written bodies stay resident (`4000` bytes), and the image reads back byte for byte from its file. Anti-proof: with `oldest_resident` filtered to bodies kept as written again, the test fails (`companions_decoded` stays 1 and the written body is evicted instead). Production LOC: 164340 -> 164337 (delta -3) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 7a9f20c33 (164340) and of the staged tree (164337). Engine -3. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 3 +- engine/crates/layerfs-nfs/src/apple_double.rs | 7 +-- .../layerfs-nfs/tests/apple_double_decode.rs | 56 +++++++++++++++++++ 3 files changed, 61 insertions(+), 5 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 49fcab020e..851e42441a 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -190,7 +190,8 @@ length, so no decoded image is memory the budget cannot see, and every READ synthesizes the same bytes again. Partial writes, resource forks and other layouts stay as the client wrote them. -Resident bodies exceeding `RESIDENT_BYTES` spill outside the companion lock to +Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` +together, spill outside the companion lock to `..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by rename to `` only if unchanged (`used` tick); spilled bodies are opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 02e0b433de..51ed13a495 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -259,13 +259,12 @@ impl Companions { self.attach(serial, file); Ok(true) } + /// The least recently used companion holding memory, a body kept as + /// written or a decoded one: the budget counts both, so both are evicted. fn oldest_resident(&self, skip: Option) -> Option { self.files .iter() - .filter(|(serial, file)| { - Some(**serial) != skip - && matches!(file.body, Body::Resident(ref b) if !b.is_empty()) - }) + .filter(|(serial, file)| Some(**serial) != skip && file.resident_cost() > 0) .min_by_key(|(_, file)| file.used) .map(|(serial, _)| *serial) } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 7dc65ecea1..25aedc1d59 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -157,6 +157,62 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn eviction_takes_the_decoded_body_before_the_written_ones() { + let base = temp("decoded-evict"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill")); + // Room for two 2,000-byte bodies and one decoded image of a few hundred + // bytes. + rig.companion_resident_bytes = 4096; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + + // A whole image, decoded: it costs its attributes, not its 4 KiB. + let whole = image( + [0x21; 32], + &[(b"com.apple.provenance", pattern(40, 40))], + ); + c.touch(&root, b"old", 0o644).unwrap(); + let old = c.touch(&root, b"._old", 0o644).unwrap(); + c.write(&old.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + let decoded_cost = server.held().companion_bytes; + assert!(decoded_cost < 4096, "the image is counted as its attributes"); + + // Two bodies kept as written fill the budget: the decoded body is the least + // recently used memory there is, so it is the one spilled, and its file + // holds the image the client wrote. + let first = pattern(41, 2000); + let second = pattern(42, 2000); + c.touch(&root, b"one", 0o644).unwrap(); + let one = c.touch(&root, b"._one", 0o644).unwrap(); + c.write(&one.handle, 0, &first).unwrap(); + c.touch(&root, b"two", 0o644).unwrap(); + let two = c.touch(&root, b"._two", 0o644).unwrap(); + c.write(&two.handle, 0, &second).unwrap(); + assert_eq!( + server.held().companions_decoded, + 0, + "the decoded body was the memory evicted" + ); + assert_eq!(server.held().companion_bytes, 4000); + assert_eq!(c.read_all(&old.handle, 64 * 1024), whole, "from its spill file"); + assert_eq!(c.read_all(&one.handle, 64 * 1024), first); + assert_eq!(c.read_all(&two.handle, 64 * 1024), second); + assert_eq!(c.getattr(&old.handle).unwrap().size as usize, whole.len()); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions_decoded, 0); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_decoded_companion_is_edited_under_a_full_resident_budget() { let base = temp("decoded-budget"); From 73f62efc2cfc09191a24b9e2118d912f2d0752cd Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:47:03 +0000 Subject: [PATCH 26/53] perf(nfs): keep companion bodies in an eviction order, not a scan (lp73) Eviction walked every companion to find the least recently used one, and `spill_for` repeated that walk up to `SPILL_ROUNDS` times, so one edit could scan the index under the companion lock several times. `Companions::by_use` is now a `BTreeSet<(used tick, serial)>` of the companions holding memory: `attach` inserts an entry when a body takes budget, `detach` removes it, and `set_used` (behind `use_serial`, the guest's last touch of the body) moves it. `oldest_resident` is the first entry, skipping the caller's own serial, so a round costs one step into the order (O(log n)) and no walk. `spill_for` no longer bounds its rounds by the number of companions: it takes the oldest body, and if that body changed under it the other call has already moved its entry to the newest end, so the next round looks at a different one; the rounds end when nothing holding memory is left. `SPILL_ROUNDS` goes away. The companion lock now does O(1) or O(log n) work per step with no I/O: `attach`/`detach`/`set_used` one set operation, `oldest_resident` one lookup, and the file written before the lock is taken and renamed after it is dropped. The kernel table lock is untouched by any of this. Review: blocking finding 2 (eviction is an O(n) scan under the lock, repeated). Tests: new `eviction_follows_the_order_of_use_not_the_shape_of_the_index`: 64 companions of 16 bytes under a 1,024-byte budget, three of them read again, then eight more; the spill directory holds exactly the serials of the eight least recently used ones, in that order, and the three read again stay resident. Anti-proof: with `oldest_resident` reversed the test fails, spilling `SERIALS+2, +64..+70` (the newest) instead of `SERIALS+3..+10`. Production LOC: 164337 -> 164342 (delta +5) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent e323c0eba (164337) and of the staged tree (164342). Engine +5. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 7 +- engine/crates/layerfs-nfs/src/apple_double.rs | 37 +++++++--- .../layerfs-nfs/src/apple_double/edit.rs | 42 ++++-------- .../layerfs-nfs/tests/apple_double_decode.rs | 68 +++++++++++++++++++ 4 files changed, 117 insertions(+), 37 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 851e42441a..b325d78a29 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -196,8 +196,11 @@ together, spill outside the companion lock to rename to `` only if unchanged (`used` tick); spilled bodies are opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), -recording length and bytes together and spilling its own body after bounded -eviction rounds (`SPILL_ROUNDS`) rather than failing with `NFS3ERR_IO`. +recording length and bytes together and spilling its own body rather than +failing with `NFS3ERR_IO`. Eviction follows `Companions::by_use`, the +`(used tick, serial)` order kept on attach, detach and every use: the victim is +the first entry (O(log n) per round, no walk of the index), and the rounds end +when no companion holding memory is left. `ExportServing::reclaim` and release delete `/.appledouble`. ## Mount (`mount.rs`, daemon `export.rs`) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 51ed13a495..5d6b172af0 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -42,7 +42,7 @@ use crate::{ use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; use layerfs_workspace::ViewStat; use std::{ - collections::HashMap, + collections::{BTreeSet, HashMap}, fs, path::{Path, PathBuf}, sync::{atomic::Ordering, Arc, Mutex}, @@ -117,6 +117,10 @@ pub(crate) struct Companions { tick: u64, files: HashMap, names: HashMap, + /// Every companion holding memory, oldest use first: (used tick, serial). + /// One tick is one touch and no serial takes two ticks, so the keys are + /// unique and the oldest entry is the first one. + by_use: BTreeSet<(u64, u64)>, resident_bytes: usize, decoded: usize, spill_dir: Option, @@ -129,6 +133,7 @@ impl Default for Companions { tick: 0, files: HashMap::new(), names: HashMap::new(), + by_use: BTreeSet::new(), resident_bytes: 0, decoded: 0, spill_dir: None, @@ -141,10 +146,22 @@ impl Companions { self.tick += 1; self.tick } + /// Marks `serial` as used now, which is the order eviction follows. Only a + /// companion holding memory is in the order: a spilled body has nothing to + /// give back. fn use_serial(&mut self, serial: u64) { let tick = self.tick(); - if let Some(file) = self.files.get_mut(&serial) { - file.used = tick; + self.set_used(serial, tick); + } + /// Moves `serial`'s index entry to `used`. + fn set_used(&mut self, serial: u64, used: u64) { + let Some(file) = self.files.get_mut(&serial) else { + return; + }; + let old = std::mem::replace(&mut file.used, used); + self.by_use.remove(&(old, serial)); + if file.resident_cost() > 0 { + self.by_use.insert((used, serial)); } } fn stat(serial: u64, file: &Companion) -> ViewStat { @@ -157,8 +174,11 @@ impl Companions { subdirs: 0, } } - /// Adds `file` to the index and to the byte counts. + /// Adds `file` to the index, the byte counts and the eviction order. fn attach(&mut self, serial: u64, file: Companion) { + if file.resident_cost() > 0 { + self.by_use.insert((file.used, serial)); + } self.resident_bytes += file.resident_cost(); self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); self.files.insert(serial, file); @@ -167,6 +187,7 @@ impl Companions { /// the caller to unindex. fn detach(&mut self, serial: u64) -> Option { let file = self.files.remove(&serial)?; + self.by_use.remove(&(file.used, serial)); self.resident_bytes -= file.resident_cost(); self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); Some(file) @@ -261,12 +282,12 @@ impl Companions { } /// The least recently used companion holding memory, a body kept as /// written or a decoded one: the budget counts both, so both are evicted. + /// One step into the eviction order, not a walk of every companion. fn oldest_resident(&self, skip: Option) -> Option { - self.files + self.by_use .iter() - .filter(|(serial, file)| Some(**serial) != skip && file.resident_cost() > 0) - .min_by_key(|(_, file)| file.used) - .map(|(serial, _)| *serial) + .find(|(_, serial)| Some(*serial) != skip) + .map(|(_, serial)| *serial) } fn holding(&self) -> Holding { Holding { diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 32a6ba9949..1bb272dc5a 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -29,12 +29,6 @@ use std::{ os::unix::fs::FileExt, }; -/// Rounds one edit takes to make room in the resident budget before it spills -/// its own body instead. Each round either spills the least recently touched -/// body or finds no body to spill; another call's spill can take the room a -/// round just made, which is why a round is retried at all. -const SPILL_ROUNDS: usize = 4; - impl Kernel { /// READ of a companion, at most `count` bytes from `offset`, appended to /// `out`; `eof` when the reply reaches the companion's end. @@ -134,9 +128,11 @@ impl Kernel { self.edit_companion(serial, Edit::Size(size as usize))?; } let mut companions = self.companions(); - let tick = companions.tick(); + if companions.files.get(&serial).is_none() { + return Err(Status::Stale); + } + companions.use_serial(serial); let file = companions.files.get_mut(&serial).ok_or(Status::Stale)?; - file.used = tick; if let Some(mode) = sattr.mode { file.metadata.mode = mode & 0o777; } @@ -169,7 +165,7 @@ impl Kernel { // Held to the end: no other edit of this companion runs meanwhile. let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); let target = edit.target_len(); - for _ in 0..SPILL_ROUNDS { + loop { match self.edit_resident(serial, target, &edit)? { Room::Resident(stat) => return Ok(stat), Room::Spilled => break, @@ -261,22 +257,17 @@ impl Kernel { companions.attach(serial, file); Ok(stat) } - /// Spills the least recently used resident companions to disk (outside the - /// companion lock) until adding `need` bytes stays within `resident_budget`. - /// Returns `true` if `need` fits in resident memory afterwards. A victim - /// another call changed meanwhile is picked again on the next round; the - /// rounds are bounded by the index, and the caller then writes out its own - /// body, which needs no budget at all. + /// Spills the least recently used bodies to disk (outside the companion + /// lock) until adding `need` bytes stays within `resident_budget`. Returns + /// `true` if `need` fits in resident memory afterwards. Each round takes + /// the oldest entry of the eviction order, so a round costs one step into + /// it rather than a walk of every companion, and the rounds end when no + /// companion holding memory is left: a victim another call changed + /// meanwhile has moved to the newest end of the order, so it is not picked + /// twice, and the caller then writes out its own body, which needs no + /// budget at all. fn spill_for(&self, target: u64, need: usize) -> Result { - let mut rounds = { - let companions = self.companions(); - if companions.resident_bytes + need <= companions.resident_budget { - return Ok(true); - } - companions.files.len() - }; - while rounds > 0 { - rounds -= 1; + loop { let victim = { let companions = self.companions(); if companions.resident_bytes + need <= companions.resident_budget { @@ -287,11 +278,8 @@ impl Kernel { let Some(victim) = victim else { return Ok(false); }; - // A victim another call changed meanwhile leaves the next round to - // pick again; only a disk failure ends the loop. let _ = self.spill_one(victim, None)?; } - Ok(false) } /// Writes `serial`'s body out to the spill directory and switches it to /// that file, keeping at least `keep` bytes (all of them when `None`), diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 25aedc1d59..eaee250495 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -16,6 +16,7 @@ mod spy; #[path = "support/tree.rs"] mod tree; use client::{Client, Set, STALE}; +use layerfs_nfs::apple_double::SERIALS; use layerfs_nfs::apple_double_codec::{Attribute, Image}; use std::{ fs, @@ -51,6 +52,73 @@ fn image(finder: [u8; 32], attrs: &[(&[u8], Vec)]) -> Vec { .encode() } +/// The companions whose bodies the spill directory holds, by serial. +fn spill_serials(dir: &Path) -> Vec { + let mut serials: Vec = fs::read_dir(dir) + .map(|entries| { + entries + .flatten() + .filter_map(|entry| entry.file_name().to_str()?.parse().ok()) + .collect() + }) + .unwrap_or_default(); + serials.sort_unstable(); + serials +} + +#[test] +fn eviction_follows_the_order_of_use_not_the_shape_of_the_index() { + const HELD: usize = 64; + let base = temp("use-order"); + let tree = base.join("tree"); + source(&tree); + let spill = base.join("spill"); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(spill.clone()); + // Room for exactly 64 bodies of 16 bytes, so every body after the 64th + // takes the room of one other. + rig.companion_resident_bytes = 16 * HELD; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let body = pattern(50, 16); + let mut handles = Vec::with_capacity(HELD); + for n in 0..HELD { + c.touch(&root, format!("c{n}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._c{n}").as_bytes(), 0o644).unwrap(); + c.write(&ad.handle, 0, &body).unwrap(); + handles.push(ad.handle); + } + assert_eq!(server.held().companion_bytes, 16 * HELD); + assert!(spill_serials(&spill).is_empty(), "nothing is on disk yet"); + // Three bodies are read again, so they are the most recently used ones. + for n in [0, 1, 2] { + assert_eq!(c.read_all(&handles[n], 4096), body); + } + // Eight more bodies: the eight least recently used ones leave memory, in + // that order, and the three read again stay. + for n in HELD..HELD + 8 { + c.touch(&root, format!("c{n}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._c{n}").as_bytes(), 0o644).unwrap(); + c.write(&ad.handle, 0, &body).unwrap(); + } + let expected: Vec = (3..11).map(|n| SERIALS + n).collect(); + assert_eq!(spill_serials(&spill), expected); + assert_eq!(server.held().companion_bytes, 16 * HELD); + assert_eq!(server.held().companions, HELD + 8); + // The evicted bodies still hold their bytes, and the kept ones never left + // memory. + for n in [3, 7, 10, 0, 1, 2] { + assert_eq!(c.read_all(&handles[n], 4096), body, "companion {n}"); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn the_clients_write_sequence_is_served_byte_for_byte() { let base = temp("sequence"); From 0cbd34cd6509a451c696d61e6210a83bcdae615b Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:54:18 +0000 Subject: [PATCH 27/53] perf(nfs): adopt a spilled companion body without the rename under the lock (lp73) `Companions::adopt_spilled` ran `fs::rename` while holding the companion lock, so the module documentation's "file I/O never holds the companion lock" was not true of the step that puts the file in place. The adoption is now three steps with the lock dropped between them: `Companions::spill_target` (lock) answers the companion's own file and whether the body is still the one the file was written from, `fs::rename` runs outside the lock, and `Companions::commit_spilled` (lock) switches the body to `Body::Spilled` with its length. A reader keeps reading the body in memory until the rename is done, so no reader ever sees a half written or missing file. The exclusion the rename needs is the companion's own edit gate, which already means "one edit of this companion at a time": a gated edit holds it across its own adoption, and eviction now takes it with `try_lock`, skipping a companion another call is editing (it never waits for another call's I/O, so no two spills of one companion can meet at the file). `spill_for` therefore passes over a victim it could not spill instead of picking it again, and a companion that is gone is nothing to spill rather than an error. Review: finding 5 (disk I/O under the companion lock); the module docs of `edit.rs` and `apple_double_spill.rs` and `nfs.md` now state what the code does. Tests: `cargo test -p layerfs-nfs`: 48 passed, 0 failed (raw `test result` sum 49 with the child-process rerun of `spilled_companions_outnumber_the_open_file_limit`), including the spill, race and file-limit cases that adopt bodies. Production LOC: 164342 -> 164372 (delta +30) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 73f62efc2 (164342) and of the staged tree (164372). Engine +30. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 10 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 70 ++++++++--------- .../layerfs-nfs/src/apple_double/edit.rs | 75 ++++++++++++++++--- .../layerfs-nfs/src/apple_double_spill.rs | 6 +- 4 files changed, 111 insertions(+), 50 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index b325d78a29..5b110c5680 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -191,9 +191,13 @@ synthesizes the same bytes again. Partial writes, resource forks and other layouts stay as the client wrote them. Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` -together, spill outside the companion lock to -`..tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by -rename to `` only if unchanged (`used` tick); spilled bodies are opened +together, are written to `..tmp` (`create_new`, dir `0700`, file +`0600`) and renamed to ``, all of it outside the companion lock; the +body is committed as spilled under the lock afterwards, so a reader reads the +body in memory until its file is whole. One writer per companion is the edit +gate (`Companion::editing`): an edit holds it, and an eviction takes it with +`try_lock`, skipping a companion someone is editing. A rename is dropped when +the body changed since the snapshot (`used` tick), and a spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), recording length and bytes together and spilling its own body rather than diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 5d6b172af0..b5c43c1455 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -34,7 +34,7 @@ //! which removes that directory too. use crate::{ apple_double_codec::Image, - apple_double_spill::{io_status, now, spill_path, touch, unlink_paths, Edit}, + apple_double_spill::{now, spill_path, touch, unlink_paths, Edit}, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, @@ -44,7 +44,7 @@ use layerfs_workspace::ViewStat; use std::{ collections::{BTreeSet, HashMap}, fs, - path::{Path, PathBuf}, + path::PathBuf, sync::{atomic::Ordering, Arc, Mutex}, }; @@ -243,50 +243,52 @@ impl Companions { Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), } } - /// Renames the temporary file `temp`, which holds `serial`'s body of `len` - /// bytes, to the companion's own name in the spill directory and switches - /// the companion to it. With `used`, the tick the snapshot was read at, - /// only a companion nothing touched since and whose body is still in memory - /// (resident or decoded) takes it: a body another call changed or already - /// spilled stays, `Ok(false)` then, and `temp` is the caller's to unlink. - /// `None` is an edit's own body written out while it holds the companion's - /// edit gate, so no other edit can have changed it. - fn adopt_spilled( - &mut self, - serial: u64, - used: Option, - temp: &Path, - len: usize, - ) -> Result { - let path = self - .spill_dir - .as_ref() - .map(|dir| spill_path(dir, serial)) - .ok_or(Status::NoSpc)?; - let Some(file) = self.files.get_mut(&serial) else { - return Err(Status::Stale); - }; + /// Where a body a spill wrote out replaces its companion: the companion's + /// own file, or `None` when another call changed the body since the + /// snapshot (`used` is the tick read then, and only a body still in memory + /// can be replaced). The caller renames its file to that path itself, + /// outside this lock, and then commits the body with + /// [`Self::commit_spilled`]. + fn spill_target(&self, serial: u64, used: Option) -> Result, Status> { + let file = self.files.get(&serial).ok_or(Status::Stale)?; if let Some(used) = used { if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { - return Ok(false); + return Ok(None); } } - fs::rename(temp, path).map_err(|e| io_status(&e))?; - let mut file = self.detach(serial).ok_or(Status::Stale)?; + let dir = self.spill_dir.as_ref().ok_or(Status::NoSpc)?; + Ok(Some(spill_path(dir, serial))) + } + /// Commits the body whose bytes now sit at the companion's spill file: it + /// holds them on disk from now on, `len` bytes of them, which were the + /// whole body the file was written from. `false` when the companion is gone + /// or already holds a file, and the file just renamed into place is the + /// caller's to drop. + /// + /// The caller holds the companion's edit gate and no other call writes this + /// companion's file, so a body that changed between the snapshot and here + /// cannot be the body this file was written from. + fn commit_spilled(&mut self, serial: u64, len: usize) -> bool { + let Some(mut file) = self.detach(serial) else { + return false; + }; + if matches!(file.body, Body::Spilled) { + self.attach(serial, file); + return false; + } file.body = Body::Spilled; - // A shorter file than the companion had described is not the body any - // more. file.len = file.len.max(len); self.attach(serial, file); - Ok(true) + true } /// The least recently used companion holding memory, a body kept as /// written or a decoded one: the budget counts both, so both are evicted. - /// One step into the eviction order, not a walk of every companion. - fn oldest_resident(&self, skip: Option) -> Option { + /// The companions the caller will not take are passed over, one step into + /// the eviction order rather than a walk of every companion. + fn oldest_resident(&self, skip: &BTreeSet) -> Option { self.by_use .iter() - .find(|(_, serial)| Some(*serial) != skip) + .find(|(_, serial)| !skip.contains(serial)) .map(|(_, serial)| *serial) } fn holding(&self) -> Holding { diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 1bb272dc5a..e30816bf74 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -12,8 +12,10 @@ //! A body that does not fit the resident budget is spilled first, least //! recently touched first; the body that still does not fit is written out //! itself and edited in its file, which needs no budget. The file I/O never -//! holds the companion lock, and no descriptor is kept for a spilled body: -//! each operation opens its file by path and closes it again. +//! holds the companion lock: the file is written from a body read under the +//! lock and renamed to the companion's own name outside it, before the body is +//! committed as spilled under the lock again. No descriptor is kept for a +//! spilled body: each operation opens its file by path and closes it again. use super::{edited_len, record, Body, Companions, DECODED_ENTRY_BYTES, FILE_BYTES}; use crate::{ apple_double_spill::{create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Room}, @@ -24,9 +26,11 @@ use crate::{ use layerfs_mount_ports::operations::write::Stamp; use layerfs_workspace::ViewStat; use std::{ - fs::{File, OpenOptions}, + collections::BTreeSet, + fs::{self, File, OpenOptions}, io, os::unix::fs::FileExt, + path::Path, }; impl Kernel { @@ -128,7 +132,7 @@ impl Kernel { self.edit_companion(serial, Edit::Size(size as usize))?; } let mut companions = self.companions(); - if companions.files.get(&serial).is_none() { + if !companions.files.contains_key(&serial) { return Err(Status::Stale); } companions.use_serial(serial); @@ -267,27 +271,45 @@ impl Kernel { /// twice, and the caller then writes out its own body, which needs no /// budget at all. fn spill_for(&self, target: u64, need: usize) -> Result { + let mut skip = BTreeSet::from([target]); loop { let victim = { let companions = self.companions(); if companions.resident_bytes + need <= companions.resident_budget { return Ok(true); } - companions.oldest_resident(Some(target)) + companions.oldest_resident(&skip) }; let Some(victim) = victim else { return Ok(false); }; - let _ = self.spill_one(victim, None)?; + if !self.spill_one(victim, None)? { + // The body changed under the file written from it, or the + // companion's own edit holds it: this call does not pick it + // again, and the next round looks at the body after it. + skip.insert(victim); + } } } /// Writes `serial`'s body out to the spill directory and switches it to /// that file, keeping at least `keep` bytes (all of them when `None`), /// with the disk I/O outside the companion lock. `Ok(false)` when another /// call changed the companion, or already spilled it, while the file was - /// written: that temporary file is dropped and the caller decides again on - /// the body it now finds. + /// written, or when the companion's own edit holds it: that temporary file + /// is dropped and the caller decides again on the body it now finds. fn spill_one(&self, serial: u64, keep: Option) -> Result { + let gate = { + let companions = self.companions(); + match companions.files.get(&serial) { + Some(file) => file.editing.clone(), + None => return Ok(true), + } + }; + // One writer of a companion's file at a time: an edit of this companion + // is writing to it, and a spill may not wait for another call's I/O. + let Ok(_editing) = gate.try_lock() else { + return Ok(false); + }; let (dir, bytes, size, used) = { let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; @@ -301,9 +323,7 @@ impl Kernel { (dir, bytes, size, file.used) }; let temp = create_spilled(&dir, serial, &bytes, size as u64)?; - let adopted = self - .companions() - .adopt_spilled(serial, Some(used), &temp, size); + let adopted = self.adopt_spilled(serial, Some(used), &temp, size); if matches!(adopted, Ok(true)) { return Ok(true); } @@ -327,12 +347,43 @@ impl Kernel { (dir, bytes, size) }; let temp = create_spilled(&dir, serial, &bytes, size as u64)?; - let adopted = self.companions().adopt_spilled(serial, None, &temp, size); + let adopted = self.adopt_spilled(serial, None, &temp, size); if !matches!(adopted, Ok(true)) { unlink_paths([temp]); } adopted.map(|_| ()) } + /// Renames `temp`, holding `serial`'s body written out, onto the + /// companion's own spill file and switches the companion to it. The + /// rename runs outside the companion lock: a reader keeps reading the + /// body in memory until the rename is done and the body is committed + /// under the lock again, and the file is never visible half written. The + /// caller holds the companion's edit gate for the whole adoption, so no + /// other call writes this companion's file. + fn adopt_spilled( + &self, + serial: u64, + used: Option, + temp: &Path, + len: usize, + ) -> Result { + let path = match self.companions().spill_target(serial, used) { + Ok(Some(path)) => path, + Ok(None) => return Ok(false), + Err(status) => return Err(status), + }; + if let Err(e) = fs::rename(temp, &path) { + // The temporary file is the caller's to drop: nothing was adopted. + return Err(io_status(&e)); + } + let committed = self.companions().commit_spilled(serial, len); + if !committed { + // The companion is gone or already holds a file: the file just put + // in place is this call's to drop. + unlink_paths([path]); + } + Ok(committed) + } /// The spill directory's file of `serial`, opened for one operation and /// closed again when the returned descriptor drops: the export holds no /// descriptor per spilled companion. A file or directory that is gone diff --git a/engine/crates/layerfs-nfs/src/apple_double_spill.rs b/engine/crates/layerfs-nfs/src/apple_double_spill.rs index 738bcc0268..dc00914dbc 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_spill.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_spill.rs @@ -5,7 +5,11 @@ //! `pread`/`pwrite` by an operation that opens it and closes it again: the //! export holds no descriptor per spilled body. A spill writes a temporary //! `..tmp` that only the call adopting it renames to ``, so -//! two calls spilling the same companion never share a file. The directory +//! two calls spilling the same companion never share a file; the rename runs +//! outside the companion lock, once the renaming call holds the companion's +//! edit gate, and the body is committed as spilled under the lock afterwards. +//! A reader therefore keeps reading the body in memory until the file is +//! whole, and never sees a partial one. The directory //! and its files are this user's alone; the modes are set here rather than //! left to the caller's umask. use crate::attributes::Status; From 485dd2f1aded43ca6cc6475d57f7ed08a6fbb3c8 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:56:32 +0000 Subject: [PATCH 28/53] fix(nfs): serve a READ that raced a truncation as a short read (lp73) `companion_read` took the companion's length under the companion lock and then read the spilled file outside it with `read_exact_at`. A truncation landing between the two made the file shorter than the window, and `read_exact_at` turned that into `NFS3ERR_IO` for a read of bytes the client had already been told were there. One `read_at` of that window is the whole reply: the bytes the file still holds, however many, are a short read at the truncation point, and `eof` still follows the length the lock saw. No retry, no second read. Review: finding 6 (spurious `NFS3ERR_IO` from READ). Tests: new `a_read_racing_a_truncation_is_a_short_read_not_an_io_error`, 512 rounds of one client reading a 64 KiB spilled body while another truncates it to zero: every reply is the body or a prefix of it, and the test client panics on any error status. Anti-proof: with `read_exact_at` back the test fails at round 0 (`panicked at tests/support/client.rs:248: self.read(...).unwrap()`). Production LOC: 164372 -> 164374 (delta +2) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 0cbd34cd6 (164372) and of the staged tree (164374). Engine +2. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- .../layerfs-nfs/src/apple_double/edit.rs | 9 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 58 +++++++++++++++++++ 2 files changed, 65 insertions(+), 2 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index e30816bf74..8edb4be8f5 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -70,10 +70,15 @@ impl Kernel { (spilled, length, start, end) }; if spilled { + // One `pread` of the window the last lock saw, outside it: another + // call may have truncated the file since, and the bytes the file + // still holds are the reply - a short read, not an I/O error. let mut buf = vec![0u8; end - start]; - self.spill_file(serial, false)? - .read_exact_at(&mut buf, start as u64) + let read = self + .spill_file(serial, false)? + .read_at(&mut buf, start as u64) .map_err(|e| io_status(&e))?; + buf.truncate(read); out.extend_from_slice(&buf); } Ok(end as u64 >= length) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index eaee250495..3fa528a7ca 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -66,6 +66,64 @@ fn spill_serials(dir: &Path) -> Vec { serials } +#[test] +fn a_read_racing_a_truncation_is_a_short_read_not_an_io_error() { + let base = temp("read-truncate"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill")); + // Smaller than one body, so every read of the body is a `pread` of its file. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut reader = Client::connect(server.local_addr(), UID, GID); + let mut writer = Client::connect(server.local_addr(), UID, GID); + let root = reader.mnt("/"); + reader.touch(&root, b"raced", 0o644).unwrap(); + let ad = reader.touch(&root, b"._raced", 0o644).unwrap(); + let body = pattern(60, 64 * 1024); + reader.write(&ad.handle, 0, &body).unwrap(); + assert_eq!(server.held().companion_bytes, 0, "the body spilled"); + + // A length read under the companion lock and the bytes read outside it can + // disagree: the truncation below may land in between. The reply is then the + // bytes the file still holds, a short read, never `NFS3ERR_IO`. + let empty = Set { + size: Some(0), + ..Set::default() + }; + for round in 0..512 { + let start = std::sync::Barrier::new(2); + let (read, truncate) = std::thread::scope(|scope| { + let read = scope.spawn(|| { + start.wait(); + reader.read_all(&ad.handle, 64 * 1024) + }); + let truncate = scope.spawn(|| { + start.wait(); + writer.setattr(&ad.handle, empty, None) + }); + (read.join().unwrap(), truncate.join().unwrap()) + }); + truncate.unwrap(); + assert!( + body.starts_with(&read), + "round {round}: {} bytes read of the body or its truncation", + read.len() + ); + // The next round starts from the whole body again: nothing else runs + // while it is written back. + writer.write(&ad.handle, 0, &body).unwrap(); + assert_eq!(reader.getattr(&ad.handle).unwrap().size as usize, body.len()); + } + + drop((reader, writer)); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn eviction_follows_the_order_of_use_not_the_shape_of_the_index() { const HELD: usize = 64; From e3e46ae06906e0e8a1fea442b76c41fd7b256bb7 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:57:27 +0000 Subject: [PATCH 29/53] docs(nfs): record the AppleDouble scratch area as a disposable area (lp73) Owner decision 2 approved `/.appledouble/` on condition that the architecture and the cleanup docs name it a new disposable area. nfs.md and the code already described it; the two remaining places did not. `docs/architecture/engine/daemon/README.md`: the "Starts NFS serving" row of the startup table now says the same reclaim that force-unmounts leftovers deletes `/.appledouble` (directories `0700`, files `0600`, no fsync, no space reserved ahead) and touches nothing else under the mount home. `docs/general/cleanup.md`: the classification table gains the scratch area as a disposable per-mount resource, with what it is and who deletes it. The test that says reclaim removes only `.appledouble` is still here: `startup_reclaim_clears_leftover_companion_spill_directories` puts a `kept/` file beside a leftover `.appledouble/7/stale`, and asserts the first survives and the second does not. Review: owner decision 2, condition "document it in the kernel routes, NFS and cleanup docs, and keep the reclaim test". Tests: `cargo test -p layerfs-nfs` at this commit: 49 passed, 0 failed (raw `test result` sum 50 with the child-process rerun of `spilled_companions_outnumber_the_open_file_limit`), including that daemon test. Production LOC: 164374 -> 164374 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 485dd2f1a (164374) and of the staged tree (164374, engine 75,739 in both). Docs and tests only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/daemon/README.md | 2 +- docs/general/cleanup.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/architecture/engine/daemon/README.md b/docs/architecture/engine/daemon/README.md index 4697766de6..3720ea868c 100644 --- a/docs/architecture/engine/daemon/README.md +++ b/docs/architecture/engine/daemon/README.md @@ -62,7 +62,7 @@ layerfs-daemon --config | Takes a fresh incarnation | `generate_keypair()`; the public half is `DaemonStatus.instance` | [`application/owner.rs`](../../../../engine/crates/layerfs-daemon/src/application/owner.rs) | | Opens the Store | An installed SQLite file with the `Disposable` profile, or PostgreSQL (feature `postgresql`); `Sqlite { install: None }` waits for an install | [`application/owner.rs`](../../../../engine/crates/layerfs-daemon/src/application/owner.rs), [`Cargo.toml`](../../../../engine/crates/layerfs-daemon/Cargo.toml) | | Starts FUSE serving (Linux) | `/dev/fuse` to `0600`, checks the mount home, mounts a private `fusectl` tree for abort controls; if that fails, writes `LAYERFS_DAEMON_ABORT_UNBOUND` and starts without forced unmount | [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs) | -| Starts NFS serving | `ExportServing`; force-unmounts client mounts a previous daemon left (`LAYERFS_NFS_RECLAIM` lines); helper overrides `LAYERFS_NFS_MOUNT`, `_UNMOUNT`, `_FORCE`, `_FLUSH` | [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs) | +| Starts NFS serving | `ExportServing`; force-unmounts client mounts a previous daemon left (`LAYERFS_NFS_RECLAIM` lines); the same reclaim deletes `/.appledouble`, the AppleDouble companions' disposable scratch area (directories `0700`, files `0600`, no fsync, no space reserved ahead), and touches nothing else under the mount home; helper overrides `LAYERFS_NFS_MOUNT`, `_UNMOUNT`, `_FORCE`, `_FLUSH` | [`application/filesystem.rs`](../../../../engine/crates/layerfs-daemon/src/application/filesystem.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | ### Phases and Hello diff --git a/docs/general/cleanup.md b/docs/general/cleanup.md index 0de4bdc7c1..da5558e14c 100644 --- a/docs/general/cleanup.md +++ b/docs/general/cleanup.md @@ -79,6 +79,7 @@ net change; do not attribute an unisolated change entirely to one removal. | Historical sample databases, exports, and payloads | Closed run, no current consumer, records preserved, disposal authorized | Remove selected payloads and record that they are unavailable for future proof reuse | | Prepared fixture masters, inventories, sealed Stores, binaries, and images | Current task, harness defaults, source identities, and reuse records | Keep resources selected for ongoing work or qualifying reuse | | Docker sample containers and volumes | Exact mapping to closed run records, current processes, consumers, and ownership | Stop and remove the identified resources after ownership is established | +| AppleDouble companion scratch area, `/.appledouble//` in a Sandbox's mount home | Disposable per-mount area: directories `0700`, files `0600`, no fsync and no space reserved ahead; the daemon deletes it at export release and its startup reclaim deletes any it finds, touching nothing else in the mount home | Remove it with the mount home or Sandbox it belongs to; it never holds Workspace, Commit or Store state, so no proof needs it kept | | Inactive agent transcripts and text records | No writer; no pinned file identity or current allocation requirement | Prefer verified transparent compression where supported | | Live application databases, WAL files, active logs, and session state | Owning application and current use | Preserve | | Download, installer, browser, and package caches | Current consumers, installation activity, and supported pruning behavior | Remove unused staging files or prune through the appropriate installed tool | From e9f49fb64fab2cd64ac367ca0245aeb293545e71 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:20:53 +0000 Subject: [PATCH 30/53] fix(nfs): decide the AppleDouble slot bound in one place, before committing (lp73) The doc comment and `nfs.md` said the index was bounded by `HELD`, but `attach` inserted every slotted companion without a check: a WRITE that broke a whole image, a SETATTR or a RENAME onto an unknown main could grow `slots` past the bound with no `NFS3ERR_NOSPC`, and every `orphans()` walk then scaled with it. `Companions::admits(serial, slotted)` is now the single adjudication: a body that takes no slot is always admitted, a companion already holding one keeps it, and otherwise the bound decides. It is asked before anything is committed, so a refusal leaves the body, its length and its name exactly as they were: - CREATE asks it for a new companion, as before: reclaim the orphan slots once, re-read the name and its main file, then `NFS3ERR_NOSPC` with the counted and rate-limited log; - a WRITE, SETATTR or RENAME that needs a new slot asks it too. The body is edited to one side (`edit_resident` keeps the previous bytes only in this case) and put back if the slot is refused; a body that would be written out and edited on its file is refused before the file is touched, since such a body is no longer known to be a whole image. `edit_companion` then reclaims the orphans once, outside the companion lock, and applies the same edit once more; a second refusal is the whole edit's `NFS3ERR_NOSPC`. The orphan reclaim moves out of `companion_create` into `Kernel::reclaim_orphans` so both paths use the same one, and `nfs.md` records that `HELD` is the admission limit of this export-local shim (owner decision, option C, a scoped waiver, with option A deferred) and not a Workspace capacity. Review: blocking finding 1 and owner decisions D1/C, including the test the owner asked for on the write path. Tests: new `a_write_that_takes_the_last_slot_is_refused_by_the_bound`, which fills the bound through WRITE and not CREATE: three companions each created as a whole image (no slot), then broken by a write; the first two take the two slots, the third answers `NFS3ERR_NOSPC` and still reads back its image byte for byte, with all three companions and their two slots intact. Anti-proof: with `admits` off by one the new test fails at that assertion (`left: Ok(()), right: Err(28)`) and so do three index-bound tests. Production LOC: 164626 -> 164676 (delta +50) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 76adb9e22 (164626) and of the staged tree (164676). Engine +50. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 9 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 65 ++++++++++++------- .../layerfs-nfs/src/apple_double/edit.rs | 58 +++++++++++++++-- .../layerfs-nfs/src/apple_double_spill.rs | 11 ++++ .../layerfs-nfs/tests/apple_double_decode.rs | 60 +++++++++++++++++ 5 files changed, 174 insertions(+), 29 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index eaa55c7152..a6536a3b91 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -177,7 +177,7 @@ the export. | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 65,536 slotted companion entries | Reclaim orphan slotted companions; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs at most once per 60 s per export | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export) | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `RESIDENT_BYTES` | 32 MiB of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost` | Spill the least recently touched bodies, decoded ones included, to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | | `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | @@ -196,6 +196,13 @@ written bytes and occupy a slot. `companion_rename` re-classifies under the destination so moving onto an unknown main name takes a slot (a spilled body keeps its prior class). +`HELD` is the admission limit of this export-local shim, not a Workspace or +Sandbox capacity: the companions live for one mount, are deleted at release and +never reach the Workspace, the SQLite overlay or a Commit (owner decision, +2026-11-14, option C, a scoped waiver). Option A, a per-export SQLite index, is +deferred until `NFS3ERR_NOSPC` shows up in real use; it would add a `rusqlite` +dependency edge to `layerfs-nfs`, which the workspace already pins. + `Table::names` and `Table::aliases` index each serial's names so unlink, `entry_taken` (when `nlink <= 1`), `renamed` (keeping an overwritten recalled name as an alias) and retirement drop only that serial's keys from `by_name` diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index ac3420de31..f8f4824786 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -412,6 +412,14 @@ impl Companions { .find(|(_, serial)| !skip.contains(serial)) .map(|(_, serial)| *serial) } + /// Whether the index takes a companion that takes a slot of the bound: the + /// one place the bound is decided. A companion already holding a slot + /// keeps it, and a body that takes no slot is always admitted. + fn admits(&self, serial: Option, slotted: bool) -> bool { + !slotted + || serial.is_some_and(|serial| self.slots.contains(&serial)) + || self.slots.len() < self.held_limit + } fn holding(&self) -> Holding { Holding { held: self.files.len(), @@ -470,11 +478,12 @@ impl Kernel { let main = name.strip_prefix(b"._").filter(|main| !main.is_empty())?; self.table().by_name.get(&(parent, main.to_vec())).copied() } - /// The companions no name reaches any more: one whose main inode holds no - /// name in the kernel table, and one whose main file the export never - /// observed and does not know now. Taken under the kernel table lock and, - /// inside it, the companion lock, so nothing here copies the namespace; - /// the caller drops them by serial under the companion lock again. + /// The companion slots no name reaches any more: one whose main inode + /// holds no name in the kernel table, and one whose main file the export + /// never observed and does not know now. Taken under the kernel table lock + /// and, inside it, the companion lock, so nothing here copies the + /// namespace; the caller drops them by serial under the companion lock + /// again. fn orphans(&self) -> Vec<(u64, Option)> { let table = self.table(); let companions = self.companions(); @@ -495,6 +504,31 @@ impl Kernel { }) .collect() } + /// Drops the companion slots no name reaches any more and answers how many + /// it dropped. Takes the kernel table lock and, inside it, the companion + /// lock; the files it retires are unlinked afterwards, outside both. Never + /// call it under the companion lock. + fn reclaim_orphans(&self) -> usize { + let orphans = self.orphans(); + let (reclaimed, spilled) = { + let mut companions = self.companions(); + let mut spilled = Vec::new(); + let mut reclaimed = 0; + for (serial, inode) in orphans { + let still_orphan = companions + .files + .get(&serial) + .is_some_and(|file| file.inode == inode && file.slotted()); + if still_orphan { + reclaimed += 1; + spilled.extend(companions.take_serial(serial)); + } + } + (reclaimed, spilled) + }; + unlink_paths(spilled); + reclaimed + } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { let mut companions = self.companions(); @@ -560,12 +594,10 @@ impl Kernel { return self.companion_open(serial, how, directory, companions, tickets); } // At the index bound, reclaim the companions no name reaches any more - // first: found under the kernel table and the companion index, one - // entry at a time, so nothing here copies the namespace. - let mut reclaimed = Vec::new(); - if companions.slots.len() >= companions.held_limit { + // first, outside this lock. + if !companions.admits(None, true) { drop(companions); - let orphans = self.orphans(); + self.reclaim_orphans(); // The reclaim held no companion lock, so another CREATE of this // name may have inserted it meanwhile and the main file may have // changed: both are read again, and the name is inserted under the @@ -575,17 +607,8 @@ impl Kernel { if let Some(serial) = companions.resolve(&named, main) { return self.companion_open(serial, how, directory, companions, tickets); } - for (serial, inode) in orphans { - let still_orphan = companions - .files - .get(&serial) - .is_some_and(|file| file.inode == inode && file.slotted()); - if still_orphan { - reclaimed.extend(companions.take_serial(serial)); - } - } } - if companions.slots.len() >= companions.held_limit { + if !companions.admits(None, true) { let held = companions.slots.len(); let limit = companions.held_limit; let log = companions @@ -596,7 +619,6 @@ impl Kernel { companions.last_refusal_log = Some(Instant::now()); } drop(companions); - unlink_paths(reclaimed); let refused = self.names_refused.fetch_add(1, Ordering::Relaxed) + 1; if let Some(namespace) = namespace { eprintln!( @@ -629,7 +651,6 @@ impl Kernel { companions.index(serial, &file); companions.attach(serial, file); drop(companions); - unlink_paths(reclaimed); self.names_detached.fetch_add(1, Ordering::Relaxed); Ok((stat, directory)) } diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index dccabe7bca..05585b1526 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -18,7 +18,9 @@ //! spilled body: each operation opens its file by path and closes it again. use super::{edited_len, record, Body, Companions, Decoded, DECODED_ENTRY_BYTES, FILE_BYTES}; use crate::{ - apple_double_spill::{create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Room}, + apple_double_spill::{ + create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Edited, Room, + }, attributes::Status, change::{Sattr, Tickets, Wcc}, kernel::Kernel, @@ -173,10 +175,34 @@ impl Kernel { }; // Held to the end: no other edit of this companion runs meanwhile. let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); + match self.apply_edit(serial, &edit)? { + Edited::Done(stat) => Ok(stat), + Edited::NoSlot => { + // A body that takes a slot of the index bound has none: + // reclaim the companions no name reaches any more, once, + // outside the companion lock, and apply the same edit again. + // A bound that still has no room refuses the whole edit, with + // the body, its length and its name as they were. + if self.reclaim_orphans() == 0 { + return Err(Status::NoSpc); + } + match self.apply_edit(serial, &edit)? { + Edited::Done(stat) => Ok(stat), + Edited::NoSlot => Err(Status::NoSpc), + } + } + } + } + /// Applies `edit` to `serial` once: in the resident body while the budget + /// holds it, else in its spilled file. It answers that a slot of the index + /// bound is missing rather than changing anything, so the caller can make + /// room and try again. + fn apply_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { let target = edit.target_len(); loop { - match self.edit_resident(serial, target, &edit)? { - Room::Resident(stat) => return Ok(stat), + match self.edit_resident(serial, target, edit)? { + Room::Resident(stat) => return Ok(Edited::Done(stat)), + Room::NoSlot => return Ok(Edited::NoSlot), Room::Spilled => break, Room::Grow(need) => { // No other call changes this body, so a round that finds @@ -188,10 +214,16 @@ impl Kernel { } } // The body still does not fit resident memory: write it out and edit - // its file, which needs no body budget. + // its file, which needs no body budget. A body edited on its file is no + // longer known to be a whole image, so it takes a slot of the index + // bound: decide that before the file is written, and leave the body, + // its file and its name as they were when the bound has none. + if !self.companions().admits(Some(serial), true) { + return Ok(Edited::NoSlot); + } self.spill_gated(serial, target)?; edit.disk(&self.spill_file(serial, true)?)?; - self.record_edit(serial, &edit) + self.record_edit(serial, edit).map(Edited::Done) } /// Applies `edit` to `serial`'s body in memory while the budget holds it /// (a decoded body is encoded first), recording its length, recency and @@ -250,12 +282,26 @@ impl Kernel { return Ok(Room::Spilled); } }; + // A companion holding no slot while the bound is full may take one with + // this edit, and only the edited body says whether it does: its bytes + // are kept when that is the case, so a refusal puts them back exactly. + let restore = (!file.slotted() && !companions.admits(Some(serial), true)) + .then(|| (bytes.clone(), file.whole, file.len)); edit.memory(&mut bytes); file.body = Body::Resident(bytes); record(edit, &mut file); + companions.classify(&mut file); + if let Some((bytes, whole, len)) = restore { + if !companions.admits(Some(serial), file.slotted()) { + file.body = Body::Resident(bytes); + file.whole = whole; + file.len = len; + companions.attach(serial, file); + return Ok(Room::NoSlot); + } + } touch(&mut file.metadata); file.used = tick; - companions.classify(&mut file); let stat = Companions::stat(serial, &file); companions.attach(serial, file); Ok(Room::Resident(stat)) diff --git a/engine/crates/layerfs-nfs/src/apple_double_spill.rs b/engine/crates/layerfs-nfs/src/apple_double_spill.rs index dc00914dbc..c55d520070 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_spill.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_spill.rs @@ -152,4 +152,15 @@ pub(crate) enum Room { Spilled, /// Resident, but growing it needs this many more budget bytes first. Grow(usize), + /// The body takes a slot of the index bound and the bound has none. + NoSlot, +} + +/// What one application of an edit made of a companion. +pub(crate) enum Edited { + /// It landed; this is the companion's stat afterwards. + Done(layerfs_workspace::ViewStat), + /// The body would take a slot of the index bound and none is free, so + /// nothing was changed. + NoSlot, } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 990a2395b7..547a6406f5 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -411,6 +411,66 @@ fn a_resource_fork_keeps_the_stored_as_written_fallback() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { + let base = temp("write-bound"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // Two slots, reached through WRITE and not through CREATE: each companion + // is created as a whole image, which takes none, and then broken by a write + // that leaves it not whole, which takes one. + rig.companions_held = 2; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let mut images = Vec::new(); + for i in 0..3 { + c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); + let ad = c + .touch(&root, format!("._m{i}").as_bytes(), 0o644) + .unwrap(); + let whole = image( + [i as u8 + 1; 32], + &[(b"user.value", pattern(70 + i, 512 + i as usize))], + ); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + images.push((ad.handle, whole)); + } + assert_eq!(server.held().companions, 3); + assert_eq!(server.held().companions_slotted, 0, "no companion takes a slot"); + // Two writes that break an image take the two slots. + for i in 0..2 { + c.write(&images[i].0, 24, b"EDIT").unwrap(); + assert_eq!(server.held().companions_slotted, i + 1); + } + // The third would take one more, and the bound has none: the whole write is + // refused, and no companion loses a byte. + assert_eq!(c.write(&images[2].0, 24, b"EDIT").map(|_| ()), Err(NOSPC)); + assert_eq!(server.held().companions, 3, "no companion was dropped"); + assert_eq!(server.held().companions_slotted, 2); + for (handle, whole) in &images { + assert_eq!(c.getattr(handle).unwrap().size as usize, whole.len()); + } + assert_eq!( + c.read_all(&images[2].0, 64 * 1024), + images[2].1, + "the refused companion still holds its image" + ); + for i in 0..2 { + let mut broken = images[i].1.clone(); + broken[24..28].copy_from_slice(b"EDIT"); + assert_eq!(c.read_all(&images[i].0, 64 * 1024), broken); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn whole_images_take_no_slot_of_the_index_bound() { let base = temp("slots"); From 812cb846438936c000679de97d244590f57bc183 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:26:00 +0000 Subject: [PATCH 31/53] fix(nfs): settle the resident budget on a companion RENAME (lp73) `Companion::classify` turns a decoded body back into the client's bytes when the companion is renamed onto a name whose main file the export does not know, and `companion_rename` attached it without looking at `RESIDENT_BYTES`: one rename could put a whole image (up to `FILE_BYTES`) of bytes into a budget it does not fit, and nothing evicted it afterwards. `companion_rename` now resolves the serial and validates the name under the lock, then hands over to `rename_companion`, which takes the companion's edit gate and decides before committing: - a decoded body moving onto an unknown main would cost its image; when that does not fit the budget it is written out first (`spill_gated`, with the file written and renamed outside the companion lock under the gate), so it takes no budget at all and the rename only records the new name and class; - a companion that needs a slot of the index bound asks `Companions::admits`, reclaims the orphan slots once and is refused with `NFS3ERR_NOSPC` rather than exceeding the bound, leaving it under its old name. Review: finding 3 (a rename can exceed the resident budget). Tests: new `a_rename_onto_an_unknown_main_keeps_the_resident_budget`: a decoded image (226 bytes counted) and a 700-byte written body under a 1,024-byte budget, then `._a` renamed to `._zzz`, whose main file does not exist. The resident count is 700 afterwards (the image left memory, `companions_decoded` 0), the new name reads the image back byte for byte and `._a` is gone. Anti-proof: without the write-out the test fails with 4,796 bytes resident against a 1,024-byte budget. Production LOC: 164676 -> 164709 (delta +33) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent e9f49fb64 (164676) and of the staged tree (164709). Engine +33. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 5 +- engine/crates/layerfs-nfs/src/apple_double.rs | 69 ++++++++++++++++--- .../layerfs-nfs/src/apple_double/edit.rs | 2 +- .../layerfs-nfs/tests/apple_double_decode.rs | 46 +++++++++++++ 4 files changed, 110 insertions(+), 12 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index a6536a3b91..6b36a8febe 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -194,7 +194,10 @@ kept as written bytes, which take the same budget at their length; partial writes, resource forks, other layouts and unknown-main companions stay as written bytes and occupy a slot. `companion_rename` re-classifies under the destination so moving onto an unknown main name takes a slot (a spilled body -keeps its prior class). +keeps its prior class); a decoded body that would be the client's bytes again +and does not fit `RESIDENT_BYTES` is written out first, under the companion's +edit gate and outside the companion lock, so the rename never exceeds the +budget and only records the new name and class. `HELD` is the admission limit of this export-local shim, not a Workspace or Sandbox capacity: the companions live for one mount, are deleted at release and diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index f8f4824786..9dcebf4057 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -723,25 +723,74 @@ impl Kernel { ) -> Option> { let from_main = self.main_of(from, name); let to_main = self.main_of(to, new_name); + let serial = { + let companions = self.companions(); + companions.resolve(&(from, name.to_vec()), from_main)? + }; + if !crate::names::apple_double(new_name) || new_name.len() > 255 { + return Some(Err(Status::Access)); + } + Some(self.rename_companion(serial, (to, new_name.to_vec()), to_main)) + } + /// Moves `serial`'s companion to `target`, under `to_main`'s inode. + /// + /// The body is classified again under the destination, so a whole image + /// renamed onto an unknown main is the client's bytes again and takes a + /// slot: such a body no longer fits the resident budget as attributes, and + /// is written out first (outside the companion lock, with the companion's + /// edit gate held), so the rename itself only records a name and a class. + /// A companion that needs a new slot of the index bound takes the same + /// decision the edit path takes: the orphan slots are reclaimed once and + /// the rename is refused if the bound still has none. + fn rename_companion(&self, serial: u64, target: Named, to_main: Option) -> Result<(), Status> { + let gate = { + let companions = self.companions(); + companions.files.get(&serial).ok_or(Status::Stale)?.editing.clone() + }; + // Held to the end: the body written out below is the body renamed. + let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); + // A decoded body renamed onto an unknown main would cost its whole + // image of the resident budget: write it out instead, which costs none. + let leaves_memory = { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + match &file.body { + Body::Decoded(image) if to_main.is_none() => { + let cost = image.len(); + companions + .resident_bytes + .saturating_sub(image.cost()) + .saturating_add(cost) + > companions.resident_budget + } + _ => false, + } + }; + if leaves_memory { + self.spill_gated(serial, 0)?; + } + // A companion moved onto an unknown main takes a slot; one already + // holding a slot keeps it, and one that stays a whole image keeps its + // exemption. + if !self.companions().admits(Some(serial), to_main.is_none()) { + self.reclaim_orphans(); + if !self.companions().admits(Some(serial), to_main.is_none()) { + return Err(Status::NoSpc); + } + } let mut replaced_path = None; { let mut companions = self.companions(); - let serial = companions.resolve(&(from, name.to_vec()), from_main)?; - if !crate::names::apple_double(new_name) || new_name.len() > 255 { - return Some(Err(Status::Access)); - } - let target = (to, new_name.to_vec()); + let mut file = companions.detach(serial).ok_or(Status::Stale)?; + companions.unindex(serial, &file); if let Some(replaced) = companions.resolve(&target, to_main) { if replaced != serial { replaced_path = companions.take_serial(replaced); } } - let tick = companions.tick(); - let mut file = companions.detach(serial)?; - companions.unindex(serial, &file); file.named = target; file.inode = to_main; - file.used = tick; + file.used = companions.tick(); // A client may write a companion under another name first, and a // name it moves onto may belong to another main inode, or to // none: the body is classified again under the destination, so @@ -752,7 +801,7 @@ impl Kernel { companions.attach(serial, file); } unlink_paths(replaced_path); - Some(Ok(())) + Ok(()) } /// Drops every companion and removes the export's spill directory; returns /// what the index held. diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 05585b1526..a63a4752ca 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -392,7 +392,7 @@ impl Kernel { /// Writes `serial`'s body out while its own edit runs alone, keeping /// `size` bytes: no other edit can change the body, so the file written is /// the body this edit then applies to. - fn spill_gated(&self, serial: u64, size: usize) -> Result<(), Status> { + pub(super) fn spill_gated(&self, serial: u64, size: usize) -> Result<(), Status> { let (dir, bytes, size) = { let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 547a6406f5..6fc351a138 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -411,6 +411,52 @@ fn a_resource_fork_keeps_the_stored_as_written_fallback() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_rename_onto_an_unknown_main_keeps_the_resident_budget() { + let base = temp("rename-budget"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(base.join("spill")); + // Nearly full: a decoded image of a few hundred bytes and a written body + // of 700 bytes. + rig.companion_resident_bytes = 1024; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + c.touch(&root, b"a", 0o644).unwrap(); + let image_name = c.touch(&root, b"._a", 0o644).unwrap(); + let whole = image([0x31; 32], &[(b"user.small", pattern(80, 64))]); + c.write(&image_name.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_decoded, 1); + c.touch(&root, b"b", 0o644).unwrap(); + let other = c.touch(&root, b"._b", 0o644).unwrap(); + c.write(&other.handle, 0, &pattern(81, 700)).unwrap(); + let before = server.held(); + assert!(before.companion_bytes <= 1024, "{}", before.companion_bytes); + + // Onto a name whose main file the export does not know: the decoded body is + // the client's bytes again, which the budget does not take, so it leaves + // memory first and the rename still happens. + c.rename(&root, b"._a", &root, b"._zzz").unwrap(); + let after = server.held(); + assert_eq!( + after.companion_bytes, 700, + "only the written body takes the budget: the image left memory" + ); + assert_eq!(after.companions_decoded, 0); + let (moved, attr) = c.lookup(&root, b"._zzz").unwrap(); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&moved, 64 * 1024), whole); + assert_eq!(c.lookup(&root, b"._a").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let base = temp("write-bound"); From e9025300f7ccd023a282cedd05039c399a3fdab5 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:32:50 +0000 Subject: [PATCH 32/53] fix(nfs): confirm a companion's main file before reclaiming it (lp73) A companion created while its main name was missing from the export's name index got `inode: None`, and `orphans()` read that as "no main file": the name index is lossy (its own bound, a name the export never looked up, a rename on the client side), so a live companion could be reclaimed at the `HELD` bound and lose its attributes. `orphans()` now answers candidates, and `reclaim_orphans` decides on one whose main inode the export does not know with one read-only lookup of its main file in the engine (`Kernel::observe`), run outside the kernel table lock and the companion lock. A file that is there binds the companion back to that inode (`file.inode` and `Companions::inodes`), which keeps its attributes and makes every name of the inode reach it; only `NFS3ERR_NOENT` makes it an orphan; a lookup that cannot answer keeps it as it is. `Companions::slots` is unchanged, so a bound companion keeps the slot it took. Review: finding 4 (live data reclaimed as an orphan). Tests: new `a_companion_of_a_main_file_the_name_index_missed_is_kept`: the main file is part of the tree the export is initialized from and the export never looks its name up, so the companion created for it has no main inode, under a one-slot bound. The next CREATE reclaims, finds the main file, keeps the companion (`companions`/`companions_slotted` 1/1, `names_refused` 1), the image reads back byte for byte, and a hard link of the main file reaches the same companion. Anti-proof: reclaiming on the name index's word again drops it, and the test then fails when the refused CREATE succeeds instead. Production LOC: 164709 -> 164756 (delta +47) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 812cb8464 (164709) and of the staged tree (164756). Engine +47. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 7 +- engine/crates/layerfs-nfs/src/apple_double.rs | 104 +++++++++++++++--- engine/crates/layerfs-nfs/src/kernel.rs | 2 +- .../layerfs-nfs/tests/apple_double_decode.rs | 47 ++++++++ 4 files changed, 140 insertions(+), 20 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 6b36a8febe..d97d0bc841 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -214,7 +214,12 @@ collect orphans from `Companions::slots` (walking only slotted entries under the table and companion locks, never whole images or `by_name`), then re-acquires the lock and re-reads the companion name and main file before inserting, so concurrent GUARDED creates of one name yield one serial and one -`NFS3ERR_EXIST`. +`NFS3ERR_EXIST`. The name index is lossy (its own bound, a name never looked +up, a client-side rename), so a candidate whose main inode the export does not +know costs one read-only lookup of its main file in the engine, outside both +locks: a file that is there binds the companion back to that inode and keeps +its attributes, only `NFS3ERR_NOENT` makes it an orphan, and a lookup that +cannot answer leaves it alone. Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` together, are written to `..tmp` (`create_new`, dir `0700`, file diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 9dcebf4057..d03d69fc36 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -51,8 +51,11 @@ use crate::{ change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, }; -use layerfs_content::{filesystem::attributes::PortableMetadata, object::inode_leaf::InodeKind}; -use layerfs_workspace::ViewStat; +use layerfs_content::{ + filesystem::{attributes::PortableMetadata, PathName}, + object::inode_leaf::InodeKind, +}; +use layerfs_workspace::{KernelReadOperation, ViewStat}; use std::{ collections::{BTreeSet, HashMap, HashSet}, fs, @@ -125,6 +128,18 @@ impl Companion { } } +/// A slot of the index the export's own name index cannot reach, and what the +/// reclaim needs to decide about it. +struct Orphan { + serial: u64, + /// The main inode the export knows for it; an inode holding no name in the + /// kernel table is gone. + inode: Option, + /// Its main file's directory and name when it has no inode: the name index + /// is lossy, so only the engine can say whether that file is there. + main: Option, +} + /// What [`Companions::keep_decoded`] made of an edited body. pub(crate) enum Decoded { /// The companion holds the body's decoded form. @@ -480,11 +495,11 @@ impl Kernel { } /// The companion slots no name reaches any more: one whose main inode /// holds no name in the kernel table, and one whose main file the export - /// never observed and does not know now. Taken under the kernel table lock - /// and, inside it, the companion lock, so nothing here copies the - /// namespace; the caller drops them by serial under the companion lock - /// again. - fn orphans(&self) -> Vec<(u64, Option)> { + /// never observed and whose name its name index does not hold. Taken under + /// the kernel table lock and, inside it, the companion lock, so nothing + /// here copies the namespace; the caller drops them by serial under the + /// companion lock again. + fn orphans(&self) -> Vec { let table = self.table(); let companions = self.companions(); companions @@ -492,15 +507,25 @@ impl Kernel { .iter() .filter_map(|serial| { let file = companions.files.get(serial)?; - let live = match file.inode { - Some(inode) => { - table.names.contains_key(&inode) || table.aliases.contains_key(&inode) - } - None => file.named.1.strip_prefix(b"._").is_some_and(|main| { - table.by_name.contains_key(&(file.named.0, main.to_vec())) - }), - }; - (!live).then_some((*serial, file.inode)) + if let Some(inode) = file.inode { + let live = + table.names.contains_key(&inode) || table.aliases.contains_key(&inode); + return (!live).then_some(Orphan { + serial: *serial, + inode: Some(inode), + main: None, + }); + } + let main = file.named.1.strip_prefix(b"._")?; + let main = (file.named.0, main.to_vec()); + // A name the index does hold reaches the companion; one it does + // not hold only makes it a candidate, since that index is + // lossy. + (!table.by_name.contains_key(&main)).then_some(Orphan { + serial: *serial, + inode: None, + main: Some(main), + }) }) .collect() } @@ -508,13 +533,56 @@ impl Kernel { /// it dropped. Takes the kernel table lock and, inside it, the companion /// lock; the files it retires are unlinked afterwards, outside both. Never /// call it under the companion lock. + /// + /// A companion whose main inode the export does not know is not dropped on + /// the name index's word: that index is lossy (its own bound, a name the + /// export never looked up, a rename on the client side), so each one costs + /// one read-only lookup of its main file in the engine, run outside both + /// locks. A main file that is there binds the companion back to its inode, + /// which keeps its attributes; only a lookup that answers "no such file" + /// makes it an orphan, and one that cannot answer leaves it as it is. fn reclaim_orphans(&self) -> usize { - let orphans = self.orphans(); + let (bound, dead) = self.orphans().into_iter().fold( + (Vec::new(), Vec::new()), + |(mut bound, mut dead), orphan| { + let Some((parent, main)) = orphan.main else { + dead.push((orphan.serial, orphan.inode)); + return (bound, dead); + }; + match PathName::from_bytes(&main) { + Ok(name) => { + let lookup = KernelReadOperation::Lookup { parent, name }; + match self.observe(parent, None, lookup) { + Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), + Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), + // Unknown: the companion keeps its custody. + Err(_) => {} + } + } + Err(_) => {} + } + (bound, dead) + }, + ); let (reclaimed, spilled) = { let mut companions = self.companions(); let mut spilled = Vec::new(); let mut reclaimed = 0; - for (serial, inode) in orphans { + for (serial, main) in bound { + let Some(mut file) = companions.detach(serial) else { + continue; + }; + if file.inode.is_some() || !file.slotted() { + companions.attach(serial, file); + continue; + } + // Bound back to the inode the engine found: it keeps the slot it + // took, and from here it follows that inode's names. + file.inode = Some(main); + companions.index(serial, &file); + companions.attach(serial, file); + } + for (serial, inode) in dead { let still_orphan = companions .files .get(&serial) diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index a2e297e7fa..3540cfefb3 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -371,7 +371,7 @@ impl Kernel { let services = self.services.request(&self.fence).map_err(failure)?; Ok((services, self.requests.fetch_add(1, Ordering::Relaxed))) } - fn observe( + pub(crate) fn observe( &self, protected: u64, handle: Option, diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 6fc351a138..b57f134db5 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -457,6 +457,53 @@ fn a_rename_onto_an_unknown_main_keeps_the_resident_budget() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_of_a_main_file_the_name_index_missed_is_kept() { + let base = temp("orphan-live"); + let tree = base.join("tree"); + source(&tree); + // The main file is part of the tree the export is initialized from, and + // this export never looks its name up, so its name index does not hold it: + // the companion created for it has no main inode, which the export's own + // index reads as an orphan. + fs::write(tree.join("live"), b"the data file").unwrap(); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // One slot, so the next CREATE has to reclaim before it can ask. + rig.companions_held = 1; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let ad = c.touch(&root, b"._live", 0o644).unwrap(); + let whole = image([0x51; 32], &[(b"user.kept", pattern(90, 128))]); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The bound is full, so the next CREATE reclaims the orphan slots first. + // The main file is there, so the lookup keeps the companion and binds it to + // that inode, and the CREATE is then refused. + c.touch(&root, b"other", 0o644).unwrap(); + assert_eq!(c.touch(&root, b"._other", 0o644).map(|_| ()), Err(NOSPC)); + let held = server.held(); + assert_eq!((held.companions, held.companions_slotted), (1, 1)); + assert_eq!(held.names_refused, 1); + assert_eq!(c.getattr(&ad.handle).unwrap().size as usize, whole.len()); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole, "attributes kept"); + + // It belongs to that inode now: another name of the inode reaches it. + let live = c.lookup(&root, b"live").unwrap().0; + c.link(&live, &root, b"alias").unwrap(); + let (shared, attr) = c.lookup(&root, b"._alias").unwrap(); + assert_eq!(shared, ad.handle, "hard links share one companion"); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&shared, 64 * 1024), whole); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let base = temp("write-bound"); From 3c3558f19aff6ad6290cadac4082699b56c33a8e Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:34:33 +0000 Subject: [PATCH 33/53] chore(nfs): make the AppleDouble companion edits fmt- and clippy-clean (lp73) `cargo fmt --check` reported four files of this branch and `cargo clippy --workspace --all-targets -D warnings` two lint findings in the new tests (`needless_range_loop`) and one in `reclaim_orphans` (`single_match`). This is that pass and nothing else: no behaviour changes. The one remaining fmt report, `api/crates/layerfs-cli/tests/concurrent_reads.rs`, is not touched by this branch (`git log 8cfb6e273..HEAD -- ` is empty) and is left alone. Checks: `cargo +1.85.1 fmt --all -- --check` reports only that file; `cargo +1.85.1 clippy --locked --workspace --exclude layerfs-node --all-targets -- -D warnings` is clean; `python3 -B tools/check_product_boundary.py --skip-sdk` PASS, `python3 -B tools/check_fuser_integrity.py` no errors, `python3 -B -m unittest discover -s tools -p 'test_*.py'` 188 OK. `cargo test -p layerfs-nfs`: 67 passed, 0 failed (raw sum 68 with the child-process rerun). Production LOC: 164756 -> 164768 (delta +12) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent e9025300f (164756) and of the staged tree (164768). Engine +12: rustfmt splits three long signatures and calls and the `if let` rewrites one match, which the counter counts. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double.rs | 32 ++++++++------ .../layerfs-nfs/src/apple_double_codec.rs | 7 ++- .../layerfs-nfs/tests/apple_double_codec.rs | 5 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 43 +++++++++++-------- 4 files changed, 56 insertions(+), 31 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index d03d69fc36..07ecc66d51 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -549,17 +549,15 @@ impl Kernel { dead.push((orphan.serial, orphan.inode)); return (bound, dead); }; - match PathName::from_bytes(&main) { - Ok(name) => { - let lookup = KernelReadOperation::Lookup { parent, name }; - match self.observe(parent, None, lookup) { - Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), - Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), - // Unknown: the companion keeps its custody. - Err(_) => {} - } + // A name the engine cannot even take, or a lookup it cannot + // answer, leaves the companion as it is. + if let Ok(name) = PathName::from_bytes(&main) { + let lookup = KernelReadOperation::Lookup { parent, name }; + match self.observe(parent, None, lookup) { + Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), + Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), + Err(_) => {} } - Err(_) => {} } (bound, dead) }, @@ -810,10 +808,20 @@ impl Kernel { /// A companion that needs a new slot of the index bound takes the same /// decision the edit path takes: the orphan slots are reclaimed once and /// the rename is refused if the bound still has none. - fn rename_companion(&self, serial: u64, target: Named, to_main: Option) -> Result<(), Status> { + fn rename_companion( + &self, + serial: u64, + target: Named, + to_main: Option, + ) -> Result<(), Status> { let gate = { let companions = self.companions(); - companions.files.get(&serial).ok_or(Status::Stale)?.editing.clone() + companions + .files + .get(&serial) + .ok_or(Status::Stale)? + .editing + .clone() }; // Held to the end: the body written out below is the body renamed. let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs index 1e45130f78..459b507c96 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -238,7 +238,12 @@ impl Image { let name_end = name_at + attr.name.len(); emit(&mut out, start, name_at, &attr.name); let next = entry + entry_len(name_len); - emit(&mut out, start, name_end + 1, &attr.pad[..next - name_end - 1]); + emit( + &mut out, + start, + name_end + 1, + &attr.pad[..next - name_end - 1], + ); emit(&mut out, start, value_at, &attr.value); entry = next; value_at += attr.value.len(); diff --git a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs index b4d0c32098..548eeb87a9 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs @@ -96,7 +96,10 @@ fn any_window_of_the_image_encodes_to_that_window() { assert_eq!(built.encode_range(len + 10, len + 20), Vec::::new()); assert_eq!(built.encode_range(7, 3), Vec::::new()); assert_eq!(built.encode_range(0, len + 10), bytes); - assert_eq!(built.encode_range(len - 1, len + 10), bytes[len - 1..].to_vec()); + assert_eq!( + built.encode_range(len - 1, len + 10), + bytes[len - 1..].to_vec() + ); // The fork's own bytes are not all zero: a window inside it is served // from the fork, not from the zeroed layout. let fork_at = get32(&bytes, FORK_AT) as usize; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index b57f134db5..73a1c28db6 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -197,7 +197,10 @@ fn a_read_racing_a_truncation_is_a_short_read_not_an_io_error() { // The next round starts from the whole body again: nothing else runs // while it is written back. writer.write(&ad.handle, 0, &body).unwrap(); - assert_eq!(reader.getattr(&ad.handle).unwrap().size as usize, body.len()); + assert_eq!( + reader.getattr(&ad.handle).unwrap().size as usize, + body.len() + ); } drop((reader, writer)); @@ -520,9 +523,7 @@ fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let mut images = Vec::new(); for i in 0..3 { c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); - let ad = c - .touch(&root, format!("._m{i}").as_bytes(), 0o644) - .unwrap(); + let ad = c.touch(&root, format!("._m{i}").as_bytes(), 0o644).unwrap(); let whole = image( [i as u8 + 1; 32], &[(b"user.value", pattern(70 + i, 512 + i as usize))], @@ -532,11 +533,15 @@ fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { images.push((ad.handle, whole)); } assert_eq!(server.held().companions, 3); - assert_eq!(server.held().companions_slotted, 0, "no companion takes a slot"); + assert_eq!( + server.held().companions_slotted, + 0, + "no companion takes a slot" + ); // Two writes that break an image take the two slots. - for i in 0..2 { - c.write(&images[i].0, 24, b"EDIT").unwrap(); - assert_eq!(server.held().companions_slotted, i + 1); + for (taken, (handle, _)) in images.iter().take(2).enumerate() { + c.write(handle, 24, b"EDIT").unwrap(); + assert_eq!(server.held().companions_slotted, taken + 1); } // The third would take one more, and the bound has none: the whole write is // refused, and no companion loses a byte. @@ -551,10 +556,10 @@ fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { images[2].1, "the refused companion still holds its image" ); - for i in 0..2 { - let mut broken = images[i].1.clone(); + for (handle, whole) in images.iter().take(2) { + let mut broken = whole.clone(); broken[24..28].copy_from_slice(b"EDIT"); - assert_eq!(c.read_all(&images[i].0, 64 * 1024), broken); + assert_eq!(c.read_all(handle, 64 * 1024), broken); } drop(c); @@ -737,16 +742,16 @@ fn eviction_takes_the_decoded_body_before_the_written_ones() { let root = c.mnt("/"); // A whole image, decoded: it costs its attributes, not its 4 KiB. - let whole = image( - [0x21; 32], - &[(b"com.apple.provenance", pattern(40, 40))], - ); + let whole = image([0x21; 32], &[(b"com.apple.provenance", pattern(40, 40))]); c.touch(&root, b"old", 0o644).unwrap(); let old = c.touch(&root, b"._old", 0o644).unwrap(); c.write(&old.handle, 0, &whole).unwrap(); assert_eq!(server.held().companions_decoded, 1); let decoded_cost = server.held().companion_bytes; - assert!(decoded_cost < 4096, "the image is counted as its attributes"); + assert!( + decoded_cost < 4096, + "the image is counted as its attributes" + ); // Two bodies kept as written fill the budget: the decoded body is the least // recently used memory there is, so it is the one spilled, and its file @@ -765,7 +770,11 @@ fn eviction_takes_the_decoded_body_before_the_written_ones() { "the decoded body was the memory evicted" ); assert_eq!(server.held().companion_bytes, 4000); - assert_eq!(c.read_all(&old.handle, 64 * 1024), whole, "from its spill file"); + assert_eq!( + c.read_all(&old.handle, 64 * 1024), + whole, + "from its spill file" + ); assert_eq!(c.read_all(&one.handle, 64 * 1024), first); assert_eq!(c.read_all(&two.handle, 64 * 1024), second); assert_eq!(c.getattr(&old.handle).unwrap().size as usize, whole.len()); From 428ffc34b9d2717a2e6e2d8970720f9a6beaaa47 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:45:48 +0000 Subject: [PATCH 34/53] chore(nfs): make the AppleDouble codec edits fmt- and clippy-clean (lp73) `cargo fmt --check` reported three files of this layer: the `emit` call rustfmt wraps in `Image::encode_range`, and two assertions of the new codec and decode tests. This is that pass and nothing else. The one remaining fmt report, `api/crates/layerfs-cli/tests/concurrent_reads.rs`, is not touched by this branch (`git log 8cfb6e273..HEAD -- ` is empty) and is left alone. Checks: `cargo +1.85.1 fmt --all -- --check` reports only that file; `cargo +1.85.1 clippy --locked -p layerfs-nfs --all-targets -- -D warnings` is clean; `cargo test -p layerfs-nfs` passes every binary. Production LOC: 163896 -> 163901 (delta +5) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 7ef50a034 (163896) and of the staged tree (163901). Engine +5: rustfmt splits the `emit` call, which the counter counts. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- engine/crates/layerfs-nfs/src/apple_double_codec.rs | 7 ++++++- engine/crates/layerfs-nfs/tests/apple_double_codec.rs | 5 ++++- engine/crates/layerfs-nfs/tests/apple_double_decode.rs | 1 - 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs index 1e45130f78..459b507c96 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -238,7 +238,12 @@ impl Image { let name_end = name_at + attr.name.len(); emit(&mut out, start, name_at, &attr.name); let next = entry + entry_len(name_len); - emit(&mut out, start, name_end + 1, &attr.pad[..next - name_end - 1]); + emit( + &mut out, + start, + name_end + 1, + &attr.pad[..next - name_end - 1], + ); emit(&mut out, start, value_at, &attr.value); entry = next; value_at += attr.value.len(); diff --git a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs index b4d0c32098..548eeb87a9 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_codec.rs @@ -96,7 +96,10 @@ fn any_window_of_the_image_encodes_to_that_window() { assert_eq!(built.encode_range(len + 10, len + 20), Vec::::new()); assert_eq!(built.encode_range(7, 3), Vec::::new()); assert_eq!(built.encode_range(0, len + 10), bytes); - assert_eq!(built.encode_range(len - 1, len + 10), bytes[len - 1..].to_vec()); + assert_eq!( + built.encode_range(len - 1, len + 10), + bytes[len - 1..].to_vec() + ); // The fork's own bytes are not all zero: a window inside it is served // from the fork, not from the zeroed layout. let fork_at = get32(&bytes, FORK_AT) as usize; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index dea993d169..73fe47c666 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -156,4 +156,3 @@ fn the_clients_write_sequence_is_served_byte_for_byte() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } - From ec17db8711d12b786daf8f666da78efe83c9163e Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:40:39 +0000 Subject: [PATCH 35/53] fix(nfs): keep an eviction victim's failure out of the writer's reply (lp73) `spill_for` passed a victim's error straight out with `?`. A victim another call had just removed answered `NFS3ERR_STALE`, and one whose spill file could not be written answered `NFS3ERR_NOSPC`/`NFS3ERR_IO`, so an unrelated WRITE failed on a companion it never named while its own body was still in memory. A victim that leaves nothing to give back, that another call changed under its file, that its own edit holds, or that cannot be written out is now passed over and the round looks at the body after it. The writer only answers its own error, from spilling its own body, which needs no budget; a writer that finds no room and cannot write out its own body still reports that. Review: finding P2-2 (an eviction victim's error reaching an unrelated writer). The report claimed this was already skipped; the code and the report now agree. Tests: new `an_eviction_victim_that_cannot_be_written_out_does_not_fail_the_writer`. Two resident bodies of 1,000 bytes in a 2,000-byte budget, the oldest one's spill path made a non-empty directory so its spill cannot be adopted, then a third 1,000-byte write: it lands, the oldest body stays in memory byte-identical, the second is on disk and reads back, and only that one file is in the spill directory. Anti-proof: with `?` back the third write answers `NFS3ERR_IO` (`Err value: 5`) and the test fails on it. Production LOC: 164379 -> 164379 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent bdb87afaa (164379) and of the staged tree (164379). Engine 0: the round's condition keeps one line and the rest is comment. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 4 +- .../layerfs-nfs/src/apple_double/edit.rs | 15 +++-- .../layerfs-nfs/tests/apple_double_decode.rs | 63 ++++++++++++++++++- 3 files changed, 76 insertions(+), 6 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 5b110c5680..f5d9a151f8 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -196,7 +196,9 @@ together, are written to `..tmp` (`create_new`, dir `0700`, file body is committed as spilled under the lock afterwards, so a reader reads the body in memory until its file is whole. One writer per companion is the edit gate (`Companion::editing`): an edit holds it, and an eviction takes it with -`try_lock`, skipping a companion someone is editing. A rename is dropped when +`try_lock`, skipping a companion someone is editing, one another call removed +and one whose file cannot be written out; only a call that finds no room and +then cannot write out its own body answers its own error. A rename is dropped when the body changed since the snapshot (`used` tick), and a spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 8edb4be8f5..8e24ffb9e8 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -275,6 +275,12 @@ impl Kernel { /// meanwhile has moved to the newest end of the order, so it is not picked /// twice, and the caller then writes out its own body, which needs no /// budget at all. + /// + /// A victim that cannot be written out is no failure of this call: one + /// another call removed has nothing left to give back, and one whose file + /// cannot be written keeps its body in memory, so the round passes over it + /// and looks at the body after it. Only a call that finds no room and then + /// cannot write out its own body reports that error, and it is its own. fn spill_for(&self, target: u64, need: usize) -> Result { let mut skip = BTreeSet::from([target]); loop { @@ -288,10 +294,11 @@ impl Kernel { let Some(victim) = victim else { return Ok(false); }; - if !self.spill_one(victim, None)? { - // The body changed under the file written from it, or the - // companion's own edit holds it: this call does not pick it - // again, and the next round looks at the body after it. + if self.spill_one(victim, None) != Ok(true) { + // The body changed under the file written from it, the + // companion's own edit holds it, or its file could not be + // written: this call does not pick it again, and the next + // round looks at the body after it. skip.insert(victim); } } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 5b2508abd5..4afab58a26 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -58,7 +58,10 @@ fn spill_serials(dir: &Path) -> Vec { .map(|entries| { entries .flatten() - .filter_map(|entry| entry.file_name().to_str()?.parse().ok()) + .filter_map(|entry| { + entry.file_type().ok().filter(std::fs::FileType::is_file)?; + entry.file_name().to_str()?.parse().ok() + }) .collect() }) .unwrap_or_default(); @@ -421,3 +424,61 @@ fn a_decoded_companion_is_edited_under_a_full_resident_budget() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn an_eviction_victim_that_cannot_be_written_out_does_not_fail_the_writer() { + let base = temp("victim-error"); + let tree = base.join("tree"); + source(&tree); + let spill = base.join("spill"); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companion_spill_dir = Some(spill.clone()); + // Room for two bodies of 1,000 bytes: a third one makes the two oldest + // give their room back. + rig.companion_resident_bytes = 2000; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let mut bodies = Vec::new(); + for i in 0..2 { + c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._m{i}").as_bytes(), 0o644).unwrap(); + let body = pattern(60 + i, 1000); + c.write(&ad.handle, 0, &body).unwrap(); + bodies.push((ad.handle, body)); + } + assert_eq!(server.held().companion_bytes, 2000); + + // The oldest body's spill file is a directory with a file in it, so no + // file can be renamed onto it: evicting that body fails. + let oldest = format!("{SERIALS}"); + fs::create_dir_all(spill.join(&oldest)).unwrap(); + fs::write(spill.join(&oldest).join("kept"), b"not a spill file").unwrap(); + + // A third body needs room. The victim that cannot be written out is + // passed over, the next one gives its room back, and this call's own + // write lands: the failure belonged to a companion this writer never + // named. + c.touch(&root, b"m2", 0o644).unwrap(); + let third = c.touch(&root, b"._m2", 0o644).unwrap(); + let body = pattern(62, 1000); + c.write(&third.handle, 0, &body).unwrap(); + assert_eq!(c.read_all(&third.handle, 4096), body); + assert_eq!( + spill_serials(&spill), + vec![SERIALS + 1], + "the victim whose file cannot be written stays in memory" + ); + assert_eq!(server.held().companion_bytes, 2000); + // Both other bodies still read back byte for byte: the spilled one from + // its file, the passed-over one from memory. + for (handle, want) in &bodies { + assert_eq!(&c.read_all(handle, 4096), want); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From aec83af3a66c5fcd9f5dd6a5d2c34da6390719f2 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:41:48 +0000 Subject: [PATCH 36/53] fix(nfs): leave a failed disk edit's length where it was (lp73) Three edges of the spill path, none of them a behaviour the client can rely on today: - A body written out whole is spilled at the length the edit wanted, and `commit_spilled` records that longer length before the edit touches the file. A `write_all_at`/`set_len` that then fails (`NFS3ERR_NOSPC`, `NFS3ERR_IO`) answered the error but left the companion longer, zero-filled: a refused edit that had changed the body's size. `apply_edit` now keeps the length the companion had and puts it back when the file operation fails, so a failed WRITE/SETATTR leaves the length as it was, as a refused slot does. - `spill_one` took the victim's edit gate with `try_lock` and read every `Err` as "busy", `Poisoned` included: a companion whose edit panicked could never be evicted, so it held its body for the export's life. A poisoned gate is now taken anyway, as every other holder of it does. - A spilled READ's one `pread` answered `NFS3ERR_IO` when a signal interrupted it, although no byte of it had moved. It is asked again in that case only; the read is still one read of one window, and a short read is still the reply. Review: findings P3-2, P3-3 and P3-5. Tests: none new. The length restore only shows on a filesystem error after a successful spill (the file is already at the wanted length, so `RLIMIT_FSIZE` and a directory at the spill path fail before it), the poisoned gate needs a panicking edit, and `EINTR` needs a signal landing inside one `pread`; all three are timing- or filesystem-dependent, and the change is a guard each. `cargo test -p layerfs-nfs`: 51 passed, 0 failed (raw sum 52 with the child-process rerun). Production LOC: 164379 -> 164405 (delta +26) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent ec17db871 (164379) and of the staged tree (164405). Engine +26: the length snapshot and restore (8), the poisoned-gate match (5), the interrupted-read loop and its helper (11), and the two rewritten error paths. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 4 +- .../layerfs-nfs/src/apple_double/edit.rs | 55 +++++++++++++++---- 2 files changed, 48 insertions(+), 11 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index f5d9a151f8..308e1fd69e 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -203,7 +203,9 @@ the body changed since the snapshot (`used` tick), and a spilled body is opened by path per `pread`/`pwrite`/`set_len` and never held open. One edit per companion runs under `Companion::editing` ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), recording length and bytes together and spilling its own body rather than -failing with `NFS3ERR_IO`. Eviction follows `Companions::by_use`, the +failing with `NFS3ERR_IO`. A file operation that fails after the spill put the +length the companion had back, so a refused write reports neither bytes nor the +longer file the spill made for it. Eviction follows `Companions::by_use`, the `(used tick, serial)` order kept on attach, detach and every use: the victim is the first entry (O(log n) per round, no walk of the index), and the rounds end when no companion holding memory is left. diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 8e24ffb9e8..f02eca56e0 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -33,6 +33,18 @@ use std::{ path::Path, }; +/// One `pread` of `buf` at `offset`: a short read is the answer, and a read a +/// signal interrupted is asked again, since no bytes of it moved. +fn read_window(file: &File, buf: &mut [u8], offset: u64) -> Result { + loop { + match file.read_at(buf, offset) { + Ok(read) => return Ok(read), + Err(e) if e.kind() == io::ErrorKind::Interrupted => {} + Err(e) => return Err(io_status(&e)), + } + } +} + impl Kernel { /// READ of a companion, at most `count` bytes from `offset`, appended to /// `out`; `eof` when the reply reaches the companion's end. @@ -74,10 +86,7 @@ impl Kernel { // call may have truncated the file since, and the bytes the file // still holds are the reply - a short read, not an I/O error. let mut buf = vec![0u8; end - start]; - let read = self - .spill_file(serial, false)? - .read_at(&mut buf, start as u64) - .map_err(|e| io_status(&e))?; + let read = read_window(&self.spill_file(serial, false)?, &mut buf, start as u64)?; buf.truncate(read); out.extend_from_slice(&buf); } @@ -188,11 +197,33 @@ impl Kernel { } } // The body still does not fit resident memory: write it out and edit - // its file, which needs no body budget. - self.spill_gated(serial, target)?; - edit.disk(&self.spill_file(serial, true)?)?; + // its file, which needs no body budget. A failed file operation leaves + // the length the companion had: the spill may have grown its file to + // the length this edit wanted, and a refused edit must not report it. + let before = self + .companions() + .files + .get(&serial) + .map(|file| file.len) + .ok_or(Status::Stale)?; + let written = self.spill_gated(serial, target).and_then(|()| { + let file = self.spill_file(serial, true)?; + edit.disk(&file) + }); + if let Err(status) = written { + self.restore_len(serial, before); + return Err(status); + } self.record_edit(serial, &edit) } + /// Puts back the length `serial` had before an edit whose file operation + /// failed. + fn restore_len(&self, serial: u64, len: usize) { + let mut companions = self.companions(); + if let Some(file) = companions.files.get_mut(&serial) { + file.len = len; + } + } /// Applies `edit` to `serial`'s body in memory while the budget holds it /// (a decoded body is encoded first), recording its length, recency and /// time and deciding again whether it is a whole image, under the same @@ -318,9 +349,13 @@ impl Kernel { } }; // One writer of a companion's file at a time: an edit of this companion - // is writing to it, and a spill may not wait for another call's I/O. - let Ok(_editing) = gate.try_lock() else { - return Ok(false); + // is writing to it, and a spill may not wait for another call's I/O. A + // gate poisoned by a panic is taken anyway, as every other holder of it + // does, so one panicked edit does not make its body undevictable. + let _editing = match gate.try_lock() { + Ok(editing) => editing, + Err(std::sync::TryLockError::Poisoned(poison)) => poison.into_inner(), + Err(std::sync::TryLockError::WouldBlock) => return Ok(false), }; let (dir, bytes, size, used) = { let companions = self.companions(); From f6cb67819ed36f4562d1d59980618ea2077eda81 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:54:57 +0000 Subject: [PATCH 37/53] fix(nfs): register the main file a reclamation's lookup found (lp73) A companion whose main inode the export did not know was, at the `HELD` bound, looked up in the engine and bound back to the inode that lookup found. The binding only set `Companion::inode`: the export's table never learned the name, so `orphans()` still read the companion as an inode holding no name at all, and the *next* reclamation dropped it and lost its attributes. The deciding visit also took one engine lookup reference that the export never recorded and never gave back, so every bound companion leaked one. The successful lookup now goes through `Kernel::entry_taken`, the same call `Kernel::lookup` and every creating mutation make: it remembers the name, takes the one reference the export keeps per serial (forgetting a second) and records the directory. The bound companion is then live for the next reclamation and its reference is given back with the rest in `Kernel::release`. Review: finding P1-1 (the fix for the reclamation lookup was incomplete and leaked a reference). Tests: new `a_companion_bound_back_to_its_main_file_survives_the_next_reclaim`: one slot, a companion for a main file in the initialized tree that this export never looks up, one reclamation that binds it (the export's lookup count grows by exactly one) and a second one with the bound still full, during which the companion keeps its slot, its bytes and its attributes and the export's count does not move; then the main file's last name goes and the companion with it. Anti-proof: without `entry_taken` the test fails at that count (`left: 1, right: 2`), and with the count assertions out of the way it fails on the second reclamation, which now succeeds because it dropped the live companion (`left: Ok(()), right: Err(28)`). Production LOC: 164794 -> 164797 (delta +3) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent c94693a9a (164794) and of the staged tree (164797). Engine +3: the registration call and the comment block around it. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 7 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 12 +++- .../layerfs-nfs/tests/apple_double_decode.rs | 58 ++++++++++++++++++- 3 files changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 0635334f59..1b7d78c8a1 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -219,7 +219,12 @@ up, a client-side rename), so a candidate whose main inode the export does not know costs one read-only lookup of its main file in the engine, outside both locks: a file that is there binds the companion back to that inode and keeps its attributes, only `NFS3ERR_NOENT` makes it an orphan, and a lookup that -cannot answer leaves it alone. +cannot answer leaves it alone. The lookup that finds the main file took one +engine reference on it, and the export keeps exactly one per serial, so the +visit registers the name it found the file under (`Kernel::entry_taken`, as +`Kernel::lookup` does) before the companion is bound: that name is what makes +the bound companion live for the next reclamation, and its reference is the one +the export later gives back. Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES` together, are written to `..tmp` (`create_new`, dir `0700`, file diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 07ecc66d51..3b578429d3 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -541,6 +541,13 @@ impl Kernel { /// locks. A main file that is there binds the companion back to its inode, /// which keeps its attributes; only a lookup that answers "no such file" /// makes it an orphan, and one that cannot answer leaves it as it is. + /// + /// A lookup that finds the main file took one engine reference on it, and + /// the export keeps exactly one per serial: the visit is the entry's, so it + /// is registered as `Kernel::lookup` registers one (`entry_taken` remembers + /// the name and forgets a second reference). Without that the name reaches + /// the companion nowhere, and the next reclamation would read the bound one + /// as an inode holding no name and drop it. fn reclaim_orphans(&self) -> usize { let (bound, dead) = self.orphans().into_iter().fold( (Vec::new(), Vec::new()), @@ -554,7 +561,10 @@ impl Kernel { if let Ok(name) = PathName::from_bytes(&main) { let lookup = KernelReadOperation::Lookup { parent, name }; match self.observe(parent, None, lookup) { - Ok((stat, _, _)) => bound.push((orphan.serial, stat.serial)), + Ok((stat, _, _)) => { + self.entry_taken(&stat, parent, &main); + bound.push((orphan.serial, stat.serial)); + } Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), Err(_) => {} } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index d754d8f12c..dc14f9e933 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -510,6 +510,63 @@ fn a_companion_of_a_main_file_the_name_index_missed_is_kept() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_bound_back_to_its_main_file_survives_the_next_reclaim() { + let base = temp("orphan-bound"); + let tree = base.join("tree"); + source(&tree); + // As in the test above: the main file is part of the tree the export was + // initialized from, and never looked up, so the companion starts with no + // main inode and takes the one slot. + fs::write(tree.join("live"), b"the data file").unwrap(); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 1; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let ad = c.touch(&root, b"._live", 0o644).unwrap(); + let whole = image([0x52; 32], &[(b"user.kept", pattern(91, 128))]); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The bound is full, so this CREATE reclaims first: the lookup finds the + // main file, the companion becomes that inode's, and the name the visit + // found is the export's one reference (not a second one it never gives + // back). The CREATE is then refused. + c.touch(&root, b"other", 0o644).unwrap(); + let lookups = server.held().lookups; + assert_eq!(c.touch(&root, b"._other", 0o644).map(|_| ()), Err(NOSPC)); + assert_eq!(server.held().lookups, lookups + 1, "one reference, kept"); + assert_eq!(server.held().companions_slotted, 1); + + // A second reclamation runs without the client ever looking the main file + // up: the bound companion holds a name in the export's table now, so it is + // not an orphan, and its attributes stay. + c.touch(&root, b"other2", 0o644).unwrap(); + let lookups = server.held().lookups; + assert_eq!(c.touch(&root, b"._other2", 0o644).map(|_| ()), Err(NOSPC)); + assert_eq!( + server.held().lookups, + lookups, + "the live name needs no visit" + ); + assert_eq!(server.held().companions, 1); + assert_eq!(server.held().companions_slotted, 1); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole, "attributes kept"); + + // It follows that inode: it goes with the inode's last name. + c.remove(&root, b"live").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + assert_eq!(c.lookup(&root, b"._live").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_write_that_takes_the_last_slot_is_refused_by_the_bound() { let base = temp("write-bound"); @@ -1123,7 +1180,6 @@ fn a_rename_keeps_the_other_names_of_the_inode_companion() { assert_eq!(server.held().companions, 0); assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); - drop(c); let released = server.stop(); let (_, outstanding) = rig.stop(released); From 45d090391aa63a7f9a5b978f31b345d1cf072b50 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:02:57 +0000 Subject: [PATCH 38/53] fix(nfs): keep a companion with the inode's other names, and link its names (lp73) macOS 27.2, build 525fcfb41, reproducible 20/20 and 5/5: a file carrying attributes, `ln a b`, then `rm a`, leaves `b` with no attributes at all and `._b` answering `NFS3ERR_NOENT`, while the companion is still in the export's index. The companion was the inode's, so nothing about the inode changed; what the client sent is what removed it. Reproduced in the rig with the client's sequence: `/bin/ln a b` links the main file, then the client drops the `._` name of the name it no longer uses with a REMOVE of `._a`, and REMOVE took the whole companion: `held().companions` 1 to 0, `._b` `NFS3ERR_NOENT`, the attributes gone. A client that carries the attributes to the new name also sends a LINK of the companion name (`._a` to `._b`), which this export refused with `NFS3ERR_ACCES`. - A companion now holds every `._` name of the inode it was linked under (`Companion::also`, indexed and unindexed with its own name, one name promoted when the recorded one goes). - `companion_link` serves LINK of a companion serial: another `._` name of the same companion, `NFS3ERR_EXIST` for a name already held or another companion's, `NFS3ERR_ACCES` for a name of the Workspace. - `companion_remove` drops one name while the companion holds another, or while its inode has another name the export knows (`Table::names` plus `Table::aliases`); only the last name of a one-name inode is the client clearing the attributes, which still takes the companion, as does any name of a companion no inode owns. Review: macOS re-test, finding 1 (hard link then remove the original name). This is the same rule the hard-link contract already stated, which the name scoped REMOVE broke. Tests: two new. `a_hard_link_keeps_the_companion_under_its_other_names`: main file and attributes, LINK, REMOVE `._a`, then REMOVE `a`; `._b` reads the same companion and bytes at every step and the companion goes with `b`. `a_linked_companion_name_is_another_name_of_the_same_companion`: LINK of the companion name succeeds and reads the same bytes, a held name answers `NFS3ERR_EXIST`, a plain name `NFS3ERR_ACCES`, REMOVE of `._a` keeps `._b`, and REMOVE of a one-name inode's only `._` name still removes the companion. Anti-proofs: with the keep rule forced off both tests fail (`left: 0, right: 1` companions, the attributes gone), and with LINK of a companion back to `NFS3ERR_ACCES` the second fails on that LINK. `cargo test -p layerfs-nfs`: 71 passed, 0 failed (raw sum 72 with the child-process rerun). Production LOC: 164797 -> 164884 (delta +87) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent f6cb67819 (164797) and of the staged tree (164884). Engine +87: the companion's extra names and the three index operations on them, `companion_link`, the name-count rule in `companion_remove`, and the routed LINK. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 11 +- engine/crates/layerfs-nfs/src/apple_double.rs | 135 ++++++++++++++++-- engine/crates/layerfs-nfs/src/change.rs | 4 +- .../layerfs-nfs/tests/apple_double_decode.rs | 106 ++++++++++++++ 4 files changed, 245 insertions(+), 11 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 1b7d78c8a1..cee540a021 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -185,7 +185,16 @@ the export. A companion whose main inode the export knows belongs to that inode rather than to one name: hard links share it, main-file RENAME keeps it under the new name and existing aliases, and only the inode's last name (or its silly rename) -drops it. When a write leaves an inode-bound companion holding a complete +drops it. It can hold several of the inode's `._` names at once: a LINK of a +companion name (`._a` to `._b`, which a client that carries the attributes to +a new name sends) adds one, answering `NFS3ERR_EXIST` for a name already held +and `NFS3ERR_ACCES` for a name of the Workspace, and a REMOVE of one of those +names drops only that name while the companion holds another or its inode has +another name the export knows. The REMOVE of the last name of an inode with one +name is the client clearing the attributes, which takes the companion with it, +as does any name of a companion no main inode owns. + +When a write leaves an inode-bound companion holding a complete AppleDouble image that encodes back to the exact bytes written ([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)), it is marked whole and takes no `HELD` slot: decoded in memory (counted as diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 3b578429d3..77cf8988d3 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -4,7 +4,8 @@ //! fork in a `._` companion file (see [`crate::names`]). When the export //! keeps such names out of the Workspace, a CREATE of one makes a file that //! lives only here, under its own serial range: LOOKUP, GETATTR, ACCESS, READ, -//! WRITE, SETATTR, COMMIT, REMOVE and a RENAME to another AppleDouble name +//! WRITE, SETATTR, COMMIT, REMOVE, a LINK to another AppleDouble name and a +//! RENAME to another AppleDouble name //! work on it, READDIR does not list it, and no mutation of it ever reaches //! the engine, so the Workspace stays clean and no Commit can capture it. //! Everything is dropped when the export is released. @@ -21,7 +22,11 @@ //! hard links share one companion, it follows the inode through RENAME, and it //! goes with the inode's last name rather than with one name. Its FinderInfo //! and extended attributes are kept under that inode's serial, not under the -//! `._` name. Whenever a write leaves such a companion holding a whole +//! `._` name. It may hold several of the inode's `._` names at once (a LINK of +//! a companion name makes one, and a client that links a file keeps the +//! attributes aside under each name), and removing one of them leaves the +//! companion to the inode's other names: only its last name, on an inode with +//! no other name the export knows, is the client clearing the attributes. Whenever a write leaves such a companion holding a whole //! AppleDouble image the client laid out itself (see //! [`crate::apple_double_codec`]), it is decoded: a small one keeps only its //! FinderInfo and attributes in memory (each at most [`DECODED_ENTRY_BYTES`] @@ -97,6 +102,10 @@ enum Body { struct Companion { /// The `._` name it was created or last renamed to. named: Named, + /// The other `._` names of the same companion, which a LINK made: a client + /// that links a file keeps its attributes aside under each of the file's + /// names, and every one of them is a name of this one companion. + also: Vec, /// The main inode it belongs to, when the export knew it at creation. inode: Option, /// Its body is a whole image: any name of the inode reads it, and it takes @@ -261,17 +270,22 @@ impl Companions { self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); Some(file) } - /// Makes `file`'s name and main inode find `serial`. + /// Makes every name of `file` and its main inode find `serial`. fn index(&mut self, serial: u64, file: &Companion) { self.names.insert(file.named.clone(), serial); + for named in &file.also { + self.names.insert(named.clone(), serial); + } if let Some(inode) = file.inode { self.inodes.insert(inode, serial); } } - /// Drops `file`'s name and inode keys that still find `serial`. + /// Drops every name of `file` and its inode key that still find `serial`. fn unindex(&mut self, serial: u64, file: &Companion) { - if self.names.get(&file.named) == Some(&serial) { - self.names.remove(&file.named); + for named in std::iter::once(&file.named).chain(&file.also) { + if self.names.get(named) == Some(&serial) { + self.names.remove(named); + } } if let Some(inode) = file.inode { if self.inodes.get(&inode) == Some(&serial) { @@ -279,6 +293,37 @@ impl Companions { } } } + /// Whether `serial` holds a name other than `named`. + fn holds_another(&self, serial: u64, named: &Named) -> bool { + self.files.get(&serial).is_some_and(|file| { + (file.named != *named && self.names.get(&file.named) == Some(&serial)) + || file.also.iter().any(|also| also != named) + }) + } + /// Drops `named`, one of `serial`'s names, and answers whether it held it. + /// A companion left with no name is still reached through its main inode, + /// so it keeps its record; another held name becomes the one its record + /// names, so a later `index` puts back only names it still holds. + fn drop_name(&mut self, serial: u64, named: &Named) -> bool { + let Some(file) = self.files.get_mut(&serial) else { + return false; + }; + let primary = file.named == *named; + if !primary && !file.also.iter().any(|also| also == named) { + return false; + } + if self.names.get(named) == Some(&serial) { + self.names.remove(named); + } + if primary { + if let Some(next) = file.also.pop() { + file.named = next; + } + } else { + file.also.retain(|also| also != named); + } + true + } /// The companion `named` reaches when its main file is `main`: the one /// held under that name, unless it belongs to another inode than `main`, /// else the one its main inode already has. @@ -715,6 +760,7 @@ impl Kernel { let used = companions.tick(); let file = Companion { named, + also: Vec::new(), inode: main, whole: false, len: 0, @@ -732,16 +778,49 @@ impl Kernel { } /// REMOVE of a companion name, with the directory's `wcc_data`; `None` /// when no companion has that name. + /// + /// A companion the export pairs with a main inode is the inode's, not one + /// name's: its FinderInfo and attributes belong to the file, so a client + /// that links the file (or removes one of its names) and drops the `._` + /// name it no longer uses leaves the companion to the inode's remaining + /// names. Only while this name is the companion's last one, and its inode + /// has no other name the export knows, is the REMOVE the client clearing + /// the attributes, which takes the companion with it. A companion no main + /// inode owns has nothing else to go with and always goes. pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { + let named = (parent, name.to_vec()); let main = self.main_of(parent, name); + let (serial, inode, one_name) = { + let companions = self.companions(); + let serial = companions.resolve(&named, main)?; + let file = companions.files.get(&serial)?; + ( + serial, + file.inode, + !companions.holds_another(serial, &named), + ) + }; + let kept = !one_name || inode.is_some_and(|inode| self.knows_another_name(inode)); let spilled = { let mut companions = self.companions(); - let serial = companions.resolve(&(parent, name.to_vec()), main)?; - companions.take_serial(serial) + if kept { + companions.drop_name(serial, &named); + Vec::new() + } else { + companions.take_serial(serial).into_iter().collect() + } }; unlink_paths(spilled); Some(self.directory_wcc(parent)) } + /// Whether the export's name index knows a name of `inode` beyond the one + /// it remembers: a hard link the client made, which the companion of an + /// inode follows. + fn knows_another_name(&self, inode: u64) -> bool { + let table = self.table(); + let remembered = usize::from(table.names.contains_key(&inode)); + remembered + table.aliases.get(&inode).map_or(0, Vec::len) > 1 + } /// The main file `name` in `parent` was removed, silly-renamed or replaced /// by `RENAME`: drops the companion held under `._`, or only that /// name when the companion belongs to an inode, which goes with the @@ -768,7 +847,7 @@ impl Kernel { .get(&serial) .is_some_and(|file| file.inode.is_some()) { - companions.names.remove(&named); + companions.drop_name(serial, &named); None } else { companions.take_serial(serial) @@ -787,6 +866,44 @@ impl Kernel { }; unlink_paths(spilled); } + /// LINK of a companion name: the same companion under another AppleDouble + /// name, as a client that links a file makes to carry its attributes to + /// the new name. The name it names must be free, and a name that is not + /// another companion name is refused, so a companion never becomes a file + /// of the Workspace. + pub(crate) fn companion_link( + &self, + serial: u64, + parent: u64, + name: &[u8], + ) -> Result<(ViewStat, Wcc), Status> { + if !crate::names::apple_double(name) || name.len() > 255 { + return Err(Status::Access); + } + if parent != self.root() && !self.table().parents.contains_key(&parent) { + return Err(Status::NotDir); + } + let named = (parent, name.to_vec()); + let directory = self.directory_wcc(parent); + let main = self.main_of(parent, name); + let mut companions = self.companions(); + if companions.names.contains_key(&named) + || companions + .resolve(&named, main) + .is_some_and(|other| other != serial) + { + return Err(Status::Exist); + } + let Some(mut file) = companions.detach(serial) else { + return Err(Status::Stale); + }; + file.also.push(named); + file.used = companions.tick(); + let stat = Companions::stat(serial, &file); + companions.index(serial, &file); + companions.attach(serial, file); + Ok((stat, directory)) + } /// RENAME of a companion name: only to another AppleDouble name, which it /// replaces when held. It then belongs to the destination's main inode, or /// to none when that is unknown. `None` when no companion has that name. diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 11f74ef414..81ebb40345 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -643,8 +643,10 @@ impl Kernel { name: &[u8], tickets: &mut Tickets, ) -> Result<(ViewStat, Wcc), Status> { + // A companion holds no engine inode, so its LINK is another `._` name + // of the same companion, decided in the export alone. if crate::apple_double::companion(serial) { - return Err(Status::Access); + return self.companion_link(serial, parent, name); } let checked = self.checked(name, true)?; let published = self.mutate( diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index dc14f9e933..38f9203130 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1244,3 +1244,109 @@ fn an_eviction_victim_that_cannot_be_written_out_does_not_fail_the_writer() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_hard_link_keeps_the_companion_under_its_other_names() { + let base = temp("hard-link"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + // What `cp` leaves: the data file and its attributes alongside. + let a = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&a.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._a", 0o644).unwrap(); + let whole = image([0x61; 32], &[(b"user.kept", pattern(11, 64))]); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions, 1); + + // `ln a b`, and the client drops the `._` name of the old name it no + // longer uses: the attributes belong to the inode `b` still names, so the + // companion stays. + c.link(&a.handle, &root, b"b").unwrap(); + let (shared, attr) = c.lookup(&root, b"._b").unwrap(); + assert_eq!( + shared, ad.handle, + "the linked name reads the same companion" + ); + assert_eq!(attr.size as usize, whole.len()); + c.remove(&root, b"._a").unwrap(); + assert_eq!(server.held().companions, 1); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole, "attributes kept"); + + // `rm a`: one name of the inode goes, the companion stays with `b`. + c.remove(&root, b"a").unwrap(); + assert_eq!(server.held().companions, 1); + let (still, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(still, ad.handle); + assert_eq!(c.read_all(&still, 64 * 1024), whole); + + // The inode's last name takes it with it. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + assert_eq!(c.getattr(&ad.handle), Err(STALE)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_linked_companion_name_is_another_name_of_the_same_companion() { + let base = temp("companion-link"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let a = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&a.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._a", 0o644).unwrap(); + let whole = image([0x62; 32], &[(b"user.kept", pattern(12, 80))]); + c.write(&ad.handle, 0, &whole).unwrap(); + + // What a client that carries the attributes to the new name does: the + // main file first, then its companion, one companion behind both names. + c.link(&a.handle, &root, b"b").unwrap(); + let linked = c.link(&ad.handle, &root, b"._b").unwrap(); + assert_eq!(linked.fileid, ad.attr.fileid); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions, 1); + // A name already held is not linked again, and a companion is never + // linked onto a name of the Workspace. + assert_eq!(c.link(&ad.handle, &root, b"._b").map(|_| ()), Err(17)); + assert_eq!(c.link(&ad.handle, &root, b"plain").map(|_| ()), Err(13)); + + // The client drops the old name: the companion keeps the new one and its + // bytes, and reads through the inode as well. + c.remove(&root, b"._a").unwrap(); + assert_eq!(server.held().companions, 1); + let (kept, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(kept, ad.handle); + assert_eq!(c.read_all(&kept, 64 * 1024), whole); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + + // An inode with one name has only one `._` name: removing it is the client + // clearing its attributes, which takes the companion. + let alone = c.touch(&root, b"alone", 0o644).unwrap(); + c.write(&alone.handle, 0, b"data").unwrap(); + let one = c.touch(&root, b"._alone", 0o644).unwrap(); + c.write(&one.handle, 0, &whole).unwrap(); + assert_eq!(server.held().companions, 2); + c.remove(&root, b"._alone").unwrap(); + assert_eq!(server.held().companions, 1); + assert_eq!(c.getattr(&one.handle), Err(STALE)); + assert_eq!(c.lookup(&root, b"._alone").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From c96af5b19ffad8e830151b1eece26faf05914658 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:06:24 +0000 Subject: [PATCH 39/53] fix(nfs): report companions no name reaches when the export releases (lp73) macOS 27.2, build 525fcfb41: in one run of 600 files carrying ~100 KiB of attributes each, the first 507 in write order read back with no attributes at all while the export still held all 652 companions, 326 bodies stayed on disk, and two re-runs of the same recipe plus two controls were 100% correct. Nothing in the export's own counts had moved, so the loss was not an eviction: either those companions were still held but no name reached them, or the client never got them back for a reason of its own. The static review found no path that removes a companion's name keys and keeps the companion - every one of them takes the companion with it, or leaves it reachable through its inode - so the run could not be reproduced from the code, and a loss with the index intact has to be told apart from one where the index lost the entry. `Companions::unreachable` counts the companions neither their recorded name nor another name of their inode reaches, and the export's release line now carries it: `held= slotted= decoded= resident_bytes= unreachable=`. It runs once, over the companions held at release, so it costs nothing on the serving path. A non-zero count beside a client that lost attributes says the name, not the body, was lost; a zero says the body itself was gone. Documented with the release line in the nfs route's AppleDouble section. Review: macOS re-test, finding 2 (507 of 600 attributes lost, not reproduced). Tests: none new. The counter can only be non-zero through the very defect it reports, so an ordinary test would assert zero; the release path is covered by every test that stops an export (the line is printed with `held=`). Production LOC: 164884 -> 164900 (delta +16) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 45d090391 (164884) and of the staged tree (164900). Engine +16: the counting method and the release line's field. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 8 ++++++ engine/crates/layerfs-nfs/src/apple_double.rs | 28 +++++++++++++++++-- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index cee540a021..c4acda2385 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -259,6 +259,14 @@ the first entry (O(log n) per round, no walk of the index), and the rounds end when no companion holding memory is left. `ExportServing::reclaim` and release delete `/.appledouble`. +Release logs one line per export that still holds companions: +`held= slotted= decoded= resident_bytes= unreachable=`. `unreachable` counts the +companions no name reaches - neither the name a companion records nor another +name of its inode finds it - which is the shape a lost attribute takes when the +body is still held but a client cannot ask for it; a zero beside a client that +lost attributes says the loss was a missing companion rather than a lost name. +It is counted once, at release, over the companions held. + ## Mount (`mount.rs`, daemon `export.rs`) ```text diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 77cf8988d3..4f415c5dcc 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -480,6 +480,27 @@ impl Companions { || serial.is_some_and(|serial| self.slots.contains(&serial)) || self.slots.len() < self.held_limit } + /// The companions no name of the export reaches: neither the name it + /// records nor another name of its inode finds it. Such a companion holds + /// its body with no way for a client to ask for it, which is one of the two + /// shapes a lost attribute takes (the other is no companion at all). It is + /// counted once, when the export releases, so a file of reports from a real + /// client can say which shape a loss had. + fn unreachable(&self) -> usize { + self.files + .iter() + .filter(|(serial, file)| { + self.names.get(&file.named) != Some(serial) + && !file + .also + .iter() + .any(|also| self.names.get(also) == Some(serial)) + && file + .inode + .is_none_or(|inode| self.inodes.get(&inode) != Some(serial)) + }) + .count() + } fn holding(&self) -> Holding { Holding { held: self.files.len(), @@ -1009,10 +1030,11 @@ impl Kernel { /// Drops every companion and removes the export's spill directory; returns /// what the index held. pub(crate) fn companions_release(&self) -> Holding { - let (held, dir) = { + let (held, dir, unreachable) = { let mut companions = self.companions(); let dir = companions.spill_dir.take(); - (std::mem::take(&mut *companions), dir) + let unreachable = companions.unreachable(); + (std::mem::take(&mut *companions), dir, unreachable) }; if let Some(dir) = dir { drop(fs::remove_dir_all(dir)); @@ -1020,7 +1042,7 @@ impl Kernel { let holding = held.holding(); if holding.held > 0 { eprintln!( - "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={}", + "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={} unreachable={unreachable}", self.mount(), holding.held, holding.slotted, From 386c5b0e210124d61a912921b6a5812baafb5467 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:15:55 +0000 Subject: [PATCH 40/53] fix(nfs): hold the index slot a commit is still going to take (lp73) The `HELD` bound was decided in one place, but on the path that needs I/O between the decision and the commit - a WRITE, SETATTR or RENAME whose body spills and is then edited on its file - `admits` passed before `spill_gated` and the file write, and `record_edit`/`classify` took the slot afterwards without asking again. Two concurrent calls could both be told the last slot was free and both take one, so `slots.len()` could exceed `held_limit` by as much as the number of edits in flight, which contradicts "the bound holds". `Companions::reserve` decides and holds in one step under the companion lock (`Slot::Taken`/`Held`/`Full`); reservations count against the bound in `admits`, and a create or reclaim cannot steal one. The disk-edit path and `rename_companion` reserve before their I/O and give the reservation back if the edit does not land (`unreserve`, `take_serial`, the failure paths of `apply_edit`/`record_edit`/`rename_companion`), so a reservation can neither be held for good nor outlive its companion. CREATE and the in-memory edit decide and take the slot under one lock and keep using `admits`. Review: finding P2-1 (the bound could be exceeded under concurrency), and the route document's claim that the bound holds is now true as written. Tests: new `the_slot_bound_holds_when_writes_claim_the_last_slot_together`. Eight companions holding whole images (no slot), one slot, a body budget that cannot hold the broken body, and one breaking WRITE from each over its own connection after a barrier: exactly one writer takes the slot, the other seven answer `NFS3ERR_NOSPC`, `slotted` is 1, and every companion still reads back as its image or that edit. Anti-proof: with `admits` back in place of `reserve` the test failed 23 of 40 runs with two or three writers succeeding (`[Ok(()), Err(28), Ok(()), ...]`); with the reservation it passed 40 of 40. Production LOC: 164900 -> 164930 (delta +30) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent c96af5b19 (164900) and of the staged tree (164930). Engine +30: the reservation set, `Slot`, `reserve`/`unreserve`, the two decision sites and the three release paths. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 2 +- engine/crates/layerfs-nfs/src/apple_double.rs | 56 ++++++++++-- .../layerfs-nfs/src/apple_double/edit.rs | 10 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 86 +++++++++++++++++++ 4 files changed, 144 insertions(+), 10 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index c4acda2385..7ff0d60f03 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -177,7 +177,7 @@ the export. | Bound | Value | Over the bound | Source | | --- | --- | --- | --- | -| `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export) | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export). A call whose commit needs I/O in between (`Companions::reserve`) holds the slot from the decision, so the bound holds when calls race for the last one | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `RESIDENT_BYTES` | 32 MiB of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost` | Spill the least recently touched bodies, decoded ones included, to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | | `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 4f415c5dcc..6e99d2fb3d 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -149,6 +149,18 @@ struct Orphan { main: Option, } +/// What [`Companions::reserve`] made of a call's claim on a slot of the index +/// bound. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(crate) enum Slot { + /// It took the slot, which it gives back if its commit does not land. + Taken, + /// It already held a slot (or a reservation for one): nothing was taken. + Held, + /// The bound has none. + Full, +} + /// What [`Companions::keep_decoded`] made of an edited body. pub(crate) enum Decoded { /// The companion holds the body's decoded form. @@ -184,6 +196,10 @@ pub(crate) struct Companions { /// takes no slot, whether it is decoded or kept as written bytes, so whole /// images add nothing to the walk. slots: HashSet, + /// The serials holding a slot for a commit that is still on its way, whose + /// I/O runs outside this lock. A reserved slot counts against the bound, so + /// two calls cannot both be told the bound has room for one. + reserved: HashSet, /// Every companion holding memory, oldest use first: (used tick, serial). /// One tick is one touch and no serial takes two ticks, so the keys are /// unique and the oldest entry is the first one. @@ -204,6 +220,7 @@ impl Default for Companions { names: HashMap::new(), inodes: HashMap::new(), slots: HashSet::new(), + reserved: HashSet::new(), by_use: BTreeSet::new(), resident_bytes: 0, decoded: 0, @@ -414,6 +431,7 @@ impl Companions { } } fn take_serial(&mut self, serial: u64) -> Option { + self.reserved.remove(&serial); let file = self.detach(serial)?; self.unindex(serial, &file); match file.body { @@ -477,8 +495,29 @@ impl Companions { /// keeps it, and a body that takes no slot is always admitted. fn admits(&self, serial: Option, slotted: bool) -> bool { !slotted - || serial.is_some_and(|serial| self.slots.contains(&serial)) - || self.slots.len() < self.held_limit + || serial.is_some_and(|serial| { + self.slots.contains(&serial) || self.reserved.contains(&serial) + }) + || self.slots.len() + self.reserved.len() < self.held_limit + } + /// Decides whether `serial` may take a slot of the bound and holds it when + /// it may, in one step under this lock: a call that needs I/O before its + /// commit keeps the slot for the commit, so two calls cannot both be told + /// the bound has room for one. [`Slot::Held`] means it already has one + /// (or a reservation) and nothing was taken. + fn reserve(&mut self, serial: u64) -> Slot { + if self.slots.contains(&serial) || self.reserved.contains(&serial) { + return Slot::Held; + } + if self.slots.len() + self.reserved.len() >= self.held_limit { + return Slot::Full; + } + self.reserved.insert(serial); + Slot::Taken + } + /// Gives back a slot reserved for a commit that did not land. + fn unreserve(&mut self, serial: u64) { + self.reserved.remove(&serial); } /// The companions no name of the export reaches: neither the name it /// records nor another name of its inode finds it. Such a companion holds @@ -995,17 +1034,21 @@ impl Kernel { } // A companion moved onto an unknown main takes a slot; one already // holding a slot keeps it, and one that stays a whole image keeps its - // exemption. - if !self.companions().admits(Some(serial), to_main.is_none()) { + // exemption. The slot is held from here, so the commit below cannot + // find another call took the last one while this rename waited. + if to_main.is_none() && self.companions().reserve(serial) == Slot::Full { self.reclaim_orphans(); - if !self.companions().admits(Some(serial), to_main.is_none()) { + if self.companions().reserve(serial) == Slot::Full { return Err(Status::NoSpc); } } let mut replaced_path = None; { let mut companions = self.companions(); - let mut file = companions.detach(serial).ok_or(Status::Stale)?; + let Some(mut file) = companions.detach(serial) else { + companions.unreserve(serial); + return Err(Status::Stale); + }; companions.unindex(serial, &file); if let Some(replaced) = companions.resolve(&target, to_main) { if replaced != serial { @@ -1023,6 +1066,7 @@ impl Kernel { companions.classify(&mut file); companions.index(serial, &file); companions.attach(serial, file); + companions.unreserve(serial); } unlink_paths(replaced_path); Ok(()) diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 283ee6740e..eac3c6670e 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -16,7 +16,7 @@ //! lock and renamed to the companion's own name outside it, before the body is //! committed as spilled under the lock again. No descriptor is kept for a //! spilled body: each operation opens its file by path and closes it again. -use super::{edited_len, record, Body, Companions, Decoded, DECODED_ENTRY_BYTES, FILE_BYTES}; +use super::{edited_len, record, Body, Companions, Decoded, Slot, DECODED_ENTRY_BYTES, FILE_BYTES}; use crate::{ apple_double_spill::{ create_spilled, io_status, spill_path, touch, unlink_paths, Edit, Edited, Room, @@ -226,8 +226,10 @@ impl Kernel { // its file, which needs no body budget. A body edited on its file is no // longer known to be a whole image, so it takes a slot of the index // bound: decide that before the file is written, and leave the body, - // its file and its name as they were when the bound has none. - if !self.companions().admits(Some(serial), true) { + // its file and its name as they were when the bound has none. The slot + // is held from the decision, not taken by the commit after the I/O, so + // another call cannot be told the same last slot is free. + if self.companions().reserve(serial) == Slot::Full { return Ok(Edited::NoSlot); } // A failed file operation leaves the length the companion had: the @@ -245,6 +247,7 @@ impl Kernel { }); if let Err(status) = written { self.restore_len(serial, before); + self.companions().unreserve(serial); return Err(status); } self.record_edit(serial, edit).map(Edited::Done) @@ -350,6 +353,7 @@ impl Kernel { touch(&mut file.metadata); let stat = Companions::stat(serial, &file); companions.attach(serial, file); + companions.unreserve(serial); Ok(stat) } /// Spills the least recently used bodies to disk (outside the companion diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 38f9203130..a74a3c94b5 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1350,3 +1350,89 @@ fn a_linked_companion_name_is_another_name_of_the_same_companion() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn the_slot_bound_holds_when_writes_claim_the_last_slot_together() { + const WRITERS: usize = 8; + let base = temp("slot-race"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // One slot, and a body budget smaller than the images below, so each + // breaking write spills its body and needs the slot after I/O. + rig.companions_held = 1; + rig.companion_resident_bytes = 1024; + rig.companion_spill_dir = Some(base.join("spill")); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let address = server.local_addr(); + let mut c = Client::connect(address, UID, GID); + let root = c.mnt("/"); + let mut images = Vec::new(); + for i in 0..WRITERS { + c.touch(&root, format!("m{i}").as_bytes(), 0o644).unwrap(); + let ad = c.touch(&root, format!("._m{i}").as_bytes(), 0o644).unwrap(); + // A whole image is 4,096 bytes however small its attributes are: it + // costs a few dozen bytes of the budget and is broken by one byte of + // its header, which leaves 4,096 bytes that cannot stay resident here. + let whole = image( + [i as u8 + 7; 32], + &[(b"user.value", pattern(70 + i as u32, 64))], + ); + assert_eq!(whole.len(), 4096); + c.write(&ad.handle, 0, &whole).unwrap(); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + images.push((ad.handle.clone(), whole)); + } + assert_eq!(server.held().companions, WRITERS); + assert_eq!( + server.held().companions_slotted, + 0, + "a whole image takes no slot" + ); + + // Every companion is broken at once, each on its own connection: one slot + // is free, so exactly one may take it. A bound decided before the I/O and + // taken after it lets more than one through. + let barrier = std::sync::Arc::new(std::sync::Barrier::new(WRITERS + 1)); + let writers: Vec<_> = images + .iter() + .map(|(handle, _)| { + let (barrier, mut writer) = (barrier.clone(), Client::connect(address, UID, GID)); + let handle = handle.clone(); + std::thread::spawn(move || { + barrier.wait(); + writer.write(&handle, 0, b"X").map(|_| ()) + }) + }) + .collect(); + barrier.wait(); + let results: Vec> = writers + .into_iter() + .map(|writer| writer.join().unwrap()) + .collect(); + assert_eq!( + results.iter().filter(|result| result.is_ok()).count(), + 1, + "one slot, one writer: {results:?}" + ); + assert_eq!(server.held().companions_slotted, 1, "{results:?}"); + assert_eq!(server.held().companions, WRITERS); + // The refused ones kept their image, the taken one holds the edit. + let refused = results.iter().filter(|result| result.is_err()).count(); + assert_eq!(refused, WRITERS - 1); + for (handle, whole) in &images { + let bytes = c.read_all(handle, 64 * 1024); + let mut edited = whole.clone(); + edited[0] = b'X'; + assert!( + bytes == *whole || bytes == edited, + "every companion is its image or the edit" + ); + } + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From 0b877168b20207756d27e2d0830c650db41d7e16 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:20:19 +0000 Subject: [PATCH 41/53] fix(nfs): reclaim a companion whose main directory is gone (lp73) Reclamation asks the engine about a candidate's main file before dropping it, and treated only "no such file" as dead. A main file whose directory the client had removed cannot answer "no such file": the engine has no such parent, so the lookup answers `NFS3ERR_STALE` (`NFS3ERR_NOTDIR` for a parent that is a file), and the candidate was kept for the export's life. Its slot stayed taken, every later CREATE at the bound repeated the same failing lookup, and the bound could stay full until release. `NFS3ERR_STALE` and `NFS3ERR_NOTDIR` now count as "the main file is not there either" and the candidate is reclaimed, which is what a removed parent means for its entries. Any other answer still leaves the companion alone, and the per-name engine lookup and the slot walk are unchanged. Review: finding P2-3 (a candidate whose main file's directory is gone is never reclaimed). Tests: new `a_companion_of_a_removed_directory_is_reclaimed`: one slot, a companion inside a directory whose main file `x` never existed (so `inode: None` and the slot), the client removes the directory (`rmdir` succeeds - nothing in it is visible to the engine), then a CREATE at the bound: its reclamation's lookup answers `NFS3ERR_STALE`, the companion is dropped and the CREATE lands with one companion and one slot. Anti-proof: with only `NFS3ERR_NOENT` counted the same CREATE answers `NFS3ERR_NOSPC` (`Err value: 28`) and the test fails there, so the lookup really answers a stale parent rather than a missing entry. Production LOC: 164930 -> 164932 (delta +2) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 386c5b0e2 (164930) and of the staged tree (164932). Engine +2: the extra answers in the reclaim's match. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 6 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 16 +++++-- .../layerfs-nfs/tests/apple_double_decode.rs | 42 +++++++++++++++++++ 3 files changed, 59 insertions(+), 5 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 7ff0d60f03..624eebbfe2 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -227,8 +227,10 @@ concurrent GUARDED creates of one name yield one serial and one up, a client-side rename), so a candidate whose main inode the export does not know costs one read-only lookup of its main file in the engine, outside both locks: a file that is there binds the companion back to that inode and keeps -its attributes, only `NFS3ERR_NOENT` makes it an orphan, and a lookup that -cannot answer leaves it alone. The lookup that finds the main file took one +its attributes, `NFS3ERR_NOENT` - or `NFS3ERR_STALE`/`NFS3ERR_NOTDIR`, a main +file whose directory the engine no longer has, which cannot hold it either - +makes it an orphan, and a lookup that cannot answer any other way leaves it +alone. The lookup that finds the main file took one engine reference on it, and the export keeps exactly one per serial, so the visit registers the name it found the file under (`Kernel::entry_taken`, as `Kernel::lookup` does) before the companion is bound: that name is what makes diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 6e99d2fb3d..61bc0559f2 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -644,8 +644,10 @@ impl Kernel { /// export never looked up, a rename on the client side), so each one costs /// one read-only lookup of its main file in the engine, run outside both /// locks. A main file that is there binds the companion back to its inode, - /// which keeps its attributes; only a lookup that answers "no such file" - /// makes it an orphan, and one that cannot answer leaves it as it is. + /// which keeps its attributes; only a lookup that answers "no such file", + /// or whose parent directory the engine no longer has (so the file cannot + /// be there either), makes it an orphan, and one that cannot answer leaves + /// it as it is. /// /// A lookup that finds the main file took one engine reference on it, and /// the export keeps exactly one per serial: the visit is the entry's, so it @@ -670,7 +672,15 @@ impl Kernel { self.entry_taken(&stat, parent, &main); bound.push((orphan.serial, stat.serial)); } - Err(Status::NoEnt) => dead.push((orphan.serial, orphan.inode)), + // A parent directory the engine no longer has cannot + // hold the main file: the companion is an orphan as + // much as one whose file answers "no such file". + // A parent directory the engine no longer has cannot + // hold the main file: the companion is an orphan as + // much as one whose file answers "no such file". + Err(Status::NoEnt | Status::Stale | Status::NotDir) => { + dead.push((orphan.serial, orphan.inode)) + } Err(_) => {} } } diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index a74a3c94b5..17323fd518 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1436,3 +1436,45 @@ fn the_slot_bound_holds_when_writes_claim_the_last_slot_together() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_companion_of_a_removed_directory_is_reclaimed() { + let base = temp("orphan-dir-gone"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + // One slot, and both companions below take one: a whole image whose main + // file the export never saw stays as the client wrote it. + rig.companions_held = 1; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + c.mkdir(&root, b"gone", 0o755).unwrap(); + let gone = c.lookup(&root, b"gone").unwrap().0; + let held = c.touch(&gone, b"._x", 0o644).unwrap(); + c.write(&held.handle, 0, &pattern(80, 64)).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The client removes the directory: nothing the engine can see is in it, + // so the removal succeeds and leaves the companion it never listed behind, + // with a main file whose parent the engine no longer has. + c.rmdir(&root, b"gone").unwrap(); + assert_eq!(server.held().companions, 1); + + // The next CREATE at the bound reclaims first. The lookup of the vanished + // main file answers `NFS3ERR_STALE` (its parent is gone), which is as much + // "there is no such file" as `NFS3ERR_NOENT`, so the slot comes free and + // this CREATE lands instead of the bound staying full for good. + let made = c.touch(&root, b"._y", 0o644).unwrap(); + assert_eq!(server.held().companions, 1); + assert_eq!(server.held().companions_slotted, 1); + assert_eq!(c.getattr(&held.handle), Err(STALE)); + c.write(&made.handle, 0, &pattern(81, 32)).unwrap(); + assert_eq!(c.read_all(&made.handle, 4096), pattern(81, 32)); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From d114c133dc2b52c876862272192d3c41cb7b9529 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sat, 14 Nov 2026 18:21:40 +0000 Subject: [PATCH 42/53] docs(nfs): state what one decoded body is charged, and the one-body overshoot (lp73) Two statements about the resident budget were wrong in the direction of claiming more than the code does. A decoded image's `Image::cost` against `RESIDENT_BYTES` is a cap on what one decoded body is charged, not a limit on what a companion may store: an image costing more than `DECODED_ENTRY_BYTES` is kept as the client wrote it and charged at its length. And an edit that leaves a body whole decodes it as it records it rather than asking for room first, so the pool may stand one decoded body over the budget until the next edit needs room - "never memory the budget cannot see" was too strong. The module documentation, the `DECODED_ENTRY_BYTES` item and the `RESIDENT_BYTES` row of the nfs route now say that. The `DECODED_ENTRY_BYTES` value stays 128 KiB: with the images a macOS client lays out it is what keeps a many-attribute image from being charged a whole 4 KiB unit's worth of body for a few dozen bytes of attributes. Review: finding P3-1 (the wording of the un-budgeted decode) and the D3 note on `DECODED_ENTRY_BYTES` (owner confirmation is asked for in the pull request). Tests: none (documentation only). `cargo test -p layerfs-nfs`: 73 passed, 0 failed (raw sum 74 with the child-process rerun). Production LOC: 164932 -> 164932 (delta 0) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent 0b877168b (164932) and of the staged tree (164932). Engine 0: documentation comments only. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 4 ++-- engine/crates/layerfs-nfs/src/apple_double.rs | 16 ++++++++++------ 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 624eebbfe2..bb95925ee9 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -179,8 +179,8 @@ the export. | --- | --- | --- | --- | | `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export). A call whose commit needs I/O in between (`Companions::reserve`) holds the slot from the decision, so the bound holds when calls race for the last one | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | -| `RESIDENT_BYTES` | 32 MiB of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost` | Spill the least recently touched bodies, decoded ones included, to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -| `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion | A whole image costing more keeps its bytes as written and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `RESIDENT_BYTES` | 32 MiB of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost`; an edit that leaves a body whole decodes it as it records it, so the count may stand one decoded body over until the next edit needs room | Spill the least recently touched bodies, decoded ones included, to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion: a cap on what one decoded body is charged, not on what a companion may store | A whole image costing more keeps its bytes as written, is charged at their length and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | A companion whose main inode the export knows belongs to that inode rather than to one name: hard links share it, main-file RENAME keeps it under the new name diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 61bc0559f2..db4110e3d3 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -41,9 +41,11 @@ //! not holding a whole image, each companion at most [`FILE_BYTES`]). Bodies up //! to [`RESIDENT_BYTES`] in all stay in memory, a body kept as written counted //! at its length and a decoded one as [`Image::cost`], so a decoded image is -//! never memory the budget cannot see; when a write or resize crosses that -//! budget, the least recently touched bodies are spilled to the export's own -//! scratch directory (see [`crate::apple_double_spill`]). Removing +//! memory the budget sees. An edit that leaves a body whole decodes it as it +//! records it rather than asking for room first, so the pool may stand one +//! decoded body over until the next write or resize needs room; that one then +//! spills the least recently touched bodies, decoded ones included, to the +//! export's own scratch directory (see [`crate::apple_double_spill`]). Removing //! or replacing a main file drops its paired `._` companion, or only that //! name when the companion is its inode's, which goes with the inode's last //! name. When [`HELD`] is reached, orphan companions whose main inode or main @@ -81,9 +83,11 @@ pub const FILE_BYTES: u64 = 1 << 20; /// Companion body bytes kept resident in memory before spilling to disk: a /// body kept as written counts its length, a decoded one [`Image::cost`]. pub const RESIDENT_BYTES: usize = 32 << 20; -/// Most bytes counted for one decoded companion, [`Image::cost`]; a whole -/// image costing more keeps its bytes as written, so one companion cannot take -/// the whole budget. +/// Most bytes counted for one decoded companion, [`Image::cost`]: a cap on +/// what one decoded body is charged to [`RESIDENT_BYTES`], not on what a +/// companion may store. A whole image costing more keeps its bytes as written +/// and is charged at their length, so one companion cannot take the whole +/// budget. pub const DECODED_ENTRY_BYTES: usize = 128 << 10; /// A name in one directory: (directory serial, name bytes). From 54b9c1b6c6fc324cebeebbbff6cc730b6725ae16 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 15 Nov 2026 03:05:56 +0000 Subject: [PATCH 43/53] fix(nfs): let any name of a companion keep it out of reclamation (lp73) A companion can hold several `._` names of its inode (a LINK of a companion name adds one), but reclamation's candidate test read only the name a companion records. A companion the client never paired with a main inode (`inode: None`) that was then linked under a second name was therefore proposed as an orphan on the strength of the first name alone: the export looked up that name's main file, answered "no such file", and dropped a companion that its other name - whose main file the export does know - still reached. One linked name lost the attributes of the other. `orphans()` now walks every name a companion holds: one whose main file a name of the index holds keeps the companion, and only a companion none of whose names the index knows becomes a candidate, for the lookup of the first such name. The slot walk, the engine lookup and the decision that follows are unchanged. Tests: new `a_companion_reached_by_one_of_its_names_is_not_an_orphan`: one slot, a companion created in a directory for a main file that does not exist (`inode: None`), LINKed under a second `._` name, then the main file of that second name created; a CREATE at the bound reclaims, finds the companion reachable through the linked name and leaves it, so the CREATE is refused and the companion still reads back. Anti-proof: with the recorded name alone the same CREATE lands (`left: Ok(()), right: Err(28)`) because the live companion was reclaimed. `cargo test -p layerfs-nfs`: 74 passed, 0 failed (raw sum 75 with the child-process rerun). Production LOC: 164932 -> 164941 (delta +9) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on git archives of the first parent d114c133d (164932) and of the staged tree (164941). Engine +9: the loop over a companion's names in `orphans`. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 3 +- engine/crates/layerfs-nfs/src/apple_double.rs | 23 +++++++--- .../layerfs-nfs/tests/apple_double_decode.rs | 44 +++++++++++++++++++ 3 files changed, 63 insertions(+), 7 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index bb95925ee9..f42c23cc0a 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -226,7 +226,8 @@ concurrent GUARDED creates of one name yield one serial and one `NFS3ERR_EXIST`. The name index is lossy (its own bound, a name never looked up, a client-side rename), so a candidate whose main inode the export does not know costs one read-only lookup of its main file in the engine, outside both -locks: a file that is there binds the companion back to that inode and keeps +locks - and a companion it holds several names of is reached by any of them, so +one whose name the index holds is no candidate at all: a file that is there binds the companion back to that inode and keeps its attributes, `NFS3ERR_NOENT` - or `NFS3ERR_STALE`/`NFS3ERR_NOTDIR`, a main file whose directory the engine no longer has, which cannot hold it either - makes it an orphan, and a lookup that cannot answer any other way leaves it diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index db4110e3d3..9a0a6a10bb 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -625,12 +625,23 @@ impl Kernel { main: None, }); } - let main = file.named.1.strip_prefix(b"._")?; - let main = (file.named.0, main.to_vec()); - // A name the index does hold reaches the companion; one it does - // not hold only makes it a candidate, since that index is - // lossy. - (!table.by_name.contains_key(&main)).then_some(Orphan { + // A name the index does hold reaches the companion; one it + // does not hold only makes it a candidate, since that index is + // lossy. Any of the names it holds reaches it, so one whose + // main file the export knows keeps it, and the first name whose + // main it does not know is the one the lookup asks about. + let mut candidate = None; + for named in std::iter::once(&file.named).chain(&file.also) { + let Some(main) = named.1.strip_prefix(b"._") else { + continue; + }; + let main = (named.0, main.to_vec()); + if table.by_name.contains_key(&main) { + return None; + } + candidate.get_or_insert(main); + } + candidate.map(|main| Orphan { serial: *serial, inode: None, main: Some(main), diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 17323fd518..9d54b4a148 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1478,3 +1478,47 @@ fn a_companion_of_a_removed_directory_is_reclaimed() { assert_eq!(outstanding, 0); fs::remove_dir_all(base).unwrap(); } + +#[test] +fn a_companion_reached_by_one_of_its_names_is_not_an_orphan() { + let base = temp("orphan-alias"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 1; + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + c.mkdir(&root, b"d", 0o755).unwrap(); + let d = c.lookup(&root, b"d").unwrap().0; + // Nothing names `ghost`, so this companion starts with no main inode and + // takes the one slot. + let ghost = c.touch(&d, b"._ghost", 0o644).unwrap(); + let body = pattern(82, 64); + c.write(&ghost.handle, 0, &body).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // The client links the companion name, then creates the main file of the + // linked name: one of the companion's names now has a main file the export + // knows. + c.link(&ghost.handle, &d, b"._kept").unwrap(); + c.touch(&d, b"kept", 0o644).unwrap(); + assert_eq!(c.read_all(&ghost.handle, 4096), body); + + // A CREATE at the bound reclaims first. The companion is reached by + // `._kept`, whose main file the export knows, so it is no orphan: nothing + // is dropped and the CREATE is refused. + c.touch(&root, b"y", 0o644).unwrap(); + assert_eq!(c.touch(&root, b"._y", 0o644).map(|_| ()), Err(NOSPC)); + assert_eq!(server.held().companions, 1); + assert_eq!(c.read_all(&ghost.handle, 4096), body); + let (kept, attr) = c.lookup(&d, b"._kept").unwrap(); + assert_eq!(kept, ghost.handle); + assert_eq!(attr.size as usize, body.len()); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} From 70c55da33328e21cd5af9f9631bfa049b5ca6453 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 15 Nov 2026 06:39:57 +0000 Subject: [PATCH 44/53] fix(nfs): trace the AppleDouble names one client asks about (lp73) A macOS client that cannot read a companion's attributes looks the same from the export whatever happened: a name it never asked for, a name the export's index could not resolve, and an answer its own caches then dropped all leave no trace behind. A run of the real client is the only way to tell them apart, so this adds an opt-in trace of exactly those requests. `LAYERFS_NFS_TRACE=1` (read once per process, off unless it is exactly `1`) prints one line per request that names an AppleDouble companion - the `._` names themselves and the main file names of the inodes that hold one - to the daemon's standard error: layerfs-nfs trace: op=LOOKUP dir=6 name="._b" main=Some(9) route=inode companion=Some(4611686018427387904) status=Ok `main` is the main inode the export's name index gave the name (or `None`), and `route` says which part of the companion index answered - the companion's own name key, the main inode, or neither - so a name no companion answers is distinguishable from one whose main file the index forgot. A CREATE that finds the companion already held reports whether it would truncate it, a SETATTR of a `._` file is traced by handle with its size, `BIND` reports a main name the kernel table re-attributed to an inode with a companion (`alias` while the inode keeps several names, `unbound` when the one it held is all it has), `UNPAIR` reports a main name whose paired `._` name the export dropped, and `RENAME`/`LINK`/`REMOVE`/`CREATE` report the companion they decided. Nothing else changes: no state is touched, and every hook costs one `OnceLock` load while the trace is off. Tests: no new test - the trace changes no behaviour and the hooks are on paths `cargo test -p layerfs-nfs` (74 passed, 0 failed, raw sum 75) already drives; checked by hand against a LINK'd companion's `._` names, where the lines above are the actual output. `lf-ci.sh` fast: 2017 passed, 0 failed. clippy -p layerfs-nfs --all-targets: no warning. Production LOC: 164941 -> 165152 (delta +211) Scope: first-party core/engine/control/api production source and shipped runtime SQL; tests, docs, tools and manifests excluded. Method: python3 tools/production_loc.py (SHA-256 d3148db88f91b09eb74eb659b2f700209776a24d022f09774dc7bb38ea1eecf6) on the first parent 54b9c1b6c (164941) and on the staged tree (165152). Engine +211: `trace.rs` and its hooks in `apple_double.rs`, `edit.rs`, `kernel.rs` and `change.rs`. Reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 18 ++ engine/crates/layerfs-nfs/src/apple_double.rs | 163 ++++++++++++++++-- .../layerfs-nfs/src/apple_double/edit.rs | 3 + engine/crates/layerfs-nfs/src/change.rs | 4 + engine/crates/layerfs-nfs/src/kernel.rs | 13 ++ engine/crates/layerfs-nfs/src/lib.rs | 1 + engine/crates/layerfs-nfs/src/trace.rs | 119 +++++++++++++ 7 files changed, 302 insertions(+), 19 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/trace.rs diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index f42c23cc0a..79c3a43a09 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -270,6 +270,24 @@ body is still held but a client cannot ask for it; a zero beside a client that lost attributes says the loss was a missing companion rather than a lost name. It is counted once, at release, over the companions held. +The requests one real client makes can be read from an optional trace +([`trace.rs`](../../../../engine/crates/layerfs-nfs/src/trace.rs)): with +`LAYERFS_NFS_TRACE=1` the export prints, to the daemon's standard error, one +line for each request that names an AppleDouble companion - the `._` names +themselves and the main file names of the inodes that hold one - carrying the +directory serial, the name, the main inode the export's name index gave the +name, which part of the companion index answered it (`route=name` for the +companion's own name key, `route=inode` for the main inode, `route=none` when +neither did), the companion serial a reply carries as its fileid, and the +status the client is answered. A CREATE that finds the companion already held +says whether it would truncate it (`existing-truncate`), a SETATTR of a `._` +file is traced by handle, `BIND` shows a main name the kernel table +re-attributed to an inode that has a companion (`alias` while that inode keeps +several names, `unbound` when the one it held is all it has), and `UNPAIR` +shows a main name whose paired `._` name the export dropped. It is off unless +the variable is exactly `1`, is read once per process, and changes no state; +the lines are written under the lock the request already holds. + ## Mount (`mount.rs`, daemon `export.rs`) ```text diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 9a0a6a10bb..f8cc7ab090 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -57,6 +57,7 @@ use crate::{ attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, + trace::{self, Route as Trace}, }; use layerfs_content::{ filesystem::{attributes::PortableMetadata, PathName}, @@ -349,13 +350,20 @@ impl Companions { /// held under that name, unless it belongs to another inode than `main`, /// else the one its main inode already has. fn resolve(&self, named: &Named, main: Option) -> Option { + self.resolve_route(named, main).0 + } + /// [`Self::resolve`], and which part of the index answered, for the trace. + fn resolve_route(&self, named: &Named, main: Option) -> (Option, Trace) { if let Some(&serial) = self.names.get(named) { let inode = self.files.get(&serial).and_then(|file| file.inode); if inode.is_none() || main.is_none() || inode == main { - return Some(serial); + return (Some(serial), Trace::Name); } } - main.and_then(|main| self.inodes.get(&main).copied()) + match main.and_then(|main| self.inodes.get(&main).copied()) { + Some(serial) => (Some(serial), Trace::Inode), + None => (None, Trace::None), + } } /// Replaces `serial`'s body by the decoded form of `bytes`, the caller's /// edited body of `len` bytes, while the resident budget takes it and the @@ -553,6 +561,16 @@ impl Companions { } } } +/// How a CREATE that found the companion already held is traced: an UNCHECKED +/// create with an explicit size truncates the body every name of the inode +/// shares, and a GUARDED or EXCLUSIVE one is answered `NFS3ERR_EXIST`. +fn opening(how: &How) -> &'static str { + match how { + How::Unchecked(sattr) if sattr.size.is_some() => "existing-truncate", + How::Unchecked(_) | How::Guarded(_) => "existing", + How::Exclusive(_) => "existing-exclusive", + } +} /// Whether a body a spill wrote out still replaces its companion: only when the /// companion is the one the snapshot saw (`used` is the tick read then) and its /// body is still in memory, so no call wrote to it while the file was written. @@ -748,9 +766,23 @@ impl Kernel { pub(crate) fn companion_named(&self, parent: u64, name: &[u8]) -> Option { let main = self.main_of(parent, name); let mut companions = self.companions(); - let serial = companions.resolve(&(parent, name.to_vec()), main)?; - let stat = Companions::stat(serial, companions.files.get(&serial)?); - companions.use_serial(serial); + let (serial, route) = companions.resolve_route(&(parent, name.to_vec()), main); + if crate::names::apple_double(name) { + trace::companion( + "LOOKUP", + parent, + name, + main, + route, + serial, + match serial { + Some(_) => "Ok", + None => "NoEnt", + }, + ); + } + let stat = Companions::stat(serial?, companions.files.get(&serial?)?); + companions.use_serial(serial?); Some(stat) } /// CREATE of an already-held companion name: UNCHECKED applies its size, @@ -796,7 +828,9 @@ impl Kernel { let named = (parent, name.to_vec()); let mut main = self.main_of(parent, name); let mut companions = self.companions(); - if let Some(serial) = companions.resolve(&named, main) { + let (held, route) = companions.resolve_route(&named, main); + if let Some(serial) = held { + trace::companion("CREATE", parent, name, main, route, held, opening(&how)); return self.companion_open(serial, how, directory, companions, tickets); } // At the index bound, reclaim the companions no name reaches any more @@ -810,7 +844,9 @@ impl Kernel { // lock this call now holds without releasing it again. main = self.main_of(parent, name); companions = self.companions(); - if let Some(serial) = companions.resolve(&named, main) { + let (held, route) = companions.resolve_route(&named, main); + if let Some(serial) = held { + trace::companion("CREATE", parent, name, main, route, held, opening(&how)); return self.companion_open(serial, how, directory, companions, tickets); } } @@ -824,6 +860,7 @@ impl Kernel { if log { companions.last_refusal_log = Some(Instant::now()); } + trace::companion("CREATE", parent, name, main, Trace::None, None, "NoSpc"); drop(companions); let refused = self.names_refused.fetch_add(1, Ordering::Relaxed) + 1; if let Some(namespace) = namespace { @@ -855,6 +892,15 @@ impl Kernel { editing: Arc::new(Mutex::new(())), }; let stat = Companions::stat(serial, &file); + trace::companion( + "CREATE", + parent, + name, + main, + Trace::None, + Some(serial), + "Ok", + ); companions.index(serial, &file); companions.attach(serial, file); drop(companions); @@ -875,17 +921,38 @@ impl Kernel { pub(crate) fn companion_remove(&self, parent: u64, name: &[u8]) -> Option { let named = (parent, name.to_vec()); let main = self.main_of(parent, name); - let (serial, inode, one_name) = { + let resolved = { let companions = self.companions(); - let serial = companions.resolve(&named, main)?; - let file = companions.files.get(&serial)?; - ( - serial, - file.inode, - !companions.holds_another(serial, &named), - ) + let (serial, route) = companions.resolve_route(&named, main); + serial.and_then(|serial| { + let file = companions.files.get(&serial)?; + Some(( + serial, + route, + file.inode, + !companions.holds_another(serial, &named), + )) + }) + }; + let Some((serial, route, inode, one_name)) = resolved else { + if crate::names::apple_double(name) { + trace::companion("REMOVE", parent, name, main, Trace::None, None, "NoEnt"); + } + return None; }; let kept = !one_name || inode.is_some_and(|inode| self.knows_another_name(inode)); + trace::companion( + "REMOVE", + parent, + name, + main, + route, + Some(serial), + match kept { + true => "name-dropped", + false => "companion-dropped", + }, + ); let spilled = { let mut companions = self.companions(); if kept { @@ -927,11 +994,23 @@ impl Kernel { let Some(&serial) = companions.names.get(&named) else { return; }; - if companions + let of_inode = companions .files .get(&serial) - .is_some_and(|file| file.inode.is_some()) - { + .is_some_and(|file| file.inode.is_some()); + trace::companion( + "UNPAIR", + parent, + name, + companions.files.get(&serial).and_then(|file| file.inode), + Trace::Name, + Some(serial), + match of_inode { + true => "name-dropped", + false => "companion-dropped", + }, + ); + if of_inode { companions.drop_name(serial, &named); None } else { @@ -977,6 +1056,7 @@ impl Kernel { .resolve(&named, main) .is_some_and(|other| other != serial) { + trace::companion("LINK", parent, name, main, Trace::Name, None, "Exist"); return Err(Status::Exist); } let Some(mut file) = companions.detach(serial) else { @@ -985,6 +1065,7 @@ impl Kernel { file.also.push(named); file.used = companions.tick(); let stat = Companions::stat(serial, &file); + trace::companion("LINK", parent, name, main, Trace::None, Some(serial), "Ok"); companions.index(serial, &file); companions.attach(serial, file); Ok((stat, directory)) @@ -1008,7 +1089,20 @@ impl Kernel { if !crate::names::apple_double(new_name) || new_name.len() > 255 { return Some(Err(Status::Access)); } - Some(self.rename_companion(serial, (to, new_name.to_vec()), to_main)) + let renamed = self.rename_companion(serial, (to, new_name.to_vec()), to_main); + trace::companion( + "RENAME", + to, + new_name, + to_main, + Trace::None, + Some(serial), + match &renamed { + Ok(()) => "Ok", + Err(status) => trace::status(*status), + }, + ); + Some(renamed) } /// Moves `serial`'s companion to `target`, under `to_main`'s inode. /// @@ -1125,4 +1219,35 @@ impl Kernel { pub(crate) fn companions_held(&self) -> Holding { self.companions().holding() } + /// Traces a request about a main file (`op`, its directory and name) when + /// the export holds a companion for that inode: these are the requests + /// that make a `._` name resolvable (see [`crate::trace`]). + pub(crate) fn trace_main_file( + &self, + op: &str, + parent: u64, + name: &[u8], + inode: u64, + status: &str, + ) { + if !trace::enabled() { + return; + } + let companion = self.companions().inodes.get(&inode).copied(); + if companion.is_some() { + trace::main_file(op, parent, name, Some(inode), companion, status); + } + } + /// Traces a name the export's kernel table bound to `inode` (`alias`: kept + /// as another name of it) or dropped from it (`unbound`), when the inode + /// has a companion: a `._` name resolves through those names. + pub(crate) fn trace_bind(&self, parent: u64, name: &[u8], inode: u64, status: &str) { + if !trace::enabled() { + return; + } + let companion = self.companions().inodes.get(&inode).copied(); + if companion.is_some() { + trace::main_file("BIND", parent, name, Some(inode), companion, status); + } + } } diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index eac3c6670e..dc49f336a5 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -145,6 +145,9 @@ impl Kernel { if size > FILE_BYTES { return Err(Status::FBig); } + if crate::trace::enabled() { + crate::trace::handle("SETATTR", serial, &format!("size={size}")); + } self.edit_companion(serial, Edit::Size(size as usize))?; } let mut companions = self.companions(); diff --git a/engine/crates/layerfs-nfs/src/change.rs b/engine/crates/layerfs-nfs/src/change.rs index 81ebb40345..14a59dc31c 100644 --- a/engine/crates/layerfs-nfs/src/change.rs +++ b/engine/crates/layerfs-nfs/src/change.rs @@ -500,6 +500,9 @@ impl Kernel { tickets, |_| Ok(MutationInput::Named(remove::unlink(parent, checked))), )?; + if let Some(detached) = &published.detached { + self.trace_main_file("REMOVE", parent, name, detached.serial, "Ok"); + } self.finish_unlink(parent, name, retire, published.detached); Ok(published.wcc[0].clone()) } @@ -660,6 +663,7 @@ impl Kernel { let stat = published.stat.ok_or(Status::ServerFault)?; // The engine took one more lookup reference; the export holds one. self.entry_taken(&stat, parent, name); + self.trace_main_file("LINK", parent, name, stat.serial, "Ok"); Ok((stat, published.wcc[0].clone())) } /// SETATTR. `guard` is the client's expected ctime (seconds, diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 3540cfefb3..b50c8f3498 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -460,6 +460,7 @@ impl Kernel { )?; // The deciding visit took one engine reference; keep exactly one. self.entry_taken(&stat, parent, name); + self.trace_main_file("LOOKUP", parent, name, stat.serial, "Ok"); Ok(stat) } /// A visit or mutation that decided `stat` as the entry `name` of @@ -498,6 +499,18 @@ impl Kernel { // that retiring the serial drops no other name. table.remember_alias(stat.serial, &old); } + // Held here: the table lock, and inside it the + // companion lock as everywhere else. Off unless the + // trace is on. + self.trace_bind( + parent, + name, + stat.serial, + match stat.namespace_refs <= 1 { + true => "unbound", + false => "alias", + }, + ); } } table.bind_name(named, stat.serial); diff --git a/engine/crates/layerfs-nfs/src/lib.rs b/engine/crates/layerfs-nfs/src/lib.rs index ca288a9089..a884bdc80d 100644 --- a/engine/crates/layerfs-nfs/src/lib.rs +++ b/engine/crates/layerfs-nfs/src/lib.rs @@ -32,6 +32,7 @@ mod nfs; pub mod refresh; pub mod rpc; mod server; +mod trace; pub mod xdr; pub use kernel::Released; diff --git a/engine/crates/layerfs-nfs/src/trace.rs b/engine/crates/layerfs-nfs/src/trace.rs new file mode 100644 index 0000000000..19cddd97e6 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/trace.rs @@ -0,0 +1,119 @@ +//! An optional trace of the AppleDouble names one client asks about. +//! +//! On a real client the export sees only the requests that arrive: whether a +//! companion a client cannot read was never asked for, was asked for under a +//! name the export cannot resolve, or was answered and then dropped by the +//! client, is invisible from the outside. This module prints one line for each +//! request that names an AppleDouble (`._`) companion - the `._` names +//! themselves and the main file names of the inodes that have one - with the +//! directory it named them in, the name, the companion the export resolved, +//! which part of its index found it (the companion's own name key or the main +//! inode) or that neither did, and the answer the client gets. A run of a real +//! client with this on is the only way to read its sequence; see +//! `docs/architecture/engine/kernel-routes/nfs.md`. +//! +//! `LAYERFS_NFS_TRACE=1` turns it on; anything else, and no variable at all, +//! leaves it off. It is read once per process and changes no state, so when it +//! is off every hook costs one `OnceLock` load. Lines go to the daemon's +//! standard error, like the release line, and are written under whatever lock +//! the request already holds. +use crate::attributes::Status; +use std::sync::OnceLock; + +static ENABLED: OnceLock = OnceLock::new(); + +/// Whether this process traces AppleDouble names. +pub fn enabled() -> bool { + *ENABLED.get_or_init(|| std::env::var("LAYERFS_NFS_TRACE").as_deref() == Ok("1")) +} + +/// Which part of the export's index found a companion for a `._` name. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum Route { + /// The companion's own name key (`Companions::names`). + Name, + /// The main inode the name's main file has (`Companions::inodes`). + Inode, + /// Neither: no companion answers that name. + None, +} +impl Route { + const fn named(self) -> &'static str { + match self { + Route::Name => "name", + Route::Inode => "inode", + Route::None => "none", + } + } +} + +/// How a status is traced: the RFC's own name for it (`Ok`, `NoEnt`, `Exist`, +/// ...), for the answers a companion request gives. +pub fn status(status: Status) -> &'static str { + match status { + Status::Ok => "Ok", + Status::NoEnt => "NoEnt", + Status::Exist => "Exist", + Status::Access => "Access", + Status::Stale => "Stale", + Status::NotDir => "NotDir", + Status::NoSpc => "NoSpc", + Status::Inval => "Inval", + Status::Perm => "Perm", + Status::Io => "Io", + Status::NotSync => "NotSync", + Status::FBig => "FBig", + _ => "other", + } +} + +/// One request about a `._` name: `main` is the main inode the export's name +/// index gave it (`None` when it does not know the main file), `found` the +/// companion it resolved, and `route` which key found it. +pub fn companion( + op: &str, + directory: u64, + name: &[u8], + main: Option, + route: Route, + found: Option, + status: &str, +) { + if !enabled() { + return; + } + eprintln!( + "layerfs-nfs trace: op={op} dir={directory} name={:?} main={main:?} route={} companion={found:?} status={status}", + String::from_utf8_lossy(name), + route.named() + ); +} + +/// One request about a companion by handle only, where the client named no +/// name: a SETATTR of a `._` file it already holds, which can truncate the +/// body shared by every name of the inode. +pub fn handle(op: &str, companion: u64, detail: &str) { + if !enabled() { + return; + } + eprintln!("layerfs-nfs trace: op={op} companion={companion} {detail}"); +} + +/// One request about a main file whose inode has a companion, which is where +/// the export learns (or forgets) the names a `._` name resolves through. +pub fn main_file( + op: &str, + directory: u64, + name: &[u8], + inode: Option, + companion: Option, + status: &str, +) { + if !enabled() { + return; + } + eprintln!( + "layerfs-nfs trace: op={op} dir={directory} name={:?} inode={inode:?} companion={companion:?} status={status}", + String::from_utf8_lossy(name) + ); +} From 6da07ef6eda3e5b78d45e0f2530e51a8af87837a Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Sun, 15 Nov 2026 07:43:40 +0000 Subject: [PATCH 45/53] fix(nfs): keep an inode's `._` name when its main name goes (lp73) `Kernel::companion_drop_for` dropped the `._` key when a main file name was removed, so `rm a` of a file `b` still named answered `._a` with NFS3ERR_NOENT although the inode and its companion were alive (a macOS 27.2 trace showed the shape three times in one matrix). A companion that belongs to an inode now keeps that `._` name until the inode's last name, which already takes the companion with every `._` name it holds (`companion_drop_inode` -> `take_serial` -> `unindex`); a companion no main inode owns goes as before. A new file under the freed name reaches the old companion nowhere: `Companions::resolve` takes a name key only for the inode its companion belongs to. `Holding` and `Released::companions_unreachable` carry the release count, so a status read reports the same number as the release line. Tests (tests/apple_double_decode.rs): the matrix's g2/g3/g5 orders (`ln`, `rm` before and after one read of the linked name), a new file under the removed name, and the inode's last name reclaiming the companion and every `._` name key, with `._a`/`._b` reading one whole image. The three order tests failed on the parent with `._a` = NFS3ERR_NOENT. Docs: nfs.md states the hard-link rule, `UNPAIR name-kept`, the native route's `env_clear` trace wrapper and the live `unreachable` count. Production LOC: 165152 -> 165155 (delta +3); scope: first-party product source under core|engine|control|api, tools/production_loc.py on the parent tree and the staged tree; reference absent (retired R9c; last counted 65,417 at tree 498dd1917812). --- docs/architecture/engine/kernel-routes/nfs.md | 27 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 69 +++--- .../crates/layerfs-nfs/src/kernel/released.rs | 7 + engine/crates/layerfs-nfs/src/trace.rs | 5 + .../layerfs-nfs/tests/apple_double_decode.rs | 212 ++++++++++++++++++ 5 files changed, 292 insertions(+), 28 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 79c3a43a09..b7d76c09ed 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -185,7 +185,14 @@ the export. A companion whose main inode the export knows belongs to that inode rather than to one name: hard links share it, main-file RENAME keeps it under the new name and existing aliases, and only the inode's last name (or its silly rename) -drops it. It can hold several of the inode's `._` names at once: a LINK of a +drops it. A name of the inode that goes does not take its `._` name with it: +after `rm a` of a file that `b` still names, `._a` still answers the inode's +companion, because the `._` name key stays until the inode's last name (a +client whose `actimeo` expired may ask either name). A new file that takes the +freed name reaches the old companion nowhere: `Companions::resolve` takes a +name key only for the inode its companion belongs to, so `._a` answers that new +inode's companion, or `NFS3ERR_NOENT` while it has none. It can hold several of +the inode's `._` names at once: a LINK of a companion name (`._a` to `._b`, which a client that carries the attributes to a new name sends) adds one, answering `NFS3ERR_EXIST` for a name already held and `NFS3ERR_ACCES` for a name of the Workspace, and a REMOVE of one of those @@ -268,7 +275,10 @@ companions no name reaches - neither the name a companion records nor another name of its inode finds it - which is the shape a lost attribute takes when the body is still held but a client cannot ask for it; a zero beside a client that lost attributes says the loss was a missing companion rather than a lost name. -It is counted once, at release, over the companions held. +The same count is in the holdings a status read reports +(`Released::companions_unreachable`), so the two never disagree; it walks the +companion index, like the release line and the reclamation walk, and only those +diagnostics read it. The requests one real client makes can be read from an optional trace ([`trace.rs`](../../../../engine/crates/layerfs-nfs/src/trace.rs)): with @@ -284,10 +294,21 @@ says whether it would truncate it (`existing-truncate`), a SETATTR of a `._` file is traced by handle, `BIND` shows a main name the kernel table re-attributed to an inode that has a companion (`alias` while that inode keeps several names, `unbound` when the one it held is all it has), and `UNPAIR` -shows a main name whose paired `._` name the export dropped. It is off unless +shows what a main name that went left behind: `name-kept` when the companion +belongs to its inode and keeps the `._` name, `companion-dropped` when the +companion goes with it. It is off unless the variable is exactly `1`, is read once per process, and changes no state; the lines are written under the lock the request already holds. +On the `native` route the daemon is started with `env_clear` and an empty +environment (`control/crates/layerfs-sandbox-backend/src/local/create.rs`), so +it does not inherit `LAYERFS_NFS_TRACE=1` from the shell that created the +Sandbox: a trace run there needs `machine update native --daemon` pointed at a +wrapper that exports the variable and `exec`s the real daemon (measured on +macOS 27.2 for #636, where the plain variable gave 0 trace lines and the wrapper +55 and 77 on the two matrices). Other routes start the daemon through a worker +or container, where the environment is passed differently. + ## Mount (`mount.rs`, daemon `export.rs`) ```text diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index f8cc7ab090..2230d37f17 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -46,9 +46,11 @@ //! decoded body over until the next write or resize needs room; that one then //! spills the least recently touched bodies, decoded ones included, to the //! export's own scratch directory (see [`crate::apple_double_spill`]). Removing -//! or replacing a main file drops its paired `._` companion, or only that -//! name when the companion is its inode's, which goes with the inode's last -//! name. When [`HELD`] is reached, orphan companions whose main inode or main +//! or replacing a main file drops its paired `._` companion when no main +//! inode owns it; a companion that belongs to an inode goes with the inode, so +//! `._` still answers for that inode after the name went, and only the +//! inode's last name takes the companion and every `._` name it holds. When +//! [`HELD`] is reached, orphan companions whose main inode or main //! file the export no longer knows are reclaimed first, and only if [`HELD`] //! live companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. use crate::{ @@ -185,6 +187,9 @@ pub(crate) struct Holding { pub slotted: usize, pub resident_bytes: usize, pub decoded: usize, + /// The companions no name reaches, so that a status read and the release + /// line report the same number. + pub unreachable: usize, } /// The companions of one export. @@ -534,9 +539,12 @@ impl Companions { /// The companions no name of the export reaches: neither the name it /// records nor another name of its inode finds it. Such a companion holds /// its body with no way for a client to ask for it, which is one of the two - /// shapes a lost attribute takes (the other is no companion at all). It is - /// counted once, when the export releases, so a file of reports from a real - /// client can say which shape a loss had. + /// shapes a lost attribute takes (the other is no companion at all). A + /// companion reached only through its main inode - one whose `._` name the + /// client removed, or whose main file went under that name - is reachable, + /// which is why a name key kept for an inode's companion is not a leak. + /// Counted with the other holdings, by who reports them: the release line + /// says which shape a loss had, and a status read says so while serving. fn unreachable(&self) -> usize { self.files .iter() @@ -558,6 +566,7 @@ impl Companions { slotted: self.slots.len(), resident_bytes: self.resident_bytes, decoded: self.decoded, + unreachable: self.unreachable(), } } } @@ -974,13 +983,24 @@ impl Kernel { remembered + table.aliases.get(&inode).map_or(0, Vec::len) > 1 } /// The main file `name` in `parent` was removed, silly-renamed or replaced - /// by `RENAME`: drops the companion held under `._`, or only that - /// name when the companion belongs to an inode, which goes with the - /// inode's last name instead (see [`Kernel::companion_drop_inode`]). A - /// plain non-replacing `RENAME` of a main file only cleans the destination - /// name `to/new_name` (via `finish_unlink`) and leaves `from/name` alone so - /// a client that renames `a -> b` and then renames `._a -> ._b` can still - /// move the companion across. + /// by `RENAME`: drops the companion held under `._` when no main + /// inode owns it, and leaves an inode's companion to the inode - it goes + /// with the inode's last name instead (see + /// [`Kernel::companion_drop_inode`]), which is also where the `._` names it + /// held go (`Companions::unindex`). A plain non-replacing `RENAME` of a + /// main file only cleans the destination name `to/new_name` (via + /// `finish_unlink`) and leaves `from/name` alone so a client that renames + /// `a -> b` and then renames `._a -> ._b` can still move the companion + /// across. + /// + /// The `._` name stays after its main name for as long as the inode does, + /// because the inode's FinderInfo and attributes are the file's: `/rm a` + /// on a file `b` still names leaves `._a` answering the companion of the + /// inode, rather than reporting attributes that the file `b` still has as + /// gone. A new file under that name reaches the old companion nowhere: + /// [`Companions::resolve`] takes a name key only for the inode its + /// companion belongs to, so the answer falls back to that inode's + /// companion, which a new file does not have. pub(crate) fn companion_drop_for(&self, parent: u64, name: &[u8]) { if crate::names::apple_double(name) { return; @@ -1006,15 +1026,13 @@ impl Kernel { Trace::Name, Some(serial), match of_inode { - true => "name-dropped", + true => "name-kept", false => "companion-dropped", }, ); - if of_inode { - companions.drop_name(serial, &named); - None - } else { - companions.take_serial(serial) + match of_inode { + true => None, + false => companions.take_serial(serial), } }; unlink_paths(spilled); @@ -1193,24 +1211,25 @@ impl Kernel { /// Drops every companion and removes the export's spill directory; returns /// what the index held. pub(crate) fn companions_release(&self) -> Holding { - let (held, dir, unreachable) = { + let (holding, dir) = { let mut companions = self.companions(); + let holding = companions.holding(); let dir = companions.spill_dir.take(); - let unreachable = companions.unreachable(); - (std::mem::take(&mut *companions), dir, unreachable) + drop(std::mem::take(&mut *companions)); + (holding, dir) }; if let Some(dir) = dir { drop(fs::remove_dir_all(dir)); } - let holding = held.holding(); if holding.held > 0 { eprintln!( - "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={} unreachable={unreachable}", + "layerfs-nfs: AppleDouble companions released: export={:?} held={} slotted={} decoded={} resident_bytes={} unreachable={}", self.mount(), holding.held, holding.slotted, holding.decoded, - holding.resident_bytes + holding.resident_bytes, + holding.unreachable ); } holding diff --git a/engine/crates/layerfs-nfs/src/kernel/released.rs b/engine/crates/layerfs-nfs/src/kernel/released.rs index 3fc13af3c0..51a4d08db5 100644 --- a/engine/crates/layerfs-nfs/src/kernel/released.rs +++ b/engine/crates/layerfs-nfs/src/kernel/released.rs @@ -44,6 +44,7 @@ impl Kernel { companion_bytes: companions.resident_bytes, companions_slotted: companions.slotted, companions_decoded: companions.decoded, + companions_unreachable: companions.unreachable, files: table.files.len(), directories: table.directories.len(), lookups: table.lookups.len(), @@ -85,6 +86,12 @@ pub struct Released { pub companions_slotted: usize, /// Of the companions held, those kept decoded. pub companions_decoded: usize, + /// Of the companions held, those no name reaches: neither the name a + /// companion records nor another name of its inode finds it. It is what a + /// status read and the release line both report, so a client that lost + /// attributes can be told whether the export still held the body with no + /// way to ask for it. + pub companions_unreachable: usize, /// AppleDouble companions created, over the export's life. pub names_detached: u64, /// References collected beyond the bound, over the export's life. diff --git a/engine/crates/layerfs-nfs/src/trace.rs b/engine/crates/layerfs-nfs/src/trace.rs index 19cddd97e6..c8759dcf1f 100644 --- a/engine/crates/layerfs-nfs/src/trace.rs +++ b/engine/crates/layerfs-nfs/src/trace.rs @@ -17,6 +17,11 @@ //! is off every hook costs one `OnceLock` load. Lines go to the daemon's //! standard error, like the release line, and are written under whatever lock //! the request already holds. +//! +//! A `native` Sandbox's daemon is spawned after `env_clear`, so it does not +//! inherit this variable from the shell that created the Sandbox; tracing one +//! means pointing the machine's daemon at a wrapper that exports it and +//! `exec`s the real daemon (see `docs/architecture/engine/kernel-routes/nfs.md`). use crate::attributes::Status; use std::sync::OnceLock; diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 9d54b4a148..5d11c9b490 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1296,6 +1296,218 @@ fn a_hard_link_keeps_the_companion_under_its_other_names() { fs::remove_dir_all(base).unwrap(); } +/// `name` and its `._` companion holding a whole image, as `cp` leaves +/// them: the main file's handle, the companion's, and the bytes written. +fn pair(c: &mut Client, root: &[u8], name: &[u8], seed: u32) -> (Vec, Vec, Vec) { + let main = c.touch(root, name, 0o644).unwrap(); + c.write(&main.handle, 0, b"the data file").unwrap(); + let mut paired = b"._".to_vec(); + paired.extend_from_slice(name); + let ad = c.touch(root, &paired, 0o644).unwrap(); + let whole = image([seed as u8; 32], &[(b"user.kept", pattern(seed, 64))]); + c.write(&ad.handle, 0, &whole).unwrap(); + (main.handle, ad.handle, whole) +} + +#[test] +fn a_removed_name_still_reaches_the_companion_of_its_inode() { + let base = temp("removed-name"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + // `cp a`, then `ln a b`: one inode behind two names, the attributes under + // `._a`. This is the matrix's g2 order: `ln`, `rm` of the original before + // the linked name was read once. + let (a, ad, whole) = pair(&mut c, &root, b"a", 13); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + assert_eq!(server.held().companions, 1, "b still names the inode"); + assert_eq!(c.lookup(&root, b"a").map(|_| ()), Err(NOENT)); + + // The name is gone, the inode is not: `._a` is still the attributes of the + // file `b` names. A client that still holds `._a`, or asks for it again + // once its `actimeo` expired, reads them there instead of finding nothing. + let (named, attr) = c.lookup(&root, b"._a").unwrap(); + assert_eq!( + named, ad, + "a name of the inode that is gone still answers its `._` name" + ); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&named, 64 * 1024), whole); + assert_eq!( + server.held().companions_unreachable, + 0, + "the name key reaches it" + ); + let (linked, attr) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(linked, ad, "the surviving name answers it too"); + assert_eq!(attr.size as usize, whole.len()); + assert_eq!(c.read_all(&linked, 64 * 1024), whole); + assert_eq!(server.held().companions, 1); + + drop(c); + let released = server.stop(); + assert_eq!(released.companions, 1, "the last name stays to the export"); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_name_the_link_read_before_its_removal_keeps_its_companion_name() { + let base = temp("removed-name-read"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + // The matrix's g3 order: `ln`, one read of the linked name and of its `._` + // name, then `rm` of the original. + let (a, ad, whole) = pair(&mut c, &root, b"a", 14); + c.link(&a, &root, b"b").unwrap(); + let (read, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(read, ad, "the linked name reaches the inode's companion"); + assert_eq!(c.lookup(&root, b"b").unwrap().0, a); + c.remove(&root, b"a").unwrap(); + + // Every name of the inode keeps answering, the removed one included. + let (named, _) = c.lookup(&root, b"._a").unwrap(); + assert_eq!(named, ad); + assert_eq!(c.read_all(&named, 64 * 1024), whole); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_name_asked_right_after_its_removal_still_reaches_the_companion() { + let base = temp("removed-name-after"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + // The matrix's g5 order: `ln`, `rm` of the original, the linked name read + // right after, and then the removed name's `._` name. + let (a, ad, whole) = pair(&mut c, &root, b"a", 15); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + let (linked, _) = c.lookup(&root, b"b").unwrap(); + assert_eq!(linked, a, "b is the inode's remaining name"); + let (named, _) = c.lookup(&root, b"._a").unwrap(); + assert_eq!(named, ad); + assert_eq!(c.read_all(&named, 64 * 1024), whole); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn a_new_file_under_a_removed_name_does_not_reach_the_old_companion() { + let base = temp("removed-name-reused"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let (a, ad, whole) = pair(&mut c, &root, b"a", 16); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + + // Another inode takes the freed name. The `._a` name the old companion + // still holds is the one the inode that had it answers, not this file `a` + // is now: `Companions::resolve` takes a name key only for the inode the + // companion belongs to. + let fresh = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&fresh.handle, 0, b"the new data file").unwrap(); + assert_eq!( + c.lookup(&root, b"._a").map(|_| ()), + Err(NOENT), + "the new file `a` has no attributes yet" + ); + // The old attributes are still the file `b` names, and the old body is + // untouched by the file that took the name. + let (kept, _) = c.lookup(&root, b"._b").unwrap(); + assert_eq!(kept, ad); + assert_eq!(c.read_all(&kept, 64 * 1024), whole); + + // A companion created under the name is the new inode's: it starts empty + // and never reads the old body. + let new_ad = c.touch(&root, b"._a", 0o644).unwrap(); + assert_ne!(new_ad.handle, ad, "another companion for another inode"); + assert_eq!(c.getattr(&new_ad.handle).unwrap().size, 0); + let fresh_whole = image([0x17; 32], &[(b"user.new", pattern(17, 32))]); + c.write(&new_ad.handle, 0, &fresh_whole).unwrap(); + assert_eq!(c.read_all(&new_ad.handle, 64 * 1024), fresh_whole); + assert_eq!(server.held().companions, 2); + assert_eq!(c.lookup(&root, b"._b").unwrap().0, ad); + assert_eq!(c.read_all(&ad, 64 * 1024), whole); + + // The old inode's last name takes only the old companion and the `._a` + // name it held, so the new file's attributes stay. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 1, "only the new file's companion"); + assert_eq!(c.getattr(&ad), Err(STALE)); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + assert_eq!(c.lookup(&root, b"._a").unwrap().0, new_ad.handle); + assert_eq!(c.read_all(&new_ad.handle, 64 * 1024), fresh_whole); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + +#[test] +fn the_last_name_of_a_hard_link_reclaims_its_companion_and_every_name_key() { + let base = temp("removed-name-last"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let (a, ad, whole) = pair(&mut c, &root, b"a", 18); + c.link(&a, &root, b"b").unwrap(); + c.remove(&root, b"a").unwrap(); + assert_eq!(c.lookup(&root, b"._a").unwrap().0, ad); + assert_eq!(c.read_all(&ad, 64 * 1024), whole); + + // The inode's last name goes: the companion goes with it, and so does the + // `._a` name key it kept for the name that went first. + c.remove(&root, b"b").unwrap(); + assert_eq!(server.held().companions, 0); + assert_eq!(server.held().companions_unreachable, 0); + assert_eq!(c.getattr(&ad), Err(STALE)); + assert_eq!(c.lookup(&root, b"._a").map(|_| ()), Err(NOENT)); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + + drop(c); + let released = server.stop(); + assert_eq!( + (released.companions, released.companions_unreachable), + (0, 0) + ); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_linked_companion_name_is_another_name_of_the_same_companion() { let base = temp("companion-link"); From 46550ff30bf1e16ffe22d6ac4c70d7f1db8474a1 Mon Sep 17 00:00:00 2001 From: liuyuchen <152110621+jiangkoumo@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:47:22 +0800 Subject: [PATCH 46/53] fix(nfs): mount macOS exports with nordirplus The macOS NFS client answers a `._` name that is absent from a directory's cached READDIRPLUS listing with "not found" without ever asking the server (the skipdu path in nfs_vnop_lookup), and this export serves AppleDouble companions without listing them, so a hard-linked file's extended attributes could read back empty. Turning READDIRPLUS off makes every `._` name arrive as a LOOKUP. Nothing else about the mount or the listing changes. Production LOC: 165155 -> 165155 (delta 0); core/engine/control/api production source only (api/crates/layerfs-*/src, api/python/src/layerfs, api JS packages), counted with tools/production_loc.py at the parent and the committed tree; comments, tests and docs excluded. --- docs/architecture/engine/kernel-routes/nfs.md | 6 +++++- engine/crates/layerfs-daemon/src/control/export.rs | 8 ++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index b7d76c09ed..5205d22d6a 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -328,10 +328,14 @@ or container, where the environment is passed differently. | 2 `DUMP`; 3 `UMNT`; 5 `EXPORT` | Empty list; success; one export with no groups | Client options are the daemon's `Mounter::host`. macOS: -`vers=3,tcp,port={port},mountport={port},locallocks,nfc,noatime,actimeo=60,rsize=262144,wsize=262144,soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse` +`vers=3,tcp,port={port},mountport={port},locallocks,nfc,noatime,actimeo=60,rsize=262144,wsize=262144,soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse,nordirplus` (`rsize`/`wsize` are `TRANSFER_WINDOW`); elsewhere `vers=3,proto=tcp,port={port},mountport={port},mountproto=tcp,nolock,actimeo=60` ([`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs)). +`nordirplus` turns READDIRPLUS off: a macOS client holding a directory's +complete READDIRPLUS listing answers a `._` name absent from it with ENOENT +and never asks the server, and this export serves AppleDouble companions +without listing them, so every `._` name has to arrive as a LOOKUP. An NFS ready receipt has `abi_major == 0` and its `mount_id` is the port. ## Application SQLite databases on the NFS route diff --git a/engine/crates/layerfs-daemon/src/control/export.rs b/engine/crates/layerfs-daemon/src/control/export.rs index 2128e08893..bffb08e420 100644 --- a/engine/crates/layerfs-daemon/src/control/export.rs +++ b/engine/crates/layerfs-daemon/src/control/export.rs @@ -97,14 +97,18 @@ impl Mounter { /// access time: this export keeps one timestamp and shows it as atime, /// mtime and ctime alike, and `layerfs-nfs` decodes and drops a SETATTR's /// access time, so the update would cost one SETATTR per file a read or a - /// scan touches and change nothing. + /// scan touches and change nothing. `nordirplus` turns READDIRPLUS off: + /// a client holding a directory's complete READDIRPLUS listing answers a + /// `._` name absent from it with "not found" and never asks the server, + /// and this export never lists the AppleDouble companions it serves, so + /// every `._` name has to arrive as a LOOKUP. pub fn host() -> Self { let helper = |words: &[&str]| Helper(words.iter().map(|w| (*w).to_owned()).collect()); if cfg!(target_os = "macos") { // `rsize`/`wsize` ask for the window FSINFO declares; the client // clamps to the smaller of the two. let options = format!( - "vers=3,tcp,port={{port}},mountport={{port}},locallocks,nfc,noatime,actimeo=60,rsize={WINDOW},wsize={WINDOW},soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse" + "vers=3,tcp,port={{port}},mountport={{port}},locallocks,nfc,noatime,actimeo=60,rsize={WINDOW},wsize={WINDOW},soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse,nordirplus" ); Self { mount: helper(&["/sbin/mount_nfs", "-o", &options, "127.0.0.1:/", "{dir}"]), From 9db8f4d35ca1401a4b744bcdf0ac10d42012f07f Mon Sep 17 00:00:00 2001 From: YifanXu1999 Date: Tue, 17 Nov 2026 12:02:13 +0800 Subject: [PATCH 47/53] fix(nfs): no LOOKUP answers the export's last directory observation (#637 review) #637 stopped LOOKUP answering `directory_wcc` (the export's last observation of a directory, which nothing ages) except on one path: a LOOKUP of an AppleDouble companion still answered it. Finder asks for `._` names all the time, so an install or another writer's change to the directory kept reaching the client as the old mtime/nlink. That LOOKUP is answered by the export alone and no job reads the directory, so it now sends no `dir_attributes`, as `.`, `..` and silly names already do. A failed LOOKUP's directory row (#637's `Refused::directory`) is now kept as the export's observation, as a successful LOOKUP's row is, so a companion CREATE/REMOVE/RENAME `wcc_data` after it answers those facts rather than older ones. Docs: nfs.md's LOOKUP row names the companion and the kept observation. Test: new `export.rs::a_companion_lookup_never_answers_a_stale_directory_observation`. It fails on the parent (b9b2a3188d) with the stale `nlink 2` directory and passes here. Production LOC: 171,501 -> 171,498 (delta -3) core 39,795 -> 39,795 (0) engine 76,924 -> 76,921 (-3) layerfs-nfs -3 control 48,436 -> 48,436 (0) api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent b9b2a3188d and the staged tree Co-Authored-By: Claude Opus 5.5 --- docs/architecture/engine/kernel-routes/nfs.md | 2 +- engine/crates/layerfs-nfs/src/kernel.rs | 19 +++----- engine/crates/layerfs-nfs/tests/export.rs | 47 +++++++++++++++++++ 3 files changed, 55 insertions(+), 13 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 0da0fd522e..83db39b278 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -154,7 +154,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | Rule | Source | | --- | --- | | One owner visit answers a LOOKUP: the job that resolves a name has already read the directory's own row, so the reply's `dir_attributes` cost no second visit | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | -| A LOOKUP that fails answers the directory's own fresh facts whenever the job that failed read its row, which is every name this export looks up: a name that binds nothing still read its parent's row in the same visit. `.`, `..`, a silly name and a refusal decided before any visit read no directory row and send no `dir_attributes`, so the client falls back to its own `actimeo`; RFC 1813 makes both fields optional. No LOOKUP answer repeats the export's last observation of the directory, which nothing ages | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | +| A LOOKUP that fails answers the directory's own fresh facts whenever the job that failed read its row, which is every name this export looks up: a name that binds nothing still read its parent's row in the same visit. `.`, `..`, a silly name, an AppleDouble companion and a refusal decided before any visit read no directory row and send no `dir_attributes`, so the client falls back to its own `actimeo`; RFC 1813 makes both fields optional. No LOOKUP answer repeats the export's last observation of the directory, which nothing ages. A failed LOOKUP's directory row is kept as the export's observation, as a successful one's is | [`nfs.rs`](../../../../engine/crates/layerfs-nfs/src/nfs.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`kernel_read.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_read.rs) | | `read.rs` holds what a read answers: the entry, its directory and its descriptors, and the refusal with its status (`NFS3ERR_STALE` for an engine `Stale`, else `NFS3ERR_IO`) and the directory row the job read | [`read.rs`](../../../../engine/crates/layerfs-nfs/src/read.rs) | | An export remembers the facts it last published or observed for a directory (LOOKUP, GETATTR, OPENDIR, a publishing change) and answers from them only where no job reads that directory: an AppleDouble companion's `wcc_data`, whose change never touches it. A directory listing is not such a place: its reply says only what its own window read | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs), [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | diff --git a/engine/crates/layerfs-nfs/src/kernel.rs b/engine/crates/layerfs-nfs/src/kernel.rs index 2dd78bb19a..48c5c087bf 100644 --- a/engine/crates/layerfs-nfs/src/kernel.rs +++ b/engine/crates/layerfs-nfs/src/kernel.rs @@ -475,11 +475,9 @@ impl Kernel { _ if name.len() > 255 => return Err(Refused::plain(Status::NameTooLong)), _ => {} } - // An AppleDouble companion lives in the export alone, so its reply's - // directory half is the facts this export last answered for the - // directory: a companion change never touches it. + // A companion lives in the export alone: no job read the directory. if let Some(stat) = self.companion_named(parent, name) { - return Ok((stat, self.directory_wcc(parent).0)); + return Ok((stat, None)); } if self.refuses_apple_double() && crate::names::apple_double(name) { if parent != self.root() && !self.table().parents.contains_key(&parent) { @@ -495,14 +493,11 @@ impl Kernel { .map_err(Refused::plain); } let path = PathName::from_bytes(name).map_err(|_| Refused::plain(Status::Inval))?; - let answer = self.observe( - parent, - None, - KernelReadOperation::Lookup { parent, name: path }, - )?; - if let Some(directory) = &answer.parent { - self.observed(directory); - } + let lookup = KernelReadOperation::Lookup { parent, name: path }; + let answer = self.observe(parent, None, lookup).inspect_err(|refused| { + refused.directory.iter().for_each(|row| self.observed(row)); + })?; + answer.parent.iter().for_each(|row| self.observed(row)); // The deciding visit took one engine reference; keep exactly one. self.entry_taken(&answer.stat, parent, name); self.trace_main_file("LOOKUP", parent, name, answer.stat.serial, "Ok"); diff --git a/engine/crates/layerfs-nfs/tests/export.rs b/engine/crates/layerfs-nfs/tests/export.rs index 2f7fb6181e..9aed2a8372 100644 --- a/engine/crates/layerfs-nfs/tests/export.rs +++ b/engine/crates/layerfs-nfs/tests/export.rs @@ -615,6 +615,53 @@ fn a_listing_spends_one_owner_visit_and_reads_its_window_in_batches() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_lookup_never_answers_a_stale_directory_observation() { + let base = temp("lookup-companion-directory"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let first = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut client = Client::connect(first.local_addr(), UID, GID); + let root = client.mnt("/"); + let made = client.mkdir(&root, b"watched", 0o755).unwrap(); + client.touch(&made.handle, b"file", 0o644).unwrap(); + let companion = client.touch(&made.handle, b"._file", 0o644).unwrap(); + let before = client.getattr(&made.handle).unwrap(); + assert_eq!(before.nlink, 2, "an empty directory"); + + // Another writer adds a child directory; this export observes nothing. + let second = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut other = Client::connect(second.local_addr(), UID, GID); + let other_root = other.mnt("/"); + let (target, _) = other.lookup(&other_root, b"watched").unwrap(); + other.mkdir(&target, b"child", 0o755).unwrap(); + + // The export answers a companion alone: no job read the directory, so the + // reply carries no directory attributes rather than the last observation. + let (status, found, directory) = client.lookup_with_directory(&made.handle, b"._file"); + assert_eq!(status, 0); + assert_eq!(found.map(|(handle, _)| handle), Some(companion.handle)); + assert_eq!(directory, None, "never the last observation"); + + // A failed LOOKUP read the directory's row: the export keeps those facts, + // so a companion change's `wcc_data` answers them, not the older ones. + let (status, _, directory) = client.lookup_with_directory(&made.handle, b"absent"); + assert_eq!(status, NOENT); + let fresh = directory.expect("the failed LOOKUP's directory row"); + assert_eq!(fresh.nlink, 3, "the directory gained a child directory"); + let removed = client.remove(&made.handle, b"._file").unwrap(); + assert_eq!(removed.after, Some(fresh), "the facts the failed LOOKUP read"); + + drop(client); + drop(other); + let released = first.stop(); + second.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn a_failed_lookup_answers_fresh_directory_facts_never_a_stale_observation() { let base = temp("lookup-directory"); From fb28450f5bf3c1977a174531d99e5d8473a7e662 Mon Sep 17 00:00:00 2001 From: YifanXu1999 Date: Tue, 17 Nov 2026 12:03:20 +0800 Subject: [PATCH 48/53] refactor(nfs): split apple_double.rs under the 999-line ceiling (#722 review) #722 left engine/crates/layerfs-nfs/src/apple_double.rs at 1,272 physical lines, and tools/check_product_boundary.py failed on it. This is relocation only, with no behaviour change: - `impl Companions` (names, inodes, slots, resident budget, eviction order) moves to `apple_double/index.rs`; - `Kernel::orphans` and `Kernel::reclaim_orphans` move to `apple_double/reclaim.rs`; - moved methods become `pub(super)`, and each file imports what it uses. The moved lines are otherwise byte-identical (checked by comparing the sorted non-import lines before and after). apple_double.rs is now 809 lines, index.rs 345, reclaim.rs 141. The boundary check passes (1,417 files). Docs: nfs.md's AppleDouble section lists the two new files. Tests: none changed. Production LOC: 171,498 -> 171,516 (delta +18; relocation: the new files' own imports) core 39,795 -> 39,795 (0) engine 76,921 -> 76,939 (+18) layerfs-nfs +18 control 48,436 -> 48,436 (0) api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent 9db8f4d35c and the staged tree Co-Authored-By: Claude Opus 5.5 --- docs/architecture/engine/kernel-routes/nfs.md | 2 +- engine/crates/layerfs-nfs/src/apple_double.rs | 473 +----------------- .../layerfs-nfs/src/apple_double/index.rs | 345 +++++++++++++ .../layerfs-nfs/src/apple_double/reclaim.rs | 141 ++++++ 4 files changed, 492 insertions(+), 469 deletions(-) create mode 100644 engine/crates/layerfs-nfs/src/apple_double/index.rs create mode 100644 engine/crates/layerfs-nfs/src/apple_double/reclaim.rs diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 83db39b278..df3d2689fc 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -176,7 +176,7 @@ drawn once per export; it makes guessing costly and does not authenticate. | The refresh never writes into the Workspace and never reverts a mode the install changed | [`refresh.rs`](../../../../engine/crates/layerfs-nfs/src/refresh.rs) | | `LAYERFS_NFS_REFRESH=0` leaves the client to `actimeo` and close-to-open | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -## AppleDouble files (`apple_double.rs`, `apple_double/edit.rs`, `apple_double_codec.rs`, `apple_double_spill.rs`) +## AppleDouble files (`apple_double.rs`, `apple_double/edit.rs`, `apple_double/index.rs`, `apple_double/reclaim.rs`, `apple_double_codec.rs`, `apple_double_spill.rs`) On NFSv3 the macOS client keeps extended attributes and resource forks in `._` files (at least one byte after `._`). With `refuse_apple_double`, a diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 90583be802..274d1a7e16 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -55,17 +55,14 @@ //! live companions still remain does `CREATE` answer `NFS3ERR_NOSPC`. use crate::{ apple_double_codec::Image, - apple_double_spill::{now, spill_path, touch, unlink_paths, Edit}, + apple_double_spill::{now, unlink_paths, Edit}, attributes::Status, change::{How, Sattr, Tickets, Wcc}, kernel::Kernel, trace::{self, Route as Trace}, }; -use layerfs_content::{ - filesystem::{attributes::PortableMetadata, PathName}, - object::inode_leaf::InodeKind, -}; -use layerfs_workspace::{KernelReadOperation, ViewStat}; +use layerfs_content::filesystem::attributes::PortableMetadata; +use layerfs_workspace::ViewStat; use std::{ collections::{BTreeSet, HashMap, HashSet}, fs, @@ -75,6 +72,8 @@ use std::{ }; mod edit; +mod index; +mod reclaim; /// The first serial of the export's own companions, far above any serial the /// engine allocates. @@ -241,335 +240,6 @@ impl Default for Companions { } } } -impl Companions { - fn tick(&mut self) -> u64 { - self.tick += 1; - self.tick - } - /// Marks `serial` as used now, which is the order eviction follows. Only a - /// companion holding memory is in the order: a spilled body has nothing to - /// give back. - fn use_serial(&mut self, serial: u64) { - let tick = self.tick(); - self.set_used(serial, tick); - } - /// Moves `serial`'s index entry to `used`. - fn set_used(&mut self, serial: u64, used: u64) { - let Some(file) = self.files.get_mut(&serial) else { - return; - }; - let old = std::mem::replace(&mut file.used, used); - self.by_use.remove(&(old, serial)); - if file.resident_cost() > 0 { - self.by_use.insert((used, serial)); - } - } - fn stat(serial: u64, file: &Companion) -> ViewStat { - ViewStat { - serial, - kind: InodeKind::RegularFile, - metadata: file.metadata, - namespace_refs: 1, - logical_len: file.len as u64, - subdirs: 0, - } - } - /// Adds `file` to the index, the slot and byte counts and the eviction - /// order. - fn attach(&mut self, serial: u64, file: Companion) { - if file.slotted() { - self.slots.insert(serial); - } - if file.resident_cost() > 0 { - self.by_use.insert((file.used, serial)); - } - self.resident_bytes += file.resident_cost(); - self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); - self.files.insert(serial, file); - } - /// Takes `serial` out of the index and the counts; its name keys stay for - /// the caller to unindex. - fn detach(&mut self, serial: u64) -> Option { - let file = self.files.remove(&serial)?; - self.slots.remove(&serial); - self.by_use.remove(&(file.used, serial)); - self.resident_bytes -= file.resident_cost(); - self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); - Some(file) - } - /// Makes every name of `file` and its main inode find `serial`. - fn index(&mut self, serial: u64, file: &Companion) { - self.names.insert(file.named.clone(), serial); - for named in &file.also { - self.names.insert(named.clone(), serial); - } - if let Some(inode) = file.inode { - self.inodes.insert(inode, serial); - } - } - /// Drops every name of `file` and its inode key that still find `serial`. - fn unindex(&mut self, serial: u64, file: &Companion) { - for named in std::iter::once(&file.named).chain(&file.also) { - if self.names.get(named) == Some(&serial) { - self.names.remove(named); - } - } - if let Some(inode) = file.inode { - if self.inodes.get(&inode) == Some(&serial) { - self.inodes.remove(&inode); - } - } - } - /// Whether `serial` holds a name other than `named`. - fn holds_another(&self, serial: u64, named: &Named) -> bool { - self.files.get(&serial).is_some_and(|file| { - (file.named != *named && self.names.get(&file.named) == Some(&serial)) - || file.also.iter().any(|also| also != named) - }) - } - /// Drops `named`, one of `serial`'s names, and answers whether it held it. - /// A companion left with no name is still reached through its main inode, - /// so it keeps its record; another held name becomes the one its record - /// names, so a later `index` puts back only names it still holds. - fn drop_name(&mut self, serial: u64, named: &Named) -> bool { - let Some(file) = self.files.get_mut(&serial) else { - return false; - }; - let primary = file.named == *named; - if !primary && !file.also.iter().any(|also| also == named) { - return false; - } - if self.names.get(named) == Some(&serial) { - self.names.remove(named); - } - if primary { - if let Some(next) = file.also.pop() { - file.named = next; - } - } else { - file.also.retain(|also| also != named); - } - true - } - /// The companion `named` reaches when its main file is `main`: the one - /// held under that name, unless it belongs to another inode than `main`, - /// else the one its main inode already has. - fn resolve(&self, named: &Named, main: Option) -> Option { - self.resolve_route(named, main).0 - } - /// [`Self::resolve`], and which part of the index answered, for the trace. - fn resolve_route(&self, named: &Named, main: Option) -> (Option, Trace) { - if let Some(&serial) = self.names.get(named) { - let inode = self.files.get(&serial).and_then(|file| file.inode); - if inode.is_none() || main.is_none() || inode == main { - return (Some(serial), Trace::Name); - } - } - match main.and_then(|main| self.inodes.get(&main).copied()) { - Some(serial) => (Some(serial), Trace::Inode), - None => (None, Trace::None), - } - } - /// Replaces `serial`'s body by the decoded form of `bytes`, the caller's - /// edited body of `len` bytes, while the resident budget takes it and the - /// export knows the companion's main inode. The decoded form is counted as - /// its attributes rather than its image, so a body that decodes usually - /// needs much less room than its bytes, and the caller is told the room it - /// would need instead of spilling a body that fits after one eviction. - fn keep_decoded(&mut self, serial: u64, bytes: &[u8], len: usize) -> Decoded { - // 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 Some(file) = self.files.get(&serial) else { - return Decoded::Unchanged; - }; - let (inode, before) = (file.inode, file.resident_cost()); - if inode.is_none() { - return Decoded::Unchanged; - } - let Some(image) = Image::compact(bytes) else { - return Decoded::Unchanged; - }; - if image.cost() > DECODED_ENTRY_BYTES { - return Decoded::Unchanged; - } - let cost = image.cost(); - let tick = self.tick(); - let Some(mut file) = self.detach(serial) else { - return Decoded::Unchanged; - }; - if self.resident_bytes + cost > self.resident_budget { - self.attach(serial, file); - // The body decodes, so the room to ask for is what the decoded - // form adds to the count, not the length of the bytes edited. - return Decoded::Room(cost.saturating_sub(before)); - } - file.len = len; - file.body = Body::Decoded(image); - file.whole = true; - file.used = tick; - touch(&mut file.metadata); - self.attach(serial, file); - Decoded::Kept - } - /// 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 [`DECODED_ENTRY_BYTES`] takes it. A - /// companion whose main file the export does not know is never a whole - /// image: it keeps the client's bytes as written and a slot of the index - /// bound, so that bound and orphan reclamation still reach it. `file` must - /// be detached from the index. - fn classify(&self, file: &mut Companion) { - if file.inode.is_none() { - // Only a decoded body has to become bytes again; a body on disk - // keeps its file and takes a slot. - if let Body::Decoded(image) = &file.body { - file.body = Body::Resident(image.encode()); - } - file.whole = false; - return; - } - // A body on disk cannot be decoded here (that reads its file under - // this lock): it keeps the class the write that spilled it left it. - file.whole = match &file.body { - Body::Decoded(_) => true, - Body::Spilled => file.whole, - Body::Resident(_) => false, - }; - let Body::Resident(bytes) = &file.body else { - return; - }; - let Some(image) = Image::compact(bytes) else { - return; - }; - file.whole = true; - if image.cost() <= DECODED_ENTRY_BYTES { - file.body = Body::Decoded(image); - } - } - fn take_serial(&mut self, serial: u64) -> Option { - self.reserved.remove(&serial); - let file = self.detach(serial)?; - self.unindex(serial, &file); - match file.body { - Body::Resident(_) | Body::Decoded(_) => None, - Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), - } - } - /// Where a body a spill wrote out replaces its companion: the companion's - /// own file, or `None` when another call changed the body since the - /// snapshot (`used` is the tick read then, and only a body still in memory - /// can be replaced). The caller renames its file to that path itself, - /// outside this lock, and then commits the body with - /// [`Self::commit_spilled`]. - fn spill_target(&self, serial: u64, used: Option) -> Result, Status> { - let file = self.files.get(&serial).ok_or(Status::Stale)?; - if let Some(used) = used { - if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { - return Ok(None); - } - } - let dir = self.spill_dir.as_ref().ok_or(Status::NoSpc)?; - Ok(Some(spill_path(dir, serial))) - } - /// Commits the body whose bytes now sit at the companion's spill file: it - /// holds them on disk from now on, `len` bytes of them, which were the - /// whole body the file was written from. `false` when the companion is gone - /// or already holds a file, and the file just renamed into place is the - /// caller's to drop. - /// - /// The caller holds the companion's edit gate and no other call writes this - /// companion's file, so a body that changed between the snapshot and here - /// cannot be the body this file was written from. - fn commit_spilled(&mut self, serial: u64, len: usize) -> bool { - let Some(mut file) = self.detach(serial) else { - return false; - }; - if matches!(file.body, Body::Spilled) { - self.attach(serial, file); - return false; - } - file.body = Body::Spilled; - // A body written out whole is still a whole image; a shorter file - // than the companion had described is not. - file.whole &= len <= file.len; - file.len = file.len.max(len); - self.attach(serial, file); - true - } - /// The least recently used companion holding memory, a body kept as - /// written or a decoded one: the budget counts both, so both are evicted. - /// The companions the caller will not take are passed over, one step into - /// the eviction order rather than a walk of every companion. - fn oldest_resident(&self, skip: &BTreeSet) -> Option { - self.by_use - .iter() - .find(|(_, serial)| !skip.contains(serial)) - .map(|(_, serial)| *serial) - } - /// Whether the index takes a companion that takes a slot of the bound: the - /// one place the bound is decided. A companion already holding a slot - /// keeps it, and a body that takes no slot is always admitted. - fn admits(&self, serial: Option, slotted: bool) -> bool { - !slotted - || serial.is_some_and(|serial| { - self.slots.contains(&serial) || self.reserved.contains(&serial) - }) - || self.slots.len() + self.reserved.len() < self.held_limit - } - /// Decides whether `serial` may take a slot of the bound and holds it when - /// it may, in one step under this lock: a call that needs I/O before its - /// commit keeps the slot for the commit, so two calls cannot both be told - /// the bound has room for one. [`Slot::Held`] means it already has one - /// (or a reservation) and nothing was taken. - fn reserve(&mut self, serial: u64) -> Slot { - if self.slots.contains(&serial) || self.reserved.contains(&serial) { - return Slot::Held; - } - if self.slots.len() + self.reserved.len() >= self.held_limit { - return Slot::Full; - } - self.reserved.insert(serial); - Slot::Taken - } - /// Gives back a slot reserved for a commit that did not land. - fn unreserve(&mut self, serial: u64) { - self.reserved.remove(&serial); - } - /// The companions no name of the export reaches: neither the name it - /// records nor another name of its inode finds it. Such a companion holds - /// its body with no way for a client to ask for it, which is one of the two - /// shapes a lost attribute takes (the other is no companion at all). A - /// companion reached only through its main inode - one whose `._` name the - /// client removed, or whose main file went under that name - is reachable, - /// which is why a name key kept for an inode's companion is not a leak. - /// Counted with the other holdings, by who reports them: the release line - /// says which shape a loss had, and a status read says so while serving. - fn unreachable(&self) -> usize { - self.files - .iter() - .filter(|(serial, file)| { - self.names.get(&file.named) != Some(serial) - && !file - .also - .iter() - .any(|also| self.names.get(also) == Some(serial)) - && file - .inode - .is_none_or(|inode| self.inodes.get(&inode) != Some(serial)) - }) - .count() - } - fn holding(&self) -> Holding { - Holding { - held: self.files.len(), - slotted: self.slots.len(), - resident_bytes: self.resident_bytes, - decoded: self.decoded, - unreachable: self.unreachable(), - } - } -} /// How a CREATE that found the companion already held is traced: an UNCHECKED /// create with an explicit size truncates the body every name of the inode /// shares, and a GUARDED or EXCLUSIVE one is answered `NFS3ERR_EXIST`. @@ -629,139 +299,6 @@ impl Kernel { let main = name.strip_prefix(b"._").filter(|main| !main.is_empty())?; self.table().by_name.get(&(parent, main.to_vec())).copied() } - /// The companion slots no name reaches any more: one whose main inode - /// holds no name in the kernel table, and one whose main file the export - /// never observed and whose name its name index does not hold. Taken under - /// the kernel table lock and, inside it, the companion lock, so nothing - /// here copies the namespace; the caller drops them by serial under the - /// companion lock again. - fn orphans(&self) -> Vec { - let table = self.table(); - let companions = self.companions(); - companions - .slots - .iter() - .filter_map(|serial| { - let file = companions.files.get(serial)?; - if let Some(inode) = file.inode { - let live = - table.names.contains_key(&inode) || table.aliases.contains_key(&inode); - return (!live).then_some(Orphan { - serial: *serial, - inode: Some(inode), - main: None, - }); - } - // A name the index does hold reaches the companion; one it - // does not hold only makes it a candidate, since that index is - // lossy. Any of the names it holds reaches it, so one whose - // main file the export knows keeps it, and the first name whose - // main it does not know is the one the lookup asks about. - let mut candidate = None; - for named in std::iter::once(&file.named).chain(&file.also) { - let Some(main) = named.1.strip_prefix(b"._") else { - continue; - }; - let main = (named.0, main.to_vec()); - if table.by_name.contains_key(&main) { - return None; - } - candidate.get_or_insert(main); - } - candidate.map(|main| Orphan { - serial: *serial, - inode: None, - main: Some(main), - }) - }) - .collect() - } - /// Drops the companion slots no name reaches any more and answers how many - /// it dropped. Takes the kernel table lock and, inside it, the companion - /// lock; the files it retires are unlinked afterwards, outside both. Never - /// call it under the companion lock. - /// - /// A companion whose main inode the export does not know is not dropped on - /// the name index's word: that index is lossy (its own bound, a name the - /// export never looked up, a rename on the client side), so each one costs - /// one read-only lookup of its main file in the engine, run outside both - /// locks. A main file that is there binds the companion back to its inode, - /// which keeps its attributes; only a lookup that answers "no such file", - /// or whose parent directory the engine no longer has (so the file cannot - /// be there either), makes it an orphan, and one that cannot answer leaves - /// it as it is. - /// - /// A lookup that finds the main file took one engine reference on it, and - /// the export keeps exactly one per serial: the visit is the entry's, so it - /// is registered as `Kernel::lookup` registers one (`entry_taken` remembers - /// the name and forgets a second reference). Without that the name reaches - /// the companion nowhere, and the next reclamation would read the bound one - /// as an inode holding no name and drop it. - fn reclaim_orphans(&self) -> usize { - let (bound, dead) = self.orphans().into_iter().fold( - (Vec::new(), Vec::new()), - |(mut bound, mut dead), orphan| { - let Some((parent, main)) = orphan.main else { - dead.push((orphan.serial, orphan.inode)); - return (bound, dead); - }; - // A name the engine cannot even take, or a lookup it cannot - // answer, leaves the companion as it is. - if let Ok(name) = PathName::from_bytes(&main) { - let lookup = KernelReadOperation::Lookup { parent, name }; - match self.observe(parent, None, lookup).map_err(|r| r.status) { - Ok(answer) => { - self.entry_taken(&answer.stat, parent, &main); - bound.push((orphan.serial, answer.stat.serial)); - } - // A parent directory the engine no longer has cannot - // hold the main file: the companion is an orphan as - // much as one whose file answers "no such file". - // A parent directory the engine no longer has cannot - // hold the main file: the companion is an orphan as - // much as one whose file answers "no such file". - Err(Status::NoEnt | Status::Stale | Status::NotDir) => { - dead.push((orphan.serial, orphan.inode)) - } - Err(_) => {} - } - } - (bound, dead) - }, - ); - let (reclaimed, spilled) = { - let mut companions = self.companions(); - let mut spilled = Vec::new(); - let mut reclaimed = 0; - for (serial, main) in bound { - let Some(mut file) = companions.detach(serial) else { - continue; - }; - if file.inode.is_some() || !file.slotted() { - companions.attach(serial, file); - continue; - } - // Bound back to the inode the engine found: it keeps the slot it - // took, and from here it follows that inode's names. - file.inode = Some(main); - companions.index(serial, &file); - companions.attach(serial, file); - } - for (serial, inode) in dead { - let still_orphan = companions - .files - .get(&serial) - .is_some_and(|file| file.inode == inode && file.slotted()); - if still_orphan { - reclaimed += 1; - spilled.extend(companions.take_serial(serial)); - } - } - (reclaimed, spilled) - }; - unlink_paths(spilled); - reclaimed - } /// GETATTR of a companion serial. pub(crate) fn companion_stat(&self, serial: u64) -> Result { let mut companions = self.companions(); diff --git a/engine/crates/layerfs-nfs/src/apple_double/index.rs b/engine/crates/layerfs-nfs/src/apple_double/index.rs new file mode 100644 index 0000000000..2e6b718d84 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double/index.rs @@ -0,0 +1,345 @@ +//! The companion index of one export: its names, main inodes, slots of the +//! index bound, resident budget and eviction order. +use super::{ + spill_applies, Body, Companion, Companions, Decoded, Holding, Named, Slot, + DECODED_ENTRY_BYTES, +}; +use crate::{ + apple_double_codec::Image, + apple_double_spill::{spill_path, touch}, + attributes::Status, + trace::Route as Trace, +}; +use layerfs_content::object::inode_leaf::InodeKind; +use layerfs_workspace::ViewStat; +use std::{collections::BTreeSet, path::PathBuf}; + +impl Companions { + pub(super) fn tick(&mut self) -> u64 { + self.tick += 1; + self.tick + } + /// Marks `serial` as used now, which is the order eviction follows. Only a + /// companion holding memory is in the order: a spilled body has nothing to + /// give back. + pub(super) fn use_serial(&mut self, serial: u64) { + let tick = self.tick(); + self.set_used(serial, tick); + } + /// Moves `serial`'s index entry to `used`. + pub(super) fn set_used(&mut self, serial: u64, used: u64) { + let Some(file) = self.files.get_mut(&serial) else { + return; + }; + let old = std::mem::replace(&mut file.used, used); + self.by_use.remove(&(old, serial)); + if file.resident_cost() > 0 { + self.by_use.insert((used, serial)); + } + } + pub(super) fn stat(serial: u64, file: &Companion) -> ViewStat { + ViewStat { + serial, + kind: InodeKind::RegularFile, + metadata: file.metadata, + namespace_refs: 1, + logical_len: file.len as u64, + subdirs: 0, + } + } + /// Adds `file` to the index, the slot and byte counts and the eviction + /// order. + pub(super) fn attach(&mut self, serial: u64, file: Companion) { + if file.slotted() { + self.slots.insert(serial); + } + if file.resident_cost() > 0 { + self.by_use.insert((file.used, serial)); + } + self.resident_bytes += file.resident_cost(); + self.decoded += usize::from(matches!(file.body, Body::Decoded(_))); + self.files.insert(serial, file); + } + /// Takes `serial` out of the index and the counts; its name keys stay for + /// the caller to unindex. + pub(super) fn detach(&mut self, serial: u64) -> Option { + let file = self.files.remove(&serial)?; + self.slots.remove(&serial); + self.by_use.remove(&(file.used, serial)); + self.resident_bytes -= file.resident_cost(); + self.decoded -= usize::from(matches!(file.body, Body::Decoded(_))); + Some(file) + } + /// Makes every name of `file` and its main inode find `serial`. + pub(super) fn index(&mut self, serial: u64, file: &Companion) { + self.names.insert(file.named.clone(), serial); + for named in &file.also { + self.names.insert(named.clone(), serial); + } + if let Some(inode) = file.inode { + self.inodes.insert(inode, serial); + } + } + /// Drops every name of `file` and its inode key that still find `serial`. + pub(super) fn unindex(&mut self, serial: u64, file: &Companion) { + for named in std::iter::once(&file.named).chain(&file.also) { + if self.names.get(named) == Some(&serial) { + self.names.remove(named); + } + } + if let Some(inode) = file.inode { + if self.inodes.get(&inode) == Some(&serial) { + self.inodes.remove(&inode); + } + } + } + /// Whether `serial` holds a name other than `named`. + pub(super) fn holds_another(&self, serial: u64, named: &Named) -> bool { + self.files.get(&serial).is_some_and(|file| { + (file.named != *named && self.names.get(&file.named) == Some(&serial)) + || file.also.iter().any(|also| also != named) + }) + } + /// Drops `named`, one of `serial`'s names, and answers whether it held it. + /// A companion left with no name is still reached through its main inode, + /// so it keeps its record; another held name becomes the one its record + /// names, so a later `index` puts back only names it still holds. + pub(super) fn drop_name(&mut self, serial: u64, named: &Named) -> bool { + let Some(file) = self.files.get_mut(&serial) else { + return false; + }; + let primary = file.named == *named; + if !primary && !file.also.iter().any(|also| also == named) { + return false; + } + if self.names.get(named) == Some(&serial) { + self.names.remove(named); + } + if primary { + if let Some(next) = file.also.pop() { + file.named = next; + } + } else { + file.also.retain(|also| also != named); + } + true + } + /// The companion `named` reaches when its main file is `main`: the one + /// held under that name, unless it belongs to another inode than `main`, + /// else the one its main inode already has. + pub(super) fn resolve(&self, named: &Named, main: Option) -> Option { + self.resolve_route(named, main).0 + } + /// [`Self::resolve`], and which part of the index answered, for the trace. + pub(super) fn resolve_route(&self, named: &Named, main: Option) -> (Option, Trace) { + if let Some(&serial) = self.names.get(named) { + let inode = self.files.get(&serial).and_then(|file| file.inode); + if inode.is_none() || main.is_none() || inode == main { + return (Some(serial), Trace::Name); + } + } + match main.and_then(|main| self.inodes.get(&main).copied()) { + Some(serial) => (Some(serial), Trace::Inode), + None => (None, Trace::None), + } + } + /// Replaces `serial`'s body by the decoded form of `bytes`, the caller's + /// edited body of `len` bytes, while the resident budget takes it and the + /// export knows the companion's main inode. The decoded form is counted as + /// its attributes rather than its image, so a body that decodes usually + /// needs much less room than its bytes, and the caller is told the room it + /// would need instead of spilling a body that fits after one eviction. + pub(super) fn keep_decoded(&mut self, serial: u64, bytes: &[u8], len: usize) -> Decoded { + // 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 Some(file) = self.files.get(&serial) else { + return Decoded::Unchanged; + }; + let (inode, before) = (file.inode, file.resident_cost()); + if inode.is_none() { + return Decoded::Unchanged; + } + let Some(image) = Image::compact(bytes) else { + return Decoded::Unchanged; + }; + if image.cost() > DECODED_ENTRY_BYTES { + return Decoded::Unchanged; + } + let cost = image.cost(); + let tick = self.tick(); + let Some(mut file) = self.detach(serial) else { + return Decoded::Unchanged; + }; + if self.resident_bytes + cost > self.resident_budget { + self.attach(serial, file); + // The body decodes, so the room to ask for is what the decoded + // form adds to the count, not the length of the bytes edited. + return Decoded::Room(cost.saturating_sub(before)); + } + file.len = len; + file.body = Body::Decoded(image); + file.whole = true; + file.used = tick; + touch(&mut file.metadata); + self.attach(serial, file); + Decoded::Kept + } + /// 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 [`DECODED_ENTRY_BYTES`] takes it. A + /// companion whose main file the export does not know is never a whole + /// image: it keeps the client's bytes as written and a slot of the index + /// bound, so that bound and orphan reclamation still reach it. `file` must + /// be detached from the index. + pub(super) fn classify(&self, file: &mut Companion) { + if file.inode.is_none() { + // Only a decoded body has to become bytes again; a body on disk + // keeps its file and takes a slot. + if let Body::Decoded(image) = &file.body { + file.body = Body::Resident(image.encode()); + } + file.whole = false; + return; + } + // A body on disk cannot be decoded here (that reads its file under + // this lock): it keeps the class the write that spilled it left it. + file.whole = match &file.body { + Body::Decoded(_) => true, + Body::Spilled => file.whole, + Body::Resident(_) => false, + }; + let Body::Resident(bytes) = &file.body else { + return; + }; + let Some(image) = Image::compact(bytes) else { + return; + }; + file.whole = true; + if image.cost() <= DECODED_ENTRY_BYTES { + file.body = Body::Decoded(image); + } + } + pub(super) fn take_serial(&mut self, serial: u64) -> Option { + self.reserved.remove(&serial); + let file = self.detach(serial)?; + self.unindex(serial, &file); + match file.body { + Body::Resident(_) | Body::Decoded(_) => None, + Body::Spilled => (self.spill_dir.as_ref()).map(|dir| spill_path(dir, serial)), + } + } + /// Where a body a spill wrote out replaces its companion: the companion's + /// own file, or `None` when another call changed the body since the + /// snapshot (`used` is the tick read then, and only a body still in memory + /// can be replaced). The caller renames its file to that path itself, + /// outside this lock, and then commits the body with + /// [`Self::commit_spilled`]. + pub(super) fn spill_target(&self, serial: u64, used: Option) -> Result, Status> { + let file = self.files.get(&serial).ok_or(Status::Stale)?; + if let Some(used) = used { + if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { + return Ok(None); + } + } + let dir = self.spill_dir.as_ref().ok_or(Status::NoSpc)?; + Ok(Some(spill_path(dir, serial))) + } + /// Commits the body whose bytes now sit at the companion's spill file: it + /// holds them on disk from now on, `len` bytes of them, which were the + /// whole body the file was written from. `false` when the companion is gone + /// or already holds a file, and the file just renamed into place is the + /// caller's to drop. + /// + /// The caller holds the companion's edit gate and no other call writes this + /// companion's file, so a body that changed between the snapshot and here + /// cannot be the body this file was written from. + pub(super) fn commit_spilled(&mut self, serial: u64, len: usize) -> bool { + let Some(mut file) = self.detach(serial) else { + return false; + }; + if matches!(file.body, Body::Spilled) { + self.attach(serial, file); + return false; + } + file.body = Body::Spilled; + // A body written out whole is still a whole image; a shorter file + // than the companion had described is not. + file.whole &= len <= file.len; + file.len = file.len.max(len); + self.attach(serial, file); + true + } + /// The least recently used companion holding memory, a body kept as + /// written or a decoded one: the budget counts both, so both are evicted. + /// The companions the caller will not take are passed over, one step into + /// the eviction order rather than a walk of every companion. + pub(super) fn oldest_resident(&self, skip: &BTreeSet) -> Option { + self.by_use + .iter() + .find(|(_, serial)| !skip.contains(serial)) + .map(|(_, serial)| *serial) + } + /// Whether the index takes a companion that takes a slot of the bound: the + /// one place the bound is decided. A companion already holding a slot + /// keeps it, and a body that takes no slot is always admitted. + pub(super) fn admits(&self, serial: Option, slotted: bool) -> bool { + !slotted + || serial.is_some_and(|serial| { + self.slots.contains(&serial) || self.reserved.contains(&serial) + }) + || self.slots.len() + self.reserved.len() < self.held_limit + } + /// Decides whether `serial` may take a slot of the bound and holds it when + /// it may, in one step under this lock: a call that needs I/O before its + /// commit keeps the slot for the commit, so two calls cannot both be told + /// the bound has room for one. [`Slot::Held`] means it already has one + /// (or a reservation) and nothing was taken. + pub(super) fn reserve(&mut self, serial: u64) -> Slot { + if self.slots.contains(&serial) || self.reserved.contains(&serial) { + return Slot::Held; + } + if self.slots.len() + self.reserved.len() >= self.held_limit { + return Slot::Full; + } + self.reserved.insert(serial); + Slot::Taken + } + /// Gives back a slot reserved for a commit that did not land. + pub(super) fn unreserve(&mut self, serial: u64) { + self.reserved.remove(&serial); + } + /// The companions no name of the export reaches: neither the name it + /// records nor another name of its inode finds it. Such a companion holds + /// its body with no way for a client to ask for it, which is one of the two + /// shapes a lost attribute takes (the other is no companion at all). A + /// companion reached only through its main inode - one whose `._` name the + /// client removed, or whose main file went under that name - is reachable, + /// which is why a name key kept for an inode's companion is not a leak. + /// Counted with the other holdings, by who reports them: the release line + /// says which shape a loss had, and a status read says so while serving. + pub(super) fn unreachable(&self) -> usize { + self.files + .iter() + .filter(|(serial, file)| { + self.names.get(&file.named) != Some(serial) + && !file + .also + .iter() + .any(|also| self.names.get(also) == Some(serial)) + && file + .inode + .is_none_or(|inode| self.inodes.get(&inode) != Some(serial)) + }) + .count() + } + pub(super) fn holding(&self) -> Holding { + Holding { + held: self.files.len(), + slotted: self.slots.len(), + resident_bytes: self.resident_bytes, + decoded: self.decoded, + unreachable: self.unreachable(), + } + } +} diff --git a/engine/crates/layerfs-nfs/src/apple_double/reclaim.rs b/engine/crates/layerfs-nfs/src/apple_double/reclaim.rs new file mode 100644 index 0000000000..8d4c69ba42 --- /dev/null +++ b/engine/crates/layerfs-nfs/src/apple_double/reclaim.rs @@ -0,0 +1,141 @@ +//! Reclamation of the companion slots no name reaches, at the index bound. +use super::Orphan; +use crate::{apple_double_spill::unlink_paths, attributes::Status, kernel::Kernel}; +use layerfs_content::filesystem::PathName; +use layerfs_workspace::KernelReadOperation; + +impl Kernel { + /// The companion slots no name reaches any more: one whose main inode + /// holds no name in the kernel table, and one whose main file the export + /// never observed and whose name its name index does not hold. Taken under + /// the kernel table lock and, inside it, the companion lock, so nothing + /// here copies the namespace; the caller drops them by serial under the + /// companion lock again. + pub(super) fn orphans(&self) -> Vec { + let table = self.table(); + let companions = self.companions(); + companions + .slots + .iter() + .filter_map(|serial| { + let file = companions.files.get(serial)?; + if let Some(inode) = file.inode { + let live = + table.names.contains_key(&inode) || table.aliases.contains_key(&inode); + return (!live).then_some(Orphan { + serial: *serial, + inode: Some(inode), + main: None, + }); + } + // A name the index does hold reaches the companion; one it + // does not hold only makes it a candidate, since that index is + // lossy. Any of the names it holds reaches it, so one whose + // main file the export knows keeps it, and the first name whose + // main it does not know is the one the lookup asks about. + let mut candidate = None; + for named in std::iter::once(&file.named).chain(&file.also) { + let Some(main) = named.1.strip_prefix(b"._") else { + continue; + }; + let main = (named.0, main.to_vec()); + if table.by_name.contains_key(&main) { + return None; + } + candidate.get_or_insert(main); + } + candidate.map(|main| Orphan { + serial: *serial, + inode: None, + main: Some(main), + }) + }) + .collect() + } + /// Drops the companion slots no name reaches any more and answers how many + /// it dropped. Takes the kernel table lock and, inside it, the companion + /// lock; the files it retires are unlinked afterwards, outside both. Never + /// call it under the companion lock. + /// + /// A companion whose main inode the export does not know is not dropped on + /// the name index's word: that index is lossy (its own bound, a name the + /// export never looked up, a rename on the client side), so each one costs + /// one read-only lookup of its main file in the engine, run outside both + /// locks. A main file that is there binds the companion back to its inode, + /// which keeps its attributes; only a lookup that answers "no such file", + /// or whose parent directory the engine no longer has (so the file cannot + /// be there either), makes it an orphan, and one that cannot answer leaves + /// it as it is. + /// + /// A lookup that finds the main file took one engine reference on it, and + /// the export keeps exactly one per serial: the visit is the entry's, so it + /// is registered as `Kernel::lookup` registers one (`entry_taken` remembers + /// the name and forgets a second reference). Without that the name reaches + /// the companion nowhere, and the next reclamation would read the bound one + /// as an inode holding no name and drop it. + pub(super) fn reclaim_orphans(&self) -> usize { + let (bound, dead) = self.orphans().into_iter().fold( + (Vec::new(), Vec::new()), + |(mut bound, mut dead), orphan| { + let Some((parent, main)) = orphan.main else { + dead.push((orphan.serial, orphan.inode)); + return (bound, dead); + }; + // A name the engine cannot even take, or a lookup it cannot + // answer, leaves the companion as it is. + if let Ok(name) = PathName::from_bytes(&main) { + let lookup = KernelReadOperation::Lookup { parent, name }; + match self.observe(parent, None, lookup).map_err(|r| r.status) { + Ok(answer) => { + self.entry_taken(&answer.stat, parent, &main); + bound.push((orphan.serial, answer.stat.serial)); + } + // A parent directory the engine no longer has cannot + // hold the main file: the companion is an orphan as + // much as one whose file answers "no such file". + // A parent directory the engine no longer has cannot + // hold the main file: the companion is an orphan as + // much as one whose file answers "no such file". + Err(Status::NoEnt | Status::Stale | Status::NotDir) => { + dead.push((orphan.serial, orphan.inode)) + } + Err(_) => {} + } + } + (bound, dead) + }, + ); + let (reclaimed, spilled) = { + let mut companions = self.companions(); + let mut spilled = Vec::new(); + let mut reclaimed = 0; + for (serial, main) in bound { + let Some(mut file) = companions.detach(serial) else { + continue; + }; + if file.inode.is_some() || !file.slotted() { + companions.attach(serial, file); + continue; + } + // Bound back to the inode the engine found: it keeps the slot it + // took, and from here it follows that inode's names. + file.inode = Some(main); + companions.index(serial, &file); + companions.attach(serial, file); + } + for (serial, inode) in dead { + let still_orphan = companions + .files + .get(&serial) + .is_some_and(|file| file.inode == inode && file.slotted()); + if still_orphan { + reclaimed += 1; + spilled.extend(companions.take_serial(serial)); + } + } + (reclaimed, spilled) + }; + unlink_paths(spilled); + reclaimed + } +} From 77e7368e52863efdfee3dbace7f872907d6ecc4b Mon Sep 17 00:00:00 2001 From: YifanXu1999 Date: Tue, 17 Nov 2026 12:06:48 +0800 Subject: [PATCH 49/53] fix(nfs): reclaim a companion only if no call used it since the decision (#722 review) Kernel::reclaim_orphans decides outside both locks: each candidate whose main file is unknown costs one engine lookup, and the commit then took the lock again and re-checked only the companion's inode and slot. A call that made the companion live in that window (a RENAME of `._x` onto a name whose main file exists, a CREATE of the main file followed by a WRITE to `._x`, a READ) did not stop the drop. The binding half could also overwrite another companion's entry for the same main inode. `Orphan` now carries the companion's `used` tick from the decision, and `Companions::unchanged` requires it, the same inode and the slot still taken, both before dropping a companion and before binding one back. A main inode that already has its companion is not rebound; the candidate stays and is looked up again at the next reclaim. Every call that reaches a companion moves its tick. Review finding rejected after testing: the review said a lookup in a directory whose reference the export had collected would answer `Stale` and so drop a live companion. It does not: the engine answers the lookup in a collected directory. The new test collects the directory (a later GETATTR of it resolves it again) and passes both before and after this change, so it is coverage, not a regression test. Test: new `apple_double_decode.rs::a_companion_in_a_collected_directory_is_kept_while_its_main_file_is_there`. The race itself has no deterministic client-side reproduction (the window is between the out-of-lock engine lookup and the commit), so no test reproduces it. Production LOC: 171,516 -> 171,525 (delta +9) core 39,795 -> 39,795 (0) engine 76,939 -> 76,948 (+9) layerfs-nfs +9 control 48,436 -> 48,436 (0) api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent fb28450f5b and the staged tree Co-Authored-By: Claude Opus 5.5 --- engine/crates/layerfs-nfs/src/apple_double.rs | 3 + .../layerfs-nfs/src/apple_double/index.rs | 9 ++- .../layerfs-nfs/src/apple_double/reclaim.rs | 80 ++++++++++--------- .../layerfs-nfs/tests/apple_double_decode.rs | 50 ++++++++++++ 4 files changed, 102 insertions(+), 40 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 274d1a7e16..1aaf5dad95 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -145,6 +145,7 @@ impl Companion { /// A slot of the index the export's own name index cannot reach, and what the /// reclaim needs to decide about it. +#[derive(Clone)] struct Orphan { serial: u64, /// The main inode the export knows for it; an inode holding no name in the @@ -153,6 +154,8 @@ struct Orphan { /// Its main file's directory and name when it has no inode: the name index /// is lossy, so only the engine can say whether that file is there. main: Option, + /// Its last use when it was found: a companion used since keeps itself. + used: u64, } /// What [`Companions::reserve`] made of a call's claim on a slot of the index diff --git a/engine/crates/layerfs-nfs/src/apple_double/index.rs b/engine/crates/layerfs-nfs/src/apple_double/index.rs index 2e6b718d84..8a455c31a5 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/index.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/index.rs @@ -1,7 +1,7 @@ //! The companion index of one export: its names, main inodes, slots of the //! index bound, resident budget and eviction order. use super::{ - spill_applies, Body, Companion, Companions, Decoded, Holding, Named, Slot, + spill_applies, Body, Companion, Companions, Decoded, Holding, Named, Orphan, Slot, DECODED_ENTRY_BYTES, }; use crate::{ @@ -333,6 +333,13 @@ impl Companions { }) .count() } + /// Whether `orphan` is still the slot reclamation found: the same main + /// inode, still taking a slot, and not used by any call since. + pub(super) fn unchanged(&self, orphan: &Orphan) -> bool { + self.files.get(&orphan.serial).is_some_and(|file| { + file.inode == orphan.inode && file.slotted() && file.used == orphan.used + }) + } pub(super) fn holding(&self) -> Holding { Holding { held: self.files.len(), diff --git a/engine/crates/layerfs-nfs/src/apple_double/reclaim.rs b/engine/crates/layerfs-nfs/src/apple_double/reclaim.rs index 8d4c69ba42..bae04d79aa 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/reclaim.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/reclaim.rs @@ -26,6 +26,7 @@ impl Kernel { serial: *serial, inode: Some(inode), main: None, + used: file.used, }); } // A name the index does hold reaches the companion; one it @@ -48,6 +49,7 @@ impl Kernel { serial: *serial, inode: None, main: Some(main), + used: file.used, }) }) .collect() @@ -77,30 +79,33 @@ impl Kernel { let (bound, dead) = self.orphans().into_iter().fold( (Vec::new(), Vec::new()), |(mut bound, mut dead), orphan| { - let Some((parent, main)) = orphan.main else { - dead.push((orphan.serial, orphan.inode)); + let Some((parent, main)) = orphan.main.clone() else { + dead.push(orphan); return (bound, dead); }; - // A name the engine cannot even take, or a lookup it cannot - // answer, leaves the companion as it is. - if let Ok(name) = PathName::from_bytes(&main) { - let lookup = KernelReadOperation::Lookup { parent, name }; - match self.observe(parent, None, lookup).map_err(|r| r.status) { - Ok(answer) => { - self.entry_taken(&answer.stat, parent, &main); - bound.push((orphan.serial, answer.stat.serial)); - } - // A parent directory the engine no longer has cannot - // hold the main file: the companion is an orphan as - // much as one whose file answers "no such file". - // A parent directory the engine no longer has cannot - // hold the main file: the companion is an orphan as - // much as one whose file answers "no such file". - Err(Status::NoEnt | Status::Stale | Status::NotDir) => { - dead.push((orphan.serial, orphan.inode)) - } - Err(_) => {} + // A name the engine cannot take, or a lookup it cannot answer, + // leaves the companion as it is. The engine answers a lookup in + // a directory whose reference the export collected as well. + let Ok(name) = PathName::from_bytes(&main) else { + return (bound, dead); + }; + let lookup = KernelReadOperation::Lookup { parent, name }; + match self.observe(parent, None, lookup) { + Ok(answer) => { + self.entry_taken(&answer.stat, parent, &main); + bound.push((orphan, answer.stat.serial)); + } + // A directory that no longer holds the main file, or that + // is gone itself, makes the companion an orphan. + Err(refused) + if matches!( + refused.status, + Status::NoEnt | Status::Stale | Status::NotDir + ) => + { + dead.push(orphan) } + Err(_) => {} } (bound, dead) }, @@ -109,28 +114,25 @@ impl Kernel { let mut companions = self.companions(); let mut spilled = Vec::new(); let mut reclaimed = 0; - for (serial, main) in bound { - let Some(mut file) = companions.detach(serial) else { - continue; - }; - if file.inode.is_some() || !file.slotted() { - companions.attach(serial, file); + for (orphan, main) in bound { + // Bound back to the inode the engine found, unless a call used + // it meanwhile or that inode already has its companion: it + // keeps the slot it took and follows that inode's names. + if !companions.unchanged(&orphan) || companions.inodes.contains_key(&main) { continue; } - // Bound back to the inode the engine found: it keeps the slot it - // took, and from here it follows that inode's names. - file.inode = Some(main); - companions.index(serial, &file); - companions.attach(serial, file); + if let Some(mut file) = companions.detach(orphan.serial) { + file.inode = Some(main); + companions.index(orphan.serial, &file); + companions.attach(orphan.serial, file); + } } - for (serial, inode) in dead { - let still_orphan = companions - .files - .get(&serial) - .is_some_and(|file| file.inode == inode && file.slotted()); - if still_orphan { + // A call that used a companion after the decision (a READ, a + // WRITE, a LINK or RENAME of one of its names) keeps it. + for orphan in dead { + if companions.unchanged(&orphan) { reclaimed += 1; - spilled.extend(companions.take_serial(serial)); + spilled.extend(companions.take_serial(orphan.serial)); } } (reclaimed, spilled) diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 5d11c9b490..7557414dac 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1691,6 +1691,56 @@ fn a_companion_of_a_removed_directory_is_reclaimed() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn a_companion_in_a_collected_directory_is_kept_while_its_main_file_is_there() { + let base = temp("orphan-collected-dir"); + let tree = base.join("tree"); + source(&tree); + let mut rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + rig.companions_held = 1; + rig.lookups_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 root = c.mnt("/"); + let kept = c.mkdir(&root, b"kept", 0o755).unwrap().handle; + // Nothing names `x` yet, so the companion takes the one slot with no main + // inode. + let held = c.touch(&kept, b"._x", 0o644).unwrap(); + let body = pattern(83, 64); + c.write(&held.handle, 0, &body).unwrap(); + assert_eq!(server.held().companions_slotted, 1); + + // Enough other names that the export collects its reference to `kept`. + let names = layerfs_nfs::kernel::RECENT_KEPT as usize + 32; + for index in 0..names { + let name = format!("f{index}"); + c.touch(&root, name.as_bytes(), 0o644) + .unwrap_or_else(|status| panic!("{name}: {status}")); + } + assert!(server.held().collected > 0, "{:?}", server.held()); + + // Another writer makes the main file; this export never looks it up. + let second = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut other = Client::connect(second.local_addr(), UID, GID); + let other_root = other.mnt("/"); + let (other_kept, _) = other.lookup(&other_root, b"kept").unwrap(); + other.touch(&other_kept, b"x", 0o644).unwrap(); + + // The CREATE at the bound asks the engine about `kept/x` through the + // directory resolved again, finds it and keeps the companion: the bound + // stays full and the companion keeps its bytes. + assert_eq!(c.touch(&root, b"._y", 0o644).map(|_| ()), Err(NOSPC)); + assert_eq!(c.read_all(&held.handle, 4096), body); + + drop(c); + drop(other); + 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_reached_by_one_of_its_names_is_not_an_orphan() { let base = temp("orphan-alias"); From 519f8db4757ccb30c38f23095c5c87530a9bb8ce Mon Sep 17 00:00:00 2001 From: YifanXu1999 Date: Tue, 17 Nov 2026 12:09:25 +0800 Subject: [PATCH 50/53] fix(nfs): AppleDouble codec review fixes (#713 review) - SETATTR of a companion runs as one edit. It checked its guard under one lock, resized under a second and set mode/mtime under a third, so a guarded SETATTR could pass its ctime check and resize a body a WRITE had changed in between. It now holds the companion's edit gate from the guard to the mode and time, and a WRITE reads its pre-op attributes under the gate (`edit_gate` + `edit_gated` replace `edit_companion`). A REMOVE takes no gate, so a SETATTR racing one can still answer `Stale` after resizing a body that is gone with its companion; nothing is left behind. - A whole image is decoded only when its decoded form costs less than its bytes (`worth_decoding`). Each attribute is charged its name, value and 56 bytes, so an image of many small attributes cost several times its length decoded, could be refused room its bytes had, and was charged more than it held. - An edit of a decoded body asks for the room its bytes add beyond the decoded charge it gives back, not for its whole length, so overwriting or shrinking one no longer spills more than it needs. - `Image::parse` bounds its first allocation by what the image can hold rather than by the client's entry count (up to 65,535 entries). The resident budget stays at 32 MiB (owner decision 2026-11-17); #713's description called it upstream's, but the base branch had 64 MiB. The architecture page already says 32 MiB. Not changed: every WRITE to a decoded body still re-encodes and re-parses the whole body under the companion lock; that needs an in-place decoded edit. Docs: nfs.md (the DECODED_ENTRY_BYTES row, and the SETATTR and WRITE gate) and the module docs of apple_double.rs. Test: new `apple_double_decode.rs::an_image_whose_attributes_cost_more_than_its_bytes_is_kept_as_written` (600 two-byte names). It fails on the parent (77e7368e52), where the image is decoded (decoded count 1), and passes here. The SETATTR race has no deterministic client-side reproduction, so it has no test. Production LOC: 171,525 -> 171,523 (delta -2) core 39,795 -> 39,795 (0) engine 76,948 -> 76,946 (-2) layerfs-nfs -2 control 48,436 -> 48,436 (0) api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent 77e7368e52 and the staged tree Co-Authored-By: Claude Opus 5.5 --- docs/architecture/engine/kernel-routes/nfs.md | 6 ++- engine/crates/layerfs-nfs/src/apple_double.rs | 7 +-- .../layerfs-nfs/src/apple_double/edit.rs | 45 +++++++++---------- .../layerfs-nfs/src/apple_double/index.rs | 11 ++++- .../layerfs-nfs/src/apple_double_codec.rs | 5 ++- .../layerfs-nfs/tests/apple_double_decode.rs | 32 +++++++++++++ 6 files changed, 75 insertions(+), 31 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index df3d2689fc..157b251112 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -193,7 +193,7 @@ the export. | `HELD` | 65,536 slotted companion entries | `Companions::admits` decides the bound in one place, before anything is committed: CREATE, and a WRITE, SETATTR or RENAME that needs a new slot, first reclaim the orphan slotted companions outside the companion lock, once, and then answer the whole operation `NFS3ERR_NOSPC` with the body, its length and its name as they were (CREATE also increments `names_refused` and logs at most once per 60 s per export). A call whose commit needs I/O in between (`Companions::reserve`) holds the slot from the decision, so the bound holds when calls race for the last one | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | | `RESIDENT_BYTES` | 32 MiB of companion bodies in all: a body kept as written at its length, a decoded one as `Image::cost`; an edit that leaves a body whole decodes it as it records it, so the count may stand one decoded body over until the next edit needs room | Spill the least recently touched bodies, decoded ones included, to `companion_spill_dir` (`/.appledouble//`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) | -| `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion: a cap on what one decoded body is charged, not on what a companion may store | A whole image costing more keeps its bytes as written, is charged at their length and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | +| `DECODED_ENTRY_BYTES` | 128 KiB counted for one decoded companion: a cap on what one decoded body is charged, not on what a companion may store | A whole image costing more, or costing at least its own length (many small attributes), keeps its bytes as written, is charged at their length and still takes no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) | A companion whose main inode the export knows belongs to that inode rather than to one name: hard links share it, main-file RENAME keeps it under the new name @@ -274,7 +274,9 @@ than the length the lock saw is a short read, not `NFS3ERR_IO`. One edit per companion runs under that gate ([`edit.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double/edit.rs)), recording length and bytes together and spilling its own body rather than -failing with `NFS3ERR_IO`. A file operation that fails after the spill put the +failing with `NFS3ERR_IO`. A SETATTR is one such edit from its guard to its +mode and time, and a WRITE reads its pre-op attributes under the gate, so a +guarded SETATTR checks the very body its size change applies to. A file operation that fails after the spill put the length the companion had back, so a refused write reports neither bytes nor the longer file the spill made for it. Eviction follows `Companions::by_use`, the `(used tick, serial)` order kept on attach, detach and every use: the victim is diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index 1aaf5dad95..b455797c4e 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -28,9 +28,10 @@ //! companion to the inode's other names: only its last name, on an inode with //! no other name the export knows, is the client clearing the attributes. Whenever a write leaves such a companion holding a whole //! AppleDouble image the client laid out itself (see -//! [`crate::apple_double_codec`]), it is decoded: a small one keeps only its -//! FinderInfo and attributes in memory (each at most [`DECODED_ENTRY_BYTES`] -//! counted), and every read synthesizes the same bytes again. Such a whole +//! [`crate::apple_double_codec`]), it is decoded: one whose attributes cost +//! less than its bytes keeps only its FinderInfo and attributes in memory +//! (each at most [`DECODED_ENTRY_BYTES`] counted), 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 diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index dc49f336a5..c4a62cb626 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -105,14 +105,12 @@ impl Kernel { if end > FILE_BYTES { return Err(Status::FBig); } + let gate = self.edit_gate(serial)?; + // Held to the end: the reply's before is the body this edit changes. + let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); let before = self.companion_stat(serial)?; - let after = self.edit_companion( - serial, - Edit::Write { - offset: offset as usize, - data, - }, - )?; + let offset = offset as usize; + let after = self.edit_gated(serial, Edit::Write { offset, data })?; Ok((data.len() as u32, (Some(before), Some(after)))) } /// SETATTR of a companion: mode, size and modification time; the @@ -130,6 +128,10 @@ impl Kernel { { return Err(Status::Perm); } + // One SETATTR runs as one edit: the guard is checked against the body + // its size change then applies to, with no WRITE in between. + let gate = self.edit_gate(serial)?; + let _editing = gate.lock().unwrap_or_else(|poison| poison.into_inner()); let before = { let companions = self.companions(); let file = companions.files.get(&serial).ok_or(Status::Stale)?; @@ -148,7 +150,7 @@ impl Kernel { if crate::trace::enabled() { crate::trace::handle("SETATTR", serial, &format!("size={size}")); } - self.edit_companion(serial, Edit::Size(size as usize))?; + self.edit_gated(serial, Edit::Size(size as usize))?; } let mut companions = self.companions(); if !companions.files.contains_key(&serial) { @@ -171,22 +173,18 @@ impl Kernel { let after = Companions::stat(serial, file); Ok((after.clone(), (Some(before), Some(after)))) } + /// `serial`'s edit gate: whoever holds it is the companion's one edit. + fn edit_gate(&self, serial: u64) -> Result>, Status> { + let companions = self.companions(); + let file = companions.files.get(&serial).ok_or(Status::Stale)?; + Ok(file.editing.clone()) + } /// 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()); + /// outside the companion lock. The caller holds this companion's gate, so + /// the edit runs alone and the length recorded is the one its own bytes + /// leave. + fn edit_gated(&self, serial: u64, edit: Edit<'_>) -> Result { match self.apply_edit(serial, &edit)? { Edited::Done(stat) => Ok(stat), Edited::NoSlot => { @@ -276,7 +274,8 @@ impl Kernel { 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()), + // The decoded form's own charge comes back when it becomes bytes. + Body::Decoded(image) => edited_len(edit, image.len()).saturating_sub(image.cost()), }; if need > avail { // The body does not fit the resident budget, but the edit may diff --git a/engine/crates/layerfs-nfs/src/apple_double/index.rs b/engine/crates/layerfs-nfs/src/apple_double/index.rs index 8a455c31a5..84e4a1c8fa 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/index.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/index.rs @@ -163,7 +163,7 @@ impl Companions { let Some(image) = Image::compact(bytes) else { return Decoded::Unchanged; }; - if image.cost() > DECODED_ENTRY_BYTES { + if !worth_decoding(&image, bytes.len()) { return Decoded::Unchanged; } let cost = image.cost(); @@ -216,7 +216,7 @@ impl Companions { return; }; file.whole = true; - if image.cost() <= DECODED_ENTRY_BYTES { + if worth_decoding(&image, bytes.len()) { file.body = Body::Decoded(image); } } @@ -350,3 +350,10 @@ impl Companions { } } } +/// Whether a whole image of `len` bytes is kept decoded: only when its decoded +/// form costs less than the bytes it replaces, and at most +/// [`DECODED_ENTRY_BYTES`]. Many small attributes cost more decoded than as +/// written, and such an image is kept as the client wrote it. +fn worth_decoding(image: &Image, len: usize) -> bool { + image.cost() <= DECODED_ENTRY_BYTES && image.cost() < len +} diff --git a/engine/crates/layerfs-nfs/src/apple_double_codec.rs b/engine/crates/layerfs-nfs/src/apple_double_codec.rs index 459b507c96..033e4dde6b 100644 --- a/engine/crates/layerfs-nfs/src/apple_double_codec.rs +++ b/engine/crates/layerfs-nfs/src/apple_double_codec.rs @@ -288,7 +288,10 @@ impl Image { 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)); + // Each entry takes more than its fixed part, so the image bounds the + // count a client may claim before any entry is read. + let fits = (len - ENTRIES_AT) / (ENTRY_FIXED + 1); + let mut attrs = Vec::with_capacity(usize::from(count).min(fits)); for _ in 0..count { let value_len = get32(image, entry + 4)? as usize; let name_len = usize::from(*image.get(entry + 10)?); diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 7557414dac..3a51bd9f43 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -54,6 +54,38 @@ fn image(finder: [u8; 32], attrs: &[(&[u8], Vec)]) -> Vec { .encode() } +#[test] +fn an_image_whose_attributes_cost_more_than_its_bytes_is_kept_as_written() { + let base = temp("decode-costly"); + 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"f", 0o644).unwrap(); + let ad = c.touch(&root, b"._f", 0o644).unwrap(); + // Many one-byte names with empty values: a whole image the client could + // write, whose decoded attributes would be counted at several times its + // bytes. + let names: Vec<[u8; 2]> = (0..600u16).map(|n| [b'a' + (n % 26) as u8, (n / 26) as u8 + b'a']).collect(); + let attrs: Vec<(&[u8], Vec)> = names.iter().map(|name| (&name[..], Vec::new())).collect(); + let bytes = image([0x22; 32], &attrs); + let decoded = Image::compact(&bytes).expect("a whole image"); + assert!(decoded.cost() > bytes.len(), "{} <= {}", decoded.cost(), bytes.len()); + c.write(&ad.handle, 0, &bytes).unwrap(); + let held = server.held(); + assert_eq!((held.companions, held.companions_decoded), (1, 0)); + assert_eq!(held.companion_bytes, bytes.len(), "charged at its length"); + assert_eq!(c.read_all(&ad.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_whole_image_is_read_back_as_written_from_every_name_of_the_inode() { let base = temp("decode"); From 3466c3db3125f0e83698c5a34767c66f3123e23f Mon Sep 17 00:00:00 2001 From: YifanXu1999 Date: Tue, 17 Nov 2026 12:11:37 +0800 Subject: [PATCH 51/53] fix(nfs): AppleDouble spill review fixes (#714 review) - A WRITE that grows a spilled body no longer shows its new length before its bytes. `apply_edit` wrote the body out pre-extended to the edit's length, and `commit_spilled` recorded that length before `edit.disk` wrote anything. A GETATTR or READ in between (neither takes the edit gate) saw the larger size and read zeros, and a failed edit shrank it back, so a client could see a length no WRITE made. The body is now written out at the length it has, the edit grows its file itself, and `record_edit` moves the length after the bytes are there. `restore_len` and the length it saved are gone, and with them the early `Stale` return that skipped `unreserve` after a reservation. - `spill_target` never replaces a body that is already on disk, whoever asks. Before, a spill with no `used` snapshot renamed its file onto the live one first and found out afterwards. That was unreachable while the edit gate holds, but it would have deleted the live body. - With no spill directory, `spill_for` stops at once instead of copying or encoding every resident victim under the companion lock only to fail on each. One victim whose file cannot be written is still passed over for the next (`an_eviction_victim_that_cannot_be_written_out_does_not_fail_the_writer` keeps that). - `spill_applies` was public only for a test that fed it integers: both are removed, and `spill_target` compares the tick itself. Deleted test: `write.rs::a_spill_replaces_a_companion_body_only_when_no_call_changed_it`. The behaviour it named holds: every body change runs under the edit gate, and a spill takes the gate with `try_lock` and checks the `used` tick. - `spilled_companions_outnumber_the_open_file_limit` waits for its child with a 90 s deadline and kills a child that hangs, instead of `status()`, which waits indefinitely. Docs: nfs.md, the paragraph on one edit per companion. Tests: no deterministic client-side test reproduces the GETATTR-during-spill window. The covering suites pass on macOS (apple_double_decode 31, write 15). Production LOC: 171,523 -> 171,508 (delta -15) core 39,795 -> 39,795 (0) engine 76,946 -> 76,931 (-15) layerfs-nfs -15 control 48,436 -> 48,436 (0) api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent 519f8db475 and the staged tree Co-Authored-By: Claude Opus 5.5 --- docs/architecture/engine/kernel-routes/nfs.md | 9 ++++-- engine/crates/layerfs-nfs/src/apple_double.rs | 6 ---- .../layerfs-nfs/src/apple_double/edit.rs | 29 ++++++----------- .../layerfs-nfs/src/apple_double/index.rs | 9 +++--- engine/crates/layerfs-nfs/tests/write.rs | 32 ++++++++++--------- 5 files changed, 37 insertions(+), 48 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 157b251112..805281dc63 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -276,9 +276,12 @@ One edit per companion runs under that gate recording length and bytes together and spilling its own body rather than failing with `NFS3ERR_IO`. A SETATTR is one such edit from its guard to its mode and time, and a WRITE reads its pre-op attributes under the gate, so a -guarded SETATTR checks the very body its size change applies to. A file operation that fails after the spill put the -length the companion had back, so a refused write reports neither bytes nor the -longer file the spill made for it. Eviction follows `Companions::by_use`, the +guarded SETATTR checks the very body its size change applies to. A body is written out at the length it has and the +edit grows its file itself; the recorded length moves only once the edit's bytes +are in the file, so no GETATTR or READ sees a length whose bytes are not there, +and a refused write leaves the length it had. A spill never replaces a body that +is already on disk. With no spill directory, a body that does not fit evicts +nothing. Eviction follows `Companions::by_use`, the `(used tick, serial)` order kept on attach, detach and every use: the victim is the first entry (O(log n) per round, no walk of the index), and the rounds end when no companion holding memory is left. `ExportServing::reclaim` and release diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index b455797c4e..fdfe0ef322 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -254,12 +254,6 @@ fn opening(how: &How) -> &'static str { How::Exclusive(_) => "existing-exclusive", } } -/// Whether a body a spill wrote out still replaces its companion: only when the -/// companion is the one the snapshot saw (`used` is the tick read then) and its -/// body is still in memory, so no call wrote to it while the file was written. -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 { diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index c4a62cb626..96937cbc2f 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -233,34 +233,21 @@ impl Kernel { if self.companions().reserve(serial) == Slot::Full { return Ok(Edited::NoSlot); } - // A failed file operation leaves the length the companion had: the - // spill may have grown its file to the length this edit wanted, and a - // refused edit must not report it. - let before = self - .companions() - .files - .get(&serial) - .map(|file| file.len) - .ok_or(Status::Stale)?; - let written = self.spill_gated(serial, target).and_then(|()| { + // The body is written out at the length it has, and the edit grows + // its file itself: the companion's recorded length moves only once + // the edit's bytes are in the file, so no GETATTR or READ meanwhile + // sees a length whose bytes are not there, and a failed file + // operation leaves the length it had. + let written = self.spill_gated(serial, 0).and_then(|()| { let file = self.spill_file(serial, true)?; edit.disk(&file) }); if let Err(status) = written { - self.restore_len(serial, before); self.companions().unreserve(serial); return Err(status); } self.record_edit(serial, edit).map(Edited::Done) } - /// Puts back the length `serial` had before an edit whose file operation - /// failed. - fn restore_len(&self, serial: u64, len: usize) { - let mut companions = self.companions(); - if let Some(file) = companions.files.get_mut(&serial) { - file.len = len; - } - } /// Applies `edit` to `serial`'s body in memory while the budget holds it /// (a decoded body is encoded first), recording its length, recency and /// time and deciding again whether it is a whole image, under the same @@ -381,6 +368,10 @@ impl Kernel { if companions.resident_bytes + need <= companions.resident_budget { return Ok(true); } + // With nowhere to spill to, no victim can give memory back. + if companions.spill_dir.is_none() { + return Ok(false); + } companions.oldest_resident(&skip) }; let Some(victim) = victim else { diff --git a/engine/crates/layerfs-nfs/src/apple_double/index.rs b/engine/crates/layerfs-nfs/src/apple_double/index.rs index 84e4a1c8fa..7bf8cdcdbe 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/index.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/index.rs @@ -1,7 +1,7 @@ //! The companion index of one export: its names, main inodes, slots of the //! index bound, resident budget and eviction order. use super::{ - spill_applies, Body, Companion, Companions, Decoded, Holding, Named, Orphan, Slot, + Body, Companion, Companions, Decoded, Holding, Named, Orphan, Slot, DECODED_ENTRY_BYTES, }; use crate::{ @@ -237,10 +237,9 @@ impl Companions { /// [`Self::commit_spilled`]. pub(super) fn spill_target(&self, serial: u64, used: Option) -> Result, Status> { let file = self.files.get(&serial).ok_or(Status::Stale)?; - if let Some(used) = used { - if !spill_applies(used, file.used, !matches!(file.body, Body::Spilled)) { - return Ok(None); - } + // A body already on disk is never replaced: its file is the body. + if matches!(file.body, Body::Spilled) || used.is_some_and(|used| used != file.used) { + return Ok(None); } let dir = self.spill_dir.as_ref().ok_or(Status::NoSpc)?; Ok(Some(spill_path(dir, serial))) diff --git a/engine/crates/layerfs-nfs/tests/write.rs b/engine/crates/layerfs-nfs/tests/write.rs index 494a3cef18..f1e444cfe3 100644 --- a/engine/crates/layerfs-nfs/tests/write.rs +++ b/engine/crates/layerfs-nfs/tests/write.rs @@ -1001,19 +1001,6 @@ fn a_companion_survives_reclaim_after_its_main_file_gains_a_second_name() { fs::remove_dir_all(base).unwrap(); } -#[test] -fn a_spill_replaces_a_companion_body_only_when_no_call_changed_it() { - use layerfs_nfs::apple_double::spill_applies; - // The companion the body was written from, still resident and untouched: - // the spilled file replaces it. - assert!(spill_applies(7, 7, true)); - // Another call wrote to the companion while its body was being written out: - // that newer body stays and the file just written is dropped. - assert!(!spill_applies(7, 8, true)); - // Another call spilled the body first: its file stays. - assert!(!spill_applies(7, 7, false)); -} - /// The process's soft and hard `RLIMIT_NOFILE`. fn nofile_limits() -> (libc::rlim_t, libc::rlim_t) { let mut limit = libc::rlimit { @@ -1133,14 +1120,29 @@ const FD_LIMIT_CHILD: &str = "LAYERFS_NFS_FD_LIMIT_CHILD"; /// 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) { + // Bounded: a child that hangs is killed and fails this test, so it never + // outlives the parent holding its server and spill directory. + const DEADLINE: Duration = Duration::from_secs(90); let exe = std::env::current_exe().expect("the test binary's own path"); - let status = std::process::Command::new(exe) + let mut child = std::process::Command::new(exe) .arg("--exact") .arg(name) .arg("--test-threads=1") .env(marker, "1") - .status() + .spawn() .expect("the test binary starts again"); + let started = std::time::Instant::now(); + let status = loop { + if let Some(status) = child.try_wait().expect("the child's status") { + break status; + } + if started.elapsed() >= DEADLINE { + drop(child.kill()); + drop(child.wait()); + panic!("{name} did not finish within {DEADLINE:?} in its own process"); + } + std::thread::sleep(Duration::from_millis(50)); + }; assert!(status.success(), "{name} failed in its own process"); } From fc40696bbd9aad08fac46aba36db01d5718c9b67 Mon Sep 17 00:00:00 2001 From: YifanXu1999 Date: Tue, 17 Nov 2026 12:14:23 +0800 Subject: [PATCH 52/53] fix(nfs): companion rename, slot reservation and macOS mount options (#722 review) - RENAME of one of a companion's names moves only that name. `rename_companion` never got the source name: it overwrote the companion's primary name and kept every LINK-made name, the renamed one included. With `._a` linked as `._b`, `mv b c` and `._b -> ._c` left `._b` answering and dropped `._a`'s own key. A companion reached only through its inode keeps the names it holds and gains the target. - A slot reservation is never left for a companion that is gone. `Companions::reserve` takes nothing for a serial another call removed (a REMOVE takes no edit gate), and `record_edit` gives the reservation back before it can find the companion gone. Either path used to leave the bound one slot smaller for the life of the export. - macOS mounts no longer add `nordirplus` (owner decision 2026-11-17). This reverts 46550ff30b: the loss it targeted reproduced 0/5 with and without the option, and every READDIR then costs a LOOKUP per entry. The hard-link loss with READDIRPLUS on stays an open, unconfirmed risk. Review finding not taken: making REMOVE of `._a` drop the whole companion while `a` still exists (to serve `xattr -c` on a hard-linked file). The client's own sequence for `ln a b` removes `._a` while `a` exists and expects the attributes under `b` to stay. That is the macOS loss #722 fixed, and `a_hard_link_keeps_the_companion_under_its_other_names` pins it. Docs: nfs.md, the companion names paragraph and the macOS client options. Test: new `apple_double_decode.rs::renaming_one_linked_companion_name_moves_only_that_name`. It fails on the parent (3466c3db31), where `._b` still answers, and passes here. The reservation race has no deterministic client-side reproduction. Production LOC: 171,508 -> 171,521 (delta +13) core 39,795 -> 39,795 (0) engine 76,931 -> 76,944 (+13) layerfs-nfs +13 control 48,436 -> 48,436 (0) api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent 3466c3db31 and the staged tree Co-Authored-By: Claude Opus 5.5 --- docs/architecture/engine/kernel-routes/nfs.md | 9 ++--- .../layerfs-daemon/src/control/export.rs | 8 +--- engine/crates/layerfs-nfs/src/apple_double.rs | 22 +++++++++-- .../layerfs-nfs/src/apple_double/edit.rs | 4 +- .../layerfs-nfs/src/apple_double/index.rs | 7 +++- .../layerfs-nfs/tests/apple_double_decode.rs | 37 +++++++++++++++++++ 6 files changed, 69 insertions(+), 18 deletions(-) diff --git a/docs/architecture/engine/kernel-routes/nfs.md b/docs/architecture/engine/kernel-routes/nfs.md index 805281dc63..48032f82a8 100644 --- a/docs/architecture/engine/kernel-routes/nfs.md +++ b/docs/architecture/engine/kernel-routes/nfs.md @@ -210,7 +210,8 @@ companion name (`._a` to `._b`, which a client that carries the attributes to a new name sends) adds one, answering `NFS3ERR_EXIST` for a name already held and `NFS3ERR_ACCES` for a name of the Workspace, and a REMOVE of one of those names drops only that name while the companion holds another or its inode has -another name the export knows. The REMOVE of the last name of an inode with one +another name the export knows, and a RENAME of one of them moves only that +name. The REMOVE of the last name of an inode with one name is the client clearing the attributes, which takes the companion with it, as does any name of a companion no main inode owns. @@ -346,14 +347,10 @@ or container, where the environment is passed differently. | 2 `DUMP`; 3 `UMNT`; 5 `EXPORT` | Empty list; success; one export with no groups | Client options are the daemon's `Mounter::host`. macOS: -`vers=3,tcp,port={port},mountport={port},locallocks,nfc,noatime,actimeo=60,rsize=262144,wsize=262144,soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse,nordirplus` +`vers=3,tcp,port={port},mountport={port},locallocks,nfc,noatime,actimeo=60,rsize=262144,wsize=262144,soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse` (`rsize`/`wsize` are `TRANSFER_WINDOW`); elsewhere `vers=3,proto=tcp,port={port},mountport={port},mountproto=tcp,nolock,actimeo=60` ([`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs)). -`nordirplus` turns READDIRPLUS off: a macOS client holding a directory's -complete READDIRPLUS listing answers a `._` name absent from it with ENOENT -and never asks the server, and this export serves AppleDouble companions -without listing them, so every `._` name has to arrive as a LOOKUP. An NFS ready receipt has `abi_major == 0` and its `mount_id` is the port. ## Application SQLite databases on the NFS route diff --git a/engine/crates/layerfs-daemon/src/control/export.rs b/engine/crates/layerfs-daemon/src/control/export.rs index bffb08e420..2128e08893 100644 --- a/engine/crates/layerfs-daemon/src/control/export.rs +++ b/engine/crates/layerfs-daemon/src/control/export.rs @@ -97,18 +97,14 @@ impl Mounter { /// access time: this export keeps one timestamp and shows it as atime, /// mtime and ctime alike, and `layerfs-nfs` decodes and drops a SETATTR's /// access time, so the update would cost one SETATTR per file a read or a - /// scan touches and change nothing. `nordirplus` turns READDIRPLUS off: - /// a client holding a directory's complete READDIRPLUS listing answers a - /// `._` name absent from it with "not found" and never asks the server, - /// and this export never lists the AppleDouble companions it serves, so - /// every `._` name has to arrive as a LOOKUP. + /// scan touches and change nothing. pub fn host() -> Self { let helper = |words: &[&str]| Helper(words.iter().map(|w| (*w).to_owned()).collect()); if cfg!(target_os = "macos") { // `rsize`/`wsize` ask for the window FSINFO declares; the client // clamps to the smaller of the two. let options = format!( - "vers=3,tcp,port={{port}},mountport={{port}},locallocks,nfc,noatime,actimeo=60,rsize={WINDOW},wsize={WINDOW},soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse,nordirplus" + "vers=3,tcp,port={{port}},mountport={{port}},locallocks,nfc,noatime,actimeo=60,rsize={WINDOW},wsize={WINDOW},soft,intr,dumbtimer,timeo=300,retrans=6,mutejukebox,nobrowse" ); Self { mount: helper(&["/sbin/mount_nfs", "-o", &options, "127.0.0.1:/", "{dir}"]), diff --git a/engine/crates/layerfs-nfs/src/apple_double.rs b/engine/crates/layerfs-nfs/src/apple_double.rs index fdfe0ef322..ae9cd22731 100644 --- a/engine/crates/layerfs-nfs/src/apple_double.rs +++ b/engine/crates/layerfs-nfs/src/apple_double.rs @@ -165,7 +165,8 @@ struct Orphan { pub(crate) enum Slot { /// It took the slot, which it gives back if its commit does not land. Taken, - /// It already held a slot (or a reservation for one): nothing was taken. + /// It already held a slot (or a reservation for one), or the companion + /// is gone: nothing was taken. Held, /// The bound has none. Full, @@ -642,7 +643,8 @@ impl Kernel { if !crate::names::apple_double(new_name) || new_name.len() > 255 { return Some(Err(Status::Access)); } - let renamed = self.rename_companion(serial, (to, new_name.to_vec()), to_main); + let source = (from, name.to_vec()); + let renamed = self.rename_companion(serial, &source, (to, new_name.to_vec()), to_main); trace::companion( "RENAME", to, @@ -657,7 +659,10 @@ impl Kernel { ); Some(renamed) } - /// Moves `serial`'s companion to `target`, under `to_main`'s inode. + /// Moves `serial`'s companion from its name `source` to `target`, under + /// `to_main`'s inode. Only `source` is replaced: its other names (a LINK + /// made them) stay, and a companion reached only through its inode keeps + /// every name it holds and gains `target`. /// /// The body is classified again under the destination, so a whole image /// renamed onto an unknown main is the client's bytes again and takes a @@ -670,6 +675,7 @@ impl Kernel { fn rename_companion( &self, serial: u64, + source: &Named, target: Named, to_main: Option, ) -> Result<(), Status> { @@ -727,7 +733,15 @@ impl Kernel { replaced_path = companions.take_serial(replaced); } } - file.named = target; + if file.named == *source { + file.named = target.clone(); + } else if let Some(named) = file.also.iter_mut().find(|named| **named == *source) { + *named = target.clone(); + } else if file.named != target { + file.also.push(target.clone()); + } + file.also.retain(|named| *named != file.named); + file.also.dedup(); file.inode = to_main; file.used = companions.tick(); // A client may write a companion under another name first, and a diff --git a/engine/crates/layerfs-nfs/src/apple_double/edit.rs b/engine/crates/layerfs-nfs/src/apple_double/edit.rs index 96937cbc2f..2d145fb248 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/edit.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/edit.rs @@ -335,6 +335,9 @@ impl Kernel { fn record_edit(&self, serial: u64, edit: &Edit<'_>) -> Result { let mut companions = self.companions(); let tick = companions.tick(); + // The slot held for this commit is given back whether or not the + // companion is still there to take it. + companions.unreserve(serial); let mut file = companions.detach(serial).ok_or(Status::Stale)?; record(edit, &mut file); file.used = tick; @@ -342,7 +345,6 @@ impl Kernel { touch(&mut file.metadata); let stat = Companions::stat(serial, &file); companions.attach(serial, file); - companions.unreserve(serial); Ok(stat) } /// Spills the least recently used bodies to disk (outside the companion diff --git a/engine/crates/layerfs-nfs/src/apple_double/index.rs b/engine/crates/layerfs-nfs/src/apple_double/index.rs index 7bf8cdcdbe..2b945bf628 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/index.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/index.rs @@ -295,7 +295,12 @@ impl Companions { /// the bound has room for one. [`Slot::Held`] means it already has one /// (or a reservation) and nothing was taken. pub(super) fn reserve(&mut self, serial: u64) -> Slot { - if self.slots.contains(&serial) || self.reserved.contains(&serial) { + // A companion another call removed takes nothing: its commit finds it + // gone, and a reservation left for it would shrink the bound for good. + if self.slots.contains(&serial) + || self.reserved.contains(&serial) + || !self.files.contains_key(&serial) + { return Slot::Held; } if self.slots.len() + self.reserved.len() >= self.held_limit { diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 3a51bd9f43..05e890ad40 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -1595,6 +1595,43 @@ fn a_linked_companion_name_is_another_name_of_the_same_companion() { fs::remove_dir_all(base).unwrap(); } +#[test] +fn renaming_one_linked_companion_name_moves_only_that_name() { + let base = temp("companion-link-rename"); + let tree = base.join("tree"); + source(&tree); + let rig = rig::Rig::new(&tree, &base.join("rig"), Duration::from_secs(30)); + let server = rig.export(TcpListener::bind("127.0.0.1:0").unwrap(), UID, GID, false); + let mut c = Client::connect(server.local_addr(), UID, GID); + let root = c.mnt("/"); + let a = c.touch(&root, b"a", 0o644).unwrap(); + c.write(&a.handle, 0, b"the data file").unwrap(); + let ad = c.touch(&root, b"._a", 0o644).unwrap(); + let whole = image([0x63; 32], &[(b"user.kept", pattern(13, 80))]); + c.write(&ad.handle, 0, &whole).unwrap(); + // `ln a b` with the attributes carried to the new name. + c.link(&a.handle, &root, b"b").unwrap(); + c.link(&ad.handle, &root, b"._b").unwrap(); + + // `mv b c`: the main name, then its companion name. + c.rename(&root, b"b", &root, b"c").unwrap(); + c.rename(&root, b"._b", &root, b"._c").unwrap(); + + // Only `._b` moved: `._a` still names the companion, `._c` is the new + // name, and `._b` names nothing any more. + assert_eq!(c.lookup(&root, b"._a").unwrap().0, ad.handle); + assert_eq!(c.lookup(&root, b"._c").unwrap().0, ad.handle); + assert_eq!(c.lookup(&root, b"._b").map(|_| ()), Err(NOENT)); + assert_eq!(c.read_all(&ad.handle, 64 * 1024), whole); + assert_eq!(server.held().companions, 1); + + drop(c); + let released = server.stop(); + let (_, outstanding) = rig.stop(released); + assert_eq!(outstanding, 0); + fs::remove_dir_all(base).unwrap(); +} + #[test] fn the_slot_bound_holds_when_writes_claim_the_last_slot_together() { const WRITERS: usize = 8; From d4c6c8297f28e27aca48a88cfc4b425d3601c1c3 Mon Sep 17 00:00:00 2001 From: YifanXu1999 Date: Tue, 17 Nov 2026 12:23:22 +0800 Subject: [PATCH 53/53] chore: format the review fixes; compile #637's PostgreSQL test unconditionally - rustfmt on apple_double/index.rs and the two NFS test files changed by the review fixes. - engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs (from #637) was behind `#![cfg(feature = "postgresql")]`, but #726 on the base branch removed that feature and always compiles the PostgreSQL engine. Clippy refused the unknown cfg value, and the file would never have run. The gate is removed, as in the other postgresql_* tests, which report NOT_RUN without LAYERFS_TEST_POSTGRES_URL. Production LOC: 171,521 -> 171,524 (delta +3; rustfmt line breaks) core 39,795 -> 39,795 (0) engine 76,944 -> 76,947 (+3) layerfs-nfs +3 control 48,436 -> 48,436 (0) api 6,346 -> 6,346 (0) reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) Method: tools/production_loc.py --detail on parent fc40696bbd and the staged tree Co-Authored-By: Claude Opus 5.5 --- engine/crates/layerfs-nfs/src/apple_double/index.rs | 9 ++++++--- .../crates/layerfs-nfs/tests/apple_double_decode.rs | 11 +++++++++-- engine/crates/layerfs-nfs/tests/export.rs | 6 +++++- .../tests/postgresql_readdirplus_window.rs | 5 +---- 4 files changed, 21 insertions(+), 10 deletions(-) diff --git a/engine/crates/layerfs-nfs/src/apple_double/index.rs b/engine/crates/layerfs-nfs/src/apple_double/index.rs index 2b945bf628..3ca6861fda 100644 --- a/engine/crates/layerfs-nfs/src/apple_double/index.rs +++ b/engine/crates/layerfs-nfs/src/apple_double/index.rs @@ -1,8 +1,7 @@ //! The companion index of one export: its names, main inodes, slots of the //! index bound, resident budget and eviction order. use super::{ - Body, Companion, Companions, Decoded, Holding, Named, Orphan, Slot, - DECODED_ENTRY_BYTES, + Body, Companion, Companions, Decoded, Holding, Named, Orphan, Slot, DECODED_ENTRY_BYTES, }; use crate::{ apple_double_codec::Image, @@ -235,7 +234,11 @@ impl Companions { /// can be replaced). The caller renames its file to that path itself, /// outside this lock, and then commits the body with /// [`Self::commit_spilled`]. - pub(super) fn spill_target(&self, serial: u64, used: Option) -> Result, Status> { + pub(super) fn spill_target( + &self, + serial: u64, + used: Option, + ) -> Result, Status> { let file = self.files.get(&serial).ok_or(Status::Stale)?; // A body already on disk is never replaced: its file is the body. if matches!(file.body, Body::Spilled) || used.is_some_and(|used| used != file.used) { diff --git a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs index 05e890ad40..d309dda38d 100644 --- a/engine/crates/layerfs-nfs/tests/apple_double_decode.rs +++ b/engine/crates/layerfs-nfs/tests/apple_double_decode.rs @@ -68,11 +68,18 @@ fn an_image_whose_attributes_cost_more_than_its_bytes_is_kept_as_written() { // Many one-byte names with empty values: a whole image the client could // write, whose decoded attributes would be counted at several times its // bytes. - let names: Vec<[u8; 2]> = (0..600u16).map(|n| [b'a' + (n % 26) as u8, (n / 26) as u8 + b'a']).collect(); + let names: Vec<[u8; 2]> = (0..600u16) + .map(|n| [b'a' + (n % 26) as u8, (n / 26) as u8 + b'a']) + .collect(); let attrs: Vec<(&[u8], Vec)> = names.iter().map(|name| (&name[..], Vec::new())).collect(); let bytes = image([0x22; 32], &attrs); let decoded = Image::compact(&bytes).expect("a whole image"); - assert!(decoded.cost() > bytes.len(), "{} <= {}", decoded.cost(), bytes.len()); + assert!( + decoded.cost() > bytes.len(), + "{} <= {}", + decoded.cost(), + bytes.len() + ); c.write(&ad.handle, 0, &bytes).unwrap(); let held = server.held(); assert_eq!((held.companions, held.companions_decoded), (1, 0)); diff --git a/engine/crates/layerfs-nfs/tests/export.rs b/engine/crates/layerfs-nfs/tests/export.rs index 9aed2a8372..4db545e2ce 100644 --- a/engine/crates/layerfs-nfs/tests/export.rs +++ b/engine/crates/layerfs-nfs/tests/export.rs @@ -651,7 +651,11 @@ fn a_companion_lookup_never_answers_a_stale_directory_observation() { let fresh = directory.expect("the failed LOOKUP's directory row"); assert_eq!(fresh.nlink, 3, "the directory gained a child directory"); let removed = client.remove(&made.handle, b"._file").unwrap(); - assert_eq!(removed.after, Some(fresh), "the facts the failed LOOKUP read"); + assert_eq!( + removed.after, + Some(fresh), + "the facts the failed LOOKUP read" + ); drop(client); drop(other); diff --git a/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs b/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs index 1fdd58a3eb..8c1bfff01f 100644 --- a/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs +++ b/engine/crates/layerfs-store-service/tests/postgresql_readdirplus_window.rs @@ -16,10 +16,7 @@ //! Needs a PostgreSQL server: set `LAYERFS_TEST_POSTGRES_URL` (for example //! `host=127.0.0.1 port=5432 user=layerfs password=… dbname=layerfs_test //! sslmode=disable`). Without it the two PostgreSQL cases report NOT_RUN and -//! assert nothing, while the SQLite cases still run. The whole file is behind -//! `#![cfg(feature = "postgresql")]`, so a build without that feature runs -//! none of them. -#![cfg(feature = "postgresql")] +//! assert nothing, while the SQLite cases still run. #[path = "support/installed_store.rs"] #[allow(dead_code)] mod installed;