furumi-ng/README.md

Furumi-ng

Remote filesystem over encrypted gRPC. Mount a directory from a remote server as a local folder via FUSE.

Designed for streaming media (video, music) over the network.

Architecture

furumi-server (gRPC + TLS)  ←→  furumi-client-core  ←→  furumi-mount-{linux,macos} (FUSE / NFS)

• furumi-server — exposes a directory over gRPC with auto-TLS, Bearer token auth, and Prometheus metrics
• furumi-client-core — cross-platform gRPC client library with attribute caching
• furumi-mount-linux — mounts the remote directory locally via FUSE (read-only)
• furumi-mount-macos — mounts the remote directory locally via a local NFS server (read-only)

Quick Start

# Build
cargo build --release --workspace

# Server — auto-generates TLS certificate, saves it for client
./target/release/furumi-server \
  --root /path/to/media \
  --token mysecrettoken \
  --tls-cert-out /tmp/furumi-ca.pem

# Client (Linux) — automatically uses TLS, trusts server certificate
./target/release/furumi-mount-linux \
  --server server-ip:50051 \
  --token mysecrettoken \
  --mount /mnt/remote

# Client (macOS)
./target/release/furumi-mount-macos \
  --server server-ip:50051 \
  --token mysecrettoken \
  --mount /Volumes/remote

# Use it
ls /mnt/remote
mpv /mnt/remote/video.mkv

Encryption

TLS is enabled by default. The server auto-generates a self-signed certificate on each start — no manual cert management required. The client automatically trusts the server's certificate for encryption.

To disable TLS (not recommended): --no-tls on both server and client.

Configuration

All options can be set via CLI flags or environment variables.

Server

Flag	Env	Default	Description
--bind	FURUMI_BIND	0.0.0.0:50051	gRPC listen address
--root	FURUMI_ROOT	.	Directory to expose
--token	FURUMI_TOKEN	(empty, auth off)	Bearer token
--metrics-bind	FURUMI_METRICS_BIND	0.0.0.0:9090	Prometheus endpoint
--no-tls	—	false	Disable TLS

Client

Flag	Env	Default	Description
--server	FURUMI_SERVER	0.0.0.0:50051	Server address
--token	FURUMI_TOKEN	(empty)	Bearer token
--mount	FURUMI_MOUNT	—	Mount point directory
--no-tls	—	false	Disable TLS

Prometheus Metrics

Available at http://<metrics-bind>/metrics:

• furumi_grpc_requests_total — request count by method and status
• furumi_grpc_request_duration_seconds — request latency histogram
• furumi_bytes_read_total — total bytes streamed
• furumi_active_streams — current streaming connections
• furumi_file_open_errors_total — file access errors
• furumi_auth_failures_total — authentication failures

Requirements

• Linux with libfuse3-dev and pkg-config (for client)
• macOS (uses built-in NFS client)
• Rust 2024 edition

License

MIT