88 lines
4.6 KiB
Markdown
88 lines
4.6 KiB
Markdown
# Furumi-ng: Distributed Virtual File System
|
|
|
|
## Project Overview
|
|
This document describes the architectural vision and technical requirements for a modern, high-performance distributed virtual file system built in Rust. The system allows a remote client to connect to a server with authorization, list directories recursively, and mount the remote directory as a local virtual file system. It is designed as a faster, more reliable, and modern alternative to WebDAV.
|
|
|
|
## Core Requirements
|
|
1. **Cross-Platform Support:** Initial support for Linux and macOS. The backend server and client mounting logic must be logically separated so that new OS support (e.g., Windows) can be added solely by writing a new mount layer without altering the core backend or client networking code.
|
|
2. **Read-Only First:** The initial implementation will support read-only operations, with an architecture designed to easily accommodate write operations in subsequent phases.
|
|
3. **Memory Safety & Reliability:** The entire stack (server, shared client core, and mount layers) will be implemented in **Rust** to leverage its strict compiler guarantees, memory safety, and high-performance asynchronous ecosystem.
|
|
|
|
## High-Level Architecture
|
|
|
|
The architecture is divided into three main components: Server, Shared Client Core, and OS-Specific Mount Layers.
|
|
|
|
### 1. Transport & Protocol (gRPC)
|
|
- **Protocol:** gRPC over HTTP/2.
|
|
- **Why gRPC:** Provides strong typing via Protobuf, multiplexing, and robust streaming capabilities which are essential for transferring large file chunks efficiently.
|
|
- **Security:** Requires TLS (e.g., mTLS or JWT via metadata headers) to secure data in transit.
|
|
|
|
### 2. Server (Linux Backend)
|
|
The server role is to expose local directories to authorized clients safely and asynchronously.
|
|
- **Runtime:** `tokio` for non-blocking I/O.
|
|
- **Security Validation:** Strict path sanitization (protection against Path Traversal). The server restricts clients strictly to their allowed document root.
|
|
- **VFS Abstraction:** Backend logic will be abstracted behind a Rust trait. This allows future swapping of the storage backend (e.g., Local Disk -> AWS S3, or In-Memory for testing) without changing the gRPC transport layer.
|
|
|
|
### 3. Client Architecture
|
|
To maximize code reuse and maintainability, the client is split into two layers:
|
|
|
|
#### A. Shared Client Core (Cross-Platform)
|
|
A Rust library containing all OS-agnostic logic:
|
|
- **Network Client:** Handles gRPC connections, request retries, backoff strategies, and error handling.
|
|
- **VFS Cache:** An in-memory cache for metadata (TTL-based) to dramatically reduce network latency for high-frequency `stat` / `getattr` calls generated by file managers or terminals.
|
|
- **VFS Translator:** Maps VFS operations into remote gRPC RPC calls.
|
|
|
|
#### B. OS-Specific Mount Layer
|
|
Thin executable wrappers that consume the Shared Client Core and handle OS integration:
|
|
- **Linux:** Uses the `fuser` crate (binds to `libfuse`) to mount and handle events from `/dev/fuse`.
|
|
- **macOS:** Can utilize `macFUSE` via the `fuser` crate initially. Future iterations may explore native Apple `FileProvider` frameworks using FFI to bypass third-party kext requirements.
|
|
- **Windows (Future):** Will wrap libraries like `WinFSP` or `dokany` to integrate with the Windows internal VFS.
|
|
|
|
## API Design (Read-Only Foundation)
|
|
The initial Protobuf specification will involve core remote procedure calls (RPCs) to support read-only mode:
|
|
|
|
```protobuf
|
|
syntax = "proto3";
|
|
package virtualfs;
|
|
|
|
message PathRequest {
|
|
string path = 1;
|
|
}
|
|
|
|
message AttrResponse {
|
|
uint64 size = 1;
|
|
uint32 mode = 2; // Permissions and file type
|
|
uint64 mtime = 3; // Modification time
|
|
// ... other standard stat attributes
|
|
}
|
|
|
|
message DirEntry {
|
|
string name = 1;
|
|
uint32 type = 2; // File or Directory
|
|
}
|
|
|
|
message ReadRequest {
|
|
string path = 1;
|
|
uint64 offset = 2;
|
|
uint32 size = 3;
|
|
}
|
|
|
|
message FileChunk {
|
|
bytes data = 1;
|
|
}
|
|
|
|
service RemoteFileSystem {
|
|
// Get file or directory attributes (size, permissions, timestamps). Maps to stat/getattr.
|
|
rpc GetAttr (PathRequest) returns (AttrResponse);
|
|
|
|
// List directory contents. Uses Server Streaming to handle massively large directories efficiently.
|
|
rpc ReadDir (PathRequest) returns (stream DirEntry);
|
|
|
|
// Read chunks of a file. Uses Server Streaming for efficient chunk delivery based on offset/size.
|
|
rpc ReadFile (ReadRequest) returns (stream FileChunk);
|
|
}
|
|
```
|
|
|
|
## Future Expansion: Write Operations
|
|
The design ensures seamless expansion to a read-write file system. Future RPCs such as `CreateFile`, `MkDir`, `Remove`, `Rename`, and `WriteChunk` (utilizing Client Streaming or Bi-directional Streaming in gRPC) can be added without restructuring the foundational architecture.
|