rain

rain

High-performance BitTorrent client and library in Go. Running in production at put.io since 2019, processing thousands of torrents daily with minimal system resources.

Features

Protocol Support

• BEP-003: Core protocol
• BEP-006: Fast extension
• BEP-009: Magnet links
• BEP-012: Multiple trackers
• BEP-015: UDP trackers
• BEP-005: DHT
• BEP-011: PEX
• BEP-019: WebSeed
• Message stream encryption

Client Features

• Fast resuming with BoltDB persistence
• IP blocklist support
• JSON-RPC 2.0 server & client
• Interactive console UI
• Tools for creating & reading .torrent files
• Resource management (connections, memory, file handles)

Screenshot

Installing

macOS

brew install cenkalti/rain/rain

Other Platforms

Download the latest binary from the releases page.

From Source

go install github.com/cenkalti/rain/v2@latest

Quick Start

Rain operates as a client-server application with a single binary.

1. Start the Server

# Start Rain server (using default config)
rain server

2. Add Your First Torrent

# Add a magnet link
rain client add "magnet:?xt=urn:btih:..."

# Or add a torrent file
rain client add /path/to/file.torrent

# Or add torrent from URL
rain client add "https://example.com/file.torrent"

3. Monitor Progress

# List all torrents
rain client list

# Get stats for a torrent
rain client stats --id <torrent-id>

# Watch progress in console UI
rain client console

4. Control Downloads

# Pause a torrent
rain client stop --id <torrent-id>

# Resume a torrent
rain client start --id <torrent-id>

# Remove completed torrent
rain client remove --id <torrent-id>

Use rain help or rain help <command> for detailed information.

Usage as library

Rain can be embedded in Go applications as a powerful BitTorrent library.

import "github.com/cenkalti/rain/v2/torrent"

// Create session with default config
ses, _ := torrent.NewSession(torrent.DefaultConfig)
defer ses.Close()

// Add a magnet link
magnetLink := "magnet:?xt=urn:btih:..."
tor, _ := ses.AddURI(magnetLink, nil)

// Monitor download progress
for range time.Tick(time.Second) {
	s := tor.Stats()
	log.Printf("Status: %s, Downloaded: %d, Peers: %d", s.Status.String(), s.Bytes.Completed, s.Peers.Total)
}

More complete example can be found under handleDownload function at main.go file.

See package documentation for complete API.

Configuration

Rain works out of the box with sensible defaults, but can be customized with a YAML configuration file.

Basic Configuration

Default config location: ~/rain/config.yaml (defaults are used if file is missing)

Custom config:

rain server --config /path/to/config.yaml

Complete Reference

For all available configuration options, see config.go.

Note: Configuration keys use dash-separated format (e.g., port-begin, not portbegin) starting from v2.

Architecture

Rain's architecture is designed specifically for high-performance server environments, with several unique characteristics:

Unique Design Decisions

Separate Port Per Torrent: Unlike other BitTorrent clients, Rain allocates a separate peer port for each torrent. This enables:

• Multiple downloads of the same torrent for different accounts on private trackers
• Accurate ratio tracking per account
• Better isolation between torrents

Server-First Design: Rain prioritizes server-side performance over desktop features:

• Optimized for hundreds of concurrent torrents
• Minimal system resource usage
• Production-ready stability (running at put.io since 2019)
• JSON-RPC API for remote management

Project Structure

rain/
├── torrent/       # Core BitTorrent session and torrent logic
├── rainrpc/       # Shared types for JSON-RPC 2.0 API
├── internal/      # Internal packages (networking, protocol, storage, etc.)
└── main.go        # Entry point

Component Architecture

Rain follows a layered architecture with clear separation of concerns:

Core Layer:

• torrent/session.go - Main orchestrator managing torrents, DHT, and shared resources
• torrent/torrent.go - Individual torrent lifecycle management

Protocol Layer:

• BitTorrent protocol implementation (internal/peerprotocol/)
• Tracker communication (internal/tracker/, internal/announcer/)
• DHT and PEX support (internal/dht/, internal/pex/)

Network Layer:

• Connection management (internal/peer/, internal/peerconn/)
• Message Stream Encryption (internal/mse/)
• Resource limiting (internal/resourcemanager/)

Storage Layer:

• Piece management (internal/piece/, internal/piececache/)
• File I/O optimization (internal/storage/)
• Resume data persistence with BoltDB

Missing features

The following features are not implemented in Rain. This list should not be considered a roadmap, as these features are intentionally omitted either because they don't provide sufficient value for our use case at put.io, or because implementing them would add unnecessary complexity to the codebase. We prefer to maintain a focused and efficient implementation that serves our specific needs.

• BEP-007: IPv6 tracker extension
• BEP-032: IPv6 extension for DHT
• BEP-029: uTorrent transport protocol
• BEP-016: Superseeding
• BEP-017: HTTP seeding
• BEP-030: Merkle tree torrent extension
• uPnP port forwarding
• Selective downloading
• Sequential downloading

Contributing

Rain is primarily developed to serve the specific requirements of put.io. Due to this focused purpose, feature requests that do not align with put.io's needs will likely be rejected. Additionally, we maintain a strong preference for simplicity in implementation. Complex solutions, even if technically superior, will generally not be accepted. Please keep these guidelines in mind when submitting issues or pull requests.

Star History