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/mod.rs

@@ -1,42 +1,45 @@
-//! Tracker authentication services and structs.
+//! Tracker authentication services and types.
 //!
-//! This module contains functions to handle tracker keys.
-//! Tracker keys are tokens used to authenticate the tracker clients when the tracker runs
-//! in `private` or `private_listed` modes.
+//! This module provides functions and data structures for handling tracker keys.
+//! Tracker keys are tokens used to authenticate tracker clients when the
+//! tracker is running in `private` mode.
 //!
-//! There are services to [`generate_key`]  and [`verify_key_expiration`]  authentication keys.
+//! Authentication keys are used exclusively by HTTP trackers. Every key has an
+//! expiration time, meaning that it is only valid for a predetermined period.
+//! Once the expiration time is reached, an expiring key will be rejected.
 //!
-//! Authentication keys are used only by HTTP trackers. All keys have an expiration time, that means
-//! they are only valid during a period of time. After that time the expiring key will no longer be valid.
+//! The primary key structure is [`PeerKey`], which couples a randomly generated
+//!  [`Key`] (a 32-character alphanumeric string) with an optional expiration
+//! timestamp.
 //!
-//! Keys are stored in this struct:
+//! # Examples
 //!
-//! ```rust,no_run
+//! Generating a new key valid for `9999` seconds:
+//!
+//! ```rust
+//! use bittorrent_tracker_core::authentication;
+//! use std::time::Duration;
+//!
+//! let expiring_key = authentication::key::generate_key(Some(Duration::new(9999, 0)));
+//!
+//! // Later, verify that the key is still valid.
+//! assert!(authentication::key::verify_key_expiration(&expiring_key).is_ok());
+//! ```
+//!
+//! The core key types are defined as follows:
+//!
+//! ```rust
 //! use bittorrent_tracker_core::authentication::Key;
 //! use torrust_tracker_primitives::DurationSinceUnixEpoch;
 //!
 //! pub struct PeerKey {
-//!     /// Random 32-char string. For example: `YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ`
+//!     /// A random 32-character authentication token (e.g., `YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ`)
 //!     pub key: Key,
 //!
-//!     /// Timestamp, the key will be no longer valid after this timestamp.
-//!     /// If `None` the keys will not expire (permanent key).
+//!     /// The timestamp after which the key expires. If `None`, the key is permanent.
 //!     pub valid_until: Option<DurationSinceUnixEpoch>,
 //! }
 //! ```
-//!
-//! You can generate a new key valid for `9999` seconds and `0` nanoseconds from the current time with the following:
-//!
-//! ```rust,no_run
-//! use bittorrent_tracker_core::authentication;
-//! use std::time::Duration;
-//!
-//! let expiring_key = authentication::key::generate_key(Some(Duration::new(9999, 0)));
-//!
-//! // And you can later verify it with:
-//!
-//! assert!(authentication::key::verify_key_expiration(&expiring_key).is_ok());
-//! ```
 pub mod peer_key;
 pub mod repository;
 
@@ -75,17 +78,33 @@ pub(crate) fn generate_expiring_key(lifetime: Duration) -> PeerKey {
     generate_key(Some(lifetime))
 }
 
-/// It generates a new random 32-char authentication [`PeerKey`].
+/// Generates a new random 32-character authentication key (`PeerKey`).
 ///
-/// It can be an expiring or permanent key.
+/// If a lifetime is provided, the generated key will expire after the specified
+///  duration; otherwise, the key is permanent (i.e., it never expires).
 ///
 /// # Panics
 ///
-/// It would panic if the `lifetime: Duration` + Duration is more than `Duration::MAX`.
+/// Panics if the addition of the lifetime to the current time overflows
+/// (an extremely unlikely event).
 ///
 /// # Arguments
 ///
-/// * `lifetime`: if `None` the key will be permanent.
+/// * `lifetime`: An optional duration specifying how long the key is valid.
+///   If `None`, the key is permanent.
+///
+/// # Examples
+///
+/// ```rust
+/// use bittorrent_tracker_core::authentication::key;
+/// use std::time::Duration;
+///
+/// // Generate an expiring key valid for 3600 seconds.
+/// let expiring_key = key::generate_key(Some(Duration::from_secs(3600)));
+///
+/// // Generate a permanent key.
+/// let permanent_key = key::generate_key(None);
+/// ```
 #[must_use]
 pub fn generate_key(lifetime: Option<Duration>) -> PeerKey {
     let random_key = Key::random();
@@ -107,13 +126,27 @@ pub fn generate_key(lifetime: Option<Duration>) -> PeerKey {
     }
 }
 
-/// It verifies an [`PeerKey`]. It checks if the expiration date has passed.
-/// Permanent keys without duration (`None`) do not expire.
+/// Verifies whether a given authentication key (`PeerKey`) is still valid.
+///
+/// For expiring keys, this function compares the key's expiration timestamp
+/// against the current time. Permanent keys (with `None` as their expiration)
+/// are always valid.
 ///
 /// # Errors
 ///
-/// Will return a verification error [`enum@crate::authentication::key::Error`] if
-/// it cannot verify the key.
+/// Returns a verification error of type [`enum@Error`] if the key has expired.
+///
+/// # Examples
+///
+/// ```rust
+/// use bittorrent_tracker_core::authentication::key;
+/// use std::time::Duration;
+///
+/// let expiring_key = key::generate_key(Some(Duration::from_secs(100)));
+///
+/// // If the key's expiration time has passed, the verification will fail.
+/// assert!(key::verify_key_expiration(&expiring_key).is_ok());
+/// ```
 pub fn verify_key_expiration(auth_key: &PeerKey) -> Result<(), Error> {
     let current_time: DurationSinceUnixEpoch = CurrentClock::now();
 
@@ -136,17 +169,20 @@ pub fn verify_key_expiration(auth_key: &PeerKey) -> Result<(), Error> {
 #[derive(Debug, Error)]
 #[allow(dead_code)]
 pub enum Error {
+    /// Wraps an underlying error encountered during key verification.
     #[error("Key could not be verified: {source}")]
     KeyVerificationError {
         source: LocatedError<'static, dyn std::error::Error + Send + Sync>,
     },
 
+    /// Indicates that the key could not be read or found.
     #[error("Failed to read key: {key}, {location}")]
     UnableToReadKey {
         location: &'static Location<'static>,
         key: Box<Key>,
     },
 
+    /// Indicates that the key has expired.
     #[error("Key has expired, {location}")]
     KeyExpired { location: &'static Location<'static> },
 }

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,22 +21,42 @@ 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`
+    /// A 32-character authentication key. For example: `YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ`
     pub key: Key,
 
-    /// Timestamp, the key will be no longer valid after this timestamp.
-    /// If `None` the keys will not expire (permanent key).
+    /// An optional expiration timestamp. If set, the key becomes invalid after
+    /// this time. A value of `None` indicates a permanent key.
     pub valid_until: Option<DurationSinceUnixEpoch>,
 }
 
 impl PartialEq for PeerKey {
     fn eq(&self, other: &Self) -> bool {
-        // We ignore the fractions of seconds when comparing the timestamps
-        // because we only store the seconds in the database.
+        // When comparing two PeerKeys, ignore fractions of seconds since only
+        // whole seconds are stored in the database.
         self.key == other.key
             && match (&self.valid_until, &other.valid_until) {
                 (Some(a), Some(b)) => a.as_secs() == b.as_secs(),
@@ -53,14 +83,17 @@ impl PeerKey {
         self.key.clone()
     }
 
-    /// It returns the expiry time. For example, for the starting time for Unix Epoch
-    /// (timestamp 0) it will return a `DateTime` whose string representation is
-    /// `1970-01-01 00:00:00 UTC`.
+    /// Computes and returns the expiration time as a UTC `DateTime`, if one
+    /// exists.
+    ///
+    /// The returned time is derived from the stored seconds since the Unix
+    /// epoch. Note that any fractional seconds are discarded since only whole
+    /// seconds are stored in the database.
     ///
     /// # Panics
     ///
-    /// Will panic when the key timestamp overflows the internal i64 type.
-    /// (this will naturally happen in 292.5 billion years)
+    /// Panics if the key's timestamp overflows the internal `i64` type (this is
+    ///  extremely unlikely, happening roughly 292.5 billion years from now).
     #[must_use]
     pub fn expiry_time(&self) -> Option<chrono::DateTime<chrono::Utc>> {
         // We remove the fractions of seconds because we only store the seconds
@@ -72,17 +105,37 @@ impl PeerKey {
 
 /// A token used for authentication.
 ///
-/// - It contains only ascii alphanumeric chars: lower and uppercase letters and
-///   numbers.
-/// - It's a 32-char string.
+/// The `Key` type encapsulates a 32-character string that must consist solely
+/// of ASCII alphanumeric characters (0-9, a-z, A-Z). This key is used by the
+/// tracker to authenticate peers.
+///
+/// # Examples
+///
+/// Creating a key from a valid string:
+///
+/// ```
+/// use bittorrent_tracker_core::authentication::key::peer_key::Key;
+/// let key = Key::new("YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ").unwrap();
+/// ```
+///
+/// Generating a random key:
+///
+/// ```
+/// use bittorrent_tracker_core::authentication::key::peer_key::Key;
+/// let random_key = Key::random();
+/// ```
 #[derive(Serialize, Deserialize, Debug, Eq, PartialEq, Clone, Display, Hash)]
 pub struct Key(String);
 
 impl Key {
+    /// Constructs a new `Key` from the given string.
+    ///
     /// # Errors
     ///
-    /// Will return an error is the string represents an invalid key.
-    /// Valid keys can only contain 32 chars including 0-9, a-z and A-Z.
+    /// Returns a `ParseKeyError` if:
+    ///
+    /// - The input string does not have exactly 32 characters.
+    /// - The input string contains characters that are not ASCII alphanumeric.
     pub fn new(value: &str) -> Result<Self, ParseKeyError> {
         if value.len() != AUTH_KEY_LENGTH {
             return Err(ParseKeyError::InvalidKeyLength);
@@ -95,11 +148,14 @@ impl Key {
         Ok(Self(value.to_owned()))
     }
 
-    /// It generates a random key.
+    /// Generates a new random authentication key.
+    ///
+    /// The random key is generated by sampling 32 ASCII alphanumeric characters.
     ///
     /// # Panics
     ///
-    /// Will panic if the random number generator fails to generate a valid key.
+    /// Panics if the random number generator fails to produce a valid key
+    /// (extremely unlikely).
     pub fn random() -> Self {
         let random_id: String = rng()
             .sample_iter(&Alphanumeric)
@@ -115,9 +171,11 @@ impl Key {
     }
 }
 
-/// Error returned when a key cannot be parsed from a string.
+/// Errors that can occur when parsing a string into a `Key`.
+///
+/// # Examples
 ///
-/// ```text
+/// ```rust
 /// use bittorrent_tracker_core::authentication::Key;
 /// use std::str::FromStr;
 ///
@@ -132,9 +190,12 @@ impl Key {
 /// this error.
 #[derive(Debug, Error)]
 pub enum ParseKeyError {
+    /// The provided key does not have exactly 32 characters.
     #[error("Invalid key length. Key must be have 32 chars")]
     InvalidKeyLength,
 
+    /// The provided key contains invalid characters. Only ASCII alphanumeric
+    /// characters are allowed.
     #[error("Invalid chars for key. Key can only alphanumeric chars (0-9, a-z, A-Z)")]
     InvalidChars,
 }

packages/tracker-core/src/authentication/key/repository/in_memory.rs

@@ -1,35 +1,78 @@
+//! In-memory implementation of the authentication key repository.
 use crate::authentication::key::{Key, PeerKey};
 
-/// In-memory implementation of the authentication key repository.
+/// An in-memory repository for storing authentication keys.
+///
+/// This repository maintains a mapping between a peer's [`Key`] and its
+/// corresponding [`PeerKey`]. It is designed for use in private tracker
+/// environments where keys are maintained in memory.
 #[derive(Debug, Default)]
 pub struct InMemoryKeyRepository {
     /// Tracker users' keys. Only for private trackers.
     keys: tokio::sync::RwLock<std::collections::HashMap<Key, PeerKey>>,
 }
 
 impl InMemoryKeyRepository {
-    /// It adds a new authentication key.
+    /// Inserts a new authentication key into the repository.
+    ///
+    /// This function acquires a write lock on the internal storage and inserts
+    /// the provided [`PeerKey`], using its inner [`Key`] as the map key.
+    ///
+    /// # Arguments
+    ///
+    /// * `auth_key` - A reference to the [`PeerKey`] to be inserted.
     pub(crate) async fn insert(&self, auth_key: &PeerKey) {
         self.keys.write().await.insert(auth_key.key.clone(), auth_key.clone());
     }
 
-    /// It removes an authentication key.
+    /// Removes an authentication key from the repository.
+    ///
+    /// This function acquires a write lock on the internal storage and removes
+    /// the key that matches the provided [`Key`].
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - A reference to the [`Key`] corresponding to the key to be removed.
     pub(crate) async fn remove(&self, key: &Key) {
         self.keys.write().await.remove(key);
     }
 
+    /// Retrieves an authentication key from the repository.
+    ///
+    /// This function acquires a read lock on the internal storage and returns a
+    ///  cloned [`PeerKey`] if the provided [`Key`] exists.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - A reference to the [`Key`] to look up.
+    ///
+    /// # Returns
+    ///
+    /// An `Option<PeerKey>` containing the matching key if found, or `None`
+    /// otherwise.
     pub(crate) async fn get(&self, key: &Key) -> Option<PeerKey> {
         self.keys.read().await.get(key).cloned()
     }
 
-    /// It clears all the authentication keys.
+    /// Clears all authentication keys from the repository.
+    ///
+    /// This function acquires a write lock on the internal storage and removes
+    /// all entries.
     #[allow(dead_code)]
     pub(crate) async fn clear(&self) {
         let mut keys = self.keys.write().await;
         keys.clear();
     }
 
-    /// It resets the authentication keys with a new list of keys.
+    /// Resets the repository with a new list of authentication keys.
+    ///
+    /// This function clears all existing keys and then inserts each key from
+    /// the provided vector.
+    ///
+    /// # Arguments
+    ///
+    /// * `peer_keys` - A vector of [`PeerKey`] instances that will replace the
+    ///   current set of keys.
     pub async fn reset_with(&self, peer_keys: Vec<PeerKey>) {
         let mut keys_lock = self.keys.write().await;
 

packages/tracker-core/src/authentication/key/repository/mod.rs

@@ -1,2 +1,3 @@
+//! Key repository implementations.
 pub mod in_memory;
 pub mod persisted;

packages/tracker-core/src/authentication/key/repository/persisted.rs

@@ -1,46 +1,72 @@
+//! The database repository for the authentication keys.
 use std::sync::Arc;
 
 use crate::authentication::key::{Key, PeerKey};
 use crate::databases::{self, Database};
 
-/// The database repository for the authentication keys.
+/// A repository for storing authentication keys in a persistent database.
+///
+/// This repository provides methods to add, remove, and load authentication
+/// keys from the underlying database. It wraps an instance of a type
+/// implementing the [`Database`] trait.
 pub struct DatabaseKeyRepository {
     database: Arc<Box<dyn Database>>,
 }
 
 impl DatabaseKeyRepository {
+    /// Creates a new `DatabaseKeyRepository` instance.
+    ///
+    /// # Arguments
+    ///
+    /// * `database` - A shared reference to a boxed database implementation.
+    ///
+    /// # Returns
+    ///
+    /// A new instance of `DatabaseKeyRepository`
     #[must_use]
     pub fn new(database: &Arc<Box<dyn Database>>) -> Self {
         Self {
             database: database.clone(),
         }
     }
 
-    /// It adds a new key to the database.
+    /// Adds a new authentication key to the database.
+    ///
+    /// # Arguments
+    ///
+    /// * `peer_key` - A reference to the [`PeerKey`] to be persisted.
     ///
     /// # Errors
     ///
-    /// Will return a `databases::error::Error` if unable to add the `auth_key` to the database.
+    /// Returns a [`databases::error::Error`] if the key cannot be added.
     pub(crate) fn add(&self, peer_key: &PeerKey) -> Result<(), databases::error::Error> {
         self.database.add_key_to_keys(peer_key)?;
         Ok(())
     }
 
-    /// It removes an key from the database.
+    /// Removes an authentication key from the database.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - A reference to the [`Key`] corresponding to the key to remove.
     ///
     /// # Errors
     ///
-    /// Will return a `database::Error` if unable to remove the `key` from the database.
+    /// Returns a [`databases::error::Error`] if the key cannot be removed.
     pub(crate) fn remove(&self, key: &Key) -> Result<(), databases::error::Error> {
         self.database.remove_key_from_keys(key)?;
         Ok(())
     }
 
-    /// It loads all keys from the database.
+    /// Loads all authentication keys from the database.
     ///
     /// # Errors
     ///
-    /// Will return a `database::Error` if unable to load the keys from the database.
+    /// Returns a [`databases::error::Error`] if the keys cannot be loaded.
+    ///
+    /// # Returns
+    ///
+    /// A vector containing all persisted [`PeerKey`] entries.
     pub(crate) fn load_keys(&self) -> Result<Vec<PeerKey>, databases::error::Error> {
         let keys = self.database.load_keys()?;
         Ok(keys)

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

@@ -1,3 +1,18 @@
+//! Tracker authentication services and structs.
+//!
+//! One of the crate responsibilities is to create and keep authentication keys.
+//! Auth keys are used by HTTP trackers when the tracker is running in `private`
+//!  mode.
+//!
+//! HTTP tracker's clients need to obtain an authentication key before starting
+//! requesting the tracker. Once they get one they have to include a `PATH`
+//! param with the key in all the HTTP requests. For example, when a peer wants
+//! to `announce` itself it has to use the HTTP tracker endpoint:
+//!
+//! `GET /announce/:key`
+//!
+//! The common way to obtain the keys is by using the tracker API directly or
+//! via other applications like the [Torrust Index](https://github.com/torrust/torrust-index).
 use crate::CurrentClock;
 
 pub mod handler;

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

@@ -1,3 +1,4 @@
+//! Authentication service.
 use std::panic::Location;
 use std::sync::Arc;
 
@@ -6,6 +7,11 @@ use torrust_tracker_configuration::Core;
 use super::key::repository::in_memory::InMemoryKeyRepository;
 use super::{key, Error, Key};
 
+/// The authentication service responsible for validating peer keys.
+///
+/// The service uses an in-memory key repository along with the tracker
+/// configuration to determine whether a given peer key is valid. In a private
+/// tracker, only registered keys (and optionally unexpired keys) are allowed.
 #[derive(Debug)]
 pub struct AuthenticationService {
     /// The tracker configuration.
@@ -16,6 +22,18 @@ pub struct AuthenticationService {
 }
 
 impl AuthenticationService {
+    /// Creates a new instance of the `AuthenticationService`.
+    ///
+    /// # Parameters
+    ///
+    /// - `config`: A reference to the tracker core configuration.
+    /// - `in_memory_key_repository`: A shared reference to an in-memory key
+    ///   repository.
+    ///
+    /// # Returns
+    ///
+    /// An `AuthenticationService` instance initialized with the given
+    /// configuration and repository.
     #[must_use]
     pub fn new(config: &Core, in_memory_key_repository: &Arc<InMemoryKeyRepository>) -> Self {
         Self {
@@ -24,12 +42,23 @@ impl AuthenticationService {
         }
     }
 
-    /// It authenticates the peer `key` against the `Tracker` authentication
-    /// key list.
+    /// Authenticates a peer key against the tracker's authentication key list.
+    ///
+    /// For private trackers, the key must be registered (and optionally not
+    /// expired) to be considered valid. For public trackers, authentication
+    /// always succeeds.
+    ///
+    /// # Parameters
+    ///
+    /// - `key`: A reference to the peer key that needs to be authenticated.
     ///
     /// # Errors
     ///
-    /// Will return an error if the the authentication key cannot be verified.
+    /// Returns an error if:
+    ///
+    /// - The tracker is in private mode and the key cannot be found in the
+    ///   repository.
+    /// - The key is found but fails the expiration check (if expiration is enforced).
     pub async fn authenticate(&self, key: &Key) -> Result<(), Error> {
         if self.tracker_is_private() {
             self.verify_auth_key(key).await
@@ -44,11 +73,25 @@ impl AuthenticationService {
         self.config.private
     }
 
-    /// It verifies an authentication key.
+    /// Verifies the authentication key against the in-memory repository.
+    ///
+    /// This function retrieves the key from the repository. If the key is not
+    /// found, it returns an error with the caller's location. If the key is
+    /// found, the function then checks the key's expiration based on the
+    /// tracker configuration. The behavior differs depending on whether a
+    /// `private` configuration is provided and whether key expiration checking
+    /// is enabled.
+    ///
+    /// # Parameters
+    ///
+    /// - `key`: A reference to the peer key that needs to be verified.
     ///
     /// # Errors
     ///
-    /// Will return a `key::Error` if unable to get any `auth_key`.
+    /// Returns an error if:
+    ///
+    /// - The key is not found in the repository.
+    /// - The key fails the expiration check when such verification is required.
     async fn verify_auth_key(&self, key: &Key) -> Result<(), Error> {
         match self.in_memory_key_repository.get(key).await {
             None => Err(Error::UnableToReadKey {

packages/tracker-core/src/databases/driver/sqlite.rs

@@ -1,4 +1,10 @@
 //! The `SQLite3` database driver.
+//!
+//! This module provides an implementation of the [`Database`] trait for
+//! `SQLite3` using the `r2d2_sqlite` connection pool. It defines the schema for
+//!  whitelist, torrent metrics, and authentication keys, and provides methods
+//! to create and drop tables as well as perform CRUD operations on these
+//! persistent objects.
 use std::panic::Location;
 use std::str::FromStr;
 
@@ -14,18 +20,29 @@ use crate::authentication::{self, Key};
 
 const DRIVER: Driver = Driver::Sqlite3;
 
+/// SQLite driver implementation.
+///
+/// This struct encapsulates a connection pool for SQLite using the `r2d2_sqlite`
+/// connection manager.
 pub(crate) struct Sqlite {
     pool: Pool<SqliteConnectionManager>,
 }
 
 impl Sqlite {
-    /// It instantiates a new `SQLite3` database driver.
+    /// Instantiates a new `SQLite3` database driver.
     ///
-    /// Refer to [`databases::Database::new`](crate::core::databases::Database::new).
+    /// This function creates a connection manager for the SQLite database
+    /// located at `db_path` and then builds a connection pool using `r2d2`. If
+    /// the pool cannot be created, an error is returned (wrapped with the
+    /// appropriate driver information).
+    ///
+    /// # Arguments
+    ///
+    /// * `db_path` - A string slice representing the file path to the SQLite database.
     ///
     /// # Errors
     ///
-    /// Will return `r2d2::Error` if `db_path` is not able to create `SqLite` database.
+    /// Returns an [`Error`] if the connection pool cannot be built.
     pub fn new(db_path: &str) -> Result<Self, Error> {
         let manager = SqliteConnectionManager::file(db_path);
         let pool = r2d2::Pool::builder().build(manager).map_err(|e| (e, DRIVER))?;

packages/tracker-core/src/databases/error.rs

@@ -1,6 +1,13 @@
 //! Database errors.
 //!
-//! This module contains the [Database errors](crate::databases::error::Error).
+//! This module defines the [`Error`] enum used to represent errors that occur
+//! during database operations. These errors encapsulate issues such as missing
+//! query results, malformed queries, connection failures, and connection pool
+//! creation errors. Each error variant includes contextual information such as
+//! the associated database driver and, when applicable, the source error.
+//!
+//! External errors from database libraries (e.g., `rusqlite`, `mysql`) are
+//! converted into this error type using the provided `From` implementations.
 use std::panic::Location;
 use std::sync::Arc;
 
@@ -9,45 +16,62 @@ use torrust_tracker_located_error::{DynError, Located, LocatedError};
 
 use super::driver::Driver;
 
+/// Database error type that encapsulates various failures encountered during
+/// database operations.
 #[derive(thiserror::Error, Debug, Clone)]
 pub enum Error {
-    /// The query unexpectedly returned nothing.
+    /// Indicates that a query unexpectedly returned no rows.
+    ///
+    /// This error variant is used when a query that is expected to return a
+    /// result does not.
     #[error("The {driver} query unexpectedly returned nothing: {source}")]
     QueryReturnedNoRows {
         source: LocatedError<'static, dyn std::error::Error + Send + Sync>,
         driver: Driver,
     },
 
-    /// The query was malformed.
+    /// Indicates that the query was malformed.
+    ///
+    /// This error variant is used when the SQL query itself is invalid or
+    /// improperly formatted.
     #[error("The {driver} query was malformed: {source}")]
     InvalidQuery {
         source: LocatedError<'static, dyn std::error::Error + Send + Sync>,
         driver: Driver,
     },
 
-    /// Unable to insert a record into the database
+    /// Indicates a failure to insert a record into the database.
+    ///
+    /// This error is raised when an insertion operation fails.
     #[error("Unable to insert record into {driver} database, {location}")]
     InsertFailed {
         location: &'static Location<'static>,
         driver: Driver,
     },
 
-    /// Unable to delete a record into the database
+    /// Indicates a failure to delete a record from the database.
+    ///
+    /// This error includes an error code that may be returned by the database
+    /// driver.
     #[error("Failed to remove record from {driver} database, error-code: {error_code}, {location}")]
     DeleteFailed {
         location: &'static Location<'static>,
         error_code: usize,
         driver: Driver,
     },
 
-    /// Unable to connect to the database
+    /// Indicates a failure to connect to the database.
+    ///
+    /// This error variant wraps connection-related errors, such as those caused by an invalid URL.
     #[error("Failed to connect to {driver} database: {source}")]
     ConnectionError {
         source: LocatedError<'static, UrlError>,
         driver: Driver,
     },
 
-    /// Unable to create a connection pool
+    /// Indicates a failure to create a connection pool.
+    ///
+    /// This error variant is used when the connection pool creation (using r2d2) fails.
     #[error("Failed to create r2d2 {driver} connection pool: {source}")]
     ConnectionPool {
         source: LocatedError<'static, r2d2::Error>,

packages/tracker-core/src/databases/mod.rs

@@ -1,48 +1,51 @@
 //! The persistence module.
 //!
-//! Persistence is currently implemented with one [`Database`] trait.
+//! Persistence is currently implemented using a single [`Database`] trait.
 //!
 //! There are two implementations of the trait (two drivers):
 //!
-//! - `Mysql`
-//! - `Sqlite`
+//! - **`MySQL`**
+//! - **`Sqlite`**
 //!
-//! > **NOTICE**: There are no database migrations. If there are any changes,
-//! > we will implemented them or provide a script to migrate to the new schema.
+//! > **NOTICE**: There are no database migrations at this time. If schema
+//! > changes occur, either migration functionality will be implemented or a
+//! > script will be provided to migrate to the new schema.
 //!
-//! The persistent objects are:
+//! The persistent objects handled by this module include:
 //!
-//! - [Torrent metrics](#torrent-metrics)
-//! - [Torrent whitelist](torrent-whitelist)
-//! - [Authentication keys](authentication-keys)
+//! - **Torrent metrics**: Metrics such as the number of completed downloads for
+//!   each torrent.
+//! - **Torrent whitelist**: A list of torrents (by infohash) that are allowed.
+//! - **Authentication keys**: Expiring authentication keys used to secure
+//!   access to private trackers.
 //!
-//! # Torrent metrics
+//! # Torrent Metrics
 //!
-//!  Field         | Sample data                              | Description
-//! ---|---|---
-//!  `id`          | 1                                        | Autoincrement id
-//!  `info_hash`   | `c1277613db1d28709b034a017ab2cae4be07ae10` | `BitTorrent` infohash V1
-//!  `completed`   | 20                                       | The number of peers that have ever completed downloading the torrent associated to this entry. See [`Entry`](torrust_tracker_torrent_repository::entry::Entry) for more information.
+//! | Field       | Sample data                                | Description                                                                 |
+//! |-------------|--------------------------------------------|-----------------------------------------------------------------------------|
+//! | `id`        | 1                                          | Auto-increment id                                                           |
+//! | `info_hash` | `c1277613db1d28709b034a017ab2cae4be07ae10` | `BitTorrent` infohash V1                                                    |
+//! | `completed` | 20                                         | The number of peers that have completed downloading the associated torrent. |
 //!
-//! > **NOTICE**: The peer list for a torrent is not persisted. Since peer have to re-announce themselves on intervals, the data is be
-//! > regenerated again after some minutes.
+//! > **NOTICE**: The peer list for a torrent is not persisted. Because peers re-announce at
+//! > intervals, the peer list is regenerated periodically.
 //!
-//! # Torrent whitelist
+//! # Torrent Whitelist
 //!
-//! Field         | Sample data                              | Description
-//! ---|---|---
-//! `id`          | 1                                        | Autoincrement id
-//! `info_hash`   | `c1277613db1d28709b034a017ab2cae4be07ae10` | `BitTorrent` infohash V1
+//! | Field       | Sample data                                | Description                    |
+//! |-------------|--------------------------------------------|--------------------------------|
+//! | `id`        | 1                                          | Auto-increment id              |
+//! | `info_hash` | `c1277613db1d28709b034a017ab2cae4be07ae10` | `BitTorrent` infohash V1       |
 //!
-//! # Authentication keys
+//! # Authentication Keys
 //!
-//! Field         | Sample data                      | Description                  
-//! ---|---|---
-//! `id`          | 1                                | Autoincrement id             
-//! `key`         | `IrweYtVuQPGbG9Jzx1DihcPmJGGpVy82` | Token                        
-//! `valid_until` | 1672419840                       | Timestamp for the expiring date  
+//! | Field         | Sample data                        | Description                          |
+//! |---------------|------------------------------------|--------------------------------------|
+//! | `id`          | 1                                  | Auto-increment id                    |
+//! | `key`         | `IrweYtVuQPGbG9Jzx1DihcPmJGGpVy82` | Authentication token (32 chars)      |
+//! | `valid_until` | 1672419840                         | Timestamp indicating expiration time |
 //!
-//! > **NOTICE**: All keys must have an expiration date.
+//! > **NOTICE**: All authentication keys must have an expiration date.
 pub mod driver;
 pub mod error;
 pub mod setup;
@@ -54,143 +57,159 @@ use torrust_tracker_primitives::PersistentTorrents;
 use self::error::Error;
 use crate::authentication::{self, Key};
 
-/// The persistence trait. It contains all the methods to interact with the database.
+/// The persistence trait.
+///
+/// This trait defines all the methods required to interact with the database,
+/// including creating and dropping schema tables, and CRUD operations for
+/// torrent metrics, whitelists, and authentication keys. Implementations of
+/// this trait must ensure that operations are safe, consistent, and report
+/// errors using the [`Error`] type.
 #[automock]
 pub trait Database: Sync + Send {
-    /// It generates the database tables. SQL queries are hardcoded in the trait
-    /// implementation.
+    /// Creates the necessary database tables.
+    ///
+    /// The SQL queries for table creation are hardcoded in the trait implementation.
     ///
     /// # Context: Schema
     ///
     /// # Errors
     ///
-    /// Will return `Error` if unable to create own tables.
+    /// Returns an [`Error`] if the tables cannot be created.
     fn create_database_tables(&self) -> Result<(), Error>;
 
-    /// It drops the database tables.
+    /// Drops the database tables.
+    ///
+    /// This operation removes the persistent schema.
     ///
     /// # Context: Schema
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to drop tables.
+    /// Returns an [`Error`] if the tables cannot be dropped.
     fn drop_database_tables(&self) -> Result<(), Error>;
 
     // Torrent Metrics
 
-    /// It loads the torrent metrics data from the database.
+    /// Loads torrent metrics data from the database.
     ///
-    /// It returns an array of tuples with the torrent
-    /// [`InfoHash`] and the
-    /// [`downloaded`](torrust_tracker_torrent_repository::entry::Torrent::downloaded) counter
-    /// which is the number of times the torrent has been downloaded.
-    /// See [`Entry::downloaded`](torrust_tracker_torrent_repository::entry::Torrent::downloaded).
+    /// This function returns the persistent torrent metrics as a collection of
+    /// tuples, where each tuple contains an [`InfoHash`] and the `downloaded`
+    /// counter (i.e. the number of times the torrent has been downloaded).
     ///
     /// # Context: Torrent Metrics
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to load.
+    /// Returns an [`Error`] if the metrics cannot be loaded.
     fn load_persistent_torrents(&self) -> Result<PersistentTorrents, Error>;
 
-    /// It saves the torrent metrics data into the database.
+    /// Saves torrent metrics data into the database.
+    ///
+    /// # Arguments
+    ///
+    /// * `info_hash` - A reference to the torrent's info hash.
+    /// * `downloaded` - The number of times the torrent has been downloaded.
     ///
     /// # Context: Torrent Metrics
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to save.
+    /// Returns an [`Error`] if the metrics cannot be saved.
     fn save_persistent_torrent(&self, info_hash: &InfoHash, downloaded: u32) -> Result<(), Error>;
 
     // Whitelist
 
-    /// It loads the whitelisted torrents from the database.
+    /// Loads the whitelisted torrents from the database.
     ///
     /// # Context: Whitelist
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to load.
+    /// Returns an [`Error`] if the whitelist cannot be loaded.
     fn load_whitelist(&self) -> Result<Vec<InfoHash>, Error>;
 
-    /// It checks if the torrent is whitelisted.
+    /// Retrieves a whitelisted torrent from the database.
     ///
-    /// It returns `Some(InfoHash)` if the torrent is whitelisted, `None` otherwise.
+    /// Returns `Some(InfoHash)` if the torrent is in the whitelist, or `None`
+    /// otherwise.
     ///
     /// # Context: Whitelist
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to load.
+    /// Returns an [`Error`] if the whitelist cannot be queried.
     fn get_info_hash_from_whitelist(&self, info_hash: InfoHash) -> Result<Option<InfoHash>, Error>;
 
-    /// It adds the torrent to the whitelist.
+    /// Adds a torrent to the whitelist.
     ///
     /// # Context: Whitelist
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to save.
+    /// Returns an [`Error`] if the torrent cannot be added to the whitelist.
     fn add_info_hash_to_whitelist(&self, info_hash: InfoHash) -> Result<usize, Error>;
 
-    /// It checks if the torrent is whitelisted.
+    /// Checks whether a torrent is whitelisted.
+    ///
+    /// This default implementation returns `true` if the infohash is included
+    /// in the whitelist, or `false` otherwise.
     ///
     /// # Context: Whitelist
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to load.
+    /// Returns an [`Error`] if the whitelist cannot be queried.
     fn is_info_hash_whitelisted(&self, info_hash: InfoHash) -> Result<bool, Error> {
         Ok(self.get_info_hash_from_whitelist(info_hash)?.is_some())
     }
 
-    /// It removes the torrent from the whitelist.
+    /// Removes a torrent from the whitelist.
     ///
     /// # Context: Whitelist
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to save.
+    /// Returns an [`Error`] if the torrent cannot be removed from the whitelist.
     fn remove_info_hash_from_whitelist(&self, info_hash: InfoHash) -> Result<usize, Error>;
 
     // Authentication keys
 
-    /// It loads the expiring authentication keys from the database.
+    /// Loads all authentication keys from the database.
     ///
     /// # Context: Authentication Keys
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to load.
+    /// Returns an [`Error`] if the keys cannot be loaded.
     fn load_keys(&self) -> Result<Vec<authentication::PeerKey>, Error>;
 
-    /// It gets an expiring authentication key from the database.
+    /// Retrieves a specific authentication key from the database.
     ///
-    /// It returns `Some(PeerKey)` if a [`PeerKey`](crate::authentication::PeerKey)
-    /// with the input [`Key`] exists, `None` otherwise.
+    /// Returns `Some(PeerKey)` if a key corresponding to the provided [`Key`]
+    /// exists, or `None` otherwise.
     ///
     /// # Context: Authentication Keys
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to load.
+    /// Returns an [`Error`] if the key cannot be queried.
     fn get_key_from_keys(&self, key: &Key) -> Result<Option<authentication::PeerKey>, Error>;
 
-    /// It adds an expiring authentication key to the database.
+    /// Adds an authentication key to the database.
     ///
     /// # Context: Authentication Keys
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to save.
+    /// Returns an [`Error`] if the key cannot be saved.
     fn add_key_to_keys(&self, auth_key: &authentication::PeerKey) -> Result<usize, Error>;
 
-    /// It removes an expiring authentication key from the database.
+    /// Removes an authentication key from the database.
     ///
     /// # Context: Authentication Keys
     ///
     /// # Errors
     ///
-    /// Will return `Err` if unable to load.
+    /// Returns an [`Error`] if the key cannot be removed.
     fn remove_key_from_keys(&self, key: &Key) -> Result<usize, Error>;
 }

packages/tracker-core/src/databases/setup.rs

@@ -1,13 +1,43 @@
+//! This module provides functionality for setting up databases.
 use std::sync::Arc;
 
 use torrust_tracker_configuration::Core;
 
 use super::driver::{self, Driver};
 use super::Database;
 
+/// Initializes and returns a database instance based on the provided configuration.
+///
+/// This function creates a new database instance according to the settings
+/// defined in the [`Core`] configuration. It selects the appropriate driver
+/// (either `Sqlite3` or `MySQL`) as specified in `config.database.driver` and
+/// attempts to build the database connection using the path defined in
+/// `config.database.path`.
+///
+/// The resulting database instance is wrapped in a shared pointer (`Arc`) to a
+/// boxed trait object, allowing safe sharing of the database connection across
+/// multiple threads.
+///
 /// # Panics
 ///
-/// Will panic if database cannot be initialized.
+/// This function will panic if the database cannot be initialized (i.e., if the
+///  driver fails to build the connection). This is enforced by the use of
+/// [`expect`](std::result::Result::expect) in the implementation.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// use torrust_tracker_configuration::Core;
+/// use bittorrent_tracker_core::databases::setup::initialize_database;
+///
+/// // Create a default configuration (ensure it is properly set up for your environment)
+/// let config = Core::default();
+///
+/// // Initialize the database; this will panic if initialization fails.
+/// let database = initialize_database(&config);
+///
+/// // The returned database instance can now be used for persistence operations.
+/// ```
 #[must_use]
 pub fn initialize_database(config: &Core) -> Arc<Box<dyn Database>> {
     let driver = match config.database.driver {
@@ -17,3 +47,15 @@ pub fn initialize_database(config: &Core) -> Arc<Box<dyn Database>> {
 
     Arc::new(driver::build(&driver, &config.database.path).expect("Database driver build failed."))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::initialize_database;
+    use crate::test_helpers::tests::ephemeral_configuration;
+
+    #[test]
+    fn it_should_initialize_the_sqlite_database() {
+        let config = ephemeral_configuration();
+        let _database = initialize_database(&config);
+    }
+}

packages/tracker-core/src/error.rs

@@ -1,4 +1,12 @@
-//! Errors returned by the core tracker.
+//! Core tracker errors.
+//!
+//! This module defines the error types used internally by the `BitTorrent`
+//! tracker core.
+//!
+//! These errors encapsulate issues such as whitelisting violations, invalid
+//! peer key data, and database persistence failures. Each error variant
+//! includes contextual information (such as source code location) to facilitate
+//!  debugging.
 use std::panic::Location;
 
 use bittorrent_primitives::info_hash::InfoHash;
@@ -7,29 +15,41 @@ use torrust_tracker_located_error::LocatedError;
 use super::authentication::key::ParseKeyError;
 use super::databases;
 
-/// Whitelist errors returned by the core tracker.
+/// Errors related to torrent whitelisting.
+///
+/// This error is returned when an operation involves a torrent that is not
+/// present in the whitelist.
 #[derive(thiserror::Error, Debug, Clone)]
 pub enum WhitelistError {
+    /// Indicates that the torrent identified by `info_hash` is not whitelisted.
     #[error("The torrent: {info_hash}, is not whitelisted, {location}")]
     TorrentNotWhitelisted {
         info_hash: InfoHash,
         location: &'static Location<'static>,
     },
 }
 
-/// Peers keys errors returned by the core tracker.
+/// Errors related to peer key operations.
+///
+/// This error type covers issues encountered during the handling of peer keys,
+/// including validation of key durations, parsing errors, and database
+/// persistence problems.
 #[allow(clippy::module_name_repetitions)]
 #[derive(thiserror::Error, Debug, Clone)]
 pub enum PeerKeyError {
+    /// Returned when the duration specified for the peer key exceeds the
+    /// maximum.
     #[error("Invalid peer key duration: {seconds_valid:?}, is not valid")]
     DurationOverflow { seconds_valid: u64 },
 
+    /// Returned when the provided peer key is invalid.
     #[error("Invalid key: {key}")]
     InvalidKey {
         key: String,
         source: LocatedError<'static, ParseKeyError>,
     },
 
+    /// Returned when persisting the peer key to the database fails.
     #[error("Can't persist key: {source}")]
     DatabaseError {
         source: LocatedError<'static, databases::error::Error>,

packages/tracker-core/src/lib.rs

@@ -1,3 +1,195 @@
+//! Scrape handler.
+//!
+//! The `scrape` request allows clients to query metadata about the swarm in bulk.
+//!
+//! An `scrape` request includes a list of infohashes whose swarm metadata you want to collect.
+//!
+//! The returned struct is:
+//!
+//! ```rust,no_run
+//! use bittorrent_primitives::info_hash::InfoHash;
+//! use std::collections::HashMap;
+//!
+//! pub struct ScrapeData {
+//!     pub files: HashMap<InfoHash, SwarmMetadata>,
+//! }
+//!
+//! pub struct SwarmMetadata {
+//!     pub complete: u32,   // The number of active peers that have completed downloading (seeders)
+//!     pub downloaded: u32, // The number of peers that have ever completed downloading
+//!     pub incomplete: u32, // The number of active peers that have not completed downloading (leechers)
+//! }
+//! ```
+//!
+//! The JSON representation of a sample `scrape` response would be like the following:
+//!
+//! ```json
+//! {
+//!     'files': {
+//!       'xxxxxxxxxxxxxxxxxxxx': {'complete': 11, 'downloaded': 13772, 'incomplete': 19},
+//!       'yyyyyyyyyyyyyyyyyyyy': {'complete': 21, 'downloaded': 206, 'incomplete': 20}
+//!     }
+//! }
+//! ```
+//!  
+//! `xxxxxxxxxxxxxxxxxxxx` and `yyyyyyyyyyyyyyyyyyyy` are 20-byte infohash arrays.
+//! There are two data structures for infohashes: byte arrays and hex strings:
+//!
+//! ```rust,no_run
+//! use bittorrent_primitives::info_hash::InfoHash;
+//! use std::str::FromStr;
+//!
+//! let info_hash: InfoHash = [255u8; 20].into();
+//!
+//! assert_eq!(
+//!     info_hash,
+//!     InfoHash::from_str("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF").unwrap()
+//! );
+//! ```
+//! Refer to `BitTorrent` BEPs and other sites for more information about the `scrape` request:
+//!
+//! - [BEP 48. Tracker Protocol Extension: Scrape](https://www.bittorrent.org/beps/bep_0048.html)
+//! - [BEP 15. UDP Tracker Protocol for `BitTorrent`. Scrape section](https://www.bittorrent.org/beps/bep_0015.html)
+//! - [Vuze docs](https://wiki.vuze.com/w/Scrape)
+//!
+//! ## Torrents
+//!
+//! The [`torrent`](crate::torrent) module contains all the data structures stored by the `Tracker` except for peers.
+//!
+//! We can represent the data stored in memory internally by the `Tracker` with this JSON object:
+//!
+//! ```json
+//! {
+//!     "c1277613db1d28709b034a017ab2cae4be07ae10": {
+//!         "completed": 0,
+//!         "peers": {
+//!             "-qB00000000000000001": {
+//!                 "peer_id": "-qB00000000000000001",
+//!                 "peer_addr": "2.137.87.41:1754",
+//!                 "updated": 1672419840,
+//!                 "uploaded": 120,
+//!                 "downloaded": 60,
+//!                 "left": 60,
+//!                 "event": "started"
+//!             },
+//!             "-qB00000000000000002": {
+//!                 "peer_id": "-qB00000000000000002",
+//!                 "peer_addr": "23.17.287.141:2345",
+//!                 "updated": 1679415984,
+//!                 "uploaded": 80,
+//!                 "downloaded": 20,
+//!                 "left": 40,
+//!                 "event": "started"
+//!             }
+//!         }
+//!     }
+//! }
+//! ```
+//!
+//! The `Tracker` maintains an indexed-by-info-hash list of torrents. For each torrent, it stores a torrent `Entry`.
+//! The torrent entry has two attributes:
+//!
+//! - `completed`: which is hte number of peers that have completed downloading the torrent file/s. As they have completed downloading,
+//!   they have a full version of the torrent data, and they can provide the full data to other peers. That's why they are also known as "seeders".
+//! - `peers`: an indexed and orderer list of peer for the torrent. Each peer contains the data received from the peer in the `announce` request.
+//!
+//! The [`crate::torrent`] module not only contains the original data obtained from peer via `announce` requests, it also contains
+//! aggregate data that can be derived from the original data. For example:
+//!
+//! ```rust,no_run
+//! pub struct SwarmMetadata {
+//!     pub complete: u32,   // The number of active peers that have completed downloading (seeders)
+//!     pub downloaded: u32, // The number of peers that have ever completed downloading
+//!     pub incomplete: u32, // The number of active peers that have not completed downloading (leechers)
+//! }
+//!
+//! ```
+//!
+//! > **NOTICE**: that `complete` or `completed` peers are the peers that have completed downloading, but only the active ones are considered "seeders".
+//!
+//! `SwarmMetadata` struct follows name conventions for `scrape` responses. See [BEP 48](https://www.bittorrent.org/beps/bep_0048.html), while `SwarmMetadata`
+//! is used for the rest of cases.
+//!
+//! Refer to [`crate::torrent`] module for more details about these data structures.
+//!
+//! ## Peers
+//!
+//! A `Peer` is the struct used by the `Tracker` to keep peers data:
+//!
+//! ```rust,no_run
+//! use std::net::SocketAddr;
+//! use aquatic_udp_protocol::PeerId;
+//! use torrust_tracker_primitives::DurationSinceUnixEpoch;
+//! use aquatic_udp_protocol::NumberOfBytes;
+//! use aquatic_udp_protocol::AnnounceEvent;
+//!
+//! pub struct Peer {
+//!     pub peer_id: PeerId,                     // The peer ID
+//!     pub peer_addr: SocketAddr,           // Peer socket address
+//!     pub updated: DurationSinceUnixEpoch, // Last time (timestamp) when the peer was updated
+//!     pub uploaded: NumberOfBytes,         // Number of bytes the peer has uploaded so far
+//!     pub downloaded: NumberOfBytes,       // Number of bytes the peer has downloaded so far   
+//!     pub left: NumberOfBytes,             // The number of bytes this peer still has to download
+//!     pub event: AnnounceEvent,            // The event the peer has announced: `started`, `completed`, `stopped`
+//! }
+//! ```
+//!
+//! Notice that most of the attributes are obtained from the `announce` request.
+//! For example, an HTTP announce request would contain the following `GET` parameters:
+//!
+//! <http://0.0.0.0:7070/announce?info_hash=%81%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00&peer_addr=2.137.87.41&downloaded=0&uploaded=0&peer_id=-qB00000000000000001&port=17548&left=0&event=completed&compact=0>
+//!
+//! The `Tracker` keeps an in-memory ordered data structure with all the torrents and a list of peers for each torrent, together with some swarm metrics.
+//!
+//! We can represent the data stored in memory with this JSON object:
+//!
+//! ```json
+//! {
+//!     "c1277613db1d28709b034a017ab2cae4be07ae10": {
+//!         "completed": 0,
+//!         "peers": {
+//!             "-qB00000000000000001": {
+//!                 "peer_id": "-qB00000000000000001",
+//!                 "peer_addr": "2.137.87.41:1754",
+//!                 "updated": 1672419840,
+//!                 "uploaded": 120,
+//!                 "downloaded": 60,
+//!                 "left": 60,
+//!                 "event": "started"
+//!             },
+//!             "-qB00000000000000002": {
+//!                 "peer_id": "-qB00000000000000002",
+//!                 "peer_addr": "23.17.287.141:2345",
+//!                 "updated": 1679415984,
+//!                 "uploaded": 80,
+//!                 "downloaded": 20,
+//!                 "left": 40,
+//!                 "event": "started"
+//!             }
+//!         }
+//!     }
+//! }
+//! ```
+//!
+//! That JSON object does not exist, it's only a representation of the `Tracker` torrents data.
+//!
+//! `c1277613db1d28709b034a017ab2cae4be07ae10` is the torrent infohash and `completed` contains the number of peers
+//! that have a full version of the torrent data, also known as seeders.
+//!
+//! Refer to [`peer`](torrust_tracker_primitives::peer) for more information about peers.
+//!
+//! # Persistence
+//!
+//! Right now the `Tracker` is responsible for storing and load data into and
+//! from the database, when persistence is enabled.
+//!
+//! There are three types of persistent object:
+//!
+//! - Authentication keys (only expiring keys)
+//! - Torrent whitelist
+//! - Torrent metrics
+//!
+//! Refer to [`crate::databases`] module for more information about persistence.
 use std::sync::Arc;
 
 use bittorrent_primitives::info_hash::InfoHash;

packages/tracker-core/src/scrape_handler.rs

@@ -1,3 +1,4 @@
+//! This module contains the logic to manage the whitelist.
 pub mod authorization;
 pub mod manager;
 pub mod repository;