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

Author: josecelano

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

@@ -1,3 +1,16 @@
+//! 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/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>,