◉ClassyGitshadowzzh

link_preview.rs

link_preview.rs
//! 內文連結的 hover 預覽卡資料來源(自架,不外送讀者行為給第三方)。
//!
//! 哲學:不用 microlink/截圖服務——那會把「讀者 hover 了哪個連結」送到外部,且有速率限制。
//! 這裡只做「抓目標頁 HTML → 解 OpenGraph/meta → 存 SQLite 快取」,不需要 headless 瀏覽器。
//!
//! - `GET /api/link-preview?url=…`:回 { title, description, image, site_name, favicon }
//!   抓不到 og:image 時仍回標題/描述/favicon → 前端顯示「降級卡」。
//! - 快取表 `link_previews` 在 migrations(0001 建表)。
//!
//! ⚠️ 這裡回的 `image` / `favicon` 是站外的絕對網址,**前端不可以直接放進 `<img src>`**——
//! 那等於讓讀者的瀏覽器去連對方主機,對方就拿到讀者的 IP/UA/Referer,上面那條
//! 「不外送讀者行為」的哲學會在最後一步破功。前端一律走 `/api/image-proxy`
//! (見 LinkHoverPreview.tsx)。
//!
//! 安全(這支會用使用者提供的 URL 發出站外請求,是 SSRF 的典型面):
//!   1. 只允許 http/https
//!   2. 解析出的 IP 若落在私網/迴環/link-local/CGNAT → 拒絕
//!   3. 逾時 6s、不跟隨跨站重導超過 3 次、回應體上限 512KB(只需要 <head>)
//!   4. 失敗一律回 200 + 空欄位(前端顯示降級卡),不把上游錯誤細節外露

use std::time::Duration;

use axum::{
    Json,
    extract::{Query, State},
};
use serde::{Deserialize, Serialize};

use crate::{
    error::AppError,
    net_guard::{is_blocked_ip, validate_url},
    state::AppState,
};

/// 快取存活時間:7 天(站外頁面的 og 很少變)
const CACHE_TTL_SECS: i64 = 7 * 24 * 60 * 60;
/// 這個端點的 `Cache-Control: max-age`。30 分鐘=對齊前端 useQuery 的 staleTime,
/// 讓「重新整理後第一次 hover」不必再跑一趟後端(在這之前完全沒有這個標頭)。
const BROWSER_CACHE_SECS: i64 = 30 * 60;
/// 只讀前 512KB —— og meta 一定在 <head>,不必把整頁拉回來
const MAX_BODY_BYTES: usize = 512 * 1024;
const FETCH_TIMEOUT: Duration = Duration::from_secs(6);

#[derive(Debug, Deserialize)]
pub struct LinkPreviewQuery {
    pub url: String,
}

/// 快取列(抽成具名結構而非裸元組——clippy::type_complexity)
#[derive(Debug, sqlx::FromRow)]
struct CachedPreview {
    title: Option<String>,
    description: Option<String>,
    image: Option<String>,
    site_name: Option<String>,
    age_secs: i64,
}

#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct LinkPreviewResponse {
    /// 目標頁標題(og:title → twitter:title → <title>)
    pub title: Option<String>,
    /// 摘要(og:description → twitter:description → meta description)
    pub description: Option<String>,
    /// 預覽圖(og:image → twitter:image);沒有就是 None → 前端走降級卡
    pub image: Option<String>,
    /// 站名(og:site_name),沒有則退回 host
    pub site_name: Option<String>,
    /// favicon 的絕對網址(降級卡用)。優先取站方 `<link rel="icon">` 宣告的那支,
    /// 沒宣告才退回猜 `/favicon.ico`——後者很多站根本沒有(見 `link_icon_href`)。
    pub favicon: Option<String>,
}

/// 從 HTML <head> 擷取一個 meta 內容。用輕量掃描而非完整 DOM parser:
/// og 標籤格式穩定,且我們只讀前 512KB,正則掃描足夠且省一個依賴。
fn meta_content(html: &str, keys: &[&str]) -> Option<String> {
    for key in keys {
        // 同時容忍 property="og:x" 與 name="og:x",屬性順序也可能相反
        for pat in [
            format!(
                r#"(?is)<meta[^>]+(?:property|name)\s*=\s*["']{k}["'][^>]*content\s*=\s*["']([^"']*)["']"#,
                k = regex::escape(key)
            ),
            format!(
                r#"(?is)<meta[^>]+content\s*=\s*["']([^"']*)["'][^>]*(?:property|name)\s*=\s*["']{k}["']"#,
                k = regex::escape(key)
            ),
        ] {
            if let Ok(re) = regex::Regex::new(&pat)
                && let Some(c) = re.captures(html)
            {
                let v = c.get(1)?.as_str().trim();
                if !v.is_empty() {
                    return Some(decode_entities(v));
                }
            }
        }
    }
    None
}

fn title_tag(html: &str) -> Option<String> {
    let re = regex::Regex::new(r"(?is)<title[^>]*>(.*?)</title>").ok()?;
    let c = re.captures(html)?;
    let v = c.get(1)?.as_str().trim();
    (!v.is_empty()).then(|| decode_entities(v))
}

/// 只處理最常見的幾個實體(og 內容裡多半是 &amp; &quot; &#39;)
///
/// ⚠️ 這裡**不截斷**。以前它結尾有 `.chars().take(400)`,而 `meta_content` 是 og:image
/// 和標題/摘要共用的,於是那個「顯示用的長度上限」也套到了網址上。GitHub repo 頁的
/// og:image 是 719 個字的預簽章網址,砍到 400 剛好把 `X-Amz-SignedHeaders=ho` 從中間
/// 切斷 → 簽章失效 → 圖一律 401。截斷要留給真正的文字欄位,見 `clamp_text`。
fn decode_entities(s: &str) -> String {
    s.replace("&amp;", "&")
        .replace("&quot;", "\"")
        .replace("&#39;", "'")
        .replace("&apos;", "'")
        .replace("&lt;", "<")
        .replace("&gt;", ">")
        .replace("&nbsp;", " ")
}

/// 顯示用文字的長度上限。只給標題/摘要/站名——**不要用在網址上**。
fn clamp_text(s: &str) -> String {
    s.chars().take(400).collect()
}

/// `<link rel="…icon…" href="…">` 的 href。
///
/// 為什麼需要:預設的 `https://{host}/favicon.ico` 是**猜**的,而很多站沒有那支檔——
/// 實測 zed.dev 回 500,它宣告的是 `/favicon_black_16.png`。猜錯的後果是降級卡上
/// 掛一個破圖示(沒有 og:image 的站才會走到降級卡,所以特別顯眼)。
///
/// `rel` 的寫法很雜(`icon`/`shortcut icon`/`apple-touch-icon`/大小寫混用),
/// 所以用「含 icon 這個字」來認,跟 `meta_content` 一樣走輕量掃描不引入 DOM parser。
/// 取**第一個**符合的:站方通常把主要的那支寫在前面。
fn link_icon_href(html: &str) -> Option<String> {
    let re = regex::Regex::new(
        r#"(?is)<link[^>]+rel\s*=\s*["'][^"']*icon[^"']*["'][^>]*href\s*=\s*["']([^"']+)["']"#,
    )
    .ok()?;
    // 屬性順序也可能相反(href 在 rel 前面)
    let re2 = regex::Regex::new(
        r#"(?is)<link[^>]+href\s*=\s*["']([^"']+)["'][^>]*rel\s*=\s*["'][^"']*icon[^"']*["']"#,
    )
    .ok()?;
    let pick = |c: regex::Captures<'_>| c.get(1).map(|m| decode_entities(m.as_str().trim()));
    re.captures(html).and_then(pick).or_else(|| re2.captures(html).and_then(pick)).filter(|s| !s.is_empty())
}

/// 相對路徑 → 絕對 URL(og:image 常給相對路徑)
fn absolutize(base: &str, maybe_relative: &str) -> Option<String> {
    let b = reqwest::Url::parse(base).ok()?;
    b.join(maybe_relative).ok().map(|u| u.to_string())
}

/// 預簽章網址的到期時刻(Unix 秒);不是預簽章就回 None。
///
/// 為什麼需要這個:有些站的 og:image 指到帶簽章、會自己失效的網址。GitHub 的 repo 頁
/// 就是——`repository-images.githubusercontent.com/…?X-Amz-Expires=300`,五分鐘後回 401。
/// 這張表的 TTL 是 7 天,所以不看期限的話,存進去五分鐘後就開始供應死連結,供應七天。
///
/// 認得兩種寫法:
///   - SigV4(AWS S3/GCS):`X-Amz-Date=20260803T110407Z` + `X-Amz-Expires=300`
///     (Google 是同樣格式的 `X-Goog-` 前綴)
///   - 舊式 CloudFront/GCS 簽章:`Expires=<unix 秒>`
///
/// 認不出來就回 None=當作不會過期,行為與加這個函式之前相同。寧可漏判也不要誤判:
/// 誤判成「會過期」只會讓穩定的站白白重抓。
fn signed_image_expiry(url: &str) -> Option<i64> {
    let u = reqwest::Url::parse(url).ok()?;
    let q: std::collections::HashMap<_, _> = u.query_pairs().collect();

    // SigV4:簽章時刻 + 有效秒數
    for (date_key, exp_key) in [("X-Amz-Date", "X-Amz-Expires"), ("X-Goog-Date", "X-Goog-Expires")] {
        if let (Some(date), Some(exp)) = (q.get(date_key), q.get(exp_key))
            && let (Some(signed_at), Ok(secs)) = (parse_sigv4_date(date), exp.parse::<i64>())
        {
            return Some(signed_at + secs);
        }
    }

    // 舊式:Expires 直接就是 unix 秒。只認「看起來像近代時間戳」的值,避免把
    // `?Expires=0`(有些站用來表示不快取)或短數字誤當成期限。
    if let Some(v) = q.get("Expires")
        && let Ok(epoch) = v.parse::<i64>()
        && epoch > 1_000_000_000
    {
        return Some(epoch);
    }

    None
}

/// `20260803T110407Z` → Unix 秒。
///
/// 欄位自己切而不用 chrono 的 `parse_from_str`:後者會擋掉 2/31、把 `60` 秒當閏秒
/// 折回 59,跟原本「日只驗 1..=31、秒數直接加」的語意不同。
fn parse_sigv4_date(s: &str) -> Option<i64> {
    let b = s.as_bytes();
    if b.len() != 16 || b[8] != b'T' || b[15] != b'Z' {
        return None;
    }
    let num = |a: usize, z: usize| s.get(a..z)?.parse::<i64>().ok();
    let (y, mo, d) = (num(0, 4)?, num(4, 6)?, num(6, 8)?);
    let (h, mi, sec) = (num(9, 11)?, num(11, 13)?, num(13, 15)?);
    if !(1..=12).contains(&mo) || !(1..=31).contains(&d) || h > 23 || mi > 59 || sec > 60 {
        return None;
    }
    // 範圍上一行已經驗過,轉 u32 不會失敗
    let days = crate::util::days_from_civil(y, u32::try_from(mo).ok()?, u32::try_from(d).ok()?)?;
    Some(days * 86_400 + h * 3600 + mi * 60 + sec)
}

/// `GET /api/link-preview?url=…` —— 站內外連結的 hover 預覽資料。
/// 一律回 200:抓不到就回空欄位讓前端顯示降級卡(不讓上游錯誤變成前端的錯誤狀態)。
#[utoipa::path(
    get, path = "/api/link-preview", tag = "misc",
    params(("url" = String, Query, description = "要預覽的目標連結(http/https)")),
    responses((status = 200, body = LinkPreviewResponse, description = "預覽資料;抓不到時欄位為 null(前端顯示降級卡)"))
)]
pub async fn link_preview(
    State(state): State<AppState>,
    Query(q): Query<LinkPreviewQuery>,
) -> Result<PreviewResponse, AppError> {
    let Some((url, host)) = validate_url(&q.url) else {
        return Ok(with_cache_headers(LinkPreviewResponse::default(), 0));
    };

    // ── 快取命中就直接回 ──
    let cached: Option<CachedPreview> = sqlx::query_as(
        "SELECT title, description, image, site_name, \
         CAST(strftime('%s','now') AS INTEGER) - CAST(strftime('%s', fetched_at) AS INTEGER) AS age_secs \
         FROM link_previews WHERE url = ?",
    )
    .bind(&url)
    .fetch_optional(&state.pool)
    .await?;

    let now = now_epoch();
    if let Some(c) = cached
        && c.age_secs < CACHE_TTL_SECS
    {
        // 到期時刻是從存下來的網址現算的,不另存一欄。這樣寫的好處是「改這段程式之前就
        // 存進去的列」也一起適用——不必為了回填而動 schema,而且期限本來就是網址的
        // 函數,存起來只是同一件事的第二份真相。
        let image_expiry = c.image.as_deref().and_then(signed_image_expiry);
        // 圖是預簽章而且已經過期 → 往下走當作 miss 重抓。不這樣做的話,這一列會在剩下
        // 的 TTL 內一直供應一個回 401 的網址(GitHub repo 的 og:image 五分鐘就到期)。
        if image_expiry.is_none_or(|exp| exp > now) {
            return Ok(with_cache_headers(
                LinkPreviewResponse {
                    title: c.title,
                    description: c.description,
                    image: c.image,
                    site_name: c.site_name.or_else(|| Some(host.clone())),
                    favicon: Some(format!("https://{host}/favicon.ico")),
                },
                response_max_age(image_expiry, now),
            ));
        }
    }

    // ── 抓取(失敗一律降級,不回錯誤)──
    let client = reqwest::Client::builder()
        .timeout(FETCH_TIMEOUT)
        .redirect(reqwest::redirect::Policy::limited(3))
        .build()
        .map_err(AppError::Upstream)?;

    let fetch_with = |ua: &'static str| {
        let client = client.clone();
        let url = url.clone();
        async move {
            let resp = client.get(&url).header(reqwest::header::USER_AGENT, ua).send().await.ok()?;
            // 解析後的 peer IP 再擋一次(DNS rebinding / 域名指向私網)
            if let Some(addr) = resp.remote_addr()
                && is_blocked_ip(&addr.ip())
            {
                return None;
            }
            if !resp.status().is_success() {
                return None;
            }
            let ct =
                resp.headers().get(reqwest::header::CONTENT_TYPE).and_then(|v| v.to_str().ok()).unwrap_or("");
            if !ct.contains("text/html") && !ct.contains("application/xhtml") {
                return None;
            }
            let bytes = resp.bytes().await.ok()?;
            let slice = &bytes[..bytes.len().min(MAX_BODY_BYTES)];
            Some(String::from_utf8_lossy(slice).to_string())
        }
    };

    // 先用**誠實的** UA(表明自己是誰、附聯絡網址)。這是對站方有禮貌的做法,
    // 而且多數站接受。
    //
    // ⚠️ 但有一批站對非瀏覽器 UA 直接擋——實測 zed.dev 回 **404**(同一個網址用
    //   瀏覽器 UA 是 200)。那種情況下 title/description/image 全是 None,
    //   前台只剩一張空的降級卡,看起來就是「這個站的預覽壞了」。
    //   所以失敗時退回瀏覽器 UA 再試一次。這是 link unfurler 的常規做法
    //   (Slack/Discord 同樣行為),抓的也只是讀者自己 hover 的那個公開頁面。
    const HONEST_UA: &str = "Mozilla/5.0 (compatible; koimsurai-linkpreview/1.0; +https://koimsurai.com)";
    const BROWSER_UA: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 \
                              (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
    let fetched = match fetch_with(HONEST_UA).await {
        Some(html) => Some(html),
        None => fetch_with(BROWSER_UA).await,
    };

    let mut out = LinkPreviewResponse {
        site_name: Some(host.clone()),
        favicon: Some(format!("https://{host}/favicon.ico")),
        ..Default::default()
    };

    if let Some(html) = fetched {
        // 文字欄位才套長度上限;image 是網址,截斷會直接讓預簽章失效(見 decode_entities)
        out.title = meta_content(&html, &["og:title", "twitter:title"])
            .or_else(|| title_tag(&html))
            .as_deref()
            .map(clamp_text);
        out.description = meta_content(&html, &["og:description", "twitter:description", "description"])
            .as_deref()
            .map(clamp_text);
        out.image = meta_content(&html, &["og:image", "og:image:url", "twitter:image"])
            .and_then(|img| absolutize(&url, &img));
        if let Some(sn) = meta_content(&html, &["og:site_name"]) {
            out.site_name = Some(clamp_text(&sn));
        }
        // 站方自己宣告的 icon 優先於猜的 /favicon.ico——很多站根本沒有那支檔。
        // 實測 zed.dev/favicon.ico 是 500,它宣告的是 /favicon_black_16.png,
        // 於是沒有 og:image 的降級卡上就掛著一個破圖示。
        if let Some(icon) = link_icon_href(&html).and_then(|href| absolutize(&url, &href)) {
            out.favicon = Some(icon);
        }

        // 寫回快取(UPSERT;失敗不影響回應)
        let _ = sqlx::query(
            "INSERT INTO link_previews (url, title, description, image, site_name, fetched_at) \
             VALUES (?, ?, ?, ?, ?, datetime('now')) \
             ON CONFLICT(url) DO UPDATE SET \
               title = excluded.title, description = excluded.description, \
               image = excluded.image, site_name = excluded.site_name, \
               fetched_at = excluded.fetched_at",
        )
        .bind(&url)
        .bind(&out.title)
        .bind(&out.description)
        .bind(&out.image)
        .bind(&out.site_name)
        .execute(&state.pool)
        .await;
    }

    let image_expiry = out.image.as_deref().and_then(signed_image_expiry);
    Ok(with_cache_headers(out, response_max_age(image_expiry, now)))
}

use crate::util::now_secs as now_epoch;

/// 這次回應可以讓瀏覽器/CDN 留多久。
///
/// 平常是 `BROWSER_CACHE_SECS`(對齊前端 useQuery 的 staleTime)。但如果圖是預簽章、
/// 而且比那個還早到期,就縮到剩餘壽命——否則瀏覽器會拿著一份「圖已經死掉」的 JSON
/// 繼續用到 max-age 結束,等於把後端剛修好的問題原封搬到讀者的快取裡。
fn response_max_age(image_expires_at: Option<i64>, now: i64) -> i64 {
    match image_expires_at {
        Some(exp) => (exp - now).clamp(0, BROWSER_CACHE_SECS),
        None => BROWSER_CACHE_SECS,
    }
}

/// 回應型別:JSON 加上一個 `Cache-Control`。兩個 return 點都走這裡,型別才一致。
type PreviewResponse = ([(axum::http::HeaderName, String); 1], Json<LinkPreviewResponse>);

fn with_cache_headers(body: LinkPreviewResponse, max_age: i64) -> PreviewResponse {
    ([(axum::http::header::CACHE_CONTROL, format!("public, max-age={max_age}"))], Json(body))
}

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

    #[test]
    fn sigv4_日期換算成_unix_秒() {
        // 2026-08-03T11:04:07Z(實測 GitHub og:image 的簽章時刻)
        assert_eq!(parse_sigv4_date("20260803T110407Z"), Some(1_785_755_047));
        // 紀元起點,驗證換算沒有偏移
        assert_eq!(parse_sigv4_date("19700101T000000Z"), Some(0));
        // 閏日:2024 是閏年,2/29 必須算得出來
        assert_eq!(parse_sigv4_date("20240229T000000Z"), Some(1_709_164_800));
    }

    #[test]
    fn 格式不對就回_none_而不是猜一個時間() {
        for bad in [
            "20260803110407Z",  // 少了 T
            "20260803T110407",  // 少了 Z
            "20261303T110407Z", // 13 月
            "20260832T110407Z", // 32 日
            "20260803T250407Z", // 25 時
            "",
            "not-a-date",
        ] {
            assert_eq!(parse_sigv4_date(bad), None, "{bad} 應該判定為無效");
        }
    }

    #[test]
    fn 認得出預簽章網址的到期時刻() {
        // GitHub 的 og:image:SigV4,簽章當下 + 300 秒
        let gh = "https://repository-images.githubusercontent.com/x/y?X-Amz-Algorithm=AWS4-HMAC-SHA256\
                  &X-Amz-Date=20260803T110407Z&X-Amz-Expires=300&X-Amz-Signature=deadbeef";
        assert_eq!(signed_image_expiry(gh), Some(1_785_755_047 + 300));

        // Google 用同樣的格式、不同前綴
        let gcs = "https://storage.googleapis.com/b/o?X-Goog-Date=20260803T110407Z&X-Goog-Expires=600";
        assert_eq!(signed_image_expiry(gcs), Some(1_785_755_047 + 600));

        // 舊式:Expires 直接是 unix 秒
        assert_eq!(
            signed_image_expiry("https://cdn.example.com/a.jpg?Expires=1785755047"),
            Some(1_785_755_047)
        );
    }

    #[test]
    fn 一般圖片網址不該被判定成會過期() {
        // 這些是實測過的穩定網址,誤判只會讓它們白白每次重抓
        for stable in [
            "https://opengraph.githubassets.com/abc/owner/repo",
            "https://eu.simkl.in/posters/97/978264e8bbc2303_m.webp",
            "https://developer.mozilla.org/mdn-social-share.png",
            // Expires=0 是「不要快取」的慣用寫法,不是期限
            "https://cdn.example.com/a.jpg?Expires=0",
            // 短數字不可能是近代時間戳
            "https://cdn.example.com/a.jpg?Expires=300",
            // 有簽章但沒給期限 → 判不出來就別猜
            "https://cdn.example.com/a.jpg?X-Amz-Signature=deadbeef",
        ] {
            assert_eq!(signed_image_expiry(stable), None, "{stable} 不該被判定成會過期");
        }
    }

    #[test]
    fn og_image_的長網址不可以被截斷() {
        // 這條守的是實際發生過的事:decode_entities 以前結尾有 .chars().take(400),
        // 而 meta_content 是文字欄位與 og:image 共用的,於是 719 個字的 GitHub 預簽章
        // 網址被砍成 400,X-Amz-SignedHeaders 從中間斷掉 → 圖一律 401。
        let long_url = format!(
            "https://repository-images.githubusercontent.com/{}?X-Amz-Algorithm=AWS4-HMAC-SHA256\
             &X-Amz-Credential={}&X-Amz-Date=20260803T110407Z&X-Amz-Expires=300\
             &X-Amz-Signature={}&X-Amz-SignedHeaders=host",
            "a".repeat(120),
            "b".repeat(120),
            "c".repeat(64),
        );
        assert!(long_url.len() > 400, "測試樣本要比舊上限長才有意義({})", long_url.len());

        let html = format!(r#"<meta property="og:image" content="{}">"#, long_url.replace('&', "&amp;"));
        let got = meta_content(&html, &["og:image"]).expect("該抓得到 og:image");
        assert_eq!(got, long_url, "網址被動過了");
        assert!(got.ends_with("SignedHeaders=host"), "結尾被截掉:{}", &got[got.len() - 40..]);
    }

    #[test]
    fn 文字欄位仍然有長度上限() {
        // 截斷本身是對的,只是不該套在網址上
        assert_eq!(clamp_text(&"字".repeat(500)).chars().count(), 400);
        assert_eq!(clamp_text("短"), "短");
        // 以字元計,不是位元組——切在多位元組字元中間會 panic
        assert_eq!(clamp_text(&"é".repeat(500)).chars().count(), 400);
    }

    #[test]
    fn max_age_會被圖片的剩餘壽命壓下來() {
        let now = 1_785_755_047;
        // 沒有期限 → 用預設值
        assert_eq!(response_max_age(None, now), BROWSER_CACHE_SECS);
        // 圖比預設值晚到期 → 還是預設值(不會超過)
        assert_eq!(response_max_age(Some(now + 99_999), now), BROWSER_CACHE_SECS);
        // 圖 5 分鐘後到期 → 只能讓瀏覽器留 5 分鐘,否則它會拿著死連結用滿 30 分
        assert_eq!(response_max_age(Some(now + 300), now), 300);
        // 已經過期 → 0,不是負數(負數會產生無效的標頭值)
        assert_eq!(response_max_age(Some(now - 1), now), 0);
    }

    #[test]
    fn 相對路徑的_og_image_會補成絕對網址() {
        // og:image 給相對路徑很常見。不補的話前端拿到 "/img/a.png" 丟給
        // image-proxy,proxy 解不出 host 就整張圖不見——而卡片其他欄位都正常,
        // 看起來只像「這個站沒有預覽圖」
        let base = "https://example.com/blog/post-1?x=1";
        assert_eq!(absolutize(base, "/img/a.png").as_deref(), Some("https://example.com/img/a.png"));
        assert_eq!(absolutize(base, "cover.png").as_deref(), Some("https://example.com/blog/cover.png"));
        assert_eq!(
            absolutize(base, "//cdn.example.com/a.png").as_deref(),
            Some("https://cdn.example.com/a.png")
        );
        // 已經是絕對網址就原樣返回(join 的語義)
        assert_eq!(absolutize(base, "https://other.test/a.png").as_deref(), Some("https://other.test/a.png"));
        // base 壞掉就回 None,不要拼出一個怪東西
        assert_eq!(absolutize("не-url", "/a.png"), None);
    }

    #[test]
    fn meta_容忍屬性順序顛倒_也吃得到_title_標籤() {
        // 這兩條走的是 meta_content 的第二個樣式與 title_tag 的退路。
        // 少了它們,某些站的卡片會只剩網域名——而不會有任何錯誤
        let reversed = r#"<meta content="倒著寫的標題" property="og:title">"#;
        assert_eq!(meta_content(reversed, &["og:title"]).as_deref(), Some("倒著寫的標題"));

        // 完全沒有 og:title 時退回 <title>
        let only_title = "<html><head><title>  純 title 標籤  </title></head></html>";
        assert_eq!(meta_content(only_title, &["og:title"]), None);
        assert_eq!(title_tag(only_title).as_deref(), Some("純 title 標籤"), "要 trim");

        // 空的 content 不算數,要繼續找下一個 key
        let empty_first =
            r#"<meta property="og:title" content="  "><meta name="twitter:title" content="備用">"#;
        assert_eq!(meta_content(empty_first, &["og:title", "twitter:title"]).as_deref(), Some("備用"));
        // 空的 <title> 也一樣不算
        assert_eq!(title_tag("<title>   </title>"), None);
    }

    // ── 端點本體(快取那一側)─────────────────────────────────────────
    //
    // 抓取那一段測不到——net_guard 會擋掉任何 loopback 位址,而本機跑得起來的
    // mock server 位址依定義就落在被擋的網段裡(127.0.0.2 還是 loopback,
    // docker bridge 的 172.17.x 是私網)。要測就得在 SSRF 守衛上開一個全域關閉
    // 開關,而那正是 cargo-mutants 證明過「壞了會安靜地壞」的那個函式,不划算。
    //
    // 但快取那一側完全不需要網路,而且它壞掉的症狀同樣是安靜的:
    // hover 卡永遠是舊的、或每次 hover 都重抓。以下都走 DB。

    use crate::state::AppState;
    use axum::extract::{Query, State};

    /// 直接呼叫 handler(不經 router),回 (Cache-Control 的秒數, body)。
    async fn preview(state: &AppState, url: &str) -> (i64, LinkPreviewResponse) {
        let ([(_, cc)], Json(body)) =
            link_preview(State(state.clone()), Query(LinkPreviewQuery { url: url.into() }))
                .await
                .expect("這支永遠回 200");
        let secs = cc.rsplit_once('=').expect("max-age=N").1.parse().expect("秒數是數字");
        (secs, body)
    }

    /// 塞一列快取。`age_secs` 是「幾秒前抓的」。
    async fn cache_row(state: &AppState, url: &str, image: Option<&str>, age_secs: i64) {
        sqlx::query(
            "INSERT INTO link_previews (url, title, description, image, site_name, fetched_at) \
             VALUES (?, '快取標題', '快取描述', ?, ?, datetime('now', ?))",
        )
        .bind(url)
        .bind(image)
        .bind(Option::<&str>::None) // site_name 留空,驗它會退回 host
        .bind(format!("-{age_secs} seconds"))
        .execute(&state.pool)
        .await
        .unwrap();
    }

    #[tokio::test]
    async fn 快取命中就直接回_不碰網路() {
        let state = crate::state::test_state().await;
        let url = "https://example.com/a";
        cache_row(&state, url, Some("https://cdn.example.com/a.png"), 60).await;

        let (max_age, body) = preview(&state, url).await;
        assert_eq!(body.title.as_deref(), Some("快取標題"));
        assert_eq!(body.description.as_deref(), Some("快取描述"));
        assert_eq!(body.image.as_deref(), Some("https://cdn.example.com/a.png"));
        // 存的時候 site_name 是 NULL → 回應要退回 host,而不是給前端一個 null
        assert_eq!(body.site_name.as_deref(), Some("example.com"));
        assert_eq!(body.favicon.as_deref(), Some("https://example.com/favicon.ico"));
        // 一般圖片沒有期限 → 用預設的 30 分鐘
        assert_eq!(max_age, BROWSER_CACHE_SECS);
    }

    #[tokio::test]
    async fn 快取過期就當作沒有() {
        let state = crate::state::test_state().await;
        // TTL 是 7 天。超過就要重抓,而這裡的重抓必定失敗,所以驗的是
        // 「沒有拿舊的那列來回」。
        //
        // ⚠ 網域刻意用 `.invalid`:那是 RFC 2606 保留的頂級網域,保證不會被註冊,
        //   DNS 查詢立刻 NXDOMAIN。用 example.com 之類的話這條測試會**真的對外
        //   發一個請求**——CI 上可能成功、可能因為對方改版而改變行為,那種測試
        //   的結果取決於別人的服務今天怎麼樣。
        let url = "https://expired.invalid/a";
        cache_row(&state, url, None, CACHE_TTL_SECS + 60).await;

        let (_, body) = preview(&state, url).await;
        assert!(body.title.is_none(), "過期的那列不該被拿來用:{:?}", body.title);
        // 抓不到也要給降級卡的兩個欄位,前端才有東西可以顯示
        assert_eq!(body.site_name.as_deref(), Some("expired.invalid"));
        assert_eq!(body.favicon.as_deref(), Some("https://expired.invalid/favicon.ico"));
    }

    #[tokio::test]
    async fn 預簽章的圖過期時_整列當作_miss_重抓() {
        let state = crate::state::test_state().await;
        // 這是 GitHub repo 卡片踩過的:og:image 五分鐘就到期,但這張表的 TTL 是 7 天。
        // 不看圖的期限的話,這一列會在剩下的 TTL 內一直供應一個回 401 的網址——
        // 讀者看到的是破圖,而後端每次都「快取命中」,log 上完全正常
        let now = now_epoch();
        let dead = format!(
            "https://repository-images.githubusercontent.com/x?X-Amz-Date={}&X-Amz-Expires=1",
            sigv4_at(now - 3600)
        );
        let url = "https://github.invalid/owner/repo";
        cache_row(&state, url, Some(&dead), 60).await; // 列本身還很新

        let (_, body) = preview(&state, url).await;
        assert!(body.title.is_none(), "圖死掉時整列要當 miss,不能只回舊資料");
    }

    #[tokio::test]
    async fn 預簽章的圖還活著時_max_age_縮到剩餘壽命() {
        let state = crate::state::test_state().await;
        let now = now_epoch();
        // 還有約 120 秒可活
        let alive = format!(
            "https://repository-images.githubusercontent.com/x?X-Amz-Date={}&X-Amz-Expires=300",
            sigv4_at(now - 180)
        );
        let url = "https://example.com/live";
        cache_row(&state, url, Some(&alive), 60).await;

        let (max_age, body) = preview(&state, url).await;
        assert_eq!(body.title.as_deref(), Some("快取標題"), "圖還活著就該命中快取");
        // 讓瀏覽器留滿 30 分鐘的話,它會拿著一份「圖已經死掉」的 JSON 用到最後
        assert!((100..=120).contains(&max_age), "max-age 應該貼著圖的剩餘壽命,得到 {max_age}");
    }

    #[tokio::test]
    async fn 擋下來的網址回空卡而且不給快取() {
        let state = crate::state::test_state().await;
        for bad in [
            "http://127.0.0.1/x",
            "http://169.254.169.254/latest/meta-data/",
            "http://localhost/x",
            "file:///etc/passwd",
            "javascript:alert(1)",
            "не-url",
        ] {
            let (max_age, body) = preview(&state, bad).await;
            // 回 200 + 空欄位是刻意的:前端顯示降級卡,不要因為一個 hover 就跳錯誤
            assert!(body.title.is_none(), "{bad} 不該有內容");
            assert!(body.site_name.is_none(), "{bad} 連 host 都不該回——那會洩漏被擋的目標");
            // max-age=0:被擋的判斷結果不值得快取
            assert_eq!(max_age, 0, "{bad} 不該讓瀏覽器記住");
        }
    }

    /// Unix 秒 → SigV4 的 `YYYYMMDDThhmmssZ`(`parse_sigv4_date` 的反函式,測試用)。
    fn sigv4_at(epoch: i64) -> String {
        chrono::DateTime::from_timestamp(epoch, 0).unwrap().format("%Y%m%dT%H%M%SZ").to_string()
    }

    #[test]
    fn sigv4_at_與_parse_互為反函式() {
        // 上面三條測試都靠 sigv4_at 造資料。它自己錯了的話,那三條會用一個
        // 錯誤的時間戳去驗「圖有沒有過期」——測試照樣綠,但驗的是別的東西
        for epoch in [0, 1_785_755_047, 1_709_164_800, 946_684_800] {
            assert_eq!(parse_sigv4_date(&sigv4_at(epoch)), Some(epoch), "epoch={epoch}");
        }
    }
}