Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
24fa155
fix(nfs): spill AppleDouble companion bodies to disk beyond resident …
jiangkoumo Nov 8, 2026
9d580d8
refactor(nfs): slim the AppleDouble spill path and keep a body writte…
jiangkoumo Nov 8, 2026
ca153a7
fix(nfs): hold no descriptor per spilled AppleDouble body and close t…
jiangkoumo Nov 8, 2026
79e378e
Fix AppleDouble companion creation and alias reclamation (LP73-ASK2-A…
jiangkoumo Nov 9, 2026
640a304
Merge commit '58c548b3e' into feat/lp73-appledouble-decode-v2
jiangkoumo Nov 10, 2026
fac9124
feat(nfs): decode AppleDouble companions into their inode's attribute…
jiangkoumo Nov 10, 2026
0ecb4c5
fix(nfs): edit decoded companions, slot unknown mains, rename one nam…
jiangkoumo Nov 10, 2026
c0c83e3
docs(nfs): reflow the companion paragraph after the rename wording (l…
jiangkoumo Nov 10, 2026
7b706ed
Merge remote-tracking branch 'upstream/layerfs_v2_0_0' into fix/lp73-…
jiangkoumo Nov 13, 2026
3ed05e4
docs(nfs): note the remaining ._ create overhead on macOS NFSv3
jiangkoumo Nov 13, 2026
3ab79db
Merge remote-tracking branch 'upstream/layerfs_v2_0_0' into pr636-r1
jiangkoumo Nov 13, 2026
5851b52
fix(nfs): drop a retired name's keys without scanning by_name (lp73)
jiangkoumo Nov 13, 2026
b4d0222
fix(nfs): edit a companion alone, reclaim without copying by_name (lp73)
jiangkoumo Nov 13, 2026
c7145b6
test(nfs): run the companion fd-limit case in its own process (lp73)
jiangkoumo Nov 13, 2026
a7b6ffd
docs(nfs): name the companion edit gate without a broken intra-doc li…
jiangkoumo Nov 13, 2026
f2dcd53
fix(nfs): re-check a companion name at the index bound, keep renamed …
jiangkoumo Nov 13, 2026
0a4dfdd
style(nfs): rustfmt the companion edit file this branch touches (lp73)
jiangkoumo Nov 13, 2026
778d831
docs(nfs): clarify whole-image bound in Companions::slots comment (lp73)
jiangkoumo Nov 13, 2026
22b8df2
Merge remote-tracking branch 'upstream/layerfs_v2_0_0' into pr636-r1 …
jiangkoumo Nov 13, 2026
2e09f02
docs(nfs): port AppleDouble spill and decode updates into #671 nfs.md…
jiangkoumo Nov 13, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

59 changes: 47 additions & 12 deletions docs/architecture/engine/kernel-routes/nfs.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The daemon starts it and has the host's own NFS client mount it.
| Item | Meaning | Source |
| --- | --- | --- |
| `Server::start` | Starts the accept thread; one connection serves one call at a time, in arrival order | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) |
| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) |
| `ExportConfig` | `path` (normally `/`), `uid`/`gid` shown on every inode, `read_only`, `refuse_apple_double`, `lookups_held`, `companion_spill_dir`, `companion_resident_bytes`, `companions_held`; `writable(uid, gid)` is the default | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) |
| `Server::stop` | Stop accepting, shut down and join every connection, then `Kernel::release`: descriptors first, then lookup references. The engine mount stays with the caller | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) |
| `Kernel` | What a FUSE kernel would hold for a stateless client: one lookup reference per handed-out serial, implicit file and directory descriptors with the facts last published through them, a parent index for `..` | [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) |
| Verifier | One WRITE/COMMIT verifier per export, from the clock and process id under a random key | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) |
Expand Down Expand Up @@ -126,7 +126,7 @@ drawn once per export; it makes guessing costly and does not authenticate.
| --- | --- |
| A publication ticket is released only after the reply's one send attempt, whether or not it reached the client | [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) |
| A WRITE is split into `WRITE_WINDOW` (256 KiB) windows, each one publication; a failure after the first is a short write of the windows already published. WRITE answers `FILE_SYNC`: published, not durable | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs), [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs) |
| `wcc_data` pre- and post-op attributes come from the publishing job's own inode state, RENAME included; no reply reads an attribute outside the job | [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs), [`kernel_visit.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_visit.rs) |
| `wcc_data` pre- and post-op attributes come from the publishing job's own inode state, RENAME included; no reply reads an attribute outside the job. An AppleDouble companion's CREATE, REMOVE or RENAME publishes no engine job and answers both halves from `Table::directory_stats` (or absent when unseen) | [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs), [`kernel_visit.rs`](../../../../engine/crates/layerfs-workspace/src/operations/kernel_visit.rs), [`kernel.rs`](../../../../engine/crates/layerfs-nfs/src/kernel.rs) |
| RENAME looks nothing up first; a detached (`nlink == 0`) destination's reference and descriptor are retired inside that job | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs) |
| COMMIT answers the attributes last published or observed through the implicit descriptor, so `fsync` costs no owner job | [`change.rs`](../../../../engine/crates/layerfs-nfs/src/change.rs) |
| A client silly rename (`.nfs` + 24 hex on Linux; `.nfs.` + 8 hex + `.` + 4 hex on macOS) is served as an UNLINK; the export keeps the inode until the final REMOVE | [`names.rs`](../../../../engine/crates/layerfs-nfs/src/names.rs) |
Expand All @@ -152,22 +152,57 @@ drawn once per export; it makes guessing costly and does not authenticate.
| The refresh never writes into the Workspace and never reverts a mode the install changed | [`refresh.rs`](../../../../engine/crates/layerfs-nfs/src/refresh.rs) |
| `LAYERFS_NFS_REFRESH=0` leaves the client to `actimeo` and close-to-open | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |

## AppleDouble files (`apple_double.rs`)
## AppleDouble files (`apple_double.rs`, `apple_double/edit.rs`, `apple_double_codec.rs`, `apple_double_spill.rs`)

On NFSv3 the macOS client keeps extended attributes and resource forks in
`._<name>` 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,
`._<name>` files (at least one byte after `._`). With `refuse_apple_double`, a
regular `._` file lives in export state only (`Companions`, serials
`SERIALS` = 2^62 and above): LOOKUP, GETATTR, ACCESS, READ, WRITE, SETATTR,
COMMIT, REMOVE and RENAME to another `._` name are served there, READDIR
never lists it and the engine is never called. Any other kind is
`NFS3ERR_ACCES`. `cp`, `copyfile`, `ditto` and `tar` succeed while nothing
reaches the Workspace or a Commit; everything is dropped with the export.
reaches the Workspace, SQLite overlay or a Commit; everything is dropped with
the export.

| Bound | Value | Over the bound |
| --- | --- | --- |
| `HELD` | 4,096 companions | CREATE `NFS3ERR_ACCES` |
| `FILE_BYTES` | 1 MiB per companion | WRITE `NFS3ERR_FBIG` |
| `TOTAL_BYTES` | 64 MiB in all | WRITE `NFS3ERR_NOSPC` |
| Bound | Value | Over the bound | Source |
| --- | --- | --- | --- |
| `HELD` | 65,536 slotted companion entries | Reclaim orphan slotted companions; if still at the bound, CREATE answers `NFS3ERR_NOSPC`, increments `names_refused` and logs at most once per 60 s per export | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) |
| `FILE_BYTES` | 1 MiB per companion | WRITE / SETATTR `NFS3ERR_FBIG` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) |
| `RESIDENT_BYTES` | 32 MiB resident bodies in all | Spill least recently touched resident bodies to `companion_spill_dir` (`<mounts>/.appledouble/<namespace>/<serial>`); host disk I/O errors map to `NFS3ERR_NOSPC` (`ENOSPC`/`EDQUOT`), `NFS3ERR_FBIG` (`EFBIG`), `NFS3ERR_ACCES` (`EACCES`), `NFS3ERR_PERM` (`EPERM`), `NFS3ERR_ROFS` (`EROFS`) or `NFS3ERR_IO` | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs), [`apple_double_spill.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_spill.rs), [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| `DECODED_BYTES` | 512 MiB over decoded companions | Further whole images keep their bytes as written and still take no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) |
| `DECODED_ENTRY_BYTES` | 128 KiB per decoded companion | Larger whole images keep their bytes as written and still take no `HELD` slot | [`apple_double.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double.rs) |

A companion whose main inode the export knows belongs to that inode rather than
to one name: hard links share it, main-file RENAME keeps it under the new name
and existing aliases, and only the inode's last name (or its silly rename)
drops it. When a write leaves an inode-bound companion holding a complete
AppleDouble image that encodes back to the exact bytes written
([`apple_double_codec.rs`](../../../../engine/crates/layerfs-nfs/src/apple_double_codec.rs)),
it is marked whole and takes no `HELD` slot (decoded in memory within
`DECODED_BYTES` / `DECODED_ENTRY_BYTES`, or kept as written bytes above them);
partial writes, resource forks, other layouts and unknown-main companions stay
as written bytes and occupy a slot. `companion_rename` re-classifies under the
destination so moving onto an unknown main name takes a slot (a spilled body
keeps its prior class).

`Table::names` and `Table::aliases` index each serial's names so unlink,
`entry_taken` (when `nlink <= 1`), `renamed` (keeping an overwritten recalled
name as an alias) and retirement drop only that serial's keys from `by_name`
without scanning it. At the `HELD` bound, CREATE releases the companion lock to
collect orphans from `Companions::slots` (walking only slotted entries under
the table and companion locks, never whole images or `by_name`), then re-acquires
the lock and re-reads the companion name and main file before inserting, so
concurrent GUARDED creates of one name yield one serial and one
`NFS3ERR_EXIST`.

Resident bodies exceeding `RESIDENT_BYTES` spill outside the companion lock to
`<serial>.<n>.tmp` (`create_new`, dir `0700`, file `0600`) and are adopted by
rename to `<serial>` 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 `<mounts>/.appledouble`.

## Mount (`mount.rs`, daemon `export.rs`)

Expand Down
51 changes: 35 additions & 16 deletions engine/crates/layerfs-daemon/src/control/export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -177,27 +177,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<String> {
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:
Expand Down Expand Up @@ -479,12 +496,10 @@ impl Service {
}
};
let export = ExportConfig {
path: "/".into(),
uid: config.command_uid,
gid: config.command_gid,
read_only: false,
refuse_apple_double: config.refuse_apple_double,
lookups_held: config.lookups_held,
companion_spill_dir: Some(serving.companion_spill_dir(token)),
..ExportConfig::writable(config.command_uid, config.command_gid)
};
let started = TcpListener::bind((config.listen, 0)).and_then(|listener| {
Server::start(
Expand Down Expand Up @@ -529,6 +544,7 @@ impl Service {
Ran::Busy(detail) | Ran::Failed(detail) => {
let released = server.stop();
drop(std::fs::remove_dir(&directory));
drop(std::fs::remove_dir(serving.spill_root()));
return Err(self.unwind_export(
workspace,
mount,
Expand Down Expand Up @@ -745,6 +761,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;
Expand Down
1 change: 1 addition & 0 deletions engine/crates/layerfs-nfs/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Loading