◉ClassyGitShadowzzh

upload.rs

upload.rs
//! `/admin/upload`(sharp 硬骨頭之 thumbhash)。移植 Express multer + `computeThumbHashBase64`。
//!
//! 檔案落地與 Express 相同(`storage/uploads/YYYY/MM/{Date.now()}-{rand}.ext`,原 bytes 不動)。
//! thumbhash:image crate resize(fit-inside 100、Lanczos3、sharp 的 Math.round 尺寸公式)
//! → `thumbhash` crate(spec port)→ base64url。實測對 sharp 版:尺寸公式 100% 對齊、
//! hash 2/5 byte 相同、3/5 差 ≤2 字元(±1 量化係數,解碼後模糊圖視覺零差異)。

use std::fmt::Write as _;

use axum::{
    Json,
    extract::{FromRequest, Multipart, Request, State},
    http::StatusCode,
    response::{IntoResponse, Response},
};
use base64::Engine;
// rand 0.10:random_range 之類的高階方法在 RngExt 上(Rng 只剩 next_u32/fill_bytes 那層)
use rand::RngExt;
use serde_json::json;

use crate::state::AppState;

fn uploads_base() -> std::path::PathBuf {
    std::env::var("UPLOAD_BASE_DIR").map_or_else(|_| "/usr/src/app/storage/uploads".into(), Into::into)
}

/// ffmpeg / ffprobe 的執行檔名,可用 env 覆寫。
///
/// 存在的理由跟 `state::ExternalUrls` 一樣:**讓外部相依可被替換,否則測不到**。
/// 這兩個函式的邏輯(有沒有旋轉 → 重編還是無損重封裝、成功要換檔、失敗要清 tmp)
/// 全都藏在 subprocess 後面,不注入的話只驗得到「ffmpeg 不在時保留原檔」那一條——
/// 實測 `cargo mutants` 有 10 個變異因此無人看守。
///
/// 正式環境完全不受影響:不設 env 就是 `ffmpeg` / `ffprobe`,跟原本一樣走 PATH。
fn ffmpeg_bin() -> String {
    std::env::var("FFMPEG_BIN").unwrap_or_else(|_| "ffmpeg".into())
}
fn ffprobe_bin() -> String {
    std::env::var("FFPROBE_BIN").unwrap_or_else(|_| "ffprobe".into())
}

/// sharp `fit:'inside'` + `withoutEnlargement` 尺寸公式(Math.round;實測 5/5 對齊)。
fn fit_inside(w: u32, h: u32, max: u32) -> (u32, u32) {
    if w <= max && h <= max {
        return (w, h);
    }
    let ratio = (f64::from(max) / f64::from(w)).min(f64::from(max) / f64::from(h));
    // ratio < 1(上面已擋 w、h 都 ≤ max),所以縮完一定小於原尺寸;max(1.0) 保證非負
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss, reason = "只縮不放且已 max(1.0)")]
    ((f64::from(w) * ratio).round().max(1.0) as u32, (f64::from(h) * ratio).round().max(1.0) as u32)
}

/// 上傳圖片的中繼資料:thumbhash + **原始像素尺寸**。
///
/// ⚠ 尺寸不是順便回傳的。前端把它寫成 `<img width height>`,那是文章頁 CLS 的解藥:
/// 圖片外層是 `width: fit-content`,寬度取決於圖片的固有尺寸——圖還沒載入時固有寬度
/// 是 0,於是 `aspect-ratio` 反推出來的高度也是 0,整個盒子塌掉。等圖載入才撐開,
/// 底下的內容就整片位移。
///
/// 實測(2026-08-07,正式站 /blog/why-i-switched-to-zed):
///   冷啟動(scrollY=0)      CLS 0.0000   ← 圖在畫面外,位移不計入
///   捲到 4000px 後重整       CLS 0.3362   ← 四個 <p> 從 0px 長到 432/216/186/101
/// 最小重現:只有 aspect-ratio → 高 19px;補上 width/height → 高 653px。
///
/// 為什麼不能只靠 thumbhash 的比例:`thumbHashToApproximateAspectRatio` 是**近似值**
/// (1142×724 解出 1.75、704×85 解出 7),預留高度會差幾個百分點。而且比例本身
/// 救不了寬度為 0 的問題——要有確定的寬度,aspect-ratio 才反推得出高度。
struct ImageMeta {
    hash: String,
    width: u32,
    height: u32,
}

/// `computeThumbHashBase64` 等價(外加原始尺寸):失敗回 None(Express catch → null)。
fn compute_image_meta(bytes: &[u8]) -> Option<ImageMeta> {
    let img = image::load_from_memory(bytes).ok()?;
    let (w, h) = (img.width(), img.height());
    let (tw, th) = fit_inside(w, h, 100);
    let resized = img.resize_exact(tw, th, image::imageops::FilterType::Lanczos3);
    let rgba = resized.to_rgba8();
    let hash = thumbhash::rgba_to_thumb_hash(tw as usize, th as usize, rgba.as_raw());
    Some(ImageMeta {
        hash: base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(&hash),
        width: w,
        height: h,
    })
}

/// ffmpeg 最長跑多久(大檔重編可能要幾分鐘;超時就保留原檔,不讓上傳卡死)
const FFMPEG_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(300);

/// 從 ffprobe 的 stdout 解出旋轉角度。抽成純函式是為了**不裝 ffmpeg 也測得到**——
/// 這段的邏輯(跳過 0、容忍雜訊行、小數要 round)全在這裡,subprocess 只負責取字串。
///
/// ffprobe 會把兩個來源都印出來(新版在 `side_data` 的 rotation、舊檔在 tags 的 rotate),
/// 一行一個值,沒有的那個是空行。取「第一個非 0 的」而不是第一行——因為兩者常常
/// 一個有值一個是 0,順序還不保證。
fn parse_rotation(stdout: &str) -> Option<i32> {
    let deg = stdout.lines().filter_map(|l| l.trim().parse::<f64>().ok()).find(|d| *d != 0.0)?;
    // exiftool 的旋轉角度只會是 -360..=360,i32 綽綽有餘
    #[allow(clippy::cast_possible_truncation, reason = "來源是 exiftool 的角度,值域 -360..=360")]
    Some(deg.round() as i32)
}

/// 讀出影片的旋轉角度(0 表示不需要處理)。ffprobe 不在或讀不到 → None。
async fn probe_rotation(path: &std::path::Path) -> Option<i32> {
    let out = tokio::process::Command::new(ffprobe_bin())
        .args([
            "-v",
            "error",
            "-select_streams",
            "v:0",
            // 新版 ffmpeg 放在 side_data 的 rotation;舊檔可能只有 tags 的 rotate
            "-show_entries",
            "stream_side_data=rotation:stream_tags=rotate",
            "-of",
            "default=nw=1:nk=1",
        ])
        .arg(path)
        .output()
        .await
        .ok()?;
    parse_rotation(&String::from_utf8_lossy(&out.stdout))
}

/// 上傳影片正規化。
///
/// 手機拍的直式影片幾乎都是「橫向存放 + tkhd 旋轉矩陣」,靠播放器自己套矩陣把畫面轉正。
/// 這條路徑在各家實作的差異很大——本站實測 Chromium 會整片黑:`canvas.drawImage()` 走軟體
/// 路徑、自己算進旋轉,取得的畫面是亮的,但 `<video>` 元素的顯示路徑合成不出來。旋轉 metadata
/// 是出了名的相容性地雷(Firefox / ExoPlayer / Safari HLS 各有各的坑),所以在上傳這一關就把
/// 旋轉烘進畫素,之後沒有任何播放器需要處理矩陣。
///
/// 沒有旋轉的檔案只做 `-c copy` 重新封裝(無損),順便把 moov atom 搬到檔頭讓它能邊下邊播。
/// ffmpeg 不在、失敗或超時 → 保留原檔,絕不讓上傳失敗。
async fn normalize_video(path: &std::path::Path) {
    let rotation = probe_rotation(path).await;
    let tmp = path.with_extension("normalizing.mp4");

    let mut cmd = tokio::process::Command::new(ffmpeg_bin());
    cmd.arg("-y").arg("-i").arg(path);
    match rotation {
        // 有旋轉 → 只能重編才能把畫面轉正(ffmpeg 解碼時預設就會套用顯示矩陣,
        // 輸出因此是已轉正的畫素 + 單位矩陣,不需要再手動 transpose)
        Some(deg) if deg != 0 => {
            tracing::info!("影片帶 {deg}° 旋轉矩陣,重編以烘進畫素:{}", path.display());
            cmd.args([
                "-c:v",
                "libx264",
                "-profile:v",
                "high",
                "-pix_fmt",
                "yuv420p",
                "-crf",
                "24",
                "-preset",
                "medium",
                "-c:a",
                "aac",
                "-b:a",
                "128k",
            ]);
        }
        // 沒旋轉 → 無損重封裝就好
        _ => {
            cmd.args(["-c", "copy"]);
        }
    }
    cmd.args(["-movflags", "+faststart"]).arg(&tmp);

    let status = match tokio::time::timeout(FFMPEG_TIMEOUT, cmd.output()).await {
        Ok(Ok(o)) if o.status.success() => Ok(()),
        Ok(Ok(o)) => {
            Err(format!("ffmpeg 失敗:{}", String::from_utf8_lossy(&o.stderr).lines().last().unwrap_or("")))
        }
        // ffmpeg 不在 image 裡(例如本機跑 cargo run)→ 保留原檔就好,不是錯誤
        Ok(Err(e)) => Err(format!("ffmpeg 無法執行:{e}")),
        Err(_) => Err("ffmpeg 超時".to_string()),
    };
    match status {
        Ok(()) => {
            if let Err(e) = tokio::fs::rename(&tmp, path).await {
                tracing::warn!("影片正規化後換檔失敗,保留原檔:{e}");
                let _ = tokio::fs::remove_file(&tmp).await;
            }
        }
        Err(msg) => {
            tracing::warn!("影片正規化跳過(保留原檔):{msg}");
            let _ = tokio::fs::remove_file(&tmp).await;
        }
    }
}

/// `POST /api/admin/upload` —— requireAdmin + multer.single('file')。
/// ⚠️ Multipart 不當參數 extractor:它拒絕時回 400,而這裡「沒有檔案」要回自己的 JSON 錯誤。
/// 身分照樣由 `AdminAuth` 先驗(parts extractor 一定比吃 body 的 `Request` 先跑)。
#[utoipa::path(post, path = "/api/admin/upload", tag = "admin", security(("bearer" = [])),
    responses((status = 200, description = "上傳結果(url/filename/thumbhash,動態 JSON)"), (status = 400, description = "未上傳檔案"), (status = 401, description = "未授權"), (status = 500, description = "寫檔失敗")))]
pub async fn upload(State(state): State<AppState>, _auth: crate::auth::AdminAuth, req: Request) -> Response {
    // 非 multipart body:multer 情境下 req.file undefined → 400
    let Ok(mut multipart) = Multipart::from_request(req, &state).await else {
        return (StatusCode::BAD_REQUEST, Json(json!({ "error": "No file uploaded" }))).into_response();
    };
    // multer.single('file'):只取 name=='file' 的欄位
    let mut file: Option<(String, String, Vec<u8>)> = None; // (original_name, mimetype, bytes)
    while let Ok(Some(field)) = multipart.next_field().await {
        if field.name() != Some("file") {
            continue;
        }
        let original = field.file_name().unwrap_or("").to_string();
        let mimetype = field.content_type().unwrap_or("").to_string();
        match field.bytes().await {
            Ok(b) => {
                file = Some((original, mimetype, b.to_vec()));
                break;
            }
            Err(_) => break,
        }
    }
    let Some((original, mimetype, bytes)) = file else {
        return (StatusCode::BAD_REQUEST, Json(json!({ "error": "No file uploaded" }))).into_response();
    };

    // 路徑/檔名:storage/uploads/YYYY/MM/{Date.now()}-{round(rand*1E9)}{ext}
    let now_ms = crate::util::now_ms();
    // Express 用 new Date().getFullYear()/getMonth()=容器本地時區(compose TZ=Asia/Taipei)
    // → chrono Local(尊重 TZ env)對齊,月界不會放錯目錄。
    let now_local = chrono::Local::now();
    let year_s = now_local.format("%Y").to_string();
    let month_s = now_local.format("%m").to_string();
    let (year, month) = (year_s.as_str(), month_s.as_str());
    let ext = std::path::Path::new(&original)
        .extension()
        .map(|e| format!(".{}", e.to_string_lossy()))
        .unwrap_or_default();
    // rand 0.9 起 thread_rng() → rng()、gen_range() → random_range()(舊名在 0.10 已移除)
    let rand_part: u64 = rand::rng().random_range(0..=1_000_000_000);
    let filename = format!("{now_ms}-{rand_part}{ext}");
    let dir = uploads_base().join(year).join(month);
    if let Err(e) = tokio::fs::create_dir_all(&dir).await {
        return crate::error::internal_error(StatusCode::INTERNAL_SERVER_ERROR, e);
    }
    let path = dir.join(&filename);
    if let Err(e) = tokio::fs::write(&path, &bytes).await {
        return crate::error::internal_error(StatusCode::INTERNAL_SERVER_ERROR, e);
    }

    // 影片:把旋轉矩陣烘進畫素(原地取代,檔名不變)
    if mimetype.starts_with("video/") {
        normalize_video(&path).await;
    }

    let mut file_url = format!("/uploads/{year}/{month}/{filename}");
    // 圖片才算 thumbhash(mimetype 為 client 宣告,對齊 multer)
    let mut meta: Option<ImageMeta> = None;
    if mimetype.starts_with("image/") {
        meta = tokio::task::spawn_blocking(move || compute_image_meta(&bytes)).await.ok().flatten();
        if let Some(m) = &meta {
            // 中繼資料全部塞在 **fragment**:瀏覽器送 HTTP 請求時不帶 fragment,
            // 所以對 nginx 快取與 CDN 完全無影響,也不必為此開 DB 欄位或改 API 型別
            // ——這些網址是寫在文章內容裡的,由內容自己帶著走。
            //
            // 順序固定 th → w → h:前端的解析用具名參數不靠順序,但固定寫法讓
            // 既有內容的 diff 讀得懂,也讓 `#th=` 那條舊 regex 照樣命中(`&` 會斷開)。
            let _ = write!(file_url, "#th={}&w={}&h={}", m.hash, m.width, m.height);
        }
    }

    Json(json!({
        "message": "success",
        "url": file_url,
        "filename": filename,
        "thumbhash": meta.as_ref().map(|m| m.hash.clone()),
        "width": meta.as_ref().map(|m| m.width),
        "height": meta.as_ref().map(|m| m.height),
    }))
    .into_response()
}

#[cfg(test)]
mod tests {
    use super::*;

    /// 造一張純色 PNG,給 thumbhash 用。
    fn png(w: u32, h: u32) -> Vec<u8> {
        let img =
            image::RgbImage::from_fn(w, h, |x, _| image::Rgb([u8::try_from(x % 256).unwrap_or(0), 128, 64]));
        let mut buf = std::io::Cursor::new(Vec::new());
        image::DynamicImage::ImageRgb8(img).write_to(&mut buf, image::ImageFormat::Png).unwrap();
        buf.into_inner()
    }

    /// sharp `withoutEnlargement`:本來就比上限小 → 原尺寸不動。
    #[test]
    fn fit_inside_never_enlarges() {
        assert_eq!(fit_inside(50, 50, 100), (50, 50));
        assert_eq!(fit_inside(100, 100, 100), (100, 100));
        assert_eq!(fit_inside(1, 1, 100), (1, 1));
    }

    /// 長邊縮到上限、短邊按比例(`Math.round`,不是 floor 也不是 ceil)。
    ///
    /// 150×100 特別選來釘住捨入:100/150 = 0.6667,100×0.6667 = 66.67 →
    /// round 是 **67**,floor 會得到 66。sharp 用的是 round,這裡對齊。
    #[test]
    fn fit_inside_scales_the_long_edge_and_rounds_the_short_one() {
        assert_eq!(fit_inside(200, 100, 100), (100, 50), "橫式");
        assert_eq!(fit_inside(100, 200, 100), (50, 100), "直式");
        assert_eq!(fit_inside(150, 100, 100), (100, 67), "短邊要 round 成 67 而不是 floor 成 66");
    }

    /// 極端長寬比不能算出 0——thumbhash 收到 0 會 panic 或產生無效 hash。
    #[test]
    fn fit_inside_clamps_to_at_least_one_pixel() {
        assert_eq!(fit_inside(1000, 1, 100), (100, 1));
        assert_eq!(fit_inside(1, 1000, 100), (1, 100));
    }

    /// 合法圖片 → Some,而且是 base64url 無 padding(會被塞進 URL 的 `#th=` 片段,
    /// 用標準 base64 的話 `+` `/` `=` 在 URL 裡會出事)。
    #[test]
    fn compute_image_meta_returns_url_safe_base64() {
        let m = compute_image_meta(&png(200, 120)).expect("合法 PNG 應該算得出 thumbhash");
        let th = m.hash;
        assert_ne!(th, "");
        assert!(!th.contains('='), "不該有 padding:{th}");
        assert!(!th.contains('+') && !th.contains('/'), "必須是 URL-safe 字母表:{th}");
        assert!(
            th.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_'),
            "出現非 base64url 字元:{th}"
        );
    }

    /// 回的是**原始**像素尺寸,不是縮圖後的(thumbhash 內部會縮到 fit_inside 100)。
    ///
    /// 這條是這次修正的核心:前端要拿它寫 `<img width height>` 來預留版面。
    /// 拿成縮圖尺寸的話比例還是對的、但 `fit-content` 的寬度會變成 100px,
    /// 圖片被限制在 100px 寬——是「看起來還好、實際壞掉」的那種錯。
    #[test]
    fn compute_image_meta_returns_original_pixel_size() {
        let m = compute_image_meta(&png(1142, 724)).expect("合法 PNG");
        assert_eq!((m.width, m.height), (1142, 724));

        // 極端長寬比也要照實回報(fit_inside 會把短邊夾成 1,但那是縮圖的事)
        let wide = compute_image_meta(&png(704, 85)).expect("合法 PNG");
        assert_eq!((wide.width, wide.height), (704, 85));
    }

    /// 不是圖片 → None(對齊 Express 的 `catch → null`),不是 panic 也不是 Err。
    #[test]
    fn compute_image_meta_returns_none_for_non_image_bytes() {
        assert!(compute_image_meta(b"this is not an image").is_none());
        assert!(compute_image_meta(&[]).is_none());
        // PNG magic 開頭但內容截斷——比純垃圾更容易讓解碼器走到別的分支
        assert!(compute_image_meta(&png(10, 10)[..8]).is_none());
    }

    /// 同一張圖每次算出來要一樣(thumbhash 進 URL,不穩定的話快取與比對都會壞)。
    #[test]
    fn compute_image_meta_is_deterministic() {
        let bytes = png(64, 64);
        let a = compute_image_meta(&bytes).expect("合法 PNG");
        let b = compute_image_meta(&bytes).expect("合法 PNG");
        assert_eq!(a.hash, b.hash);
        assert_eq!((a.width, a.height), (b.width, b.height));
    }

    /// ffprobe 真實輸出的兩種形狀:新版把值放 `side_data` 的 rotation,舊檔放 tags 的
    /// rotate。兩行都會印,沒有的那個是空行——所以不能取第一行,要取第一個非 0 的。
    #[test]
    fn parse_rotation_reads_either_ffprobe_field() {
        assert_eq!(parse_rotation("-90\n\n"), Some(-90), "側資料有值、tags 沒有");
        assert_eq!(parse_rotation("\n90\n"), Some(90), "側資料沒有、tags 有");
        assert_eq!(parse_rotation("-90\n270\n"), Some(-90), "兩個都有 → 取第一個");
    }

    /// 0 要被跳過而不是當成答案。
    ///
    /// 這是整段最容易寫錯的一行:`find(|d| *d != 0.0)`。改成 `== 0.0` 或拿掉 filter 的話,
    /// 「side_data 是 0、tags 才是真正的 90」這種檔案會被判成不需要旋轉——而那正是
    /// 手機直式影片最常見的形狀,結果就是 Chromium 上整片黑(檔頭註解那個線上問題)。
    #[test]
    fn parse_rotation_skips_zero_and_returns_none_when_all_zero() {
        assert_eq!(parse_rotation("0\n90\n"), Some(90), "前面的 0 要跳過");
        assert_eq!(parse_rotation("0\n0\n"), None, "全部是 0 → 不需要處理");
        assert_eq!(parse_rotation("0\n"), None);
        assert_eq!(parse_rotation("0.0\n-180\n"), Some(-180));
    }

    /// 沒有輸出、或輸出不是數字 → None(ffprobe 不在、或影片沒有旋轉欄位)。
    #[test]
    fn parse_rotation_tolerates_garbage() {
        assert_eq!(parse_rotation(""), None);
        assert_eq!(parse_rotation("\n\n\n"), None);
        assert_eq!(parse_rotation("N/A\n"), None);
        assert_eq!(parse_rotation("rotation=90\n"), None, "帶 key 的形式不是我們要的 -of 格式");
        assert_eq!(parse_rotation("not a number\n90\n"), Some(90), "雜訊行要跳過而不是中斷");
    }

    /// 小數要 round(ffprobe 對某些檔案會印 `89.999998`)。
    #[test]
    fn parse_rotation_rounds_fractional_degrees() {
        assert_eq!(parse_rotation("89.999998\n"), Some(90));
        assert_eq!(parse_rotation("-90.4\n"), Some(-90));
        assert_eq!(parse_rotation("  270.5  \n"), Some(271), "前後空白要 trim");
    }

    /// **round 之後可能變成 0**——所以這裡回的是 `Some(0)` 而不是 `None`。
    ///
    /// 濾網 `!= 0.0` 看的是解析出來的浮點數(0.4 通過),round 才把它變成 0。
    /// `normalize_video` 那邊的 `deg != 0` guard 因此不是死碼,它擋的正是這種值。
    #[test]
    fn parse_rotation_can_round_down_to_zero() {
        assert_eq!(parse_rotation("0.4\n"), Some(0));
        assert_eq!(parse_rotation("-0.2\n"), Some(0));
    }

    /// `UPLOAD_BASE_DIR` 有設就用它,沒設退回容器內的正式路徑。
    ///
    /// ⚠ 依賴 nextest 的行程隔離(每個測試各自一個行程)。
    #[test]
    fn uploads_base_honours_the_env_override() {
        unsafe { std::env::remove_var("UPLOAD_BASE_DIR") };
        assert_eq!(uploads_base(), std::path::PathBuf::from("/usr/src/app/storage/uploads"));
        unsafe { std::env::set_var("UPLOAD_BASE_DIR", "/tmp/somewhere") };
        assert_eq!(uploads_base(), std::path::PathBuf::from("/tmp/somewhere"));
    }
}