Crate fuser_ng 

fuser-ng

fuser-ng is a higher-level, path-oriented FUSE filesystem library for Rust, built on top of fuser 0.18.

It started as a fork of fuse-mt. The 0.7 series moved the crate to fuser 0.17, uses fuser’s native threading instead of an internal thread pool, and adds a new inode table that keeps descendant paths correct when a parent directory is renamed. Version 0.8 refines the public path API for inode-aware getattr and create callbacks and adds an optional asynchronous filesystem interface. Version 0.9 adds streaming directory reads for synchronous and asynchronous filesystems.

Overview

fuser exposes low-level FUSE kernel operations. fuser-ng wraps those operations with an API that is closer to the FUSE C API and simpler to implement for path-based filesystems.

The crate:

• translates FUSE inodes into paths;
• 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.

Path API

Filesystem methods receive path-oriented types instead of raw inode numbers:

• EntryName is a child name resolved relative to a parent directory. It is used for operations such as mkdir, mknod, symlink, unlink, and rename.
• ResolvedPath is an entry path with its inode attached. It is used when FuserNG already has an inode for the entry, including operations such as open, read, write, and create.
• EntryRef is used by getattr, which may run either while resolving a parent/name lookup or after an inode has already been resolved.

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. Implementations can choose an appropriate batch size and produce entries incrementally instead of collecting the complete directory first.

The adapter consumes batches as reply space becomes available and handles directory offsets internally. AsyncFilesystem::readdir provides the same model through an asynchronous Stream.

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.

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.