From 3c76794a4601a4e44682ff4b6a246c9a9b20e4f8 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Thu, 8 Feb 2024 16:22:58 +0000 Subject: [PATCH] docs: [#466] improve docs for seeder command --- project-words.txt | 1 + src/console/commands/mod.rs | 1 + src/console/commands/seeder/api.rs | 1 + src/console/commands/seeder/app.rs | 119 ++++++++++++++++++++++++- src/console/commands/seeder/logging.rs | 1 + src/console/commands/seeder/mod.rs | 1 + src/console/cronjobs/mod.rs | 1 + src/console/mod.rs | 1 + src/lib.rs | 2 +- src/web/api/mod.rs | 5 +- 10 files changed, 128 insertions(+), 5 deletions(-) diff --git a/project-words.txt b/project-words.txt index b8755b5a..9cc5b6b7 100644 --- a/project-words.txt +++ b/project-words.txt @@ -92,6 +92,7 @@ upgrader Uragqm urlencoding uroot +uuidgen Verstappen waivable webseeding diff --git a/src/console/commands/mod.rs b/src/console/commands/mod.rs index 38506b77..e218659c 100644 --- a/src/console/commands/mod.rs +++ b/src/console/commands/mod.rs @@ -1,2 +1,3 @@ +//! Console commands that can be run manually. pub mod seeder; pub mod tracker_statistics_importer; diff --git a/src/console/commands/seeder/api.rs b/src/console/commands/seeder/api.rs index 2236082f..499a8605 100644 --- a/src/console/commands/seeder/api.rs +++ b/src/console/commands/seeder/api.rs @@ -1,3 +1,4 @@ +//! Action that a user can perform on a Index website. use log::debug; use thiserror::Error; diff --git a/src/console/commands/seeder/app.rs b/src/console/commands/seeder/app.rs index ac84dc83..8297e071 100644 --- a/src/console/commands/seeder/app.rs +++ b/src/console/commands/seeder/app.rs @@ -1,19 +1,132 @@ -//! Program to upload random torrent to a live Index API. +//! Console app to upload random torrents to a live Index API. //! //! Run with: //! //! ```text -//! cargo run --bin seeder -- --api-base-url --number-of-torrents --user --password --interval +//! cargo run --bin seeder -- \ +//! --api-base-url \ +//! --number-of-torrents \ +//! --user \ +//! --password \ +//! --interval //! ``` //! //! For example: //! //! ```text -//! cargo run --bin seeder -- --api-base-url "localhost:3001" --number-of-torrents 1000 --user admin --password 12345678 --interval 0 +//! cargo run --bin seeder -- \ +//! --api-base-url "localhost:3001" \ +//! --number-of-torrents 1000 \ +//! --user admin \ +//! --password 12345678 \ +//! --interval 0 //! ``` //! //! That command would upload 1000 random torrents to the Index using the user //! account admin with password 123456 and waiting 1 second between uploads. +//! +//! The random torrents generated are single-file torrents from a TXT file. +//! All generated torrents used a UUID to identify the test torrent. The torrent +//! is generated on the fly without needing to generate the contents file. +//! However, if you like it, you can generate the contents and the torrent +//! manually with the following commands: +//! +//! ```text +//! cd /tmp +//! mkdir test_torrents +//! cd test_torrents +//! uuidgen +//! echo $'1fd827fb-29dc-47bd-b116-bf96f6466e65' > file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt +//! imdl torrent create file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt +//! imdl torrent show file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt.torrent +//! ``` +//! +//! That could be useful for testing purposes. For example, if you want to seed +//! the torrent with a `BitTorrent` client. +//! +//! Let's explain each line: +//! +//! First, we need to generate the UUID: +//! +//! ```text +//! uuidgen +//! 1fd827fb-29dc-47bd-b116-bf96f6466e65 +//! ```` +//! +//! Then, we need to create a text file and write the UUID into the file: +//! +//! ```text +//! echo $'1fd827fb-29dc-47bd-b116-bf96f6466e65' > file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt +//! ``` +//! +//! Finally you can use a torrent creator like [Intermodal](https://github.com/casey/intermodal) +//! to generate the torrent file. You can use any `BitTorrent` client or other +//! console tool. +//! +//! ```text +//! imdl torrent create file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt +//! $ imdl torrent create file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt +//! [1/3] 🧿 Searching `file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt` for files… +//! [2/3] 🧮 Hashing pieces… +//! [3/3] 💾 Writing metainfo to `file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt.torrent`… +//! ✨✨ Done! ✨✨ +//! ```` +//! +//! The torrent meta file contains this information: +//! +//! ```text +//! $ imdl torrent show file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt.torrent +//! Name file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt +//! Creation Date 2024-02-07 12:47:32 UTC +//! Created By imdl/0.1.13 +//! Info Hash c8cf845e9771013b5c0e022cb1fc1feebdb24b66 +//! Torrent Size 201 bytes +//! Content Size 37 bytes +//! Private no +//! Piece Size 16 KiB +//! Piece Count 1 +//! File Count 1 +//! Files file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt +//!```` +//! +//! The torrent generated manually contains this info: +//! +//! ```json +//! { +//! "created by": "imdl/0.1.13", +//! "creation date": 1707304810, +//! "encoding": "UTF-8", +//! "info": { +//! "length": 37, +//! "name": "file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt", +//! "piece length": 16384, +//! "pieces": "E2 11 4F 69 79 50 1E CC F6 32 91 A5 12 FA D5 6B 49 20 12 D3" +//! } +//! } +//! ``` +//! +//! If you upload that torrent to the Index and you download it, then you +//! get this torrent information: +//! +//! ```json +//! { +//! "announce": "udp://tracker.torrust-demo.com:6969/k24qT2KgWFh9d5e1iHSJ9kOwfK45fH4V", +//! "announce-list": [ +//! [ +//! "udp://tracker.torrust-demo.com:6969/k24qT2KgWFh9d5e1iHSJ9kOwfK45fH4V" +//! ] +//! ], +//! "info": { +//! "length": 37, +//! "name": "file-1fd827fb-29dc-47bd-b116-bf96f6466e65.txt", +//! "piece length": 16384, +//! "pieces": "E2 11 4F 69 79 50 1E CC F6 32 91 A5 12 FA D5 6B 49 20 12 D3" +//! } +//! } +//! ``` +//! +//! As you can see the `info` dictionary is exactly the same, which produces +//! the same info-hash for the torrent. use std::thread::sleep; use std::time::Duration; diff --git a/src/console/commands/seeder/logging.rs b/src/console/commands/seeder/logging.rs index 13d9c745..85634719 100644 --- a/src/console/commands/seeder/logging.rs +++ b/src/console/commands/seeder/logging.rs @@ -1,3 +1,4 @@ +//! Logging setup for the `seeder`. use log::{debug, LevelFilter}; /// # Panics diff --git a/src/console/commands/seeder/mod.rs b/src/console/commands/seeder/mod.rs index c29812b4..dc37e756 100644 --- a/src/console/commands/seeder/mod.rs +++ b/src/console/commands/seeder/mod.rs @@ -1,3 +1,4 @@ +//! Command to upload random torrents to a live Index API. pub mod api; pub mod app; pub mod logging; diff --git a/src/console/cronjobs/mod.rs b/src/console/cronjobs/mod.rs index 43be8073..3fe5bab6 100644 --- a/src/console/cronjobs/mod.rs +++ b/src/console/cronjobs/mod.rs @@ -1 +1,2 @@ +//! Cronjobs that are executed automatically. pub mod tracker_statistics_importer; diff --git a/src/console/mod.rs b/src/console/mod.rs index 80eff453..486d5d30 100644 --- a/src/console/mod.rs +++ b/src/console/mod.rs @@ -1,2 +1,3 @@ +//! Console modules. pub mod commands; pub mod cronjobs; diff --git a/src/lib.rs b/src/lib.rs index 45e6ad24..44ee238d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -231,7 +231,7 @@ //! This console command allows you to manually import the tracker statistics. //! //! For more information about this command you can visit the documentation for -//! the [`Import tracker statistics`](crate::console::commands::import_tracker_statistics) module. +//! the [`Import tracker statistics`](crate::console::commands::tracker_statistics_importer) module. //! //! ## Upgrader //! diff --git a/src/web/api/mod.rs b/src/web/api/mod.rs index 8bfdacd9..f2d5b996 100644 --- a/src/web/api/mod.rs +++ b/src/web/api/mod.rs @@ -2,7 +2,10 @@ //! //! Currently, the API has only one version: `v1`. //! -//! Refer to the [`v1`]) module for more information. +//! Refer to: +//! +//! - [`client::v1`]) module for more information about the API client. +//! - [`server::v1`]) module for more information about the API server. pub mod client; pub mod server;