Merge torrust#788: New API endpoint for listing users

1c62a9e refactor: [torrust#796] minor correction in handler comment (Mario)
3efaf48 refactor: [torrust#796] fix minor clippy error (Mario)
f1259cc feat: [torrust#796] added pagination (Mario)
ae1e6a9 refactor: [torrust#796] minor variable renaming (Mario)
ef0c1e7 refactor: [torrust#658] More renaming (Mario)
b4108dc feat: [torrust#658] new API endpoint for listing user profiles (Mario)
185e17c refactor: [torrust#658] modified naming to make the code more self explanatory (Mario)
23dfbdd ci: [torrust#658] FIxed Mysql E2E tests failing (Mario)
83aaea2 docs: [torrust#658] fixed docs CI error (Mario)
b44ea9b feat: [torrust#658] New API endpoint for getting all the users (Mario)
e8bd16d ci: [torrust#658] fixed minor linting error (Mario)
deb738e feat: [torrust#658] new users listing service (Mario)
f48c4a2 feat: [torrust#658] new repository method to get all user profiles (Mario)
9d5c639 feat: [torrust#658] new database method to get all user profiles (Mario)

Pull request description:

  Parent issue [torrust#658](torrust/torrust-index-gui#658)
  Resolves torrust#796

ACKs for top commit:
  josecelano:
    ACK 1c62a9e

Tree-SHA512: 767f691e0fdb4ec4007b863da6f21186ac9c4d703cb1a093203bbaf3036d18498e3aeda8ecbc2c608f466de3509fb3219757a209c62e04c5e40e9671a468d8a6

Author: josecelano

src/app.rs

@@ -160,6 +160,13 @@ pub async fn run(configuration: Configuration, api_version: &Version) -> Running
 
     let about_service = Arc::new(about::Service::new(authorization_service.clone()));
 
+    let listing_service = Arc::new(user::ListingService::new(
+        configuration.clone(),
+        user_profile_repository.clone(),
+        authorization_service.clone(),
+    ))
+    .clone();
+
     // Build app container
 
     let app_data = Arc::new(AppData::new(
@@ -194,6 +201,7 @@ pub async fn run(configuration: Configuration, api_version: &Version) -> Running
         profile_service,
         ban_service,
         about_service,
+        listing_service,
     ));
 
     // Start cronjob to import tracker torrent data and updating

src/common.rs

@@ -52,6 +52,7 @@ pub struct AppData {
     pub profile_service: Arc<user::ProfileService>,
     pub ban_service: Arc<user::BanService>,
     pub about_service: Arc<about::Service>,
+    pub listing_service: Arc<user::ListingService>,
 }
 
 impl AppData {
@@ -90,6 +91,7 @@ impl AppData {
         profile_service: Arc<user::ProfileService>,
         ban_service: Arc<user::BanService>,
         about_service: Arc<about::Service>,
+        listing_service: Arc<user::ListingService>,
     ) -> AppData {
         AppData {
             cfg,
@@ -125,6 +127,7 @@ impl AppData {
             profile_service,
             ban_service,
             about_service,
+            listing_service,
         }
     }
 }

src/config/v2/api.rs

@@ -10,13 +10,23 @@ pub struct Api {
     /// The maximum page size for torrent lists.
     #[serde(default = "Api::default_max_torrent_page_size")]
     pub max_torrent_page_size: u8,
+
+    /// The default page size for user profile lists.
+    #[serde(default = "Api::default_user_profile_page_size")]
+    pub default_user_profile_page_size: u8,
+
+    /// The maximum page size for user profile lists.
+    #[serde(default = "Api::default_max_user_profile_page_size")]
+    pub max_user_profile_page_size: u8,
 }
 
 impl Default for Api {
     fn default() -> Self {
         Self {
             default_torrent_page_size: Api::default_default_torrent_page_size(),
             max_torrent_page_size: Api::default_max_torrent_page_size(),
+            default_user_profile_page_size: Api::default_user_profile_page_size(),
+            max_user_profile_page_size: Api::default_max_user_profile_page_size(),
         }
     }
 }
@@ -29,4 +39,12 @@ impl Api {
     fn default_max_torrent_page_size() -> u8 {
         30
     }
+
+    fn default_user_profile_page_size() -> u8 {
+        10
+    }
+
+    fn default_max_user_profile_page_size() -> u8 {
+        100
+    }
 }

src/databases/database.rs

@@ -7,7 +7,7 @@ use url::Url;
 use crate::databases::mysql::Mysql;
 use crate::databases::sqlite::Sqlite;
 use crate::models::category::CategoryId;
-use crate::models::response::TorrentsResponse;
+use crate::models::response::{TorrentsResponse, UserProfilesResponse};
 use crate::models::torrent::{Metadata, TorrentListing};
 use crate::models::torrent_file::{DbTorrent, Torrent, TorrentFile};
 use crate::models::torrent_tag::{TagId, TorrentTag};
@@ -143,6 +143,9 @@ pub trait Database: Sync + Send {
     /// Get `UserProfile` from `username`.
     async fn get_user_profile_from_username(&self, username: &str) -> Result<UserProfile, Error>;
 
+    /// Get all user profiles in a paginated form as `UserProfilesResponse`.
+    async fn get_user_profiles_paginated(&self, offset: u64, page_size: u8) -> Result<UserProfilesResponse, Error>;
+
     /// Get `UserCompact` from `user_id`.
     async fn get_user_compact_from_id(&self, user_id: i64) -> Result<UserCompact, Error>;
 

src/databases/mysql.rs

@@ -12,7 +12,7 @@ use super::database::TABLES_TO_TRUNCATE;
 use crate::databases::database;
 use crate::databases::database::{Category, Database, Driver, Sorting, TorrentCompact};
 use crate::models::category::CategoryId;
-use crate::models::response::TorrentsResponse;
+use crate::models::response::{TorrentsResponse, UserProfilesResponse};
 use crate::models::torrent::{Metadata, TorrentListing};
 use crate::models::torrent_file::{
     DbTorrent, DbTorrentAnnounceUrl, DbTorrentFile, DbTorrentHttpSeedUrl, DbTorrentNode, Torrent, TorrentFile,
@@ -155,6 +155,34 @@ impl Database for Mysql {
             .map_err(|_| database::Error::UserNotFound)
     }
 
+    async fn get_user_profiles_paginated(&self, offset: u64, limit: u8) -> Result<UserProfilesResponse, database::Error> {
+        let mut query_string = "SELECT * FROM torrust_user_profiles".to_string();
+
+        let count_query = format!("SELECT COUNT(*) as count FROM ({query_string}) AS count_table");
+
+        let count_result: Result<i64, database::Error> = query_as(&count_query)
+            .fetch_one(&self.pool)
+            .await
+            .map(|(v,)| v)
+            .map_err(|_| database::Error::Error);
+
+        let count = count_result?;
+
+        query_string = format!("{query_string}  LIMIT ?, ?");
+
+        let res: Vec<UserProfile> = sqlx::query_as::<_, UserProfile>(&query_string)
+            .bind(i64::saturating_add_unsigned(0, offset))
+            .bind(limit)
+            .fetch_all(&self.pool)
+            .await
+            .map_err(|_| database::Error::Error)?;
+
+        Ok(UserProfilesResponse {
+            total: u32::try_from(count).expect("variable `count` is larger than u32"),
+            results: res,
+        })
+    }
+
     async fn get_user_compact_from_id(&self, user_id: i64) -> Result<UserCompact, database::Error> {
         query_as::<_, UserCompact>("SELECT tu.user_id, tp.username, tu.administrator FROM torrust_users tu INNER JOIN torrust_user_profiles tp ON tu.user_id = tp.user_id WHERE tu.user_id = ?")
             .bind(user_id)

src/databases/sqlite.rs

@@ -12,7 +12,7 @@ use super::database::TABLES_TO_TRUNCATE;
 use crate::databases::database;
 use crate::databases::database::{Category, Database, Driver, Sorting, TorrentCompact};
 use crate::models::category::CategoryId;
-use crate::models::response::TorrentsResponse;
+use crate::models::response::{TorrentsResponse, UserProfilesResponse};
 use crate::models::torrent::{Metadata, TorrentListing};
 use crate::models::torrent_file::{
     DbTorrent, DbTorrentAnnounceUrl, DbTorrentFile, DbTorrentHttpSeedUrl, DbTorrentNode, Torrent, TorrentFile,
@@ -156,6 +156,34 @@ impl Database for Sqlite {
             .map_err(|_| database::Error::UserNotFound)
     }
 
+    async fn get_user_profiles_paginated(&self, offset: u64, limit: u8) -> Result<UserProfilesResponse, database::Error> {
+        let mut query_string = "SELECT * FROM torrust_user_profiles".to_string();
+
+        let count_query = format!("SELECT COUNT(*) as count FROM ({query_string}) AS count_table");
+
+        let count_result: Result<i64, database::Error> = query_as(&count_query)
+            .fetch_one(&self.pool)
+            .await
+            .map(|(v,)| v)
+            .map_err(|_| database::Error::Error);
+
+        let count = count_result?;
+
+        query_string = format!("{query_string}  LIMIT ?, ?");
+
+        let res: Vec<UserProfile> = sqlx::query_as::<_, UserProfile>(&query_string)
+            .bind(i64::saturating_add_unsigned(0, offset))
+            .bind(limit)
+            .fetch_all(&self.pool)
+            .await
+            .map_err(|_| database::Error::Error)?;
+
+        Ok(UserProfilesResponse {
+            total: u32::try_from(count).expect("variable `count` is larger than u32"),
+            results: res,
+        })
+    }
+
     async fn get_user_compact_from_id(&self, user_id: i64) -> Result<UserCompact, database::Error> {
         query_as::<_, UserCompact>("SELECT tu.user_id, tp.username, tu.administrator FROM torrust_users tu INNER JOIN torrust_user_profiles tp ON tu.user_id = tp.user_id WHERE tu.user_id = ?")
             .bind(user_id)

src/models/response.rs

@@ -3,6 +3,7 @@ use url::Url;
 
 use super::category::Category;
 use super::torrent::TorrentId;
+use super::user::UserProfile;
 use crate::databases::database::Category as DatabaseCategory;
 use crate::models::torrent::TorrentListing;
 use crate::models::torrent_file::TorrentFile;
@@ -123,3 +124,10 @@ pub struct TorrentsResponse {
     pub total: u32,
     pub results: Vec<TorrentListing>,
 }
+
+#[allow(clippy::module_name_repetitions)]
+#[derive(Serialize, Deserialize, Debug, sqlx::FromRow)]
+pub struct UserProfilesResponse {
+    pub total: u32,
+    pub results: Vec<UserProfile>,
+}

src/services/authorization.rs

@@ -52,6 +52,7 @@ pub enum ACTION {
     GetCanonicalInfoHash,
     ChangePassword,
     BanUser,
+    GenerateUserProfilesListing,
 }
 
 pub struct Service {
@@ -248,6 +249,7 @@ impl Default for CasbinConfiguration {
                 admin, GetCanonicalInfoHash
                 admin, ChangePassword
                 admin, BanUser
+                admin, GenerateUserProfilesListing
                 registered, GetAboutPage
                 registered, GetLicensePage
                 registered, GetCategories

src/services/user.rs

@@ -8,6 +8,7 @@ use jsonwebtoken::{decode, Algorithm, DecodingKey, Validation};
 #[cfg(test)]
 use mockall::automock;
 use pbkdf2::password_hash::rand_core::OsRng;
+use serde_derive::Deserialize;
 use tracing::{debug, info};
 
 use super::authentication::DbUserAuthenticationRepository;
@@ -17,6 +18,7 @@ use crate::databases::database::{Database, Error};
 use crate::errors::ServiceError;
 use crate::mailer;
 use crate::mailer::VerifyClaims;
+use crate::models::response::UserProfilesResponse;
 use crate::models::user::{UserCompact, UserId, UserProfile, Username};
 use crate::services::authentication::verify_password;
 use crate::utils::validation::validate_email_address;
@@ -29,6 +31,20 @@ fn no_email() -> String {
     String::new()
 }
 
+/// User request to generate a user profile listing.
+#[derive(Debug, Deserialize)]
+pub struct ListingRequest {
+    pub page_size: Option<u8>,
+    pub page: Option<u32>,
+}
+
+/// Internal specification for user profiles listings.
+#[derive(Debug, Deserialize)]
+pub struct ListingSpecification {
+    pub offset: u64,
+    pub page_size: u8,
+}
+
 pub struct RegistrationService {
     configuration: Arc<Configuration>,
     mailer: Arc<mailer::Service>,
@@ -321,6 +337,74 @@ impl BanService {
     }
 }
 
+pub struct ListingService {
+    configuration: Arc<Configuration>,
+    user_profile_repository: Arc<DbUserProfileRepository>,
+    authorization_service: Arc<authorization::Service>,
+}
+
+impl ListingService {
+    #[must_use]
+    pub fn new(
+        configuration: Arc<Configuration>,
+        user_profile_repository: Arc<DbUserProfileRepository>,
+        authorization_service: Arc<authorization::Service>,
+    ) -> Self {
+        Self {
+            configuration,
+            user_profile_repository,
+            authorization_service,
+        }
+    }
+
+    /// Returns a list of all the user profiles matching the search criteria.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `ServiceError::DatabaseError` if the database query fails.
+    pub async fn generate_user_profile_listing(
+        &self,
+        request: &ListingRequest,
+        maybe_user_id: Option<UserId>,
+    ) -> Result<UserProfilesResponse, ServiceError> {
+        self.authorization_service
+            .authorize(ACTION::GenerateUserProfilesListing, maybe_user_id)
+            .await?;
+
+        let user_profile_listing_specification = self.listing_specification_from_user_request(request).await;
+
+        let user_profiles_response = self
+            .user_profile_repository
+            .generate_listing(&user_profile_listing_specification)
+            .await?;
+
+        Ok(user_profiles_response)
+    }
+
+    /// It converts the user listing request into an internal listing
+    /// specification.
+    async fn listing_specification_from_user_request(&self, request: &ListingRequest) -> ListingSpecification {
+        let settings = self.configuration.settings.read().await;
+        let default_user_profile_page_size = settings.api.default_user_profile_page_size;
+        let max_user_profile_page_size = settings.api.max_user_profile_page_size;
+        drop(settings);
+
+        let page = request.page.unwrap_or(0);
+        let page_size = request.page_size.unwrap_or(default_user_profile_page_size);
+
+        // Guard that page size does not exceed the maximum
+        let page_size = if page_size > max_user_profile_page_size {
+            max_user_profile_page_size
+        } else {
+            page_size
+        };
+
+        let offset = u64::from(page * u32::from(page_size));
+
+        ListingSpecification { offset, page_size }
+    }
+}
+
 #[cfg_attr(test, automock)]
 #[async_trait]
 pub trait Repository: Sync + Send {
@@ -412,6 +496,17 @@ impl DbUserProfileRepository {
     pub async fn get_user_profile_from_username(&self, username: &str) -> Result<UserProfile, Error> {
         self.database.get_user_profile_from_username(username).await
     }
+
+    /// It gets all the user profiles for all the users.
+    ///
+    /// # Errors
+    ///
+    /// It returns an error if there is a database error.
+    pub async fn generate_listing(&self, specification: &ListingSpecification) -> Result<UserProfilesResponse, Error> {
+        self.database
+            .get_user_profiles_paginated(specification.offset, specification.page_size)
+            .await
+    }
 }
 
 pub struct DbBannedUserList {