Skip to main content

Crate fuser_ng

Crate fuser_ng 

Source
Expand description

§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 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, 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:

[dependencies]
fuser-ng = "0.9"

Implement fuser_ng::Filesystem, then wrap it before mounting:

ⓘ
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:

ⓘ
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:

[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:

ⓘ
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.

Modules§

asynchronousasync
Asynchronous counterparts to the main filesystem trait and adapter.

Structs§

AsyncFuserNGasync
Adapts an asynchronous path-oriented filesystem to the synchronous FUSE callback interface.
CallbackResult
Dummy struct returned by the callback in the read() method. Cannot be constructed outside this crate, read() requires you to return it, thus ensuring that you don’t forget to call the callback.
CreatedEntry
The return value for create: contains info on the newly-created file, as well as a handle to the opened file.
DirectoryEntry
A directory entry together with its attributes.
EntryName
Entry name resolved relative to a parent directory path.
FileAttr
File attributes.
FuserNG
Path-oriented wrapper around a user filesystem implementation.
InitFlags
Init request/reply flags.
KernelConfig
Configuration of the fuse kernel module connection
LegacyDirectoryEntrylegacy_readdir
A directory entry without attributes for the legacy FUSE readdir operation.
RequestInfo
Info about a request.
ResolvedPath
Path resolved from an inode with the current inode number attached.
Statfs
Filesystem statistics.

Enums§

EntryRef
Entry path passed to callbacks that may run before or after inode resolution.
FileType
File types
MountOption
Mount options accepted by the FUSE filesystem type See ‘man mount.fuse’ for details
ThreadCount
Number of fuser event-loop threads used to serve a mount. This configures fuser session threading, not an internal worker pool.
Xattr
Represents the return value from the listxattr and getxattr calls, which can be either a size or contain data, depending on how they are called.

Traits§

AsyncFilesystemasync
Filesystem operations that may complete asynchronously.
Filesystem
This trait must be implemented to implement a filesystem with FuserNG.
Streamasync
A stream of values produced asynchronously.

Functions§

mount
Mount the given filesystem to the given mountpoint. This function will not return until the filesystem is unmounted.
spawn_mount
Mount the given filesystem to the given mountpoint. This function spawns a background thread to handle filesystem operations while being mounted and therefore returns immediately. The returned handle should be stored to reference the mounted filesystem. If it’s dropped, the filesystem will be unmounted.

Type Aliases§

Inode
Inode number used by the public path-oriented API.
ResultCreate
Result containing a newly created and opened entry.
ResultData
Result containing an owned byte buffer.
ResultEmpty
Result for operations that return no data.
ResultEntry
Result containing the cache duration and attributes of an entry.
ResultLegacyReaddirBatchlegacy_readdir
Result containing one batch of legacy directory entries without attributes.
ResultOpen
Result containing a file handle and FUSE open response flags.
ResultReaddirBatch
Result containing one batch of directory entries and their attributes.
ResultSlice
Result containing a borrowed byte slice.
ResultStatfs
Result containing filesystem statistics.
ResultWrite
Result containing the number of bytes written.
ResultXattr
Result containing extended attribute data or its required size.