fuser-ng
fuser-ng simplifies building FUSE filesystems in Rust by combining
convenient path-based operations with explicit access to inode identities.
Built on top of fuser, it supports both
synchronous and asynchronous implementations.
fuser-ng was created as a fork of fuse-mt to overcome its limitations.
It provides broader unit and integration test coverage, uses fuser's native
multithreaded request handling, and combines a hybrid path/inode API with
batched directory reads for progressive result delivery. Asynchronous
filesystem support is opt-in through the async feature.
The project now prioritizes stabilizing its public interfaces. Breaking changes are expected to be exceptional, though they remain possible.
Overview
fuser exposes low-level FUSE kernel operations. fuser-ng wraps those
operations with an API that combines path resolution with access to inode
identities. It handles low-level replies and simplifies filesystem implementation.
The crate:
- resolves FUSE inodes to paths and exposes inode numbers to callbacks that receive a resolved entry;
- lets
Filesystemmethods returnstd::io::Resultvalues instead of using fuser reply objects directly; - provides default
ENOSYSimplementations for operations you do not support; - streams directory entries in batches while handling FUSE pagination internally;
- uses fuser's threaded event loop, configurable with
ThreadCount; - optionally adapts futures returned by
AsyncFilesystemthrough a caller-owned Tokio runtime; - adds broader unit and integration test coverage than the original
fuse-mtcodebase, including inode-table rename cases and passthrough FUSE operations.
Hybrid path/inode API
Filesystem methods receive entry types that carry paths and, when available, the inode assigned by the adapter. Both synchronous and asynchronous callbacks use these types:
EntryNameis a child name resolved relative to a parent directory, with no inode attached. It is used for operations such asmkdir,mknod,symlink,unlink, andrename.ResolvedPathcombines an entry path with its inode, accessible throughino(). It is used for operations such asopen,read, andwrite.createalso receives this type after the adapter has selected an inode for the entry.EntryRefis used bygetattr, which may run either while resolving a parent/name lookup or after an inode has already been resolved. MatchEntryRef::Resolved(path)to accesspath.ino();EntryRef::Lookupcarries anEntryNamewithout an inode.
Unlike the path-only callback arguments in
fuse-mt,
ResolvedPath exposes the adapter's inode number alongside the path.
These inode numbers are assigned by FuserNG for the mount. They are independent of any underlying filesystem's inode numbers and can be reused after the corresponding inode-table entry is freed.
These path wrapper types implement Clone. Cloning them is cheap because the
stored path components are shared internally.
The inode table stores complete paths for directories and derives leaf paths from their parent directories. This keeps descendants consistent after a directory subtree is renamed.
Usage
Add the crate to your Cargo.toml:
[]
= "0.9"
Implement fuser_ng::Filesystem, then wrap it before mounting:
let options = ;
mount?;
Directory reads
Filesystem::readdir returns directory entries in batches. Each
DirectoryEntry contains the entry name, its attributes, and their cache
duration. Batching reduces the wait for initial results: applications can
receive entries while the rest of the directory is still being enumerated.
The adapter consumes batches as reply space becomes available and handles
directory offsets internally. It fills FUSE reply buffers progressively,
without first collecting the complete directory. AsyncFilesystem::readdir
provides the same model through an asynchronous Stream.
FUSE can request an earlier offset again, for example when an application uses
seekdir or rewinddir. For each open directory handle, FuserNG deliberately
retains the entries already consumed until releasedir. This history allows
offsets to be replayed without restarting enumeration or repeating backend
requests. Retaining it is a performance choice: batching improves result
delivery latency, while memory usage grows with the retained entries.
Migrating from 0.8
Replace the former ResultReaddir return value with an iterator whose items
are ResultReaddirBatch values. An implementation that still builds the
complete directory can initially wrap that result without changing its
internal logic:
let batch: ResultReaddirBatch = read_all_entries;
once
Each DirectoryEntry must now provide ttl and attr. Implementations can
then move from one complete batch to smaller batches as entries become
available. Asynchronous implementations perform the same conversion but yield
the batches through a Stream.
Asynchronous filesystems
Asynchronous support is opt-in. Enable the async feature and provide Tokio
with a multithreaded runtime:
[]
= { = "0.9", = ["async"] }
= { = "1", = ["rt-multi-thread"] }
Implement fuser_ng::AsyncFilesystem, then pass a cloned runtime handle to the
adapter:
let runtime = new_multi_thread
.enable_all
.build?;
let options = ;
mount?;
The asynchronous trait receives owned path and data arguments and returns
Send futures. init and destroy remain synchronous because they are
lifecycle callbacks.
Like Filesystem, AsyncFilesystem provides default ENOSYS
implementations for unsupported operations, so implementations only need to
override the operations they support.
AsyncFuserNG only stores the Tokio Handle; it does not own or shut down the
runtime. The caller must keep the runtime alive while the filesystem is
mounted and decides how outstanding tasks are handled during shutdown.
destroy is forwarded directly to the target filesystem.
The same APIs are also available as fuser_ng::asynchronous::Filesystem and
fuser_ng::asynchronous::FuserNG.