grabbit
5d8bf52ae9
Full Rust implementation of the warpgate NAS cache proxy: - CLI: clap-based with subcommands (run, setup, status, cache, warmup, bwlimit, speed-test, config-init, log) - Config: TOML-based with env var override, preset templates - rclone: VFS mount args builder, config generator, RC API client - Services: Samba config gen, NFS exports, WebDAV serve args, systemd units - Deploy: dependency checker, filesystem validation, one-click setup - Supervisor: single-process tree managing rclone mount + smbd + WebDAV as child processes — no systemd dependency for protocol management Supervisor hardening: - ProtocolChildren Drop impl prevents orphaned processes on startup failure - Early rclone exit detection in mount wait loop (fail fast, not 30s timeout) - Graceful SIGTERM → 3s grace → SIGKILL (prevents orphaned smbd workers) - RestartTracker with 5-min stability reset and linear backoff (2s/4s/6s) - Shutdown signal checked during mount wait and before protocol start Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**Warpgate** is an SSD read-write caching proxy that accelerates remote NAS access for photographers, videographers, and remote workers. It sits between client devices and a remote NAS, providing local SSD caching with automatic write-back.
|
|
|
|
- **Current state**: Specification/PRD only (`warpgate-prd-v4.md`, written in Chinese). No implementation code exists yet.
|
|
- **MVP target**: Configuration files + bash deployment scripts for Linux (Ubuntu 22.04+ / Debian 12+)
|
|
- **Primary user**: Photographers using Lightroom over Tailscale to access a home NAS
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Clients (macOS/Windows/Linux/iPad)
|
|
│ SMB / NFS / WebDAV
|
|
▼
|
|
Warpgate Proxy (local network)
|
|
├─ Samba Server (SMB2/3 — primary, for Lightroom/Finder/Explorer)
|
|
├─ NFS Server (Linux clients)
|
|
├─ WebDAV Server (mobile)
|
|
└─ rclone VFS FUSE mount (/mnt/nas-photos)
|
|
└─ SSD Cache (rclone-managed LRU, dirty file protection)
|
|
│ SFTP over Tailscale/WireGuard
|
|
▼
|
|
Remote NAS (any brand supporting SFTP)
|
|
```
|
|
|
|
**Key design decisions:**
|
|
- All protocols share a single rclone FUSE mount point — one cache layer, no duplication
|
|
- rclone VFS with `--vfs-cache-mode full` handles both read-through caching and async write-back
|
|
- **Single-direction write constraint**: NAS doesn't change while user is away, eliminating conflict resolution
|
|
- Remote change detection uses rclone's `--dir-cache-time` (no brand-specific NAS APIs)
|
|
- Cache filesystem should be btrfs or ZFS (CoW + journal for crash consistency)
|
|
|
|
## Core Technologies
|
|
|
|
- **rclone** v1.65+ — VFS FUSE mount, read-through cache, async write-back, LRU eviction, RC API
|
|
- **Samba** 4.x — SMB shares for macOS/Windows clients
|
|
- **nfs-kernel-server** — NFS exports for Linux clients
|
|
- **FUSE** 3.x — userspace filesystem for rclone mount
|
|
- **Tailscale/WireGuard** — secure tunnel to remote NAS via SFTP
|
|
|
|
## PRD Structure (warpgate-prd-v4.md)
|
|
|
|
The PRD is comprehensive (836 lines, Chinese) with these sections:
|
|
- Sections 1-2: Product positioning, target users
|
|
- Section 3: System architecture with Mermaid diagrams
|
|
- Section 4: Features organized by priority (P0=MVP, P1=important, P2=future)
|
|
- Section 5: Data consistency model and scenario walkthroughs
|
|
- Sections 6-7: Remote change detection, cache behavior details
|
|
- Section 8: Full configuration parameter reference
|
|
- Section 9: Preset templates (photographer, video editor, office)
|
|
- Sections 10-11: Deployment requirements, risks
|
|
- Sections 12-15: Roadmap, paid services, anti-scope, glossary
|
|
|
|
## Feature Priority
|
|
|
|
- **P0 (MVP)**: Transparent multi-protocol proxy, read-through cache, cache consistency, remote change detection, cache space management, one-click deployment
|
|
- **P1**: WiFi setup AP + captive portal proxy, cache warm-up, CLI tools (`warpgate status/cache-list/warmup/bwlimit/...`), adaptive bandwidth throttling, connection resilience
|
|
- **P2**: WiFi AP sharing, web UI, NAS-side agent push, multi-NAS support, smart cache policies, Docker image, notifications
|
|
|
|
## Configuration
|
|
|
|
All behavior driven by environment variables — key groups:
|
|
- Connection: `NAS_HOST`, `NAS_USER`, `NAS_PASS`/`NAS_KEY_FILE`, `NAS_REMOTE_PATH`
|
|
- Cache: `CACHE_DIR`, `CACHE_MAX_SIZE`, `CACHE_MAX_AGE`, `CACHE_MIN_FREE`
|
|
- Read tuning: `READ_CHUNK_SIZE`, `READ_AHEAD`, `BUFFER_SIZE`
|
|
- Write-back: `VFS_WRITE_BACK` (default 5s), `TRANSFERS`
|
|
- Bandwidth: `BW_LIMIT_UP`, `BW_LIMIT_DOWN`, `BW_ADAPTIVE`
|
|
- Protocols: `ENABLE_SMB`, `ENABLE_NFS`, `ENABLE_WEBDAV`
|
|
- Directory cache: `DIR_CACHE_TIME`
|
|
|
|
## Language & Conventions
|
|
|
|
- PRD and product context are in **Simplified Chinese**
|
|
- Product name is **Warpgate** (English)
|
|
- NAS brand-agnostic: must work with Synology, QNAP, TrueNAS, DIY — SFTP only, no vendor APIs
|
|
- Deployment targets Linux only; clients are cross-platform
|