grabbit 5d8bf52ae9 Add warpgate MVP implementation with hardened supervisor

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>

2026-02-17 23:29:17 +08:00

3.9 KiB

Raw Blame History

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

3.9 KiB Raw Blame History