dev: cleanup http responses: announce

Author: da2ce7

src/core/databases/mod.rs

@@ -134,7 +134,7 @@ pub trait Database: Sync + Send {
     /// # Errors
     ///
     /// Will return `Err` if unable to save.
-    async fn save_persistent_torrent(&self, info_hash: &InfoHash, completed: u32) -> Result<(), Error>;
+    async fn save_persistent_torrent(&self, info_hash: &InfoHash, downloaded: u32) -> Result<(), Error>;
 
     // Whitelist
 

src/core/mod.rs

@@ -98,12 +98,12 @@
 //!
 //! ```rust,no_run
 //! use torrust_tracker::core::peer::Peer;
+//! use torrust_tracker::core::AnnouncePolicy;
 //!
 //! pub struct AnnounceData {
 //!     pub peers: Vec<Peer>,
 //!     pub swarm_stats: SwarmStats,
-//!     pub interval: u32, // Option `announce_interval` from core tracker configuration
-//!     pub interval_min: u32, // Option `min_announce_interval` from core tracker configuration
+//!     pub policy: AnnouncePolicy, // the tracker announce policy.
 //! }
 //!
 //! pub struct SwarmStats {
@@ -445,6 +445,7 @@ use std::panic::Location;
 use std::sync::Arc;
 use std::time::Duration;
 
+use derive_more::Constructor;
 use futures::future::join_all;
 use tokio::sync::mpsc::error::SendError;
 use torrust_tracker_configuration::Configuration;
@@ -487,7 +488,7 @@ pub struct Tracker {
 /// Structure that holds general `Tracker` torrents metrics.
 ///
 /// Metrics are aggregate values for all torrents.
-#[derive(Debug, PartialEq, Default)]
+#[derive(Copy, Clone, Debug, PartialEq, Default)]
 pub struct TorrentsMetrics {
     /// Total number of seeders for all torrents
     pub seeders: u64,
@@ -499,21 +500,45 @@ pub struct TorrentsMetrics {
     pub torrents: u64,
 }
 
+/// Announce policy
+#[derive(Copy, Clone, Debug, PartialEq, Constructor)]
+pub struct AnnouncePolicy {
+    /// Interval in seconds that the client should wait between sending regular
+    /// announce requests to the tracker.
+    ///
+    /// It's a **recommended** wait time between announcements.
+    ///
+    /// This is the standard amount of time that clients should wait between
+    /// sending consecutive announcements to the tracker. This value is set by
+    /// the tracker and is typically provided in the tracker's response to a
+    /// client's initial request. It serves as a guideline for clients to know
+    /// how often they should contact the tracker for updates on the peer list,
+    /// while ensuring that the tracker is not overwhelmed with requests.
+    pub interval: u32,
+
+    /// Minimum announce interval. Clients must not reannounce more frequently
+    /// than this.
+    ///
+    /// It establishes the shortest allowed wait time.
+    ///
+    /// This is an optional parameter in the protocol that the tracker may
+    /// provide in its response. It sets a lower limit on the frequency at which
+    /// clients are allowed to send announcements. Clients should respect this
+    /// value to prevent sending too many requests in a short period, which
+    /// could lead to excessive load on the tracker or even getting banned by
+    /// the tracker for not adhering to the rules.
+    pub interval_min: u32,
+}
+
 /// Structure that holds the data returned by the `announce` request.
-#[derive(Debug, PartialEq, Default)]
+#[derive(Clone, Debug, PartialEq, Constructor)]
 pub struct AnnounceData {
     /// The list of peers that are downloading the same torrent.
     /// It excludes the peer that made the request.
     pub peers: Vec<Peer>,
     /// Swarm statistics
     pub swarm_stats: SwarmStats,
-    /// The interval in seconds that the client should wait between sending
-    /// regular requests to the tracker.
-    /// Refer to [`announce_interval`](torrust_tracker_configuration::Configuration::announce_interval).
-    pub interval: u32,
-    /// The minimum announce interval in seconds that the client should wait.
-    /// Refer to [`min_announce_interval`](torrust_tracker_configuration::Configuration::min_announce_interval).
-    pub interval_min: u32,
+    pub policy: AnnouncePolicy,
 }
 
 /// Structure that holds the data returned by the `scrape` request.
@@ -631,8 +656,7 @@ impl Tracker {
         AnnounceData {
             peers,
             swarm_stats,
-            interval: self.config.announce_interval,
-            interval_min: self.config.min_announce_interval,
+            policy: AnnouncePolicy::new(self.config.announce_interval, self.config.min_announce_interval),
         }
     }
 
@@ -732,7 +756,7 @@ impl Tracker {
         let (stats, stats_updated) = self.torrents.update_torrent_with_peer_and_get_stats(info_hash, peer).await;
 
         if self.config.persistent_torrent_completed_stat && stats_updated {
-            let completed = stats.downloaded;
+            let completed = stats.downloaded; // i.e `completed`
             let info_hash = *info_hash;
 
             drop(self.database.save_persistent_torrent(&info_hash, completed).await);

src/core/torrent/mod.rs

@@ -33,6 +33,7 @@ pub mod repository;
 use std::time::Duration;
 
 use aquatic_udp_protocol::AnnounceEvent;
+use derive_more::Constructor;
 use serde::{Deserialize, Serialize};
 
 use super::peer::{self, Peer};
@@ -56,13 +57,13 @@ pub struct Entry {
 /// Swarm metadata dictionary in the scrape response.
 ///
 /// See [BEP 48: Tracker Protocol Extension: Scrape](https://www.bittorrent.org/beps/bep_0048.html)
-#[derive(Debug, PartialEq, Default)]
+#[derive(Copy, Clone, Debug, PartialEq, Default, Constructor)]
 pub struct SwarmMetadata {
-    /// The number of peers that have ever completed downloading
-    pub downloaded: u32,
-    /// The number of active peers that have completed downloading (seeders)
-    pub complete: u32,
-    /// The number of active peers that have not completed downloading (leechers)
+    /// (i.e `completed`): The number of peers that have ever completed downloading
+    pub downloaded: u32, //
+    /// (i.e `seeders`): The number of active peers that have completed downloading (seeders)
+    pub complete: u32, //seeders
+    /// (i.e `leechers`): The number of active peers that have not completed downloading (leechers)
     pub incomplete: u32,
 }
 
@@ -73,7 +74,7 @@ impl SwarmMetadata {
     }
 }
 
-/// [`SwarmStats`] is has the same type as [`SwarmMetadata`]
+/// We use the same format for [`SwarmStats`] as [`SwarmMetadata`]
 pub type SwarmStats = SwarmMetadata;
 
 impl Entry {

src/servers/http/mod.rs

@@ -152,7 +152,7 @@
 //! 000000f0: 65                                       e
 //! ```
 //!
-//! Refer to the [`NonCompact`](crate::servers::http::v1::responses::announce::NonCompact)
+//! Refer to the [`Normal`](crate::servers::http::v1::responses::announce::Normal), i.e. `Non-Compact`
 //! response for more information about the response.
 //!
 //! **Sample compact response**

src/servers/http/v1/requests/announce.rs

@@ -180,7 +180,7 @@ impl fmt::Display for Event {
 /// Depending on the value of this param, the tracker will return a different
 /// response:
 ///
-/// - [`NonCompact`](crate::servers::http::v1::responses::announce::NonCompact) response.
+/// - [`Normal`](crate::servers::http::v1::responses::announce::Normal), i.e. a `non-compact` response.
 /// - [`Compact`](crate::servers::http::v1::responses::announce::Compact) response.
 ///
 /// Refer to [BEP 23. Tracker Returns Compact Peer Lists](https://www.bittorrent.org/beps/bep_0023.html)