rqbit 3.1.0

A bittorrent command line client and server.
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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

![crates.io](https://img.shields.io/crates/v/rqbit.svg)(https://crates.io/crates/rqbit)
![crates.io](https://img.shields.io/crates/v/librqbit.svg)(https://crates.io/crates/librqbit)
![docs.rs](https://img.shields.io/docsrs/librqbit.svg)(https://docs.rs/crate/librqbit/latest)

# rqbit - bittorrent client in Rust

**rqbit** is a bittorrent client written in Rust.

## Installation

There are pre-built binaries in [releases](https://github.com/ikatson/rqbit/releases).
If someone wants to put rqbit into e.g. homebrew, PRs welcome :)

If you have rust toolchain installed, this should work:

```
cargo install rqbit
```

## Build
Just a regular Rust binary build process.

    cargo build --release

## Usage quick start

### Optional - start the server

Assuming you are downloading to ~/Downloads.

    rqbit server start ~/Downloads

### Download torrents

Assuming you are downloading to ~/Downloads. If the server is already started, ```-o ~/Downloads``` can be omitted.

    rqbit download -o ~/Downloads 'magnet:?....' [https?://url/to/.torrent] [/path/to/local/file.torrent]

## Useful options

### -v <log-level>
Increase verbosity. Possible values: trace, debug, info, warn, error.

### --list
Will print the contents of the torrent file or the magnet link.

### --overwrite
If you want to resume downloading a file that already exists, you'll need to add this option.

### --peer-connect-timeout=10s

This will increase the default peer connect timeout. The default one is 2 seconds, and it's sometimes not enough.

### -r / --filename-re

Use a regex here to select files by their names.

## Features and missing features

### Some supported features
- Sequential downloading (the default and only option)
- Resume downloading file(s) if they already exist on disk
- Selective downloading using a regular expression for filename
- DHT support. Allows magnet links to work, and makes more peers available.
- HTTP API
- Web UI

### Code features
- Serde-based bencode serializer/deserializer
- Custom code for binary protocol serialization/deserialization. And for everything else too :)
- Supports several SHA1 implementations, as this seems to be the biggest performance bottleneck. Default is openssl as it's the fastest in my benchmarks.
- In theory, the libraries that rqbit is made of are re-usable.
- No unsafe

### Bugs, missing features and other caveats
PRs are very welcome.

- Only supports BitTorrent V1 over TCP
- As this was created for personal needs, and for educational purposes, documentation, commit message quality etc. leave a lot to be desired.

## HTTP API

By default it listens on http://127.0.0.1:3030.

    curl -s 'http://127.0.0.1:3030/'

    {
        "apis": {
            "GET /": "list all available APIs",
            "GET /dht/stats": "DHT stats",
            "GET /dht/table": "DHT routing table",
            "GET /torrents": "List torrents (default torrent is 0)",
            "GET /torrents/{index}": "Torrent details",
            "GET /torrents/{index}/haves": "The bitfield of have pieces",
            "GET /torrents/{index}/stats": "Torrent stats",
            "POST /torrents/": "Add a torrent here. magnet: or http:// or a local file.",
            "GET /web/": "Web UI"
        }
    }

### Add torrent through HTTP API

```curl -d 'magnet:?...' http://127.0.0.1:3030/torrents```

OR

```curl -d 'http://.../file.torrent' http://127.0.0.1:3030/torrents```

OR

```curl -d '/some/local/file.torrent' http://127.0.0.1:3030/torrents```

Supported query parameters, all optional:
- overwrite=true|false
- only_files_regex - the regular expression string to match filenames
- output_folder - the folder to download to. If not specified, defaults to the one that rqbit server started with
- list_only=true|false - if you want to just list the files in the torrent instead of downloading

## Web UI
Access with http://localhost:3030/web/

<img width="1165" alt="Web UI" src="https://github.com/ikatson/rqbit/assets/221386/3854c1d6-94ee-4416-8af5-7ede6cd2047a">

## Code organization
- crates/rqbit - main binary
- crates/librqbit - main library
- crates/librqbit-core - torrent utils
- crates/bencode - bencode serializing/deserializing
- crates/buffers - wrappers around binary buffers
- crates/clone_to_owned - a trait to make something owned
- crates/sha1w - wrappers around sha1 libraries
- crates/peer_binary_protocol - the protocol to talk to peers
- crates/dht - Distributed Hash Table implementation

## Motivation

First of all, I love Rust. The project was created purely for the fun of the process of writing code in Rust.

I was not satisfied with my regular bittorrent client, and was wondering how much work would it be to create a new one from scratch, and it got where it is, starting from bencode protocol implemenation, then peer protocol, etc, etc.