fractal-fuse

An async FUSE (Filesystem in Userspace) library for Linux, built on io_uring and the compio async runtime. It uses the FUSE_OVER_IO_URING kernel interface (Linux 6.14+) for high-performance userspace filesystem I/O with zero-copy buffer registration.

Features

• io_uring-native FUSE transport -- Uses FUSE_IO_URING_CMD_REGISTER and FUSE_IO_URING_CMD_COMMIT_AND_FETCH for zero-copy request/response cycles
• Thread-per-core io_uring rings -- One worker per CPU by default, each with thread affinity and its own compio runtime; with_worker_count optionally folds onto fewer threads while still covering every kernel qid
• Async filesystem trait -- Implement the Filesystem trait with async methods; unimplemented operations default to ENOSYS
• Unprivileged mounting -- Uses fusermount3 for non-root mounts
• Configurable mount options -- Builder-pattern MountOptions for allow_other, default_permissions, writeback_cache, and more
• FUSE protocol v7.45 -- Full ABI definitions with support for readdirplus, fallocate, lseek, copy_file_range, and other modern operations

Requirements

• Linux 6.14+ with FUSE_OVER_IO_URING support enabled
• fusermount3 installed and accessible in $PATH
• Rust edition 2024 (nightly or Rust 1.85+)

Usage

Implement the Filesystem trait and run a session:

use std::path::Path;
use fractal_fuse::{Filesystem, MountOptions, Session};

struct MyFs;

impl Filesystem for MyFs {
    // Implement the operations your filesystem supports.
    // All methods default to returning ENOSYS.
}

fn main() -> std::io::Result<()> {
    let opts = MountOptions::new()
        .fs_name("myfs")
        .allow_other(true)
        .default_permissions(true);

    Session::new("/mnt/myfs".into(), opts)?
        .with_queue_depth(128)
        .run(MyFs)
}

Architecture

Session::new(mount_path, mount_options)
  |
  +-- fusermount3 (mount, receive /dev/fuse fd)

Session::run(fs)
  |
  +-- FUSE_INIT handshake (blocking read/write on /dev/fuse)
  +-- Filesystem::init(req, Arc<OwnedFd>)  (FS may build a FuseNotifier here)
  +-- one worker thread per CPU (each with compio Runtime + thread affinity)
  |     |
  |     +-- RingEntry buffers (page-aligned, mmap'd)
  |     +-- FuseRegister (register buffers with kernel)
  |     +-- Loop: dispatch request -> FuseCommitAndFetch (respond + fetch next)
  |
  +-- Filesystem::destroy()  (after all workers stop)

By default, one worker thread runs per CPU, each pinned to its own core with a compio single-threaded runtime. This matches the kernel's fuse-uring model (one queue per possible CPU, requests routed by task_cpu(caller)). Setting with_worker_count(n) collapses onto fewer threads while still covering every kernel qid.

Ring entries use page-aligned mmap buffers for the header (288 bytes) and payload (up to the filesystem's max_write, default 1MB, capped at 16MB by the session transport). The kernel fills request data directly into these buffers, and responses are written back in-place.

Filesystem Trait

Implement the Filesystem trait to handle FUSE operations. All methods are async (!Send, matching compio's single-threaded model) and default to returning ENOSYS. The trait itself is Send + Sync for sharing via Arc across worker threads.

Supported operations follow the low-level FUSE API:

Filesystem

Files

Directories

See the trait documentation for method signatures and semantics.

License

Licensed under Apache License, Version 2.0.