Skip to content

Commit 0bf13e6

Browse files
josecelanojosecelano
committed
docs: [#260] crate docs for shared mod
1 parent d164f90 commit 0bf13e6

File tree

15 files changed

+400
-6
lines changed

15 files changed

+400
-6
lines changed

‎cSpell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
"leechers",
3838
"libtorrent",
3939
"Lphant",
40+
"metainfo",
4041
"middlewares",
4142
"mockall",
4243
"multimap",

‎docs/media/mandelbrot_2048x2048_infohash_v1.png.torrent‎

375 Bytes
Binary file not shown.

‎docs/media/mandelbrot_2048x2048_infohash_v1.png.torrent.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"created by": "qBittorrent v4.4.1",
3+
"creation date": 1679674628,
4+
"info": {
5+
"length": 172204,
6+
"name": "mandelbrot_2048x2048.png",
7+
"piece length": 16384,
8+
"pieces": "<hex>7D 91 71 0D 9D 4D BA 88 9B 54 20 54 D5 26 72 8D 5A 86 3F E1 21 DF 77 C7 F7 BB 6C 77 96 21 66 25 38 C5 D9 CD AB 8B 08 EF 8C 24 9B B2 F5 C4 CD 2A DF 0B C0 0C F0 AD DF 72 90 E5 B6 41 4C 23 6C 47 9B 8E 9F 46 AA 0C 0D 8E D1 97 FF EE 68 8B 5F 34 A3 87 D7 71 C5 A6 F9 8E 2E A6 31 7C BD F0 F9 E2 23 F9 CC 80 AF 54 00 04 F9 85 69 1C 77 89 C1 76 4E D6 AA BF 61 A6 C2 80 99 AB B6 5F 60 2F 40 A8 25 BE 32 A3 3D 9D 07 0C 79 68 98 D4 9D 63 49 AF 20 58 66 26 6F 98 6B 6D 32 34 CD 7D 08 15 5E 1A D0 00 09 57 AB 30 3B 20 60 C1 DC 12 87 D6 F3 E7 45 4F 70 67 09 36 31 55 F2 20 F6 6C A5 15 6F 2C 89 95 69 16 53 81 7D 31 F1 B6 BD 37 42 CC 11 0B B2 FC 2B 49 A5 85 B6 FC 76 74 44 93</hex>"
9+
}
10+
}

‎src/shared/bit_torrent/common.rs‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,56 @@
1+
//! `BitTorrent` protocol primitive types
2+
//!
3+
//! [BEP 3. The `BitTorrent` Protocol Specification](https://www.bittorrent.org/beps/bep_0003.html)
14
use aquatic_udp_protocol::{AnnounceEvent, NumberOfBytes};
25
use serde::{Deserialize, Serialize};
36

7+
/// The maximum number of torrents that can be returned in an `scrape` response.
8+
/// It's also the maximum number of peers returned in an `announce` response.
9+
///
10+
/// The [BEP 15. UDP Tracker Protocol for `BitTorrent`](https://www.bittorrent.org/beps/bep_0015.html)
11+
/// defines this limit:
12+
///
13+
/// "Up to about 74 torrents can be scraped at once. A full scrape can't be done
14+
/// with this protocol."
15+
///
16+
/// The [BEP 48. Tracker Protocol Extension: Scrape](https://www.bittorrent.org/beps/bep_0048.html)
17+
/// does not specifically mention this limit, but the limit is being used for
18+
/// both the UDP and HTTP trackers since it's applied at the domain level.
419
pub const MAX_SCRAPE_TORRENTS: u8 = 74;
20+
21+
/// HTTP tracker authentication key length.
22+
///
23+
/// See function to [`generate`](crate::tracker::auth::generate) the
24+
/// [`ExpiringKeys`](crate::tracker::auth::ExpiringKey) for more information.
525
pub const AUTH_KEY_LENGTH: usize = 32;
626

727
#[repr(u32)]
828
#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
9-
pub enum Actions {
29+
enum Actions {
30+
// todo: it seems this enum is not used anywhere. Values match the ones in
31+
// aquatic_udp_protocol::request::Request::from_bytes.
1032
Connect = 0,
1133
Announce = 1,
1234
Scrape = 2,
1335
Error = 3,
1436
}
1537

38+
/// Announce events. Described on the
39+
/// [BEP 3. The `BitTorrent` Protocol Specification](https://www.bittorrent.org/beps/bep_0003.html)
1640
#[derive(Serialize, Deserialize)]
1741
#[serde(remote = "AnnounceEvent")]
1842
pub enum AnnounceEventDef {
43+
/// The peer has started downloading the torrent.
1944
Started,
45+
/// The peer has ceased downloading the torrent.
2046
Stopped,
47+
/// The peer has completed downloading the torrent.
2148
Completed,
49+
/// This is one of the announcements done at regular intervals.
2250
None,
2351
}
2452

53+
/// Number of bytes downloaded, uploaded or pending to download (left) by the peer.
2554
#[derive(Serialize, Deserialize)]
2655
#[serde(remote = "NumberOfBytes")]
2756
pub struct NumberOfBytesDef(pub i64);

‎src/shared/bit_torrent/info_hash.rs‎

Lines changed: 139 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,147 @@
1+
//! A `BitTorrent` `InfoHash`. It's a unique identifier for a `BitTorrent` torrent.
2+
//!
3+
//! "The 20-byte sha1 hash of the bencoded form of the info value
4+
//! from the metainfo file."
5+
//!
6+
//! See [BEP 3. The `BitTorrent` Protocol Specification](https://www.bittorrent.org/beps/bep_0003.html)
7+
//! for the official specification.
8+
//!
9+
//! This modules provides a type that can be used to represent infohashes.
10+
//!
11+
//! > **NOTICE**: It only supports Info Hash v1.
12+
//!
13+
//! Typically infohashes are represented as hex strings, but internally they are
14+
//! a 20-byte array.
15+
//!
16+
//! # Calculating the info-hash of a torrent file
17+
//!
18+
//! A sample torrent:
19+
//!
20+
//! - Torrent file: `mandelbrot_2048x2048_infohash_v1.png.torrent`
21+
//! - File: `mandelbrot_2048x2048.png`
22+
//! - Info Hash v1: `5452869be36f9f3350ccee6b4544e7e76caaadab`
23+
//! - Sha1 hash of the info dictionary: `5452869BE36F9F3350CCEE6B4544E7E76CAAADAB`
24+
//!
25+
//! A torrent file is a binary file encoded with [Bencode encoding](https://en.wikipedia.org/wiki/Bencode):
26+
//!
27+
//! ```text
28+
//! 0000000: 6431 303a 6372 6561 7465 6420 6279 3138 d10:created by18
29+
//! 0000010: 3a71 4269 7474 6f72 7265 6e74 2076 342e :qBittorrent v4.
30+
//! 0000020: 342e 3131 333a 6372 6561 7469 6f6e 2064 4.113:creation d
31+
//! 0000030: 6174 6569 3136 3739 3637 3436 3238 6534 atei1679674628e4
32+
//! 0000040: 3a69 6e66 6f64 363a 6c65 6e67 7468 6931 :infod6:lengthi1
33+
//! 0000050: 3732 3230 3465 343a 6e61 6d65 3234 3a6d 72204e4:name24:m
34+
//! 0000060: 616e 6465 6c62 726f 745f 3230 3438 7832 andelbrot_2048x2
35+
//! 0000070: 3034 382e 706e 6731 323a 7069 6563 6520 048.png12:piece
36+
//! 0000080: 6c65 6e67 7468 6931 3633 3834 6536 3a70 lengthi16384e6:p
37+
//! 0000090: 6965 6365 7332 3230 3a7d 9171 0d9d 4dba ieces220:}.q..M.
38+
//! 00000a0: 889b 5420 54d5 2672 8d5a 863f e121 df77 ..T T.&r.Z.?.!.w
39+
//! 00000b0: c7f7 bb6c 7796 2166 2538 c5d9 cdab 8b08 ...lw.!f%8......
40+
//! 00000c0: ef8c 249b b2f5 c4cd 2adf 0bc0 0cf0 addf ..$.....*.......
41+
//! 00000d0: 7290 e5b6 414c 236c 479b 8e9f 46aa 0c0d r...AL#lG...F...
42+
//! 00000e0: 8ed1 97ff ee68 8b5f 34a3 87d7 71c5 a6f9 .....h._4...q...
43+
//! 00000f0: 8e2e a631 7cbd f0f9 e223 f9cc 80af 5400 ...1|....#....T.
44+
//! 0000100: 04f9 8569 1c77 89c1 764e d6aa bf61 a6c2 ...i.w..vN...a..
45+
//! 0000110: 8099 abb6 5f60 2f40 a825 be32 a33d 9d07 ...._`/@.%.2.=..
46+
//! 0000120: 0c79 6898 d49d 6349 af20 5866 266f 986b .yh...cI. Xf&o.k
47+
//! 0000130: 6d32 34cd 7d08 155e 1ad0 0009 57ab 303b m24.}..^....W.0;
48+
//! 0000140: 2060 c1dc 1287 d6f3 e745 4f70 6709 3631 `.......EOpg.61
49+
//! 0000150: 55f2 20f6 6ca5 156f 2c89 9569 1653 817d U. .l..o,..i.S.}
50+
//! 0000160: 31f1 b6bd 3742 cc11 0bb2 fc2b 49a5 85b6 1...7B.....+I...
51+
//! 0000170: fc76 7444 9365 65 .vtD.ee
52+
//! ```
53+
//!
54+
//! You can generate that output with the command:
55+
//!
56+
//! ```text
57+
//! xxd mandelbrot_2048x2048_infohash_v1.png.torrent
58+
//! ```
59+
//!
60+
//! And you can show only the bytes (hexadecimal):
61+
//!
62+
//! ```text
63+
//! 6431303a6372656174656420627931383a71426974746f7272656e742076
64+
//! 342e342e3131333a6372656174696f6e2064617465693136373936373436
65+
//! 323865343a696e666f64363a6c656e6774686931373232303465343a6e61
66+
//! 6d6532343a6d616e64656c62726f745f3230343878323034382e706e6731
67+
//! 323a7069656365206c656e67746869313633383465363a70696563657332
68+
//! 32303a7d91710d9d4dba889b542054d526728d5a863fe121df77c7f7bb6c
69+
//! 779621662538c5d9cdab8b08ef8c249bb2f5c4cd2adf0bc00cf0addf7290
70+
//! e5b6414c236c479b8e9f46aa0c0d8ed197ffee688b5f34a387d771c5a6f9
71+
//! 8e2ea6317cbdf0f9e223f9cc80af540004f985691c7789c1764ed6aabf61
72+
//! a6c28099abb65f602f40a825be32a33d9d070c796898d49d6349af205866
73+
//! 266f986b6d3234cd7d08155e1ad0000957ab303b2060c1dc1287d6f3e745
74+
//! 4f706709363155f220f66ca5156f2c8995691653817d31f1b6bd3742cc11
75+
//! 0bb2fc2b49a585b6fc767444936565
76+
//! ```
77+
//!
78+
//! You can generate that output with the command:
79+
//!
80+
//! ```text
81+
//! `xxd -ps mandelbrot_2048x2048_infohash_v1.png.torrent`.
82+
//! ```
83+
//!
84+
//! The same data can be represented in a JSON format:
85+
//!
86+
//! ```json
87+
//! {
88+
//! "created by": "qBittorrent v4.4.1",
89+
//! "creation date": 1679674628,
90+
//! "info": {
91+
//! "length": 172204,
92+
//! "name": "mandelbrot_2048x2048.png",
93+
//! "piece length": 16384,
94+
//! "pieces": "<hex>7D 91 71 0D 9D 4D BA 88 9B 54 20 54 D5 26 72 8D 5A 86 3F E1 21 DF 77 C7 F7 BB 6C 77 96 21 66 25 38 C5 D9 CD AB 8B 08 EF 8C 24 9B B2 F5 C4 CD 2A DF 0B C0 0C F0 AD DF 72 90 E5 B6 41 4C 23 6C 47 9B 8E 9F 46 AA 0C 0D 8E D1 97 FF EE 68 8B 5F 34 A3 87 D7 71 C5 A6 F9 8E 2E A6 31 7C BD F0 F9 E2 23 F9 CC 80 AF 54 00 04 F9 85 69 1C 77 89 C1 76 4E D6 AA BF 61 A6 C2 80 99 AB B6 5F 60 2F 40 A8 25 BE 32 A3 3D 9D 07 0C 79 68 98 D4 9D 63 49 AF 20 58 66 26 6F 98 6B 6D 32 34 CD 7D 08 15 5E 1A D0 00 09 57 AB 30 3B 20 60 C1 DC 12 87 D6 F3 E7 45 4F 70 67 09 36 31 55 F2 20 F6 6C A5 15 6F 2C 89 95 69 16 53 81 7D 31 F1 B6 BD 37 42 CC 11 0B B2 FC 2B 49 A5 85 B6 FC 76 74 44 93</hex>"
95+
//! }
96+
//! }
97+
//! ```
98+
//!
99+
//! The JSON object was generated with: <https://github.com/Chocobo1/bencode_online>
100+
//!
101+
//! As you can see, there is a `info` attribute:
102+
//!
103+
//! ```json
104+
//! {
105+
//! "length": 172204,
106+
//! "name": "mandelbrot_2048x2048.png",
107+
//! "piece length": 16384,
108+
//! "pieces": "<hex>7D 91 71 0D 9D 4D BA 88 9B 54 20 54 D5 26 72 8D 5A 86 3F E1 21 DF 77 C7 F7 BB 6C 77 96 21 66 25 38 C5 D9 CD AB 8B 08 EF 8C 24 9B B2 F5 C4 CD 2A DF 0B C0 0C F0 AD DF 72 90 E5 B6 41 4C 23 6C 47 9B 8E 9F 46 AA 0C 0D 8E D1 97 FF EE 68 8B 5F 34 A3 87 D7 71 C5 A6 F9 8E 2E A6 31 7C BD F0 F9 E2 23 F9 CC 80 AF 54 00 04 F9 85 69 1C 77 89 C1 76 4E D6 AA BF 61 A6 C2 80 99 AB B6 5F 60 2F 40 A8 25 BE 32 A3 3D 9D 07 0C 79 68 98 D4 9D 63 49 AF 20 58 66 26 6F 98 6B 6D 32 34 CD 7D 08 15 5E 1A D0 00 09 57 AB 30 3B 20 60 C1 DC 12 87 D6 F3 E7 45 4F 70 67 09 36 31 55 F2 20 F6 6C A5 15 6F 2C 89 95 69 16 53 81 7D 31 F1 B6 BD 37 42 CC 11 0B B2 FC 2B 49 A5 85 B6 FC 76 74 44 93</hex>"
109+
//! }
110+
//! ```
111+
//!
112+
//! The infohash is the [SHA1](https://en.wikipedia.org/wiki/SHA-1) hash
113+
//! of the `info` attribute. That is, the SHA1 hash of:
114+
//!
115+
//! ```text
116+
//! 64363a6c656e6774686931373232303465343a6e61
117+
//! d6532343a6d616e64656c62726f745f3230343878323034382e706e6731
118+
//! 23a7069656365206c656e67746869313633383465363a70696563657332
119+
//! 2303a7d91710d9d4dba889b542054d526728d5a863fe121df77c7f7bb6c
120+
//! 79621662538c5d9cdab8b08ef8c249bb2f5c4cd2adf0bc00cf0addf7290
121+
//! 5b6414c236c479b8e9f46aa0c0d8ed197ffee688b5f34a387d771c5a6f9
122+
//! e2ea6317cbdf0f9e223f9cc80af540004f985691c7789c1764ed6aabf61
123+
//! 6c28099abb65f602f40a825be32a33d9d070c796898d49d6349af205866
124+
//! 66f986b6d3234cd7d08155e1ad0000957ab303b2060c1dc1287d6f3e745
125+
//! f706709363155f220f66ca5156f2c8995691653817d31f1b6bd3742cc11
126+
//! bb2fc2b49a585b6fc7674449365
127+
//! ```
128+
//!
129+
//! You can hash that byte string with <https://www.pelock.com/products/hash-calculator>
130+
//!
131+
//! The result is a 20-char string: `5452869BE36F9F3350CCEE6B4544E7E76CAAADAB`
1132
use std::panic::Location;
2133

3134
use thiserror::Error;
4135

136+
/// `BitTorrent` Info Hash v1
5137
#[derive(PartialEq, Eq, Hash, Clone, Copy, Debug)]
6138
pub struct InfoHash(pub [u8; 20]);
7139

8140
const INFO_HASH_BYTES_LEN: usize = 20;
9141

10142
impl InfoHash {
143+
/// Create a new `InfoHash` from a byte slice.
144+
///
11145
/// # Panics
12146
///
13147
/// Will panic if byte slice does not contains the exact amount of bytes need for the `InfoHash`.
@@ -19,12 +153,13 @@ impl InfoHash {
19153
ret
20154
}
21155

22-
/// For readability, when accessing the bytes array
156+
/// Returns the `InfoHash` internal byte array.
23157
#[must_use]
24158
pub fn bytes(&self) -> [u8; 20] {
25159
self.0
26160
}
27161

162+
/// Returns the `InfoHash` as a hex string.
28163
#[must_use]
29164
pub fn to_hex_string(&self) -> String {
30165
self.to_string()
@@ -79,13 +214,16 @@ impl std::convert::From<[u8; 20]> for InfoHash {
79214
}
80215
}
81216

217+
/// Errors that can occur when converting from a `Vec<u8>` to an `InfoHash`.
82218
#[derive(Error, Debug)]
83219
pub enum ConversionError {
220+
/// Not enough bytes for infohash. An infohash is 20 bytes.
84221
#[error("not enough bytes for infohash: {message} {location}")]
85222
NotEnoughBytes {
86223
location: &'static Location<'static>,
87224
message: String,
88225
},
226+
/// Too many bytes for infohash. An infohash is 20 bytes.
89227
#[error("too many bytes for infohash: {message} {location}")]
90228
TooManyBytes {
91229
location: &'static Location<'static>,

‎src/shared/bit_torrent/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1+
//! Common code for the `BitTorrent` protocol.
12
pub mod common;
23
pub mod info_hash;

0 commit comments

Comments
 (0)