torrent/CLAUDE.md

CLAUDE.md — Torrent Faker

Project Purpose

Torrent Faker is a fake BitTorrent seeder that announces upload stats to real trackers without transferring any actual data. It simulates realistic seeding behavior to satisfy tracker requirements.

Tech Stack

Layer	Technology
Runtime	Bun
Language	TypeScript (strict, ESNext)
HTTP	Hono 4.x
Config	YAML (js-yaml) + Zod validation
Linting	Biome
Frontend	Svelte 5 + Vite (in ui/)

Project Structure

src/
  index.ts                  # Entry point: loads config, starts registry + HTTP server
  cli/index.ts              # CLI client (talks to running API)
  config/Config.ts          # Zod schema + config loader
  config/config.default.yml # Default config values
  api/
    server.ts               # Hono app, mounts routes, serves UI
    SeederRegistry.ts       # Central in-memory store for all FakeSeeder instances
    response.ts             # HTTP response helpers
    routes/
      torrents.ts           # GET/POST/DELETE /api/torrents
      status.ts             # GET /api/status, GET /api/status/stream (SSE)
      config.ts             # GET/PATCH /api/config
  core/
    bencode/                # Bencode decoder + encoder
    client/
      ClientProfile.ts      # Profile interface + peer ID generation
      profiles/             # qbittorrent.ts, transmission.ts
    seeder/
      FakeSeeder.ts         # Announce loop, lifecycle (started → running → stopped)
      SpeedSimulator.ts     # Gaussian noise + burst/stall events
    torrent/TorrentFile.ts  # Parses .torrent, extracts info hash + tracker list
    tracker/
      ITracker.ts           # Tracker interface
      HttpTracker.ts        # HTTP/HTTPS tracker (BEP 3)
      UdpTracker.ts         # UDP tracker (BEP 15)
      TrackerResponse.ts    # Response types
config/config.yml           # Runtime config (gitignored defaults)
torrents/                   # Drop .torrent files here
ui/                         # Svelte frontend (built to ui/dist/)

TypeScript Path Aliases

@core/*   → src/core/*
@api/*    → src/api/*
@config/* → src/config/*

Dev Commands

bun run dev          # Start server (hot-reload)
bun run start        # Start server (production)
bun run cli <cmd>    # Run CLI against running server
bun test             # Run tests
bun run lint         # Biome check
bun run format       # Biome format --write
bun run build:ui     # Build Svelte UI to ui/dist/
bun run build        # Full build (UI only for now)

Architecture

SeederRegistry
  └── FakeSeeder (one per torrent)
        ├── SpeedSimulator  — random base rate, ±15% jitter, burst/stall
        └── Tracker[]
              ├── HttpTracker (BEP 3)
              └── UdpTracker  (BEP 15)

• SeederRegistry is the single source of truth; routes call it, not FakeSeeder directly.
• FakeSeeder extends EventEmitter; emits announce, stopped, stateChange.
• SeederRegistry subscribes to seeder events and pushes SSE updates to connected clients.
• Announce lifecycle: first call sends event=started, subsequent calls send event= (empty), final call on removal sends event=stopped.

Configuration

Runtime config file: config/config.yml (copied from src/config/config.default.yml).

Field	Default	Description
port	3000	HTTP server port (UI + API)
announcePort	6881	Port reported to trackers
minUploadRateBytesPerSec	524288	Min simulated speed (512 KB/s)
maxUploadRateBytesPerSec	2097152	Max simulated speed (2 MB/s)
clientProfile	qbittorrent	Client to impersonate
torrentsDir	./torrents	Directory for .torrent files
autoLoad	true	Load all torrents in dir on startup

Config is Zod-validated at startup. PATCH /api/config persists changes back to config.yml.

API Endpoints

Method	Path	Description
GET	/api/torrents	List all active torrents
POST	/api/torrents	Upload .torrent file (multipart)
GET	/api/torrents/:hash	Stats + announce history for one
DELETE	/api/torrents/:hash	Stop seeding and remove
GET	/api/status	Global stats snapshot
GET	/api/status/stream	SSE stream (stats, torrent, ping)
GET	/api/config	Current config
PATCH	/api/config	Update mutable config fields
GET	/*	Serve Svelte SPA from ui/dist/

SSE Event Types

• stats — global stats on every change
• torrent — per-torrent state update on announce/change
• torrents — full list on initial connection
• ping — keep-alive every 30s

CLI

Requires a running server. Reads TORRENT_FAKER_API env var (default: http://localhost:3000).

bun run cli add <file.torrent>   # Start fake-seeding
bun run cli list                 # List active torrents
bun run cli remove <hash>        # Stop and remove (hash prefix OK)
bun run cli status               # Global stats

Client Profiles

Profile	Peer ID prefix	User-Agent
qbittorrent	-qB4520-	qBittorrent/4.5.2
transmission	-TR3000-	Transmission/3.00

Each seeder generates a unique 20-byte peer ID per session.

Code Conventions

• Biome enforces formatting; run bun run format before committing.
• Zod schemas for all external input (config file, API request bodies).
• No ORM — binary protocols implemented manually (bencode, UDP packets).
• EventEmitter pattern for seeder → registry communication.
• SSE for live UI updates (no WebSockets, no polling).