feat: [torrust#1539] add method to Database trait to persis global downloads counter

It does not use the new methods in production yet.

Author: josecelano

packages/tracker-core/migrations/mysql/20240730183000_torrust_tracker_create_all_tables.sql

@@ -4,6 +4,7 @@ CREATE TABLE
         info_hash VARCHAR(40) NOT NULL UNIQUE
     );
 
+# todo: rename to `torrent_metrics`
 CREATE TABLE
     IF NOT EXISTS torrents (
         id integer PRIMARY KEY AUTO_INCREMENT,

packages/tracker-core/migrations/mysql/20250527093000_torrust_tracker_new_torrent_aggregate_metrics_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE
+    IF NOT EXISTS torrent_aggregate_metrics (
+        id integer PRIMARY KEY AUTO_INCREMENT,
+        metric_name VARCHAR(50) NOT NULL UNIQUE,
+        value INTEGER DEFAULT 0 NOT NULL
+    );

packages/tracker-core/migrations/sqlite/20240730183000_torrust_tracker_create_all_tables.sql

@@ -4,6 +4,7 @@ CREATE TABLE
         info_hash TEXT NOT NULL UNIQUE
     );
 
+# todo: rename to `torrent_metrics`
 CREATE TABLE
     IF NOT EXISTS torrents (
         id INTEGER PRIMARY KEY AUTOINCREMENT,

packages/tracker-core/migrations/sqlite/20250527093000_torrust_tracker_new_torrent_aggregate_metrics_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE
+    IF NOT EXISTS torrent_aggregate_metrics (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        metric_name TEXT NOT NULL UNIQUE,
+        value INTEGER DEFAULT 0 NOT NULL
+    );

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

@@ -6,6 +6,9 @@ use sqlite::Sqlite;
 use super::error::Error;
 use super::Database;
 
+/// Metric name in DB for the total number of downloads across all torrents.
+const TORRENTS_DOWNLOADS_TOTAL: &str = "torrents_downloads_total";
+
 /// The database management system used by the tracker.
 ///
 /// Refer to:
@@ -97,9 +100,14 @@ pub(crate) mod tests {
 
         // Persistent torrents (stats)
 
+        // Torrent metrics
         handling_torrent_persistence::it_should_save_and_load_persistent_torrents(driver);
         handling_torrent_persistence::it_should_load_all_persistent_torrents(driver);
         handling_torrent_persistence::it_should_increase_the_number_of_downloads_for_a_given_torrent(driver);
+        // Aggregate metrics for all torrents
+        handling_torrent_persistence::it_should_save_and_load_the_global_number_of_downloads(driver);
+        handling_torrent_persistence::it_should_load_the_global_number_of_downloads(driver);
+        handling_torrent_persistence::it_should_increase_the_global_number_of_downloads(driver);
 
         // Authentication keys (for private trackers)
 
@@ -154,6 +162,8 @@ pub(crate) mod tests {
         use crate::databases::Database;
         use crate::test_helpers::tests::sample_info_hash;
 
+        // Metrics per torrent
+
         pub fn it_should_save_and_load_persistent_torrents(driver: &Arc<Box<dyn Database>>) {
             let infohash = sample_info_hash();
 
@@ -192,6 +202,40 @@ pub(crate) mod tests {
 
             assert_eq!(number_of_downloads, 2);
         }
+
+        // Aggregate metrics for all torrents
+
+        pub fn it_should_save_and_load_the_global_number_of_downloads(driver: &Arc<Box<dyn Database>>) {
+            let number_of_downloads = 1;
+
+            driver.save_global_number_of_downloads(number_of_downloads).unwrap();
+
+            let number_of_downloads = driver.load_global_number_of_downloads().unwrap().unwrap();
+
+            assert_eq!(number_of_downloads, 1);
+        }
+
+        pub fn it_should_load_the_global_number_of_downloads(driver: &Arc<Box<dyn Database>>) {
+            let number_of_downloads = 1;
+
+            driver.save_global_number_of_downloads(number_of_downloads).unwrap();
+
+            let number_of_downloads = driver.load_global_number_of_downloads().unwrap().unwrap();
+
+            assert_eq!(number_of_downloads, 1);
+        }
+
+        pub fn it_should_increase_the_global_number_of_downloads(driver: &Arc<Box<dyn Database>>) {
+            let number_of_downloads = 1;
+
+            driver.save_global_number_of_downloads(number_of_downloads).unwrap();
+
+            driver.increase_global_number_of_downloads().unwrap();
+
+            let number_of_downloads = driver.load_global_number_of_downloads().unwrap().unwrap();
+
+            assert_eq!(number_of_downloads, 2);
+        }
     }
 
     mod handling_authentication_keys {

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

@@ -15,7 +15,7 @@ use r2d2_mysql::mysql::{params, Opts, OptsBuilder};
 use r2d2_mysql::MySqlConnectionManager;
 use torrust_tracker_primitives::{PersistentTorrent, PersistentTorrents};
 
-use super::{Database, Driver, Error};
+use super::{Database, Driver, Error, TORRENTS_DOWNLOADS_TOTAL};
 use crate::authentication::key::AUTH_KEY_LENGTH;
 use crate::authentication::{self, Key};
 
@@ -46,6 +46,27 @@ impl Mysql {
 
         Ok(Self { pool })
     }
+
+    fn load_torrent_aggregate_metric(&self, metric_name: &str) -> Result<Option<PersistentTorrent>, Error> {
+        let mut conn = self.pool.get().map_err(|e| (e, DRIVER))?;
+
+        let query = conn.exec_first::<u32, _, _>(
+            "SELECT value FROM torrent_aggregate_metrics WHERE metric_name = :metric_name",
+            params! { "metric_name" => metric_name },
+        );
+
+        let persistent_torrent = query?;
+
+        Ok(persistent_torrent)
+    }
+
+    fn save_torrent_aggregate_metric(&self, metric_name: &str, completed: PersistentTorrent) -> Result<(), Error> {
+        const COMMAND : &str = "INSERT INTO torrent_aggregate_metrics (metric_name, value) VALUES (:metric_name, :completed) ON DUPLICATE KEY UPDATE value = VALUES(value)";
+
+        let mut conn = self.pool.get().map_err(|e| (e, DRIVER))?;
+
+        Ok(conn.exec_drop(COMMAND, params! { metric_name, completed })?)
+    }
 }
 
 impl Database for Mysql {
@@ -66,6 +87,14 @@ impl Database for Mysql {
         );"
         .to_string();
 
+        let create_torrent_aggregate_metrics_table = "
+        CREATE TABLE IF NOT EXISTS torrent_aggregate_metrics (
+            id integer PRIMARY KEY AUTO_INCREMENT,
+            metric_name VARCHAR(50) NOT NULL UNIQUE,
+            value INTEGER DEFAULT 0 NOT NULL
+        );"
+        .to_string();
+
         let create_keys_table = format!(
             "
         CREATE TABLE IF NOT EXISTS `keys` (
@@ -82,6 +111,8 @@ impl Database for Mysql {
 
         conn.query_drop(&create_torrents_table)
             .expect("Could not create torrents table.");
+        conn.query_drop(&create_torrent_aggregate_metrics_table)
+            .expect("Could not create create_torrent_aggregate_metrics_table table.");
         conn.query_drop(&create_keys_table).expect("Could not create keys table.");
         conn.query_drop(&create_whitelist_table)
             .expect("Could not create whitelist table.");
@@ -168,6 +199,30 @@ impl Database for Mysql {
         Ok(())
     }
 
+    /// Refer to [`databases::Database::load_global_number_of_downloads`](crate::core::databases::Database::load_global_number_of_downloads).
+    fn load_global_number_of_downloads(&self) -> Result<Option<PersistentTorrent>, Error> {
+        self.load_torrent_aggregate_metric(TORRENTS_DOWNLOADS_TOTAL)
+    }
+
+    /// Refer to [`databases::Database::save_global_number_of_downloads`](crate::core::databases::Database::save_global_number_of_downloads).
+    fn save_global_number_of_downloads(&self, downloaded: PersistentTorrent) -> Result<(), Error> {
+        self.save_torrent_aggregate_metric(TORRENTS_DOWNLOADS_TOTAL, downloaded)
+    }
+
+    /// Refer to [`databases::Database::increase_global_number_of_downloads`](crate::core::databases::Database::increase_global_number_of_downloads).
+    fn increase_global_number_of_downloads(&self) -> Result<(), Error> {
+        let mut conn = self.pool.get().map_err(|e| (e, DRIVER))?;
+
+        let metric_name = TORRENTS_DOWNLOADS_TOTAL;
+
+        conn.exec_drop(
+            "UPDATE torrent_aggregate_metrics SET value = value + 1 WHERE metric_name = :metric_name",
+            params! { metric_name },
+        )?;
+
+        Ok(())
+    }
+
     /// Refer to [`databases::Database::load_keys`](crate::core::databases::Database::load_keys).
     fn load_keys(&self) -> Result<Vec<authentication::PeerKey>, Error> {
         let mut conn = self.pool.get().map_err(|e| (e, DRIVER))?;

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

@@ -15,7 +15,7 @@ use r2d2_sqlite::rusqlite::types::Null;
 use r2d2_sqlite::SqliteConnectionManager;
 use torrust_tracker_primitives::{DurationSinceUnixEpoch, PersistentTorrent, PersistentTorrents};
 
-use super::{Database, Driver, Error};
+use super::{Database, Driver, Error, TORRENTS_DOWNLOADS_TOTAL};
 use crate::authentication::{self, Key};
 
 const DRIVER: Driver = Driver::Sqlite3;
@@ -49,6 +49,39 @@ impl Sqlite {
 
         Ok(Self { pool })
     }
+
+    fn load_torrent_aggregate_metric(&self, metric_name: &str) -> Result<Option<PersistentTorrent>, Error> {
+        let conn = self.pool.get().map_err(|e| (e, DRIVER))?;
+
+        let mut stmt = conn.prepare("SELECT value FROM torrent_aggregate_metrics WHERE metric_name = ?")?;
+
+        let mut rows = stmt.query([metric_name])?;
+
+        let persistent_torrent = rows.next()?;
+
+        Ok(persistent_torrent.map(|f| {
+            let value: i64 = f.get(0).unwrap();
+            u32::try_from(value).unwrap()
+        }))
+    }
+
+    fn save_torrent_aggregate_metric(&self, metric_name: &str, completed: PersistentTorrent) -> Result<(), Error> {
+        let conn = self.pool.get().map_err(|e| (e, DRIVER))?;
+
+        let insert = conn.execute(
+            "INSERT INTO torrent_aggregate_metrics (metric_name, value) VALUES (?1, ?2) ON CONFLICT(metric_name) DO UPDATE SET value = ?2",
+            [metric_name.to_string(), completed.to_string()],
+        )?;
+
+        if insert == 0 {
+            Err(Error::InsertFailed {
+                location: Location::caller(),
+                driver: DRIVER,
+            })
+        } else {
+            Ok(())
+        }
+    }
 }
 
 impl Database for Sqlite {
@@ -69,6 +102,14 @@ impl Database for Sqlite {
         );"
         .to_string();
 
+        let create_torrent_aggregate_metrics_table = "
+        CREATE TABLE IF NOT EXISTS torrent_aggregate_metrics (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            metric_name TEXT NOT NULL UNIQUE,
+            value INTEGER DEFAULT 0 NOT NULL
+        );"
+        .to_string();
+
         let create_keys_table = "
         CREATE TABLE IF NOT EXISTS keys (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -82,6 +123,7 @@ impl Database for Sqlite {
         conn.execute(&create_whitelist_table, [])?;
         conn.execute(&create_keys_table, [])?;
         conn.execute(&create_torrents_table, [])?;
+        conn.execute(&create_torrent_aggregate_metrics_table, [])?;
 
         Ok(())
     }
@@ -172,6 +214,30 @@ impl Database for Sqlite {
         Ok(())
     }
 
+    /// Refer to [`databases::Database::load_global_number_of_downloads`](crate::core::databases::Database::load_global_number_of_downloads).
+    fn load_global_number_of_downloads(&self) -> Result<Option<PersistentTorrent>, Error> {
+        self.load_torrent_aggregate_metric(TORRENTS_DOWNLOADS_TOTAL)
+    }
+
+    /// Refer to [`databases::Database::save_global_number_of_downloads`](crate::core::databases::Database::save_global_number_of_downloads).
+    fn save_global_number_of_downloads(&self, downloaded: PersistentTorrent) -> Result<(), Error> {
+        self.save_torrent_aggregate_metric(TORRENTS_DOWNLOADS_TOTAL, downloaded)
+    }
+
+    /// Refer to [`databases::Database::increase_global_number_of_downloads`](crate::core::databases::Database::increase_global_number_of_downloads).
+    fn increase_global_number_of_downloads(&self) -> Result<(), Error> {
+        let conn = self.pool.get().map_err(|e| (e, DRIVER))?;
+
+        let metric_name = TORRENTS_DOWNLOADS_TOTAL;
+
+        let _ = conn.execute(
+            "UPDATE torrent_aggregate_metrics SET value = value + 1 WHERE metric_name = ?",
+            [metric_name],
+        )?;
+
+        Ok(())
+    }
+
     /// Refer to [`databases::Database::load_keys`](crate::core::databases::Database::load_keys).
     fn load_keys(&self) -> Result<Vec<authentication::PeerKey>, Error> {
         let conn = self.pool.get().map_err(|e| (e, DRIVER))?;

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

@@ -131,16 +131,48 @@ pub trait Database: Sync + Send {
     /// It does not create a new entry if the torrent is not found and it does
     /// not return an error.
     ///
+    /// # Context: Torrent Metrics
+    ///
+    /// # Arguments
+    ///
+    /// * `info_hash` - A reference to the torrent's info hash.
+    ///
+    /// # Errors
+    ///
+    /// Returns an [`Error`] if the query failed.
+    fn increase_number_of_downloads(&self, info_hash: &InfoHash) -> Result<(), Error>;
+
+    /// Loads the total number of downloads for all torrents from the database.
+    ///
+    /// # Context: Torrent Metrics
+    ///
+    /// # Errors
+    ///
+    /// Returns an [`Error`] if the total downloads cannot be loaded.
+    fn load_global_number_of_downloads(&self) -> Result<Option<PersistentTorrent>, Error>;
+
+    /// Saves the total number of downloads for all torrents into the database.
+    ///
+    /// # Context: Torrent Metrics
+    ///
     /// # Arguments
     ///
     /// * `info_hash` - A reference to the torrent's info hash.
+    /// * `downloaded` - The number of times the torrent has been downloaded.
+    ///
+    /// # Errors
+    ///
+    /// Returns an [`Error`] if the total downloads cannot be saved.
+    fn save_global_number_of_downloads(&self, downloaded: PersistentTorrent) -> Result<(), Error>;
+
+    /// Increases the total number of downloads for all torrents.
     ///
     /// # Context: Torrent Metrics
     ///
     /// # Errors
     ///
     /// Returns an [`Error`] if the query failed.
-    fn increase_number_of_downloads(&self, info_hash: &InfoHash) -> Result<(), Error>;
+    fn increase_global_number_of_downloads(&self) -> Result<(), Error>;
 
     // Whitelist