Torrex

A high-performance BitTorrent client library and download server built in Rust from scratch, featuring a REST API, WebSocket progress streaming, and a web dashboard.

Demo: Link:

Features

• Torrent File Parsing: Decode .torrent files using built-in Bencode parsing (supporting both single-file and multi-file torrents).
• Local .torrent File Upload: Upload .torrent files directly from your computer through the web UI or API (POST /initial_info_upload).
• Download .torrent from Web URL: Fetch and load .torrent files directly from remote HTTP/HTTPS links (GET /initial_info_url).
• Magnet Link Support: Resolve magnet links via Extended Metadata Exchange (BEP 09 / BEP 10).
• HTTP REST API: Built with actix-web for managing downloads (start, pause, resume, stop).
• Web Dashboard: Minimalist, zero-dependency web frontend to manage downloads, upload torrents, and track progress visually.
• Real-time Progress: WebSocket integration for streaming live download progress, speed, and peer stats to clients.
• Peer Discovery: Fetch peer IPs from standard HTTP trackers. (Note: UDP trackers and DHT are not supported yet).
• Swarm Management: Connect to multiple peers concurrently to download pieces and verify SHA-1 hashes.

---

Getting Started

Option 1: Running with Docker Compose (Recommended)

Run both the Torrex API server and the Web Dashboard with a single command:

1. Clone the repository:

   git clone https://github.com/your-username/torrex.git
   cd torrex

2. Start the containers:

   docker compose up -d --build

3. Access the services:

   • Web Dashboard: http://localhost:3000
   • HTTP API Server: http://localhost:7878/torrex/api/v1
   • Downloaded Files: Automatically saved to the ./downloads folder on your host machine.

4. View logs or stop:

   # View live logs
   docker compose logs -f
   
   # Stop services
   docker compose down

---

Option 2: Running Natively (Cargo)

Prerequisites

• Rust toolchain (cargo, rustc 1.85+)

1. Build the workspace:

   cargo build --release

2. Start the API server (runs on port 7878 by default):

   cargo run -p torrex-api

   The server will be live at http://127.0.0.1:7878.

3. Open the Web Frontend: Open torrex-frontend/index.html directly in your browser, or serve it locally:

   cd torrex-frontend
   python3 -m http.server 3000

   Then open http://localhost:3000.

---

Web Dashboard & GUI Usage

The web dashboard allows you to load and manage downloads with four convenient methods:

1. Option A: Magnet Links — Paste any magnet link with an HTTP tracker.
2. Option B: Upload Local .torrent File — Drag and drop or browse to select a .torrent file from your computer.
3. Option C: Download .torrent from Web URL — Paste any direct .torrent link from the web.
4. Option D: Server File Path — Specify a path to a .torrent file on the server.

Once loaded, click Start Download to stream real-time progress, download speed, and connected peers.

---

Quick Test Downloads

Why these links? Torrex currently discovers peers via HTTP trackers. The CodeCrafters test tracker (bittorrent-test-tracker.codecrafters.io) is purpose-built for BitTorrent client testing — it responds reliably and never chokes connections, making it the best starting point for testing Torrex:

Verified Test Links

Source	Type	Link / URL
magnet1.gif	Magnet Link	magnet:?xt=urn:btih:ad42ce8109f54c99613ce38f9b4d87e70f24a165&dn=magnet1.gif&tr=http%3A%2F%2Fbittorrent-test-tracker.codecrafters.io%2Fannounce
magnet2.gif	Magnet Link	magnet:?xt=urn:btih:3f994a835e090238873498636b98a3e78d1c34ca&dn=magnet2.gif&tr=http%3A%2F%2Fbittorrent-test-tracker.codecrafters.io%2Fannounce
magnet3.gif	Magnet Link	magnet:?xt=urn:btih:c5fb9894bdaba464811b088d806bdd611ba490af&dn=magnet3.gif&tr=http%3A%2F%2Fbittorrent-test-tracker.codecrafters.io%2Fannounce
sample.torrent	Local .torrent	torrex-lib/sample.torrent
sample.torrent	Remote Web URL	https://raw.githubusercontent.com/sauhardh/torrex/main/torrex-lib/sample.torrent

---

API Reference

The API is exposed under the /torrex/api/v1 path prefix.

1. Check API Status

• Endpoint: GET /
• Response:

  { "success": "true", "message": "Torrex API is running" }

2. Upload Local .torrent File

Upload a .torrent file directly as binary data from the client or browser.

• Endpoint: POST /initial_info_upload
• Content-Type: application/x-bittorrent (or application/octet-stream)
• Body: Binary contents of .torrent file
• Response:

  {
    "success": "true",
    "uuid": "<download-uuid>",
    "name": "filename.iso",
    "length": 104857600
  }

3. Load .torrent File from Web URL

Download and parse a .torrent file directly from a remote HTTP/HTTPS URL.

• Endpoint: GET /initial_info_url
• Query Parameters:
  • url: Direct HTTP/HTTPS link to the .torrent file.
• Example: GET /torrex/api/v1/initial_info_url?url=https://raw.githubusercontent.com/sauhardh/torrex/main/torrex-lib/sample.torrent
• Response:

  {
    "success": "true",
    "uuid": "<download-uuid>",
    "name": "sample.txt",
    "length": 92160
  }

4. Load .torrent File from Server Path

Parse and load a local server .torrent file to prepare for downloading.

• Endpoint: GET /initial_info_metafile
• Query Parameters:
  • filepath: Path to the .torrent file on the server.
• Example: GET /torrex/api/v1/initial_info_metafile?filepath="torrex-lib/sample.torrent"

5. Load Magnet Link

Parse and resolve a magnet link to prepare for downloading.

• Endpoint: GET /initial_info_magnet
• Query Parameters:
  • url: The full magnet URL.
• Example: GET /torrex/api/v1/initial_info_magnet?url=magnet:?xt=urn:btih:...

6. Start Download

Initiate the download process for a previously loaded torrent or magnet link.

• Endpoint: POST /start_download
• Content-Type: application/json
• Body:

  {
    "uuid": "<download-uuid>",
    "destination": "/optional/custom/save/path"
  }

  (If destination is omitted, the downloaded file will be saved to ./downloads or the system temporary directory).

7. Stream Download Progress (WebSocket)

Connect via WebSocket to stream real-time download progress events.

• Endpoint: WS /ws/download/{uuid}
• Example: ws://127.0.0.1:7878/torrex/api/v1/ws/download/<download-uuid>

8. Pause Download

Pause an active download manager.

• Endpoint: GET /pause?uuid=<download-uuid>

9. Resume Download

Resume a paused download.

• Endpoint: GET /resume?uuid=<download-uuid>

10. Stop Download

Stop a download entirely and close connections.

• Endpoint: GET /stop?uuid=<download-uuid>

---

System Architecture Flow Diagram

The following diagram illustrates the high-level architecture and data flow between the client, Torrex API, and the Torrex library:

---

Todo

• Extend support for various .torrent file metainfo.
• Add UDP tracker support for peer discovery (currently supports HTTP trackers).
• Add support for DHT (Distributed Hash Table) and trackerless magnets.
• Support multi-chunk ut_metadata extended metadata downloading.
• Heavy refactor needed for connection module.
• Web frontend dashboard with file upload and remote URL loading.
• Complete Event announcement to tracker.
• Implement support for seeding.
• Fully implement download manager for pausing, resuming, and stopping downloads.