Merge #258: docs: crate docs for core tracker and bootstrap mods

fe28ef5 docs: [#256] crate docs for tracker and bootstrap mods (Jose Celano)

Pull request description:

  Documentation for:

  - [Tracker mod](https://github.com/torrust/torrust-tracker/tree/develop/src/tracker)
  - [Bootstrap mod](https://github.com/torrust/torrust-tracker/tree/develop/src/bootstrap)

Top commit has no ACKs.

Tree-SHA512: c1f6cc83259a3d121de7b5fcee93dffe878064533bd5376b40256d306b59659fc6cc10eef74c5191dffc38339b6adc53d0b987ed8547fc54bcdf3e846694f5ef

cSpell.json

@@ -51,6 +51,7 @@
         "proot",
         "Quickstart",
         "Rasterbar",
+        "reannounce",
         "repr",
         "reqwest",
         "rngs",

packages/configuration/src/lib.rs

@@ -59,17 +59,26 @@ impl HttpApi {
 pub struct Configuration {
     pub log_level: Option<String>,
     pub mode: TrackerMode,
+
+    // Database configuration
     pub db_driver: DatabaseDriver,
     pub db_path: String,
+
+    /// Interval in seconds that the client should wait between sending regular announce requests to the tracker
     pub announce_interval: u32,
+    /// Minimum announce interval. Clients must not reannounce more frequently than this
     pub min_announce_interval: u32,
-    pub max_peer_timeout: u32,
     pub on_reverse_proxy: bool,
     pub external_ip: Option<String>,
     pub tracker_usage_statistics: bool,
     pub persistent_torrent_completed_stat: bool,
+
+    // Cleanup job configuration
+    pub max_peer_timeout: u32,
     pub inactive_peer_cleanup_interval: u64,
     pub remove_peerless_torrents: bool,
+
+    // Server jobs configuration
     pub udp_trackers: Vec<UdpTracker>,
     pub http_trackers: Vec<HttpTracker>,
     pub http_api: HttpApi,

src/bootstrap/app.rs

@@ -1,3 +1,16 @@
+//! Setup for the main tracker application.
+//!
+//! The [`setup`](bootstrap::app::setup) only builds the application and its dependencies but it does not start the application.
+//! In fact, there is no such thing as the main application process. When the application starts, the only thing it does is
+//! starting a bunch of independent jobs. If you are looking for how things are started you should read [`app::start`](crate::app::start)
+//! function documentation.
+//!
+//! Setup steps:
+//!
+//! 1. Load the global application configuration.
+//! 2. Initialize static variables.
+//! 3. Initialize logging.
+//! 4. Initialize the domain tracker.
 use std::env;
 use std::sync::Arc;
 
@@ -9,6 +22,7 @@ use crate::shared::crypto::ephemeral_instance_keys;
 use crate::tracker::services::tracker_factory;
 use crate::tracker::Tracker;
 
+/// It loads the configuration from the environment and builds the main domain [`tracker`](crate::tracker::Tracker) struct.
 #[must_use]
 pub fn setup() -> (Arc<Configuration>, Arc<Tracker>) {
     let configuration = Arc::new(initialize_configuration());
@@ -17,13 +31,22 @@ pub fn setup() -> (Arc<Configuration>, Arc<Tracker>) {
     (configuration, tracker)
 }
 
+/// It initializes the application with the given configuration.
+///
+/// The configuration may be obtained from the environment (via config file or env vars).
 #[must_use]
 pub fn initialize_with_configuration(configuration: &Arc<Configuration>) -> Arc<Tracker> {
     initialize_static();
     initialize_logging(configuration);
     Arc::new(initialize_tracker(configuration))
 }
 
+/// It initializes the application static values.
+///
+/// These values are accessible throughout the entire application:
+///
+/// - The time when the application started.
+/// - An ephemeral instance random seed. This seed is used for encryption and it's changed when the main application process is restarted.
 pub fn initialize_static() {
     // Set the time of Torrust app starting
     lazy_static::initialize(&static_time::TIME_AT_APP_START);
@@ -32,6 +55,17 @@ pub fn initialize_static() {
     lazy_static::initialize(&ephemeral_instance_keys::RANDOM_SEED);
 }
 
+/// It loads the application configuration from the environment.
+///
+/// There are two methods to inject the configuration:
+///
+/// 1. By using a config file: `config.toml`. The file must be in the same folder where you are running the tracker.
+/// 2. Environment variable: `TORRUST_TRACKER_CONFIG`. The variable contains the same contents as the `config.toml` file.
+///
+/// Environment variable has priority over the config file.
+///
+/// Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration) for the configuration options.
+///
 /// # Panics
 ///
 /// Will panic if it can't load the configuration from either
@@ -50,11 +84,18 @@ fn initialize_configuration() -> Configuration {
     }
 }
 
+/// It builds the domain tracker
+///
+/// The tracker is the domain layer service. It's the entrypoint to make requests to the domain layer.
+/// It's used by other higher-level components like the UDP and HTTP trackers or the tracker API.
 #[must_use]
 pub fn initialize_tracker(config: &Arc<Configuration>) -> Tracker {
     tracker_factory(config.clone())
 }
 
+/// It initializes the log level, format and channel.
+///
+/// See [the logging setup](crate::bootstrap::logging::setup) for more info about logging.
 pub fn initialize_logging(config: &Arc<Configuration>) {
     bootstrap::logging::setup(config);
 }

src/bootstrap/jobs/http_tracker.rs

@@ -1,3 +1,16 @@
+//! HTTP tracker job starter.
+//!
+//! The function [`http_tracker::start_job`](crate::bootstrap::jobs::http_tracker::start_job) starts a new HTTP tracker server.
+//!
+//! > **NOTICE**: the application can launch more than one HTTP tracker on different ports.
+//! Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration) for the configuration options.
+//!
+//! The [`http_tracker::start_job`](crate::bootstrap::jobs::http_tracker::start_job) function spawns a new asynchronous task,
+//! that tasks is the "**launcher**". The "**launcher**" starts the actual server and sends a message back to the main application.
+//! The main application waits until receives the message [`ServerJobStarted`](crate::bootstrap::jobs::http_tracker::ServerJobStarted) from the "**launcher**".
+//!
+//! 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.
+//! In that case it would not need to notify a parent process.
 use std::sync::Arc;
 
 use axum_server::tls_rustls::RustlsConfig;
@@ -10,9 +23,16 @@ use crate::servers::http::v1::launcher;
 use crate::servers::http::Version;
 use crate::tracker;
 
+/// This is the message that the "**launcher**" spawned task sends to the main application process to notify that the HTTP server was successfully started.
+///
+/// > **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.
 #[derive(Debug)]
 pub struct ServerJobStarted();
 
+/// It starts a new HTTP server with the provided configuration and version.
+///
+/// Right now there is only one version but in the future we could support more than one HTTP tracker version at the same time.
+/// This feature allows supporting breaking changes on `BitTorrent` BEPs.
 pub async fn start_job(config: &HttpTracker, tracker: Arc<tracker::Tracker>, version: Version) -> JoinHandle<()> {
     match version {
         Version::V1 => start_v1(config, tracker.clone()).await,

src/bootstrap/jobs/mod.rs

@@ -1,3 +1,11 @@
+//! Application jobs launchers.
+//!
+//! The main application setup has only two main stages:
+//!
+//! 1. Setup the domain layer: the core tracker.
+//! 2. Launch all the application services as concurrent jobs.
+//!
+//! This modules contains all the functions needed to start those jobs.
 pub mod http_tracker;
 pub mod torrent_cleanup;
 pub mod tracker_apis;

src/bootstrap/jobs/torrent_cleanup.rs

@@ -1,3 +1,15 @@
+//! Job that runs a task on intervals to clean up torrents.
+//!
+//! It removes inactive peers and (optionally) peerless torrents.
+//!
+//! **Inactive peers** are peers that have not been updated for more than `max_peer_timeout` seconds.
+//! `max_peer_timeout` is a customizable core tracker option.
+//!
+//! If the core tracker configuration option `remove_peerless_torrents` is true, the cleanup job will also
+//! remove **peerless torrents** which are torrents with an empty peer list.
+//!
+//! Refer to [`torrust-tracker-configuration documentation`](https://docs.rs/torrust-tracker-configuration) for more info about those options.
+
 use std::sync::Arc;
 
 use chrono::Utc;
@@ -7,6 +19,11 @@ use torrust_tracker_configuration::Configuration;
 
 use crate::tracker;
 
+/// It starts a jobs for cleaning up the torrent data in the tracker.
+///
+/// The cleaning task is executed on an `inactive_peer_cleanup_interval`.
+///
+/// Refer to [`torrust-tracker-configuration documentation`](https://docs.rs/torrust-tracker-configuration) for more info about that option.
 #[must_use]
 pub fn start_job(config: &Arc<Configuration>, tracker: &Arc<tracker::Tracker>) -> JoinHandle<()> {
     let weak_tracker = std::sync::Arc::downgrade(tracker);

src/bootstrap/jobs/tracker_apis.rs

@@ -1,3 +1,25 @@
+//! Tracker API job starter.
+//!
+//! The [`tracker_apis::start_job`](crate::bootstrap::jobs::tracker_apis::start_job)
+//! function starts a the HTTP tracker REST API.
+//!
+//! > **NOTICE**: that even thought there is only one job the API has different
+//! versions. API consumers can choose which version to use. The API version is
+//! part of the URL, for example: `http://localhost:1212/api/v1/stats`.
+//!
+//! The [`tracker_apis::start_job`](crate::bootstrap::jobs::tracker_apis::start_job)  
+//! function spawns a new asynchronous task, that tasks is the "**launcher**".
+//! The "**launcher**" starts the actual server and sends a message back
+//! to the main application. The main application waits until receives
+//! the message [`ApiServerJobStarted`](crate::bootstrap::jobs::tracker_apis::ApiServerJobStarted)
+//! from the "**launcher**".
+//!
+//! The "**launcher**" is an intermediary thread that decouples the API server
+//! from the process that handles it. The API could be used independently
+//! in the future. In that case it would not need to notify a parent process.
+//!
+//! Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration)
+//! for the API configuration options.
 use std::sync::Arc;
 
 use axum_server::tls_rustls::RustlsConfig;
@@ -9,9 +31,21 @@ use torrust_tracker_configuration::HttpApi;
 use crate::servers::apis::server;
 use crate::tracker;
 
+/// This is the message that the "launcher" spawned task sends to the main
+/// application process to notify the API server was successfully started.
+///
+/// > **NOTICE**: it does not mean the API 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.
 #[derive(Debug)]
 pub struct ApiServerJobStarted();
 
+/// This function starts a new API server with the provided configuration.
+///
+/// The functions starts a new concurrent task that will run the API server.
+/// This task will send a message to the main application process to notify
+/// that the API server was successfully started.
+///
 /// # Panics
 ///
 /// It would panic if unable to send the  `ApiServerJobStarted` notice.

src/bootstrap/jobs/udp_tracker.rs

@@ -1,3 +1,11 @@
+//! UDP tracker job starter.
+//!
+//! The [`udp_tracker::start_job`](crate::bootstrap::jobs::udp_tracker::start_job)
+//! function starts a new UDP tracker server.
+//!
+//! > **NOTICE**: that the application can launch more than one UDP tracker
+//! on different ports. Refer to the [configuration documentation](https://docs.rs/torrust-tracker-configuration)
+//! for the configuration options.
 use std::sync::Arc;
 
 use log::{error, info, warn};
@@ -7,6 +15,9 @@ use torrust_tracker_configuration::UdpTracker;
 use crate::servers::udp::server::Udp;
 use crate::tracker;
 
+/// It starts a new UDP server with the provided configuration.
+///
+/// It spawns a new asynchronous task for the new UDP server.
 #[must_use]
 pub fn start_job(config: &UdpTracker, tracker: Arc<tracker::Tracker>) -> JoinHandle<()> {
     let bind_addr = config.bind_address.clone();

src/bootstrap/logging.rs

@@ -1,3 +1,15 @@
+//! Setup for the application logging.
+//!
+//! It redirects the log info to the standard output with the log level defined in the configuration.
+//!
+//! - `Off`
+//! - `Error`
+//! - `Warn`
+//! - `Info`
+//! - `Debug`
+//! - `Trace`
+//!
+//! Refer to the [configuration crate documentation](https://docs.rs/torrust-tracker-configuration) to know how to change log settings.
 use std::str::FromStr;
 use std::sync::Once;
 
@@ -6,6 +18,7 @@ use torrust_tracker_configuration::Configuration;
 
 static INIT: Once = Once::new();
 
+/// It redirects the log info to the standard output with the log level defined in the configuration
 pub fn setup(cfg: &Configuration) {
     let level = config_level_or_default(&cfg.log_level);
 

src/bootstrap/mod.rs

@@ -1,3 +1,10 @@
+//! Tracker application bootstrapping.
+//!
+//! This module includes all the functions to build the application, its dependencies, and run the jobs.
+//!
+//! Jobs are tasks executed concurrently. Some of them are concurrent because of the asynchronous nature of the task,
+//! like cleaning torrents, and other jobs because they can be enabled/disabled depending on the configuration.
+//! For example, you can have more than one UDP and HTTP tracker, each server is executed like a independent job.
 pub mod app;
 pub mod jobs;
 pub mod logging;

src/lib.rs

@@ -27,10 +27,15 @@
 //! - [Features](#features)
 //! - [Services](#services)
 //! - [Installation](#installation)
+//!     - [Minimum requirements](#minimum-requirements)
+//!     - [Prerequisites](#prerequisites)
+//!     - [Install from sources](#install-from-sources)
+//!     - [Run with docker](#run-with-docker)
 //! - [Configuration](#configuration)
 //! - [Usage](#usage)
 //! - [Components](#components)
 //! - [Implemented BEPs](#implemented-beps)
+//! - [Contributing](#contributing)
 //!
 //! # Features
 //!
@@ -356,7 +361,7 @@
 //! - The [`UDP`](crate::servers::udp) tracker
 //! - The [`HTTP`](crate::servers::http) tracker
 //!
-//! ![Torrust Tracker Components](https://github.com/torrust/torrust-tracker/blob/main/docs/media/torrust-tracker-components.png)
+//! ![Torrust Tracker Components](https://raw.githubusercontent.com/torrust/torrust-tracker/main/docs/media/torrust-tracker-components.png)
 //!
 //! ## Core tracker
 //!
@@ -421,6 +426,10 @@
 //! - [BEP 27](https://www.bittorrent.org/beps/bep_0027.html): Private Torrents
 //! - [BEP 41](https://www.bittorrent.org/beps/bep_0041.html): UDP Tracker Protocol Extensions
 //! - [BEP 48](https://www.bittorrent.org/beps/bep_0048.html): Tracker Protocol Extension: Scrape
+//!
+//! # Contributing
+//!
+//! If you want to contribute to this documentation you can [open a new pull request](https://github.com/torrust/torrust-tracker/pulls).
 pub mod app;
 pub mod bootstrap;
 pub mod servers;