refactor: rename structs and functions, and add docs

Author: josecelano

src/app.rs

@@ -14,7 +14,7 @@ use crate::config::Configuration;
 use crate::databases::database::connect_database;
 use crate::mailer::MailerService;
 use crate::routes;
-use crate::tracker::service::TrackerService;
+use crate::tracker::service::Service;
 
 pub struct Running {
     pub api_server: Server,
@@ -44,7 +44,7 @@ pub async fn run(configuration: Configuration) -> Running {
 
     let database = Arc::new(connect_database(&database_connect_url).await.expect("Database error."));
     let auth = Arc::new(AuthorizationService::new(cfg.clone(), database.clone()));
-    let tracker_service = Arc::new(TrackerService::new(cfg.clone(), database.clone()).await);
+    let tracker_service = Arc::new(Service::new(cfg.clone(), database.clone()).await);
     let mailer_service = Arc::new(MailerService::new(cfg.clone()).await);
     let image_cache_service = Arc::new(ImageCacheService::new(cfg.clone()).await);
 

src/common.rs

@@ -5,7 +5,7 @@ use crate::cache::image::manager::ImageCacheService;
 use crate::config::Configuration;
 use crate::databases::database::Database;
 use crate::mailer::MailerService;
-use crate::tracker::service::TrackerService;
+use crate::tracker::service::Service;
 
 pub type Username = String;
 
@@ -15,7 +15,7 @@ pub struct AppData {
     pub cfg: Arc<Configuration>,
     pub database: Arc<Box<dyn Database>>,
     pub auth: Arc<AuthorizationService>,
-    pub tracker: Arc<TrackerService>,
+    pub tracker: Arc<Service>,
     pub mailer: Arc<MailerService>,
     pub image_cache_manager: Arc<ImageCacheService>,
 }
@@ -25,7 +25,7 @@ impl AppData {
         cfg: Arc<Configuration>,
         database: Arc<Box<dyn Database>>,
         auth: Arc<AuthorizationService>,
-        tracker: Arc<TrackerService>,
+        tracker: Arc<Service>,
         mailer: Arc<MailerService>,
         image_cache_manager: Arc<ImageCacheService>,
     ) -> AppData {

src/console/commands/import_tracker_statistics.rs

@@ -9,7 +9,7 @@ use text_colorizer::*;
 use crate::bootstrap::config::init_configuration;
 use crate::bootstrap::logging;
 use crate::databases::database::connect_database;
-use crate::tracker::service::TrackerService;
+use crate::tracker::service::Service;
 
 const NUMBER_OF_ARGUMENTS: usize = 0;
 
@@ -76,7 +76,7 @@ pub async fn import(_args: &Arguments) {
             .expect("Database error."),
     );
 
-    let tracker_service = Arc::new(TrackerService::new(cfg.clone(), database.clone()).await);
+    let tracker_service = Arc::new(Service::new(cfg.clone(), database.clone()).await);
 
     tracker_service.update_torrents().await.unwrap();
 }

src/tracker/api.rs

@@ -1,30 +1,39 @@
 use reqwest::{Error, Response};
-pub struct ApiConnectionInfo {
+pub struct ConnectionInfo {
+    /// The URL of the tracker. Eg: <https://tracker:7070> or <udp://tracker:6969>
     pub url: String,
+    /// The token used to authenticate with the tracker API.
     pub token: String,
 }
 
-impl ApiConnectionInfo {
+impl ConnectionInfo {
+    #[must_use]
     pub fn new(url: String, token: String) -> Self {
         Self { url, token }
     }
 }
 
-pub struct ApiClient {
-    pub connection_info: ApiConnectionInfo,
+pub struct Client {
+    pub connection_info: ConnectionInfo,
     base_url: String,
 }
 
-impl ApiClient {
-    pub fn new(connection_info: ApiConnectionInfo) -> Self {
+impl Client {
+    #[must_use]
+    pub fn new(connection_info: ConnectionInfo) -> Self {
         let base_url = format!("{}/api/v1", connection_info.url);
         Self {
             connection_info,
             base_url,
         }
     }
 
-    pub async fn whitelist_info_hash(&self, info_hash: &str) -> Result<Response, Error> {
+    /// Add a torrent to the tracker whitelist.
+    ///
+    /// # Errors
+    ///
+    /// Will return an error if the HTTP request fails.
+    pub async fn whitelist_torrent(&self, info_hash: &str) -> Result<Response, Error> {
         let request_url = format!(
             "{}/whitelist/{}?token={}",
             self.base_url, info_hash, self.connection_info.token
@@ -35,7 +44,12 @@ impl ApiClient {
         client.post(request_url).send().await
     }
 
-    pub async fn remove_info_hash_from_whitelist(&self, info_hash: &str) -> Result<Response, Error> {
+    /// Remove a torrent from the tracker whitelist.
+    ///
+    /// # Errors
+    ///
+    /// Will return an error if the HTTP request fails.
+    pub async fn remove_torrent_from_whitelist(&self, info_hash: &str) -> Result<Response, Error> {
         let request_url = format!(
             "{}/whitelist/{}?token={}",
             self.base_url, info_hash, self.connection_info.token
@@ -46,6 +60,11 @@ impl ApiClient {
         client.delete(request_url).send().await
     }
 
+    /// Retrieve a new tracker key.
+    ///
+    /// # Errors
+    ///
+    /// Will return an error if the HTTP request fails.
     pub async fn retrieve_new_tracker_key(&self, token_valid_seconds: u64) -> Result<Response, Error> {
         let request_url = format!(
             "{}/key/{}?token={}",
@@ -57,6 +76,11 @@ impl ApiClient {
         client.post(request_url).send().await
     }
 
+    /// Retrieve the info for a torrent.
+    ///
+    /// # Errors
+    ///
+    /// Will return an error if the HTTP request fails.
     pub async fn get_torrent_info(&self, info_hash: &str) -> Result<Response, Error> {
         let request_url = format!("{}/torrent/{}?token={}", self.base_url, info_hash, self.connection_info.token);
 

src/tracker/service.rs

@@ -3,7 +3,7 @@ use std::sync::Arc;
 use log::{error, info};
 use serde::{Deserialize, Serialize};
 
-use super::api::{ApiClient, ApiConnectionInfo};
+use super::api::{Client, ConnectionInfo};
 use crate::config::Configuration;
 use crate::databases::database::Database;
 use crate::errors::ServiceError;
@@ -35,24 +35,24 @@ pub struct PeerId {
     pub client: Option<String>,
 }
 
-pub struct TrackerService {
+pub struct Service {
     database: Arc<Box<dyn Database>>,
-    api_client: ApiClient,
+    api_client: Client,
     token_valid_seconds: u64,
     tracker_url: String,
 }
 
-impl TrackerService {
-    pub async fn new(cfg: Arc<Configuration>, database: Arc<Box<dyn Database>>) -> TrackerService {
+impl Service {
+    pub async fn new(cfg: Arc<Configuration>, database: Arc<Box<dyn Database>>) -> Service {
         let settings = cfg.settings.read().await;
-        let api_client = ApiClient::new(ApiConnectionInfo::new(
+        let api_client = Client::new(ConnectionInfo::new(
             settings.tracker.api_url.clone(),
             settings.tracker.token.clone(),
         ));
         let token_valid_seconds = settings.tracker.token_valid_seconds;
         let tracker_url = settings.tracker.url.clone();
         drop(settings);
-        TrackerService {
+        Service {
             database,
             api_client,
             token_valid_seconds,
@@ -67,7 +67,7 @@ impl TrackerService {
     /// Will return an error if the HTTP request failed (for example if the
     /// tracker API is offline) or if the tracker API returned an error.
     pub async fn whitelist_info_hash(&self, info_hash: String) -> Result<(), ServiceError> {
-        let response = self.api_client.whitelist_info_hash(&info_hash).await;
+        let response = self.api_client.whitelist_torrent(&info_hash).await;
 
         match response {
             Ok(response) => {
@@ -88,7 +88,7 @@ impl TrackerService {
     /// Will return an error if the HTTP request failed (for example if the
     /// tracker API is offline) or if the tracker API returned an error.
     pub async fn remove_info_hash_from_whitelist(&self, info_hash: String) -> Result<(), ServiceError> {
-        let response = self.api_client.remove_info_hash_from_whitelist(&info_hash).await;
+        let response = self.api_client.remove_torrent_from_whitelist(&info_hash).await;
 
         match response {
             Ok(response) => {