torrent

High-level user-facing BitTorrent library. Provides async I/O, session management, tracker communication, and file storage — built on top of torrent-core.

Modules

Quick Start

use std::path::PathBuf;
use torrent::session::{Session, SessionConfig};

#[tokio::main]
async fn main() -> Result<(), torrent::error::Error> {
    let config = SessionConfig {
        download_dir: PathBuf::from("./downloads"),
        ..Default::default()
    };
    let session = Session::new(config).await?;

    let data = std::fs::read("ubuntu-24.04.torrent")?;
    let info_hash = session.add_torrent_bytes(&data).await?;

    loop {
        let status = session.torrent_status(&info_hash).await?;
        println!("{:.1}% — {} peers", status.progress * 100.0, status.num_peers);
        if status.progress >= 1.0 {
            println!("Download complete!");
            break;
        }
        tokio::time::sleep(tokio::time::Duration::from_secs(5)).await;
    }

    session.remove_torrent(&info_hash).await?;
    Ok(())
}

Re-exports from torrent-core

All commonly used core types are re-exported so you only need torrent as a dependency:

use torrent::bencode::{decode, encode, Bencode};
use torrent::metainfo::Metainfo;
use torrent::magnet::MagnetUri;
use torrent::error::{Error, ErrorKind};
use torrent::peer::{Handshake, PeerId, PeerMessage};
use torrent::storage::PieceManager;

Examples

See the examples/ directory for runnable scenario guides:

Run with:

cargo run -p torrent --example parse_metainfo

Relationship with torrent-core

┌─────────────────────────────────────────────────────┐
│                   torrent (async)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│  │ session  │ │ tracker  │ │ dht/rpc  │ │storage/ │ │
│  │          │ │ http/udp │ │ query    │ │fs       │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │
│       │            │            │            │      │
│       └────────────┴────────────┴────────────┘      │
│                        │                            │
│              depends on torrent_core                │
│                        │                            │
├────────────────────────┼────────────────────────────┤
│              torrent-core (sync, no tokio)          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│  │ bencode  │ │ metainfo │ │   peer   │ │ dht/    │ │
│  │ error    │ │ magnet   │ │ handshake│ │ krpc    │ │
│  │          │ │          │ │ message  │ │ routing │ │
│  └──────────┘ └──────────┘ └──────────┘ └─────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│  │ tracker  │ │  piece   │ │ storage              │ │
│  │ data     │ │ manager  │ │ trait (read/write)   │ │
│  │ types    │ │ selector │ │                      │ │
│  └──────────┘ └──────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────┘

Testing

cargo test -p torrent                    # Run all tests
cargo clippy -p torrent -- -D warnings   # Lint

License

MIT — see LICENSE.