async-fusex 0.1.2

Async fuse library to make fuse develop easier
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# async-fusex

[![Crates.io](https://img.shields.io/crates/v/async-fusex.svg)](https://crates.io/crates/async-fusex)
[![Documentation](https://docs.rs/async-fusex/badge.svg)](https://docs.rs/async-fusex)
[![License](https://img.shields.io/crates/l/async-fusex.svg)](LICENSE)

An async-friendly Rust library for building FUSE (Filesystem in Userspace) filesystems. Origin code is taken from DatenLord.

## Overview

async-fusex provides a high-level, async/await-based abstraction over the FUSE kernel interface, making it easy to develop custom filesystems that run in userspace. Built on top of Tokio, it enables efficient concurrent handling of filesystem requests.

## Features

- **Async/Await Support**: Built on Tokio for non-blocking, concurrent request handling
- **Full FUSE Protocol Support**: Supports FUSE ABI versions 7.8 through 7.31
- **Complete Filesystem Operations**:
  - File operations: create, read, write, open, release, flush, fsync
  - Directory operations: mkdir, rmdir, opendir, readdir, releasedir
  - Metadata: getattr, setattr, lookup, statfs
  - Links: symlink, hardlink, rename, unlink
  - Extended attributes: setxattr, getxattr, listxattr, removexattr
  - POSIX file locking: getlk, setlk
- **Multi-threaded Request Handling**: Configurable FUSE device reader threads with buffer pooling
- **Graceful Shutdown**: Cancellation token support for clean unmounting

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
async-fusex = "0.1"
```

## Usage

Implement the `FileSystem` trait and create a session:

```rust
use async_fusex::{FileSystem, Session, Request, ReplyEntry, ReplyAttr};
use async_trait::async_trait;
use tokio_util::sync::CancellationToken;
use std::path::Path;

struct MyFilesystem;

#[async_trait]
impl FileSystem for MyFilesystem {
    async fn init(&self, req: &Request<'_>) -> nix::Result<()> {
        // Initialize your filesystem
        Ok(())
    }

    async fn lookup(
        &self,
        req: &Request<'_>,
        parent: u64,
        name: &str,
        reply: ReplyEntry<'_>,
    ) -> nix::Result<usize> {
        // Handle directory entry lookup
        // ...
    }

    async fn getattr(
        &self,
        req: &Request<'_>,
        ino: u64,
        reply: ReplyAttr<'_>,
    ) -> nix::Result<usize> {
        // Return file attributes
        // ...
    }

    // Implement other operations as needed...
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let fs = MyFilesystem;
    let mountpoint = Path::new("/mnt/myfs");

    let session = async_fusex::new_session(mountpoint, fs).await?;
    let token = CancellationToken::new();

    session.run(token).await?;
    Ok(())
}
```

## Architecture

```
User Code (FileSystem Implementation)
        │
        ▼
FileSystem Trait (async interface)
        │
        ▼
    Session (FUSE session manager)
        │
        ▼
FUSE Device Reader Threads + Tokio Runtime
        │
        ▼
   /dev/fuse (Kernel Interface)
```

## Requirements

- Linux with FUSE support
- Rust 2024 edition

## get your fuse api version

```
dmesg | grep fuse

[    2.095512] fuse: init (API version 7.39)
```

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.