# 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`](https://github.com/cberner/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 `Filesystem` methods return `std::io::Result` values instead of using
fuser reply objects directly;
* provides default `ENOSYS` implementations 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 `AsyncFilesystem` through a caller-owned
Tokio runtime;
* adds broader unit and integration test coverage than the original `fuse-mt`
codebase, 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:
* `EntryName` is a child name resolved relative to a parent directory, with no
inode attached. It is used for operations such as `mkdir`, `mknod`, `symlink`,
`unlink`, and `rename`.
* `ResolvedPath` combines an entry path with its inode, accessible through
`ino()`. It is used for operations such as `open`, `read`, and `write`.
`create` also receives this type after the adapter has selected an inode
for the entry.
* `EntryRef` is used by `getattr`, which may run either while resolving a
parent/name lookup or after an inode has already been resolved. Match
`EntryRef::Resolved(path)` to access `path.ino()`; `EntryRef::Lookup` carries
an `EntryName` without an inode.
Unlike the path-only callback arguments in
[`fuse-mt`](https://docs.rs/fuse_mt/0.6.4/fuse_mt/trait.FilesystemMT.html),
`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`:
```toml
[dependencies]
fuser-ng = "0.9"
```
Implement `fuser_ng::Filesystem`, then wrap it before mounting:
```rust,ignore
let options = [fuser_ng::MountOption::FSName("myfs".into())];
fuser_ng::mount(
fuser_ng::FuserNG::new(filesystem),
mountpoint,
&options,
fuser_ng::ThreadCount::Default,
)?;
```
## 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:
```rust,ignore
let batch: fuser_ng::ResultReaddirBatch = read_all_entries();
std::iter::once(batch)
```
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:
```toml
[dependencies]
fuser-ng = { version = "0.9", features = ["async"] }
tokio = { version = "1", features = ["rt-multi-thread"] }
```
Implement `fuser_ng::AsyncFilesystem`, then pass a cloned runtime handle to the
adapter:
```rust,ignore
let runtime = tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()?;
let options = [fuser_ng::MountOption::FSName("my-async-fs".into())];
fuser_ng::mount(
fuser_ng::AsyncFuserNG::new(filesystem, runtime.handle().clone()),
mountpoint,
&options,
fuser_ng::ThreadCount::Default,
)?;
```
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`.