docs: [#1261] review docs for tracker-core package

Author: josecelano

packages/http-protocol/src/v1/query.rs

@@ -249,6 +249,13 @@ mod tests {
             assert_eq!(query.get_param("param2"), Some("value2".to_string()));
         }
 
+        #[test]
+        fn should_ignore_duplicate_param_values_when_asked_to_return_only_one_value() {
+            let query = Query::from(vec![("param1", "value1"), ("param1", "value2")]);
+
+            assert_eq!(query.get_param("param1"), Some("value1".to_string()));
+        }
+
         #[test]
         fn should_fail_parsing_an_invalid_query_string() {
             let invalid_raw_query = "name=value=value";

packages/tracker-core/src/announce_handler.rs

@@ -1,3 +1,87 @@
+//! Announce handler.
+//!
+//! Handling `announce` requests is the most important task for a `BitTorrent` tracker.
+//!
+//! A `BitTorrent` swarm is a network of peers that are all trying to download the same torrent.
+//! When a peer wants to find other peers it announces itself to the swarm via the tracker.
+//! The peer sends its data to the tracker so that the tracker can add it to the swarm.
+//! The tracker responds to the peer with the list of other peers in the swarm so that
+//! the peer can contact them to start downloading pieces of the file from them.
+//!
+//! Once you have instantiated the `AnnounceHandler` you can `announce` a new [`peer::Peer`](torrust_tracker_primitives) with:
+//!
+//! ```rust,no_run
+//! use std::net::SocketAddr;
+//! use std::net::IpAddr;
+//! use std::net::Ipv4Addr;
+//! use std::str::FromStr;
+//!
+//! use aquatic_udp_protocol::{AnnounceEvent, NumberOfBytes, PeerId};
+//! use torrust_tracker_primitives::DurationSinceUnixEpoch;
+//! use torrust_tracker_primitives::peer;
+//! use bittorrent_primitives::info_hash::InfoHash;
+//!
+//! let info_hash = InfoHash::from_str("3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0").unwrap();
+//!
+//! let peer = peer::Peer {
+//!     peer_id: PeerId(*b"-qB00000000000000001"),
+//!     peer_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(126, 0, 0, 1)), 8081),
+//!     updated: DurationSinceUnixEpoch::new(1_669_397_478_934, 0),
+//!     uploaded: NumberOfBytes::new(0),
+//!     downloaded: NumberOfBytes::new(0),
+//!     left: NumberOfBytes::new(0),
+//!     event: AnnounceEvent::Completed,
+//! };
+//!
+//! let peer_ip = IpAddr::V4(Ipv4Addr::from_str("126.0.0.1").unwrap());
+//! ```
+//!
+//! ```text
+//! let announce_data = announce_handler.announce(&info_hash, &mut peer, &peer_ip).await;
+//! ```
+//!
+//! The `Tracker` returns the list of peers for the torrent with the infohash `3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0`,
+//! filtering out the peer that is making the `announce` request.
+//!
+//! > **NOTICE**: that the peer argument is mutable because the `Tracker` can change the peer IP if the peer is using a loopback IP.
+//!
+//! The `peer_ip` argument is the resolved peer ip. It's a common practice that trackers ignore the peer ip in the `announce` request params,
+//! and resolve the peer ip using the IP of the client making the request. As the tracker is a domain service, the peer IP must be provided
+//! for the `Tracker` user, which is usually a higher component with access the the request metadata, for example, connection data, proxy headers,
+//! etcetera.
+//!
+//! The returned struct is:
+//!
+//! ```rust,no_run
+//! use torrust_tracker_primitives::peer;
+//! use torrust_tracker_configuration::AnnouncePolicy;
+//!
+//! pub struct AnnounceData {
+//!     pub peers: Vec<peer::Peer>,
+//!     pub swarm_stats: SwarmMetadata,
+//!     pub policy: AnnouncePolicy, // the tracker announce policy.
+//! }
+//!
+//! pub struct SwarmMetadata {
+//!     pub completed: u32, // The number of peers that have ever completed downloading
+//!     pub seeders: u32,   // The number of active peers that have completed downloading (seeders)
+//!     pub leechers: u32,  // The number of active peers that have not completed downloading (leechers)
+//! }
+//!
+//! // Core tracker configuration
+//! pub struct AnnounceInterval {
+//!     // ...
+//!     pub interval: u32, // Interval in seconds that the client should wait between sending regular announce requests to the tracker
+//!     pub interval_min: u32, // Minimum announce interval. Clients must not reannounce more frequently than this
+//!     // ...
+//! }
+//! ```
+//!
+//! Refer to `BitTorrent` BEPs and other sites for more information about the `announce` request:
+//!
+//! - [BEP 3. The `BitTorrent` Protocol Specification](https://www.bittorrent.org/beps/bep_0003.html)
+//! - [BEP 23. Tracker Returns Compact Peer Lists](https://www.bittorrent.org/beps/bep_0023.html)
+//! - [Vuze docs](https://wiki.vuze.com/w/Announce)
 use std::net::IpAddr;
 use std::sync::Arc;
 

packages/tracker-core/src/authentication/handler.rs

@@ -1,3 +1,11 @@
+//! This module implements the `KeysHandler` service
+//!
+//! It's responsible for managing authentication keys for the `BitTorrent` tracker.
+//!
+//! The service handles both persistent and in-memory storage of peer keys, and
+//! supports adding new keys (either pre-generated or randomly created),
+//! removing keys, and loading keys from the database into memory. Keys can be
+//! either permanent or expire after a configurable duration per key.
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -11,29 +19,44 @@ use super::{key, CurrentClock, Key, PeerKey};
 use crate::databases;
 use crate::error::PeerKeyError;
 
-/// This type contains the info needed to add a new tracker key.
+/// Contains the information needed to add a new tracker key.
 ///
-/// You can upload a pre-generated key or let the app to generate a new one.
-/// You can also set an expiration date or leave it empty (`None`) if you want
-/// to create a permanent key that does not expire.
+/// A new key can either be a pre-generated key provided by the user or can be
+/// randomly generated by the application. Additionally, the key may be set to
+/// expire after a certain number of seconds, or be permanent (if no expiration
+/// is specified).
 #[derive(Debug)]
 pub struct AddKeyRequest {
-    /// The pre-generated key. Use `None` to generate a random key.
+    /// The pre-generated key as a string. If `None` the service will generate a
+    ///  random key.
     pub opt_key: Option<String>,
 
-    /// How long the key will be valid in seconds. Use `None` for permanent keys.
+    /// The duration (in seconds) for which the key is valid. Use `None` for
+    /// permanent keys.
     pub opt_seconds_valid: Option<u64>,
 }
 
+/// The `KeysHandler` service manages the creation, addition, removal, and loading
+///  of authentication keys for the tracker.
+///
+/// It uses both a persistent (database) repository and an in-memory repository
+/// to manage keys.
 pub struct KeysHandler {
-    /// The database repository for the authentication keys.
+    /// The database repository for storing authentication keys persistently.
     db_key_repository: Arc<DatabaseKeyRepository>,
 
-    /// In-memory implementation of the authentication key repository.
+    /// The in-memory repository for caching authentication keys.
     in_memory_key_repository: Arc<InMemoryKeyRepository>,
 }
 
 impl KeysHandler {
+    /// Creates a new instance of the `KeysHandler` service.
+    ///
+    /// # Parameters
+    ///
+    /// - `db_key_repository`: A shared reference to the database key repository.
+    /// - `in_memory_key_repository`: A shared reference to the in-memory key
+    ///   repository.
     #[must_use]
     pub fn new(db_key_repository: &Arc<DatabaseKeyRepository>, in_memory_key_repository: &Arc<InMemoryKeyRepository>) -> Self {
         Self {
@@ -42,18 +65,24 @@ impl KeysHandler {
         }
     }
 
-    /// Adds new peer keys to the tracker.
+    /// Adds a new peer key to the tracker.
+    ///
+    /// The key may be pre-generated or generated on-the-fly.
+    ///
+    /// Depending on whether an expiration duration is specified, the key will
+    /// be either expiring or permanent.
     ///
-    /// Keys can be pre-generated or randomly created. They can also be
-    /// permanent or expire.
+    /// # Parameters
+    ///
+    /// - `add_key_req`: The request containing options for key creation.
     ///
     /// # Errors
     ///
-    /// Will return an error if:
+    /// Returns an error if:
     ///
-    /// - The key duration overflows the duration type maximum value.
+    /// - The provided key duration exceeds the maximum allowed value.
     /// - The provided pre-generated key is invalid.
-    /// - The key could not been persisted due to database issues.
+    /// - There is an error persisting the key in the database.
     pub async fn add_peer_key(&self, add_key_req: AddKeyRequest) -> Result<PeerKey, PeerKeyError> {
         if let Some(pre_existing_key) = add_key_req.opt_key {
             // Pre-generated key
@@ -125,29 +154,31 @@ impl KeysHandler {
         }
     }
 
-    /// It generates a new permanent authentication key.
+    /// Generates a new permanent authentication key.
     ///
-    /// Authentication keys are used by HTTP trackers.
+    /// Permanent keys do not expire.
     ///
     /// # Errors
     ///
-    /// Will return a `database::Error` if unable to add the `auth_key` to the database.
+    /// Returns a `databases::error::Error` if the key cannot be persisted in
+    /// the database.
     pub(crate) async fn generate_permanent_peer_key(&self) -> Result<PeerKey, databases::error::Error> {
         self.generate_expiring_peer_key(None).await
     }
 
-    /// It generates a new expiring authentication key.
+    /// Generates a new authentication key with an optional expiration lifetime.
     ///
-    /// Authentication keys are used by HTTP trackers.
+    /// If a `lifetime` is provided, the generated key will expire after that
+    /// duration. The new key is stored both in the database and in memory.
     ///
-    /// # Errors
+    /// # Parameters
     ///
-    /// Will return a `database::Error` if unable to add the `auth_key` to the database.
+    /// - `lifetime`: An optional duration specifying how long the key is valid.
     ///
-    /// # Arguments
+    /// # Errors
     ///
-    /// * `lifetime` - The duration in seconds for the new key. The key will be
-    ///   no longer valid after `lifetime` seconds.
+    /// Returns a `databases::error::Error` if there is an issue adding the key
+    /// to the database.
     pub async fn generate_expiring_peer_key(&self, lifetime: Option<Duration>) -> Result<PeerKey, databases::error::Error> {
         let peer_key = key::generate_key(lifetime);
 
@@ -158,36 +189,36 @@ impl KeysHandler {
         Ok(peer_key)
     }
 
-    /// It adds a pre-generated permanent authentication key.
+    /// Adds a pre-generated permanent authentication key.
     ///
-    /// Authentication keys are used by HTTP trackers.
+    /// Internally, this calls `add_expiring_peer_key` with no expiration.
     ///
-    /// # Errors
+    /// # Parameters
     ///
-    /// Will return a `database::Error` if unable to add the `auth_key` to the
-    /// database. For example, if the key already exist.
+    /// - `key`: The pre-generated key.
     ///
-    /// # Arguments
+    /// # Errors
     ///
-    /// * `key` - The pre-generated key.
+    /// Returns a `databases::error::Error` if there is an issue persisting the
+    /// key.
     pub(crate) async fn add_permanent_peer_key(&self, key: Key) -> Result<PeerKey, databases::error::Error> {
         self.add_expiring_peer_key(key, None).await
     }
 
-    /// It adds a pre-generated authentication key.
+    /// Adds a pre-generated authentication key with an optional expiration.
     ///
-    /// Authentication keys are used by HTTP trackers.
+    /// The key is stored in both the database and the in-memory repository.
     ///
-    /// # Errors
+    /// # Parameters
     ///
-    /// Will return a `database::Error` if unable to add the `auth_key` to the
-    /// database. For example, if the key already exist.
+    /// - `key`: The pre-generated key.
+    /// - `valid_until`: An optional timestamp (as a duration since the Unix
+    ///   epoch) after which the key expires.
     ///
-    /// # Arguments
+    /// # Errors
     ///
-    /// * `key` - The pre-generated key.
-    /// * `lifetime` - The duration in seconds for the new key. The key will be
-    ///   no longer valid after `lifetime` seconds.
+    /// Returns a `databases::error::Error` if there is an issue adding the key
+    /// to the database.
     pub(crate) async fn add_expiring_peer_key(
         &self,
         key: Key,
@@ -205,11 +236,18 @@ impl KeysHandler {
         Ok(peer_key)
     }
 
-    /// It removes an authentication key.
+    /// Removes an authentication key.
+    ///
+    /// The key is removed from both the database and the in-memory repository.
+    ///
+    /// # Parameters
+    ///
+    /// - `key`: A reference to the key to be removed.
     ///
     /// # Errors
     ///
-    /// Will return a `database::Error` if unable to remove the `key` to the database.
+    /// Returns a `databases::error::Error` if the key cannot be removed from
+    /// the database.
     pub async fn remove_peer_key(&self, key: &Key) -> Result<(), databases::error::Error> {
         self.db_key_repository.remove(key)?;
 
@@ -218,19 +256,26 @@ impl KeysHandler {
         Ok(())
     }
 
-    /// It removes an authentication key from memory.
+    /// Removes an authentication key from the in-memory repository.
+    ///
+    /// This function does not interact with the database.
+    ///
+    /// # Parameters
+    ///
+    /// - `key`: A reference to the key to be removed.
     pub(crate) async fn remove_in_memory_auth_key(&self, key: &Key) {
         self.in_memory_key_repository.remove(key).await;
     }
 
-    /// The `Tracker` stores the authentication keys in memory and in the
-    /// database. In case you need to restart the `Tracker` you can load the
-    /// keys from the database into memory with this function. Keys are
-    /// automatically stored in the database when they are generated.
+    /// Loads all authentication keys from the database into the in-memory
+    /// repository.
+    ///
+    /// This is useful during tracker startup to ensure that all persisted keys
+    /// are available in memory.
     ///
     /// # Errors
     ///
-    /// Will return a `database::Error` if unable to `load_keys` from the database.
+    /// Returns a `databases::error::Error` if there is an issue loading the keys from the database.
     pub async fn load_peer_keys_from_database(&self) -> Result<(), databases::error::Error> {
         let keys_from_database = self.db_key_repository.load_keys()?;
 

packages/tracker-core/src/authentication/key/peer_key.rs

@@ -1,3 +1,13 @@
+//! Authentication keys for private trackers.
+//!
+//! This module defines the types and functionality for managing authentication
+//! keys used by the tracker. These keys, represented by the `Key` and `PeerKey`
+//!  types, are essential for authenticating peers in private tracker
+//! environments.
+//!
+//! A `Key` is a 32-character alphanumeric token, while a `PeerKey` couples a
+//! `Key` with an optional expiration timestamp. If the expiration is set (via
+//! `valid_until`), the key will become invalid after that time.
 use std::str::FromStr;
 use std::time::Duration;
 
@@ -11,8 +21,28 @@ use torrust_tracker_primitives::DurationSinceUnixEpoch;
 
 use super::AUTH_KEY_LENGTH;
 
-/// An authentication key which can potentially have an expiration time.
-/// After that time is will automatically become invalid.
+/// A peer authentication key with an optional expiration time.
+///
+/// A `PeerKey` associates a generated `Key` (a 32-character alphanumeric string)
+/// with an optional expiration timestamp (`valid_until`). If `valid_until` is
+/// `None`, the key is considered permanent.
+///
+/// # Example
+///
+/// ```rust
+/// use std::time::Duration;
+/// use bittorrent_tracker_core::authentication::key::peer_key::{Key, PeerKey};
+///
+/// let expiring_key = PeerKey {
+///     key: Key::random(),
+///     valid_until: Some(Duration::from_secs(3600)), // Expires in 1 hour
+/// };
+///
+/// let permanent_key = PeerKey {
+///     key: Key::random(),
+///     valid_until: None,
+/// };
+/// ```
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct PeerKey {
     /// Random 32-char string. For example: `YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ`