Crate rbit 

rbit

A comprehensive BitTorrent library implementing core BEP (BitTorrent Enhancement Proposals) specifications in pure Rust.

Overview

rbit provides building blocks for creating BitTorrent applications, including:

• Torrent parsing - Read .torrent files and magnet links
• Peer communication - Connect to and exchange data with peers
• Tracker protocols - Discover peers via HTTP and UDP trackers
• DHT - Trackerless peer discovery using a distributed hash table
• Storage management - Efficient disk I/O with piece verification
• Caching - Memory-efficient caching using the ARC algorithm

Quick Start

Parsing a torrent file

use rbit::Metainfo;

let torrent_data = std::fs::read("example.torrent")?;
let metainfo = Metainfo::from_bytes(&torrent_data)?;

println!("Name: {}", metainfo.info.name);
println!("Info hash: {}", metainfo.info_hash);
println!("Total size: {} bytes", metainfo.info.total_length);
println!("Piece count: {}", metainfo.info.piece_count());

for tracker in metainfo.trackers() {
    println!("Tracker: {}", tracker);
}

Parsing a magnet link

use rbit::MagnetLink;

let magnet = MagnetLink::parse(
    "magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&dn=Example"
)?;

println!("Info hash: {}", magnet.info_hash);
println!("Display name: {:?}", magnet.display_name);

Connecting to a peer

use rbit::{PeerConnection, PeerId, Message};
use std::net::SocketAddr;

let peer_addr: SocketAddr = "192.168.1.100:6881".parse()?;
let info_hash = [0u8; 20]; // Your torrent's info hash
let our_peer_id = PeerId::generate();

let mut conn = PeerConnection::connect(
    peer_addr,
    info_hash,
    *our_peer_id.as_bytes()
).await?;

// Express interest in downloading
conn.send(Message::Interested).await?;

// Wait for unchoke before requesting pieces
loop {
    match conn.receive().await? {
        Message::Unchoke => break,
        Message::Bitfield(bits) => println!("Peer has {} bytes of bitfield", bits.len()),
        _ => {}
    }
}

Announcing to an HTTP tracker

use rbit::{HttpTracker, TrackerEvent};

let tracker = HttpTracker::new("http://tracker.example.com/announce")?;

let response = tracker.announce(
    &[0u8; 20],           // info_hash
    &[0u8; 20],           // peer_id
    6881,                 // port
    0,                    // uploaded
    0,                    // downloaded
    1000,                 // left
    TrackerEvent::Started,
).await?;

println!("Found {} peers", response.peers.len());
println!("Re-announce in {} seconds", response.interval);

Using the DHT for trackerless peer discovery

use rbit::DhtServer;

let dht = DhtServer::bind(6881).await?;

// Bootstrap from well-known nodes
dht.bootstrap().await?;

// Find peers for a specific info hash
let info_hash = [0u8; 20];
let peers = dht.get_peers(info_hash).await?;

for peer in peers {
    println!("Found peer: {}", peer);
}

Supported BEPs

BEP	Description	Module
BEP-3	BitTorrent Protocol	peer, metainfo, tracker
BEP-5	DHT Protocol	dht
BEP-6	Fast Extension	peer
BEP-9	Magnet Links	metainfo
BEP-10	Extension Protocol	peer
BEP-11	Peer Exchange (PEX)	pex
BEP-14	Local Service Discovery	lsd
BEP-15	UDP Tracker Protocol	tracker
BEP-23	Compact Peer Lists	tracker
BEP-52	BitTorrent v2	metainfo, storage

Module Overview

• bencode - Bencode serialization format used throughout BitTorrent
• metainfo - Torrent file parsing, magnet links, and info hashes
• peer - Peer wire protocol for data exchange between clients
• tracker - HTTP and UDP tracker clients for peer discovery
• dht - Kademlia-based distributed hash table for trackerless operation
• pex - Peer Exchange for sharing peer lists between connected peers
• lsd - Local Service Discovery via multicast for LAN peers
• storage - Disk I/O management with piece verification
• cache - Memory caching for pieces and blocks using ARC

Feature Highlights

• Async/await - Built on tokio for efficient async I/O
• Zero-copy - Uses bytes::Bytes for efficient buffer handling
• Memory-safe - Pure Rust with no unsafe code in the public API
• Concurrent - Thread-safe primitives from parking_lot and dashmap

Architecture Notes

This library provides low-level building blocks rather than a complete BitTorrent client. You are responsible for:

• Coordinating peer connections and piece selection
• Managing download/upload state across peers
• Implementing rate limiting and choking algorithms
• Handling torrent lifecycle (start, pause, resume, remove)

For a complete client implementation, you would combine these modules with your own orchestration logic.

Re-exports

pub use bandwidth::BandwidthLimiter;

pub use bandwidth::RateLimiter;

pub use bencode::decode;

pub use bencode::encode;

pub use bencode::BencodeError;

pub use bencode::Value;

pub use cache::BlockCache;

pub use cache::BufferPool;

pub use cache::MemoryBudget;

pub use cache::PieceCache;

pub use dht::decode_compact_ip_port;

pub use dht::encode_compact_ip_port;

pub use dht::generate_secure_node_id;

pub use dht::is_local_network;

pub use dht::validate_node_id;

pub use dht::Bep42Config;

pub use dht::DhtError;

pub use dht::DhtMessage;

pub use dht::DhtServer;

pub use dht::Node;

pub use dht::NodeId;

pub use dht::RoutingTable;

pub use dht::BEP42_IPV4_MASK;

pub use dht::BEP42_IPV6_MASK;

pub use dht::BEP42_REQUIRED_VOTES;

pub use lsd::LsdAnnounce;

pub use lsd::LsdError;

pub use lsd::LsdService;

pub use metainfo::compute_piece_root;

pub use metainfo::compute_root;

pub use metainfo::extract_layer_hashes;

pub use metainfo::generate_proof_hashes;

pub use metainfo::hash_block;

pub use metainfo::hash_data_blocks;

pub use metainfo::verify_piece;

pub use metainfo::verify_piece_layer;

pub use metainfo::File;

pub use metainfo::FileTree;

pub use metainfo::FlattenedFile;

pub use metainfo::Info;

pub use metainfo::InfoHash;

pub use metainfo::InfoHashV1;

pub use metainfo::InfoHashV2;

pub use metainfo::MagnetLink;

pub use metainfo::MerkleTree;

pub use metainfo::Metainfo;

pub use metainfo::MetainfoError;

pub use metainfo::PieceHashes;

pub use metainfo::PieceLayers;

pub use metainfo::TorrentBuilder;

pub use metainfo::TorrentVersion;

pub use metainfo::DEFAULT_PIECE_LENGTH;

pub use metainfo::MERKLE_BLOCK_SIZE;

pub use metainfo::MIN_V2_PIECE_LENGTH;

pub use peer::generate_allowed_fast_set;

pub use peer::metadata_piece_count;

pub use peer::metadata_piece_size;

pub use peer::validate_hash_request;

pub use peer::Bitfield;

pub use peer::Block;

pub use peer::BlockRequest;

pub use peer::ChokingAlgorithm;

pub use peer::ChokingDecision;

pub use peer::ExtensionHandshake;

pub use peer::FastExtensionState;

pub use peer::Handshake;

pub use peer::HolepunchError;

pub use peer::HolepunchErrorCode;

pub use peer::HolepunchMessage;

pub use peer::HolepunchMessageType;

pub use peer::HolepunchState;

pub use peer::Message;

pub use peer::MessageId;

pub use peer::MetadataMessage;

pub use peer::MetadataMessageType;

pub use peer::PeerConnection;

pub use peer::PeerError;

pub use peer::PeerId;

pub use peer::PeerState;

pub use peer::PieceManager;

pub use peer::ProtocolMode;

pub use peer::HOLEPUNCH_EXTENSION_NAME;

pub use peer::METADATA_PIECE_SIZE;

pub use pex::PexFlags;

pub use pex::PexMessage;

pub use pex::PexPeer;

pub use storage::coalesce_blocks;

pub use storage::AllocationMode;

pub use storage::CachingDiskManager;

pub use storage::DiskManager;

pub use storage::FileEntry;

pub use storage::FlushRequest;

pub use storage::FlushResult;

pub use storage::IoQueue;

pub use storage::IoWorker;

pub use storage::MemoryStats;

pub use storage::PieceFileSpan;

pub use storage::PieceInfo;

pub use storage::StorageError;

pub use storage::TorrentStorage;

pub use storage::V2PieceMap;

pub use storage::WriteCoalescer;

pub use storage::WriteOp;

pub use storage::WritePriority;

pub use storage::WriteRegion;

pub use storage::WriteResult;

pub use tracker::AnnounceParams;

pub use tracker::AnnounceResponse;

pub use tracker::CompactPeer;

pub use tracker::HttpTracker;

pub use tracker::Peer;

pub use tracker::ScrapeResponse;

pub use tracker::TrackerClient;

pub use tracker::TrackerError;

pub use tracker::TrackerEvent;

pub use tracker::UdpTracker;

pub use upnp::PortMapper;

pub use upnp::PortMapping;

pub use upnp::Protocol;

pub use upnp::UpnpError;

pub use webseed::FileInfo as WebSeedFileInfo;

pub use webseed::GapAwarePieceSelector;

pub use webseed::TorrentInfo as WebSeedTorrentInfo;

pub use webseed::WebSeedClient;

pub use webseed::WebSeedError;

pub use webseed::WEBSEED_CONNECT_TIMEOUT;

pub use webseed::WEBSEED_GAP_FILL_THRESHOLD;

pub use webseed::WEBSEED_MAX_RETRIES;

pub use webseed::WEBSEED_READ_TIMEOUT;

Modules

bandwidth

Bandwidth limiting using token bucket algorithm.

bencode

Bencode encoding and decoding (BEP-3).

cache

Memory caching for pieces and blocks.

constants

Protocol constants and tuning parameters.

dht

Distributed Hash Table (BEP-5).

lsd

Local Service Discovery (BEP-14).

metainfo

Torrent metainfo handling (BEP-3, BEP-9, BEP-52).

peer

Peer wire protocol (BEP-3, BEP-6, BEP-10).

pex

Peer Exchange (BEP-11).

storage

Disk storage and I/O management.

tracker

Tracker protocols (BEP-3, BEP-15, BEP-23).

upnp

UPnP and NAT-PMP port mapping.

webseed

BEP-19: WebSeed - HTTP/FTP Seeding