You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2026/10/26 16:10:01 UTC
(opendal-yinyang) 01/03: feat: add the Linux FUSE mount foundation (#83)
This is an automated email from the ASF dual-hosted git repository.
Xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal-yinyang.git
commit 99bad2bf9c60cbf1d6803466000fc4e8c8c36f81
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Tue Oct 27 00:09:50 2026 +0800
feat: add the Linux FUSE mount foundation (#83)
* fix: remove a redundant closure borrow for current clippy
Co-authored-by: Chojan Shang <ps...@apache.org>
* feat: admit read-only Linux FUSE volumes
Negotiate the fuse frontend from its own implemented capability set
instead of rejecting every non-library frontend. The combination baseline
is now the intersection of the volume, access and frontend contracts, so
a read-only FUSE mount still requires read, list, stable identity, pinned
reads and retained-unlink reads without claiming recoverable staging or
any write-side operation. Writable and non-Linux FUSE configurations are
rejected before an authority connection or staging lease.
Co-authored-by: Chojan Shang <ps...@apache.org>
* feat: add a read-only Linux FUSE mount frontend
Mount a Managed read-only volume in the foreground with
`yy --volume CONFIG mount MOUNTPOINT`. The volume must select
`frontend = "fuse"` and `read_only = true`; the frontend then uses
`fuser` 0.17 only on Linux and keeps every other platform build free of
FUSE dependencies.
The adapter implements the shared Mount contract directly: lookups pin
one authority observation, inode numbers are deterministic from NodeId
with root fixed at 1, kernel lookup counts are tracked per inode,
open/release map to independent references on the node's staged version,
direct I/O bypasses the page cache, and a clean release reclaims the
staged node so the next open re-observes the remote revision. Open
handles report their staged length through fstat, so content and
metadata cannot disagree when the remote side changes. Directory
handles pin a single snapshot revision and serve stable ordinal readdir
offsets.
The read-only frontend refuses to mount a staging database that still
contains unpublished, frozen, conflicted or failed handles instead of
exposing locally staged bytes as a remote snapshot. All remote-capable
callbacks dispatch onto the Tokio runtime with owned request values and
move replies into the tasks; fuser guarantees one reply per request and
replies EIO to dropped unanswered replies. SIGINT/SIGTERM unmount the
session cleanly. FUSE_INTERRUPT is explicitly not cancellation: the
binding answers ENOSYS and the kernel ignores it, so interrupted
syscalls do not stop in-flight remote work.
Co-authored-by: Chojan Shang <ps...@apache.org>
* style: rustfmt the read-only FUSE capability set
* fix: end the FUSE session after an external unmount
A spawned fuser session only ends when the kernel unmounts it; waiting
only on a signal would leave the process and its staging lease alive
after `fusermount3 -u`. A blocking owner now polls the public
BackgroundSession guard for a natural end and receives a local teardown
request, so both an external unmount and SIGINT/SIGTERM lead to one
join/umount_and_join and process exit.
SessionUnmounter is not usable here: fuser 0.17 Session::spawn moves the
mount object into BackgroundSession, emptying any pre-spawn unmounter.
Co-authored-by: Chojan Shang <ps...@apache.org>
* docs: specify the read-only Linux FUSE frontend
Document the mount CLI, the staged-state admission boundary, the
fuse.yinyang session, deterministic inode mapping and lookup references,
pinned file handles with staged-length fstat, pinned directory cursors,
errno policy, cancellation/exit behavior, and the writable-layer
extension points without claiming operations this layer does not
implement. Update the volume admission spec and index for the new
frontend capability set.
Co-authored-by: Chojan Shang <ps...@apache.org>
* refactor: give the FUSE session one blocking owner
The async side only sends an mpsc teardown request, so the background
session never needs shared mutex state: the spawn_blocking closure owns
it, polls `BackgroundSession::guard.is_finished()` for a natural end,
and performs the one join or umount_and_join. Also state the actual
detached-task semantics: ending the session does not abort request
tasks, and the CLI runtime shutdown at process exit drops them.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: bridge FUSE inode newtypes to the inode table
fuser represents inode numbers with the `INodeNo` newtype while the
volume-lifetime map keys plain u64 values. Convert at the adapter
boundary so the root constant, table lookups, and kernel reference
counters have matching types, and release the inode-table guard before
reacquiring it in `resolve_entry` to avoid a cached-readdir deadlock.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: remove unused inode table accessors
InodeTable stored the root identity but never read it, and the root()
accessor had no caller. Drop both instead of silencing the lint.
lookup_count is only exercised by unit tests, so gate it on test builds.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: cover the mount command in non-volume dispatch
The no-volume path rejected mount through a boolean guard, but the
subsequent exhaustive match still needed a Mount arm for the compiler.
Reject mount with a diagnostic naming the required configuration and
list Mount among the unreachable arms that earlier checks consume.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: merge the identical permission branches
Clippy rejects an if/else-if pair whose two bodies are both 0o555;
directories and executable files share the same read-execute mode.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: pin open-handle metadata for path stats
An open read-only handle binds bytes and fstat to the staged version,
but lookup and fh-less getattr served the latest remote observation,
letting a path stat overwrite the same inode's attr cache with an
external size. While any active open exists, lookup/getattr now route
through the handle's staged length and a base snapshot captured at open
(kind, executable and revision from that exact observation, never the
latest inode cache); only inodes without active handles fall back to the
latest snapshot. prepare_open captures the base by observing the staged
record's own revision, and failure paths reclaim the clean staged copy.
Adds a targeted test: publish a first version, open read-only, publish a
second version, assert path stat and fstat stay pinned at the first
length until the reference is released and the clean node is reclaimed.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: bound FUSE teardown and abort the connection on expiry
A lazy unmount keeps the kernel connection alive while clients hold open
references or in-flight requests, so a signal-initiated unmount could
block forever in BackgroundSession::umount_and_join and pin both the
daemon and the blocked clients. The signal path now waits a five-second
grace period after the lazy unmount and exits the process when the
session has not ended; closing /dev/fuse makes the kernel abort every
pending request (fs/fuse fuse_dev_release -> fuse_abort_conn,
-ECONNABORTED) instead of leaving clients wedged.
The cancellation section now states the kernel-verified wait boundary
instead of claiming late replies are discarded: requests already
delivered to the daemon are waited out by the kernel until a reply or a
connection abort, so the daemon must reply exactly once and its exit is
the abort guarantee.
Co-authored-by: Chojan Shang <ps...@apache.org>
* refactor: return teardown expiry to the CLI boundary
The fuse entry point no longer calls process::exit. A signal-initiated
lazy unmount that leaves the session alive past the five-second grace
returns an explicit TeardownExpired outcome, and the CLI prints a stderr
diagnostic and exits non-zero. Exiting there is required so the OS
closes /dev/fuse and the kernel aborts pending requests instead of a
runtime shutdown waiting forever for the blocked session task; the spec
states that this is a crash-equivalent recovery boundary, not a graceful
unmount.
Co-authored-by: Chojan Shang <ps...@apache.org>
* test: materialize the pinned handle before locking the file table
Clippy rejects awaiting prepare_open while the temporary file-table
MutexGuard is alive. Build the open handle first, then insert it.
Co-authored-by: Chojan Shang <ps...@apache.org>
* style: format the tokio feature list for taplo
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: reclaim stale clean records before a fresh open
A release that races an in-flight OpenFile clone reports busy and leaves
the clean staged record in the Mount map with zero references. A later
open would then reuse that snapshot and miss externally published
changes. prepare_open now attempts Mount::reclaim first: busy keeps the
actively shared node, any other error maps normally, and an absent node
is a no-op, so a references-zero clean record is refreshed before
materialization. Adds a targeted test that leaves a stale clean record,
publishes a new version and asserts the next open reads it.
Co-authored-by: Chojan Shang <ps...@apache.org>
* feat: refresh known kernel state on SIGHUP
Add the explicit refresh entry point the #74 acceptance needs. SIGHUP
re-observes the latest snapshot once, reclaims clean unreferenced nodes
through Mount (Busy nodes stay pinned), and invalidates known inode
attributes plus dentries this adapter actually replied to the kernel.
Mount::refresh is never used because it would rebase live handles, and
there is no polling or change-feed watch.
The notifier comes from BackgroundSession before teardown takes
ownership. Notifications run on a blocking thread after all state locks
are released; at most one refresh is in flight and duplicate SIGHUPs
merge into one trailing run. Stable `yy: fuse refresh:` lines report the
revision, reclaimed/active counts and native notification counts, and a
send failure after unmount ends the refresh without retrying. Positive
LOOKUP results and READDIR entries are recorded; negative lookups carry
no timeout and are not recorded.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: format refresh diagnostics without Display impls
Errno and NodeId do not implement Display; use their Debug forms in the
refresh log lines.
Co-authored-by: Chojan Shang <ps...@apache.org>
* refactor: track the SIGHUP loop inside teardown
Register the SIGHUP handler synchronously before the mount becomes
visible, then run one signal-driven loop as a tracked Tokio task instead
of detached refresh flags. The stream coalesces duplicate requests while
a refresh runs. Teardown sends the loop a stop signal and waits for the
session join and the refresh task under the same five-second grace, so
the CLI deadline really bounds both; an executing refresh may finish
inside the window.
Notification error handling matches the binding: fuser send_inval
already accepts ENOENT, so only explicit connection-ended errnos
(ENODEV/ENOTCONN/EPIPE/ECONNRESET/ESHUTDOWN) stop the batch and other
failures are counted and skipped. Log lines count sent/acceptance of
invalidations, not proof the kernel still cached the inode. Dentry
recording covers positive LOOKUP replies only: plain READDIR does not
install dentries without READDIRPLUS, and the comment and spec say so.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: add the connection-ended errno classifier
The refresh loop referenced is_connection_ended without defining it.
Co-authored-by: Chojan Shang <ps...@apache.org>
* build: record the Linux libc dependency in the lockfile
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: avoid re-polling the session handle during teardown
The select already completed the session JoinHandle on the external
unmount path; awaiting it again in the bounded finalize panicked, and an
early `?` on that result would have skipped refresh cleanup. Keep the
select result as an option, await the session only when the signal path
ran, always await the refresh task, and propagate both results after
both waits. The SIGHUP loop checks its stop signal first and exits if
the signal stream closes.
Co-authored-by: Chojan Shang <ps...@apache.org>
* fix: cover both teardown owners in the expiry diagnostic
The grace period also bounds the tracked refresh task, which can be
inside remote I/O independently of client references. Report the session
or refresh task instead of claiming only open references.
Co-authored-by: Chojan Shang <ps...@apache.org>
---------
Co-authored-by: Chojan Shang <ps...@apache.org>
---
Cargo.lock | 203 +++++++
Cargo.toml | 14 +-
crates/core/src/transaction.rs | 2 +-
specs/README.md | 1 +
specs/linux-fuse.md | 204 +++++++
specs/volume-capabilities.md | 22 +-
src/file_cli.rs | 25 +-
src/fuse/attrs.rs | 86 +++
src/fuse/frontend.rs | 1230 ++++++++++++++++++++++++++++++++++++++++
src/fuse/inode.rs | 199 +++++++
src/fuse/mod.rs | 288 ++++++++++
src/lib.rs | 2 +
src/main.rs | 22 +-
src/volume.rs | 89 ++-
tests/volume.rs | 42 ++
15 files changed, 2391 insertions(+), 38 deletions(-)
diff --git a/Cargo.lock b/Cargo.lock
index 8ced4f9..25e57af 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -80,6 +80,12 @@ version = "1.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
[[package]]
name = "aws-lc-rs"
version = "1.18.1"
@@ -525,6 +531,26 @@ version = "1.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+[[package]]
+name = "fuser"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80a5eca878900c2e39e9e52fd797954b7fc39eeefc8558257114bfea6a698fcf"
+dependencies = [
+ "bitflags 2.13.2",
+ "libc",
+ "log",
+ "memchr",
+ "nix",
+ "num_enum",
+ "page_size",
+ "parking_lot",
+ "pkg-config",
+ "ref-cast",
+ "smallvec",
+ "zerocopy",
+]
+
[[package]]
name = "futures"
version = "0.3.34"
@@ -1075,6 +1101,15 @@ version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
[[package]]
name = "log"
version = "0.4.34"
@@ -1113,6 +1148,15 @@ version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
[[package]]
name = "mio"
version = "1.2.3"
@@ -1124,6 +1168,41 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "nix"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
+dependencies = [
+ "bitflags 2.13.2",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+ "memoffset",
+]
+
+[[package]]
+name = "num_enum"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26"
+dependencies = [
+ "num_enum_derive",
+ "rustversion",
+]
+
+[[package]]
+name = "num_enum_derive"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
[[package]]
name = "once_cell"
version = "1.21.4"
@@ -1224,6 +1303,39 @@ dependencies = [
"hashbrown 0.14.5",
]
+[[package]]
+name = "page_size"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d5b2194ed13191c1999ae0704b7839fb18384fa22e49b57eeaa97d79ce40da"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
[[package]]
name = "percent-encoding"
version = "2.3.2"
@@ -1392,6 +1504,35 @@ dependencies = [
"rand_core",
]
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags 2.13.2",
+]
+
+[[package]]
+name = "ref-cast"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
[[package]]
name = "reqsign-aws-core"
version = "3.1.1"
@@ -1669,6 +1810,12 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
[[package]]
name = "security-framework"
version = "3.7.0"
@@ -1781,6 +1928,16 @@ version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
[[package]]
name = "simd_cesu8"
version = "1.2.0"
@@ -1962,6 +2119,7 @@ dependencies = [
"libc",
"mio",
"pin-project-lite",
+ "signal-hook-registry",
"socket2",
"tokio-macros",
"windows-sys 0.61.2",
@@ -2313,6 +2471,22 @@ dependencies = [
"libc",
]
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
[[package]]
name = "winapi-util"
version = "0.1.11"
@@ -2322,6 +2496,12 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
[[package]]
name = "windows-link"
version = "0.2.1"
@@ -2440,6 +2620,9 @@ dependencies = [
"blake3",
"borsh",
"clap",
+ "fuser",
+ "libc",
+ "nix",
"opendal",
"rusqlite",
"serde",
@@ -2502,6 +2685,26 @@ dependencies = [
"synstructure",
]
+[[package]]
+name = "zerocopy"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.63"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
[[package]]
name = "zerofrom"
version = "0.1.8"
diff --git a/Cargo.toml b/Cargo.toml
index 31cfe71..89537da 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -43,10 +43,22 @@ rusqlite = { version = "0.40.2", default-features = false, features = ["bundled"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tempfile = "3"
-tokio = { workspace = true, features = ["fs", "macros", "rt-multi-thread", "sync"] }
+tokio = { workspace = true, features = [
+ "fs",
+ "macros",
+ "rt-multi-thread",
+ "signal",
+ "sync",
+ "time",
+] }
uuid.workspace = true
yinyang-core = { path = "crates/core" }
+[target.'cfg(target_os = "linux")'.dependencies]
+fuser = "0.17.0"
+libc = "0.2"
+nix = { version = "0.30.0", features = ["user"] }
+
[workspace]
members = [".", "crates/core", "crates/native", "xtask"]
resolver = "3"
diff --git a/crates/core/src/transaction.rs b/crates/core/src/transaction.rs
index d19664c..3e88268 100644
--- a/crates/core/src/transaction.rs
+++ b/crates/core/src/transaction.rs
@@ -331,7 +331,7 @@ impl Transaction {
id: NodeId::from_bytes(node),
parent: NodeId::from_bytes(parent),
name,
- file: file.map(&find).transpose()?,
+ file: file.map(find).transpose()?,
executable,
}
}
diff --git a/specs/README.md b/specs/README.md
index 7d2ff38..a7c6837 100644
--- a/specs/README.md
+++ b/specs/README.md
@@ -14,6 +14,7 @@ This directory contains the maintained contracts for Apache OpenDALâ„¢ YinYang.
| [Native bridge](native-bridge.md) | In-process ownership and private adapter request semantics. |
| [Experimental macOS frontends](macos-frontends.md) | Native FSKit and File Provider integration boundaries. |
| [Volume capabilities](volume-capabilities.md) | Configuration, four-layer admission, read-only enforcement, and CLI status. |
+| [Linux FUSE frontend](linux-fuse.md) | Read-only Managed mount: FUSE binding, inode mapping, pinned handles, directory cursors, and teardown. |
| [Transactional filesystem](transactional-filesystem.md) | Shared target contract. Object-storage and metadata-service bindings implemented experimentally. |
A specification describes the currently supported behavior, APIs, wire formats,
diff --git a/specs/linux-fuse.md b/specs/linux-fuse.md
new file mode 100644
index 0000000..ea8024b
--- /dev/null
+++ b/specs/linux-fuse.md
@@ -0,0 +1,204 @@
+# Read-only Linux FUSE frontend
+
+**Status: experimental read-only Managed mount; protocol transport is the
+`fuser` 0.17 binding, not a YinYang FUSE implementation.**
+
+The Linux frontend mounts one Managed volume through the kernel FUSE ABI with
+`yy --volume CONFIG mount MOUNTPOINT` and keeps the process in the foreground.
+It uses the shared Authority, Mount and Runtime contracts directly; it never
+initializes or reformats remote storage. The macOS bridge crate is not part of
+the Linux path.
+
+## Startup and admission
+
+The volume configuration must declare `model = "managed"`, `access = "mount"`,
+`frontend = "fuse"` and `read_only = true`. The shared admission rules in
+[`volume-capabilities.md`](volume-capabilities.md) reject every other
+combination before an authority connection or staging lease exists, and reject
+the FUSE frontend entirely on non-Linux targets. Object and service publication
+authorities are both accepted through `Volume::connect`.
+
+Startup order:
+
+1. validate the configuration and the storage capability intersection;
+2. connect the object or service authority;
+3. open the shared [`Mount`](mount-runtime.md) read-only (acquires the staging
+ lease and runs the existing recovery);
+4. inspect the recovered runtime status and refuse the mount if any handle is
+ pending, frozen, conflicted or failed;
+5. observe the latest remote snapshot and verify the root is a directory;
+6. handshake with the kernel as `fuse.yinyang` and serve requests.
+
+Step 4 is the read-only dirty-data boundary. Recovered clean observations are
+disposable and reclaimed by existing Mount recovery, while unpublished staged
+bytes are never exposed as a remote snapshot: the mount fails with a
+diagnostic naming the handle instead. The lease is already held during the
+inspection, so another client cannot interleave. Refusing startup changes no
+remote state.
+
+The mount is owner-only (`SessionACL::Owner`) and advertised as `ro` with
+`fsname=yinyang-<name>` and `subtype=yinyang`, so the kernel reports
+`fuse.yinyang` as the filesystem type.
+
+## Identity and lookup references
+
+Inode numbers are deterministic functions of the core `NodeId`: the root is
+always 1 and every other node derives a 64-bit value from a domain-separated
+BLAKE3 digest of its identity, so numbers are stable across mounts and
+restarts. A derivation that collides with the root, zero, or an already mapped
+identity is an error (`EIO`) rather than an alias. The NodeId-inode map and the
+observed kind/executable cache live for the mount lifetime; memory is
+proportional to the visited tree, the same boundary as the macOS prototype.
+
+Each successful `LOOKUP` reply adds one kernel reference. `forget` subtracts
+the reported count with saturating arithmetic. Mappings are retained after the
+count reaches zero so a later deterministic lookup cannot change numbers; the
+counters exist for a future eviction layer. FUSE reply generations are 0;
+kernel NFS export is not supported.
+
+## Attributes and pinned file handles
+
+Filesystem callbacks that can touch the authority or staging dispatch onto the
+process Tokio runtime, moving the reply into the task; the binding sends one
+reply per request and replaces a dropped unanswered reply with `EIO`.
+
+`lookup` and non-handle `getattr` observe the latest snapshot for metadata and
+use that same snapshot's revision for timestamps, so a reply never mixes
+metadata from two observations. Attributes are synthesized: directories
+`0555`, files `0444` (readable plus the core executable bit), the mounting
+user's uid/gid, size from the content descriptor or a fixed directory size,
+and timestamps encoding the revision sequence rather than wall-clock time.
+`getxattr`, `listxattr`, `readlink` and options outside the read-only contract
+return explicit errors; mutations return `EROFS`.
+
+`open` requires a read-only access mode, rejects cached directories with
+`EISDIR`, and takes one reference on the node's shared staged version through
+`Mount::open_node`. The reply opens with `FOPEN_DIRECT_IO`, so the kernel does
+not cache file pages. Reads stream from the staged version. `getattr` with an
+open handle reports the staged record's length, so `fstat` and read bytes
+always describe the same pinned version even when the remote side changed;
+`release` drops the reference and then reclaims a clean node, so the next open
+materializes the current remote revision. A release whose reclaim loses to an
+interrupted read leaves a clean references-zero record; `open` reclaims such a
+record before materializing, so a fresh open still observes the current
+revision instead of reusing the stale clean snapshot.
+
+A clean node is only reclaimed when its last adapter reference is released. If
+an interrupted read still shares the node, reclaim reports busy and the pinned
+version remains coherent until a later release becomes the final reference;
+that open's metadata and content never disagree. The frontend does not call
+`Mount::refresh` while references exist, because refresh rebases live handles;
+a writable layer that in-place refreshes must first define its open-fd and
+kernel-cache invalidation policy.
+
+## Explicit refresh
+
+`SIGHUP` triggers one explicit refresh; this is a manual invalidation entry
+point, not an automatic change watch. There is no background polling, no
+change-feed watcher, and no whole-tree enumeration. The refresh observes the
+latest snapshot once and then:
+
+- reclaims every clean, unreferenced node through the shared `Mount` contract,
+ so the next open materializes the current remote revision; nodes with live
+ references or retained state are left pinned (`Busy`);
+- invalidates known inode attributes with `inval_inode(ino, -1, 0)` and
+ replied dentries with `inval_entry(parent, name)` through the fuser
+ `Notifier`. Only dentries this adapter actually replied to the kernel are
+ recorded: successful `LOOKUP` results. Negative lookups carry no timeout in
+ FUSE replies and are not recorded, and plain `READDIR` does not install
+ dentries without `READDIRPLUS`, so directory names are not recorded.
+
+The adapter never calls `Mount::refresh`, because that replaces the shared
+staged handle and would rebase open file descriptors. The refresh must also
+hold no adapter lock while reclaiming nodes or sending notifications; targets
+are collected under short locks, then the sends run on a blocking thread. At
+most one refresh runs at a time and duplicate `SIGHUP`s while one is running
+are coalesced by the signal stream. The SIGHUP loop is a tracked Tokio task:
+the signal handler is registered synchronously before the mount becomes
+visible, teardown sends it a stop signal, and the session join and the refresh
+task share the same five-second grace period; a refresh already in progress
+may finish inside that window. A `NotFound` notification result is expected
+(the kernel already dropped the entry or inode) and is counted separately, so
+only explicit connection-ended errors (`ENODEV`, `ENOTCONN`, `EPIPE`,
+`ECONNRESET`, `ESHUTDOWN`) stop the batch before it would otherwise finish.
+
+Stable `yy: fuse refresh:` log lines report the observed revision, the
+reclaimed/active node counts, and the native notification counts at
+completion, so an acceptance harness can confirm a refresh finished.
+
+## Pinned directory cursors
+
+`opendir` pins one `Snapshot` revision and one directory identity. `readdir`
+fills the kernel buffer from stable ordinal offsets: `.` at 1, `..` at 2, then
+recorded entries in the snapshot's ordered scan, with each entry's returned
+offset being the next ordinal. Pages of 512 entries are fetched lazily through
+`Snapshot::scan` with the continuation bound to the pinned revision. Offset 0
+rewinds the same pinned enumeration; a handle never silently switches to a
+newer snapshot. Cursor state is serialized per open directory handle, and no
+mount-wide lock spans a page scan or per-entry metadata read.
+
+Each entry's inode and kind need the entry node's metadata; the frontend caches
+observed kinds per NodeId, so listing a directory again after its children
+were looked up does not re-read every node record. A fresh large listing still
+performs one metadata read per entry plus small ordered pages; batched
+metadata reads are a future optimization, not a completeness requirement.
+
+## statfs, capacity and errors
+
+`statfs` reports zero blocks, zero files and `bsize=4096` with `namelen=255`.
+A remote snapshot implies no local capacity claim. Core and runtime failures
+map to the narrow errno intended for each operation; unknown identity is
+`ESTALE`, read-only violations `EROFS`, unsupported operations `ENOSYS` or
+`EOPNOTSUPP`, and every other failure class degrades to `EIO` without guessing.
+
+## Cancellation and exit
+
+The binding answers `FUSE_INTERRUPT` with `ENOSYS` (fuser 0.17
+`src/request.rs`), so an interrupted syscall does not cancel in-flight remote
+work. The Linux kernel waits out every request already delivered to the daemon
+(`fs/fuse/dev.c` `request_wait_answer`): a client terminated by a fatal signal
+while its request is in userspace stays in an uninterruptible wait until the
+reply arrives or the connection aborts, and only a request that was never
+delivered can be dropped with `-EINTR`. The daemon therefore replies to every
+request exactly once, and daemon termination is the abort guarantee: closing
+`/dev/fuse` makes the kernel end pending requests with `-ECONNABORTED`
+(`fuse_dev_release` -> `fuse_abort_conn`).
+
+The session runs in the foreground. Teardown waits on both the session end and
+SIGINT/SIGTERM: an external `fusermount3 -u` ends the session loop and the
+process exits on its own, while a signal detaches the mount and waits up to a
+five-second grace period. `Session::spawn` moves the mount object into
+`BackgroundSession`, so a `SessionUnmounter` obtained before spawning would
+find an empty slot; one blocking owner holds the background session, polls its
+public thread guard for a natural end, and receives the local teardown
+request. Exactly one `join` or `umount_and_join` runs. A lazy unmount does not
+end the kernel connection while clients still hold open references or in-flight
+requests, so when the grace period expires the mount entry returns an explicit
+teardown-expired outcome instead of returning into a runtime shutdown that
+would wait for the blocked session task. The CLI prints a diagnostic to stderr
+and exits non-zero; the process exit closes `/dev/fuse`, the kernel aborts the
+connection, and every blocked client syscall returns an error instead of
+hanging. Forced termination is a crash-equivalent recovery boundary, not a
+graceful unmount: the staging lease is released by the OS and the next start
+recovers local state through the normal crash-recovery path. Request tasks are
+detached and owned by the CLI runtime; their unanswered replies are dropped on
+the closing channel. In-flight tasks hold their `Arc<Mount>` for that window;
+there is no mid-session cancellation signal.
+
+## Boundaries and known limits
+
+- Every open materializes the complete file through the existing shared Mount
+ staging contract; there is no partial-download or mmap coherence claim, and
+ `FOPEN_DIRECT_IO` does not provide page-cache-backed mmap behavior.
+- Writes, create, mkdir, unlink, rename, links, xattrs, ioctl, poll, locking
+ and capacity accounting are not implemented; the kernel read-only mount and
+ the callback errno policy reject them.
+- The module keeps existing core Mount behavior, including the node-map lock
+ that already spans first materialization; the adapter adds no mount-wide
+ lock across authority or staging I/O.
+- The session `Notifier` is used only by the explicit `SIGHUP` refresh above;
+ there is no automatic external-change watch, and its capability set does
+ not claim recoverable staging or any write-side operation beyond the
+ read-only contract. Remaining extension points for the next layer are the
+ runtime namespace operations and `Mount::refresh` guarded by reference
+ counts.
diff --git a/specs/volume-capabilities.md b/specs/volume-capabilities.md
index 87328f5..d4e32aa 100644
--- a/specs/volume-capabilities.md
+++ b/specs/volume-capabilities.md
@@ -1,9 +1,11 @@
# Volume admission and capabilities
-**Status: experimental Managed volume, Mount durability policy, library frontend.**
-This is a headless runtime/CLI combination, not an OS mount. Direct, Sync
-reconciliation, FUSE, macOS, and Windows frontends are recognized configuration
-choices but are rejected as unimplemented before startup.
+**Status: experimental Managed volume, Mount durability policy, library and
+read-only Linux FUSE frontends.**
+Direct, Sync reconciliation, writable FUSE, macOS, and Windows frontends are
+recognized configuration choices but are rejected as unimplemented before
+startup. The read-only Linux FUSE frontend is specified separately in
+[`linux-fuse.md`](linux-fuse.md).
## Configuration
@@ -38,6 +40,9 @@ The config contains no service secret or storage credentials.
`access=mount` selects online remote-fsync semantics. `frontend=library`
executes these semantics through Runtime/FileHandle and the CLI without
installing a mount point. It does not claim an OS frontend or offline Sync.
+`frontend=fuse` requires Linux and `read_only=true`; the mount command hands
+the same validated configuration to the Linux FUSE frontend, which adds its
+own staged-state admission before serving reads.
## Negotiation and enforcement
@@ -48,6 +53,14 @@ The effective capability set is the intersection of:
3. the access model and read-only policy;
4. the implemented frontend.
+Startup also requires the intersection of the volume, access, and frontend
+contracts (the combination baseline) to survive the storage intersection, so a
+frontend cannot silently weaken the model. The library frontend claims the full
+implemented runtime set. The Linux FUSE frontend claims read, list,
+stable-identity, pinned-reads, and retained-unlink-read; its read-only mount
+does not claim recoverable staging or any write-side operation. Every other
+frontend claims an empty set and is rejected by its own admission rule.
+
The storage layer reports whether its primitives can support the Managed
contract. It does not require raw S3 to implement filesystem rename. Read,
immutable streaming writes, and conditional creation are required for content;
@@ -78,6 +91,7 @@ Initialize an object authority with the existing `yy create`, or a service
authority with `yy serve --database metadata.db`. Then:
```shell
+yy --volume volume.json mount /mnt/workspace
yy --volume volume.json capabilities
yy --volume volume.json file create hello
yy --volume volume.json file open hello --write
diff --git a/src/file_cli.rs b/src/file_cli.rs
index faa7cf3..ca080ad 100644
--- a/src/file_cli.rs
+++ b/src/file_cli.rs
@@ -178,8 +178,31 @@ pub async fn run(path: &Path, command: Command) -> Result<(), Box<dyn std::error
);
return Ok(());
}
+ if let Command::Mount { mountpoint } = command {
+ #[cfg(target_os = "linux")]
+ {
+ return match yinyang::fuse::run(config, operator, token, mountpoint).await? {
+ yinyang::fuse::Outcome::Unmounted => Ok(()),
+ yinyang::fuse::Outcome::TeardownExpired { grace } => {
+ eprintln!(
+ "yy: FUSE mount did not finish teardown within {}s (the session or the \
+ refresh task is still running, for example clients holding references or a \
+ refresh blocked on remote I/O); exiting non-zero to abort the connection \
+ (equivalent to crash recovery)",
+ grace.as_secs()
+ );
+ std::process::exit(1);
+ }
+ };
+ }
+ #[cfg(not(target_os = "linux"))]
+ {
+ let _ = (operator, token, mountpoint);
+ return Err("the fuse frontend is implemented only on Linux".into());
+ }
+ }
let Command::File { command } = command else {
- return Err("with --volume use file, capabilities, receipt, or status; initialize object storage with yy create or service storage with yy serve".into());
+ return Err("with --volume use mount, file, capabilities, receipt, or status; initialize object storage with yy create or service storage with yy serve".into());
};
let volume = Volume::open(config, operator, token).await?;
let runtime = volume.runtime();
diff --git a/src/fuse/attrs.rs b/src/fuse/attrs.rs
new file mode 100644
index 0000000..356bfe1
--- /dev/null
+++ b/src/fuse/attrs.rs
@@ -0,0 +1,86 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Synthesized FUSE attributes for the YinYang metadata model.
+
+use fuser::{FileAttr, FileType};
+use std::time::{Duration, SystemTime};
+use yinyang_core::Revision;
+
+/// Short kernel attribute lifetime. This frontend re-observes the authority
+/// on demand; a one-second window keeps `stat` churn low without pretending
+/// that a longer-lived kernel cache is a coherent remote snapshot.
+pub const ATTR_TTL: Duration = Duration::from_secs(1);
+
+/// Directory size reported to `stat`; the core stores no directory payload.
+pub const DIRECTORY_SIZE: u64 = 4096;
+
+/// Fixed offset makes revision-derived stamps readable without claiming that
+/// they are wall-clock times.
+const STAMP_EPOCH: u64 = 1_600_000_000;
+
+/// Build attributes for an immutable observation. `size` must come from the
+/// same version as `revision`; handles and snapshots both satisfy that rule.
+pub fn attribute(
+ ino: fuser::INodeNo,
+ directory: bool,
+ executable: bool,
+ size: u64,
+ revision: Revision,
+) -> FileAttr {
+ let (uid, gid) = mount_owner();
+ let stamp = SystemTime::UNIX_EPOCH
+ + Duration::from_secs(
+ STAMP_EPOCH
+ + u64::from_be_bytes(
+ revision.to_bytes()[..8]
+ .try_into()
+ .expect("revision sequence prefix"),
+ ),
+ );
+ let perm = if directory || executable {
+ 0o555
+ } else {
+ 0o444
+ };
+ FileAttr {
+ ino,
+ size,
+ blocks: size.div_ceil(512),
+ atime: stamp,
+ mtime: stamp,
+ ctime: stamp,
+ crtime: stamp,
+ kind: if directory {
+ FileType::Directory
+ } else {
+ FileType::RegularFile
+ },
+ perm,
+ nlink: if directory { 2 } else { 1 },
+ uid,
+ gid,
+ rdev: 0,
+ blksize: 4096,
+ flags: 0,
+ }
+}
+
+fn mount_owner() -> (u32, u32) {
+ use nix::unistd::{getegid, geteuid};
+ (geteuid().as_raw(), getegid().as_raw())
+}
diff --git a/src/fuse/frontend.rs b/src/fuse/frontend.rs
new file mode 100644
index 0000000..239982b
--- /dev/null
+++ b/src/fuse/frontend.rs
@@ -0,0 +1,1230 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Read-only Linux FUSE frontend over the shared Mount staging contract.
+//!
+//! `fuser` owns the FUSE device, session loop and reply wire encoding; this
+//! module implements only the filesystem callbacks. Every callback that can
+//! perform remote I/O dispatches onto the process Tokio runtime and moves its
+//! reply into the task, so one reply is sent per request and no adapter-wide
+//! lock is held across an authority or staging await. Input buffers borrowed
+//! from the request are converted to owned values before the dispatch, and
+//! the low-level binding replies EIO if a task drops an unanswered reply.
+//!
+//! Files pin the node's shared staged version. `fstat` on an open handle uses
+//! that staged record's length, and reads return staged bytes, so an old
+//! descriptor never mixes a newer remote length with older content. `release`
+//! reclaims a clean shared node, and `open` first reclaims any clean record a
+//! raced release left behind, so a fresh open observes the current remote
+//! revision without rebasing live handles. Directory handles
+//! pin one `Snapshot` revision; readdir offsets are stable ordinal positions
+//! over pages of that pinned listing.
+//!
+//! The binding replies ENOSYS to FUSE_INTERRUPT, which the kernel ignores;
+//! an interrupted syscall therefore does not cancel in-flight remote work.
+//! Each operation still replies exactly once. Request tasks are detached and
+//! owned by the process Tokio runtime: ending the FUSE session does not abort
+//! them, and a reply written after unmount fails on the closing channel. The
+//! CLI returns after session teardown, so the runtime shutdown at process
+//! exit is the actual point where remaining tasks are dropped.
+
+use super::attrs::{ATTR_TTL, DIRECTORY_SIZE, attribute};
+use super::inode::{CachedInfo, InodeTable};
+use crate::mount::{Mount, MountFile};
+use fuser::{
+ AccessFlags, BsdFileFlags, FileAttr, FileHandle, FileType, Filesystem, FopenFlags, Generation,
+ INodeNo, InitFlags, KernelConfig, LockOwner, Notifier, OpenAccMode, OpenFlags, ReplyAttr,
+ ReplyData, ReplyDirectory, ReplyEmpty, ReplyEntry, ReplyOpen, ReplyStatfs, ReplyWrite,
+ ReplyXattr, Request, TimeOrNow, WriteFlags,
+};
+use std::collections::{BTreeMap, BTreeSet};
+use std::ffi::OsStr;
+use std::future::Future;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::SystemTime;
+use tokio::runtime::Handle;
+use tokio::sync::Mutex as AsyncMutex;
+use yinyang_core::{NodeId, ScanToken, Snapshot};
+
+/// Entries fetched per pinned directory scan.
+const READDIR_PAGE: usize = 512;
+
+pub(super) struct Inner {
+ mount: Mount,
+ inodes: Mutex<InodeTable>,
+ files: Mutex<BTreeMap<u64, Arc<OpenFile>>>,
+ dirs: Mutex<BTreeMap<u64, Arc<AsyncMutex<DirCursor>>>>,
+ /// Dentry names this adapter actually replied to the kernel; only those
+ /// can be cached and invalidated by an explicit refresh.
+ dentries: Mutex<BTreeSet<(u64, String)>>,
+ notifier: Mutex<Option<Notifier>>,
+ next_handle: AtomicU64,
+ runtime: Handle,
+}
+
+/// One kernel open maps to one reference on the node's shared staged version.
+struct OpenFile {
+ node: NodeId,
+ file: MountFile,
+ /// Metadata from the exact observation the staged version was
+ /// materialized from, so path stats and fstat agree with read bytes.
+ base: CachedInfo,
+}
+
+#[derive(Clone)]
+struct DirItem {
+ ino: INodeNo,
+ kind: FileType,
+ name: String,
+}
+
+/// A pinned directory enumeration. Cursor state is serialized per open handle;
+/// no mount-wide lock spans the page scans or per-entry metadata reads.
+struct DirCursor {
+ snapshot: Snapshot,
+ ino: INodeNo,
+ directory: NodeId,
+ parent_ino: INodeNo,
+ entries: Vec<DirItem>,
+ token: Option<ScanToken>,
+ complete: bool,
+}
+
+impl Inner {
+ pub(super) fn new(mount: Mount, runtime: Handle) -> Self {
+ let root = mount.authority().root();
+ Self {
+ mount,
+ inodes: Mutex::new(InodeTable::new(root)),
+ files: Mutex::new(BTreeMap::new()),
+ dirs: Mutex::new(BTreeMap::new()),
+ dentries: Mutex::new(BTreeSet::new()),
+ notifier: Mutex::new(None),
+ next_handle: AtomicU64::new(0),
+ runtime,
+ }
+ }
+
+ fn spawn(&self, future: impl Future<Output = ()> + Send + 'static) {
+ self.runtime.spawn(future);
+ }
+
+ fn next_handle(&self) -> u64 {
+ self.next_handle.fetch_add(1, Ordering::Relaxed) + 1
+ }
+
+ /// Install the kernel notification handle once the session is spawned.
+ pub(super) fn install_notifier(&self, notifier: Notifier) {
+ guard(&self.notifier).replace(notifier);
+ }
+
+ /// Remember a dentry this adapter replied to the kernel.
+ fn record_dentry(&self, parent: INodeNo, name: &str) {
+ guard(&self.dentries).insert((parent.0, name.to_owned()));
+ }
+
+ /// Serve explicit refresh requests. The signal stream was registered
+ /// before the mount became visible; SIGHUPs arriving while a refresh runs
+ /// are coalesced by the stream, and `stop` ends the loop so the caller can
+ /// bound the task with the session teardown deadline.
+ pub(super) async fn serve_hup(
+ self: Arc<Self>,
+ mut signal: tokio::signal::unix::Signal,
+ mut stop: tokio::sync::oneshot::Receiver<()>,
+ ) {
+ loop {
+ tokio::select! {
+ biased;
+ _ = &mut stop => return,
+ event = signal.recv() => match event {
+ Some(()) => self.refresh_once().await,
+ // The signal stream cannot be re-established; stop rather
+ // than spin on a closed stream.
+ None => return,
+ },
+ }
+ }
+ }
+
+ /// One explicit refresh: re-observe latest, reclaim clean unreferenced
+ /// nodes, and invalidate known inode attributes and replied dentries.
+ async fn refresh_once(&self) {
+ let snapshot = match self.observe().await {
+ Ok(snapshot) => snapshot,
+ Err(errno) => {
+ eprintln!("yy: fuse refresh: cannot observe latest: {errno:?}");
+ return;
+ }
+ };
+ let revision = revision_hex(snapshot.revision());
+ let inodes = { guard(&self.inodes).inodes() };
+ let dentries = { guard(&self.dentries).iter().cloned().collect::<Vec<_>>() };
+ eprintln!(
+ "yy: fuse refresh: revision {revision} over {} inodes and {} dentries",
+ inodes.len(),
+ dentries.len()
+ );
+ let (mut reclaimed, mut active, mut failures) = (0usize, 0usize, 0usize);
+ for inode in &inodes {
+ let Some(id) = self.node(INodeNo(*inode)) else {
+ continue;
+ };
+ // Busy means live references or retained state: keep the pinned
+ // version. Mount::refresh is never used here because it rebases
+ // live open handles.
+ match self.mount.reclaim(id).await {
+ Ok(()) => reclaimed += 1,
+ Err(error) if error.kind() == crate::runtime::ErrorKind::Busy => active += 1,
+ Err(error) => {
+ failures += 1;
+ eprintln!("yy: fuse refresh: reclaim {id:?}: {error}");
+ }
+ }
+ }
+ eprintln!(
+ "yy: fuse refresh: reclaimed {reclaimed} clean nodes ({active} active, {failures} failed)"
+ );
+ let Some(notifier) = guard(&self.notifier).clone() else {
+ eprintln!("yy: fuse refresh: notifier not installed; skipping kernel invalidation");
+ return;
+ };
+ // fuser's send_inval already treats NotFound/ENOENT as an accepted
+ // notification, so Ok below means the kernel accepted the send, not
+ // that the inode or entry was still cached. Only explicit
+ // connection-ended errors stop the batch; other failures are counted
+ // and skipped so one vanished inode cannot abort the whole refresh.
+ let attempts = inodes.len() + dentries.len();
+ let (inode_ok, entry_ok, errors, ended) = tokio::task::spawn_blocking(move || {
+ let mut inode_ok = 0usize;
+ let mut entry_ok = 0usize;
+ let mut errors = 0usize;
+ let mut ended = false;
+ for inode in inodes.iter() {
+ match notifier.inval_inode(INodeNo(*inode), -1, 0) {
+ Ok(()) => inode_ok += 1,
+ Err(error) if is_connection_ended(&error) => {
+ // The session is gone; stop instead of spamming.
+ errors += 1;
+ ended = true;
+ return (inode_ok, entry_ok, errors, ended);
+ }
+ Err(_) => errors += 1,
+ }
+ }
+ for (parent, name) in dentries.iter() {
+ match notifier.inval_entry(INodeNo(*parent), OsStr::new(name)) {
+ Ok(()) => entry_ok += 1,
+ Err(error) if is_connection_ended(&error) => {
+ errors += 1;
+ ended = true;
+ return (inode_ok, entry_ok, errors, ended);
+ }
+ Err(_) => errors += 1,
+ }
+ }
+ (inode_ok, entry_ok, errors, ended)
+ })
+ .await
+ .unwrap_or((0, 0, attempts, false));
+ if ended {
+ eprintln!(
+ "yy: fuse refresh: channel ended; sent {inode_ok} inode and {entry_ok} entry invalidations before {errors} errors"
+ );
+ } else {
+ eprintln!(
+ "yy: fuse refresh: done (inode={inode_ok} entries={entry_ok} errors={errors})"
+ );
+ }
+ }
+
+ fn inode_for(&self, id: NodeId, info: Option<CachedInfo>) -> Result<INodeNo, fuser::Errno> {
+ let mut inodes = guard(&self.inodes);
+ if let Some(info) = info {
+ inodes.cache(id, info);
+ }
+ inodes.inode(id).map(INodeNo).map_err(|_| fuser::Errno::EIO)
+ }
+
+ fn node(&self, ino: INodeNo) -> Option<NodeId> {
+ guard(&self.inodes).node(ino.0)
+ }
+
+ fn remember_lookup(&self, ino: INodeNo) {
+ guard(&self.inodes).remember_lookup(ino.0);
+ }
+
+ fn forget(&self, ino: INodeNo, count: u64) {
+ guard(&self.inodes).forget(ino.0, count);
+ }
+
+ fn open_file(&self, fh: FileHandle) -> Option<Arc<OpenFile>> {
+ guard(&self.files).get(&fh.0).cloned()
+ }
+
+ /// Any active open for a node. `Mount::open_node` reuses the node's shared
+ /// staged version, so all handles for one node report the same base.
+ fn open_for_node(&self, id: NodeId) -> Option<Arc<OpenFile>> {
+ guard(&self.files)
+ .values()
+ .find(|open| open.node == id)
+ .cloned()
+ }
+
+ fn dir_cursor(&self, fh: FileHandle) -> Option<Arc<AsyncMutex<DirCursor>>> {
+ guard(&self.dirs).get(&fh.0).cloned()
+ }
+
+ async fn observe(&self) -> Result<Snapshot, fuser::Errno> {
+ self.mount
+ .authority()
+ .observe_latest()
+ .await
+ .map_err(|e| core_errno(&e))
+ }
+
+ /// Attributes and size from one pinned observation.
+ async fn snapshot_attr(
+ &self,
+ snapshot: &Snapshot,
+ id: NodeId,
+ ) -> Result<FileAttr, fuser::Errno> {
+ let node = snapshot
+ .node(id)
+ .await
+ .map_err(|e| core_errno(&e))?
+ .ok_or(fuser::Errno::ENOENT)?;
+ let info = CachedInfo {
+ directory: node.is_directory(),
+ executable: node.executable(),
+ generation: node.generation(),
+ };
+ let ino = self.inode_for(id, Some(info))?;
+ let size = match node.kind() {
+ yinyang_core::NodeKind::File(content) => content.content_id().length(),
+ yinyang_core::NodeKind::Directory { .. } => DIRECTORY_SIZE,
+ };
+ Ok(attribute(
+ ino,
+ info.directory,
+ info.executable,
+ size,
+ snapshot.revision(),
+ ))
+ }
+
+ /// Attributes for an open handle: the staged length and the base
+ /// observation are authoritative, so `fstat`, path stats and read bytes
+ /// describe the same pinned version.
+ async fn handle_attr(&self, open: &OpenFile) -> Result<FileAttr, fuser::Errno> {
+ let status = open.file.status().await.map_err(|e| runtime_errno(&e))?;
+ let ino = self.inode_for(open.node, None)?;
+ Ok(attribute(
+ ino,
+ open.base.directory,
+ open.base.executable,
+ status.length,
+ status.remote_revision,
+ ))
+ }
+
+ /// Metadata for one inode. While any open handle exists, the staged/base
+ /// version wins over the latest remote observation so the kernel attr
+ /// cache cannot mix an external size with staged bytes for the same inode.
+ async fn attr_for(&self, snapshot: &Snapshot, id: NodeId) -> Result<FileAttr, fuser::Errno> {
+ if let Some(open) = self.open_for_node(id) {
+ self.handle_attr(&open).await
+ } else {
+ self.snapshot_attr(snapshot, id).await
+ }
+ }
+
+ async fn lookup(&self, parent: INodeNo, name: String, reply: ReplyEntry) {
+ let Some(parent_id) = self.node(parent) else {
+ return reply.error(fuser::Errno::ESTALE);
+ };
+ let snapshot = match self.observe().await {
+ Ok(snapshot) => snapshot,
+ Err(errno) => return reply.error(errno),
+ };
+ let entry = match snapshot.lookup(parent_id, &name).await {
+ Ok(Some(entry)) => entry,
+ Ok(None) => return reply.error(fuser::Errno::ENOENT),
+ Err(error) => return reply.error(core_errno(&error)),
+ };
+ // A positive LOOKUP reply may install a kernel dentry; remember it
+ // for the explicit refresh. Negative results carry no timeout and are
+ // skipped, and a plain READDIR does not install positive dentries
+ // (that is READDIRPLUS), so scanned names are not recorded.
+ self.record_dentry(parent, &name);
+ match self.attr_for(&snapshot, entry.node_id).await {
+ Ok(attr) => {
+ self.remember_lookup(attr.ino);
+ reply.entry(&ATTR_TTL, &attr, Generation(0));
+ }
+ Err(errno) => reply.error(errno),
+ }
+ }
+
+ async fn getattr(&self, ino: INodeNo, fh: Option<FileHandle>, reply: ReplyAttr) {
+ if let Some(fh) = fh
+ && let Some(open) = self.open_file(fh)
+ {
+ return match self.handle_attr(&open).await {
+ Ok(attr) => reply.attr(&ATTR_TTL, &attr),
+ Err(errno) => reply.error(errno),
+ };
+ }
+ let Some(id) = self.node(ino) else {
+ return reply.error(fuser::Errno::ESTALE);
+ };
+ let snapshot = match self.observe().await {
+ Ok(snapshot) => snapshot,
+ Err(errno) => return reply.error(errno),
+ };
+ match self.attr_for(&snapshot, id).await {
+ Ok(attr) => reply.attr(&ATTR_TTL, &attr),
+ Err(errno) => reply.error(errno),
+ }
+ }
+
+ async fn open(&self, ino: INodeNo, flags: OpenFlags, reply: ReplyOpen) {
+ if flags.acc_mode() != OpenAccMode::O_RDONLY {
+ return reply.error(fuser::Errno::EROFS);
+ }
+ let Some(id) = self.node(ino) else {
+ return reply.error(fuser::Errno::ESTALE);
+ };
+ if guard(&self.inodes)
+ .cached(id)
+ .is_some_and(|info| info.directory)
+ {
+ return reply.error(fuser::Errno::EISDIR);
+ }
+ match self.prepare_open(id).await {
+ Ok(open) => {
+ let fh = self.next_handle();
+ guard(&self.files).insert(fh, Arc::new(open));
+ reply.opened(FileHandle(fh), FopenFlags::FOPEN_DIRECT_IO);
+ }
+ Err(errno) => reply.error(errno),
+ }
+ }
+
+ /// Materialize the shared staged version and capture its base observation.
+ async fn prepare_open(&self, id: NodeId) -> Result<OpenFile, fuser::Errno> {
+ // A release whose reclaim raced an in-flight read leaves a clean,
+ // references-zero record behind. Reclaim it before materializing so a
+ // fresh open observes the current remote revision; an actively shared
+ // node reports Busy and is reused as before.
+ match self.mount.reclaim(id).await {
+ Ok(()) => {}
+ Err(error) if error.kind() == crate::runtime::ErrorKind::Busy => {}
+ Err(error) => return Err(runtime_errno(&error)),
+ }
+ let file = self
+ .mount
+ .open_node(id, false)
+ .await
+ .map_err(|e| runtime_errno(&e))?;
+ let status = match file.status().await {
+ Ok(status) => status,
+ Err(error) => {
+ drop(file);
+ let _ = self.mount.reclaim(id).await;
+ return Err(runtime_errno(&error));
+ }
+ };
+ let snapshot = match self
+ .mount
+ .authority()
+ .observe_revision(status.remote_revision)
+ .await
+ {
+ Ok(snapshot) => snapshot,
+ Err(error) => {
+ drop(file);
+ let _ = self.mount.reclaim(id).await;
+ return Err(core_errno(&error));
+ }
+ };
+ let node = match snapshot.node(id).await {
+ Ok(Some(node)) => node,
+ Ok(None) => {
+ drop(file);
+ let _ = self.mount.reclaim(id).await;
+ return Err(fuser::Errno::ENOENT);
+ }
+ Err(error) => {
+ drop(file);
+ let _ = self.mount.reclaim(id).await;
+ return Err(core_errno(&error));
+ }
+ };
+ let base = CachedInfo {
+ directory: node.is_directory(),
+ executable: node.executable(),
+ generation: node.generation(),
+ };
+ if base.directory {
+ drop(file);
+ let _ = self.mount.reclaim(id).await;
+ return Err(fuser::Errno::EISDIR);
+ }
+ Ok(OpenFile {
+ node: id,
+ file,
+ base,
+ })
+ }
+
+ async fn read(&self, fh: FileHandle, offset: u64, size: u32, reply: ReplyData) {
+ let Some(open) = self.open_file(fh) else {
+ return reply.error(fuser::Errno::EBADF);
+ };
+ match open.file.read(offset, size as usize).await {
+ Ok(bytes) => reply.data(&bytes),
+ Err(error) => reply.error(runtime_errno(&error)),
+ }
+ }
+
+ async fn release(&self, ino: INodeNo, fh: FileHandle, reply: ReplyEmpty) {
+ let Some(removed) = guard(&self.files).remove(&fh.0) else {
+ return reply.ok();
+ };
+ let node = removed.node;
+ drop(removed);
+ // Reclaim only the last clean reference so the next open materializes
+ // the current remote revision. A busy result means an interrupted read
+ // still shares the node; that pinned version stays coherent and is
+ // reclaimed once a later release is the final reference.
+ if let Err(error) = self.mount.reclaim(node).await
+ && error.kind() != crate::runtime::ErrorKind::Busy
+ {
+ eprintln!("yy: fuse release cleanup inode {ino}: {error}");
+ }
+ reply.ok();
+ }
+
+ async fn opendir(&self, ino: INodeNo, reply: ReplyOpen) {
+ let Some(id) = self.node(ino) else {
+ return reply.error(fuser::Errno::ESTALE);
+ };
+ let snapshot = match self.observe().await {
+ Ok(snapshot) => snapshot,
+ Err(errno) => return reply.error(errno),
+ };
+ let node = match snapshot.node(id).await {
+ Ok(Some(node)) => node,
+ Ok(None) => return reply.error(fuser::Errno::ENOENT),
+ Err(error) => return reply.error(core_errno(&error)),
+ };
+ if !node.is_directory() {
+ return reply.error(fuser::Errno::ENOTDIR);
+ }
+ let parent_ino = match node.link() {
+ Some(link) => match self.inode_for(link.parent, None) {
+ Ok(ino) => ino,
+ Err(errno) => return reply.error(errno),
+ },
+ // The root's "." and ".." both denote itself.
+ None => INodeNo::ROOT,
+ };
+ guard(&self.inodes).cache(
+ id,
+ CachedInfo {
+ directory: true,
+ executable: false,
+ generation: node.generation(),
+ },
+ );
+ let fh = self.next_handle();
+ let cursor = Arc::new(AsyncMutex::new(DirCursor {
+ snapshot,
+ ino,
+ directory: id,
+ parent_ino,
+ entries: Vec::new(),
+ token: None,
+ complete: false,
+ }));
+ guard(&self.dirs).insert(fh, cursor);
+ reply.opened(FileHandle(fh), FopenFlags::empty());
+ }
+
+ async fn readdir(&self, fh: FileHandle, offset: u64, mut reply: ReplyDirectory) {
+ let Some(handle) = self.dir_cursor(fh) else {
+ return reply.error(fuser::Errno::EBADF);
+ };
+ let mut cursor = handle.lock().await;
+ if offset == 0 {
+ cursor.entries.clear();
+ cursor.token = None;
+ cursor.complete = false;
+ }
+ let mut index = offset as usize;
+ let mut added = false;
+ loop {
+ if index == 0 {
+ if reply.add(cursor.ino, 1, FileType::Directory, ".") {
+ break;
+ }
+ added = true;
+ index = 1;
+ continue;
+ }
+ if index == 1 {
+ if reply.add(cursor.parent_ino, 2, FileType::Directory, "..") {
+ break;
+ }
+ added = true;
+ index = 2;
+ continue;
+ }
+ let local = index - 2;
+ if local >= cursor.entries.len() {
+ if cursor.complete {
+ break;
+ }
+ let before = cursor.entries.len();
+ if let Err(errno) = self.load_page(&mut cursor).await {
+ // Verified entries stay visible; a mid-stream failure
+ // resumes from the committed offset on the next call.
+ if added || cursor.entries.len() > before {
+ break;
+ }
+ return reply.error(errno);
+ }
+ continue;
+ }
+ let item = cursor.entries[local].clone();
+ if reply.add(item.ino, index as u64 + 1, item.kind, &item.name) {
+ break;
+ }
+ added = true;
+ index += 1;
+ }
+ reply.ok();
+ }
+
+ async fn releasedir(&self, fh: FileHandle, reply: ReplyEmpty) {
+ guard(&self.dirs).remove(&fh.0);
+ reply.ok();
+ }
+
+ async fn load_page(&self, cursor: &mut DirCursor) -> Result<(), fuser::Errno> {
+ let page = cursor
+ .snapshot
+ .scan(cursor.directory, cursor.token.as_ref(), READDIR_PAGE)
+ .await
+ .map_err(|e| core_errno(&e))?;
+ cursor.token = page.next;
+ cursor.complete = cursor.token.is_none();
+ for entry in page.entries {
+ let (ino, kind) = self.resolve_entry(&cursor.snapshot, entry.node_id).await?;
+ cursor.entries.push(DirItem {
+ ino,
+ kind,
+ name: entry.name,
+ });
+ }
+ Ok(())
+ }
+
+ async fn resolve_entry(
+ &self,
+ snapshot: &Snapshot,
+ id: NodeId,
+ ) -> Result<(INodeNo, FileType), fuser::Errno> {
+ // Release the inode-table guard before `inode_for` reacquires it;
+ // an `if let` scrutinee would keep the temporary guard alive.
+ let cached = { guard(&self.inodes).cached(id) };
+ if let Some(info) = cached {
+ let ino = self.inode_for(id, None)?;
+ return Ok((ino, entry_kind(info.directory)));
+ }
+ let node = snapshot
+ .node(id)
+ .await
+ .map_err(|e| core_errno(&e))?
+ .ok_or(fuser::Errno::EIO)?;
+ let info = CachedInfo {
+ directory: node.is_directory(),
+ executable: node.executable(),
+ generation: node.generation(),
+ };
+ let ino = self.inode_for(id, Some(info))?;
+ Ok((ino, entry_kind(info.directory)))
+ }
+}
+
+fn entry_kind(directory: bool) -> FileType {
+ if directory {
+ FileType::Directory
+ } else {
+ FileType::RegularFile
+ }
+}
+
+fn revision_hex(revision: yinyang_core::Revision) -> String {
+ revision
+ .to_bytes()
+ .iter()
+ .map(|byte| format!("{byte:02x}"))
+ .collect()
+}
+
+/// Explicit connection-ended errnos. ENOENT is not one of them: fuser already
+/// treats a missing inode or entry as an accepted invalidation.
+fn is_connection_ended(error: &std::io::Error) -> bool {
+ matches!(
+ error.raw_os_error(),
+ Some(code)
+ if matches!(
+ code,
+ libc::ENODEV | libc::ENOTCONN | libc::EPIPE | libc::ECONNRESET | libc::ESHUTDOWN
+ )
+ )
+}
+
+fn guard<T>(lock: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+ lock.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+fn runtime_errno(error: &crate::runtime::Error) -> fuser::Errno {
+ use crate::runtime::ErrorKind;
+ match error.kind() {
+ ErrorKind::NotFound => fuser::Errno::ENOENT,
+ ErrorKind::AlreadyExists => fuser::Errno::EEXIST,
+ ErrorKind::NotDirectory => fuser::Errno::ENOTDIR,
+ ErrorKind::IsDirectory => fuser::Errno::EISDIR,
+ ErrorKind::NotEmpty => fuser::Errno::ENOTEMPTY,
+ ErrorKind::ReadOnly => fuser::Errno::EROFS,
+ ErrorKind::PermissionDenied => fuser::Errno::EACCES,
+ ErrorKind::Busy | ErrorKind::Frozen => fuser::Errno::EBUSY,
+ ErrorKind::TooLarge => fuser::Errno::EFBIG,
+ ErrorKind::NoSpace => fuser::Errno::ENOSPC,
+ ErrorKind::Invalid | ErrorKind::InvalidName => fuser::Errno::EINVAL,
+ ErrorKind::Unsupported => fuser::Errno::ENOSYS,
+ ErrorKind::Closed
+ | ErrorKind::Conflict
+ | ErrorKind::Retryable
+ | ErrorKind::Unknown
+ | ErrorKind::Corrupt
+ | ErrorKind::Storage
+ | ErrorKind::Io
+ | ErrorKind::Unclassified => fuser::Errno::EIO,
+ }
+}
+
+fn core_errno(error: &yinyang_core::Error) -> fuser::Errno {
+ use yinyang_core::ErrorKind;
+ match error.kind() {
+ ErrorKind::NotFound => fuser::Errno::ENOENT,
+ ErrorKind::AlreadyExists => fuser::Errno::EEXIST,
+ ErrorKind::NotDirectory => fuser::Errno::ENOTDIR,
+ ErrorKind::IsDirectory => fuser::Errno::EISDIR,
+ ErrorKind::NotEmpty => fuser::Errno::ENOTEMPTY,
+ ErrorKind::PermissionDenied => fuser::Errno::EACCES,
+ ErrorKind::Invalid | ErrorKind::InvalidName => fuser::Errno::EINVAL,
+ ErrorKind::Unsupported => fuser::Errno::ENOSYS,
+ ErrorKind::Corrupt | ErrorKind::Storage | ErrorKind::Io => fuser::Errno::EIO,
+ }
+}
+
+/// The filesystem object handed to the fuser session.
+pub(super) struct FuseFrontend {
+ pub(super) inner: Arc<Inner>,
+}
+
+impl Filesystem for FuseFrontend {
+ fn init(&mut self, _req: &Request, config: &mut KernelConfig) -> std::io::Result<()> {
+ // FILE_OPS makes the kernel carry the open handle on getattr, which
+ // lets fstat report the staged version; PARALLEL_DIROPS admits
+ // concurrent lookup/readdir, which the adapter already supports.
+ let _ = config.add_capabilities(InitFlags::FUSE_FILE_OPS | InitFlags::FUSE_PARALLEL_DIROPS);
+ let _ = config.set_time_granularity(std::time::Duration::from_secs(1));
+ Ok(())
+ }
+
+ fn destroy(&mut self) {}
+
+ fn lookup(&self, _req: &Request, parent: INodeNo, name: &std::ffi::OsStr, reply: ReplyEntry) {
+ let Some(name) = name.to_str() else {
+ return reply.error(fuser::Errno::EINVAL);
+ };
+ let name = name.to_owned();
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.lookup(parent, name, reply).await });
+ }
+
+ fn getattr(&self, _req: &Request, ino: INodeNo, fh: Option<FileHandle>, reply: ReplyAttr) {
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.getattr(ino, fh, reply).await });
+ }
+
+ fn setattr(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _mode: Option<u32>,
+ _uid: Option<u32>,
+ _gid: Option<u32>,
+ _size: Option<u64>,
+ _atime: Option<TimeOrNow>,
+ _mtime: Option<TimeOrNow>,
+ _ctime: Option<SystemTime>,
+ _fh: Option<FileHandle>,
+ _crtime: Option<SystemTime>,
+ _chgtime: Option<SystemTime>,
+ _bkuptime: Option<SystemTime>,
+ _flags: Option<BsdFileFlags>,
+ reply: ReplyAttr,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn readlink(&self, _req: &Request, _ino: INodeNo, reply: ReplyData) {
+ reply.error(fuser::Errno::EINVAL);
+ }
+
+ fn mknod(
+ &self,
+ _req: &Request,
+ _parent: INodeNo,
+ _name: &std::ffi::OsStr,
+ _mode: u32,
+ _umask: u32,
+ _rdev: u32,
+ reply: ReplyEntry,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn mkdir(
+ &self,
+ _req: &Request,
+ _parent: INodeNo,
+ _name: &std::ffi::OsStr,
+ _mode: u32,
+ _umask: u32,
+ reply: ReplyEntry,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn unlink(&self, _req: &Request, _parent: INodeNo, _name: &std::ffi::OsStr, reply: ReplyEmpty) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn rmdir(&self, _req: &Request, _parent: INodeNo, _name: &std::ffi::OsStr, reply: ReplyEmpty) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn symlink(
+ &self,
+ _req: &Request,
+ _parent: INodeNo,
+ _link_name: &std::ffi::OsStr,
+ _target: &std::path::Path,
+ reply: ReplyEntry,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn rename(
+ &self,
+ _req: &Request,
+ _parent: INodeNo,
+ _name: &std::ffi::OsStr,
+ _newparent: INodeNo,
+ _newname: &std::ffi::OsStr,
+ _flags: fuser::RenameFlags,
+ reply: ReplyEmpty,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn link(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _newparent: INodeNo,
+ _newname: &std::ffi::OsStr,
+ reply: ReplyEntry,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn open(&self, _req: &Request, ino: INodeNo, flags: OpenFlags, reply: ReplyOpen) {
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.open(ino, flags, reply).await });
+ }
+
+ fn read(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ fh: FileHandle,
+ offset: u64,
+ size: u32,
+ _flags: OpenFlags,
+ _lock_owner: Option<LockOwner>,
+ reply: ReplyData,
+ ) {
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.read(fh, offset, size, reply).await });
+ }
+
+ fn write(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _fh: FileHandle,
+ _offset: u64,
+ _data: &[u8],
+ _write_flags: WriteFlags,
+ _flags: OpenFlags,
+ _lock_owner: Option<LockOwner>,
+ reply: ReplyWrite,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn flush(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _fh: FileHandle,
+ _lock_owner: LockOwner,
+ reply: ReplyEmpty,
+ ) {
+ reply.ok();
+ }
+
+ fn fsync(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _fh: FileHandle,
+ _datasync: bool,
+ reply: ReplyEmpty,
+ ) {
+ reply.ok();
+ }
+
+ fn opendir(&self, _req: &Request, ino: INodeNo, _flags: OpenFlags, reply: ReplyOpen) {
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.opendir(ino, reply).await });
+ }
+
+ fn readdir(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ fh: FileHandle,
+ offset: u64,
+ reply: ReplyDirectory,
+ ) {
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.readdir(fh, offset, reply).await });
+ }
+
+ fn releasedir(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ fh: FileHandle,
+ _flags: OpenFlags,
+ reply: ReplyEmpty,
+ ) {
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.releasedir(fh, reply).await });
+ }
+
+ fn fsyncdir(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _fh: FileHandle,
+ _datasync: bool,
+ reply: ReplyEmpty,
+ ) {
+ reply.ok();
+ }
+
+ fn statfs(&self, _req: &Request, _ino: INodeNo, reply: ReplyStatfs) {
+ // No local capacity claim is implied by a remote snapshot.
+ reply.statfs(0, 0, 0, 0, 0, 4096, 255, 0);
+ }
+
+ fn setxattr(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _name: &std::ffi::OsStr,
+ _value: &[u8],
+ _flags: i32,
+ _position: u32,
+ reply: ReplyEmpty,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn getxattr(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _name: &std::ffi::OsStr,
+ _size: u32,
+ reply: ReplyXattr,
+ ) {
+ reply.error(fuser::Errno::EOPNOTSUPP);
+ }
+
+ fn listxattr(&self, _req: &Request, _ino: INodeNo, _size: u32, reply: ReplyXattr) {
+ reply.error(fuser::Errno::EOPNOTSUPP);
+ }
+
+ fn removexattr(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _name: &std::ffi::OsStr,
+ reply: ReplyEmpty,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn access(&self, _req: &Request, _ino: INodeNo, mask: AccessFlags, reply: ReplyEmpty) {
+ if mask.contains(AccessFlags::W_OK) {
+ reply.error(fuser::Errno::EROFS);
+ } else {
+ reply.ok();
+ }
+ }
+
+ fn create(
+ &self,
+ _req: &Request,
+ _parent: INodeNo,
+ _name: &std::ffi::OsStr,
+ _mode: u32,
+ _umask: u32,
+ _flags: i32,
+ reply: fuser::ReplyCreate,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn forget(&self, _req: &Request, ino: INodeNo, nlookup: u64) {
+ self.inner.forget(ino, nlookup);
+ }
+
+ fn release(
+ &self,
+ _req: &Request,
+ ino: INodeNo,
+ fh: FileHandle,
+ _flags: OpenFlags,
+ _lock_owner: Option<LockOwner>,
+ _flush: bool,
+ reply: ReplyEmpty,
+ ) {
+ let inner = self.inner.clone();
+ self.inner
+ .spawn(async move { inner.release(ino, fh, reply).await });
+ }
+
+ fn fallocate(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _fh: FileHandle,
+ _offset: u64,
+ _length: u64,
+ _mode: i32,
+ reply: ReplyEmpty,
+ ) {
+ reply.error(fuser::Errno::EROFS);
+ }
+
+ fn lseek(
+ &self,
+ _req: &Request,
+ _ino: INodeNo,
+ _fh: FileHandle,
+ _offset: i64,
+ _whence: i32,
+ reply: fuser::ReplyLseek,
+ ) {
+ reply.error(fuser::Errno::ENOSYS);
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{Inner, guard};
+ use crate::core::{BackendProfile, Fs};
+ use crate::mount::Mount;
+ use crate::runtime::Runtime;
+ use crate::support;
+ use std::sync::Arc;
+ use yinyang_core::Authority;
+
+ /// An open read-only handle pins the staged version: while the file table
+ /// holds a reference, path stats and fstat both report the base length,
+ /// and a later external version is only visible after release.
+ #[tokio::test]
+ async fn active_handle_pins_metadata_until_release() {
+ let temp = tempfile::tempdir().unwrap();
+ let backend = support::TestBackend::default();
+ Fs::create(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap();
+ let authority: Arc<dyn Authority> = Arc::new(
+ Fs::open(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap(),
+ );
+
+ let published = temp.path().join("published");
+ let runtime = Runtime::open(authority.clone(), &published).await.unwrap();
+ runtime
+ .create_file(runtime.authority().root(), "file")
+ .await
+ .unwrap();
+ let id = authority
+ .observe_latest()
+ .await
+ .unwrap()
+ .resolve("file")
+ .await
+ .unwrap()
+ .unwrap()
+ .id();
+ let mut first = runtime.open_file("file", true).await.unwrap();
+ first.write(0, b"first version").await.unwrap();
+ first.fsync().await.unwrap();
+ first.close().await.unwrap();
+ drop(runtime);
+
+ let mount = Mount::open(authority.clone(), temp.path().join("ro"), true)
+ .await
+ .unwrap();
+ let inner = Inner::new(mount, tokio::runtime::Handle::current());
+ let fh = inner.next_handle();
+ let open = inner.prepare_open(id).await.unwrap();
+ guard(&inner.files).insert(fh, Arc::new(open));
+
+ let other = temp.path().join("other");
+ let writer = Runtime::open(authority.clone(), &other).await.unwrap();
+ let mut second = writer.open_file("file", true).await.unwrap();
+ second.write(0, b"second version").await.unwrap();
+ second.fsync().await.unwrap();
+
+ let latest = authority.observe_latest().await.unwrap();
+ let pinned = inner.attr_for(&latest, id).await.unwrap();
+ assert_eq!(pinned.size, "first version".len() as u64);
+ let open = inner.open_for_node(id).unwrap();
+ assert_eq!(inner.handle_attr(&open).await.unwrap().size, pinned.size);
+ assert_eq!(inner.handle_attr(&open).await.unwrap().perm, 0o444);
+
+ // Release the only reference: clean staging is reclaimed and the next
+ // observation reports the externally published second version.
+ drop(second);
+ drop(writer);
+ drop(open);
+ drop(guard(&inner.files).remove(&fh).unwrap());
+ inner.mount.reclaim(id).await.unwrap();
+ let latest = authority.observe_latest().await.unwrap();
+ let refreshed = inner.attr_for(&latest, id).await.unwrap();
+ assert_eq!(refreshed.size, "second version".len() as u64);
+ }
+
+ /// A clean record left by a release/reclaim race must not satisfy a later
+ /// open; prepare_open reclaims it first and materializes the latest
+ /// revision.
+ #[tokio::test]
+ async fn fresh_open_reclaims_a_stale_clean_record() {
+ let temp = tempfile::tempdir().unwrap();
+ let backend = support::TestBackend::default();
+ Fs::create(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap();
+ let authority: Arc<dyn Authority> = Arc::new(
+ Fs::open(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap(),
+ );
+ let runtime = Runtime::open(authority.clone(), temp.path().join("published"))
+ .await
+ .unwrap();
+ runtime
+ .create_file(runtime.authority().root(), "file")
+ .await
+ .unwrap();
+ let id = authority
+ .observe_latest()
+ .await
+ .unwrap()
+ .resolve("file")
+ .await
+ .unwrap()
+ .unwrap()
+ .id();
+ let mut first = runtime.open_file("file", true).await.unwrap();
+ first.write(0, b"old").await.unwrap();
+ first.fsync().await.unwrap();
+ first.close().await.unwrap();
+ drop(runtime);
+
+ let mount = Mount::open(authority.clone(), temp.path().join("ro"), true)
+ .await
+ .unwrap();
+ let inner = Inner::new(mount, tokio::runtime::Handle::current());
+ // Simulate a release whose reclaim raced a live read: the clean record
+ // stays in the Mount map with zero references after the clone drops.
+ let stale = inner.prepare_open(id).await.unwrap();
+ assert_eq!(inner.handle_attr(&stale).await.unwrap().size, 3);
+ drop(stale);
+
+ let writer = Runtime::open(authority.clone(), temp.path().join("other"))
+ .await
+ .unwrap();
+ let mut second = writer.open_file("file", true).await.unwrap();
+ second.write(0, b"fresh version").await.unwrap();
+ second.fsync().await.unwrap();
+ drop(second);
+ drop(writer);
+
+ let fresh = inner.prepare_open(id).await.unwrap();
+ assert_eq!(
+ inner.handle_attr(&fresh).await.unwrap().size,
+ "fresh version".len() as u64
+ );
+ drop(fresh);
+ inner.mount.reclaim(id).await.unwrap();
+ }
+}
diff --git a/src/fuse/inode.rs b/src/fuse/inode.rs
new file mode 100644
index 0000000..dc07ea8
--- /dev/null
+++ b/src/fuse/inode.rs
@@ -0,0 +1,199 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Volume-lifetime numeric inode mapping for the Linux FUSE boundary.
+//!
+//! Inode numbers are deterministic functions of the core [`NodeId`], so they
+//! are stable across mounts and restarts. The root is always 1. Identities
+//! with a colliding derivation are rejected instead of aliased; collisions
+//! are astronomically unlikely for 128-bit node identities.
+//!
+//! The map and the cached kind/executable observations live for the whole
+//! mount, mirroring the macOS prototype's identity-map lifetime. Lookup
+//! counters still track kernel references so a later layer can evict entries
+//! without changing the deterministic inode numbers. This module holds no
+//! lock while touching the authority or runtime.
+
+use std::collections::BTreeMap;
+use yinyang_core::NodeId;
+
+/// The FUSE inode reserved for the volume root.
+pub const ROOT_INODE: u64 = 1;
+
+/// Domain separation keeps the derivation independent of content hashes.
+const INODE_DOMAIN: &[u8] = b"yinyang fuse inode v1";
+
+/// Kind-adjacent metadata observed from an authority snapshot.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct CachedInfo {
+ pub directory: bool,
+ pub executable: bool,
+ pub generation: u64,
+}
+
+/// Stable NodeId <-> inode mapping with kernel lookup counters.
+pub struct InodeTable {
+ by_inode: BTreeMap<u64, NodeId>,
+ by_node: BTreeMap<NodeId, u64>,
+ lookups: BTreeMap<u64, u64>,
+ info: BTreeMap<NodeId, CachedInfo>,
+}
+
+impl InodeTable {
+ pub fn new(root: NodeId) -> Self {
+ Self {
+ by_inode: [(ROOT_INODE, root)].into_iter().collect(),
+ by_node: [(root, ROOT_INODE)].into_iter().collect(),
+ lookups: BTreeMap::new(),
+ info: BTreeMap::new(),
+ }
+ }
+
+ /// Resolve or allocate the deterministic inode for a node identity.
+ pub fn inode(&mut self, id: NodeId) -> Result<u64, &'static str> {
+ if let Some(inode) = self.by_node.get(&id) {
+ return Ok(*inode);
+ }
+ let inode = derive(id)?;
+ if let Some(existing) = self.by_inode.get(&inode) {
+ return Err(if *existing == id {
+ "inode already mapped to another identity"
+ } else {
+ "inode collision"
+ });
+ }
+ self.by_inode.insert(inode, id);
+ self.by_node.insert(id, inode);
+ Ok(inode)
+ }
+
+ /// Resolve an inode number to a node identity.
+ pub fn node(&self, inode: u64) -> Option<NodeId> {
+ self.by_inode.get(&inode).copied()
+ }
+
+ /// Remember one successful kernel lookup for an inode.
+ pub fn remember_lookup(&mut self, inode: u64) {
+ let count = self.lookups.entry(inode).or_default().saturating_add(1);
+ self.lookups.insert(inode, count);
+ }
+
+ /// Forget `count` lookups. Mappings are retained for the mount lifetime.
+ pub fn forget(&mut self, inode: u64, count: u64) {
+ let Some(remaining) = self.lookups.get_mut(&inode) else {
+ return;
+ };
+ *remaining = remaining.saturating_sub(count);
+ if *remaining == 0 {
+ self.lookups.remove(&inode);
+ }
+ }
+
+ #[cfg(test)]
+ pub fn lookup_count(&self, inode: u64) -> u64 {
+ self.lookups.get(&inode).copied().unwrap_or(0)
+ }
+
+ /// Cache kind-adjacent metadata observed from a snapshot.
+ pub fn cache(&mut self, id: NodeId, info: CachedInfo) {
+ self.info.insert(id, info);
+ }
+
+ pub fn cached(&self, id: NodeId) -> Option<CachedInfo> {
+ self.info.get(&id).copied()
+ }
+
+ /// Inode numbers mapped so far; used by the explicit refresh to invalidate
+ /// only the attributes the kernel may cache.
+ pub fn inodes(&self) -> Vec<u64> {
+ self.by_inode.keys().copied().collect()
+ }
+}
+
+fn derive(id: NodeId) -> Result<u64, &'static str> {
+ let mut hasher = blake3::Hasher::new();
+ hasher.update(INODE_DOMAIN);
+ hasher.update(id.as_bytes());
+ let hash = hasher.finalize();
+ let mut bytes = [0u8; 8];
+ bytes.copy_from_slice(&hash.as_bytes()[..8]);
+ let inode = u64::from_be_bytes(bytes);
+ if inode <= ROOT_INODE {
+ return Err("derived inode collides with the root mapping");
+ }
+ Ok(inode)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn root_is_always_inode_one() {
+ let root = NodeId::generate();
+ let mut table = InodeTable::new(root);
+ assert_eq!(table.inode(root).unwrap(), ROOT_INODE);
+ assert_eq!(table.node(ROOT_INODE), Some(root));
+ }
+
+ #[test]
+ fn derivation_is_stable_and_unique() {
+ let root = NodeId::generate();
+ let mut table = InodeTable::new(root);
+ let ids: Vec<NodeId> = (0..512).map(|_| NodeId::generate()).collect();
+ let first: Vec<u64> = ids.iter().map(|id| table.inode(*id).unwrap()).collect();
+ let mut second = InodeTable::new(root);
+ let repeated: Vec<u64> = ids.iter().map(|id| second.inode(*id).unwrap()).collect();
+ assert_eq!(first, repeated);
+ for (index, inode) in first.iter().enumerate() {
+ assert_ne!(*inode, ROOT_INODE);
+ assert_eq!(second.node(*inode), Some(ids[index]));
+ assert!(!first[..index].contains(inode));
+ }
+ }
+
+ #[test]
+ fn lookup_counters_are_saturating() {
+ let root = NodeId::generate();
+ let mut table = InodeTable::new(root);
+ let id = NodeId::generate();
+ let inode = table.inode(id).unwrap();
+ table.remember_lookup(inode);
+ table.remember_lookup(inode);
+ assert_eq!(table.lookup_count(inode), 2);
+ table.forget(inode, 1);
+ assert_eq!(table.lookup_count(inode), 1);
+ table.forget(inode, 100);
+ assert_eq!(table.lookup_count(inode), 0);
+ assert_eq!(table.node(inode), Some(id));
+ }
+
+ #[test]
+ fn cached_kind_tracks_observations() {
+ let root = NodeId::generate();
+ let mut table = InodeTable::new(root);
+ let id = NodeId::generate();
+ assert_eq!(table.cached(id), None);
+ let info = CachedInfo {
+ directory: false,
+ executable: true,
+ generation: 3,
+ };
+ table.cache(id, info);
+ assert_eq!(table.cached(id), Some(info));
+ }
+}
diff --git a/src/fuse/mod.rs b/src/fuse/mod.rs
new file mode 100644
index 0000000..f655759
--- /dev/null
+++ b/src/fuse/mod.rs
@@ -0,0 +1,288 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Linux FUSE mount frontend for Managed read-only volumes.
+//!
+//! The CLI form is `yy --volume CONFIG mount MOUNTPOINT`; the process stays in
+//! the foreground until unmounted. The volume must declare `frontend = "fuse"`
+//! and `read_only = true`; the shared admission rules in
+//! [`crate::volume`] reject every other combination before an authority
+//! connection or staging lease is created.
+//!
+//! Startup takes the staging lease through [`crate::mount::Mount`] and then
+//! refuses to serve a staging database that still holds unpublished, frozen,
+//! conflicted or failed handles: a read-only snapshot view must never surface
+//! those locally staged bytes as if they were remote. Clean observations are
+//! disposable and are reclaimed by the existing Mount recovery.
+//!
+//! The session mounts as `fuse.yinyang` and runs in the foreground. SIGINT and
+//! SIGTERM detach the mount and wait briefly for the session. Lazy unmounting
+//! does not end the kernel connection while clients still hold open
+//! references, so the entry point returns [`Outcome::TeardownExpired`] when a
+//! bounded wait expires. The CLI handles that outcome by exiting non-zero,
+//! which closes `/dev/fuse` and makes the kernel abort every pending request.
+//!
+//! See `specs/linux-fuse.md` for the full read-only contract.
+
+mod attrs;
+mod frontend;
+mod inode;
+
+use crate::mount::Mount;
+use crate::volume::{Volume, VolumeConfig};
+use fuser::{Config, MountOption, Session, SessionACL};
+use std::path::PathBuf;
+use std::sync::Arc;
+
+/// How long a signal-initiated teardown waits after a lazy unmount before it
+/// reports that the caller must terminate the process.
+const TEARDOWN_GRACE: std::time::Duration = std::time::Duration::from_secs(5);
+
+/// Result of a foreground mount run.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Outcome {
+ /// The session ended on its own or a signal-initiated unmount finished.
+ Unmounted,
+ /// A lazy unmount left the kernel connection alive past the grace period
+ /// because clients still hold references. The caller must terminate the
+ /// process so the OS closes `/dev/fuse` and the kernel aborts pending
+ /// requests (equivalent to crash recovery, not a graceful unmount).
+ TeardownExpired { grace: std::time::Duration },
+}
+
+/// Mount a validated read-only FUSE volume in the foreground.
+///
+/// `staging` must already be resolved to an absolute path by the CLI.
+pub async fn run(
+ config: VolumeConfig,
+ operator: opendal::Operator,
+ token: Option<String>,
+ mountpoint: PathBuf,
+) -> Result<Outcome, Box<dyn std::error::Error>> {
+ let authority = Volume::connect(&config, operator, token).await?;
+ let mount = Mount::open(authority, &config.staging, true).await?;
+ reject_unpublished_staging(&mount).await?;
+ let snapshot = mount.authority().observe_latest().await?;
+ let root = mount.authority().root();
+ let root_node = snapshot.node(root).await?;
+ if !root_node.is_some_and(|node| node.is_directory()) {
+ return Err(std::io::Error::other(
+ "remote filesystem root is unavailable or not a directory",
+ )
+ .into());
+ }
+ let inner = Arc::new(frontend::Inner::new(
+ mount,
+ tokio::runtime::Handle::current(),
+ ));
+ let filesystem = frontend::FuseFrontend {
+ inner: inner.clone(),
+ };
+ let mut options = Config::default();
+ options.mount_options = vec![
+ MountOption::RO,
+ MountOption::FSName(format!("yinyang-{}", config.name)),
+ MountOption::Subtype("yinyang".into()),
+ ];
+ options.acl = SessionACL::Owner;
+ // Register SIGHUP before the mount becomes externally visible so a
+ // refresh signal cannot fall through to the default handler while the loop
+ // task waits for its first poll.
+ let hangup = match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::hangup()) {
+ Ok(signal) => Some(signal),
+ Err(error) => {
+ eprintln!("yy: fuse refresh: cannot handle SIGHUP: {error}");
+ None
+ }
+ };
+ let session = Session::new(filesystem, &mountpoint, &options)?;
+ println!(
+ "yy: mounted {} read-only at {} (fuse.yinyang)",
+ config.name,
+ mountpoint.display()
+ );
+ // `Session::spawn` moves the mount object into `BackgroundSession`, so a
+ // `SessionUnmounter` obtained from the pre-spawn session would find an
+ // empty slot. One blocking owner holds the background session, polls its
+ // public thread guard for a natural end (for example `fusermount3 -u`),
+ // and receives the local teardown request. Exactly one `join` or
+ // `umount_and_join` runs under the shared grace period.
+ let background = session.spawn()?;
+ inner.install_notifier(background.notifier());
+ let (stop_refresh, stop_refresh_rx) = tokio::sync::oneshot::channel::<()>();
+ let refresh_task = hangup.map(|signal| {
+ let refresh = inner.clone();
+ tokio::runtime::Handle::current()
+ .spawn(async move { refresh.serve_hup(signal, stop_refresh_rx).await })
+ });
+ let (teardown, teardown_rx) = std::sync::mpsc::channel();
+ let join = tokio::task::spawn_blocking(move || {
+ loop {
+ match teardown_rx.recv_timeout(std::time::Duration::from_millis(100)) {
+ Ok(()) | Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
+ return background.umount_and_join();
+ }
+ Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
+ if background.guard.is_finished() {
+ return background.join();
+ }
+ }
+ }
+ }
+ });
+ tokio::pin!(join);
+ // A JoinHandle must not be polled after completion: remember a natural
+ // session end here and only await it in finalize when the signal path ran.
+ let joined = tokio::select! {
+ result = &mut join => Some(result),
+ _ = shutdown_signal() => {
+ let _ = teardown.send(());
+ None
+ }
+ };
+ // One grace period covers the session teardown and the SIGHUP loop: stop
+ // the refresh task, then wait for both. A refresh in progress may finish
+ // inside this window; no cancellation is needed. Both waits happen before
+ // either result is propagated so an error cannot skip the other cleanup.
+ let _ = stop_refresh.send(());
+ match tokio::time::timeout(TEARDOWN_GRACE, async {
+ let session = match joined {
+ Some(result) => result,
+ None => join.await,
+ };
+ let refresh = match refresh_task {
+ Some(task) => task.await,
+ None => Ok(()),
+ };
+ session.map_err(blocking_error)??;
+ refresh.map_err(blocking_error)?;
+ Ok(())
+ })
+ .await
+ {
+ Ok(Ok(())) => {
+ println!("yy: unmounted {}", mountpoint.display());
+ Ok(Outcome::Unmounted)
+ }
+ Ok(Err(error)) => Err(error),
+ // A lazy unmount keeps the session alive while clients hold the
+ // mount. Report it to the CLI instead of returning into a runtime
+ // shutdown that would wait for the blocked session task; the CLI exits
+ // the process so the kernel aborts the connection.
+ Err(_) => Ok(Outcome::TeardownExpired {
+ grace: TEARDOWN_GRACE,
+ }),
+ }
+}
+
+fn blocking_error(error: tokio::task::JoinError) -> std::io::Error {
+ std::io::Error::other(format!("filesystem session task failed: {error}"))
+}
+
+/// A read-only snapshot must never expose staged bytes that were not
+/// published. The staging lease is already held, so the check cannot race
+/// another client, and refusing startup changes no remote state.
+async fn reject_unpublished_staging(mount: &Mount) -> Result<(), Box<dyn std::error::Error>> {
+ let status = mount.status().await?;
+ if let Some(handle) = status
+ .handles
+ .iter()
+ .find(|handle| handle.pending || handle.frozen || handle.conflict || handle.error.is_some())
+ {
+ return Err(std::io::Error::other(format!(
+ "staging contains handle {} with unpublished, frozen, conflicted or failed state; \
+ a read-only FUSE mount will not expose it; publish or acknowledge it with the \
+ library frontend before mounting",
+ handle.id
+ ))
+ .into());
+ }
+ Ok(())
+}
+
+/// Wait for SIGINT or SIGTERM, the two signals a foreground mount operator uses
+/// to tear the session down cleanly.
+async fn shutdown_signal() {
+ use tokio::signal::unix::{SignalKind, signal};
+ let mut terminate = match signal(SignalKind::terminate()) {
+ Ok(signal) => signal,
+ Err(_) => {
+ let _ = tokio::signal::ctrl_c().await;
+ return;
+ }
+ };
+ tokio::select! {
+ _ = tokio::signal::ctrl_c() => {}
+ _ = terminate.recv() => {}
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::reject_unpublished_staging;
+ use crate::core::{BackendProfile, Fs};
+ use crate::mount::Mount;
+ use crate::runtime::Runtime;
+ use crate::support;
+ use std::sync::Arc;
+ use yinyang_core::Authority;
+
+ #[tokio::test]
+ async fn read_only_mount_refuses_unpublished_staging() {
+ let temp = tempfile::tempdir().unwrap();
+ let backend = support::TestBackend::default();
+ Fs::create(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap();
+ let authority: Arc<dyn Authority> = Arc::new(
+ Fs::open(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap(),
+ );
+ let staging = temp.path().join("staging");
+ let runtime = Runtime::open(authority.clone(), &staging).await.unwrap();
+ runtime
+ .create_file(runtime.authority().root(), "dirty")
+ .await
+ .unwrap();
+ let mut handle = runtime.open_file("dirty", true).await.unwrap();
+ handle.write(0, b"unpublished").await.unwrap();
+ drop(handle);
+ drop(runtime);
+ let mount = Mount::open(authority, &staging, true).await.unwrap();
+ let error = reject_unpublished_staging(&mount).await.unwrap_err();
+ assert!(error.to_string().contains("unpublished"));
+ }
+
+ #[tokio::test]
+ async fn read_only_mount_accepts_clean_staging() {
+ let temp = tempfile::tempdir().unwrap();
+ let backend = support::TestBackend::default();
+ Fs::create(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap();
+ let authority: Arc<dyn Authority> = Arc::new(
+ Fs::open(backend.operator(), BackendProfile::Minio)
+ .await
+ .unwrap(),
+ );
+ let mount = Mount::open(authority, temp.path().join("staging"), true)
+ .await
+ .unwrap();
+ reject_unpublished_staging(&mount).await.unwrap();
+ }
+}
diff --git a/src/lib.rs b/src/lib.rs
index aa12db0..e68fec3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -20,6 +20,8 @@
//! One-shot publication and restoration of local directories on a Managed filesystem.
mod directory;
+#[cfg(target_os = "linux")]
+pub mod fuse;
pub mod mount;
pub mod runtime;
pub mod sync;
diff --git a/src/main.rs b/src/main.rs
index dc3ba17..79080e7 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -37,6 +37,8 @@ struct Cli {
enum Command {
/// Inspect each capability layer and its effective intersection.
Capabilities,
+ /// Mount a read-only Managed volume through the Linux FUSE frontend.
+ Mount { mountpoint: PathBuf },
/// Operate recoverable file handles (requires --volume).
File {
#[command(subcommand)]
@@ -83,8 +85,16 @@ async fn run(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
if let Some(path) = &cli.volume {
return file_cli::run(path, cli.command).await;
}
- if matches!(cli.command, Command::File { .. } | Command::Capabilities) {
- return Err("this command requires --volume CONFIG.json".into());
+ match cli.command {
+ Command::Mount { .. } => {
+ return Err(
+ "mount requires --volume CONFIG.json with frontend=fuse and read_only=true".into(),
+ );
+ }
+ Command::File { .. } | Command::Capabilities => {
+ return Err("this command requires --volume CONFIG.json".into());
+ }
+ _ => {}
}
let profile = match std::env::var("YINYANG_STORAGE_PROFILE").as_deref() {
Ok("amazon-s3") => BackendProfile::AmazonS3,
@@ -123,9 +133,11 @@ async fn run(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
let fs = Fs::open(operator, profile).await?;
let observed = fs.observe_latest().await?;
match cli.command {
- Command::Create | Command::Serve { .. } | Command::File { .. } | Command::Capabilities => {
- unreachable!()
- }
+ Command::Create
+ | Command::Serve { .. }
+ | Command::File { .. }
+ | Command::Capabilities
+ | Command::Mount { .. } => unreachable!(),
Command::Publish {
source,
replace,
diff --git a/src/volume.rs b/src/volume.rs
index 7ae8ded..9eee05f 100644
--- a/src/volume.rs
+++ b/src/volume.rs
@@ -73,6 +73,15 @@ fn read_only() -> CapabilitySet {
.into_iter()
.collect()
}
+/// Read-only Linux FUSE frontend capabilities. The frontend serves immutable
+/// pinned file versions and pinned directory scans, so it does not provide
+/// recoverable staging or any write-side operation.
+fn fuse() -> CapabilitySet {
+ use Capability::*;
+ [Read, List, StableIdentity, PinnedReads, RetainedUnlinkRead]
+ .into_iter()
+ .collect()
+}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Model {
@@ -168,11 +177,7 @@ impl VolumeConfig {
/// Negotiation is read-only. Storage capabilities are semantic prerequisites
/// for Managed operations, not claims that raw S3 implements atomic rename.
pub fn capabilities(&self, operator: &Operator) -> Capabilities {
- let volume = if self.model == Model::Managed {
- managed()
- } else {
- CapabilitySet::new()
- };
+ let volume = self.volume_capabilities();
let cap = operator.info().capability();
let content = operator.info().scheme() == "s3"
&& cap.read
@@ -185,21 +190,43 @@ impl VolumeConfig {
} else {
CapabilitySet::new()
};
- let access = if self.access == Access::Mount {
- if self.read_only {
- read_only()
- } else {
- managed()
- }
- } else {
- CapabilitySet::new()
- };
- let frontend = if self.frontend == Frontend::Library {
+ let access = self.access_capabilities();
+ let frontend = self.frontend_capabilities();
+ Capabilities::intersect(volume, storage, access, frontend)
+ }
+ fn volume_capabilities(&self) -> CapabilitySet {
+ if self.model == Model::Managed {
managed()
} else {
CapabilitySet::new()
- };
- Capabilities::intersect(volume, storage, access, frontend)
+ }
+ }
+ fn access_capabilities(&self) -> CapabilitySet {
+ match self.access {
+ Access::Mount if self.read_only => read_only(),
+ Access::Mount => managed(),
+ Access::Sync => CapabilitySet::new(),
+ }
+ }
+ fn frontend_capabilities(&self) -> CapabilitySet {
+ match self.frontend {
+ Frontend::Library => managed(),
+ Frontend::Fuse => fuse(),
+ Frontend::Macos | Frontend::Windows => CapabilitySet::new(),
+ }
+ }
+ /// Capabilities the selected combination promises independent of storage
+ /// support. Startup requires this intersection to survive storage and
+ /// frontend negotiation, so a frontend cannot silently weaken the model.
+ fn baseline(&self) -> CapabilitySet {
+ let volume = self.volume_capabilities();
+ let access = self.access_capabilities();
+ let frontend = self.frontend_capabilities();
+ volume
+ .intersection(&access)
+ .filter(|capability| frontend.contains(capability))
+ .copied()
+ .collect()
}
pub fn validate(&self, operator: &Operator) -> Result<Capabilities> {
if self.name.trim().is_empty() || self.staging.as_os_str().is_empty() {
@@ -211,10 +238,24 @@ impl VolumeConfig {
if self.access != Access::Mount {
return Err(Error::Invalid("Sync reconciliation is not implemented"));
}
- if self.frontend != Frontend::Library {
- return Err(Error::Invalid(
- "OS frontends are not implemented; select the library frontend",
- ));
+ match self.frontend {
+ Frontend::Library => {}
+ Frontend::Fuse if !cfg!(target_os = "linux") => {
+ return Err(Error::Invalid(
+ "the fuse frontend is implemented only on Linux",
+ ));
+ }
+ Frontend::Fuse if !self.read_only => {
+ return Err(Error::Invalid(
+ "the Linux FUSE frontend is read-only in this release",
+ ));
+ }
+ Frontend::Fuse => {}
+ Frontend::Macos | Frontend::Windows => {
+ return Err(Error::Invalid(
+ "macOS and Windows frontends are not implemented; select library or fuse",
+ ));
+ }
}
match (self.publication, self.service_address) {
(Publication::Service, Some(addr)) if addr.ip().is_loopback() => {}
@@ -226,11 +267,7 @@ impl VolumeConfig {
}
}
let caps = self.capabilities(operator);
- let baseline = if self.read_only {
- read_only()
- } else {
- managed()
- };
+ let baseline = self.baseline();
if !baseline.is_subset(&caps.effective) || !self.require.is_subset(&caps.effective) {
return Err(Error::Invalid(
"effective capability intersection is missing baseline or required operations",
diff --git a/tests/volume.rs b/tests/volume.rs
index e512c78..15e3fe8 100644
--- a/tests/volume.rs
+++ b/tests/volume.rs
@@ -95,6 +95,48 @@ async fn capability_intersection_and_startup_rejection_precede_visibility() {
assert!(VolumeConfig::from_json(&serde_json::to_vec(&json).unwrap()).is_err());
}
#[tokio::test]
+async fn fuse_frontend_admits_only_read_only_managed_mounts() {
+ let temp = tempfile::tempdir().unwrap();
+ let backend = TestBackend::default();
+ let cfg = VolumeConfig {
+ frontend: Frontend::Fuse,
+ read_only: true,
+ require: BTreeSet::new(),
+ ..config(temp.path().join("state"))
+ };
+ let caps = cfg.capabilities(&backend.operator());
+ let expected: CapabilitySet = [
+ Capability::Read,
+ Capability::List,
+ Capability::StableIdentity,
+ Capability::PinnedReads,
+ Capability::RetainedUnlinkRead,
+ ]
+ .into_iter()
+ .collect();
+ assert_eq!(caps.frontend, expected);
+ assert_eq!(caps.effective, expected);
+ assert!(!caps.effective.contains(&Capability::RecoverableStaging));
+ if cfg!(target_os = "linux") {
+ assert!(cfg.validate(&backend.operator()).is_ok());
+ } else {
+ assert!(cfg.validate(&backend.operator()).is_err());
+ }
+ for invalid in [
+ VolumeConfig {
+ read_only: false,
+ ..cfg.clone()
+ },
+ VolumeConfig {
+ service_address: Some("0.0.0.0:7447".parse().unwrap()),
+ publication: Publication::Service,
+ ..cfg.clone()
+ },
+ ] {
+ assert!(invalid.validate(&backend.operator()).is_err());
+ }
+}
+#[tokio::test]
async fn read_only_volume_enforces_policy_on_new_and_recovered_handles() {
let temp = tempfile::tempdir().unwrap();
let backend = TestBackend::default();