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)
```

- **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** / **furumi-mount-macos** — mounts the remote directory locally via FUSE (read-only)

## Quick Start

```bash
# 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 with `macFUSE` installed (for macOS client)
- Rust 2024 edition

## License

MIT