//! Router 組裝(自 main.rs 抽出):main 只負責 env/pool/state 與監聽,
//! 整合測試則以 `build_router(test_state)` + tower `oneshot` 直接打端點,
//! 走與正式環境完全相同的 middleware 疊層(CORS / body limit / revalidate / trace)。
use axum::{
Router,
extract::DefaultBodyLimit,
http::{HeaderName, HeaderValue, Method},
routing::{delete, get, patch, post, put},
};
use tower_http::cors::{AllowHeaders, Any, CorsLayer};
use tower_http::set_header::SetResponseHeaderLayer;
use tower_http::trace::TraceLayer;
use utoipa::OpenApi;
use utoipa_scalar::{Scalar, Servable};
use crate::upstream_cache::{self, CachePolicy, UpstreamCache};
use crate::{handlers, openapi, revalidate, state::AppState};
/// 全域 404(Express 退役後取代舊的 proxy fallback):未知路徑回 404;
/// 未接管的「方法」則由 axum MethodRouter 自動回 405(標準語意)。
async fn not_found() -> (axum::http::StatusCode, &'static str) {
(axum::http::StatusCode::NOT_FOUND, "Not Found")
}
/// 完整路由表 + middleware 疊層。全站端點皆 Rust 原生(Express 已於 2026-07-14 退役)。
pub fn build_router(state: AppState) -> Router {
// 第三方代理共用一份回應快取,TTL 依資料多常變(見 upstream_cache 的說明)
let upstream = std::sync::Arc::new(UpstreamCache::default());
let cached = |secs: u64| {
axum::middleware::from_fn_with_state(
CachePolicy { cache: upstream.clone(), ttl: std::time::Duration::from_secs(secs) },
upstream_cache::layer,
)
};
Router::new()
.route("/api/tags", get(handlers::tags::list_tags))
.route("/api/categories", get(handlers::categories::list_categories))
.route("/api/series", get(handlers::series::list_series))
.route("/api/series/{name}", get(handlers::series::series_by_name))
.route("/api/stats", get(handlers::stats::site_stats))
// 前端 Core Web Vitals(B4):beacon 寫入 + 聚合自看
.route("/api/vitals", post(handlers::vitals::report_vital))
// 前端錯誤(Sentry SDK 的 tunnel 目的地)與 CSP 違規回報。
// 兩個都是公開無認證的——CSP report 是瀏覽器直接送的,帶不了任何標頭。
// 路徑刻意不含 sentry/envelope/store,那是廣告外掛通用規則在比對的字。
.route("/api/_report", post(handlers::report_tunnel::tunnel))
.route("/api/csp-report", post(handlers::report_tunnel::csp_report))
.route("/api/vitals/stats", get(handlers::vitals::vitals_stats))
.route("/api/link-preview", get(handlers::link_preview::link_preview))
// thoughts:/rss 靜態路由(axum matchit 優先於 /{id})
.route("/api/thoughts/rss", get(handlers::thoughts::thoughts_rss))
.route("/api/thoughts", get(handlers::thoughts::list_thoughts))
.route("/api/thoughts/{id}", get(handlers::thoughts::get_thought))
.route(
"/api/thoughts/{id}/comments",
get(handlers::thoughts::list_thought_comments).post(handlers::comments::thought_comment),
)
.route("/api/health", get(handlers::home::health))
// 設備頁的遙測:只有溫度、負載、記憶體、功耗(見 handlers::telemetry),快取 30 秒
.route("/api/telemetry", get(handlers::telemetry::telemetry).layer(cached(30)))
// 朋友頁:朋友清單寫死在後端,順手抓每個人的 RSS 最新一篇,快取一小時
// 名單每次讀 DB(收下一位朋友馬上出現),feed 在 handler 裡各自快取一小時
.route("/api/friends", get(handlers::friends::friends))
.route("/api/friends/apply", post(handlers::friend_links::apply))
// 每日名言(opencc cn→tw + 當日快取)
.route("/api/quote/daily", get(handlers::quote::quote_daily))
// 全站 RSS(app-level 非 /api;nginx `location = /rss` 指過來)
.route("/rss", get(handlers::rss::site_rss))
// home digest(純 DB 讀)
.route("/api/home/digest", get(handlers::home::home_digest))
// posts:列表 / 單篇 / 反應 / 留言
.route("/api/posts", get(handlers::posts::list_posts))
.route("/api/posts/{id}", get(handlers::posts::get_post))
// MCP 的 set_post_status 在用;其餘寫入一律走 /api/admin/posts
.route("/api/posts/{id}/status", patch(handlers::posts::patch_post_status))
.route(
"/api/posts/{id}/reactions",
get(handlers::posts::post_reactions).post(handlers::posts::post_reaction),
)
// 站台層級:首頁「留下印記」按讚 + GitHub 星數(後端代理 + 快取)
.route("/api/site/likes", get(handlers::site::get_site_likes).post(handlers::site::post_site_like))
.route("/api/site/github-stars", get(handlers::site::get_github_stars))
// 文章內嵌投票(公開;防重複投票在 client 端做)
.route("/api/polls/{id}", get(handlers::polls::get_poll))
.route("/api/polls/{id}/vote", post(handlers::polls::vote_poll))
.route(
"/api/posts/{id}/comments",
get(handlers::posts::post_comments).post(handlers::comments::post_comment),
)
// 不是文章也不是碎念、自己有留言的頁面(留言頁)
.route(
"/api/pages/{page}/comments",
get(handlers::comments::page_comments).post(handlers::comments::page_comment),
)
// 計數寫入(公開)
.route("/api/posts/{id}/view", post(handlers::posts::post_view))
.route("/api/posts/{id}/like", post(handlers::posts::post_like))
.route("/api/posts/{id}/unlike", post(handlers::posts::post_unlike))
.route("/api/comments/{id}/like", post(handlers::posts::comment_like))
.route("/api/thoughts/{id}/react", post(handlers::thoughts::thought_react))
// admin thoughts CRUD(unfurl / TMDb enrich)
.route("/api/admin/thoughts", post(handlers::thoughts::admin_create_thought))
.route(
"/api/admin/thoughts/{id}",
put(handlers::thoughts::admin_update_thought).delete(handlers::thoughts::admin_delete_thought),
)
// auth:登入 / 當前使用者 / 登出 / OAuth 設定
.route("/api/auth/login", post(handlers::auth::login))
.route("/api/auth/me", get(handlers::auth::me))
.route("/api/auth/logout", post(handlers::auth::logout))
.route("/api/auth/providers", get(handlers::auth::providers))
.route("/api/auth/reset-admin", post(handlers::auth::reset_admin))
// 用戶角色管理(requireOwner)
.route("/api/admin/users/{id}/role", put(handlers::admin::admin_update_user_role))
// spotify 一次性 setup callback(簡版 HTML)
.route("/api/spotify/callback", get(handlers::spotify::spotify_callback))
// OAuth callbacks(google/github)
.route("/api/auth/google/callback", post(handlers::oauth::google_callback))
.route("/api/auth/github/callback", post(handlers::oauth::github_callback))
// newsletter
.route("/api/newsletter/subscribe", post(handlers::newsletter::subscribe))
.route("/api/newsletter/unsubscribe", post(handlers::newsletter::unsubscribe))
.route("/api/newsletter/by-token/{token}", get(handlers::newsletter::by_token))
.route("/api/newsletter/subscribers", get(handlers::newsletter::subscribers))
// admin authed 讀 + CRUD 寫入
.route("/api/admin/tags", get(handlers::admin::admin_tags).post(handlers::admin::create_tag))
.route("/api/admin/tags/{id}", put(handlers::admin::update_tag).delete(handlers::admin::delete_tag))
.route(
"/api/admin/categories",
get(handlers::admin::admin_categories).post(handlers::admin::create_category),
)
.route(
"/api/admin/categories/{id}",
put(handlers::admin::update_category).delete(handlers::admin::delete_category),
)
.route("/api/admin/users", get(handlers::admin::admin_users))
.route(
"/api/admin/blacklist",
get(handlers::admin::admin_blacklist).post(handlers::admin::create_blacklist),
)
.route("/api/admin/blacklist/{id}", delete(handlers::admin::delete_blacklist))
.route(
"/api/admin/keyword-filters",
get(handlers::admin::admin_keyword_filters).post(handlers::admin::create_keyword_filter),
)
.route("/api/admin/keyword-filters/{id}", delete(handlers::admin::delete_keyword_filter))
.route("/api/admin/posts", get(handlers::admin::admin_posts).post(handlers::admin::admin_create_post))
.route(
"/api/admin/posts/{id}",
get(handlers::admin::admin_get_post)
.put(handlers::admin::admin_update_post)
.delete(handlers::admin::admin_delete_post),
)
.route("/api/admin/posts/{id}/restore", post(handlers::admin::admin_restore_post))
// generate-zh-cn(ferrous-opencc Tw2s,byte-identical)
.route("/api/admin/posts/{id}/generate-zh-cn", post(handlers::opencc::generate_zh_cn))
// send-newsletter(reqwest 直打 Resend batch API)
.route("/api/admin/posts/{id}/send-newsletter", post(handlers::mailer::send_newsletter_route))
.route("/api/admin/comments", get(handlers::admin::admin_comments))
// 批次審核(Express bug #2 死路由的修好版;靜態段優先於 :id/status)
.route("/api/admin/comments/batch/status", patch(handlers::admin::admin_batch_comment_status))
// 後台統計(⚠️ visitors 用 Math.random,非 byte 對拍——除該欄外對拍)
.route("/api/admin/stats", get(handlers::admin::admin_stats))
// 流量(代理自架 Plausible 的 Stats API,key 只在後端)
.route("/api/admin/analytics", get(handlers::analytics::admin_analytics))
.route("/api/admin/comments/{id}/status", patch(handlers::admin::patch_comment_status))
.route("/api/admin/comments/{id}/reply", post(handlers::admin::reply_comment))
.route(
"/api/admin/comments/{id}",
put(handlers::admin::update_comment).delete(handlers::admin::delete_comment),
)
// books 域
.route("/api/books", get(handlers::books::list_books).post(handlers::books::create_book))
.route(
"/api/books/{id}",
get(handlers::books::get_book)
.put(handlers::books::update_book)
.delete(handlers::books::delete_book),
)
.route("/api/books/stats/summary", get(handlers::books::book_stats))
.route("/api/admin/books", get(handlers::books::admin_books))
.route(
"/api/admin/friends",
get(handlers::friend_links::admin_friends).post(handlers::friend_links::admin_create_friend),
)
.route(
"/api/admin/friends/{id}",
patch(handlers::friend_links::admin_update_friend)
.delete(handlers::friend_links::admin_delete_friend),
)
.route("/api/admin/friends/{id}/check", post(handlers::friend_links::admin_check_friend))
// gallery(讀 manifest / 串流代理)
.route("/api/gallery/photos", get(handlers::gallery::gallery_photos))
.route("/api/image-proxy", get(handlers::gallery::image_proxy))
// gallery sync(rotate+resize+lossy webp+EXIF+manifest)
.route("/api/admin/gallery/sync", post(handlers::gallery::gallery_sync))
// 照片的後台設定(標題、標籤、精選、隱藏),疊在 manifest 上
.route("/api/admin/gallery/photos", get(handlers::photo_meta::admin_photos))
.route("/api/admin/gallery/photos/{id}", patch(handlers::photo_meta::admin_update_photo))
// 收藏頁:觀看紀錄與聽的歌要不要出現在前台
.route("/api/admin/collection", get(handlers::collection::admin_collection))
.route("/api/admin/collection/hidden", put(handlers::collection::admin_set_hidden))
// OG 圖(takumi;axum 不支援 :id.png 部分參數,handler 內 strip 後綴)
.route("/api/og/{file}", get(handlers::og::og_png))
// 上傳(axum multipart;thumbhash 實測等價)
.route(
"/api/admin/upload",
post(handlers::upload::upload)
// multer limits.fileSize = 50MB(其餘路由走全域 10MB)
.route_layer(DefaultBodyLimit::max(50 * 1024 * 1024)),
)
// 第三方代理(/steam/profile SWR 快取、spotify、github、wakatime)
.route("/api/github/user/{username}", get(handlers::thirdparty::github_user).layer(cached(600)))
.route("/api/github/events/{username}", get(handlers::thirdparty::github_events).layer(cached(300)))
// repos / contributions 以前是瀏覽器直接打第三方(api.github.com 未認證、
// jogruber 的爬蟲服務);收進後端才吃得到 token 額度,型別也才有來源
.route("/api/github/repos/{username}", get(handlers::thirdparty::github_repos).layer(cached(1800)))
// 作品頁的數據:一天變不了多少,快取六小時
.route("/api/github/works", get(handlers::thirdparty::github_works).layer(cached(21600)))
.route(
"/api/github/contributions/{username}",
get(handlers::thirdparty::github_contributions).layer(cached(3600)),
)
.route("/api/wakatime/today", get(handlers::thirdparty::wakatime_today).layer(cached(300)))
.route("/api/wakatime/week", get(handlers::thirdparty::wakatime_week).layer(cached(1800)))
.route("/api/wakatime/projects", get(handlers::thirdparty::wakatime_projects).layer(cached(1800)))
// profile 自己有 SWR 快取(refresh_steam_profile),不再疊一層
.route("/api/steam/profile", get(handlers::thirdparty::steam_profile))
.route("/api/spotify/login", get(handlers::spotify::login))
.route("/api/spotify/recently-played", get(handlers::spotify::recently_played).layer(cached(60)))
// 每個分頁每 30 秒輪詢一次;10 秒內的請求共用同一份,Spotify 只被打一次
.route("/api/spotify/now-playing", get(handlers::spotify::now_playing).layer(cached(10)))
.route("/api/spotify/top-genres", get(handlers::spotify::top_genres))
.route("/api/spotify/top-tracks", get(handlers::spotify::top_tracks))
.route("/api/spotify/audio-features", get(handlers::spotify::audio_features))
.route("/api/spotify/me", get(handlers::spotify::me))
// player 帶「線上/遊戲中」狀態,TTL 短;其餘幾小時才變一次
.route("/api/steam/player", get(handlers::thirdparty::steam_player).layer(cached(60)))
.route("/api/steam/recent-games", get(handlers::thirdparty::steam_recent_games).layer(cached(600)))
.route("/api/steam/owned-games", get(handlers::thirdparty::steam_owned_games).layer(cached(3600)))
.route(
"/api/steam/achievements/{appid}",
get(handlers::thirdparty::steam_achievements).layer(cached(3600)),
)
// watch 域
.route("/api/anime/history", get(handlers::watch::anime_history))
.route("/api/films/recent", get(handlers::watch::films_recent))
.route("/api/tv/recent", get(handlers::watch::tv_recent))
.route("/api/watch/stats", get(handlers::watch::watch_stats))
.route("/api/watch/favorites", get(handlers::watch::favorites).post(handlers::watch::create_favorite))
.route(
"/api/watch/favorites/{id}",
put(handlers::watch::update_favorite).delete(handlers::watch::delete_favorite),
)
.route("/api/watch/tmdb-search", get(handlers::watch::tmdb_search))
.route("/api/watch/now", get(handlers::watch::watch_now))
.route("/api/admin/watch/now", post(handlers::watch::heartbeat))
// 動畫瘋 cookie/status(bahamutPushAuth)
.route("/api/admin/bahamut/status", get(handlers::bahamut::status))
.route("/api/admin/bahamut/cookie", post(handlers::bahamut::cookie))
.route("/api/books/search/external", get(handlers::thirdparty::books_search_external))
.route("/api/books/tw", get(handlers::tw_isbn::tw_search))
// OpenAPI 文件(utoipa,與前端 specta 型別同源):spec 自架 + Scalar UI
.route("/api/openapi.json", get(openapi::openapi_json))
.merge(Scalar::with_url("/api/docs", openapi::ApiDoc::openapi()))
.fallback(not_found)
// 對齊 Express `app.use(cors())`:所有回應 ACAO:*;preflight 回六 methods、
// Allow-Headers reflect 請求(mirror_request = cors 套件預設行為)。
// 已知微差:preflight Rust 回 200、Express 回 204(瀏覽器語意等價)。
.layer(
CorsLayer::new()
.allow_origin(Any)
.allow_methods([
Method::GET,
Method::HEAD,
Method::PUT,
Method::PATCH,
Method::POST,
Method::DELETE,
])
.allow_headers(AllowHeaders::mirror_request()),
)
// API 回應一律 `X-Robots-Tag: noindex`。
//
// 取代 robots.txt 裡的 `Disallow: /api/`:那行的本意是「別索引這些 JSON」,實際效果卻是
// 「別抓取」——Googlebot 連渲染時要用都不行。GSC 的網址審查會列出一整排「遭到 robots.txt
// 封鎖」(留言數、按讚數、文章清單…)。目前正文是 SSR 出來的所以沒實害,但只要有任何內容
// 改成客戶端載入就會安靜地出事。Google 官方建議正是:不要用 robots.txt 擋渲染需要的資源,
// 要防止被收錄改用這個標頭。
.layer(SetResponseHeaderLayer::overriding(
HeaderName::from_static("x-robots-tag"),
HeaderValue::from_static("noindex"),
))
// 對齊 Express `express.json({limit:'10mb'})`(axum 預設 2MB 會讓長文 PUT 413)
.layer(DefaultBodyLimit::max(10 * 1024 * 1024))
// 文章內容變更後通知前端清 ISR 快取(fire-and-forget;未設 env 則不啟用)
.layer(axum::middleware::from_fn(revalidate::notify_on_post_write))
// ⚠️ on_failure 降到 WARN 是刻意的。預設是 ERROR,而 ERROR 現在會變成 Sentry
// issue(見 main.rs 的 event_filter)——於是每個 5xx 都產生**兩則**:
// 一則是 error.rs 的 `internal_error` 發的(帶檔名、行號、原始訊息,有用),
// 一則是這裡發的 "response failed"(culprit 空、metadata {},零資訊)。
// 降成 WARN 之後它變成麵包屑,附在真正那則上說明「這次回應是 5xx」。
.layer(
TraceLayer::new_for_http()
.on_failure(tower_http::trace::DefaultOnFailure::new().level(tracing::Level::WARN)),
)
// ── 錯誤追蹤(自架 GlitchTip)──────────────────────────────────
// 兩層都要,缺一不可:
// NewSentryLayer 每個請求開一個獨立 Hub。沒有它的話,並發請求會共用同一個
// scope,A 請求的麵包屑會出現在 B 請求的 issue 裡。
// SentryHttpLayer 把請求資訊掛進事件。`enable_transaction()` 沒開——
// 那是 APM,這裡 traces_sample_rate = 0。
//
// ⚠️ 順序:NewSentryLayer 要在外層(先開 Hub,裡面的東西才寫得進去)。
// axum 的 layer 是**由下往上**包,所以寫在後面的是外層。
//
// SENTRY_DSN 沒設時 sentry 是 no-op,這兩層留著也沒有成本,
// 所以不做條件式組裝——那會讓 build_router 的回傳型別變複雜。
.layer(sentry_tower::SentryHttpLayer::new())
.layer(sentry_tower::NewSentryLayer::new_from_top())
.with_state(state)
}