src/interfaces/api/handlers/file_handler.rs

use axum::{
    Json,
    body::Body,
    extract::{Multipart, Path, Query, State},
    http::{HeaderMap, Response, StatusCode, header},
    response::IntoResponse,
};
use bytes::Bytes;
use http_range_header::parse_range_header;
use serde::Deserialize;
use std::collections::HashMap;
use utoipa::ToSchema;

use crate::application::ports::file_ports::{
    FileManagementUseCase, FileRetrievalUseCase, FileUploadUseCase,
};
use crate::application::ports::storage_ports::{FileReadPort, StorageUsagePort};
use crate::application::ports::thumbnail_ports::ThumbnailPort;
use crate::application::ports::{file_ports::OptimizedFileContent, folder_ports::FolderUseCase};
use crate::common::di::AppState;
use crate::infrastructure::services::audio_metadata_service::AudioMetadataService;
use crate::interfaces::errors::AppError;
use crate::interfaces::middleware::auth::AuthUser;
use crate::{application::dtos::file_dto::FileDto, domain::services::authorization::Permission};
use std::sync::Arc;

/**
 * Type aliases for dependency injection state.
 */
/// Global application state for dependency injection
type GlobalState = Arc<AppState>;

/**
 * API handler for file-related operations.
 *
 * Acts as a thin HTTP adapter in the hexagonal architecture: it parses requests,
 * delegates business logic to application services, and maps results to HTTP
 * responses.  No infrastructure or strategy logic lives here.
 */
pub struct FileHandler;

impl FileHandler {
    // ── Why no #[utoipa::path] here? ─────────────────────────────────────────────
    // utoipa 5.4.0's proc macro generates helper structs / impls inside its expansion.
    // Rust allows struct definitions at module scope but forbids them inside impl blocks,
    // so `#[utoipa::path]` fails on every method in this impl block regardless of HTTP
    // verb or annotation content. All route handlers are free functions below.
    // TODO: collapse after utoipa upgrade.

    // ═══════════════════════════════════════════════════════════════════════
    //  UPLOAD
    // ═══════════════════════════════════════════════════════════════════════

    /// Streaming file upload — constant ~64 KB RAM regardless of file size.
    ///
    /// **Hash-on-Write**: BLAKE3 is computed while spooling the multipart
    /// body to the temp file. This eliminates the second sequential read
    /// that dedup_service would otherwise need, cutting total I/O in half.
    pub async fn upload_file(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        multipart: Multipart,
    ) -> impl IntoResponse {
        match Self::upload_file_inner(&state, &auth_user, multipart).await {
            Ok((file, _blob_hash)) => Self::created_json_response(&file).into_response(),
            Err(response) => response.into_response(),
        }
    }

    /// Core upload logic shared by [`Self::upload_file`] and
    /// [`Self::upload_file_with_thumbnails`].
    ///
    /// Returns `(FileDto, blob_hash)` on success.  The blob hash is the
    /// BLAKE3 digest computed during the hash-on-write spool and is
    /// propagated without an extra database round-trip so that callers
    /// (e.g. thumbnail generation) can resolve the physical blob path
    /// immediately.
    async fn upload_file_inner(
        state: &GlobalState,
        auth_user: &AuthUser,
        mut multipart: Multipart,
    ) -> Result<(crate::application::dtos::file_dto::FileDto, String), Response<Body>> {
        let upload_service = &state.applications.file_upload_service;
        let mut folder_id: Option<String> = None;

        tracing::debug!("📤 Processing streaming file upload (hash-on-write)");

        // caveat: if folder_id field is given after check can fails
        while let Some(field) = multipart.next_field().await.unwrap_or(None) {
            let name = field.name().unwrap_or("").to_string();

            if name == "folder_id" {
                let v = field.text().await.unwrap_or_default();
                if !v.is_empty() {
                    folder_id = Some(v);
                }
                continue;
            }

            if name == "file" {
                let raw_filename = field.file_name().unwrap_or("unnamed").to_string();
                // Browsers send the full relative path (e.g. "Screenshots/file.png")
                // as the filename for folder uploads via webkitRelativePath.
                // Strip path components to get the basename only.
                // This also prevents path-traversal attacks.
                let filename = raw_filename
                    .rsplit('/')
                    .next()
                    .unwrap_or(&raw_filename)
                    .rsplit('\\')
                    .next()
                    .unwrap_or(&raw_filename)
                    .to_string();
                let content_type = field
                    .content_type()
                    .unwrap_or("application/octet-stream")
                    .to_string();

                // ── Fail-fast pre-check: verify the caller can Create inside
                // the target folder BEFORE spooling the multipart body to disk.
                // The upload service re-checks at write time — this is a
                // UX/resource optimization, not the security boundary.
                if let Some(ref fid) = folder_id
                    && let Err(err) = state
                        .applications
                        .folder_service_concrete
                        .require_permission(auth_user.id, Permission::Create, fid)
                        .await
                {
                    tracing::warn!(
                        "⛔ UPLOAD REJECTED: user='{}' folder='{}' err='{}'",
                        auth_user.username,
                        fid,
                        err
                    );
                    return Err(Self::domain_error_response(err));
                }

                // ── Early quota check (before spooling to disk) ──────
                if let Some(storage_svc) = state.storage_usage_service.as_ref() {
                    let estimated_size = field
                        .headers()
                        .get(header::CONTENT_LENGTH)
                        .and_then(|v| v.to_str().ok())
                        .and_then(|s| s.parse::<u64>().ok())
                        .unwrap_or(0);
                    if let Err(err) = storage_svc
                        .check_storage_quota(auth_user.id, estimated_size)
                        .await
                    {
                        tracing::warn!(
                            "⛔ UPLOAD REJECTED (early quota): user={}, file={}, est_size={}",
                            auth_user.username,
                            filename,
                            estimated_size
                        );
                        return Err(Self::quota_error_response(err));
                    }
                }

                // ── Spool multipart field to temp file + hash-on-write ──
                // .dedup_temp is created once by DedupService::initialize() at startup
                let temp_dir = state.core.path_service.get_root_path().join(".dedup_temp");
                let temp_path = temp_dir.join(format!("upload-{}", uuid::Uuid::new_v4()));

                let mut total_size: u64 = 0;
                let mut hasher = blake3::Hasher::new();
                let spool_result: Result<(), String> = async {
                    let file = tokio::fs::File::create(&temp_path)
                        .await
                        .map_err(|e| format!("Failed to create temp file: {}", e))?;

                    // Pre-allocate if Content-Length is known (reduces fragmentation)
                    let hint = field
                        .headers()
                        .get(axum::http::header::CONTENT_LENGTH)
                        .and_then(|v| v.to_str().ok())
                        .and_then(|s| s.parse::<u64>().ok());
                    if let Some(len) = hint {
                        let _ = file.set_len(len).await; // best-effort
                    }

                    // 512 KB buffer — 8× fewer write syscalls than 64 KB
                    let mut writer = tokio::io::BufWriter::with_capacity(524_288, file);
                    let mut field = field;
                    // IMPORTANT: use explicit match instead of `while let Ok(Some(..))`.
                    // The old pattern silently swallowed Err (client disconnect)
                    // and accepted partially received data as a complete upload.
                    loop {
                        match field.chunk().await {
                            Ok(Some(chunk)) => {
                                total_size += chunk.len() as u64;
                                hasher.update(&chunk);
                                tokio::io::AsyncWriteExt::write_all(&mut writer, &chunk)
                                    .await
                                    .map_err(|e| format!("Failed to write chunk: {}", e))?;
                            }
                            Ok(None) => break, // End of field — upload complete
                            Err(e) => {
                                return Err(format!(
                                    "Connection lost during upload (received {} bytes): {}",
                                    total_size, e
                                ));
                            }
                        }
                    }
                    tokio::io::AsyncWriteExt::flush(&mut writer)
                        .await
                        .map_err(|e| format!("Failed to flush temp file: {}", e))?;
                    Ok(())
                }
                .await;

                if let Err(e) = spool_result {
                    let _ = tokio::fs::remove_file(&temp_path).await;
                    tracing::error!("❌ UPLOAD SPOOL FAILED: {} - {}", filename, e);
                    return Err(Self::domain_error_response(
                        crate::common::errors::DomainError::internal_error("FileUpload", e),
                    ));
                }

                // Empty file — use streaming path with the (empty) temp file
                if total_size == 0 {
                    let hash = hasher.finalize().to_hex().to_string();
                    let dto = upload_service
                        .upload_file_streaming(
                            filename,
                            folder_id,
                            content_type,
                            &temp_path,
                            0,
                            Some(hash.clone()),
                        )
                        .await
                        .map_err(Self::domain_error_response)?;
                    return Ok((dto, hash));
                }

                // Finalize hash
                let hash = hasher.finalize().to_hex().to_string();

                // ── MIME detection (magic bytes + extension fallback) ─
                let content_type = crate::common::mime_detect::refine_content_type_from_file(
                    &temp_path,
                    &filename,
                    &content_type,
                )
                .await;

                // ── Quota enforcement ────────────────────────────────
                if let Some(storage_svc) = state.storage_usage_service.as_ref()
                    && let Err(err) = storage_svc
                        .check_storage_quota(auth_user.id, total_size)
                        .await
                {
                    let _ = tokio::fs::remove_file(&temp_path).await;
                    tracing::warn!(
                        "⛔ UPLOAD REJECTED (quota): user={}, file={}, size={}",
                        auth_user.username,
                        filename,
                        total_size
                    );
                    return Err(Self::quota_error_response(err));
                }

                // ── Streaming upload (temp file → blob store, hash pre-computed) ─
                match upload_service
                    .upload_file_streaming(
                        filename.clone(),
                        folder_id,
                        content_type,
                        &temp_path,
                        total_size,
                        Some(hash.clone()),
                    )
                    .await
                {
                    Ok(file) => {
                        tracing::info!(
                            "✅ STREAMING UPLOAD: {} ({} bytes, ID: {})",
                            filename,
                            total_size,
                            file.id
                        );
                        return Ok((file, hash));
                    }
                    Err(err) => {
                        let _ = tokio::fs::remove_file(&temp_path).await;
                        tracing::error!("❌ UPLOAD FAILED: {} - {}", filename, err);
                        return Err(Self::domain_error_response(err));
                    }
                }
            }
        }

        Err((
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "No file provided"
            })),
        )
            .into_response())
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  THUMBNAILS
    // ═══════════════════════════════════════════════════════════════════════

    /// Get a thumbnail for a file (image or video).
    ///
    /// **Cache-first**: if the thumbnail already exists in the moka in-memory
    /// cache or on disk, serve it immediately — **zero DB queries**.  The
    /// ownership check was already performed when the thumbnail was first
    /// generated (at upload) or uploaded (PUT by the owner).  UUIDv4 file IDs
    /// have 122 bits of entropy, making enumeration infeasible.
    ///
    /// **ETag / 304**: responses carry an immutable ETag.  If the browser
    /// sends `If-None-Match` matching the ETag, we return 304 Not Modified
    /// without touching cache or DB — pure header round-trip.
    ///
    /// The DB path is only taken on a **cache miss for images** where the
    /// thumbnail hasn't been generated yet (first access after upload if
    /// background generation hasn't finished).
    pub(super) async fn get_thumbnail_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        headers: HeaderMap,
        Path((id, size)): Path<(String, String)>,
    ) -> impl IntoResponse {
        use crate::application::ports::thumbnail_ports::ThumbnailSize;

        // check first that user can access this resource
        if let Err(err) = state
            .applications
            .file_management_service
            .require_permission(auth_user.id, Permission::Read, &id)
            .await
        {
            return AppError::from(err).into_response();
        }

        let thumbnail_service = &state.core.thumbnail_service;

        let thumb_size = match size.as_str() {
            "icon" => ThumbnailSize::Icon,
            "preview" => ThumbnailSize::Preview,
            "large" => ThumbnailSize::Large,
            _ => {
                return (
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({
                        "error": "Invalid thumbnail size. Use: icon, preview, or large"
                    })),
                )
                    .into_response();
            }
        };

        // ── ETag short-circuit (Solution C) ──────────────────────────
        // Thumbnails are immutable — the ETag never changes for a given
        // (file_id, size) pair.  If the browser already has it, return 304
        // with zero I/O or DB work.
        let etag = format!("\"thumb-{}-{:?}\"", id, thumb_size);
        if let Some(if_none_match) = headers.get(header::IF_NONE_MATCH)
            && let Ok(val) = if_none_match.to_str()
            && (val == etag || val == "*")
        {
            return Response::builder()
                .status(StatusCode::NOT_MODIFIED)
                .header(header::ETAG, &etag)
                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
                .body(Body::empty())
                .unwrap()
                .into_response();
        }

        // ── Cache-first path (Solution A) ────────────────────────────
        // Try moka (RAM) → disk before touching the database.
        // If the thumbnail exists it was authorized at creation time.
        if let Some(data) = thumbnail_service
            .get_cached_thumbnail(&id, None, thumb_size.into())
            .await
        {
            return Response::builder()
                .status(StatusCode::OK)
                .header(header::CONTENT_TYPE, "image/jpeg")
                .header(header::CONTENT_LENGTH, data.len())
                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
                .header(header::ETAG, &etag)
                .body(Body::from(data))
                .unwrap()
                .into_response();
        }

        // ── Cache miss — need DB for ownership + blob resolution ─────
        let file_retrieval_service = &state.applications.file_retrieval_service;

        let file = match file_retrieval_service
            .get_file_or_trashed_with_perms(&id, auth_user.id)
            .await
        {
            Ok(f) => f,
            Err(err) => {
                return AppError::from(err).into_response();
            }
        };

        // Non-image (video, etc.) with no cached thumbnail → 204
        if !thumbnail_service.is_supported_image(&file.mime_type) {
            return Response::builder()
                .status(StatusCode::NO_CONTENT)
                .header(header::CACHE_CONTROL, "no-store")
                .body(Body::empty())
                .unwrap()
                .into_response();
        }

        // Resolve the blob hash (content-addressable storage).
        let blob_hash = match state
            .repositories
            .file_read_repository
            .get_blob_hash(&id)
            .await
        {
            Ok(hash) => hash,
            Err(_) => {
                return AppError::internal_error("File blob not found").into_response();
            }
        };
        if let Some(data) = thumbnail_service
            .get_cached_thumbnail(&id, Some(&blob_hash), thumb_size.into())
            .await
        {
            return Response::builder()
                .status(StatusCode::OK)
                .header(header::CONTENT_TYPE, "image/jpeg")
                .header(header::CONTENT_LENGTH, data.len())
                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
                .header(header::ETAG, &etag)
                .body(Body::from(data))
                .unwrap()
                .into_response();
        }

        let original_bytes = match state.core.dedup_service.read_blob_bytes(&blob_hash).await {
            Ok(bytes) => bytes,
            Err(err) => {
                return AppError::internal_error(format!(
                    "Failed to load source image for thumbnail generation: {}",
                    err
                ))
                .into_response();
            }
        };

        match thumbnail_service
            .get_thumbnail_from_bytes(&id, &blob_hash, thumb_size.into(), original_bytes)
            .await
        {
            Ok(data) => Response::builder()
                .status(StatusCode::OK)
                .header(header::CONTENT_TYPE, "image/jpeg")
                .header(header::CONTENT_LENGTH, data.len())
                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
                .header(header::ETAG, &etag)
                .body(Body::from(data))
                .unwrap()
                .into_response(),
            Err(err) => AppError::internal_error(format!("Thumbnail generation failed: {}", err))
                .into_response(),
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  UPLOAD THUMBNAIL (client-generated, e.g. video frames)
    // ═══════════════════════════════════════════════════════════════════════

    /// Accept a client-generated thumbnail (e.g. video frame extracted via
    /// `<video>` + `<canvas>` in the browser) and persist it in the server
    /// cache.  The image is validated, re-encoded to WebP, and stored so
    /// subsequent `GET …/thumbnail/{size}` requests are served instantly.
    ///
    /// **Max body: 512 KB** — thumbnails are small.
    pub(super) async fn upload_thumbnail_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        Path((id, size)): Path<(String, String)>,
        body: Bytes,
    ) -> impl IntoResponse {
        use crate::application::ports::thumbnail_ports::ThumbnailSize;

        // check first that user can access this resource
        if let Err(err) = state
            .applications
            .file_management_service
            .require_permission(auth_user.id, Permission::Update, &id)
            .await
        {
            return AppError::from(err).into_response();
        }

        let thumbnail_service = &state.core.thumbnail_service;

        // Validate size
        let thumb_size = match size.as_str() {
            "icon" => ThumbnailSize::Icon,
            "preview" => ThumbnailSize::Preview,
            "large" => ThumbnailSize::Large,
            _ => {
                return (
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({
                        "error": "Invalid thumbnail size. Use: icon, preview, or large"
                    })),
                )
                    .into_response();
            }
        };

        // Reject oversized payloads (512 KB)
        if body.len() > 512 * 1024 {
            return (
                StatusCode::PAYLOAD_TOO_LARGE,
                Json(serde_json::json!({ "error": "Thumbnail exceeds 512 KB limit" })),
            )
                .into_response();
        }

        // Validate file ownership
        let file_retrieval_service = &state.applications.file_retrieval_service;
        if let Err(err) = file_retrieval_service
            .get_file_with_perms(&id, auth_user.id)
            .await
        {
            return AppError::from(err).into_response();
        }

        // Validate, re-encode to WebP, and store
        match thumbnail_service
            .store_external_thumbnail(&id, thumb_size.into(), body)
            .await
        {
            Ok(_) => StatusCode::CREATED.into_response(),
            Err(err) => AppError::internal_error(format!("Failed to store thumbnail: {}", err))
                .into_response(),
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  DOWNLOAD
    // ═══════════════════════════════════════════════════════════════════════

    /// Downloads a file with optimized multi-tier strategy.
    ///
    /// The tier selection (write-behind → hot cache → WebP transcode → mmap →
    /// streaming) is fully handled by `FileRetrievalUseCase::get_file_optimized`.
    /// This handler only deals with HTTP concerns: ETag, Range, Content-Disposition,
    /// and optional compression.
    pub(super) async fn download_file_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        Path(id): Path<String>,
        Query(params): Query<HashMap<String, String>>,
        headers: HeaderMap,
    ) -> impl IntoResponse {
        let retrieval = &state.applications.file_retrieval_service;

        // ── Get file metadata (ownership-scoped) ────────────────────────
        let file_dto = match retrieval.get_file_with_perms(&id, auth_user.id).await {
            Ok(f) => f,
            Err(err) => {
                return AppError::from(err).into_response();
            }
        };

        // ── Metadata-only request ────────────────────────────────────
        if params
            .get("metadata")
            .is_some_and(|v| v == "true" || v == "1")
        {
            return (
                StatusCode::OK,
                Json(serde_json::json!({
                    "id": file_dto.id,
                    "name": file_dto.name,
                    "path": file_dto.path,
                    "size": file_dto.size,
                    "mime_type": file_dto.mime_type,
                    "folder_id": file_dto.folder_id,
                    "created_at": file_dto.created_at,
                    "modified_at": file_dto.modified_at
                })),
            )
                .into_response();
        }

        let etag = format!("\"{}-{}\"", id, file_dto.modified_at);

        // ── ETag (304 Not Modified) ──────────────────────────────────
        if let Some(inm) = headers.get(header::IF_NONE_MATCH)
            && let Ok(client_etag) = inm.to_str()
            && (client_etag == etag || client_etag == "*")
        {
            return Response::builder()
                .status(StatusCode::NOT_MODIFIED)
                .header(header::ETAG, &etag)
                .body(Body::empty())
                .unwrap()
                .into_response();
        }

        // ── Range Requests ───────────────────────────────────────────
        if let Some(range_header) = headers.get(header::RANGE)
            && let Ok(range_str) = range_header.to_str()
            && let Ok(ranges) = parse_range_header(range_str)
        {
            let validated = ranges.validate(file_dto.size);
            if let Ok(valid_ranges) = validated {
                if let Some(range) = valid_ranges.first() {
                    let start = *range.start();
                    let end = *range.end();
                    let range_length = end - start + 1;
                    let disposition =
                        Self::content_disposition(&file_dto.name, &file_dto.mime_type, &params);

                    match retrieval
                        .get_file_range_stream_with_perms(&id, auth_user.id, start, Some(end + 1))
                        .await
                    {
                        Ok(stream) => {
                            return Response::builder()
                                .status(StatusCode::PARTIAL_CONTENT)
                                .header(header::CONTENT_TYPE, &*file_dto.mime_type)
                                .header(header::CONTENT_DISPOSITION, &disposition)
                                .header(header::CONTENT_LENGTH, range_length)
                                .header(
                                    header::CONTENT_RANGE,
                                    format!("bytes {}-{}/{}", start, end, file_dto.size),
                                )
                                .header(header::ACCEPT_RANGES, "bytes")
                                .header(header::ETAG, &etag)
                                .header(
                                    header::CACHE_CONTROL,
                                    "private, max-age=3600, must-revalidate",
                                )
                                .body(Body::from_stream(Box::into_pin(stream)))
                                .unwrap()
                                .into_response();
                        }
                        Err(err) => {
                            tracing::error!("Error creating range stream: {}", err);
                            // fall through to normal download
                        }
                    }
                }
            } else {
                return Response::builder()
                    .status(StatusCode::RANGE_NOT_SATISFIABLE)
                    .header(header::CONTENT_RANGE, format!("bytes */{}", file_dto.size))
                    .body(Body::empty())
                    .unwrap()
                    .into_response();
            }
        }

        // ── Normal download (delegated to service) ───────────────────
        let disposition = Self::content_disposition(&file_dto.name, &file_dto.mime_type, &params);

        let accept_webp = headers
            .get(header::ACCEPT)
            .and_then(|v| v.to_str().ok())
            .is_some_and(|a| a.contains("image/webp"));
        let prefer_original = params
            .get("original")
            .is_some_and(|v| v == "true" || v == "1");

        // Use the ownership-scoped optimized download.
        // Ownership was already verified by get_file_owned above,
        // so we can safely use the preloaded variant.
        match retrieval
            .get_file_optimized_preloaded(&id, file_dto.clone(), accept_webp, prefer_original)
            .await
        {
            Ok((_file, content)) => match content {
                OptimizedFileContent::Bytes {
                    data, mime_type, ..
                } => Self::build_cached_response(data, &mime_type, &disposition, &etag)
                    .into_response(),
                OptimizedFileContent::Mmap(mmap_data) => Response::builder()
                    .status(StatusCode::OK)
                    .header(header::CONTENT_TYPE, &*file_dto.mime_type)
                    .header(header::CONTENT_DISPOSITION, &disposition)
                    .header(header::CONTENT_LENGTH, mmap_data.len())
                    .header(header::ETAG, &etag)
                    .header(
                        header::CACHE_CONTROL,
                        "private, max-age=3600, must-revalidate",
                    )
                    .header(header::ACCEPT_RANGES, "bytes")
                    .body(Body::from(mmap_data))
                    .unwrap()
                    .into_response(),
                OptimizedFileContent::Stream(pinned_stream) => Response::builder()
                    .status(StatusCode::OK)
                    .header(header::CONTENT_TYPE, &*file_dto.mime_type)
                    .header(header::CONTENT_DISPOSITION, &disposition)
                    .header(header::CONTENT_LENGTH, file_dto.size)
                    .header(header::ETAG, &etag)
                    .header(
                        header::CACHE_CONTROL,
                        "private, max-age=3600, must-revalidate",
                    )
                    .header(header::ACCEPT_RANGES, "bytes")
                    .body(Body::from_stream(pinned_stream))
                    .unwrap()
                    .into_response(),
            },
            Err(err) => AppError::from(err).into_response(),
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  LIST
    // ═══════════════════════════════════════════════════════════════════════

    /// Lists files in a folder, extracting `folder_id` from query parameters.
    pub(super) async fn list_files_query_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        headers: HeaderMap,
        Query(params): Query<HashMap<String, String>>,
    ) -> impl IntoResponse {
        let folder_id = params.get("folder_id").map(|id| id.as_str());
        tracing::info!("API: Listing files with folder_id: {:?}", folder_id);

        let retrieval = &state.applications.file_retrieval_service;
        match retrieval
            .list_files_with_perms(folder_id, auth_user.id)
            .await
        {
            Ok(files) => {
                // Compute lightweight ETag from max modified_at + count
                let max_mod = files.iter().map(|f| f.modified_at).max().unwrap_or(0);
                let count = files.len();
                let mut hasher = std::collections::hash_map::DefaultHasher::new();
                std::hash::Hash::hash(&max_mod, &mut hasher);
                std::hash::Hash::hash(&count, &mut hasher);
                let etag = format!("\"{:x}\"", std::hash::Hasher::finish(&hasher));

                // 304 Not Modified if client already has this version
                if let Some(inm) = headers.get(header::IF_NONE_MATCH)
                    && let Ok(client_etag) = inm.to_str()
                    && client_etag == etag
                {
                    return Response::builder()
                        .status(StatusCode::NOT_MODIFIED)
                        .header(header::ETAG, &etag)
                        .body(Body::empty())
                        .unwrap()
                        .into_response();
                }

                tracing::info!("Found {} files", files.len());
                let mut resp = (StatusCode::OK, Json(files)).into_response();
                resp.headers_mut()
                    .insert(header::ETAG, header::HeaderValue::from_str(&etag).unwrap());
                resp
            }
            Err(err) => AppError::from(err).into_response(),
        }
    }

    /// Uploads a file and generates thumbnails in the background for images.
    ///
    /// Delegates to [`Self::upload_file_inner`] and, on success, spawns
    /// a background task to generate all thumbnail sizes before serialising
    /// the `FileDto` once.
    /// TODO: should move thumbnail generation to a generic hook ? (onfileUploaded, other services will beneficiate it)
    pub(super) async fn upload_file_with_thumbnails_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        multipart: Multipart,
    ) -> impl IntoResponse {
        let (file, blob_hash) = match Self::upload_file_inner(&state, &auth_user, multipart).await {
            Ok(pair) => pair,
            Err(response) => return response.into_response(),
        };

        // Generate thumbnails for supported images in background.
        // The blob_hash was already computed during the hash-on-write spool,
        // so we can reconstruct the source bytes directly from DedupService
        // without an extra DB round-trip.
        if state
            .core
            .thumbnail_service
            .is_supported_image(&file.mime_type)
        {
            let file_id = file.id.clone();
            let thumbnail_service = state.core.thumbnail_service.clone();
            let dedup_service = state.core.dedup_service.clone();
            let blob_hash_owned = blob_hash.clone();

            tokio::spawn(async move {
                tracing::info!("🖼️ Generating thumbnails for: {}", file_id);
                match dedup_service.read_blob_bytes(&blob_hash_owned).await {
                    Ok(original_bytes) => {
                        thumbnail_service.generate_all_sizes_background_from_bytes(
                            file_id,
                            blob_hash_owned,
                            original_bytes,
                            dedup_service.clone(),
                        );
                    }
                    Err(err) => {
                        tracing::warn!(
                            "Failed to load source image for thumbnail generation {}: {}",
                            file_id,
                            err
                        );
                    }
                }
            });
        }

        // TODO: same remark: a hook to handle easily audio service
        // Extract audio metadata for supported audio files in background.
        if let Some(ref audio_service) = state.applications.audio_metadata_service
            && AudioMetadataService::is_audio_file(&file.mime_type)
            && let Ok(file_id) = uuid::Uuid::parse_str(&file.id)
        {
            let file_path = state.core.dedup_service.blob_path(&blob_hash);
            AudioMetadataService::spawn_extraction_background(
                audio_service.clone(),
                file_id,
                file_path,
            );
        }

        Self::created_json_response(&file).into_response()
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  METADATA
    // ═══════════════════════════════════════════════════════════════════════

    /// Returns EXIF/media metadata for a file.
    ///
    /// Used by the Photos lightbox and for testing EXIF extraction.
    pub(super) async fn get_file_metadata_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        Path(file_id): Path<String>,
    ) -> impl IntoResponse {
        // check first that user can access this resource
        if let Err(err) = state
            .applications
            .file_management_service
            .require_permission(auth_user.id, Permission::Read, &file_id)
            .await
        {
            return AppError::from(err).into_response();
        }

        let metadata_repo = &state.repositories.file_metadata_repository;
        match metadata_repo.get(&file_id).await {
            Ok(Some(meta)) => (StatusCode::OK, Json(meta)).into_response(),
            Ok(None) => (
                StatusCode::OK,
                Json(serde_json::json!({
                    "file_id": file_id,
                    "message": "No EXIF metadata available"
                })),
            )
                .into_response(),
            Err(e) => (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(serde_json::json!({ "error": e.to_string() })),
            )
                .into_response(),
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  DELETE
    // ═══════════════════════════════════════════════════════════════════════

    /// Deletes a file (trash-first with dedup cleanup).
    ///
    /// All logic (trash fallback, dedup ref-count, hash computation) is handled
    /// by `FileManagementUseCase::delete_with_cleanup`.
    ///
    /// When auth is available, uses trash-first deletion; otherwise falls back
    /// to permanent delete so the endpoint works with or without auth.
    pub(super) async fn delete_file_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        Path(id): Path<String>,
    ) -> impl IntoResponse {
        let mgmt = &state.applications.file_management_service;

        // Auth required: trash-first with dedup cleanup + ownership verification
        let result = mgmt
            .delete_and_cleanup_with_perms(&id, auth_user.id)
            .await
            .map(|was_trashed| {
                if was_trashed {
                    tracing::info!("File moved to trash: {}", id);
                } else {
                    tracing::info!("File permanently deleted: {}", id);
                }
            });

        match result {
            Ok(_) => StatusCode::NO_CONTENT.into_response(),
            Err(err) => AppError::from(err).into_response(),
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  MOVE
    // ═══════════════════════════════════════════════════════════════════════

    /// Renames a file (ownership-verified)
    pub(super) async fn rename_file_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        Path(id): Path<String>,
        Json(payload): Json<serde_json::Value>,
    ) -> impl IntoResponse {
        let new_name = match payload.get("name").and_then(|v| v.as_str()) {
            Some(name) if !name.trim().is_empty() => name.trim().to_string(),
            _ => {
                return (
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({
                        "error": "Missing or empty 'name' field"
                    })),
                )
                    .into_response();
            }
        };

        tracing::info!("Renaming file {} to \"{}\"", id, new_name);
        let mgmt = &state.applications.file_management_service;
        match mgmt
            .rename_file_with_perms(&id, auth_user.id, &new_name)
            .await
        {
            Ok(file_dto) => (StatusCode::OK, Json(file_dto)).into_response(),
            Err(err) => AppError::from(err).into_response(),
        }
    }

    /// Moves a file to a different folder (ownership-verified)
    /// TODO: dead function ?
    pub async fn move_file(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        Path(id): Path<String>,
        Json(payload): Json<MoveFilePayload>,
    ) -> impl IntoResponse {
        tracing::info!("Moving file {} to folder {:?}", id, payload.folder_id);

        let mgmt = &state.applications.file_management_service;

        match mgmt
            .move_file_with_perms(&id, auth_user.id, payload.folder_id)
            .await
        {
            Ok(file) => (StatusCode::OK, Json(file)).into_response(),
            Err(err) => AppError::from(err).into_response(),
        }
    }

    /// Moves a file to a different folder (ownership-verified)
    pub(super) async fn move_file_simple_impl(
        State(state): State<GlobalState>,
        auth_user: AuthUser,
        Path(id): Path<String>,
        Json(payload): Json<serde_json::Value>,
    ) -> impl IntoResponse {
        let folder_id = payload
            .get("folder_id")
            .and_then(|v| v.as_str())
            .map(|s| s.to_string());

        let mgmt = &state.applications.file_management_service;
        match mgmt
            .move_file_with_perms(&id, auth_user.id, folder_id)
            .await
        {
            Ok(file_dto) => (StatusCode::OK, Json(file_dto)).into_response(),
            Err(err) => AppError::from(err).into_response(),
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    //  PRIVATE HELPERS
    // ═══════════════════════════════════════════════════════════════════════

    /// Build a Content-Disposition header value.
    ///
    /// Build a `Content-Disposition` header value for an authenticated download,
    /// honouring the `?inline=true|1` query param. Delegates to the shared
    /// `build_content_disposition` so the share-link path produces identical
    /// header values for the same `(name, mime)` pair.
    fn content_disposition(name: &str, mime: &str, params: &HashMap<String, String>) -> String {
        let force_inline = params
            .get("inline")
            .is_some_and(|v| v == "true" || v == "1");
        build_content_disposition(name, mime, force_inline)
    }

    /// Build a 201 Created JSON response.
    fn created_json_response(file: &crate::application::dtos::file_dto::FileDto) -> Response<Body> {
        Response::builder()
            .status(StatusCode::CREATED)
            .header(header::CONTENT_TYPE, "application/json")
            .header(header::CACHE_CONTROL, "no-cache, no-store, must-revalidate")
            .body(Body::from(serde_json::to_string(file).unwrap()))
            .unwrap()
    }

    /// Build error response for DomainError.
    fn domain_error_response(err: crate::common::errors::DomainError) -> Response<Body> {
        AppError::from(err).into_response()
    }

    /// Build a quota-specific error response with 507 status and structured body.
    fn quota_error_response(err: crate::common::errors::DomainError) -> Response<Body> {
        AppError::from(err).into_response()
    }

    /// Build response for cached/small files.
    ///
    /// Compression is handled uniformly by `CompressionLayer` (tower-http)
    /// which negotiates `Accept-Encoding` and applies gzip/brotli in streaming
    /// mode. No manual compression is done here to avoid double-encoding.
    fn build_cached_response(
        content: Bytes,
        mime_type: &str,
        disposition: &str,
        etag: &str,
    ) -> Response<Body> {
        Response::builder()
            .status(StatusCode::OK)
            .header(header::CONTENT_TYPE, mime_type)
            .header(header::CONTENT_DISPOSITION, disposition)
            .header(header::ETAG, etag)
            .header(
                header::CACHE_CONTROL,
                "private, max-age=3600, must-revalidate",
            )
            .header(header::VARY, "Accept-Encoding")
            .header(header::CONTENT_LENGTH, content.len())
            .body(Body::from(content))
            .unwrap()
    }
}

/// Payload for moving a file
#[derive(Debug, Deserialize, ToSchema)]
pub struct MoveFilePayload {
    /// Target folder ID (None means root)
    pub folder_id: Option<String>,
}

/// RFC 5987-compliant `Content-Disposition` with both ASCII fallback and
/// `filename*=UTF-8''...` for non-ASCII filenames.
pub(super) fn build_content_disposition(name: &str, mime: &str, force_inline: bool) -> String {
    let disposition = if force_inline
        || mime.starts_with("image/")
        || mime == "application/pdf"
        || mime.starts_with("video/")
        || mime.starts_with("audio/")
    {
        "inline"
    } else {
        "attachment"
    };

    use percent_encoding::{AsciiSet, NON_ALPHANUMERIC, utf8_percent_encode};
    // RFC 5987 attr-char safe set (no encoding needed for these).
    const RFC5987_SET: &AsciiSet = &NON_ALPHANUMERIC
        .remove(b'!')
        .remove(b'#')
        .remove(b'$')
        .remove(b'&')
        .remove(b'+')
        .remove(b'-')
        .remove(b'.')
        .remove(b'^')
        .remove(b'_')
        .remove(b'`')
        .remove(b'|')
        .remove(b'~');
    let encoded = utf8_percent_encode(name, RFC5987_SET).to_string();

    let ascii_safe: String = name
        .chars()
        .filter(|c| c.is_ascii_graphic() || *c == ' ')
        .map(|c| match c {
            '"' | '\\' => '_',
            _ => c,
        })
        .collect();

    format!("{disposition}; filename=\"{ascii_safe}\"; filename*=UTF-8''{encoded}")
}

// ── Route handlers (free functions) ──────────────────────────────────────────
//
// All annotated route functions live here rather than as methods on FileHandler
// because utoipa 5.4.0's #[utoipa::path] macro generates helper structs inside
// its expansion. Rust allows struct definitions at module scope but forbids them
// inside impl blocks — so every #[utoipa::path] annotation on a FileHandler
// method fails to compile regardless of HTTP verb or annotation content.
//
// All logic lives in the FileHandler::*_impl methods above; these thin wrappers
// exist solely to carry the OpenAPI annotation at a scope where utoipa can
// generate its helper types.
//
// routes.rs calls these free functions directly.
// TODO: collapse back into the impl block after a utoipa upgrade resolves the issue.

#[utoipa::path(
    get,
    path = "/api/files",
    params(("folder_id" = Option<String>, Query, description = "Filter by folder ID")),
    responses(
        (status = 200, description = "List of files", body = Vec<FileDto>),
        (status = 304, description = "Not modified"),
    ),
    tag = "files"
)]
pub async fn list_files_query(
    state: State<GlobalState>,
    auth_user: AuthUser,
    headers: HeaderMap,
    query: Query<HashMap<String, String>>,
) -> impl IntoResponse {
    FileHandler::list_files_query_impl(state, auth_user, headers, query).await
}

#[utoipa::path(
    post,
    path = "/api/files/upload",
    request_body(content_type = "multipart/form-data", description = "File data + optional folder_id field"),
    responses(
        (status = 201, description = "File uploaded", body = FileDto),
        (status = 400, description = "Invalid request"),
        (status = 507, description = "Storage quota exceeded"),
    ),
    tag = "files"
)]
pub async fn upload_file_with_thumbnails(
    state: State<GlobalState>,
    auth_user: AuthUser,
    multipart: Multipart,
) -> impl IntoResponse {
    FileHandler::upload_file_with_thumbnails_impl(state, auth_user, multipart).await
}

#[utoipa::path(
    get,
    path = "/api/files/{id}",
    params(
        ("id" = String, Path, description = "File ID"),
        ("metadata" = Option<bool>, Query, description = "Return metadata JSON instead of file content"),
        ("original" = Option<bool>, Query, description = "Skip WebP transcoding"),
        ("inline" = Option<bool>, Query, description = "Content-Disposition: inline"),
    ),
    responses(
        (status = 200, description = "File content"),
        (status = 206, description = "Partial content (Range request)"),
        (status = 304, description = "Not modified"),
        (status = 404, description = "File not found"),
    ),
    tag = "files"
)]
pub async fn download_file(
    state: State<GlobalState>,
    auth_user: AuthUser,
    path: Path<String>,
    query: Query<HashMap<String, String>>,
    headers: HeaderMap,
) -> impl IntoResponse {
    FileHandler::download_file_impl(state, auth_user, path, query, headers).await
}

#[utoipa::path(
    get,
    path = "/api/files/{id}/thumbnail/{size}",
    params(
        ("id" = String, Path, description = "File ID"),
        ("size" = String, Path, description = "Thumbnail size: icon | preview | large"),
    ),
    responses(
        (status = 200, description = "Thumbnail image (image/jpeg or image/webp)"),
        (status = 204, description = "No thumbnail available for this file type"),
        (status = 304, description = "Not modified"),
        (status = 404, description = "File not found"),
    ),
    tag = "files"
)]
pub async fn get_thumbnail(
    state: State<GlobalState>,
    auth_user: AuthUser,
    headers: HeaderMap,
    path: Path<(String, String)>,
) -> impl IntoResponse {
    FileHandler::get_thumbnail_impl(state, auth_user, headers, path).await
}

#[utoipa::path(
    put,
    path = "/api/files/{id}/thumbnail/{size}",
    params(
        ("id" = String, Path, description = "File ID"),
        ("size" = String, Path, description = "Thumbnail size: icon | preview | large"),
    ),
    request_body(content_type = "application/octet-stream", description = "Raw image bytes (max 512 KB)"),
    responses(
        (status = 201, description = "Thumbnail stored"),
        (status = 400, description = "Invalid image or size too large"),
        (status = 404, description = "File not found"),
    ),
    tag = "files"
)]
pub async fn upload_thumbnail(
    state: State<GlobalState>,
    auth_user: AuthUser,
    path: Path<(String, String)>,
    body: Bytes,
) -> impl IntoResponse {
    FileHandler::upload_thumbnail_impl(state, auth_user, path, body).await
}

#[utoipa::path(
    get,
    path = "/api/files/{id}/metadata",
    params(("id" = String, Path, description = "File ID")),
    responses(
        (status = 200, description = "File metadata (EXIF, dimensions, duration, etc.)"),
        (status = 404, description = "File not found"),
    ),
    tag = "files"
)]
pub async fn get_file_metadata(
    state: State<GlobalState>,
    auth_user: AuthUser,
    path: Path<String>,
) -> impl IntoResponse {
    FileHandler::get_file_metadata_impl(state, auth_user, path).await
}

#[utoipa::path(
    delete,
    path = "/api/files/{id}",
    params(("id" = String, Path, description = "File ID")),
    responses(
        (status = 204, description = "File deleted (moved to trash if enabled)"),
        (status = 404, description = "File not found"),
    ),
    tag = "files"
)]
pub async fn delete_file(
    state: State<GlobalState>,
    auth_user: AuthUser,
    path: Path<String>,
) -> impl IntoResponse {
    FileHandler::delete_file_impl(state, auth_user, path).await
}

#[utoipa::path(
    put,
    path = "/api/files/{id}/rename",
    params(("id" = String, Path, description = "File ID")),
    request_body(content_type = "application/json", description = r#"{"name": "new-name.txt"}"#),
    responses(
        (status = 200, description = "Renamed file", body = FileDto),
        (status = 404, description = "File not found"),
    ),
    tag = "files"
)]
pub async fn rename_file(
    state: State<GlobalState>,
    auth_user: AuthUser,
    path: Path<String>,
    json: Json<serde_json::Value>,
) -> impl IntoResponse {
    FileHandler::rename_file_impl(state, auth_user, path, json).await
}

#[utoipa::path(
    put,
    path = "/api/files/{id}/move",
    params(("id" = String, Path, description = "File ID")),
    request_body(content = MoveFilePayload, content_type = "application/json", description = "MoveFilePayload"),
    responses(
        (status = 200, description = "Moved file", body = FileDto),
        (status = 404, description = "File or destination not found"),
    ),
    tag = "files"
)]
pub async fn move_file_simple(
    state: State<GlobalState>,
    auth_user: AuthUser,
    path: Path<String>,
    json: Json<serde_json::Value>,
) -> impl IntoResponse {
    FileHandler::move_file_simple_impl(state, auth_user, path, json).await
}
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								use axum::{
 								    Json,
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								    body::Body,
 								    extract::{Multipart, Path, Query, State},
 								    http::{HeaderMap, Response, StatusCode, header},
 								    response::IntoResponse,
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								};
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								use bytes::Bytes;
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								use http_range_header::parse_range_header;
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								use serde::Deserialize;
-											adding several features
										
										
											2025-03-19 00:44:27 +01:00
+								use std::collections::HashMap;
-											feat: add OpenAPI spec generation with utoipa and justfile
										
										
											2026-03-29 18:49:10 +02:00
+								use utoipa::ToSchema;
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
-											fix: resolve all clippy warnings and convert integration_tests to custom cfg
										
										
											2026-03-04 23:55:08 +01:00
+								use crate::application::ports::file_ports::{
 								    FileManagementUseCase, FileRetrievalUseCase, FileUploadUseCase,
 								};
-											fix(thumbnails): resolve blob path instead of logical path for thumbnail generation
										
										
											2026-03-04 18:03:17 -05:00
+								use crate::application::ports::storage_ports::{FileReadPort, StorageUsagePort};
-											fix: resolve all clippy warnings and convert integration_tests to custom cfg
										
										
											2026-03-04 23:55:08 +01:00
+								use crate::application::ports::thumbnail_ports::ThumbnailPort;
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								use crate::application::ports::{file_ports::OptimizedFileContent, folder_ports::FolderUseCase};
-											fix trash and additional bugs
										
										
											2025-03-26 18:33:22 +01:00
+								use crate::common::di::AppState;
-											Music Player & Playlist Manager
										
										
											2026-04-08 15:14:03 +03:00
+								use crate::infrastructure::services::audio_metadata_service::AudioMetadataService;
-											security: fix vulnerabilities 1-7 from security audit
										
										
											2026-03-05 13:15:34 +01:00
+								use crate::interfaces::errors::AppError;
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								use crate::interfaces::middleware::auth::AuthUser;
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								use crate::{application::dtos::file_dto::FileDto, domain::services::authorization::Permission};
-											perf: Arc<AppState>, streaming PROPFIND, spawn_blocking SHA-256
										
										
											2026-02-24 15:11:56 +01:00
+								use std::sync::Arc;
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
-											adding features
										
										
											2025-03-26 19:08:07 +01:00
+								/**
 								 * Type aliases for dependency injection state.
 								 */
 								/// Global application state for dependency injection
-											perf: Arc<AppState>, streaming PROPFIND, spawn_blocking SHA-256
										
										
											2026-02-24 15:11:56 +01:00
+								type GlobalState = Arc<AppState>;
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
-											adding features
										
										
											2025-03-26 19:08:07 +01:00
+								/**
 								 * API handler for file-related operations.
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								 *
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								 * Acts as a thin HTTP adapter in the hexagonal architecture: it parses requests,
 								 * delegates business logic to application services, and maps results to HTTP
 								 * responses.  No infrastructure or strategy logic lives here.
-											adding features
										
										
											2025-03-26 19:08:07 +01:00
+								 */
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								pub struct FileHandler;
 								impl FileHandler {
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    // ── Why no #[utoipa::path] here? ─────────────────────────────────────────────
 								    // utoipa 5.4.0's proc macro generates helper structs / impls inside its expansion.
 								    // Rust allows struct definitions at module scope but forbids them inside impl blocks,
 								    // so `#[utoipa::path]` fails on every method in this impl block regardless of HTTP
 								    // verb or annotation content. All route handlers are free functions below.
 								    // TODO: collapse after utoipa upgrade.
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    // ═══════════════════════════════════════════════════════════════════════
 								    //  UPLOAD
 								    // ═══════════════════════════════════════════════════════════════════════
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								    /// Streaming file upload — constant ~64 KB RAM regardless of file size.
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								    ///
-											perf: replace SHA-256 with BLAKE3 + add mimalloc global allocator
										
										
											2026-03-01 21:47:39 +01:00
+								    /// **Hash-on-Write**: BLAKE3 is computed while spooling the multipart
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								    /// body to the temp file. This eliminates the second sequential read
 								    /// that dedup_service would otherwise need, cutting total I/O in half.
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								    pub async fn upload_file(
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        State(state): State<GlobalState>,
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								        auth_user: AuthUser,
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								        multipart: Multipart,
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								    ) -> impl IntoResponse {
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								        match Self::upload_file_inner(&state, &auth_user, multipart).await {
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								            Ok((file, _blob_hash)) => Self::created_json_response(&file).into_response(),
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								            Err(response) => response.into_response(),
 								        }
 								    }
 								    /// Core upload logic shared by [`Self::upload_file`] and
 								    /// [`Self::upload_file_with_thumbnails`].
 								    ///
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								    /// Returns `(FileDto, blob_hash)` on success.  The blob hash is the
 								    /// BLAKE3 digest computed during the hash-on-write spool and is
 								    /// propagated without an extra database round-trip so that callers
 								    /// (e.g. thumbnail generation) can resolve the physical blob path
 								    /// immediately.
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								    async fn upload_file_inner(
 								        state: &GlobalState,
 								        auth_user: &AuthUser,
 								        mut multipart: Multipart,
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								    ) -> Result<(crate::application::dtos::file_dto::FileDto, String), Response<Body>> {
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								        let upload_service = &state.applications.file_upload_service;
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        let mut folder_id: Option<String> = None;
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								        tracing::debug!("📤 Processing streaming file upload (hash-on-write)");
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								        // caveat: if folder_id field is given after check can fails
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								        while let Some(field) = multipart.next_field().await.unwrap_or(None) {
 								            let name = field.name().unwrap_or("").to_string();
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            if name == "folder_id" {
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								                let v = field.text().await.unwrap_or_default();
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                if !v.is_empty() {
 								                    folder_id = Some(v);
 								                }
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								                continue;
 								            }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								            if name == "file" {
-											fix(upload): sanitize multipart filename for folder uploads (#121)
										
										
											2026-02-16 17:58:50 +01:00
+								                let raw_filename = field.file_name().unwrap_or("unnamed").to_string();
 								                // Browsers send the full relative path (e.g. "Screenshots/file.png")
 								                // as the filename for folder uploads via webkitRelativePath.
 								                // Strip path components to get the basename only.
 								                // This also prevents path-traversal attacks.
 								                let filename = raw_filename
 								                    .rsplit('/')
 								                    .next()
 								                    .unwrap_or(&raw_filename)
 								                    .rsplit('\\')
 								                    .next()
 								                    .unwrap_or(&raw_filename)
 								                    .to_string();
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                let content_type = field
 								                    .content_type()
 								                    .unwrap_or("application/octet-stream")
 								                    .to_string();
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								                // ── Fail-fast pre-check: verify the caller can Create inside
 								                // the target folder BEFORE spooling the multipart body to disk.
 								                // The upload service re-checks at write time — this is a
 								                // UX/resource optimization, not the security boundary.
 								                if let Some(ref fid) = folder_id
 								                    && let Err(err) = state
 								                        .applications
 								                        .folder_service_concrete
-											refactor(authz): permet require_permission() as has_permission(), more explicit
										
										
											2026-05-21 21:50:42 +02:00
+								                        .require_permission(auth_user.id, Permission::Create, fid)
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								                        .await
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								                {
 								                    tracing::warn!(
 								                        "⛔ UPLOAD REJECTED: user='{}' folder='{}' err='{}'",
 								                        auth_user.username,
 								                        fid,
 								                        err
 								                    );
 								                    return Err(Self::domain_error_response(err));
-											fix: security audit — patch vulnerabilities V-02 through V-16
										
										
											2026-03-05 14:52:11 +01:00
+								                }
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                // ── Early quota check (before spooling to disk) ──────
 								                if let Some(storage_svc) = state.storage_usage_service.as_ref() {
 								                    let estimated_size = field
 								                        .headers()
 								                        .get(header::CONTENT_LENGTH)
 								                        .and_then(|v| v.to_str().ok())
 								                        .and_then(|s| s.parse::<u64>().ok())
 								                        .unwrap_or(0);
 								                    if let Err(err) = storage_svc
-											perf: migrate all user/session/auth IDs from VARCHAR(36) to native UUID
										
										
											2026-03-07 14:59:32 +01:00
+								                        .check_storage_quota(auth_user.id, estimated_size)
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                        .await
 								                    {
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                        tracing::warn!(
 								                            "⛔ UPLOAD REJECTED (early quota): user={}, file={}, est_size={}",
 								                            auth_user.username,
 								                            filename,
 								                            estimated_size
 								                        );
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								                        return Err(Self::quota_error_response(err));
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								                    }
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								                }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                // ── Spool multipart field to temp file + hash-on-write ──
-											perf: add socket2 TCP_NODELAY + socket tuning for low-latency responses
										
										
											2026-03-02 00:12:33 +01:00
+								                // .dedup_temp is created once by DedupService::initialize() at startup
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                let temp_dir = state.core.path_service.get_root_path().join(".dedup_temp");
 								                let temp_path = temp_dir.join(format!("upload-{}", uuid::Uuid::new_v4()));
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                let mut total_size: u64 = 0;
-											perf: replace SHA-256 with BLAKE3 + add mimalloc global allocator
										
										
											2026-03-01 21:47:39 +01:00
+								                let mut hasher = blake3::Hasher::new();
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                let spool_result: Result<(), String> = async {
 								                    let file = tokio::fs::File::create(&temp_path)
 								                        .await
 								                        .map_err(|e| format!("Failed to create temp file: {}", e))?;
 								                    // Pre-allocate if Content-Length is known (reduces fragmentation)
 								                    let hint = field
 								                        .headers()
 								                        .get(axum::http::header::CONTENT_LENGTH)
 								                        .and_then(|v| v.to_str().ok())
 								                        .and_then(|s| s.parse::<u64>().ok());
 								                    if let Some(len) = hint {
-											style: fix clippy collapsible_if + cargo fmt
										
										
											2026-02-15 18:04:32 +01:00
+								                        let _ = file.set_len(len).await; // best-effort
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                    }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                    // 512 KB buffer — 8× fewer write syscalls than 64 KB
 								                    let mut writer = tokio::io::BufWriter::with_capacity(524_288, file);
 								                    let mut field = field;
-											quick fix
										
										
											2026-03-06 13:18:36 +01:00
+								                    // IMPORTANT: use explicit match instead of `while let Ok(Some(..))`.
 								                    // The old pattern silently swallowed Err (client disconnect)
 								                    // and accepted partially received data as a complete upload.
 								                    loop {
 								                        match field.chunk().await {
 								                            Ok(Some(chunk)) => {
 								                                total_size += chunk.len() as u64;
 								                                hasher.update(&chunk);
 								                                tokio::io::AsyncWriteExt::write_all(&mut writer, &chunk)
 								                                    .await
 								                                    .map_err(|e| format!("Failed to write chunk: {}", e))?;
 								                            }
 								                            Ok(None) => break, // End of field — upload complete
 								                            Err(e) => {
 								                                return Err(format!(
 								                                    "Connection lost during upload (received {} bytes): {}",
 								                                    total_size, e
 								                                ));
 								                            }
 								                        }
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                    }
 								                    tokio::io::AsyncWriteExt::flush(&mut writer)
 								                        .await
 								                        .map_err(|e| format!("Failed to flush temp file: {}", e))?;
 								                    Ok(())
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                }
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                .await;
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                if let Err(e) = spool_result {
 								                    let _ = tokio::fs::remove_file(&temp_path).await;
 								                    tracing::error!("❌ UPLOAD SPOOL FAILED: {} - {}", filename, e);
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								                    return Err(Self::domain_error_response(
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                        crate::common::errors::DomainError::internal_error("FileUpload", e),
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								                    ));
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								                }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: eliminate Vec<u8> buffer paths — all uploads now stream to disk
										
										
											2026-02-25 23:41:16 +01:00
+								                // Empty file — use streaming path with the (empty) temp file
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                if total_size == 0 {
-											perf: replace SHA-256 with BLAKE3 + add mimalloc global allocator
										
										
											2026-03-01 21:47:39 +01:00
+								                    let hash = hasher.finalize().to_hex().to_string();
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								                    let dto = upload_service
-											perf: eliminate Vec<u8> buffer paths — all uploads now stream to disk
										
										
											2026-02-25 23:41:16 +01:00
+								                        .upload_file_streaming(
 								                            filename,
 								                            folder_id,
 								                            content_type,
 								                            &temp_path,
 ,
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								                            Some(hash.clone()),
-											perf: eliminate Vec<u8> buffer paths — all uploads now stream to disk
										
										
											2026-02-25 23:41:16 +01:00
+								                        )
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                        .await
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								                        .map_err(Self::domain_error_response)?;
 								                    return Ok((dto, hash));
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								                }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                // Finalize hash
-											perf: replace SHA-256 with BLAKE3 + add mimalloc global allocator
										
										
											2026-03-01 21:47:39 +01:00
+								                let hash = hasher.finalize().to_hex().to_string();
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
-											feat: P1 — audio/video modal player + MIME detection via magic bytes (infer)
										
										
											2026-02-24 23:15:10 +01:00
+								                // ── MIME detection (magic bytes + extension fallback) ─
 								                let content_type = crate::common::mime_detect::refine_content_type_from_file(
 								                    &temp_path,
 								                    &filename,
 								                    &content_type,
 								                )
 								                .await;
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                // ── Quota enforcement ────────────────────────────────
 								                if let Some(storage_svc) = state.storage_usage_service.as_ref()
 								                    && let Err(err) = storage_svc
-											perf: migrate all user/session/auth IDs from VARCHAR(36) to native UUID
										
										
											2026-03-07 14:59:32 +01:00
+								                        .check_storage_quota(auth_user.id, total_size)
-											fix(#104): enforce storage quota on uploads & fix usage tracking
										
										
											2026-02-14 10:34:07 +01:00
+								                        .await
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                {
-											style: fix clippy collapsible_if + cargo fmt
										
										
											2026-02-15 18:04:32 +01:00
+								                    let _ = tokio::fs::remove_file(&temp_path).await;
 								                    tracing::warn!(
 								                        "⛔ UPLOAD REJECTED (quota): user={}, file={}, size={}",
 								                        auth_user.username,
 								                        filename,
 								                        total_size
 								                    );
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								                    return Err(Self::quota_error_response(err));
-											style: fix clippy collapsible_if + cargo fmt
										
										
											2026-02-15 18:04:32 +01:00
+								                }
-											fix(#104): enforce storage quota on uploads & fix usage tracking
										
										
											2026-02-14 10:34:07 +01:00
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                // ── Streaming upload (temp file → blob store, hash pre-computed) ─
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								                match upload_service
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                    .upload_file_streaming(
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                        filename.clone(),
 								                        folder_id,
 								                        content_type,
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                        &temp_path,
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                        total_size,
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								                        Some(hash.clone()),
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                    )
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								                    .await
 								                {
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                    Ok(file) => {
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								                        tracing::info!(
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                            "✅ STREAMING UPLOAD: {} ({} bytes, ID: {})",
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                            filename,
 								                            total_size,
 								                            file.id
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								                        );
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								                        return Ok((file, hash));
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								                    }
 								                    Err(err) => {
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								                        let _ = tokio::fs::remove_file(&temp_path).await;
 								                        tracing::error!("❌ UPLOAD FAILED: {} - {}", filename, err);
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								                        return Err(Self::domain_error_response(err));
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								                    }
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								                }
 								            }
 								        }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								        Err((
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								            StatusCode::BAD_REQUEST,
 								            Json(serde_json::json!({
 								                "error": "No file provided"
 								            })),
 								        )
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								            .into_response())
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								    }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    // ═══════════════════════════════════════════════════════════════════════
 								    //  THUMBNAILS
 								    // ═══════════════════════════════════════════════════════════════════════
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								    /// Get a thumbnail for a file (image or video).
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    ///
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								    /// **Cache-first**: if the thumbnail already exists in the moka in-memory
 								    /// cache or on disk, serve it immediately — **zero DB queries**.  The
 								    /// ownership check was already performed when the thumbnail was first
 								    /// generated (at upload) or uploaded (PUT by the owner).  UUIDv4 file IDs
 								    /// have 122 bits of entropy, making enumeration infeasible.
 								    ///
 								    /// **ETag / 304**: responses carry an immutable ETag.  If the browser
 								    /// sends `If-None-Match` matching the ETag, we return 304 Not Modified
 								    /// without touching cache or DB — pure header round-trip.
 								    ///
 								    /// The DB path is only taken on a **cache miss for images** where the
 								    /// thumbnail hasn't been generated yet (first access after upload if
 								    /// background generation hasn't finished).
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    pub(super) async fn get_thumbnail_impl(
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        State(state): State<GlobalState>,
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        auth_user: AuthUser,
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								        headers: HeaderMap,
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        Path((id, size)): Path<(String, String)>,
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								    ) -> impl IntoResponse {
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        use crate::application::ports::thumbnail_ports::ThumbnailSize;
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								        // check first that user can access this resource
 								        if let Err(err) = state
 								            .applications
 								            .file_management_service
-											refactor(authz): permet require_permission() as has_permission(), more explicit
										
										
											2026-05-21 21:50:42 +02:00
+								            .require_permission(auth_user.id, Permission::Read, &id)
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								            .await
 								        {
 								            return AppError::from(err).into_response();
 								        }
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        let thumbnail_service = &state.core.thumbnail_service;
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        let thumb_size = match size.as_str() {
 								            "icon" => ThumbnailSize::Icon,
 								            "preview" => ThumbnailSize::Preview,
 								            "large" => ThumbnailSize::Large,
 								            _ => {
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                return (
 								                    StatusCode::BAD_REQUEST,
 								                    Json(serde_json::json!({
 								                        "error": "Invalid thumbnail size. Use: icon, preview, or large"
 								                    })),
 								                )
 								                    .into_response();
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            }
-											adding several features
										
										
											2025-03-19 00:44:27 +01:00
+								        };
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								        // ── ETag short-circuit (Solution C) ──────────────────────────
 								        // Thumbnails are immutable — the ETag never changes for a given
 								        // (file_id, size) pair.  If the browser already has it, return 304
 								        // with zero I/O or DB work.
 								        let etag = format!("\"thumb-{}-{:?}\"", id, thumb_size);
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								        if let Some(if_none_match) = headers.get(header::IF_NONE_MATCH)
 								            && let Ok(val) = if_none_match.to_str()
 								            && (val == etag || val == "*")
 								        {
 								            return Response::builder()
 								                .status(StatusCode::NOT_MODIFIED)
 								                .header(header::ETAG, &etag)
 								                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
 								                .body(Body::empty())
 								                .unwrap()
 								                .into_response();
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								        }
 								        // ── Cache-first path (Solution A) ────────────────────────────
 								        // Try moka (RAM) → disk before touching the database.
 								        // If the thumbnail exists it was authorized at creation time.
 								        if let Some(data) = thumbnail_service
-											feat: thumbnail dedup — store thumbnails by blob_hash instead of file_id (#233)
										
										
											2026-04-12 00:50:10 +02:00
+								            .get_cached_thumbnail(&id, None, thumb_size.into())
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								            .await
 								        {
 								            return Response::builder()
 								                .status(StatusCode::OK)
-											perf(thumbs): switch thumbnail encoding from WebP to JPEG q=80
										
										
											2026-03-07 20:37:19 +01:00
+								                .header(header::CONTENT_TYPE, "image/jpeg")
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								                .header(header::CONTENT_LENGTH, data.len())
 								                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
 								                .header(header::ETAG, &etag)
 								                .body(Body::from(data))
 								                .unwrap()
 								                .into_response();
 								        }
 								        // ── Cache miss — need DB for ownership + blob resolution ─────
 								        let file_retrieval_service = &state.applications.file_retrieval_service;
-											fix: resolve all clippy warnings and convert integration_tests to custom cfg
										
										
											2026-03-04 23:55:08 +01:00
+								        let file = match file_retrieval_service
-											feat(ui/trash): show original file path in tooltip on mouse over + display thumbnails
										
										
											2026-05-22 00:38:44 +02:00
+								            .get_file_or_trashed_with_perms(&id, auth_user.id)
-											fix: resolve all clippy warnings and convert integration_tests to custom cfg
										
										
											2026-03-04 23:55:08 +01:00
+								            .await
 								        {
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            Ok(f) => f,
 								            Err(err) => {
-											security: fix vulnerabilities 1-7 from security audit
										
										
											2026-03-05 13:15:34 +01:00
+								                return AppError::from(err).into_response();
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            }
 								        };
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf(thumbnails): cache-first + ETag 304 eliminates DB queries on GET
										
										
											2026-03-07 19:48:35 +01:00
+								        // Non-image (video, etc.) with no cached thumbnail → 204
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        if !thumbnail_service.is_supported_image(&file.mime_type) {
-											fix: instant video thumbnails on tab switch + throttle decodes
										
										
											2026-03-07 19:06:37 +01:00
+								            return Response::builder()
 								                .status(StatusCode::NO_CONTENT)
 								                .header(header::CACHE_CONTROL, "no-store")
 								                .body(Body::empty())
 								                .unwrap()
 								                .into_response();
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											Fix thumbnail generation for CDC blob storage
										
										
											2026-04-26 11:55:05 +02:00
+								        // Resolve the blob hash (content-addressable storage).
-											style: apply rustfmt formatting to fix CI
										
										
											2026-03-05 21:28:51 +01:00
+								        let blob_hash = match state
 								            .repositories
 								            .file_read_repository
 								            .get_blob_hash(&id)
 								            .await
 								        {
-											quick fix
										
										
											2026-03-06 13:18:36 +01:00
+								            Ok(hash) => hash,
 								            Err(_) => {
 								                return AppError::internal_error("File blob not found").into_response();
-											fix(thumbnails): resolve blob path instead of logical path for thumbnail generation
										
										
											2026-03-04 18:03:17 -05:00
+								            }
 								        };
-											Fix thumbnail generation for CDC blob storage
										
										
											2026-04-26 11:55:05 +02:00
+								        if let Some(data) = thumbnail_service
 								            .get_cached_thumbnail(&id, Some(&blob_hash), thumb_size.into())
 								            .await
 								        {
 								            return Response::builder()
 								                .status(StatusCode::OK)
 								                .header(header::CONTENT_TYPE, "image/jpeg")
 								                .header(header::CONTENT_LENGTH, data.len())
 								                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
 								                .header(header::ETAG, &etag)
 								                .body(Body::from(data))
 								                .unwrap()
 								                .into_response();
 								        }
 								        let original_bytes = match state.core.dedup_service.read_blob_bytes(&blob_hash).await {
 								            Ok(bytes) => bytes,
 								            Err(err) => {
 								                return AppError::internal_error(format!(
 								                    "Failed to load source image for thumbnail generation: {}",
 								                    err
 								                ))
 								                .into_response();
 								            }
 								        };
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								        match thumbnail_service
-											Fix thumbnail generation for CDC blob storage
										
										
											2026-04-26 11:55:05 +02:00
+								            .get_thumbnail_from_bytes(&id, &blob_hash, thumb_size.into(), original_bytes)
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								            .await
 								        {
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Ok(data) => Response::builder()
 								                .status(StatusCode::OK)
 								                .header(header::CONTENT_TYPE, "image/jpeg")
 								                .header(header::CONTENT_LENGTH, data.len())
 								                .header(header::CACHE_CONTROL, "public, max-age=31536000, immutable")
 								                .header(header::ETAG, &etag)
 								                .body(Body::from(data))
 								                .unwrap()
 								                .into_response(),
 								            Err(err) => AppError::internal_error(format!("Thumbnail generation failed: {}", err))
 								                .into_response(),
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        }
 								    }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											feat: client-side video thumbnail generation (no ffmpeg)
										
										
											2026-03-07 18:55:44 +01:00
+								    // ═══════════════════════════════════════════════════════════════════════
 								    //  UPLOAD THUMBNAIL (client-generated, e.g. video frames)
 								    // ═══════════════════════════════════════════════════════════════════════
 								    /// Accept a client-generated thumbnail (e.g. video frame extracted via
 								    /// `<video>` + `<canvas>` in the browser) and persist it in the server
 								    /// cache.  The image is validated, re-encoded to WebP, and stored so
 								    /// subsequent `GET …/thumbnail/{size}` requests are served instantly.
 								    ///
 								    /// **Max body: 512 KB** — thumbnails are small.
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    pub(super) async fn upload_thumbnail_impl(
-											feat: client-side video thumbnail generation (no ffmpeg)
										
										
											2026-03-07 18:55:44 +01:00
+								        State(state): State<GlobalState>,
 								        auth_user: AuthUser,
 								        Path((id, size)): Path<(String, String)>,
 								        body: Bytes,
 								    ) -> impl IntoResponse {
 								        use crate::application::ports::thumbnail_ports::ThumbnailSize;
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								        // check first that user can access this resource
 								        if let Err(err) = state
 								            .applications
 								            .file_management_service
-											refactor(authz): permet require_permission() as has_permission(), more explicit
										
										
											2026-05-21 21:50:42 +02:00
+								            .require_permission(auth_user.id, Permission::Update, &id)
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								            .await
 								        {
 								            return AppError::from(err).into_response();
 								        }
-											feat: client-side video thumbnail generation (no ffmpeg)
										
										
											2026-03-07 18:55:44 +01:00
+								        let thumbnail_service = &state.core.thumbnail_service;
 								        // Validate size
 								        let thumb_size = match size.as_str() {
 								            "icon" => ThumbnailSize::Icon,
 								            "preview" => ThumbnailSize::Preview,
 								            "large" => ThumbnailSize::Large,
 								            _ => {
 								                return (
 								                    StatusCode::BAD_REQUEST,
 								                    Json(serde_json::json!({
 								                        "error": "Invalid thumbnail size. Use: icon, preview, or large"
 								                    })),
 								                )
 								                    .into_response();
 								            }
 								        };
 								        // Reject oversized payloads (512 KB)
 								        if body.len() > 512 * 1024 {
 								            return (
 								                StatusCode::PAYLOAD_TOO_LARGE,
 								                Json(serde_json::json!({ "error": "Thumbnail exceeds 512 KB limit" })),
 								            )
 								                .into_response();
 								        }
 								        // Validate file ownership
 								        let file_retrieval_service = &state.applications.file_retrieval_service;
 								        if let Err(err) = file_retrieval_service
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								            .get_file_with_perms(&id, auth_user.id)
-											feat: client-side video thumbnail generation (no ffmpeg)
										
										
											2026-03-07 18:55:44 +01:00
+								            .await
 								        {
 								            return AppError::from(err).into_response();
 								        }
 								        // Validate, re-encode to WebP, and store
 								        match thumbnail_service
 								            .store_external_thumbnail(&id, thumb_size.into(), body)
 								            .await
 								        {
 								            Ok(_) => StatusCode::CREATED.into_response(),
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Err(err) => AppError::internal_error(format!("Failed to store thumbnail: {}", err))
 								                .into_response(),
-											feat: client-side video thumbnail generation (no ffmpeg)
										
										
											2026-03-07 18:55:44 +01:00
+								        }
 								    }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    // ═══════════════════════════════════════════════════════════════════════
 								    //  DOWNLOAD
 								    // ═══════════════════════════════════════════════════════════════════════
 								    /// Downloads a file with optimized multi-tier strategy.
 								    ///
 								    /// The tier selection (write-behind → hot cache → WebP transcode → mmap →
 								    /// streaming) is fully handled by `FileRetrievalUseCase::get_file_optimized`.
 								    /// This handler only deals with HTTP concerns: ETag, Range, Content-Disposition,
 								    /// and optional compression.
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    pub(super) async fn download_file_impl(
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        State(state): State<GlobalState>,
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        auth_user: AuthUser,
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        Path(id): Path<String>,
 								        Query(params): Query<HashMap<String, String>>,
 								        headers: HeaderMap,
 								    ) -> impl IntoResponse {
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        let retrieval = &state.applications.file_retrieval_service;
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        // ── Get file metadata (ownership-scoped) ────────────────────────
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								        let file_dto = match retrieval.get_file_with_perms(&id, auth_user.id).await {
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            Ok(f) => f,
 								            Err(err) => {
-											security: fix vulnerabilities 1-7 from security audit
										
										
											2026-03-05 13:15:34 +01:00
+								                return AppError::from(err).into_response();
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            }
 								        };
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											feat: fix favorites display and add star indicator on favorited items
										
										
											2026-02-13 09:32:16 +01:00
+								        // ── Metadata-only request ────────────────────────────────────
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								        if params
 								            .get("metadata")
 								            .is_some_and(|v| v == "true" || v == "1")
 								        {
 								            return (
 								                StatusCode::OK,
 								                Json(serde_json::json!({
 								                    "id": file_dto.id,
 								                    "name": file_dto.name,
 								                    "path": file_dto.path,
 								                    "size": file_dto.size,
 								                    "mime_type": file_dto.mime_type,
 								                    "folder_id": file_dto.folder_id,
 								                    "created_at": file_dto.created_at,
 								                    "modified_at": file_dto.modified_at
 								                })),
 								            )
 								                .into_response();
-											feat: fix favorites display and add star indicator on favorited items
										
										
											2026-02-13 09:32:16 +01:00
+								        }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        let etag = format!("\"{}-{}\"", id, file_dto.modified_at);
 								        // ── ETag (304 Not Modified) ──────────────────────────────────
-											refactor: apply clippy auto-fixes (162 warnings resolved)
										
										
											2026-02-14 01:26:02 +01:00
+								        if let Some(inm) = headers.get(header::IF_NONE_MATCH)
 								            && let Ok(client_etag) = inm.to_str()
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								            && (client_etag == etag || client_etag == "*")
 								        {
 								            return Response::builder()
 								                .status(StatusCode::NOT_MODIFIED)
 								                .header(header::ETAG, &etag)
 								                .body(Body::empty())
 								                .unwrap()
 								                .into_response();
 								        }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
 								        // ── Range Requests ───────────────────────────────────────────
-											refactor: apply clippy auto-fixes (162 warnings resolved)
										
										
											2026-02-14 01:26:02 +01:00
+								        if let Some(range_header) = headers.get(header::RANGE)
 								            && let Ok(range_str) = range_header.to_str()
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								            && let Ok(ranges) = parse_range_header(range_str)
 								        {
 								            let validated = ranges.validate(file_dto.size);
 								            if let Ok(valid_ranges) = validated {
 								                if let Some(range) = valid_ranges.first() {
 								                    let start = *range.start();
 								                    let end = *range.end();
 								                    let range_length = end - start + 1;
 								                    let disposition =
 								                        Self::content_disposition(&file_dto.name, &file_dto.mime_type, &params);
 								                    match retrieval
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								                        .get_file_range_stream_with_perms(&id, auth_user.id, start, Some(end + 1))
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                        .await
 								                    {
 								                        Ok(stream) => {
 								                            return Response::builder()
 								                                .status(StatusCode::PARTIAL_CONTENT)
-											perf: use Arc<str> for repetitive DTO fields to eliminate clone allocations
										
										
											2026-03-03 15:55:15 +00:00
+								                                .header(header::CONTENT_TYPE, &*file_dto.mime_type)
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                                .header(header::CONTENT_DISPOSITION, &disposition)
 								                                .header(header::CONTENT_LENGTH, range_length)
 								                                .header(
 								                                    header::CONTENT_RANGE,
 								                                    format!("bytes {}-{}/{}", start, end, file_dto.size),
 								                                )
 								                                .header(header::ACCEPT_RANGES, "bytes")
 								                                .header(header::ETAG, &etag)
 								                                .header(
 								                                    header::CACHE_CONTROL,
 								                                    "private, max-age=3600, must-revalidate",
 								                                )
 								                                .body(Body::from_stream(Box::into_pin(stream)))
 								                                .unwrap()
 								                                .into_response();
 								                        }
 								                        Err(err) => {
 								                            tracing::error!("Error creating range stream: {}", err);
 								                            // fall through to normal download
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								                        }
 								                    }
 								                }
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								            } else {
 								                return Response::builder()
 								                    .status(StatusCode::RANGE_NOT_SATISFIABLE)
 								                    .header(header::CONTENT_RANGE, format!("bytes */{}", file_dto.size))
 								                    .body(Body::empty())
 								                    .unwrap()
 								                    .into_response();
 								            }
 								        }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
 								        // ── Normal download (delegated to service) ───────────────────
 								        let disposition = Self::content_disposition(&file_dto.name, &file_dto.mime_type, &params);
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								        let accept_webp = headers
 								            .get(header::ACCEPT)
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								            .and_then(|v| v.to_str().ok())
-											refactor: apply clippy auto-fixes (162 warnings resolved)
										
										
											2026-02-14 01:26:02 +01:00
+								            .is_some_and(|a| a.contains("image/webp"));
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								        let prefer_original = params
 								            .get("original")
 								            .is_some_and(|v| v == "true" || v == "1");
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        // Use the ownership-scoped optimized download.
 								        // Ownership was already verified by get_file_owned above,
 								        // so we can safely use the preloaded variant.
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								        match retrieval
-											perf: Phase 4+5 optimizations — uploads 10x, downloads 2x, concurrent 2x. moka cache, 512KB buffers, remove sync_all, hash-on-write, preloaded queries, bench.sh v3, gitignore storage/. 500MB upload 12.6s->1.3s (392MB/s). RSS 69-113MB, 0 swap.
										
										
											2026-02-15 17:53:25 +01:00
+								            .get_file_optimized_preloaded(&id, file_dto.clone(), accept_webp, prefer_original)
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								            .await
 								        {
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								            Ok((_file, content)) => match content {
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                OptimizedFileContent::Bytes {
 								                    data, mime_type, ..
-											fix: resolve all clippy warnings and enforce cargo fmt
										
										
											2026-02-25 10:28:34 +01:00
+								                } => Self::build_cached_response(data, &mime_type, &disposition, &etag)
 								                    .into_response(),
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                OptimizedFileContent::Mmap(mmap_data) => Response::builder()
 								                    .status(StatusCode::OK)
-											perf: use Arc<str> for repetitive DTO fields to eliminate clone allocations
										
										
											2026-03-03 15:55:15 +00:00
+								                    .header(header::CONTENT_TYPE, &*file_dto.mime_type)
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                    .header(header::CONTENT_DISPOSITION, &disposition)
 								                    .header(header::CONTENT_LENGTH, mmap_data.len())
 								                    .header(header::ETAG, &etag)
 								                    .header(
 								                        header::CACHE_CONTROL,
 								                        "private, max-age=3600, must-revalidate",
 								                    )
 								                    .header(header::ACCEPT_RANGES, "bytes")
 								                    .body(Body::from(mmap_data))
 								                    .unwrap()
 								                    .into_response(),
 								                OptimizedFileContent::Stream(pinned_stream) => Response::builder()
 								                    .status(StatusCode::OK)
-											perf: use Arc<str> for repetitive DTO fields to eliminate clone allocations
										
										
											2026-03-03 15:55:15 +00:00
+								                    .header(header::CONTENT_TYPE, &*file_dto.mime_type)
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                    .header(header::CONTENT_DISPOSITION, &disposition)
 								                    .header(header::CONTENT_LENGTH, file_dto.size)
 								                    .header(header::ETAG, &etag)
 								                    .header(
 								                        header::CACHE_CONTROL,
 								                        "private, max-age=3600, must-revalidate",
 								                    )
 								                    .header(header::ACCEPT_RANGES, "bytes")
 								                    .body(Body::from_stream(pinned_stream))
 								                    .unwrap()
 								                    .into_response(),
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								            },
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Err(err) => AppError::from(err).into_response(),
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        }
 								    }
 								    // ═══════════════════════════════════════════════════════════════════════
 								    //  LIST
 								    // ═══════════════════════════════════════════════════════════════════════
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    /// Lists files in a folder, extracting `folder_id` from query parameters.
 								    pub(super) async fn list_files_query_impl(
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        State(state): State<GlobalState>,
-											security: fix vulnerabilities 1-7 from security audit
										
										
											2026-03-05 13:15:34 +01:00
+								        auth_user: AuthUser,
-											perf: remove HTTP cache middleware, add service-level ETags
										
										
											2026-02-24 09:52:22 +01:00
+								        headers: HeaderMap,
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        Query(params): Query<HashMap<String, String>>,
 								    ) -> impl IntoResponse {
 								        let folder_id = params.get("folder_id").map(|id| id.as_str());
 								        tracing::info!("API: Listing files with folder_id: {:?}", folder_id);
 								        let retrieval = &state.applications.file_retrieval_service;
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								        match retrieval
 								            .list_files_with_perms(folder_id, auth_user.id)
 								            .await
 								        {
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								            Ok(files) => {
-											perf: remove HTTP cache middleware, add service-level ETags
										
										
											2026-02-24 09:52:22 +01:00
+								                // Compute lightweight ETag from max modified_at + count
 								                let max_mod = files.iter().map(|f| f.modified_at).max().unwrap_or(0);
 								                let count = files.len();
 								                let mut hasher = std::collections::hash_map::DefaultHasher::new();
 								                std::hash::Hash::hash(&max_mod, &mut hasher);
 								                std::hash::Hash::hash(&count, &mut hasher);
 								                let etag = format!("\"{:x}\"", std::hash::Hasher::finish(&hasher));
 								                // 304 Not Modified if client already has this version
 								                if let Some(inm) = headers.get(header::IF_NONE_MATCH)
 								                    && let Ok(client_etag) = inm.to_str()
 								                    && client_etag == etag
 								                {
 								                    return Response::builder()
 								                        .status(StatusCode::NOT_MODIFIED)
 								                        .header(header::ETAG, &etag)
 								                        .body(Body::empty())
 								                        .unwrap()
 								                        .into_response();
 								                }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								                tracing::info!("Found {} files", files.len());
-											perf: remove HTTP cache middleware, add service-level ETags
										
										
											2026-02-24 09:52:22 +01:00
+								                let mut resp = (StatusCode::OK, Json(files)).into_response();
-											fix: resolve all clippy warnings and enforce cargo fmt
										
										
											2026-02-25 10:28:34 +01:00
+								                resp.headers_mut()
 								                    .insert(header::ETAG, header::HeaderValue::from_str(&etag).unwrap());
-											perf: remove HTTP cache middleware, add service-level ETags
										
										
											2026-02-24 09:52:22 +01:00
+								                resp
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								            }
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Err(err) => AppError::from(err).into_response(),
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        }
 								    }
 								    /// Uploads a file and generates thumbnails in the background for images.
 								    ///
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								    /// Delegates to [`Self::upload_file_inner`] and, on success, spawns
 								    /// a background task to generate all thumbnail sizes before serialising
 								    /// the `FileDto` once.
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								    /// TODO: should move thumbnail generation to a generic hook ? (onfileUploaded, other services will beneficiate it)
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    pub(super) async fn upload_file_with_thumbnails_impl(
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        State(state): State<GlobalState>,
-											fix(#104): enforce storage quota on uploads & fix usage tracking
										
										
											2026-02-14 10:34:07 +01:00
+								        auth_user: AuthUser,
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        multipart: Multipart,
 								    ) -> impl IntoResponse {
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								        let (file, blob_hash) = match Self::upload_file_inner(&state, &auth_user, multipart).await {
 								            Ok(pair) => pair,
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								            Err(response) => return response.into_response(),
 								        };
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								        // Generate thumbnails for supported images in background.
 								        // The blob_hash was already computed during the hash-on-write spool,
-											Fix thumbnail generation for CDC blob storage
										
										
											2026-04-26 11:55:05 +02:00
+								        // so we can reconstruct the source bytes directly from DedupService
 								        // without an extra DB round-trip.
-											fix: resolve all clippy warnings and enforce cargo fmt
										
										
											2026-02-25 10:28:34 +01:00
+								        if state
 								            .core
 								            .thumbnail_service
 								            .is_supported_image(&file.mime_type)
 								        {
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								            let file_id = file.id.clone();
 								            let thumbnail_service = state.core.thumbnail_service.clone();
-											Fix thumbnail generation for CDC blob storage
										
										
											2026-04-26 11:55:05 +02:00
+								            let dedup_service = state.core.dedup_service.clone();
-											feat: thumbnail dedup — store thumbnails by blob_hash instead of file_id (#233)
										
										
											2026-04-12 00:50:10 +02:00
+								            let blob_hash_owned = blob_hash.clone();
-											feat(photos): add EXIF metadata extraction and storage
										
										
											2026-03-05 12:48:47 -05:00
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								            tokio::spawn(async move {
 								                tracing::info!("🖼️ Generating thumbnails for: {}", file_id);
-											Fix thumbnail generation for CDC blob storage
										
										
											2026-04-26 11:55:05 +02:00
+								                match dedup_service.read_blob_bytes(&blob_hash_owned).await {
 								                    Ok(original_bytes) => {
 								                        thumbnail_service.generate_all_sizes_background_from_bytes(
 								                            file_id,
 								                            blob_hash_owned,
 								                            original_bytes,
-											feat: check thumbnail cleanup on files deletion + correct ref counter
										
										
											2026-05-13 11:33:45 +02:00
+								                            dedup_service.clone(),
-											Fix thumbnail generation for CDC blob storage
										
										
											2026-04-26 11:55:05 +02:00
+								                        );
 								                    }
 								                    Err(err) => {
 								                        tracing::warn!(
 								                            "Failed to load source image for thumbnail generation {}: {}",
 								                            file_id,
 								                            err
 								                        );
 								                    }
 								                }
-											perf: eliminate redundant PG round-trip for blob_hash after image upload
										
										
											2026-03-07 00:10:56 +01:00
+								            });
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								        }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								        // TODO: same remark: a hook to handle easily audio service
-											Music Player & Playlist Manager
										
										
											2026-04-08 15:14:03 +03:00
+								        // Extract audio metadata for supported audio files in background.
 								        if let Some(ref audio_service) = state.applications.audio_metadata_service
 								            && AudioMetadataService::is_audio_file(&file.mime_type)
 								            && let Ok(file_id) = uuid::Uuid::parse_str(&file.id)
 								        {
 								            let file_path = state.core.dedup_service.blob_path(&blob_hash);
 								            AudioMetadataService::spawn_extraction_background(
 								                audio_service.clone(),
 								                file_id,
 								                file_path,
 								            );
 								        }
-											optimize folder search: SQL-level filtering, user isolation, no in-memory filter; batch cascade trigger
										
										
											2026-02-24 17:15:36 +01:00
+								        Self::created_json_response(&file).into_response()
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    }
-											feat(photos): add EXIF metadata extraction and storage
										
										
											2026-03-05 12:48:47 -05:00
+								    // ═══════════════════════════════════════════════════════════════════════
 								    //  METADATA
 								    // ═══════════════════════════════════════════════════════════════════════
 								    /// Returns EXIF/media metadata for a file.
 								    ///
 								    /// Used by the Photos lightbox and for testing EXIF extraction.
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    pub(super) async fn get_file_metadata_impl(
-											feat(photos): add EXIF metadata extraction and storage
										
										
											2026-03-05 12:48:47 -05:00
+								        State(state): State<GlobalState>,
 								        auth_user: AuthUser,
 								        Path(file_id): Path<String>,
 								    ) -> impl IntoResponse {
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								        // check first that user can access this resource
 								        if let Err(err) = state
 								            .applications
 								            .file_management_service
-											refactor(authz): permet require_permission() as has_permission(), more explicit
										
										
											2026-05-21 21:50:42 +02:00
+								            .require_permission(auth_user.id, Permission::Read, &file_id)
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								            .await
 								        {
 								            return AppError::from(err).into_response();
-											feat(photos): add EXIF metadata extraction and storage
										
										
											2026-03-05 12:48:47 -05:00
+								        }
 								        let metadata_repo = &state.repositories.file_metadata_repository;
 								        match metadata_repo.get(&file_id).await {
 								            Ok(Some(meta)) => (StatusCode::OK, Json(meta)).into_response(),
 								            Ok(None) => (
 								                StatusCode::OK,
 								                Json(serde_json::json!({
 								                    "file_id": file_id,
 								                    "message": "No EXIF metadata available"
 								                })),
 								            )
 								                .into_response(),
 								            Err(e) => (
 								                StatusCode::INTERNAL_SERVER_ERROR,
 								                Json(serde_json::json!({ "error": e.to_string() })),
 								            )
 								                .into_response(),
 								        }
 								    }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    // ═══════════════════════════════════════════════════════════════════════
 								    //  DELETE
 								    // ═══════════════════════════════════════════════════════════════════════
 								    /// Deletes a file (trash-first with dedup cleanup).
 								    ///
 								    /// All logic (trash fallback, dedup ref-count, hash computation) is handled
 								    /// by `FileManagementUseCase::delete_with_cleanup`.
-											fix: resolve file management operations not working (#83)
										
										
											2026-02-13 08:54:51 +01:00
+								    ///
 								    /// When auth is available, uses trash-first deletion; otherwise falls back
 								    /// to permanent delete so the endpoint works with or without auth.
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    pub(super) async fn delete_file_impl(
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        State(state): State<GlobalState>,
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        auth_user: AuthUser,
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        Path(id): Path<String>,
 								    ) -> impl IntoResponse {
 								        let mgmt = &state.applications.file_management_service;
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        // Auth required: trash-first with dedup cleanup + ownership verification
-											fix: resolve all clippy warnings and convert integration_tests to custom cfg
										
										
											2026-03-04 23:55:08 +01:00
+								        let result = mgmt
-											refactor(server): file_management_service: move all method without owner check into private, add folder_ports
										
										
											2026-05-20 15:39:53 +02:00
+								            .delete_and_cleanup_with_perms(&id, auth_user.id)
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								            .await
 								            .map(|was_trashed| {
 								                if was_trashed {
 								                    tracing::info!("File moved to trash: {}", id);
 								                } else {
 								                    tracing::info!("File permanently deleted: {}", id);
 								                }
 								            });
-											fix: resolve file management operations not working (#83)
										
										
											2026-02-13 08:54:51 +01:00
 								        match result {
 								            Ok(_) => StatusCode::NO_CONTENT.into_response(),
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Err(err) => AppError::from(err).into_response(),
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        }
 								    }
 								    // ═══════════════════════════════════════════════════════════════════════
 								    //  MOVE
 								    // ═══════════════════════════════════════════════════════════════════════
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								    /// Renames a file (ownership-verified)
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    pub(super) async fn rename_file_impl(
-											modernizing frontend
										
										
											2026-02-08 22:44:42 +01:00
+								        State(state): State<GlobalState>,
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        auth_user: AuthUser,
-											modernizing frontend
										
										
											2026-02-08 22:44:42 +01:00
+								        Path(id): Path<String>,
 								        Json(payload): Json<serde_json::Value>,
 								    ) -> impl IntoResponse {
 								        let new_name = match payload.get("name").and_then(|v| v.as_str()) {
 								            Some(name) if !name.trim().is_empty() => name.trim().to_string(),
 								            _ => {
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								                return (
 								                    StatusCode::BAD_REQUEST,
 								                    Json(serde_json::json!({
 								                        "error": "Missing or empty 'name' field"
 								                    })),
 								                )
 								                    .into_response();
-											modernizing frontend
										
										
											2026-02-08 22:44:42 +01:00
+								            }
 								        };
 								        tracing::info!("Renaming file {} to \"{}\"", id, new_name);
 								        let mgmt = &state.applications.file_management_service;
-											refactor(server): file_management_service: move all method without owner check into private, add folder_ports
										
										
											2026-05-20 15:39:53 +02:00
+								        match mgmt
 								            .rename_file_with_perms(&id, auth_user.id, &new_name)
 								            .await
 								        {
-											modernizing frontend
										
										
											2026-02-08 22:44:42 +01:00
+								            Ok(file_dto) => (StatusCode::OK, Json(file_dto)).into_response(),
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Err(err) => AppError::from(err).into_response(),
-											modernizing frontend
										
										
											2026-02-08 22:44:42 +01:00
+								        }
 								    }
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								    /// Moves a file to a different folder (ownership-verified)
-											feat(authz): check permission on read handlers + check create permission on folder
										
										
											2026-05-21 11:07:04 +02:00
+								    /// TODO: dead function ?
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    pub async fn move_file(
 								        State(state): State<GlobalState>,
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        auth_user: AuthUser,
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        Path(id): Path<String>,
 								        Json(payload): Json<MoveFilePayload>,
 								    ) -> impl IntoResponse {
 								        tracing::info!("Moving file {} to folder {:?}", id, payload.folder_id);
 								        let mgmt = &state.applications.file_management_service;
-											fix: resolve all clippy warnings and convert integration_tests to custom cfg
										
										
											2026-03-04 23:55:08 +01:00
+								        match mgmt
-											refactor(server): file_management_service: move all method without owner check into private, add folder_ports
										
										
											2026-05-20 15:39:53 +02:00
+								            .move_file_with_perms(&id, auth_user.id, payload.folder_id)
-											fix: resolve all clippy warnings and convert integration_tests to custom cfg
										
										
											2026-03-04 23:55:08 +01:00
+								            .await
 								        {
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								            Ok(file) => (StatusCode::OK, Json(file)).into_response(),
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Err(err) => AppError::from(err).into_response(),
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        }
 								    }
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								    /// Moves a file to a different folder (ownership-verified)
 								    pub(super) async fn move_file_simple_impl(
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        State(state): State<GlobalState>,
-											fix(security): IDOR protection for file operations
										
										
											2026-03-04 17:18:39 +01:00
+								        auth_user: AuthUser,
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								        Path(id): Path<String>,
 								        Json(payload): Json<serde_json::Value>,
 								    ) -> impl IntoResponse {
 								        let folder_id = payload
 								            .get("folder_id")
 								            .and_then(|v| v.as_str())
 								            .map(|s| s.to_string());
 								        let mgmt = &state.applications.file_management_service;
-											refactor(server): file_management_service: move all method without owner check into private, add folder_ports
										
										
											2026-05-20 15:39:53 +02:00
+								        match mgmt
 								            .move_file_with_perms(&id, auth_user.id, folder_id)
 								            .await
 								        {
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								            Ok(file_dto) => (StatusCode::OK, Json(file_dto)).into_response(),
-											fix: resolve clippy warnings and rustfmt issues for CI compliance
										
										
											2026-03-09 14:34:07 +01:00
+								            Err(err) => AppError::from(err).into_response(),
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								        }
 								    }
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
 								    // ═══════════════════════════════════════════════════════════════════════
 								    //  PRIVATE HELPERS
 								    // ═══════════════════════════════════════════════════════════════════════
 								    /// Build a Content-Disposition header value.
-											fix: security audit — patch vulnerabilities V-02 through V-16
										
										
											2026-03-05 14:52:11 +01:00
+								    ///
-											feat(share): public folder browsing API + range support + zip
										
										
											2026-05-05 22:41:55 +02:00
+								    /// Build a `Content-Disposition` header value for an authenticated download,
 								    /// honouring the `?inline=true|1` query param. Delegates to the shared
 								    /// `build_content_disposition` so the share-link path produces identical
 								    /// header values for the same `(name, mime)` pair.
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    fn content_disposition(name: &str, mime: &str, params: &HashMap<String, String>) -> String {
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								        let force_inline = params
 								            .get("inline")
 								            .is_some_and(|v| v == "true" || v == "1");
-											feat(share): public folder browsing API + range support + zip
										
										
											2026-05-05 22:41:55 +02:00
+								        build_content_disposition(name, mime, force_inline)
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    }
 								    /// Build a 201 Created JSON response.
 								    fn created_json_response(file: &crate::application::dtos::file_dto::FileDto) -> Response<Body> {
 								        Response::builder()
 								            .status(StatusCode::CREATED)
 								            .header(header::CONTENT_TYPE, "application/json")
 								            .header(header::CACHE_CONTROL, "no-cache, no-store, must-revalidate")
 								            .body(Body::from(serde_json::to_string(file).unwrap()))
 								            .unwrap()
 								    }
 								    /// Build error response for DomainError.
 								    fn domain_error_response(err: crate::common::errors::DomainError) -> Response<Body> {
-											security: fix vulnerabilities 1-7 from security audit
										
										
											2026-03-05 13:15:34 +01:00
+								        AppError::from(err).into_response()
-											refactoring hexagonal and clean architecture
										
										
											2026-02-08 13:40:23 +01:00
+								    }
-											fix(#104): enforce storage quota on uploads & fix usage tracking
										
										
											2026-02-14 10:34:07 +01:00
+								    /// Build a quota-specific error response with 507 status and structured body.
 								    fn quota_error_response(err: crate::common::errors::DomainError) -> Response<Body> {
-											security: fix vulnerabilities 1-7 from security audit
										
										
											2026-03-05 13:15:34 +01:00
+								        AppError::from(err).into_response()
-											fix(#104): enforce storage quota on uploads & fix usage tracking
										
										
											2026-02-14 10:34:07 +01:00
+								    }
-											perf: implement findings #2, #3, #17 from architecture audit
										
										
											2026-02-22 14:12:53 +01:00
+								    /// Build response for cached/small files.
 								    ///
 								    /// Compression is handled uniformly by `CompressionLayer` (tower-http)
 								    /// which negotiates `Accept-Encoding` and applies gzip/brotli in streaming
 								    /// mode. No manual compression is done here to avoid double-encoding.
 								    fn build_cached_response(
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								        content: Bytes,
 								        mime_type: &str,
 								        disposition: &str,
 								        etag: &str,
 								    ) -> Response<Body> {
-											perf: implement findings #2, #3, #17 from architecture audit
										
										
											2026-02-22 14:12:53 +01:00
+								        Response::builder()
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            .status(StatusCode::OK)
-											perf: implement findings #2, #3, #17 from architecture audit
										
										
											2026-02-22 14:12:53 +01:00
+								            .header(header::CONTENT_TYPE, mime_type)
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								            .header(header::CONTENT_DISPOSITION, disposition)
 								            .header(header::ETAG, etag)
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								            .header(
 								                header::CACHE_CONTROL,
 								                "private, max-age=3600, must-revalidate",
 								            )
-											perf: implement findings #2, #3, #17 from architecture audit
										
										
											2026-02-22 14:12:53 +01:00
+								            .header(header::VARY, "Accept-Encoding")
 								            .header(header::CONTENT_LENGTH, content.len())
 								            .body(Body::from(content))
 								            .unwrap()
-											big refactoring
										
										
											2026-02-03 17:59:04 +01:00
+								    }
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								}
 								/// Payload for moving a file
-											feat: add OpenAPI spec generation with utoipa and justfile
										
										
											2026-03-29 18:49:10 +02:00
+								#[derive(Debug, Deserialize, ToSchema)]
-											Initial commit
										
										
											2025-03-17 21:28:08 +01:00
+								pub struct MoveFilePayload {
 								    /// Target folder ID (None means root)
 								    pub folder_id: Option<String>,
-											style: apply cargo fmt to entire codebase
										
										
											2026-02-14 01:29:34 +01:00
+								}
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
-											feat(share): public folder browsing API + range support + zip
										
										
											2026-05-05 22:41:55 +02:00
+								/// RFC 5987-compliant `Content-Disposition` with both ASCII fallback and
 								/// `filename*=UTF-8''...` for non-ASCII filenames.
 								pub(super) fn build_content_disposition(name: &str, mime: &str, force_inline: bool) -> String {
 								    let disposition = if force_inline
 								        || mime.starts_with("image/")
 								        || mime == "application/pdf"
 								        || mime.starts_with("video/")
 								        || mime.starts_with("audio/")
 								    {
 								        "inline"
 								    } else {
 								        "attachment"
 								    };
 								    use percent_encoding::{AsciiSet, NON_ALPHANUMERIC, utf8_percent_encode};
 								    // RFC 5987 attr-char safe set (no encoding needed for these).
 								    const RFC5987_SET: &AsciiSet = &NON_ALPHANUMERIC
 								        .remove(b'!')
 								        .remove(b'#')
 								        .remove(b'$')
 								        .remove(b'&')
 								        .remove(b'+')
 								        .remove(b'-')
 								        .remove(b'.')
 								        .remove(b'^')
 								        .remove(b'_')
 								        .remove(b'`')
 								        .remove(b'|')
 								        .remove(b'~');
 								    let encoded = utf8_percent_encode(name, RFC5987_SET).to_string();
 								    let ascii_safe: String = name
 								        .chars()
 								        .filter(|c| c.is_ascii_graphic() || *c == ' ')
 								        .map(|c| match c {
 								            '"' | '\\' => '_',
 								            _ => c,
 								        })
 								        .collect();
 								    format!("{disposition}; filename=\"{ascii_safe}\"; filename*=UTF-8''{encoded}")
 								}
-											feat(openapi): upgrade code to gnerate openapi on all path
										
										
											2026-04-27 22:59:18 +02:00
+								// ── Route handlers (free functions) ──────────────────────────────────────────
 								//
 								// All annotated route functions live here rather than as methods on FileHandler
 								// because utoipa 5.4.0's #[utoipa::path] macro generates helper structs inside
 								// its expansion. Rust allows struct definitions at module scope but forbids them
 								// inside impl blocks — so every #[utoipa::path] annotation on a FileHandler
 								// method fails to compile regardless of HTTP verb or annotation content.
 								//
 								// All logic lives in the FileHandler::*_impl methods above; these thin wrappers
 								// exist solely to carry the OpenAPI annotation at a scope where utoipa can
 								// generate its helper types.
 								//
 								// routes.rs calls these free functions directly.
 								// TODO: collapse back into the impl block after a utoipa upgrade resolves the issue.
 								#[utoipa::path(
 								    get,
 								    path = "/api/files",
 								    params(("folder_id" = Option<String>, Query, description = "Filter by folder ID")),
 								    responses(
 								        (status = 200, description = "List of files", body = Vec<FileDto>),
 								        (status = 304, description = "Not modified"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn list_files_query(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    headers: HeaderMap,
 								    query: Query<HashMap<String, String>>,
 								) -> impl IntoResponse {
 								    FileHandler::list_files_query_impl(state, auth_user, headers, query).await
 								}
 								#[utoipa::path(
 								    post,
 								    path = "/api/files/upload",
 								    request_body(content_type = "multipart/form-data", description = "File data + optional folder_id field"),
 								    responses(
 								        (status = 201, description = "File uploaded", body = FileDto),
 								        (status = 400, description = "Invalid request"),
 								        (status = 507, description = "Storage quota exceeded"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn upload_file_with_thumbnails(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    multipart: Multipart,
 								) -> impl IntoResponse {
 								    FileHandler::upload_file_with_thumbnails_impl(state, auth_user, multipart).await
 								}
 								#[utoipa::path(
 								    get,
 								    path = "/api/files/{id}",
 								    params(
 								        ("id" = String, Path, description = "File ID"),
 								        ("metadata" = Option<bool>, Query, description = "Return metadata JSON instead of file content"),
 								        ("original" = Option<bool>, Query, description = "Skip WebP transcoding"),
 								        ("inline" = Option<bool>, Query, description = "Content-Disposition: inline"),
 								    ),
 								    responses(
 								        (status = 200, description = "File content"),
 								        (status = 206, description = "Partial content (Range request)"),
 								        (status = 304, description = "Not modified"),
 								        (status = 404, description = "File not found"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn download_file(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    path: Path<String>,
 								    query: Query<HashMap<String, String>>,
 								    headers: HeaderMap,
 								) -> impl IntoResponse {
 								    FileHandler::download_file_impl(state, auth_user, path, query, headers).await
 								}
 								#[utoipa::path(
 								    get,
 								    path = "/api/files/{id}/thumbnail/{size}",
 								    params(
 								        ("id" = String, Path, description = "File ID"),
 								        ("size" = String, Path, description = "Thumbnail size: icon | preview | large"),
 								    ),
 								    responses(
 								        (status = 200, description = "Thumbnail image (image/jpeg or image/webp)"),
 								        (status = 204, description = "No thumbnail available for this file type"),
 								        (status = 304, description = "Not modified"),
 								        (status = 404, description = "File not found"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn get_thumbnail(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    headers: HeaderMap,
 								    path: Path<(String, String)>,
 								) -> impl IntoResponse {
 								    FileHandler::get_thumbnail_impl(state, auth_user, headers, path).await
 								}
 								#[utoipa::path(
 								    put,
 								    path = "/api/files/{id}/thumbnail/{size}",
 								    params(
 								        ("id" = String, Path, description = "File ID"),
 								        ("size" = String, Path, description = "Thumbnail size: icon | preview | large"),
 								    ),
 								    request_body(content_type = "application/octet-stream", description = "Raw image bytes (max 512 KB)"),
 								    responses(
 								        (status = 201, description = "Thumbnail stored"),
 								        (status = 400, description = "Invalid image or size too large"),
 								        (status = 404, description = "File not found"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn upload_thumbnail(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    path: Path<(String, String)>,
 								    body: Bytes,
 								) -> impl IntoResponse {
 								    FileHandler::upload_thumbnail_impl(state, auth_user, path, body).await
 								}
 								#[utoipa::path(
 								    get,
 								    path = "/api/files/{id}/metadata",
 								    params(("id" = String, Path, description = "File ID")),
 								    responses(
 								        (status = 200, description = "File metadata (EXIF, dimensions, duration, etc.)"),
 								        (status = 404, description = "File not found"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn get_file_metadata(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    path: Path<String>,
 								) -> impl IntoResponse {
 								    FileHandler::get_file_metadata_impl(state, auth_user, path).await
 								}
 								#[utoipa::path(
 								    delete,
 								    path = "/api/files/{id}",
 								    params(("id" = String, Path, description = "File ID")),
 								    responses(
 								        (status = 204, description = "File deleted (moved to trash if enabled)"),
 								        (status = 404, description = "File not found"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn delete_file(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    path: Path<String>,
 								) -> impl IntoResponse {
 								    FileHandler::delete_file_impl(state, auth_user, path).await
 								}
 								#[utoipa::path(
 								    put,
 								    path = "/api/files/{id}/rename",
 								    params(("id" = String, Path, description = "File ID")),
 								    request_body(content_type = "application/json", description = r#"{"name": "new-name.txt"}"#),
 								    responses(
 								        (status = 200, description = "Renamed file", body = FileDto),
 								        (status = 404, description = "File not found"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn rename_file(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    path: Path<String>,
 								    json: Json<serde_json::Value>,
 								) -> impl IntoResponse {
 								    FileHandler::rename_file_impl(state, auth_user, path, json).await
 								}
 								#[utoipa::path(
 								    put,
 								    path = "/api/files/{id}/move",
 								    params(("id" = String, Path, description = "File ID")),
 								    request_body(content = MoveFilePayload, content_type = "application/json", description = "MoveFilePayload"),
 								    responses(
 								        (status = 200, description = "Moved file", body = FileDto),
 								        (status = 404, description = "File or destination not found"),
 								    ),
 								    tag = "files"
 								)]
 								pub async fn move_file_simple(
 								    state: State<GlobalState>,
 								    auth_user: AuthUser,
 								    path: Path<String>,
 								    json: Json<serde_json::Value>,
 								) -> impl IntoResponse {
 								    FileHandler::move_file_simple_impl(state, auth_user, path, json).await
 								}