//! 分享圖(`GET /api/og/{file}?l=<語系>`)。
//!
//! - `/api/og/<文章 id>.png`:文章。背景是手記的星軌,亮的是這一篇自己那道。
//! - `/api/og/<頁>.png`:各頁(`PAGES`)。背景是那一頁自己的畫面(`og/scenes/`)。
//!
//! 每張都是 APNG:背景逐格畫(`scenes`)、字那一層用 takumi 排一次、疊起來編碼(`apng`)。
//! 字的語系照 `?l=`,頁名與副標直接讀前端的 `src/locales/*/common.json`,不另外抄一份。
//!
//! ## 為什麼字用 takumi 排
//!
//! 舊版手工組 SVG 字串再光柵化,而 SVG **沒有排版引擎**——`<text>` 不會換行,自己算斷行的
//! 那份程式在線上產出過壞圖:逗號被推到行首、`CTranslate2` 被切在字母中間、英文標題 56 個字
//! 只顯示 48 個(它數字元不數寬度)。takumi 內含 taffy(flexbox)、parley(文字排版)與
//! icu_segmenter(斷行規則),這些都由引擎處理。
//!
//! ## 字型
//!
//! ⚠ takumi **不吃系統字型**。CJK 一定要自己註冊,否則中文全部變成豆腐——而且**不會報錯**,
//! 只是圖裡沒有字。容器裡的 `fonts-noto-cjk` 仍然要裝,只是改由我們讀檔案。見 `load_fonts`。
mod apng;
mod canvas;
mod scenes;
use std::collections::HashMap;
use std::sync::{Arc, LazyLock};
use axum::{
extract::{Path, Query, State},
http::{HeaderMap, StatusCode, header},
response::{IntoResponse, Response},
};
use parking_lot::Mutex;
use serde::Deserialize;
use takumi::prelude::*;
use crate::handlers::posts::{parse_locale, sky_list};
use crate::state::AppState;
// 模板是字串組裝,所以標題要轉義(改用 node tree 就不需要,但模板會變成一大串 builder 呼叫)
use crate::util::escape_html;
use scenes::{
About, Collection, Colophon, Friends, Log, Messages, Moments, Notes, Photos, Saturn, Scene, Setup,
SkyPost, Works,
};
/// 主標與副標:跟前端 `lib/blogReading.ts` 的 `splitTitle` 同一套規則——全形冒號,
/// 或半形冒號後面接空白(`Rust 1.85:2024` 那種不拆)。兩邊任一段是空的就不拆
fn split_title(title: &str) -> (&str, Option<&str>) {
let cut = title.char_indices().find_map(|(i, c)| match c {
':' => Some((i, c.len_utf8())),
':' if title[i + 1..].starts_with(char::is_whitespace) => Some((i, 1)),
_ => None,
});
let Some((at, len)) = cut else { return (title, None) };
let (main, sub) = (title[..at].trim(), title[at + len..].trim());
if main.is_empty() || sub.is_empty() { (title, None) } else { (main, Some(sub)) }
}
// ── 語系 ───────────────────────────────────────────────────────
/// 站上的五個語系 → 語系檔、takumi 的語言標記、Noto CJK 裡對應的字形版本
/// (同一個字在繁中、簡中、日文、韓文的寫法不一樣,`.ttc` 裡四套都有)
struct Locale {
code: &'static str,
json: &'static str,
lang: &'static str,
cjk: &'static str,
}
const LOCALES: [Locale; 5] = [
Locale {
code: "zh-TW",
json: include_str!("../../../src/locales/zh-TW/common.json"),
lang: "zh-Hant",
cjk: "TC",
},
Locale {
code: "zh-CN",
json: include_str!("../../../src/locales/zh-CN/common.json"),
lang: "zh-Hans",
cjk: "SC",
},
Locale { code: "en", json: include_str!("../../../src/locales/en/common.json"), lang: "en", cjk: "TC" },
Locale { code: "ja", json: include_str!("../../../src/locales/ja/common.json"), lang: "ja", cjk: "JP" },
Locale { code: "ko", json: include_str!("../../../src/locales/ko/common.json"), lang: "ko", cjk: "KR" },
];
static STRINGS: LazyLock<HashMap<&'static str, serde_json::Value>> = LazyLock::new(|| {
LOCALES
.iter()
.map(|l| {
(
l.code,
serde_json::from_str(l.json).expect("src/locales 的 JSON 由前端的測試把關,壞了編不到這裡"),
)
})
.collect()
});
fn locale_of(code: &str) -> &'static Locale {
LOCALES.iter().find(|l| l.code == code).unwrap_or(&LOCALES[0])
}
/// 語系檔裡 `a.b.c` 那一條;這個語系沒有就退回繁中
fn text(locale: &str, key: &str) -> String {
let find = |code: &str| {
let mut v = STRINGS.get(code)?;
for part in key.split('.') {
v = v.get(part)?;
}
v.as_str().map(str::to_string)
};
find(locale).or_else(|| find("zh-TW")).unwrap_or_default()
}
// ── 頁面 ───────────────────────────────────────────────────────
/// 有分享圖的頁:網址上的名字、頁名(語系檔的 key)、頁名旁那行等寬英文(`data/siteSections.ts`
/// 的 caps)、副標(頁面上那一句,都是站長自己寫的)。前端的 `seo/seoMeta.ts` 用同一組名字
struct Page {
key: &'static str,
name: &'static str,
caps: &'static str,
sub: &'static str,
}
const PAGES: [Page; 12] = [
Page { key: "home", name: "", caps: "KOIMSURAI", sub: "og.tagline" },
Page { key: "notes", name: "siteNav.notes", caps: "NOTES", sub: "blog.subtitle" },
Page { key: "moments", name: "siteNav.moments", caps: "MOMENTS", sub: "thinking.subtitle" },
Page { key: "works", name: "siteNav.works", caps: "WORK", sub: "works.subtitle" },
Page { key: "collection", name: "siteNav.collection", caps: "COLLECTION", sub: "collection.subtitle" },
Page { key: "about", name: "siteNav.aboutAll", caps: "ABOUT", sub: "aboutFall.title" },
Page { key: "setup", name: "siteNav.setup", caps: "SETUP", sub: "setup.subtitle" },
Page { key: "log", name: "siteNav.log", caps: "LOG", sub: "log.subtitle" },
Page { key: "messages", name: "siteNav.messages", caps: "MESSAGES", sub: "messages.subtitle" },
Page { key: "photos", name: "siteNav.photos", caps: "PHOTOS", sub: "photos.subtitle" },
Page { key: "friends", name: "siteNav.friends", caps: "FRIENDS", sub: "friends.subtitle" },
Page { key: "colophon", name: "siteNav.colophon", caps: "COLOPHON", sub: "colophon.subtitle" },
];
/// 不需要資料的背景,整個進程算一次
static SATURN: LazyLock<Saturn> = LazyLock::new(Saturn::new);
// ── 字那一層 ───────────────────────────────────────────────────
/// 一張卡上的字。`kicker` 是標題上面那行琥珀色的小字(分類 · 日期,或頁名的英文)
struct Card<'a> {
kicker: &'a str,
title: &'a str,
sub: Option<&'a str>,
/// 左上角要不要寫站名:首頁那張的大標就是站名,只留網址
brand: bool,
/// Noto CJK 的字形版本(TC/SC/JP/KR)
cjk: &'a str,
}
/// 字那一層的 HTML:**底是透明的**,背景由 `scenes` 逐格畫好再疊上來。
/// 版面照設計畫布的 OgImage(字在左、圖在右),字型與顏色照翻新後的站:
/// 思源宋體(容器裡是同一套字的 Noto Serif CJK)、暖白字、琥珀色的 Fira Code 小字。
///
/// ⚠ 根節點要自己撐滿畫布(`width/height: 100%`)——takumi 不會替你做,
/// 忘了的話內容會擠在左上角。
///
/// ⚠ 省略號要靠 `text-overflow: ellipsis`,**不是** `line-clamp` 自己加的。
/// 這是試出來的,三種寫法的實際結果:
/// `line-clamp:3` 單獨用 → 正確截成三行,但**沒有省略號**
/// `max-lines:3; block-ellipsis:auto` → 完全沒截,變五行把頁尾擠出畫面
/// `…; continue:discard` → 整段 style 被丟掉(字級/顏色全失效)
/// 所以是 `line-clamp` + `text-overflow:ellipsis`。動這兩行之前先跑 `產生樣張`。
///
/// 讓背景在字底下淡掉的那片漸層不在這裡,在 `apng::compose`:見那邊的註解。
fn build_html(card: &Card) -> String {
let serif = format!("'Noto Serif CJK {}'", card.cjk);
let sans = format!("'Noto Sans CJK {}'", card.cjk);
let brand = if card.brand {
format!(
r#"<span style="font-family:{serif}; font-size:30px; font-weight:700; color:#f1ece3;">宙と木</span>"#
)
} else {
String::new()
};
let sub = card.sub.map_or_else(String::new, |s| {
format!(
r#"<div style="font-size:26px; line-height:1.45; color:rgba(241,236,227,0.7); line-clamp:2; text-overflow:ellipsis;">{}</div>"#,
escape_html(s)
)
});
format!(
r#"<div style="width:100%; height:100%; display:flex; position:relative; font-family:{serif};">
<div style="position:absolute; left:72px; top:64px; bottom:64px; width:620px;
display:flex; flex-direction:column; justify-content:space-between;">
<div style="display:flex; flex-direction:row; align-items:baseline; gap:14px;">
{brand}
<span style="font-family:'Fira Code'; font-size:15px; letter-spacing:0.16em; color:rgba(241,236,227,0.45);">koimsurai.com</span>
</div>
<div style="display:flex; flex-direction:column; gap:20px;">
<div style="font-family:'Fira Code',{sans}; font-size:18px; letter-spacing:0.12em; color:#e9c17a;">{kicker}</div>
<div style="font-size:54px; font-weight:700; line-height:1.25; color:#f1ece3; line-clamp:3; text-overflow:ellipsis; text-wrap:balance;">{title}</div>
{sub}
</div>
</div>
</div>"#,
kicker = escape_html(card.kicker),
title = escape_html(card.title.trim()),
)
}
/// 文章的卡:分類是空的時候退回「手記」那個字,日期寫成 `2026/10/13`
fn post_card_html(title: &str, category: Option<&str>, date: &str, locale: &str) -> String {
let fallback = text(locale, "siteNav.notes");
let cat = category.filter(|c| !c.is_empty()).unwrap_or(&fallback);
let date = date.replace('-', "/");
let kicker = if date.is_empty() { cat.to_string() } else { format!("{cat} · {date}") };
let (main, sub) = split_title(title.trim());
build_html(&Card { kicker: &kicker, title: main, sub, brand: true, cjk: locale_of(locale).cjk })
}
fn page_card_html(page: &Page, locale: &str) -> String {
let home = page.name.is_empty();
let title = if home { "宙と木".to_string() } else { text(locale, page.name) };
let sub = text(locale, page.sub);
build_html(&Card {
kicker: page.caps,
title: &title,
sub: Some(sub.as_str()).filter(|s| !s.is_empty()),
brand: !home,
cjk: locale_of(locale).cjk,
})
}
// ── 字型與產圖 ─────────────────────────────────────────────────
/// Debian 的 `fonts-noto-cjk` 裝出來的路徑。標題是宋體 700、分類那行的中文退回黑體。
/// 每個字重都要有檔案——少了的話 takumi 會用合成粗體(font-synthesis),中文的合成粗體很糊。
///
/// ⚠ 這裡刻意**不 panic**。字型讀不到時仍然要能出圖,只是中文會變豆腐——
/// 而那至少還看得出「圖有產出、字型掛了」,比整條端點 500 好查。
const CJK_FONTS: [&str; 3] = [
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc",
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
];
/// 分類、日期、網址那幾行的等寬字,跟站上同一套(`@fontsource-variable/fira-code` 的拉丁子集,
/// 授權 OFL,見同目錄的 FiraCode-OFL.txt)。只有 35 KB,直接編進執行檔,不用動容器
const FIRA_CODE: &[u8] = include_bytes!("../../assets/fonts/FiraCode-latin.woff2");
fn load_fonts() -> Fonts {
let mut fonts = Fonts::default();
if let Err(e) = fonts.register(FontResource::new(FIRA_CODE.to_vec())) {
tracing::error!("[OG] Fira Code 註冊失敗: {e}");
}
let mut loaded = 0usize;
for path in CJK_FONTS {
match std::fs::read(path) {
// register 回傳它註冊到的 family 清單(.ttc 一個檔可能含多個),這裡只在意成敗
Ok(bytes) => match fonts.register(FontResource::new(bytes)) {
Ok(families) => {
tracing::info!("[OG] 載入字型 {path}({} 個 family)", families.len());
loaded += 1;
}
Err(e) => tracing::error!("[OG] 字型註冊失敗 {path}: {e}"),
},
Err(e) => tracing::error!("[OG] 讀不到字型 {path}: {e}"),
}
}
if loaded == 0 {
// 這一行要夠大聲:症狀是「OG 圖裡的中文全變方框」,而端點仍然回 200
tracing::error!("[OG] 一個 CJK 字型都沒載到——OG 圖的中文會是豆腐。容器裝了 fonts-noto-cjk 嗎?");
}
fonts
}
static FONTS: LazyLock<Fonts> = LazyLock::new(load_fonts);
/// 字那一層,RGBA(非預乘),底是透明的。
///
/// ⚠ `lang` **不會**消掉 render 時 stderr 上那幾行 `ICU4X data error: No segmentation model
/// for language: ja`——那是 parley 在字型層決定語言標記時發出的,跟這裡是兩條路徑。它是無害的:
/// 斷行仍然正確,缺的只是日文的「詞典式斷詞」。分享圖有快取,每張實際只會 render 一次。
fn render_overlay(html: &str, locale: &str) -> anyhow::Result<Vec<u8>> {
let node = Node::from_html(html, FromHtmlOptions::default())
.map_err(|e| anyhow::anyhow!("takumi from_html: {e}"))?;
let options = RenderOptions::builder()
.viewport(Viewport::new(apng::SIZE))
.node(node)
.fonts(&FONTS)
.lang(Lang::parse(locale_of(locale).lang).ok())
.build();
let image = takumi::render(options).map_err(|e| anyhow::anyhow!("takumi render: {e}"))?;
let raw = image.into_raw();
anyhow::ensure!(raw.len() == apng::W * apng::H * 4, "takumi 畫出來的尺寸不對({} bytes)", raw.len());
Ok(raw)
}
/// 字 → 疊在每一格背景上 → APNG(CPU 密集,呼叫端丟 spawn_blocking)
fn render(html: &str, locale: &str, scene: &dyn Scene) -> anyhow::Result<Vec<u8>> {
let overlay = render_overlay(html, locale)?;
apng::encode(scene.frames(), scene.frame_ms(), |i| apng::compose(&scene.frame(i), &overlay))
}
/// 這一頁的背景。`sky` 是手記星軌要用的文章清單(只有 notes 用得到)
fn page_scene(key: &str, sky: &[SkyPost]) -> Box<dyn Scene> {
match key {
"notes" => Box::new(Notes::new(sky, 0)),
"about" => Box::new(About::new()),
"log" => Box::new(Log::new()),
"works" => Box::new(Works::new()),
"colophon" => Box::new(Colophon::new()),
"setup" => Box::new(Setup::new()),
"messages" => Box::new(Messages::new()),
"moments" => Box::new(Moments::new()),
"friends" => Box::new(Friends::new()),
"collection" => Box::new(Collection::new()),
"photos" => Box::new(Photos::new()),
// 首頁(PAGES 以外的名字進不到這裡)
_ => Box::new(SaturnRef),
}
}
/// 把共用的那顆土星包成 `Box<dyn Scene>`(它本身是 static,不能搬進 Box)
struct SaturnRef;
impl Scene for SaturnRef {
fn frames(&self) -> usize {
SATURN.frames()
}
fn frame_ms(&self) -> u32 {
SATURN.frame_ms()
}
fn frame(&self, index: usize) -> tiny_skia::Pixmap {
SATURN.frame(index)
}
}
// ── 快取與 HTTP ────────────────────────────────────────────────
struct CachedOg {
png: Arc<Vec<u8>>,
etag: String,
/// 內容的指紋:標題、時間戳、文章清單一變就不一樣,快取跟著失效
key: String,
}
/// 一個「位置」(哪一篇或哪一頁 × 語系)一張。動畫一張約幾百 KB;沒有上限的話只會長不會縮
static CACHE: LazyLock<Mutex<HashMap<String, CachedOg>>> = LazyLock::new(|| Mutex::new(HashMap::new()));
const CACHE_MAX: usize = 64;
/// ETag 用的雜湊。FNV-1a:不需要相依、跨版本永遠決定性(ETag 會被客戶端與 CDN
/// 存著,換 Rust 版本就變值的話等於每次升級都讓全站的圖失效)。
///
/// ⚠️ 這裡原本是 `base64(cacheKey).slice(0, 12)`(照抄 Express)。那是**壞的**:
/// 12 個 base64 字元只編碼 9 個 byte,標題與大部分時間戳從來沒有進入 ETag,
/// 改標題前後算出來是同一個值 → 讀者拿到 304、一直看到舊圖。
fn fnv1a(s: &str) -> u64 {
let mut h: u64 = 0xcbf2_9ce4_8422_2325;
for b in s.as_bytes() {
h ^= u64::from(*b);
h = h.wrapping_mul(0x1000_0000_01b3);
}
h
}
fn text_resp(code: StatusCode, body: &'static str) -> Response {
(code, [(header::CONTENT_TYPE, "text/html; charset=utf-8")], body).into_response()
}
fn png_resp(png: &[u8], etag: String) -> Response {
(
[
(header::CONTENT_TYPE, "image/png".to_string()),
(header::ETAG, etag),
(header::CACHE_CONTROL, "public, max-age=300, s-maxage=86400".to_string()),
],
png.to_vec(),
)
.into_response()
}
#[derive(Deserialize)]
pub struct OgQuery {
/// 語系(zh-TW/zh-CN/en/ja/ko),沒給或不認得就是繁中
l: Option<String>,
}
/// 文章清單 → 星軌參數,加上清單的指紋(新文章、改標題都會讓手記的那片天不一樣)
fn sky_of(list: &[(i64, String, usize)]) -> (Vec<SkyPost>, u64) {
let max_len = list.iter().map(|p| p.2).max().unwrap_or(1);
let sky = list.iter().map(|(_, t, n)| SkyPost::of(t, *n, max_len)).collect();
let sig = fnv1a(&list.iter().map(|(id, t, n)| format!("{id}:{n}:{t}")).collect::<Vec<_>>().join("|"));
(sky, sig)
}
/// `GET /api/og/{file}`(axum 不支援 `:id.png` 部分參數)——非 `.png` 後綴、不認得的頁回 404。
#[utoipa::path(get, path = "/api/og/{file}", tag = "media",
params(("file" = String, Path, description = "`<文章 id>.png` 或 `<頁>.png`"), ("l" = Option<String>, Query, description = "語系")),
responses((status = 200, description = "分享圖(APNG)"), (status = 304, description = "Not Modified(ETag 命中)"), (status = 404, description = "找不到"), (status = 500, description = "產生失敗")))]
pub async fn og_png(
State(state): State<AppState>,
Path(file): Path<String>,
Query(q): Query<OgQuery>,
headers: HeaderMap,
) -> Response {
let Some(stem) = file.strip_suffix(".png") else {
return text_resp(StatusCode::NOT_FOUND, "not found");
};
let locale = parse_locale(q.l.as_deref()).unwrap_or("zh-TW");
let inm = headers.get(header::IF_NONE_MATCH).and_then(|v| v.to_str().ok()).map(String::from);
// 位置、內容指紋、字那一層的 HTML、背景
let prepared = if let Ok(id) = stem.parse::<i64>() {
prepare_post(&state, id, locale).await
} else if let Some(page) = PAGES.iter().find(|p| p.key == stem) {
Some(prepare_page(&state, page, locale).await)
} else {
None
};
let Some((slot, key, html, scene)) = prepared else {
return text_resp(StatusCode::NOT_FOUND, "not found");
};
if let Some(c) = CACHE.lock().get(&slot).filter(|c| c.key == key) {
if inm.as_deref() == Some(c.etag.as_str()) {
return StatusCode::NOT_MODIFIED.into_response();
}
return png_resp(&c.png, c.etag.clone());
}
let loc = locale.to_string();
let png = match tokio::task::spawn_blocking(move || render(&html, &loc, scene.as_ref())).await {
Ok(Ok(p)) => Arc::new(p),
Ok(Err(e)) => {
tracing::error!("[OG] 產圖失敗 ({slot}): {e}");
return text_resp(StatusCode::INTERNAL_SERVER_ERROR, "og generation failed");
}
Err(e) => {
tracing::error!("[OG] 產圖 task 掛了 ({slot}): {e}");
return text_resp(StatusCode::INTERNAL_SERVER_ERROR, "og generation failed");
}
};
let etag = format!("\"og-{:016x}\"", fnv1a(&format!("{slot}::{key}")));
{
let mut cache = CACHE.lock();
// 滿了就隨便丟一張(不追蹤誰最久沒用):被丟掉的那張下次再算一次就好
if cache.len() >= CACHE_MAX
&& !cache.contains_key(&slot)
&& let Some(evict) = cache.keys().next().cloned()
{
cache.remove(&evict);
}
cache.insert(slot, CachedOg { png: png.clone(), etag: etag.clone(), key });
}
png_resp(&png, etag)
}
/// 位置、內容指紋、字那一層的 HTML、背景
type Prepared = (String, String, String, Box<dyn Scene>);
async fn prepare_post(state: &AppState, id: i64, locale: &str) -> Option<Prepared> {
let (post_id, title, category, created_at, updated_at) = sqlx::query_as::<
_,
(i64, Option<String>, Option<String>, Option<String>, Option<String>),
>(
// 只畫已發佈的:分享圖是公開網址,草稿與排程的標題不能從這裡漏出去
"SELECT id, title, category, created_at, updated_at FROM posts WHERE id = ? AND status = 'published'",
)
.bind(id)
.fetch_optional(&state.pool)
.await
.ok()??;
// 這個語系的手記清單裡有它就用它的譯名與位置;沒有(沒譯、還沒發布)就退回繁中的清單
let mut list = sky_list(&state.pool, locale).await.unwrap_or_default();
let mut text_locale = locale;
if !list.iter().any(|p| p.0 == post_id) {
list = sky_list(&state.pool, "zh-TW").await.unwrap_or_default();
text_locale = "zh-TW";
}
let found = list.iter().position(|p| p.0 == post_id);
let lit = found.unwrap_or(0);
let title = found.map_or_else(|| title.unwrap_or_default(), |i| list[i].1.clone());
// 分類的譯名在 categories 表(name_en…);沒有譯名就用原名
let category = match (category.as_deref(), crate::handlers::posts::locale_suffix(text_locale)) {
(Some(c), Some(sfx)) if !c.is_empty() => {
let sql = format!("SELECT name_{sfx} FROM categories WHERE name = ?");
let localized = sqlx::query_scalar::<_, Option<String>>(sqlx::AssertSqlSafe(sql.as_str()))
.bind(c)
.fetch_optional(&state.pool)
.await
.ok()
.flatten()
.flatten()
.filter(|s| !s.is_empty());
localized.or(category)
}
_ => category,
};
let date = crate::util::js_substring_prefix(created_at.as_deref().unwrap_or(""), 10);
let stamp = updated_at.filter(|s| !s.is_empty()).or(created_at).unwrap_or_default();
let (sky, sig) = sky_of(&list);
let html = post_card_html(&title, category.as_deref(), &date, text_locale);
let key = format!("{stamp}::{title}::{}::{sig:x}", category.unwrap_or_default());
Some((format!("post:{post_id}:{locale}"), key, html, Box::new(Notes::new(&sky, lit))))
}
async fn prepare_page(state: &AppState, page: &Page, locale: &str) -> Prepared {
let (sky, sig) = if page.key == "notes" {
sky_of(&sky_list(&state.pool, locale).await.unwrap_or_default())
} else {
(Vec::new(), 0)
};
let html = page_card_html(page, locale);
// 頁名與副標改了(語系檔跟著部署)快取也要失效:指紋直接用 HTML
let key = format!("{:x}::{sig:x}", fnv1a(&html));
(format!("page:{}:{locale}", page.key), key, html, page_scene(page.key, &sky))
}
#[cfg(test)]
mod tests {
use super::*;
/// ETag 的雜湊必須涵蓋**整個**字串(回歸:舊版只吃前 9 個 byte,改標題 ETag 不變)。
#[test]
fn etag_雜湊要涵蓋整個_cache_key() {
let a = fnv1a("1::2026-08-03 20:00:00::公開文章");
let b = fnv1a("1::2026-02-01 00:00:00::改過的標題");
let c = fnv1a("1::2026-08-03 20:00:00::公開文章 "); // 只差一個空白
assert_ne!(a, b, "改了標題與時間戳卻算出同一個 ETag——讀者會一直看到舊圖");
assert_ne!(a, c, "只差一個字元也要換值");
assert_eq!(a, fnv1a("1::2026-08-03 20:00:00::公開文章"));
assert_ne!(fnv1a(""), fnv1a("1::::"));
}
/// 標題直接來自使用者輸入,`</div>` 之類的東西不能把模板打斷。
#[test]
fn 標題裡的標籤不會逃出模板() {
let html =
post_card_html("</div><script>alert(1)</script>:<b>副標</b>", None, "2026-08-09", "zh-TW");
assert!(!html.contains("<script>") && !html.contains("<b>"), "原始標籤進了模板:{html}");
assert!(html.contains("<script>") && html.contains("<b>"));
}
/// 分類是空的時候退回「手記」(照語系);日期寫成斜線。
#[test]
fn 空分類退回手記() {
assert!(post_card_html("t", None, "d", "zh-TW").contains("手記"));
assert!(post_card_html("t", Some(""), "d", "en").contains("Notes"));
assert!(post_card_html("t", Some("技術"), "2026-10-13", "zh-TW").contains("技術 · 2026/10/13"));
assert!(
post_card_html("t", Some("技術"), "", "zh-TW").contains(">技術<"),
"沒有日期就不要留一個孤零零的 ·"
);
}
/// 主標/副標的拆法要跟前端 `splitTitle` 一致(那邊的測試在 `lib/blogReading.test.ts`)。
#[test]
fn 主標副標照前端的規則拆() {
assert_eq!(
split_title("為什麼我開始使用 Zed 編輯器:從 VS Code 搬家"),
("為什麼我開始使用 Zed 編輯器", Some("從 VS Code 搬家"))
);
assert_eq!(split_title("CrowdSec: 取代 fail2ban"), ("CrowdSec", Some("取代 fail2ban")));
assert_eq!(split_title("Rust 1.85:2024 edition"), ("Rust 1.85:2024 edition", None));
assert_eq!(split_title(":只有副標"), (":只有副標", None));
assert_eq!(split_title("只有主標:"), ("只有主標:", None));
assert_eq!(split_title(""), ("", None));
}
/// 每一頁在每個語系都要拿得到頁名與副標——語系檔改了 key 名,這裡會先紅,
/// 不會等到分享圖上出現一塊空白才發現。
#[test]
fn 每頁每個語系都有頁名與副標() {
for l in &LOCALES {
for p in &PAGES {
for key in [p.name, p.sub].into_iter().filter(|k| !k.is_empty()) {
let v = STRINGS[l.code].pointer(&format!("/{}", key.replace('.', "/")));
assert!(
v.and_then(|v| v.as_str()).is_some_and(|s| !s.is_empty()),
"{} 沒有 {key}",
l.code
);
}
}
}
}
/// 走完整條路徑(HTML → 排版 → 光柵化 → 疊上背景 → APNG),檢查輸出真的是
/// 1200×630、會動、而且後面的格只存差異。只編三格:整段在 debug 建置下要跑很久,
/// 而格與格之間走的是同一段程式。
#[test]
fn 長標題也畫得出正確尺寸的_apng() {
let sky: Vec<SkyPost> =
(0..20).map(|i| SkyPost::of(&format!("第 {i} 篇"), 1000 + i * 300, 7000)).collect();
let scene = Notes::new(&sky, 3);
let long = "把 NLLB 翻譯接進 Rust,在 Windows 上撞穿整條工具鏈:ct2rs × CTranslate2 的 protobuf 撞名、CRT 之爭、關閉死鎖與 NVIDIA 崩潰";
let overlay = render_overlay(&post_card_html(long, Some("位元築夢"), "2026-07-21", "zh-TW"), "zh-TW")
.expect("長標題要畫得出來");
// 從拖軌跡的那段開始取,三格之間才有東西在動
let png =
apng::encode(3, 100, |i| apng::compose(&scene.frame(i + 100), &overlay)).expect("要編得出來");
assert_eq!(&png[..8], &[0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a], "輸出不是 PNG");
let w = u32::from_be_bytes([png[16], png[17], png[18], png[19]]);
let h = u32::from_be_bytes([png[20], png[21], png[22], png[23]]);
assert_eq!((w, h), apng::SIZE, "尺寸不對");
// acTL(動畫控制)要在第一個 IDAT 之前,不然瀏覽器把它當成一般的 PNG
let pos = |tag: &[u8]| png.windows(4).position(|c| c == tag);
let (actl, idat) = (pos(b"acTL").expect("沒有 acTL:不是 APNG"), pos(b"IDAT").expect("沒有 IDAT"));
assert!(actl < idat);
let bytes_of = |tag: &[u8]| -> usize {
let (mut at, mut sum) = (8, 0);
while at + 8 <= png.len() {
let len = u32::from_be_bytes([png[at], png[at + 1], png[at + 2], png[at + 3]]) as usize;
if &png[at + 4..at + 8] == tag {
sum += len;
}
at += 12 + len;
}
sum
};
let (first, rest) = (bytes_of(b"IDAT"), bytes_of(b"fdAT"));
assert!(
rest > 0 && rest * 5 < first,
"後面的格沒有只存差異:第一格 {first} bytes,後兩格 {rest} bytes"
);
}
/// 背景要真的會動,而且最後一格接得回第一格。
#[test]
fn 背景會動而且首尾接得起來() {
let sky: Vec<SkyPost> = (0..12).map(|i| SkyPost::of(&format!("p{i}"), 500 * (i + 1), 6000)).collect();
let scenes: [Box<dyn Scene>; 12] = [
Box::new(Saturn::new()),
Box::new(Notes::new(&sky, 0)),
Box::new(About::new()),
Box::new(Log::new()),
Box::new(Works::new()),
Box::new(Colophon::new()),
Box::new(Setup::new()),
Box::new(Messages::new()),
Box::new(Moments::new()),
Box::new(Friends::new()),
Box::new(Collection::new()),
Box::new(Photos::new()),
];
for scene in scenes {
let n = scene.frames();
let (a, b) = (scene.frame(0), scene.frame(n * 3 / 5));
assert_ne!(a.data(), b.data(), "一圈裡的畫面跟第一格一模一樣:沒有在動");
let last = scene.frame(n - 1);
let diff = a.data().iter().zip(last.data()).filter(|(p, q)| p.abs_diff(**q) > 24).count();
assert!(diff < 2000, "最後一格跟第一格差太多({diff} 個色值),循環會跳一下");
}
}
/// 空標題、空日期、沒有文章也不能炸——資料庫裡真的有這種列。
#[test]
fn 空輸入不會_panic() {
assert!(render_overlay(&post_card_html("", None, "", "ja"), "ja").is_ok());
assert_eq!(Notes::new(&[], 0).frame(0).data().len(), apng::W * apng::H * 4);
}
/// 把樣張寫到 `/tmp/og-preview/`,用眼睛看(不是斷言,是工具)。改動模板或背景時跑它:
///
/// cargo nextest run --release --run-ignored only -E 'test(產生樣張)' --no-capture
///
/// `OG_PREVIEW=notes,home` 只產這幾張(`post` 是文章);`OG_LOCALES=en,ja` 換語系(預設繁中)。
#[test]
#[ignore = "產生樣張供人工檢視,不做斷言"]
fn 產生樣張() {
let dir = std::path::Path::new("/tmp/og-preview");
std::fs::create_dir_all(dir).unwrap();
let only = std::env::var("OG_PREVIEW").ok();
let wanted = |k: &str| only.as_deref().is_none_or(|o| o.split(',').any(|x| x == k));
let locales = std::env::var("OG_LOCALES").unwrap_or_else(|_| "zh-TW".into());
let sky: Vec<SkyPost> =
(0..48).map(|i| SkyPost::of(&format!("篇 {i}"), 800 + (i * 977) % 9000, 9800)).collect();
for loc in locales.split(',') {
for page in PAGES.iter().filter(|p| wanted(p.key)) {
let png =
render(&page_card_html(page, loc), loc, page_scene(page.key, &sky).as_ref()).unwrap();
let path = dir.join(format!("{}-{loc}.png", page.key));
std::fs::write(&path, &png).unwrap();
println!("{} → {} bytes", path.display(), png.len());
}
if wanted("post") {
let title =
"用 Frigate + Home Assistant 自製 Furbo 寵物保母:本機 AI 寫貓咪日記,但分不出我的兩隻貓";
let png = render(
&post_card_html(title, Some("位元築夢"), "2026-10-13", loc),
loc,
&Notes::new(&sky, 5),
)
.unwrap();
let path = dir.join(format!("post-{loc}.png"));
std::fs::write(&path, &png).unwrap();
println!("{} → {} bytes", path.display(), png.len());
}
}
}
}