feat: implement thumbnail generation and management

- Remove unused image dependencies from Cargo.lock.
- Update API to handle thumbnail generation and checkup processes.
- Introduce new routes for rebuilding and regenerating thumbnails.
- Enhance job tracking with progress indicators for thumbnail jobs.
- Update front-end components to display thumbnail job status and progress.
- Add backend logic for managing thumbnail jobs and integrating with the API.
- Refactor existing code to accommodate new thumbnail functionalities.

apps/api/src/books.rs

@@ -351,25 +351,29 @@ pub async fn get_thumbnail(
     State(state): State<AppState>,
     Path(book_id): Path<Uuid>,
 ) -> Result<impl IntoResponse, ApiError> {
-    let row = sqlx::query(
-        "SELECT thumbnail_path FROM books WHERE id = $1"
-    )
-    .bind(book_id)
-    .fetch_optional(&state.pool)
-    .await
-    .map_err(|e| ApiError::internal(e.to_string()))?;
+    let row = sqlx::query("SELECT thumbnail_path FROM books WHERE id = $1")
+        .bind(book_id)
+        .fetch_optional(&state.pool)
+        .await
+        .map_err(|e| ApiError::internal(e.to_string()))?;
 
     let row = row.ok_or_else(|| ApiError::not_found("book not found"))?;
     let thumbnail_path: Option<String> = row.get("thumbnail_path");
 
-    let path = thumbnail_path.ok_or_else(|| ApiError::not_found("thumbnail not found"))?;
-
-    let data = std::fs::read(&path)
-        .map_err(|e| ApiError::internal(format!("cannot read thumbnail: {}", e)))?;
+    let data = if let Some(ref path) = thumbnail_path {
+        std::fs::read(path)
+            .map_err(|e| ApiError::internal(format!("cannot read thumbnail: {}", e)))?
+    } else {
+        // Fallback: render page 1 on the fly (same as pages logic)
+        crate::pages::render_book_page_1(&state, book_id, 300, 80).await?
+    };
 
     let mut headers = HeaderMap::new();
     headers.insert(header::CONTENT_TYPE, HeaderValue::from_static("image/webp"));
-    headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("public, max-age=31536000, immutable"));
+    headers.insert(
+        header::CACHE_CONTROL,
+        HeaderValue::from_static("public, max-age=31536000, immutable"),
+    );
 
     Ok((StatusCode::OK, headers, Body::from(data)))
 }

apps/api/src/index_jobs.rs

@@ -34,6 +34,9 @@ pub struct IndexJobResponse {
     pub error_opt: Option<String>,
     #[schema(value_type = String)]
     pub created_at: DateTime<Utc>,
+    pub progress_percent: Option<i32>,
+    pub processed_files: Option<i32>,
+    pub total_files: Option<i32>,
 }
 
 #[derive(Serialize, ToSchema)]
@@ -142,7 +145,7 @@ pub async fn enqueue_rebuild(
 )]
 pub async fn list_index_jobs(State(state): State<AppState>) -> Result<Json<Vec<IndexJobResponse>>, ApiError> {
     let rows = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at FROM index_jobs ORDER BY created_at DESC LIMIT 100",
+        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files FROM index_jobs ORDER BY created_at DESC LIMIT 100",
     )
     .fetch_all(&state.pool)
     .await?;
@@ -171,7 +174,7 @@ pub async fn cancel_job(
     id: axum::extract::Path<Uuid>,
 ) -> Result<Json<IndexJobResponse>, ApiError> {
     let rows_affected = sqlx::query(
-        "UPDATE index_jobs SET status = 'cancelled' WHERE id = $1 AND status IN ('pending', 'running')",
+        "UPDATE index_jobs SET status = 'cancelled' WHERE id = $1 AND status IN ('pending', 'running', 'generating_thumbnails')",
     )
     .bind(id.0)
     .execute(&state.pool)
@@ -182,7 +185,7 @@ pub async fn cancel_job(
     }
 
     let row = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at FROM index_jobs WHERE id = $1",
+        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files FROM index_jobs WHERE id = $1",
     )
     .bind(id.0)
     .fetch_one(&state.pool)
@@ -298,6 +301,9 @@ pub fn map_row(row: sqlx::postgres::PgRow) -> IndexJobResponse {
         stats_json: row.get("stats_json"),
         error_opt: row.get("error_opt"),
         created_at: row.get("created_at"),
+        progress_percent: row.try_get("progress_percent").ok(),
+        processed_files: row.try_get("processed_files").ok(),
+        total_files: row.try_get("total_files").ok(),
     }
 }
 
@@ -333,9 +339,9 @@ fn map_row_detail(row: sqlx::postgres::PgRow) -> IndexJobDetailResponse {
 )]
 pub async fn get_active_jobs(State(state): State<AppState>) -> Result<Json<Vec<IndexJobResponse>>, ApiError> {
     let rows = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at 
+        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files
          FROM index_jobs 
-         WHERE status IN ('pending', 'running') 
+         WHERE status IN ('pending', 'running', 'generating_thumbnails') 
          ORDER BY created_at ASC"
     )
     .fetch_all(&state.pool)

apps/api/src/main.rs

@@ -7,6 +7,7 @@ mod openapi;
 mod pages;
 mod search;
 mod settings;
+mod thumbnails;
 mod tokens;
 
 use std::{
@@ -99,10 +100,13 @@ async fn main() -> anyhow::Result<()> {
         .route("/libraries/:id/scan", axum::routing::post(libraries::scan_library))
         .route("/libraries/:id/monitoring", axum::routing::patch(libraries::update_monitoring))
         .route("/index/rebuild", axum::routing::post(index_jobs::enqueue_rebuild))
+        .route("/index/thumbnails/rebuild", axum::routing::post(thumbnails::start_thumbnails_rebuild))
+        .route("/index/thumbnails/regenerate", axum::routing::post(thumbnails::start_thumbnails_regenerate))
         .route("/index/status", get(index_jobs::list_index_jobs))
         .route("/index/jobs/active", get(index_jobs::get_active_jobs))
         .route("/index/jobs/:id", get(index_jobs::get_job_details))
         .route("/index/jobs/:id/stream", get(index_jobs::stream_job_progress))
+        .route("/index/jobs/:id/thumbnails/checkup", axum::routing::post(thumbnails::start_checkup))
         .route("/index/jobs/:id/errors", get(index_jobs::get_job_errors))
         .route("/index/cancel/:id", axum::routing::post(index_jobs::cancel_job))
         .route("/folders", get(index_jobs::list_folders))

apps/api/src/openapi.rs

@@ -10,6 +10,8 @@ use utoipa::OpenApi;
         crate::pages::get_page,
         crate::search::search_books,
         crate::index_jobs::enqueue_rebuild,
+        crate::thumbnails::start_thumbnails_rebuild,
+        crate::thumbnails::start_thumbnails_regenerate,
         crate::index_jobs::list_index_jobs,
         crate::index_jobs::get_active_jobs,
         crate::index_jobs::get_job_details,
@@ -37,6 +39,7 @@ use utoipa::OpenApi;
             crate::search::SearchQuery,
             crate::search::SearchResponse,
             crate::index_jobs::RebuildRequest,
+            crate::thumbnails::ThumbnailsRebuildRequest,
             crate::index_jobs::IndexJobResponse,
             crate::index_jobs::IndexJobDetailResponse,
             crate::index_jobs::JobErrorResponse,

apps/api/src/pages.rs

@@ -279,6 +279,54 @@ fn image_response(bytes: Arc<Vec<u8>>, content_type: &str, etag_suffix: Option<&
     (StatusCode::OK, headers, Body::from((*bytes).clone())).into_response()
 }
 
+/// Render page 1 of a book (for thumbnail fallback or thumbnail checkup). Uses thumbnail dimensions by default.
+pub async fn render_book_page_1(
+    state: &AppState,
+    book_id: Uuid,
+    width: u32,
+    quality: u8,
+) -> Result<Vec<u8>, ApiError> {
+    let row = sqlx::query(
+        r#"SELECT abs_path, format FROM book_files WHERE book_id = $1 ORDER BY updated_at DESC LIMIT 1"#,
+    )
+    .bind(book_id)
+    .fetch_optional(&state.pool)
+    .await
+    .map_err(|e| ApiError::internal(e.to_string()))?;
+
+    let row = row.ok_or_else(|| ApiError::not_found("book file not found"))?;
+    let abs_path: String = row.get("abs_path");
+    let abs_path = remap_libraries_path(&abs_path);
+    let input_format: String = row.get("format");
+
+    let _permit = state
+        .page_render_limit
+        .clone()
+        .acquire_owned()
+        .await
+        .map_err(|_| ApiError::internal("render limiter unavailable"))?;
+
+    let abs_path_clone = abs_path.clone();
+    let bytes = tokio::time::timeout(
+        Duration::from_secs(60),
+        tokio::task::spawn_blocking(move || {
+            render_page(
+                &abs_path_clone,
+                &input_format,
+                1,
+                &OutputFormat::Webp,
+                quality,
+                width,
+            )
+        }),
+    )
+    .await
+    .map_err(|_| ApiError::internal("page rendering timeout"))?
+    .map_err(|e| ApiError::internal(format!("render task failed: {e}")))?;
+
+    bytes
+}
+
 fn render_page(
     abs_path: &str,
     input_format: &str,

apps/api/src/thumbnails.rs

@@ -0,0 +1,284 @@
+use std::path::Path;
+
+use anyhow::Context;
+use axum::{
+    extract::{Path as AxumPath, State},
+    http::StatusCode,
+    Json,
+};
+use image::GenericImageView;
+use serde::Deserialize;
+use sqlx::Row;
+use tracing::{info, warn};
+use uuid::Uuid;
+use utoipa::ToSchema;
+
+use crate::{error::ApiError, index_jobs, pages, AppState};
+
+#[derive(Clone)]
+struct ThumbnailConfig {
+    enabled: bool,
+    width: u32,
+    height: u32,
+    quality: u8,
+    directory: String,
+}
+
+async fn load_thumbnail_config(pool: &sqlx::PgPool) -> ThumbnailConfig {
+    let fallback = ThumbnailConfig {
+        enabled: true,
+        width: 300,
+        height: 400,
+        quality: 80,
+        directory: "/data/thumbnails".to_string(),
+    };
+    let row = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'thumbnail'"#)
+        .fetch_optional(pool)
+        .await;
+
+    match row {
+        Ok(Some(row)) => {
+            let value: serde_json::Value = row.get("value");
+            ThumbnailConfig {
+                enabled: value
+                    .get("enabled")
+                    .and_then(|v| v.as_bool())
+                    .unwrap_or(fallback.enabled),
+                width: value
+                    .get("width")
+                    .and_then(|v| v.as_u64())
+                    .map(|v| v as u32)
+                    .unwrap_or(fallback.width),
+                height: value
+                    .get("height")
+                    .and_then(|v| v.as_u64())
+                    .map(|v| v as u32)
+                    .unwrap_or(fallback.height),
+                quality: value
+                    .get("quality")
+                    .and_then(|v| v.as_u64())
+                    .map(|v| v as u8)
+                    .unwrap_or(fallback.quality),
+                directory: value
+                    .get("directory")
+                    .and_then(|v| v.as_str())
+                    .map(|s| s.to_string())
+                    .unwrap_or_else(|| fallback.directory.clone()),
+            }
+        }
+        _ => fallback,
+    }
+}
+
+fn generate_thumbnail(image_bytes: &[u8], config: &ThumbnailConfig) -> anyhow::Result<Vec<u8>> {
+    let img = image::load_from_memory(image_bytes).context("failed to load image")?;
+    let (orig_w, orig_h) = img.dimensions();
+    let ratio_w = config.width as f32 / orig_w as f32;
+    let ratio_h = config.height as f32 / orig_h as f32;
+    let ratio = ratio_w.min(ratio_h);
+    let new_w = (orig_w as f32 * ratio) as u32;
+    let new_h = (orig_h as f32 * ratio) as u32;
+    let resized = img.resize(new_w, new_h, image::imageops::FilterType::Lanczos3);
+    let rgba = resized.to_rgba8();
+    let (w, h) = rgba.dimensions();
+    let rgb_data: Vec<u8> = rgba.pixels().flat_map(|p| [p[0], p[1], p[2]]).collect();
+    let quality = f32::max(config.quality as f32, 85.0);
+    let webp_data =
+        webp::Encoder::new(&rgb_data, webp::PixelLayout::Rgb, w, h).encode(quality);
+    Ok(webp_data.to_vec())
+}
+
+fn save_thumbnail(book_id: Uuid, thumbnail_bytes: &[u8], config: &ThumbnailConfig) -> anyhow::Result<String> {
+    let dir = Path::new(&config.directory);
+    std::fs::create_dir_all(dir)?;
+    let filename = format!("{}.webp", book_id);
+    let path = dir.join(&filename);
+    std::fs::write(&path, thumbnail_bytes)?;
+    Ok(path.to_string_lossy().to_string())
+}
+
+async fn run_checkup(state: AppState, job_id: Uuid) {
+    let pool = &state.pool;
+    let row = sqlx::query("SELECT library_id, type FROM index_jobs WHERE id = $1")
+        .bind(job_id)
+        .fetch_optional(pool)
+        .await;
+
+    let (library_id, job_type) = match row {
+        Ok(Some(r)) => (
+            r.get::<Option<Uuid>, _>("library_id"),
+            r.get::<String, _>("type"),
+        ),
+        _ => {
+            warn!("thumbnails checkup: job {} not found", job_id);
+            return;
+        }
+    };
+
+    // Regenerate: clear existing thumbnails in scope so they get regenerated
+    if job_type == "thumbnail_regenerate" {
+        let cleared = sqlx::query(
+            r#"UPDATE books SET thumbnail_path = NULL WHERE (library_id = $1 OR $1 IS NULL)"#,
+        )
+        .bind(library_id)
+        .execute(pool)
+        .await;
+        if let Ok(res) = cleared {
+            info!("thumbnails regenerate: cleared {} books", res.rows_affected());
+        }
+    }
+
+    let book_ids: Vec<Uuid> = sqlx::query_scalar(
+        r#"SELECT id FROM books WHERE (library_id = $1 OR $1 IS NULL) AND thumbnail_path IS NULL"#,
+    )
+    .bind(library_id)
+    .fetch_all(pool)
+    .await
+    .unwrap_or_default();
+
+    let config = load_thumbnail_config(pool).await;
+    if !config.enabled || book_ids.is_empty() {
+        let _ = sqlx::query(
+            "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
+        )
+        .bind(job_id)
+        .execute(pool)
+        .await;
+        return;
+    }
+
+    let total = book_ids.len() as i32;
+    let _ = sqlx::query(
+        "UPDATE index_jobs SET status = 'generating_thumbnails', total_files = $2, processed_files = 0, current_file = NULL WHERE id = $1",
+    )
+    .bind(job_id)
+    .bind(total)
+    .execute(pool)
+    .await;
+
+    for (i, &book_id) in book_ids.iter().enumerate() {
+        match pages::render_book_page_1(&state, book_id, config.width, config.quality).await {
+            Ok(page_bytes) => {
+                match generate_thumbnail(&page_bytes, &config) {
+                    Ok(thumb_bytes) => {
+                        if let Ok(path) = save_thumbnail(book_id, &thumb_bytes, &config) {
+                            if sqlx::query("UPDATE books SET thumbnail_path = $1 WHERE id = $2")
+                                .bind(&path)
+                                .bind(book_id)
+                                .execute(pool)
+                                .await
+                                .is_ok()
+                            {
+                                let processed = (i + 1) as i32;
+                                let percent = ((i + 1) as f64 / total as f64 * 100.0) as i32;
+                                let _ = sqlx::query(
+                                    "UPDATE index_jobs SET processed_files = $2, progress_percent = $3 WHERE id = $1",
+                                )
+                                .bind(job_id)
+                                .bind(processed)
+                                .bind(percent)
+                                .execute(pool)
+                                .await;
+                            }
+                        }
+                    }
+                    Err(e) => warn!("thumbnail generate failed for book {}: {:?}", book_id, e),
+                }
+            }
+            Err(e) => warn!("render page 1 failed for book {}: {:?}", book_id, e),
+        }
+    }
+
+    let _ = sqlx::query(
+        "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
+    )
+    .bind(job_id)
+    .execute(pool)
+    .await;
+
+    info!("thumbnails checkup finished for job {} ({} books)", job_id, total);
+}
+
+#[derive(Deserialize, ToSchema)]
+pub struct ThumbnailsRebuildRequest {
+    #[schema(value_type = Option<String>)]
+    pub library_id: Option<Uuid>,
+}
+
+/// POST /index/thumbnails/rebuild — create a job and generate thumbnails for books that don't have one (optional library scope).
+#[utoipa::path(
+    post,
+    path = "/index/thumbnails/rebuild",
+    tag = "indexing",
+    request_body = Option<ThumbnailsRebuildRequest>,
+    responses(
+        (status = 200, body = index_jobs::IndexJobResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden - Admin scope required"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn start_thumbnails_rebuild(
+    State(state): State<AppState>,
+    payload: Option<Json<ThumbnailsRebuildRequest>>,
+) -> Result<Json<index_jobs::IndexJobResponse>, ApiError> {
+    let library_id = payload.as_ref().and_then(|p| p.0.library_id);
+    let job_id = Uuid::new_v4();
+
+    let row = sqlx::query(
+        r#"INSERT INTO index_jobs (id, library_id, type, status)
+           VALUES ($1, $2, 'thumbnail_rebuild', 'pending')
+           RETURNING id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at"#,
+    )
+    .bind(job_id)
+    .bind(library_id)
+    .fetch_one(&state.pool)
+    .await
+    .map_err(|e| ApiError::internal(e.to_string()))?;
+
+    Ok(Json(index_jobs::map_row(row)))
+}
+
+/// POST /index/thumbnails/regenerate — create a job and regenerate all thumbnails in scope (clears then regenerates).
+#[utoipa::path(
+    post,
+    path = "/index/thumbnails/regenerate",
+    tag = "indexing",
+    request_body = Option<ThumbnailsRebuildRequest>,
+    responses(
+        (status = 200, body = index_jobs::IndexJobResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden - Admin scope required"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn start_thumbnails_regenerate(
+    State(state): State<AppState>,
+    payload: Option<Json<ThumbnailsRebuildRequest>>,
+) -> Result<Json<index_jobs::IndexJobResponse>, ApiError> {
+    let library_id = payload.as_ref().and_then(|p| p.0.library_id);
+    let job_id = Uuid::new_v4();
+
+    let row = sqlx::query(
+        r#"INSERT INTO index_jobs (id, library_id, type, status)
+           VALUES ($1, $2, 'thumbnail_regenerate', 'pending')
+           RETURNING id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at"#,
+    )
+    .bind(job_id)
+    .bind(library_id)
+    .fetch_one(&state.pool)
+    .await
+    .map_err(|e| ApiError::internal(e.to_string()))?;
+
+    Ok(Json(index_jobs::map_row(row)))
+}
+
+/// POST /index/jobs/:id/thumbnails/checkup — start thumbnail generation for books missing thumbnails (called by indexer at end of build).
+pub async fn start_checkup(
+    State(state): State<AppState>,
+    AxumPath(job_id): AxumPath<Uuid>,
+) -> Result<StatusCode, ApiError> {
+    let state = state.clone();
+    tokio::spawn(async move { run_checkup(state, job_id).await });
+    Ok(StatusCode::ACCEPTED)
+}