torrent 0.1.5

High-level async BitTorrent library — session management, HTTP/UDP tracker communication, DHT networking, peer connections, and file storage. Built on torrent-core with tokio.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

# torrent

[![MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)

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

## Modules

| Module                     | Description                                      | BEP           |
| -------------------------- | ------------------------------------------------ | ------------- |
| [`session`](./src/session) | Session, download/upload loops, peer manager     | —             |
| [`peer`](./src/peer)       | Async `PeerConnection`, re-exports core types    | BEP 3         |
| [`tracker`](./src/tracker) | HTTP (manual) + UDP tracker announce             | BEP 3, 15, 23 |
| [`dht`](./src/dht)         | Async DHT RPC, query helpers (`find_node`, etc.) | BEP 5         |
| [`storage`](./src/storage) | `FileStorage` (async file I/O)                   | —             |

## Quick Start

```rust
use torrent::session::{Session, SessionConfig};

#[tokio::main]
async fn main() -> Result<(), torrent::error::Error> {
    let config = SessionConfig::default();
    let session = Session::new(config).await?;

    let data = std::fs::read("ubuntu-24.04.torrent")?;
    let info_hash = session.add_torrent_bytes(&data, "./downloads").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:

```rust
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/`](./examples) directory for runnable scenario guides:

| Example                                                 | Scenario                                            |
| ------------------------------------------------------- | --------------------------------------------------- |
| [`parse_metainfo.rs`](./examples/parse_metainfo.rs)     | Parse a .torrent file and inspect metadata          |
| [`tracker_announce.rs`](./examples/tracker_announce.rs) | Query HTTP/UDP trackers for peer lists              |
| [`dht_discovery.rs`](./examples/dht_discovery.rs)       | Discover peers via the DHT (Kademlia)               |
| [`peer_connect.rs`](./examples/peer_connect.rs)         | Low-level peer wire protocol (handshake + messages) |

Run with:

```bash
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

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

## License

MIT — see [LICENSE](LICENSE).