Skip to content

Commit fe28ef5

Browse files
josecelanojosecelano
committed
docs: [#256] crate docs for tracker and bootstrap mods
1 parent 1333cc0 commit fe28ef5

26 files changed

Lines changed: 1423 additions & 213 deletions

File tree

‎cSpell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@
5151
"proot",
5252
"Quickstart",
5353
"Rasterbar",
54+
"reannounce",
5455
"repr",
5556
"reqwest",
5657
"rngs",

‎packages/configuration/src/lib.rs‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,17 +59,26 @@ impl HttpApi {
5959
pub struct Configuration {
6060
pub log_level: Option<String>,
6161
pub mode: TrackerMode,
62+
63+
// Database configuration
6264
pub db_driver: DatabaseDriver,
6365
pub db_path: String,
66+
67+
/// Interval in seconds that the client should wait between sending regular announce requests to the tracker
6468
pub announce_interval: u32,
69+
/// Minimum announce interval. Clients must not reannounce more frequently than this
6570
pub min_announce_interval: u32,
66-
pub max_peer_timeout: u32,
6771
pub on_reverse_proxy: bool,
6872
pub external_ip: Option<String>,
6973
pub tracker_usage_statistics: bool,
7074
pub persistent_torrent_completed_stat: bool,
75+
76+
// Cleanup job configuration
77+
pub max_peer_timeout: u32,
7178
pub inactive_peer_cleanup_interval: u64,
7279
pub remove_peerless_torrents: bool,
80+
81+
// Server jobs configuration
7382
pub udp_trackers: Vec<UdpTracker>,
7483
pub http_trackers: Vec<HttpTracker>,
7584
pub http_api: HttpApi,

‎src/bootstrap/app.rs‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
1+
//! Setup for the main tracker application.
2+
//!
3+
//! The [`setup`](bootstrap::app::setup) only builds the application and its dependencies but it does not start the application.
4+
//! In fact, there is no such thing as the main application process. When the application starts, the only thing it does is
5+
//! starting a bunch of independent jobs. If you are looking for how things are started you should read [`app::start`](crate::app::start)
6+
//! function documentation.
7+
//!
8+
//! Setup steps:
9+
//!
10+
//! 1. Load the global application configuration.
11+
//! 2. Initialize static variables.
12+
//! 3. Initialize logging.
13+
//! 4. Initialize the domain tracker.
114
use std::env;
215
use std::sync::Arc;
316

@@ -9,6 +22,7 @@ use crate::shared::crypto::ephemeral_instance_keys;
922
use crate::tracker::services::tracker_factory;
1023
use crate::tracker::Tracker;
1124

25+
/// It loads the configuration from the environment and builds the main domain [`tracker`](crate::tracker::Tracker) struct.
1226
#[must_use]
1327
pub fn setup() -> (Arc<Configuration>, Arc<Tracker>) {
1428
let configuration = Arc::new(initialize_configuration());
@@ -17,13 +31,22 @@ pub fn setup() -> (Arc<Configuration>, Arc<Tracker>) {
1731
(configuration, tracker)
1832
}
1933

34+
/// It initializes the application with the given configuration.
35+
///
36+
/// The configuration may be obtained from the environment (via config file or env vars).
2037
#[must_use]
2138
pub fn initialize_with_configuration(configuration: &Arc<Configuration>) -> Arc<Tracker> {
2239
initialize_static();
2340
initialize_logging(configuration);
2441
Arc::new(initialize_tracker(configuration))
2542
}
2643

44+
/// It initializes the application static values.
45+
///
46+
/// These values are accessible throughout the entire application:
47+
///
48+
/// - The time when the application started.
49+
/// - An ephemeral instance random seed. This seed is used for encryption and it's changed when the main application process is restarted.
2750
pub fn initialize_static() {
2851
// Set the time of Torrust app starting
2952
lazy_static::initialize(&static_time::TIME_AT_APP_START);
@@ -32,6 +55,17 @@ pub fn initialize_static() {
3255
lazy_static::initialize(&ephemeral_instance_keys::RANDOM_SEED);
3356
}
3457

58+
/// It loads the application configuration from the environment.
59+
///
60+
/// There are two methods to inject the configuration:
61+
///
62+
/// 1. By using a config file: `config.toml`. The file must be in the same folder where you are running the tracker.
63+
/// 2. Environment variable: `TORRUST_TRACKER_CONFIG`. The variable contains the same contents as the `config.toml` file.
64+
///
65+
/// Environment variable has priority over the config file.
66+
///
67+
/// Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration) for the configuration options.
68+
///
3569
/// # Panics
3670
///
3771
/// Will panic if it can't load the configuration from either
@@ -50,11 +84,18 @@ fn initialize_configuration() -> Configuration {
5084
}
5185
}
5286

87+
/// It builds the domain tracker
88+
///
89+
/// The tracker is the domain layer service. It's the entrypoint to make requests to the domain layer.
90+
/// It's used by other higher-level components like the UDP and HTTP trackers or the tracker API.
5391
#[must_use]
5492
pub fn initialize_tracker(config: &Arc<Configuration>) -> Tracker {
5593
tracker_factory(config.clone())
5694
}
5795

96+
/// It initializes the log level, format and channel.
97+
///
98+
/// See [the logging setup](crate::bootstrap::logging::setup) for more info about logging.
5899
pub fn initialize_logging(config: &Arc<Configuration>) {
59100
bootstrap::logging::setup(config);
60101
}

‎src/bootstrap/jobs/http_tracker.rs‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
1+
//! HTTP tracker job starter.
2+
//!
3+
//! The function [`http_tracker::start_job`](crate::bootstrap::jobs::http_tracker::start_job) starts a new HTTP tracker server.
4+
//!
5+
//! > **NOTICE**: the application can launch more than one HTTP tracker on different ports.
6+
//! Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration) for the configuration options.
7+
//!
8+
//! The [`http_tracker::start_job`](crate::bootstrap::jobs::http_tracker::start_job) function spawns a new asynchronous task,
9+
//! that tasks is the "**launcher**". The "**launcher**" starts the actual server and sends a message back to the main application.
10+
//! The main application waits until receives the message [`ServerJobStarted`](crate::bootstrap::jobs::http_tracker::ServerJobStarted) from the "**launcher**".
11+
//!
12+
//! The "**launcher**" is an intermediary thread that decouples the HTTP servers from the process that handles it. The HTTP could be used independently in the future.
13+
//! In that case it would not need to notify a parent process.
114
use std::sync::Arc;
215

316
use axum_server::tls_rustls::RustlsConfig;
@@ -10,9 +23,16 @@ use crate::servers::http::v1::launcher;
1023
use crate::servers::http::Version;
1124
use crate::tracker;
1225

26+
/// This is the message that the "**launcher**" spawned task sends to the main application process to notify that the HTTP server was successfully started.
27+
///
28+
/// > **NOTICE**: it does not mean the HTTP server is ready to receive requests. It only means the new server started. It might take some time to the server to be ready to accept request.
1329
#[derive(Debug)]
1430
pub struct ServerJobStarted();
1531

32+
/// It starts a new HTTP server with the provided configuration and version.
33+
///
34+
/// Right now there is only one version but in the future we could support more than one HTTP tracker version at the same time.
35+
/// This feature allows supporting breaking changes on `BitTorrent` BEPs.
1636
pub async fn start_job(config: &HttpTracker, tracker: Arc<tracker::Tracker>, version: Version) -> JoinHandle<()> {
1737
match version {
1838
Version::V1 => start_v1(config, tracker.clone()).await,

‎src/bootstrap/jobs/mod.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
//! Application jobs launchers.
2+
//!
3+
//! The main application setup has only two main stages:
4+
//!
5+
//! 1. Setup the domain layer: the core tracker.
6+
//! 2. Launch all the application services as concurrent jobs.
7+
//!
8+
//! This modules contains all the functions needed to start those jobs.
19
pub mod http_tracker;
210
pub mod torrent_cleanup;
311
pub mod tracker_apis;

‎src/bootstrap/jobs/torrent_cleanup.rs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
//! Job that runs a task on intervals to clean up torrents.
2+
//!
3+
//! It removes inactive peers and (optionally) peerless torrents.
4+
//!
5+
//! **Inactive peers** are peers that have not been updated for more than `max_peer_timeout` seconds.
6+
//! `max_peer_timeout` is a customizable core tracker option.
7+
//!
8+
//! If the core tracker configuration option `remove_peerless_torrents` is true, the cleanup job will also
9+
//! remove **peerless torrents** which are torrents with an empty peer list.
10+
//!
11+
//! Refer to [`torrust-tracker-configuration documentation`](https://docs.rs/torrust-tracker-configuration) for more info about those options.
12+
113
use std::sync::Arc;
214

315
use chrono::Utc;
@@ -7,6 +19,11 @@ use torrust_tracker_configuration::Configuration;
719

820
use crate::tracker;
921

22+
/// It starts a jobs for cleaning up the torrent data in the tracker.
23+
///
24+
/// The cleaning task is executed on an `inactive_peer_cleanup_interval`.
25+
///
26+
/// Refer to [`torrust-tracker-configuration documentation`](https://docs.rs/torrust-tracker-configuration) for more info about that option.
1027
#[must_use]
1128
pub fn start_job(config: &Arc<Configuration>, tracker: &Arc<tracker::Tracker>) -> JoinHandle<()> {
1229
let weak_tracker = std::sync::Arc::downgrade(tracker);

‎src/bootstrap/jobs/tracker_apis.rs‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,25 @@
1+
//! Tracker API job starter.
2+
//!
3+
//! The [`tracker_apis::start_job`](crate::bootstrap::jobs::tracker_apis::start_job)
4+
//! function starts a the HTTP tracker REST API.
5+
//!
6+
//! > **NOTICE**: that even thought there is only one job the API has different
7+
//! versions. API consumers can choose which version to use. The API version is
8+
//! part of the URL, for example: `http://localhost:1212/api/v1/stats`.
9+
//!
10+
//! The [`tracker_apis::start_job`](crate::bootstrap::jobs::tracker_apis::start_job)
11+
//! function spawns a new asynchronous task, that tasks is the "**launcher**".
12+
//! The "**launcher**" starts the actual server and sends a message back
13+
//! to the main application. The main application waits until receives
14+
//! the message [`ApiServerJobStarted`](crate::bootstrap::jobs::tracker_apis::ApiServerJobStarted)
15+
//! from the "**launcher**".
16+
//!
17+
//! The "**launcher**" is an intermediary thread that decouples the API server
18+
//! from the process that handles it. The API could be used independently
19+
//! in the future. In that case it would not need to notify a parent process.
20+
//!
21+
//! Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration)
22+
//! for the API configuration options.
123
use std::sync::Arc;
224

325
use axum_server::tls_rustls::RustlsConfig;
@@ -9,9 +31,21 @@ use torrust_tracker_configuration::HttpApi;
931
use crate::servers::apis::server;
1032
use crate::tracker;
1133

34+
/// This is the message that the "launcher" spawned task sends to the main
35+
/// application process to notify the API server was successfully started.
36+
///
37+
/// > **NOTICE**: it does not mean the API server is ready to receive requests.
38+
/// It only means the new server started. It might take some time to the server
39+
/// to be ready to accept request.
1240
#[derive(Debug)]
1341
pub struct ApiServerJobStarted();
1442

43+
/// This function starts a new API server with the provided configuration.
44+
///
45+
/// The functions starts a new concurrent task that will run the API server.
46+
/// This task will send a message to the main application process to notify
47+
/// that the API server was successfully started.
48+
///
1549
/// # Panics
1650
///
1751
/// It would panic if unable to send the `ApiServerJobStarted` notice.

‎src/bootstrap/jobs/udp_tracker.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
//! UDP tracker job starter.
2+
//!
3+
//! The [`udp_tracker::start_job`](crate::bootstrap::jobs::udp_tracker::start_job)
4+
//! function starts a new UDP tracker server.
5+
//!
6+
//! > **NOTICE**: that the application can launch more than one UDP tracker
7+
//! on different ports. Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration)
8+
//! for the configuration options.
19
use std::sync::Arc;
210

311
use log::{error, info, warn};
@@ -7,6 +15,9 @@ use torrust_tracker_configuration::UdpTracker;
715
use crate::servers::udp::server::Udp;
816
use crate::tracker;
917

18+
/// It starts a new UDP server with the provided configuration.
19+
///
20+
/// It spawns a new asynchronous task for the new UDP server.
1021
#[must_use]
1122
pub fn start_job(config: &UdpTracker, tracker: Arc<tracker::Tracker>) -> JoinHandle<()> {
1223
let bind_addr = config.bind_address.clone();

‎src/bootstrap/logging.rs‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
//! Setup for the application logging.
2+
//!
3+
//! It redirects the log info to the standard output with the log level defined in the configuration.
4+
//!
5+
//! - `Off`
6+
//! - `Error`
7+
//! - `Warn`
8+
//! - `Info`
9+
//! - `Debug`
10+
//! - `Trace`
11+
//!
12+
//! Refer to the [configuration crate documentation](https://docs.rs/torrust-tracker-configuration) to know how to change log settings.
113
use std::str::FromStr;
214
use std::sync::Once;
315

@@ -6,6 +18,7 @@ use torrust_tracker_configuration::Configuration;
618

719
static INIT: Once = Once::new();
820

21+
/// It redirects the log info to the standard output with the log level defined in the configuration
922
pub fn setup(cfg: &Configuration) {
1023
let level = config_level_or_default(&cfg.log_level);
1124

‎src/bootstrap/mod.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
//! Tracker application bootstrapping.
2+
//!
3+
//! This module includes all the functions to build the application, its dependencies, and run the jobs.
4+
//!
5+
//! Jobs are tasks executed concurrently. Some of them are concurrent because of the asynchronous nature of the task,
6+
//! like cleaning torrents, and other jobs because they can be enabled/disabled depending on the configuration.
7+
//! For example, you can have more than one UDP and HTTP tracker, each server is executed like a independent job.
18
pub mod app;
29
pub mod jobs;
310
pub mod logging;

0 commit comments

Comments
 (0)