feat(rate-limit): implement comprehensive rate limiting and listen validation

Add multi-tier rate limiting system with IP-based tracking for anonymous users and user-based tracking for authenticated users. Implements global request limits (150 req/min, 10 req/10sec burst) and song-specific listen validation including duration-based cooldowns.

Key changes:
- Add ListenValidator for validating listen requests before recording
- Implement global rate limit middleware with minute and burst protection
- Add RateLimited error variant with retry_after_secs support
- Extract song/album fetching logic from listen methods for validation
- Add ConnectInfo extraction for IP-based rate limiting
- Update comprehensive README with features, setup, and API documentation

The rate limiting prevents abuse while allowing normal usage patterns, with authenticated users receiving more generous limits than anonymous users.

Author: atomkernel0

README.md

@@ -1 +1,128 @@
-# audio-collection-manager-rust
+# Audio Collection Manager API (Rust)
+
+# README WIP
+
+A high-performance audio collection management API built with Rust, Axum, and SurrealDB.
+
+## Features
+
+- 🎵 Song, Album, and Artist management
+- 👤 User authentication and authorization
+- ⭐ Favorites and playlists
+- 🔍 Advanced search capabilities
+- 📊 Listen tracking and statistics
+- 🏆 Badge system for user achievements
+- 🛡️ Rate limiting for authenticated and anonymous users
+
+## Rate Limiting
+
+The API implements two types of rate limiting:
+
+### Authenticated Users
+- Maximum 100 listens per hour
+- Maximum 10 listens per minute
+- Cannot listen to the same song twice within 70% of its duration (minimum 10 seconds)
+
+### Anonymous Users (IP-based)
+- Maximum 5 listens per minute per IP address
+- Encourages users to sign in for unlimited listening
+- Automatic cleanup of old tracking records
+
+## Database Setup
+
+Run the following migration scripts in order:
+
+```bash
+# Main database schema
+surreal import --conn http://localhost:8000 --user root --pass root --ns your_namespace --db your_database database_schema.surql
+
+# Anonymous listen tracking (for IP-based rate limiting)
+surreal import --conn http://localhost:8000 --user root --pass root --ns your_namespace --db your_database database_anonymous_listen_log.surql
+
+# Other migrations as needed
+surreal import --conn http://localhost:8000 --user root --pass root --ns your_namespace --db your_database database_events_migration.surql
+```
+
+## Environment Variables
+
+Create a `.env` file based on `.env.example`:
+
+```env
+DB_URL=http://localhost:8000
+DB_NS=your_namespace
+DB_NAME=your_database
+DB_USER=root
+DB_PASSWORD=root
+JWT_SECRET=your_secret_key_here
+JWT_EXPIRATION=86400
+BIND_HOST=0.0.0.0
+PORT=8080
+```
+
+## Running the API
+
+```bash
+# Development
+cargo run
+
+# Production build
+cargo build --release
+./target/release/audio-collection-manager-rust
+```
+
+## API Endpoints
+
+### Authentication
+- `POST /api/auth/register` - Register new user
+- `POST /api/auth/login` - Login user
+
+### Songs
+- `POST /api/song/{song_id}/listen` - Record a song listen (supports both authenticated and anonymous users)
+- `GET /api/song/recents` - Get user's recent listens (requires auth)
+- `GET /api/song/{song_id}/album` - Get album from song
+
+### Albums
+- `GET /api/albums` - List all albums
+- `GET /api/albums/{album_id}` - Get album details
+
+### Artists
+- `GET /api/artists` - List all artists
+- `GET /api/artists/{artist_id}` - Get artist details
+
+### Search
+- `GET /api/search?q={query}` - Search across songs, albums, and artists
+
+### User (Protected)
+- `GET /api/user/profile` - Get user profile
+- `GET /api/user/top-songs` - Get user's top songs
+- `GET /api/user/badges` - Get user badges
+
+### Playlists (Protected)
+- `GET /api/playlist` - List user playlists
+- `POST /api/playlist` - Create playlist
+- `GET /api/playlist/{playlist_id}` - Get playlist details
+
+### Favorites (Protected)
+- `POST /api/favorites/song/{song_id}` - Favorite a song
+- `DELETE /api/favorites/song/{song_id}` - Unfavorite a song
+
+## Architecture
+
+- **Framework**: Axum (async web framework)
+- **Database**: SurrealDB (multi-model database)
+- **Authentication**: JWT tokens
+- **Rate Limiting**: In-memory cache + database tracking
+- **Logging**: tracing + tracing-subscriber
+
+## Security Features
+
+- JWT-based authentication
+- Password hashing with bcrypt
+- IP-based rate limiting for anonymous users
+- User-based rate limiting for authenticated users
+- CORS protection
+- Request tracing and logging
+
+## License
+
+See LICENSE file for details.

database_anonymous_listen_log.surql

@@ -0,0 +1,15 @@
+-- Create table for anonymous listen tracking with TTL
+DEFINE TABLE anonymous_listen_log SCHEMAFULL;
+
+-- Define fields
+DEFINE FIELD ip_address ON anonymous_listen_log TYPE string ASSERT $value != NONE;
+DEFINE FIELD song_id ON anonymous_listen_log TYPE string ASSERT $value != NONE;
+DEFINE FIELD listened_at ON anonymous_listen_log TYPE datetime DEFAULT time::now();
+
+-- Index for efficient querying by IP and timestamp
+DEFINE INDEX idx_anonymous_ip_time ON anonymous_listen_log FIELDS ip_address, listened_at;
+
+-- Optional: Event to automatically delete records older than 2 minutes (cleanup)
+DEFINE EVENT cleanup_anonymous_logs ON TABLE anonymous_listen_log WHEN true THEN {
+    DELETE FROM anonymous_listen_log WHERE listened_at < time::now() - 2m;
+};

src/controllers/album_controller.rs

@@ -3,16 +3,18 @@ use crate::{
     models::album::{AlbumWithArtists, AlbumWithRelations, AlbumsMetaResponse},
     models::database_helpers::CountResult,
     services::album_service::AlbumService,
+    validators::listen_validator::{ListenValidator, ValidationResult},
     middlewares::mw_auth::Ctx,
     AppState,
     Result,
 };
 use axum::{
-    extract::{Path, State, Query},
+    extract::{ConnectInfo, Path, State, Query},
     Extension,
     Json,
 };
 use serde::Deserialize;
+use std::net::SocketAddr;
 
 pub struct AlbumController;
 
@@ -125,9 +127,37 @@ impl AlbumController {
     pub async fn listen_to_album(
         State(state): State<AppState>,
         Path(album_id): Path<String>,
+        ConnectInfo(addr): ConnectInfo<SocketAddr>,
         ctx: Option<Extension<Ctx>>,
     ) -> Result<Json<bool>> {
         let user_id = ctx.as_ref().map(|c| c.user_id.as_str());
+        let client_ip = addr.ip().to_string();
+
+        let album = AlbumService::get_album(&state.db, &album_id)
+            .await?
+            .ok_or_else(|| Error::AlbumNotFound {
+                id: album_id.clone(),
+            })?;
+
+        let validation_result = ListenValidator::validate_album_listen(
+            &state.db,
+            &album_id,
+            user_id,
+            Some(&client_ip),
+            album.total_duration.as_secs(),
+        )
+        .await?;
+
+        if let ValidationResult::RateLimited {
+            reason,
+            retry_after_secs,
+        } = validation_result
+        {
+            return Err(Error::RateLimited {
+                reason,
+                retry_after_secs,
+            });
+        }
 
         let success = AlbumService::listen_to_album(&state.db, &album_id, user_id).await?;
 

src/controllers/song_controller.rs

@@ -1,30 +1,52 @@
 use crate::{
-    error::Result,
-    models::{
+    error::Result, middlewares::mw_auth::Ctx, models::{
         album::AlbumWithRelations,
         pagination::{PaginatedResponse, PaginationQuery},
-        song::SongWithRelations,
-    },
-    services::song_service::{SongService, ListenResult},
-    middlewares::mw_auth::Ctx,
-    AppState, Error,
+        song::{SongWithRelations},
+    }, services::song_service::{ListenResult, SongService}, validators::listen_validator::{ListenValidator, ValidationResult}, AppState, Error
 };
 use axum::{
-    extract::{Path, Query, State},
+    extract::{ConnectInfo, Path, Query, State},
     Extension, Json,
 };
+use std::net::SocketAddr;
 
 pub struct SongController;
 
 impl SongController {
     pub async fn listen_to_song(
         State(state): State<AppState>,
         Path(song_id): Path<String>,
+        ConnectInfo(addr): ConnectInfo<SocketAddr>,
         ctx: Option<Extension<Ctx>>,
     ) -> Result<Json<ListenResult>> {
         let user_id = ctx.as_ref().map(|c| c.user_id.as_str());
+        let client_ip = addr.ip().to_string();
 
-        let result = SongService::listen_to_song(&state.db, &song_id, user_id).await?;
+        let song = SongService::get_song_by_id(&state.db, &song_id)
+            .await?
+            .ok_or_else(|| Error::SongNotFound {
+                id: song_id.clone(),
+            })?;
+
+        let validation_result =
+            ListenValidator::validate_listen(&state.db, &song_id, user_id, Some(&client_ip), song.duration.as_secs())
+                .await?;
+
+        if let ValidationResult::RateLimited {
+            reason,
+            retry_after_secs,
+        } = validation_result
+        {
+            return Err(Error::RateLimited {
+                reason,
+                retry_after_secs,
+            });
+        }
+
+        let result =
+            SongService::listen_to_song(&state.db, &song_id, user_id, song.duration)
+                .await?;
 
         Ok(Json(result))
     }

src/error.rs

@@ -60,6 +60,10 @@ pub enum Error {
     InvalidInput {
         reason: String,
     },
+    RateLimited {
+        reason: String,
+        retry_after_secs: u64,
+    },
 }
 
 impl core::fmt::Display for Error {

src/main.rs

@@ -37,6 +37,7 @@ mod models;
 mod routes;
 mod services;
 mod middlewares;
+mod validators;
 
 #[derive(Clone)]
 struct AppState {
@@ -87,7 +88,11 @@ async fn main() -> Result<()> {
         .nest("/albums", AlbumRoutes::routes())
         .nest("/artists", ArtistRoutes::routes())
         .nest("/song", SongRoutes::routes())
-        .nest("/search", SearchRoutes::routes());
+        .nest("/search", SearchRoutes::routes())
+        .route_layer(middleware::from_fn_with_state(
+            app_state.clone(),
+            middlewares::mw_rate_limit::rate_limit_middleware,
+        ));
 
     let protected_routes = Router::new()
         .nest("/user", UserRoutes::routes())
@@ -96,6 +101,10 @@ async fn main() -> Result<()> {
         .route_layer(middleware::from_fn_with_state(
             app_state.clone(),
             middlewares::mw_auth::mw_auth,
+        ))
+        .route_layer(middleware::from_fn_with_state(
+            app_state.clone(),
+            middlewares::mw_rate_limit::rate_limit_middleware,
         ));
 
     let routes_all = Router::new()

src/middlewares/mw_rate_limit.rs

@@ -2,41 +2,71 @@ use std::net::SocketAddr;
 
 use axum::{
     body::Body,
-    extract::{ConnectInfo, MatchedPath, State},
+    extract::{ConnectInfo, State},
     http::{Request, StatusCode},
     middleware::Next,
     response::Response,
 };
 
 use crate::{middlewares::mw_auth::Ctx, AppState};
 
+/// Global rate limiting middleware that only blocks heavy spammers
+///
+/// Limits:
+/// - 150 requests per minute per user/IP (very generous for normal usage)
+/// - 10 requests per 10 seconds (prevents rapid bursts)
+///
+/// This allows users to listen to multiple songs quickly without issues
+/// while still protecting against abuse.
+///
+/// Uses a simple counter-based approach with the moka cache which has TTL support.
 pub async fn rate_limit_middleware(
     State(app_state): State<AppState>,
     ConnectInfo(ip): ConnectInfo<SocketAddr>,
-    matched_path: MatchedPath,
     req: Request<Body>,
     next: Next,
 ) -> Result<Response, StatusCode> {
-    let path = matched_path.as_str();
-    let song_id = if let Some(id) = path.split('/').nth(2) {
-        id
-    } else {
-        // This case should ideally not be reached if routes are set up correctly.
-        // Returning a server error because it indicates a configuration issue.
-        return Err(StatusCode::INTERNAL_SERVER_ERROR);
-    };
-
-    let key = req
+    // Identify the requester (user or IP)
+    let identifier = req
         .extensions()
         .get::<Ctx>()
-        .map(|ctx| format!("{}:{}", ctx.user_id, song_id))
-        .unwrap_or_else(|| format!("{}:{}", ip, song_id));
+        .map(|ctx| format!("user:{}", ctx.user_id))
+        .unwrap_or_else(|| format!("ip:{}", ip.ip()));
 
-    if app_state.rate_limit_cache.get(&key).await.is_some() {
+    // Generate unique request ID for this request
+    let request_id = uuid::Uuid::new_v4();
+    
+    // Minute-based rate limit (150 requests per minute)
+    let minute_key = format!("rl:min:{}:{}", identifier, request_id);
+    app_state.rate_limit_cache.insert(minute_key.clone(), ()).await;
+    
+    // Count requests in the last minute
+    let minute_prefix = format!("rl:min:{}:", identifier);
+    let minute_reqs = app_state.rate_limit_cache
+        .iter()
+        .filter(|(k, _)| k.starts_with(&minute_prefix))
+        .count();
+    
+    const MAX_REQUESTS_PER_MINUTE: usize = 150;
+    if minute_reqs > MAX_REQUESTS_PER_MINUTE {
+        return Err(StatusCode::TOO_MANY_REQUESTS);
+    }
+    
+    // 10-second burst limit (10 requests per 10 seconds)
+    // Only check burst if we're under minute limit
+    let burst_key = format!("rl:burst:{}:{}", identifier, request_id);
+    app_state.rate_limit_cache.insert(burst_key, ()).await;
+    
+    let burst_prefix = format!("rl:burst:{}:", identifier);
+    let burst_reqs = app_state.rate_limit_cache
+        .iter()
+        .filter(|(k, _)| k.starts_with(&burst_prefix))
+        .count();
+    
+    const MAX_REQUESTS_PER_10SEC: usize = 10;
+    if burst_reqs > MAX_REQUESTS_PER_10SEC {
         return Err(StatusCode::TOO_MANY_REQUESTS);
     }
-
-    app_state.rate_limit_cache.insert(key, ()).await;
 
     Ok(next.run(req).await)
 }