Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
1810b4e
refactor(nfs): move Released and Kernel::release into kernel/released…
jiangkoumo Nov 14, 2026
210d5f8
feat(nfs): decode the AppleDouble image a macOS client writes (lp73)
jiangkoumo Nov 14, 2026
fa5dd34
feat(nfs): hold a whole AppleDouble image as its own attributes (lp73)
jiangkoumo Nov 14, 2026
584cc3e
docs(nfs): document the decoded AppleDouble companion (lp73)
jiangkoumo Nov 14, 2026
7b38dad
feat(nfs): spill AppleDouble companion bodies beyond the resident bud…
jiangkoumo Nov 14, 2026
91434f9
test(nfs): cover the companion spill, its files and its cleanup (lp73)
jiangkoumo Nov 14, 2026
8183f89
docs(nfs): document the companion spill area and its cleanup (lp73)
jiangkoumo Nov 14, 2026
b01e805
feat(nfs): encode only the window of the AppleDouble image a READ ask…
jiangkoumo Nov 14, 2026
7ef50a0
refactor(nfs): count decoded AppleDouble images in the resident budge…
jiangkoumo Nov 14, 2026
7a9f20c
Merge lp636-codec into lp636-spill (lp73)
jiangkoumo Nov 14, 2026
e323c0e
feat(nfs): spill a decoded AppleDouble body like any other body (lp73)
jiangkoumo Nov 14, 2026
73f62ef
perf(nfs): keep companion bodies in an eviction order, not a scan (lp73)
jiangkoumo Nov 14, 2026
0cbd34c
perf(nfs): adopt a spilled companion body without the rename under th…
jiangkoumo Nov 14, 2026
485dd2f
fix(nfs): serve a READ that raced a truncation as a short read (lp73)
jiangkoumo Nov 14, 2026
e3e46ae
docs(nfs): record the AppleDouble scratch area as a disposable area (…
jiangkoumo Nov 14, 2026
428ffc3
chore(nfs): make the AppleDouble codec edits fmt- and clippy-clean (l…
jiangkoumo Nov 14, 2026
bdb87af
Merge the codec layer's fmt and clippy pass (lp73)
jiangkoumo Nov 14, 2026
ec17db8
fix(nfs): keep an eviction victim's failure out of the writer's reply…
jiangkoumo Nov 14, 2026
aec83af
fix(nfs): leave a failed disk edit's length where it was (lp73)
jiangkoumo Nov 14, 2026
ff28f61
Merge upstream/layerfs_v2_0_0 (cb8ced9d3) into the codec layer (lp73)
jiangkoumo Nov 15, 2026
e3c80ed
Merge the codec layer's upstream merge (ff28f6118) into the spill lay…
jiangkoumo Nov 15, 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.

2 changes: 1 addition & 1 deletion docs/architecture/engine/daemon/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ layerfs-daemon --config <file>
| 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 `<mounts>/.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

Expand Down
47 changes: 39 additions & 8 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`; `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 @@ -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) |
Expand All @@ -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/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
Expand All @@ -174,11 +174,42 @@ 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 of companion 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_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 `RESIDENT_BYTES`
as `Image::cost` (its names and values, not its image) rather than at its
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.

Bodies kept as written and decoded bodies alike, exceeding `RESIDENT_BYTES`
together, are written to `<serial>.<n>.tmp` (`create_new`, dir `0700`, file
`0600`) and renamed to `<serial>`, 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, 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)),
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
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.
`ExportServing::reclaim` and release delete `<mounts>/.appledouble`.

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

Expand Down
1 change: 1 addition & 0 deletions docs/general/cleanup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, `<mounts>/.appledouble/<namespace>/` 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 |
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 @@ -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<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 @@ -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(
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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;
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