ClassyGitShadowzzh

gallery_sync.rs

gallery_sync.rs

//! 相簿同步(`POST /api/admin/gallery/sync`)。
//!
//! 這是 `gallery.rs` 裡最大的一塊,也是原本幾乎完全沒測到的一塊(223 個 region 漏 214)。
//! 它做的事很重:遞迴掃描來源目錄 → 每張新圖旋轉/縮放/編成 webp → 抽 EXIF →
//! 打 RAM++ 拿標籤 → 寫 manifest。壞掉的樣子有三種,沒有一種會噴錯:
//!
//!   · 掃描漏檔/多掃 → 相簿少了幾張,或多出縮圖快取那種本來就不該出現的東西
//!   · orientation 沒套用 → 直式照片的寬高顛倒,manifest 的 aspectRatio 跟著錯,
//!     前端瀑布流用它算欄高,於是整個版面錯位
//!   · 增量判斷失效 → 每次同步都把全部照片重編一次(幾百張,幾分鐘)
//!
//! ⚠ 這個檔用 `std::env::set_var`(sync 的路徑全靠環境變數注入),**依賴 nextest 的
//!   行程隔離**——每個測試各自一個行程,所以互不干擾。用 `cargo test` 跑會共用行程,
//!   這些測試就會互相踩。CI 用的是 nextest。

mod common;

use common::{owner_token, request, test_app};
use serde_json::Value;
use wiremock::matchers::{method, path};
use wiremock::{Mock, MockServer, ResponseTemplate};

/// 素材目錄(唯讀;產生方式見 scratchpad 的 gen_gallery_fixtures.py 註解):
///
/// ```text
/// photo-a.jpg                 60x40,EXIF orientation=6(順時針 90 度)+ 相機參數
/// photo-b.png                 30x50,無 EXIF
/// sub/photo-c.jpeg            40x40,驗遞迴掃描與 .jpeg 副檔名
/// cache/should-not-be-seen.jpg  在被排除的目錄名底下
/// notes.txt                   不支援的副檔名
/// broken.jpg                  副檔名對、內容不是圖片
/// ```
fn source_dir() -> String {
    concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/gallery_src").to_string()
}

/// 每個測試自己的輸出目錄。nextest 一個測試一個行程,所以 pid 就足以區隔;
/// 不共用是必要的——sync 會把 manifest 寫進去,共用等於測試之間互相污染。
struct OutDir(std::path::PathBuf);

impl OutDir {
    fn new(tag: &str) -> Self {
        let p = std::env::temp_dir().join(format!("koimsurai-gallery-{tag}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&p);
        std::fs::create_dir_all(&p).unwrap();
        unsafe {
            std::env::set_var("GALLERY_SOURCE_PATH", source_dir());
            std::env::set_var("GALLERY_OUTPUT_DIR", &p);
        }
        Self(p)
    }
    fn manifest(&self) -> Value {
        serde_json::from_str(&std::fs::read_to_string(self.0.join("manifest.json")).unwrap()).unwrap()
    }
    fn has(&self, name: &str) -> bool {
        self.0.join(name).exists()
    }
}

impl Drop for OutDir {
    fn drop(&mut self) {
        let _ = std::fs::remove_dir_all(&self.0);
    }
}

/// 沒有 tagger 的話 sync 會對每張照片打一次不存在的服務再等 timeout。
/// 指到一個「回 500」的假服務,讓那條路徑走得快又走得到(tagger 失敗不該擋 sync)。
async fn failing_tagger() -> MockServer {
    let server = MockServer::start().await;
    Mock::given(method("POST"))
        .and(path("/tag"))
        .respond_with(ResponseTemplate::new(500))
        .mount(&server)
        .await;
    unsafe {
        std::env::set_var("PHOTO_TAGGER_URL", server.uri());
        std::env::set_var("PHOTO_TAGGER_TIMEOUT_MS", "2000");
    }
    server
}

async fn sync(app: &axum::Router) -> (axum::http::StatusCode, Value) {
    request(app, "POST", "/api/admin/gallery/sync", None, Some(&owner_token(true))).await
}

#[tokio::test]
async fn 掃描只收支援的圖片_排除的目錄整個不進去() {
    let out = OutDir::new("scan");
    let _tagger = failing_tagger().await;
    let (app, _pool) = test_app().await;

    let (status, body) = sync(&app).await;
    assert_eq!(status, 200, "{body}");

    // total = 掃到的來源檔數。photo-a / photo-b / sub/photo-c / broken.jpg 共四個:
    //   · notes.txt 副檔名不支援 → 不算
    //   · cache/ 是被排除的目錄名 → 裡面那張連看都不該看
    assert_eq!(body["total"], 4, "掃描到的檔數不對:{body}");
    assert_eq!(body["processed"], 3);
    // broken.jpg 解不開 → 記一筆 failed 但不能讓整個 sync 掛掉
    assert_eq!(body["failed"], 1, "壞掉的圖片應該只記一筆失敗,而不是中斷整批");
    assert_eq!(body["skipped"], 0);
    assert_eq!(body["totalPhotos"], 3);

    // 排除目錄裡那張若被處理了,輸出目錄會多出它的 webp——這是最直接的證據
    assert!(!out.has("should-not-be-seen.webp"), "被排除目錄裡的照片被處理了");
    for id in ["photo-a", "photo-b", "photo-c"] {
        assert!(out.has(&format!("{id}.webp")), "{id} 的全尺寸圖沒產出來");
        assert!(out.has(&format!("{id}-thumb.webp")), "{id} 的縮圖沒產出來");
    }
}

#[tokio::test]
async fn orientation_要套用_寬高跟著交換() {
    let out = OutDir::new("orient");
    let _tagger = failing_tagger().await;
    let (app, _pool) = test_app().await;
    sync(&app).await;

    let m = out.manifest();
    let a = m["photos"]
        .as_array()
        .unwrap()
        .iter()
        .find(|p| p["id"] == "photo-a")
        .expect("photo-a 該在 manifest 裡");

    // 來源是 60x40 橫幅,EXIF orientation=6(順時針 90 度)→ 輸出必須是 40x60。
    // 沿用旋轉前的尺寸的話這裡會是 60x40,而 aspectRatio 跟著顛倒——
    // 前端瀑布流拿它算欄高,於是每一張直式照片都會把版面撐歪。
    assert_eq!(a["width"], 40, "orientation 沒套用到輸出尺寸");
    assert_eq!(a["height"], 60);
    let ar = a["aspectRatio"].as_f64().unwrap();
    assert!((ar - 40.0 / 60.0).abs() < 1e-9, "aspectRatio={ar}");

    // 沒有 orientation 的那張照原樣
    let b = m["photos"].as_array().unwrap().iter().find(|p| p["id"] == "photo-b").unwrap();
    assert_eq!((b["width"].as_u64(), b["height"].as_u64()), (Some(30), Some(50)));
}

#[tokio::test]
async fn exif_抽得出相機參數與拍攝時間() {
    let out = OutDir::new("exif");
    let _tagger = failing_tagger().await;
    let (app, _pool) = test_app().await;
    sync(&app).await;

    let m = out.manifest();
    let a = m["photos"].as_array().unwrap().iter().find(|p| p["id"] == "photo-a").unwrap();
    let e = &a["exif"];
    assert_eq!(e["make"], "TestMake");
    assert_eq!(e["model"], "TestModel");
    assert_eq!(e["ISO"], 100);
    // 分數要換算成小數:f/1.4 存的是 14/10,直接輸出分子的話前端會顯示 f/14
    assert!((e["FNumber"].as_f64().unwrap() - 1.4).abs() < 1e-6, "FNumber={}", e["FNumber"]);
    assert!((e["FocalLength"].as_f64().unwrap() - 32.0).abs() < 1e-6);
    assert!((e["ExposureTime"].as_f64().unwrap() - 1.0 / 640.0).abs() < 1e-9);

    // ⚠ 這張沒寫 OffsetTimeOriginal,所以輸出的是**不帶時區**的裸本地時間。
    //   舊版是拿容器的 TZ 硬補上去,於是在國外拍的照片會被標成台北時間。
    //   「不知道就不要假裝知道」——後面補不了的資訊,寫錯比留白糟。
    assert_eq!(e["DateTimeOriginal"], "2026-01-02T03:04:05");

    // 沒有 EXIF 的那張要是 null,不是一包全 null 的殼
    let b = m["photos"].as_array().unwrap().iter().find(|p| p["id"] == "photo-b").unwrap();
    assert!(b["exif"].is_null(), "沒有 EXIF 時應該整個是 null:{}", b["exif"]);
}

#[tokio::test]
async fn manifest_的網址與格式欄位() {
    let out = OutDir::new("manifest");
    let _tagger = failing_tagger().await;
    let (app, _pool) = test_app().await;
    sync(&app).await;

    let m = out.manifest();
    assert_eq!(m["totalPhotos"], 3);
    assert!(m["generatedAt"].as_str().unwrap().contains('T'), "generatedAt 應該是 ISO 8601");

    let a = m["photos"].as_array().unwrap().iter().find(|p| p["id"] == "photo-a").unwrap();
    // 四種尺寸的網址前端都會用到,缺一個就是某個版位的圖裂掉
    assert_eq!(a["urls"]["full"], "/nas-images/photo-a.webp");
    assert_eq!(a["urls"]["regular"], "/nas-images/photo-a.webp");
    assert_eq!(a["urls"]["small"], "/nas-images/photo-a-thumb.webp");
    assert_eq!(a["urls"]["thumb"], "/nas-images/photo-a-thumb.webp");
    assert_eq!(a["originalUrl"], "/nas-images/photo-a.webp");
    assert_eq!(a["thumbnailUrl"], "/nas-images/photo-a-thumb.webp");
    // title 是檔名(含副檔名),id 是去掉副檔名的
    assert_eq!(a["title"], "photo-a.jpg");
    // format 記的是**來源**格式,不是輸出的 webp
    assert_eq!(a["format"], "jpeg");
    assert!(a["size"].as_u64().unwrap() > 0, "size 應該是輸出檔的實際大小");
    // 沒有拍攝時間就退回檔案 mtime,不能是 0(前端拿它排序)
    assert!(a["shootTime"].as_f64().unwrap() > 0.0);

    let b = m["photos"].as_array().unwrap().iter().find(|p| p["id"] == "photo-b").unwrap();
    assert_eq!(b["format"], "png");
}

#[tokio::test]
async fn 第二次同步整批跳過_不重編() {
    // 綁到具名變數(不是 `_`)才會活到測試結束——OutDir 的 Drop 負責清掉暫存目錄,
    // 用 `_` 會當場 drop,第二次 sync 就找不到第一次的產物了
    let _out = OutDir::new("incr");
    let _tagger = failing_tagger().await;
    let (app, _pool) = test_app().await;

    let (_, first) = sync(&app).await;
    assert_eq!(first["processed"], 3);

    // 增量判斷是「manifest 裡有這筆 **且** 兩個輸出檔都在」。少了任何一半,
    // 每次同步都會把全部照片重編一次——幾百張就是好幾分鐘,而且完全沒有症狀,
    // 只是「同步好像有點慢」。
    let (status, second) = sync(&app).await;
    assert_eq!(status, 200);
    assert_eq!(second["skipped"], 3, "第二次應該整批跳過:{second}");
    assert_eq!(second["processed"], 0);
    assert_eq!(second["totalPhotos"], 3);
}

#[tokio::test]
async fn 輸出檔被刪掉的那張會重新處理() {
    let out = OutDir::new("repair");
    let _tagger = failing_tagger().await;
    let (app, _pool) = test_app().await;
    sync(&app).await;

    // 只看 manifest 不看檔案的話,這張永遠補不回來——相簿上就一直是破圖
    std::fs::remove_file(out.0.join("photo-b-thumb.webp")).unwrap();
    let (_, again) = sync(&app).await;
    assert_eq!(again["processed"], 1, "缺檔的那張應該被重新處理:{again}");
    assert_eq!(again["skipped"], 2);
    assert!(out.has("photo-b-thumb.webp"), "重新處理之後縮圖該補回來");
}

#[tokio::test]
async fn tagger_回得了標籤就寫進_manifest() {
    let out = OutDir::new("tagged");
    let server = MockServer::start().await;
    Mock::given(method("POST"))
        .and(path("/tag"))
        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
            "zh_tw": ["日落", "海洋"],
            // 非字串的要被丟掉而不是塞進 manifest —— 前端的 renderer 吃不下數字,
            // 而它會在渲染時才炸,離這裡很遠
            "en": ["sunset", 42, "ocean"],
        })))
        .mount(&server)
        .await;
    unsafe {
        std::env::set_var("PHOTO_TAGGER_URL", server.uri());
        std::env::set_var("PHOTO_TAGGER_TIMEOUT_MS", "2000");
    }
    let (app, _pool) = test_app().await;

    let (_, body) = sync(&app).await;
    assert_eq!(body["tagged"], 3);

    let m = out.manifest();
    let a = m["photos"].as_array().unwrap().iter().find(|p| p["id"] == "photo-a").unwrap();
    assert_eq!(a["tags"], serde_json::json!(["日落", "海洋"]));
    assert_eq!(a["tagsEn"], serde_json::json!(["sunset", "ocean"]));
}

#[tokio::test]
async fn tagger_掛掉不影響同步本身() {
    let out = OutDir::new("no-tagger");
    // 指到一個沒人在聽的埠:連線直接失敗,比回 500 更接近「服務整個沒起來」
    unsafe {
        std::env::set_var("PHOTO_TAGGER_URL", "http://127.0.0.1:1");
        std::env::set_var("PHOTO_TAGGER_TIMEOUT_MS", "1000");
    }
    let (app, _pool) = test_app().await;

    // 標籤是加分項不是必需品。tagger 失敗就讓整批同步失敗的話,那個服務一掛,
    // 新照片就再也上不了架。
    let (status, body) = sync(&app).await;
    assert_eq!(status, 200, "tagger 掛掉不該讓同步失敗:{body}");
    assert_eq!(body["processed"], 3);
    assert_eq!(body["tagged"], 0);
    let m = out.manifest();
    assert_eq!(m["totalPhotos"], 3);
}

#[tokio::test]
async fn 來源目錄不存在時回_500_並說清楚是哪個路徑() {
    let _out = OutDir::new("missing");
    unsafe { std::env::set_var("GALLERY_SOURCE_PATH", "/definitely/not/here") };
    let (app, _pool) = test_app().await;

    let (status, body) = sync(&app).await;
    assert_eq!(status, 500);
    // 錯誤訊息要帶路徑。只回「同步失敗」的話,NAS 沒掛載跟目錄打錯字長得一模一樣。
    let err = body["error"].as_str().unwrap_or_default();
    assert!(err.contains("/definitely/not/here"), "錯誤訊息沒帶路徑:{err}");
}

#[tokio::test]
async fn 同步需要管理員身分() {
    let out = OutDir::new("auth");
    let (app, _pool) = test_app().await;
    let (status, _) = request(&app, "POST", "/api/admin/gallery/sync", None, None).await;
    assert_eq!(status, 401);
    // 沒帶身分時連掃描都不該開始(掃 NAS 是有成本的操作)
    assert!(!out.has("manifest.json"));
}

#[tokio::test]
async fn 舊_manifest_裡的描述與縮圖雜湊會被保留() {
    let out = OutDir::new("preserve");
    let _tagger = failing_tagger().await;
    let (app, _pool) = test_app().await;

    // 先跑一次拿到正確結構,再手動塞進「只有人工才會有」的欄位
    sync(&app).await;
    let mut m = out.manifest();
    for p in m["photos"].as_array_mut().unwrap() {
        if p["id"] == "photo-a" {
            p["description"] = Value::from("我手寫的說明");
            p["thumbHash"] = Value::from("FggGDIIYdopqcGu4i3SQbhT3Vg==");
        }
    }
    std::fs::write(out.0.join("manifest.json"), serde_json::to_string_pretty(&m).unwrap()).unwrap();
    // 讓它非跑不可(否則會走 skip 那條,什麼都沒驗到)
    std::fs::remove_file(out.0.join("photo-a.webp")).unwrap();

    let (_, again) = sync(&app).await;
    assert_eq!(again["processed"], 1);

    let a = out.manifest();
    let a = a["photos"].as_array().unwrap().iter().find(|p| p["id"] == "photo-a").unwrap();
    // 這兩欄重編時產不出來,只能從舊 manifest 沿用。沖掉的話使用者手寫的說明
    // 會在某一次例行同步之後靜默消失。
    assert_eq!(a["description"], "我手寫的說明");
    assert_eq!(a["thumbHash"], "FggGDIIYdopqcGu4i3SQbhT3Vg==");
}