Skip to content

Commit 3c76794

Browse files
josecelanojosecelano
committed
docs: [torrust#466] improve docs for seeder command
1 parent 3b8d179 commit 3c76794

File tree

10 files changed

+128
-5
lines changed

10 files changed

+128
-5
lines changed

‎project-words.txt

+1
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ upgrader
9292
Uragqm
9393
urlencoding
9494
uroot
95+
uuidgen
9596
Verstappen
9697
waivable
9798
webseeding

‎src/console/commands/mod.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1+
//! Console commands that can be run manually.
12
pub mod seeder;
23
pub mod tracker_statistics_importer;

‎src/console/commands/seeder/api.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Action that a user can perform on a Index website.
12
use log::debug;
23
use thiserror::Error;
34

‎src/console/commands/seeder/app.rs

+116-3
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,132 @@
1-
//! Program to upload random torrent to a live Index API.
1+
//! Console app to upload random torrents to a live Index API.
22
//!
33
//! Run with:
44
//!
55
//! ```text
6-
//! cargo run --bin seeder -- --api-base-url <API_BASE_URL> --number-of-torrents <NUMBER_OF_TORRENTS> --user <USER> --password <PASSWORD> --interval <INTERVAL>
6+
//! cargo run --bin seeder -- \
7+
//! --api-base-url <API_BASE_URL> \
8+
//! --number-of-torrents <NUMBER_OF_TORRENTS> \
9+
//! --user <USER> \
10+
//! --password <PASSWORD> \
11+
//! --interval <INTERVAL>
712
//! ```
813
//!
914
//! For example:
1015
//!
1116
//! ```text
12-
//! cargo run --bin seeder -- --api-base-url "localhost:3001" --number-of-torrents 1000 --user admin --password 12345678 --interval 0
17+
//! cargo run --bin seeder -- \
18+
//! --api-base-url "localhost:3001" \
19+
//! --number-of-torrents 1000 \
20+
//! --user admin \
21+
//! --password 12345678 \
22+
//! --interval 0
1323
//! ```
1424
//!
1525
//! That command would upload 1000 random torrents to the Index using the user
1626
//! account admin with password 123456 and waiting 1 second between uploads.
27+
//!
28+
//! The random torrents generated are single-file torrents from a TXT file.
29+
//! All generated torrents used a UUID to identify the test torrent. The torrent
30+
//! is generated on the fly without needing to generate the contents file.
31+
//! However, if you like it, you can generate the contents and the torrent
32+
//! manually with the following commands:
33+
//!
34+
//! ```text
35+
//! cd /tmp
36+
//! mkdir test_torrents
37+
//! cd test_torrents
38+
//! uuidgen
39+
//! echo $'1fd827fb-29dc-47bd-b116-bf96f6466e65' > file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt
40+
//! imdl torrent create file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt
41+
//! imdl torrent show file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt.torrent
42+
//! ```
43+
//!
44+
//! That could be useful for testing purposes. For example, if you want to seed
45+
//! the torrent with a `BitTorrent` client.
46+
//!
47+
//! Let's explain each line:
48+
//!
49+
//! First, we need to generate the UUID:
50+
//!
51+
//! ```text
52+
//! uuidgen
53+
//! 1fd827fb-29dc-47bd-b116-bf96f6466e65
54+
//! ````
55+
//!
56+
//! Then, we need to create a text file and write the UUID into the file:
57+
//!
58+
//! ```text
59+
//! echo $'1fd827fb-29dc-47bd-b116-bf96f6466e65' > file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt
60+
//! ```
61+
//!
62+
//! Finally you can use a torrent creator like [Intermodal](https://github.com/casey/intermodal)
63+
//! to generate the torrent file. You can use any `BitTorrent` client or other
64+
//! console tool.
65+
//!
66+
//! ```text
67+
//! imdl torrent create file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt
68+
//! $ imdl torrent create file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt
69+
//! [1/3] 🧿 Searching `file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt` for files…
70+
//! [2/3] 🧮 Hashing pieces…
71+
//! [3/3] 💾 Writing metainfo to `file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt.torrent`…
72+
//! ✨✨ Done! ✨✨
73+
//! ````
74+
//!
75+
//! The torrent meta file contains this information:
76+
//!
77+
//! ```text
78+
//! $ imdl torrent show file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt.torrent
79+
//! Name file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt
80+
//! Creation Date 2024-02-07 12:47:32 UTC
81+
//! Created By imdl/0.1.13
82+
//! Info Hash c8cf845e9771013b5c0e022cb1fc1feebdb24b66
83+
//! Torrent Size 201 bytes
84+
//! Content Size 37 bytes
85+
//! Private no
86+
//! Piece Size 16 KiB
87+
//! Piece Count 1
88+
//! File Count 1
89+
//! Files file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt
90+
//!````
91+
//!
92+
//! The torrent generated manually contains this info:
93+
//!
94+
//! ```json
95+
//! {
96+
//! "created by": "imdl/0.1.13",
97+
//! "creation date": 1707304810,
98+
//! "encoding": "UTF-8",
99+
//! "info": {
100+
//! "length": 37,
101+
//! "name": "file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt",
102+
//! "piece length": 16384,
103+
//! "pieces": "<hex>E2 11 4F 69 79 50 1E CC F6 32 91 A5 12 FA D5 6B 49 20 12 D3</hex>"
104+
//! }
105+
//! }
106+
//! ```
107+
//!
108+
//! If you upload that torrent to the Index and you download it, then you
109+
//! get this torrent information:
110+
//!
111+
//! ```json
112+
//! {
113+
//! "announce": "udp://tracker.torrust-demo.com:6969/k24qT2KgWFh9d5e1iHSJ9kOwfK45fH4V",
114+
//! "announce-list": [
115+
//! [
116+
//! "udp://tracker.torrust-demo.com:6969/k24qT2KgWFh9d5e1iHSJ9kOwfK45fH4V"
117+
//! ]
118+
//! ],
119+
//! "info": {
120+
//! "length": 37,
121+
//! "name": "file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt",
122+
//! "piece length": 16384,
123+
//! "pieces": "<hex>E2 11 4F 69 79 50 1E CC F6 32 91 A5 12 FA D5 6B 49 20 12 D3</hex>"
124+
//! }
125+
//! }
126+
//! ```
127+
//!
128+
//! As you can see the `info` dictionary is exactly the same, which produces
129+
//! the same info-hash for the torrent.
17130
use std::thread::sleep;
18131
use std::time::Duration;
19132

‎src/console/commands/seeder/logging.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Logging setup for the `seeder`.
12
use log::{debug, LevelFilter};
23

34
/// # Panics

‎src/console/commands/seeder/mod.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Command to upload random torrents to a live Index API.
12
pub mod api;
23
pub mod app;
34
pub mod logging;

‎src/console/cronjobs/mod.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1+
//! Cronjobs that are executed automatically.
12
pub mod tracker_statistics_importer;

‎src/console/mod.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1+
//! Console modules.
12
pub mod commands;
23
pub mod cronjobs;

‎src/lib.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@
231231
//! This console command allows you to manually import the tracker statistics.
232232
//!
233233
//! For more information about this command you can visit the documentation for
234-
//! the [`Import tracker statistics`](crate::console::commands::import_tracker_statistics) module.
234+
//! the [`Import tracker statistics`](crate::console::commands::tracker_statistics_importer) module.
235235
//!
236236
//! ## Upgrader
237237
//!

‎src/web/api/mod.rs

+4-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@
22
//!
33
//! Currently, the API has only one version: `v1`.
44
//!
5-
//! Refer to the [`v1`]) module for more information.
5+
//! Refer to:
6+
//!
7+
//! - [`client::v1`]) module for more information about the API client.
8+
//! - [`server::v1`]) module for more information about the API server.
69
pub mod client;
710
pub mod server;
811

0 commit comments

Comments
 (0)