Update dependencies, enhance API structure, and improve error handling

- Updated various dependencies in Cargo.toml for better performance and security.
- Refactored API structure to improve modularity and maintainability, including the addition of new endpoints for Spotify real-time data and enhanced error handling.
- Improved README documentation to reflect recent changes and provide clearer usage examples.
- Introduced a consistent error handling mechanism across the application.
- Enhanced the organization of modules for better clarity and separation of concerns.

Author: Snipey

Cargo.lock

@@ -2,25 +2,28 @@
 name = "null-api"
 version = "0.1.0"
 edition = "2021"
-author = "Stephen F<stephen@thenull.dev>"
+authors = ["Stephen F <stephen@thenull.dev>"]
 
 [dependencies]
 # Runtime
-tokio = { version = "1", features = ["full"] }
+tokio = { version = "1.40", features = ["full"] }
 # Environment
-dotenvy = "0.15.6"
-env_logger = "0.10.0"
+dotenvy = "0.15.7"
+env_logger = "0.11.0"
 envconfig = "0.10.0"
-log = "0.4"
+log = "0.4.21"
 # HTTP Libs
-actix-web = "4"
-reqwest = "0.11.13"
+actix-web = "4.5.0"
+reqwest = { version = "0.12", features = ["json"] }
 gql_client = "1.0.7"
 # Json
-serde = {version = "1.0.147", features= ["derive"] }
-serde_json = "1.0.89"
-serde_urlencoded = "0.7"
+serde = { version = "1.0.217", features = ["derive"] }
+serde_json = "1.0.133"
+serde_urlencoded = "0.7.1"
 
 # Database
-redis = {version ="0.22.1", features = ["tokio-comp", "connection-manager"]}
-sqlx = { version = "0.6", features = [ "runtime-tokio-rustls", "postgres", "chrono" ] }
+redis = { version = "0.24", features = ["tokio-comp", "connection-manager"] }
+sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres", "chrono"] }
+
+# Date/Time
+chrono = { version = "0.4", features = ["serde"] }

Cargo.toml

@@ -55,6 +55,8 @@
     <li>
       <a href="#about-the-project">About The Project</a>
       <ul>
+        <li><a href="#project-structure">Project Structure</a></li>
+        <li><a href="#recent-improvements">Recent Improvements</a></li>
         <li><a href="#built-with">Built With</a></li>
       </ul>
     </li>
@@ -77,16 +79,56 @@
 <!-- ABOUT THE PROJECT -->
 ## About The Project
 
-This is a project to track stats on services I use
+This is a Rust-based API for collecting and tracking personal statistics from various services including Spotify, Duolingo, and GitHub. The API provides endpoints to retrieve real-time data and analytics for dashboard visualization.
+
+### Project Structure
+
+The API follows a clean modular architecture with each service having its own dedicated module:
+
+```
+src/modules/
+├── duolingo/
+│   ├── entity.rs    # Data structures for Duolingo API responses
+│   ├── handler.rs   # HTTP request handlers and endpoints
+│   ├── manager.rs   # Business logic and API interactions
+│   └── mod.rs       # Module exports and public API
+├── spotify/
+│   ├── entity.rs    # Data structures for Spotify API responses
+│   ├── handler.rs   # HTTP request handlers and endpoints
+│   ├── manager.rs   # Business logic and API interactions
+│   └── mod.rs       # Module exports and public API
+└── github/
+    ├── entity.rs    # Data structures for GitHub API responses
+    ├── handler.rs   # HTTP request handlers and endpoints
+    ├── manager.rs   # Business logic and API interactions
+    └── mod.rs       # Module exports and public API
+```
+
+Each module follows a consistent pattern:
+- **Entity**: Defines data structures and types for API responses
+- **Handler**: Contains HTTP route handlers and request/response logic
+- **Manager**: Implements business logic, API calls, and data management
+- **Mod**: Provides clean module exports and public API surface
+
+### Recent Improvements
+
+The project has been recently refactored to improve code organization and maintainability:
+
+- **Separated Manager Logic**: Manager implementations have been moved from `mod.rs` files into dedicated `manager.rs` files
+- **Cleaner Module Structure**: Each `mod.rs` now only contains module declarations and re-exports, making them much more readable
+- **Better Separation of Concerns**: Business logic is now clearly separated from module organization
+- **Improved Maintainability**: Each manager's implementation is now in its own focused file, making it easier to maintain and extend
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ### Built With
 
-* Actix-Web
-* SQLx
-* Redis
-* Reqwest
+* **[Rust](https://www.rust-lang.org/)** - Systems programming language for performance and safety
+* **[Actix-Web](https://actix.rs/)** - High-performance web framework for Rust
+* **[SQLx](https://github.com/launchbadge/sqlx)** - Async SQL toolkit with compile-time checked queries
+* **[Redis](https://redis.io/)** - In-memory data structure store for caching
+* **[Reqwest](https://github.com/seanmonstar/reqwest)** - HTTP client library for making API requests
+* **[Serde](https://serde.rs/)** - Serialization framework for converting data structures
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -139,8 +181,34 @@ This is an example of how to list things you need to use the software and how to
 <!-- USAGE EXAMPLES -->
 ## Usage
 
-This is mainly used to track my personal stats to display on a dashboard and for learning.
+This API is designed to collect and aggregate personal statistics from various services for dashboard visualization and analytics. Each module provides specific functionality:
+
+### Available Modules
+
+- **Duolingo Module**: Tracks language learning progress, streak data, and user statistics
+- **Spotify Module**: Retrieves currently playing tracks, user playlists, top artists/tracks, and listening analytics
+- **GitHub Module**: Monitors repository activity, GitHub Actions runners, and organization statistics
+
+### API Endpoints
+
+The API provides RESTful endpoints for each service module, allowing you to:
+- Retrieve real-time data from external APIs
+- Cache frequently accessed data using Redis
+- Aggregate statistics for dashboard visualization
+- Monitor service health and availability
+
+### Example Usage
+
+```bash
+# Get Spotify currently playing track
+GET /spotify/current
+
+# Get Duolingo user stats
+GET /duolingo/stats/{username}
 
+# Get GitHub runners status
+GET /github/runners
+```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -150,7 +218,10 @@ This is mainly used to track my personal stats to display on a dashboard and for
 - [x] Spotify Stats
 - [x] Duolingo Stats
 - [x] Github Stats
+- [x] Modular Architecture Refactoring
 - [ ] Waka Stats
+- [ ] Enhanced Error Handling
+- [ ] API Documentation with OpenAPI/Swagger
 
 See the [open issues](https://github.com/thenulldev/api/issues) for a full list of proposed features (and known issues).
 

README.md

@@ -6,12 +6,16 @@ use tokio::sync::Mutex;
 use crate::{
     config::Config,
     db::{postgres::PostgresManager, redis::RedisManager},
+    error::AppError,
     modules::{
         default,
         duolingo::handler::get_duo_user,
         github::handler::{repos, runners},
         health, index,
-        spotify::handler::{authorize, callback, current},
+        spotify::handler::{
+            authorize, callback, current, devices, playlists, queue, 
+            realtime_info, recently_played, top_artists, top_tracks
+        },
     },
 };
 
@@ -22,16 +26,17 @@ pub struct NullClient {
 
 impl NullClient {
     // Start the Client
-    pub async fn start() -> std::io::Result<()> {
+    pub async fn start() -> Result<(), AppError> {
         // Init Redis
-        let redis = RedisManager::new().await;
+        let redis = RedisManager::new().await?;
         // Init Postgres
-        let postgres = PostgresManager::new().await;
+        let postgres = PostgresManager::new().await?;
 
         // Store data in State
         let data = web::Data::new(Mutex::new(Self { postgres, redis }));
         // Load Client Config
-        let config = Config::init_from_env().unwrap();
+        let config = Config::init_from_env()?;
+        
         // Start HTTP Server
         let server = HttpServer::new(move || {
             let logger = Logger::default();
@@ -41,13 +46,14 @@ impl NullClient {
                 .configure(Self::init)
                 .app_data(web::Data::clone(&data))
         })
-        .bind(((config.listen_host).to_owned(), config.listen_port))?;
+        .bind((config.listen_host.clone(), config.listen_port))?;
+        
         info!(
-            "Connected and listening on http://{}:{}",
-            (config.listen_host).to_owned(),
-            config.listen_port
+            "Server started and listening on http://{}:{}",
+            config.listen_host, config.listen_port
         );
-        server.run().await
+        
+        server.run().await.map_err(AppError::from)
     }
 
     // Initialize Services
@@ -59,6 +65,13 @@ impl NullClient {
         cfg.service(current);
         cfg.service(authorize);
         cfg.service(callback);
+        cfg.service(realtime_info);
+        cfg.service(devices);
+        cfg.service(queue);
+        cfg.service(top_tracks);
+        cfg.service(top_artists);
+        cfg.service(recently_played);
+        cfg.service(playlists);
         // Github
         cfg.service(runners);
         cfg.service(repos);

src/client.rs

@@ -1,26 +1,23 @@
-// let conn = Database::connect(&db_url).await.unwrap();
-
 use envconfig::Envconfig;
 use log::info;
 use sqlx::{postgres::PgPoolOptions, Pool, Postgres};
 
-use crate::config::Config;
+use crate::{config::Config, error::AppError};
 
 pub struct PostgresManager {
-    pub pm: Pool<Postgres>,
+    pub pool: Pool<Postgres>,
 }
 
 impl PostgresManager {
-    pub async fn new() -> Self {
-        let config = Config::init_from_env().unwrap();
+    pub async fn new() -> Result<Self, AppError> {
+        let config = Config::init_from_env()?;
 
         let pool = PgPoolOptions::new()
             .max_connections(5)
             .connect(&config.db_url)
-            .await
-            .unwrap();
+            .await?;
 
-        info!("Connected to Database");
-        Self { pm: pool }
+        info!("Connected to PostgreSQL database");
+        Ok(Self { pool })
     }
 }

src/db/postgres.rs

@@ -1,20 +1,20 @@
 use envconfig::Envconfig;
 use log::info;
 use redis::{aio::ConnectionManager, Client};
-extern crate serde_json;
-use crate::config::Config;
+
+use crate::{config::Config, error::AppError};
 
 #[derive(Clone)]
 pub struct RedisManager {
-    pub cm: ConnectionManager,
+    pub connection: ConnectionManager,
 }
 
 impl RedisManager {
-    pub async fn new() -> Self {
-        let config = Config::init_from_env().unwrap();
-        let client = Client::open(config.redis).unwrap();
-        let cm = ConnectionManager::new(client).await.unwrap();
+    pub async fn new() -> Result<Self, AppError> {
+        let config = Config::init_from_env()?;
+        let client = Client::open(config.redis)?;
+        let connection = ConnectionManager::new(client).await?;
         info!("Connected to Redis");
-        Self { cm }
+        Ok(Self { connection })
     }
 }

src/db/redis.rs

@@ -0,0 +1,80 @@
+use actix_web::{HttpResponse, ResponseError};
+use std::fmt;
+
+#[derive(Debug)]
+pub enum AppError {
+    DatabaseError(sqlx::Error),
+    RedisError(redis::RedisError),
+    ConfigError(envconfig::Error),
+    HttpError(reqwest::Error),
+    JsonError(serde_json::Error),
+    UrlEncodedError(serde_urlencoded::ser::Error),
+    IoError(std::io::Error),
+    SpotifyError(String),
+}
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AppError::DatabaseError(err) => write!(f, "Database error: {}", err),
+            AppError::RedisError(err) => write!(f, "Redis error: {}", err),
+            AppError::ConfigError(err) => write!(f, "Configuration error: {}", err),
+            AppError::HttpError(err) => write!(f, "HTTP error: {}", err),
+            AppError::JsonError(err) => write!(f, "JSON error: {}", err),
+            AppError::UrlEncodedError(err) => write!(f, "URL encoding error: {}", err),
+            AppError::IoError(err) => write!(f, "IO error: {}", err),
+            AppError::SpotifyError(msg) => write!(f, "Spotify error: {}", msg),
+        }
+    }
+}
+
+impl ResponseError for AppError {
+    fn error_response(&self) -> HttpResponse {
+        HttpResponse::InternalServerError().json(serde_json::json!({
+            "error": self.to_string()
+        }))
+    }
+}
+
+// Conversion implementations
+impl From<sqlx::Error> for AppError {
+    fn from(err: sqlx::Error) -> Self {
+        AppError::DatabaseError(err)
+    }
+}
+
+impl From<redis::RedisError> for AppError {
+    fn from(err: redis::RedisError) -> Self {
+        AppError::RedisError(err)
+    }
+}
+
+impl From<envconfig::Error> for AppError {
+    fn from(err: envconfig::Error) -> Self {
+        AppError::ConfigError(err)
+    }
+}
+
+impl From<reqwest::Error> for AppError {
+    fn from(err: reqwest::Error) -> Self {
+        AppError::HttpError(err)
+    }
+}
+
+impl From<serde_json::Error> for AppError {
+    fn from(err: serde_json::Error) -> Self {
+        AppError::JsonError(err)
+    }
+}
+
+impl From<serde_urlencoded::ser::Error> for AppError {
+    fn from(err: serde_urlencoded::ser::Error) -> Self {
+        AppError::UrlEncodedError(err)
+    }
+}
+
+impl From<std::io::Error> for AppError {
+    fn from(err: std::io::Error) -> Self {
+        AppError::IoError(err)
+    }
+}