commenting backend

Author: zerox80

backend/src/db/migrations.rs

@@ -558,12 +558,12 @@ async fn fix_comment_schema(
 
     tracing::info!("Fixing comment schema: Making tutorial_id nullable");
 
-    // 1. Rename existing table
+    // 1. Rename existing table to avoid name collision during schema swap
     sqlx::query("ALTER TABLE comments RENAME TO comments_old")
         .execute(&mut **tx)
         .await?;
 
-    // 2. Create new table with nullable tutorial_id and post_id
+    // 2. Create new table with nullable tutorial_id and post_id (the fix)
     sqlx::query(
         r#"
         CREATE TABLE comments (
@@ -577,21 +577,12 @@ async fn fix_comment_schema(
             is_admin BOOLEAN NOT NULL DEFAULT FALSE,
             CONSTRAINT fk_comments_tutorial FOREIGN KEY (tutorial_id) REFERENCES tutorials(id) ON DELETE CASCADE
         )
-        "#,
+        "# ,
     )
     .execute(&mut **tx)
     .await?;
 
-    // 3. Copy data from old table
-    // We need to handle the case where post_id might not exist in comments_old if the previous migration failed or wasn't run fully,
-    // but we assume apply_comment_migrations ran before this or we handle it.
-    // Actually, apply_comment_migrations adds post_id.
-    // Let's check columns in comments_old to be safe, or just assume standard flow.
-    // To be safe, we'll select specific columns.
-
-    // Note: We need to handle the case where tutorial_id was NOT NULL.
-    // If we have data, it's fine.
-
+    // 3. Migrate data from the old schema to the new one
     sqlx::query(
         r#"
         INSERT INTO comments (id, tutorial_id, post_id, author, content, created_at, votes, is_admin)
@@ -601,20 +592,20 @@ async fn fix_comment_schema(
     .execute(&mut **tx)
     .await?;
 
-    // 4. Drop old table
+    // 4. Cleanup old temporary table
     sqlx::query("DROP TABLE comments_old")
         .execute(&mut **tx)
         .await?;
 
-    // 5. Recreate indices
+    // 5. Recreate performance indices on the new table
     sqlx::query("CREATE INDEX IF NOT EXISTS idx_comments_tutorial ON comments(tutorial_id)")
         .execute(&mut **tx)
         .await?;
     sqlx::query("CREATE INDEX IF NOT EXISTS idx_comments_post ON comments(post_id)")
         .execute(&mut **tx)
         .await?;
 
-    // 6. Mark as fixed
+    // 6. Persist migration state to prevent re-execution
     sqlx::query("INSERT INTO app_metadata (key, value) VALUES ('comment_schema_fixed_v1', 'true')")
         .execute(&mut **tx)
         .await?;

backend/src/db/mod.rs

@@ -1,5 +1,11 @@
-pub mod migrations;
-pub mod pool;
-pub mod seed;
+//! Database Layer
+//! 
+//! This module coordinates database initialization, schema migrations, 
+//! and initial data seeding. It provides a shared connection pool 
+//! used by all repository instances.
+
+pub mod migrations; // SQL schema versioning
+pub mod pool;       // Connection lifecycle management
+pub mod seed;       // Initial data (Default User, etc.)
 
 pub use pool::{create_pool, DbPool};

backend/src/db/pool.rs

@@ -82,8 +82,11 @@ pub async fn create_pool() -> Result<DbPool, sqlx::Error> {
 }
 
 fn ensure_sqlite_directory(database_url: &str) -> Result<(), sqlx::Error> {
+    // Step 1: Extract file path from connection string
     if let Some(db_path) = sqlite_file_path(database_url) {
+        // Step 2: Get parent directory
         if let Some(parent) = db_path.parent() {
+            // Step 3: Create directory if not current working dir
             if parent != Path::new("") && parent != Path::new(".") {
                 if let Err(err) = std::fs::create_dir_all(parent) {
                     tracing::error!(error = %err, path = ?parent, "Failed to create SQLite directory");
@@ -100,20 +103,25 @@ fn ensure_sqlite_directory(database_url: &str) -> Result<(), sqlx::Error> {
 fn sqlite_file_path(database_url: &str) -> Option<PathBuf> {
     const PREFIX: &str = "sqlite:";
 
+    // Verify scheme
     if !database_url.starts_with(PREFIX) {
         return None;
     }
 
+    // Extract path part after prefix
     let mut remainder = &database_url[PREFIX.len()..];
 
+    // Reject memory-only databases or empty paths for directory creation
     if remainder.starts_with(':') || remainder.is_empty() {
         return None;
     }
 
+    // Strip optional query parameters (e.g., ?mode=rwc)
     if let Some((path_part, _)) = remainder.split_once('?') {
         remainder = path_part;
     }
 
+    // Normalize slashes for mixed OS environments
     let normalized = if remainder.starts_with("///") {
         &remainder[2..]
     } else if remainder.starts_with("//") {

backend/src/db/seed.rs

@@ -5,6 +5,7 @@ pub async fn seed_site_content_tx(
     tx: &mut Transaction<'_, Sqlite>,
 ) -> Result<(), sqlx::Error> {
     for (section, content) in default_site_content() {
+        // Step 1: Check if this content section already exists (Idempotency)
         let exists: Option<(String,)> =
             sqlx::query_as("SELECT section FROM site_content WHERE section = ?")
                 .bind(section)
@@ -15,6 +16,7 @@ pub async fn seed_site_content_tx(
             continue;
         }
 
+        // Step 2: Persist the default JSON content
         sqlx::query("INSERT INTO site_content (section, content_json) VALUES (?, ?)")
             .bind(section)
             .bind(content.to_string())

backend/src/handlers/comments.rs

@@ -30,20 +30,27 @@ use serde::{Deserialize, Serialize};
 use std::net::SocketAddr;
 use html_escape;
 
+/// Request payload for creating a comment
 #[derive(Deserialize)]
 pub struct CreateCommentRequest {
+    /// The actual comment text
     content: String,
-    author: Option<String>, // For guest comments
+    /// The author's name (optional for guests)
+    author: Option<String>,
 }
 
+/// Query parameters for listing comments with pagination and sorting
 #[derive(Deserialize)]
 pub struct CommentListQuery {
+    /// Maximum number of comments to return (default: 50)
     #[serde(default = "default_comment_limit")]
     limit: i64,
 
+    /// Number of comments to skip for pagination
     #[serde(default)]
     offset: i64,
 
+    /// Sorting criteria (e.g., "created_at:desc")
     #[serde(default)]
     sort: Option<String>,
 }
@@ -52,18 +59,30 @@ fn default_comment_limit() -> i64 {
     50
 }
 
+/// Local DTO for comment responses, mapping from the database model
 #[derive(Serialize, sqlx::FromRow)]
 pub struct Comment {
+    /// Unique identifier for the comment
     pub id: String,
+    /// Optional parent tutorial ID
     pub tutorial_id: Option<String>,
+    /// Optional parent post ID
     pub post_id: Option<String>,
+    /// Display name of the author
     pub author: String,
+    /// The comment content (HTML escaped)
     pub content: String,
+    /// RFC3339 formatted creation timestamp
     pub created_at: String,
+    /// Total number of votes/likes
     pub votes: i64,
+    /// Whether the comment was posted by an administrator
     pub is_admin: bool,
 }
 
+/// Validates and sanitizes comment content
+///
+/// Trims whitespace, checks length constraints, and escapes HTML characters.
 fn sanitize_comment_content(raw: &str) -> Result<String, (StatusCode, Json<ErrorResponse>)> {
     let trimmed = raw.trim();
 
@@ -90,6 +109,9 @@ fn sanitize_comment_content(raw: &str) -> Result<String, (StatusCode, Json<Error
     Ok(sanitized)
 }
 
+/// Handler for listing comments on a tutorial
+///
+/// Returns a paginated list of comments for the specified tutorial.
 pub async fn list_comments(
     State(pool): State<DbPool>,
     Path(tutorial_id): Path<String>,
@@ -158,6 +180,9 @@ pub async fn list_comments(
     Ok(Json(response_comments))
 }
 
+/// Handler for creating a comment on a tutorial
+///
+/// Validates the tutorial existence and delegates to internal creation logic.
 pub async fn create_comment(
     State(pool): State<DbPool>,
     ConnectInfo(addr): ConnectInfo<SocketAddr>,
@@ -193,6 +218,9 @@ pub async fn create_comment(
     create_comment_internal(pool, Some(tutorial_id), None, payload, None, addr.ip().to_string()).await
 }
 
+/// Handler for listing comments on a blog post
+///
+/// Returns a paginated list of comments for the specified post.
 pub async fn list_post_comments(
     State(pool): State<DbPool>,
     Path(post_id): Path<String>,
@@ -258,6 +286,9 @@ pub async fn list_post_comments(
     Ok(Json(response_comments))
 }
 
+/// Handler for creating a comment on a blog post
+///
+/// Supports both authenticated users and guest comments.
 pub async fn create_post_comment(
     State(pool): State<DbPool>,
     ConnectInfo(addr): ConnectInfo<SocketAddr>,
@@ -290,6 +321,9 @@ pub async fn create_post_comment(
     create_comment_internal(pool, None, Some(post_id), payload, claims, addr.ip().to_string()).await
 }
 
+/// Internal logic for creating a comment on either a tutorial or a post
+///
+/// Handles author resolution (admin/user vs guest), rate limiting, and database insertion.
 async fn create_comment_internal(
     pool: DbPool,
     tutorial_id: Option<String>,
@@ -435,6 +469,9 @@ async fn create_comment_internal(
     Ok(Json(response_comment))
 }
 
+/// Handler for deleting a comment
+///
+/// Requires the user to be either an administrator or the original author.
 pub async fn delete_comment(
     claims: auth::Claims,
     State(pool): State<DbPool>,
@@ -510,6 +547,9 @@ pub async fn delete_comment(
     Ok(StatusCode::NO_CONTENT)
 }
 
+/// Handler for voting on a comment
+///
+/// Authenticated users can upvote/downvote comments. Prevention logic ensures one vote per user.
 pub async fn vote_comment(
     State(pool): State<DbPool>,
     claims: auth::Claims,

backend/src/handlers/frontend_proxy.rs

@@ -1,3 +1,11 @@
+//! Frontend Proxy and SEO Meta Injection
+//!
+//! This module acts as a bridge between the Rust backend and the static frontend.
+//! Instead of serving files directly, it proxies requests to the frontend service
+//! and dynamically injects SEO metadata (title, description) from the database
+//! into the HTML response. This ensures search engines and social media crawlers
+//! see relevant page information even for a Single Page Application (SPA).
+
 use crate::db;
 use axum::{
     extract::State,
@@ -6,15 +14,22 @@ use axum::{
 use reqwest::Client;
 use std::env;
 
-// Default frontend URL (internal Docker network)
+/// Internal URL for the frontend service in the container network
 const DEFAULT_FRONTEND_URL: &str = "http://frontend";
 
+/// Core handler to serve the application entry point (index.html).
+///
+/// This function:
+/// 1. Proxies the raw index.html from the frontend service.
+/// 2. Fetches global site metadata (site_meta section) from the database.
+/// 3. Performs string-based injection of <title> and <meta> tags.
+/// 4. Provides fallback defaults if database records are missing.
 pub async fn serve_index(State(pool): State<db::DbPool>) -> impl IntoResponse {
     let frontend_url =
         env::var("FRONTEND_URL").unwrap_or_else(|_| DEFAULT_FRONTEND_URL.to_string());
     let index_url = format!("{}/index.html", frontend_url);
 
-    // Fetch index.html from frontend container
+    // Proxied Fetch: Retrieve the template from the frontend service
     let client = Client::new();
     let html_content = match client.get(&index_url).send().await {
         Ok(resp) => match resp.text().await {
@@ -37,7 +52,7 @@ pub async fn serve_index(State(pool): State<db::DbPool>) -> impl IntoResponse {
         }
     };
 
-    // Fetch site meta from DB
+    // Metadata Retrieval: Fetch SEO config from database section 'site_meta'
     let site_meta =
         match crate::repositories::content::fetch_site_content_by_section(&pool, "site_meta").await
         {
@@ -50,20 +65,24 @@ pub async fn serve_index(State(pool): State<db::DbPool>) -> impl IntoResponse {
             _ => serde_json::json!({}),
         };
 
+    // Extract title from JSON, providing a sensible fallback
     let title = site_meta
         .get("title")
         .and_then(|v| v.as_str())
         .unwrap_or("Linux Tutorial - Lerne Linux Schritt für Schritt");
 
+    // Extract description from JSON, providing a sensible fallback
     let description = site_meta
         .get("description")
         .and_then(|v| v.as_str())
         .unwrap_or("Lerne Linux von Grund auf - Interaktiv, modern und praxisnah.");
 
-    // Inject meta tags using simple string replacement
-    // We target the specific default tags to replace them
+    // Injection Phase:
+    // We use simple string replacement to swap hardcoded defaults in the build
+    // for dynamic database-driven values.
     let mut injected_html = html_content;
 
+    // SECURITY: Thoroughly escape database-sourced text to prevent XSS via meta tags
     let safe_title = html_escape::encode_text(&title);
     let safe_description = html_escape::encode_text(&description);