ProtoTorrent

ProtoTorrent is a CLI-first BitTorrent client with an in-progress React web interface.

It currently provides:

• A working Node.js torrent downloader (tracker discovery, peer connections, piece/block download, hash verification, file writes).
• A frontend shell (/ landing + /upload) that is being prepared for backend integration.
• Experimental Python scripts in core/ that document earlier protocol exploration.

What This Repository Is

This project is a practical implementation of the BitTorrent download pipeline:

• Parse a .torrent file
• Compute info hash
• Discover peers via HTTP/HTTPS/UDP trackers
• Handshake and exchange peer-wire messages
• Request blocks, verify SHA-1 piece hashes
• Persist data to disk

The long-term direction is a fullstack local torrent manager: Node service + React UI.

Current Status

Implemented now

• Fully runnable CLI downloader from server/cli.js
• Interactive terminal controls (pause/resume/quit)
• Piece-level integrity verification and progress tracking
• Single-file and multi-file write mapping support
• Frontend layout and upload page UX scaffold

Not implemented yet

• Backend HTTP API for the web UI (server/index.js and server/api/api.js are empty)
• Real frontend-to-backend download requests
• Magnet link execution path
• Persistent download job database/history

Tech Stack

• Backend runtime: Node.js (ES modules)
• Backend libs: bencode, express (Express not wired yet)
• Frontend: React 19 + Vite 7 + Tailwind CSS 4 + React Router
• Legacy/experimental: Python scripts in core/

Project Structure

ProtoTorrent/
|-- client/                     # React frontend
|   |-- src/
|   |   |-- components/layout/  # Navbar, Footer, Layout shell
|   |   |-- pages/              # Landing and Upload pages
|   |   |-- App.jsx             # Route map
|   |   `-- main.jsx            # BrowserRouter bootstrap
|   `-- package.json
|-- server/                     # Torrent engine and CLI
|   |-- cli.js                  # Main executable entrypoint
|   |-- service/
|   |   |-- tracker.js          # HTTP/HTTPS/UDP tracker client
|   |   |-- peer.js             # Peer TCP state machine
|   |   |-- pieces.js           # Piece/block scheduling + verification
|   |   |-- file-handler.js     # Piece-to-file disk writer
|   |   |-- message.js          # Peer-wire message codecs
|   |   `-- download.js         # Orchestrator
|   |-- index.js                # Reserved for API server (currently empty)
|   `-- api/api.js              # Reserved for API routes (currently empty)
|-- core/                       # Python prototypes and protocol experiments
|-- torrent/                    # Sample .torrent inputs
`-- downloads/                  # Local downloaded output

Quick Start

1) Run the CLI downloader

From repository root:

cd server
npm install
node cli.js <path_to_torrent_file> --output <path_to_store_download> --max-peers 30

Useful flags:

• --info print torrent metadata and exit
• --output <dir> output directory (default ./downloads)
• --max-peers <n> maximum concurrent peer connections
• --no-prompt skip interactive concurrency prompt
• --quiet minimal output

During download (TTY mode):

• p pause/resume
• q stop and exit
• Ctrl+C stop and exit

2) Run the frontend

From repository root:

cd client
npm install
npm run dev

Open the local Vite URL (typically http://localhost:5173).

Note: the Upload page currently uses a mock handler and does not call backend APIs yet.

How the Backend Download Flow Works

1. cli.js parses arguments and opens the .torrent.
2. tracker.js asks tracker(s) for peers (HTTP/HTTPS/UDP, with announce-list fallback).
3. download.js creates peer connections and starts the download loop.
4. peer.js handles handshake and peer-wire messages (bitfield, unchoke, piece, etc.).
5. pieces.js decides the next missing block and verifies completed piece hashes.
6. file-handler.js maps piece segments into file offsets and writes to disk.

Frontend Overview

Current routes:

• / -> marketing/landing page
• /upload -> upload/magnet input interface (UI-only for now)

Current UI modules:

• Layout with fixed Navbar and Footer
• Landing section with feature highlights
• Upload page with tabs for .torrent file and magnet link input

Python core/ Folder (Experimental)

The core/ directory contains earlier Python experiments:

• parser.py: custom bencode encode/decode
• calculate_hash.py: info hash generation
• find_peers.py: tracker peer discovery workflow

These scripts are useful for learning/prototyping but are not the active runtime used by the Node CLI.

Development Notes

• Frontend and backend are currently separate processes.
• Express is installed in server but API endpoints are not wired yet.
• The repository includes large local artifacts in downloads/ and torrent/ for testing.

Roadmap (Suggested Next Milestones)

• Implement backend API (start, status, pause, resume, cancel, list)
• Connect frontend upload flow to real backend requests
• Add streaming/polling progress updates in UI
• Add automated tests for parser/tracker/piece logic
• Add multi-download session management

Safety and Legal

Use only torrents you have the legal right to download/share. You are responsible for how you use this software.