simkl.rs
simkl.rs
//! Simkl 觀看紀錄同步(取代已移除的 Trakt 同步,見 handlers/watch.rs 檔頭)。
//!
//! 背景:Trakt 在 2026-07-30 把「建立 API application」改成 VIP-only,並未預告刪除了免費
//! 帳號的既有 app(trakt/trakt-web PR #3057;症狀是 refresh 回 "session not found"、
//! device/code 回 "client not found")。Simkl 是替代的資料來源。
//!
//! ⚠️ Simkl 的 API 規則跟 Trakt 很不一樣,照抄 Trakt 那套會被停權。官方原文:
//! - "For continuous sync, DO NOT use without fetching the Activity endpoint first."
//! - "Never run unconditional background polling timers without active user interaction."
//! - "Ensure you always use `date_from` … If you don't follow these rules, your client_id
//! will be suspended."
//!
//! 所以這裡的流程是:
//! 1. GET /sync/activities 很輕,只回各類別的時間戳
//! 2. 跟 sync_state 存的游標比對 一樣就直接結束,不打任何 all-items
//! 3. GET /sync/all-items/?date_from= 只有時間戳變了才拉,而且只拉增量
//!
//! 相對 Trakt 少掉的東西:Simkl 的 token 不過期、沒有 refresh_token(回應只有
//! access_token / token_type / scope),所以 watch.rs 裡那整套 refresh 輪替 + mutex +
//! 原子寫檔 + double-check 完全不需要——那套機制本身就是 Trakt 授權被燒掉的原因之一。
use serde_json::Value;
use crate::state::AppState;
/// API 根位址。可用 `SIMKL_BASE_URL` 覆寫——**存在的理由只有測試**。
///
/// 這支最該被守住的不是資料轉換(那些純函式下面已經測了),而是 `sync_once` 裡
/// 那三條「違反就會被 Simkl 停權」的規則:先問 activities、游標沒變不准拉
/// all-items、增量一定要帶 date_from。要驗證那些就得攔得到實際發出的請求。
///
/// 正式環境不設 env 就是官方位址,行為完全不變。
/// (同 `state::ExternalUrls`、`RESEND_BASE_URL`、`FFMPEG_BIN` 的做法。)
fn simkl_api() -> String {
std::env::var("SIMKL_BASE_URL").ok().filter(|s| !s.is_empty()).unwrap_or_else(|| SIMKL_API.into())
}
const SIMKL_API: &str = "https://api.simkl.com";
/// 官方要求帶「描述性」的 User-Agent(文件範例:`PlexMediaServer/1.43.1.10540`)。
const SIMKL_UA: &str = "koimsurai/1.0 (+https://koimsurai.com)";
/// 游標的 key。值是 /sync/activities 的 `all` 欄位,原樣存、原樣送回去當 date_from。
const CURSOR_KEY: &str = "simkl.activities_all";
fn client_id() -> String {
std::env::var("SIMKL_CLIENT_ID").unwrap_or_default()
}
fn access_token() -> String {
std::env::var("SIMKL_ACCESS_TOKEN").unwrap_or_default()
}
/// 官方要求每個請求都帶 client_id / app-name / app-version 這三個 query 參數。
fn with_required_params(path: &str) -> String {
let sep = if path.contains('?') { '&' } else { '?' };
format!("{}{path}{sep}client_id={}&app-name=koimsurai&app-version=1.0", simkl_api(), client_id())
}
async fn simkl_get(state: &AppState, path: &str) -> Option<Value> {
let resp = state
.http
.get(with_required_params(path))
.header("Content-Type", "application/json")
.header("Authorization", format!("Bearer {}", access_token()))
.header("simkl-api-key", client_id())
.header("User-Agent", SIMKL_UA)
.send()
.await
.ok()?;
let status = resp.status();
let body = resp.text().await.ok()?;
if !status.is_success() {
// 401/403 多半是 token 或 client_id 出事;印出來才不會像 Trakt 那次一路猜到底
tracing::warn!("[Simkl] GET {path} → {status}: {}", body.chars().take(200).collect::<String>());
return None;
}
serde_json::from_str(&body).ok()
}
async fn load_cursor(state: &AppState) -> Option<String> {
sqlx::query_scalar::<_, Option<String>>("SELECT value FROM sync_state WHERE key = ?")
.bind(CURSOR_KEY)
.fetch_optional(&state.pool)
.await
.ok()
.flatten()
.flatten()
}
async fn save_cursor(state: &AppState, value: &str) {
if let Err(e) = sqlx::query(
"INSERT INTO sync_state (key, value, updated_at) VALUES (?, ?, datetime('now')) \
ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = datetime('now')",
)
.bind(CURSOR_KEY)
.bind(value)
.execute(&state.pool)
.await
{
tracing::warn!("[Simkl] 游標寫入失敗(下次會重拉同一段): {e}");
}
}
/// `last_watched_at` → `YYYY-MM-DD`。Simkl 給的是 ISO8601,資料表存的是 DATE。
/// 拿不到日期時回 None 存 NULL——比塞一個假日期好,Trakt 那批 tv_history 的
/// watched_date 全是 NULL 就是因為來源真的沒給。
fn iso_to_date(raw: Option<&str>) -> Option<String> {
let s = raw?;
let d: String = s.chars().take(10).collect();
if d.len() == 10 && d.as_bytes()[4] == b'-' { Some(d) } else { None }
}
/// Simkl 的 poster 是相對路徑(例 "15/15189563adfbde5fe9"),要自己組 CDN 網址。
///
/// ⚠️ **有 tmdb_id 就不要用這個**,見 `poster_for()`。
fn poster_url(raw: Option<&str>) -> Option<String> {
let p = raw?;
if p.is_empty() {
return None;
}
Some(format!("https://wsrv.nl/?url=https://simkl.in/posters/{p}_m.webp"))
}
/// 決定要不要把 Simkl 的海報寫進 DB。**有 tmdb_id 就回 None。**
///
/// `films_recent` / `tv_recent` 會對「poster_url 是空的」那些列去 TMDb 補圖,補的是
/// w342 海報 **加上 original 的橫式 backdrop**(見 watch.rs 的 tmdb_detail)。填了 Simkl
/// 海報反而把那段補圖擋掉——結果 backdrop 永遠是 NULL,而「在看什麼」的橫幅 hero 沒有
/// backdrop 就退回拉寬海報,Simkl 的 `_m` 只有中等尺寸,拉寬就糊掉了。
///
/// 這是實際發生過的:Kung Fu Panda 4 同步進來之後橫幅明顯比 Trakt 那批模糊,
/// 因為 Trakt 的同步只寫 title/date/tmdb_id,把補圖的路留著。
///
/// 所以只有「Simkl 沒給 tmdb_id」時才用它的圖——那種情況 TMDb 補不了,有圖總比沒有好。
fn poster_for(tmdb_id: Option<i64>, raw: Option<&str>) -> Option<String> {
if tmdb_id.is_some() {
return None;
}
poster_url(raw)
}
fn as_i64(v: Option<&Value>) -> Option<i64> {
match v? {
Value::Number(n) => n.as_i64(),
// ids.tmdb 在回應裡是字串("1011985"),不是數字
Value::String(s) => s.parse().ok(),
_ => None,
}
}
/// 寫入一部電影。UNIQUE(title, watched_date) 讓重跑是冪等的。
async fn upsert_film(state: &AppState, item: &Value) -> bool {
let Some(movie) = item.get("movie").filter(|v| !v.is_null()) else { return false };
let Some(title) = movie.get("title").and_then(|v| v.as_str()) else { return false };
let watched = iso_to_date(item.get("last_watched_at").and_then(|v| v.as_str()));
let tmdb = as_i64(movie.pointer("/ids/tmdb"));
let r = sqlx::query(
"INSERT OR IGNORE INTO film_history \
(title, watched_date, source, tmdb_id, poster_url, release_year) \
VALUES (?, ?, 'simkl', ?, ?, ?)",
)
.bind(title)
.bind(&watched)
.bind(tmdb)
.bind(poster_for(tmdb, movie.get("poster").and_then(|v| v.as_str())))
.bind(as_i64(movie.get("year")))
.execute(&state.pool)
.await;
match r {
Ok(res) => res.rows_affected() > 0,
Err(e) => {
tracing::warn!("[Simkl] film_history 寫入失敗 ({title}): {e}");
false
}
}
}
/// 寫入影集的每一集。
///
/// 需要 `extended=full&episode_watched_at=yes` 才有逐集的 watched_at——這是 Simkl 比
/// Trakt 好的地方(Trakt 同步進來的 151 筆 tv_history,watched_date 全是 NULL)。
/// 文件警告這個參數會讓回應「exponentially larger」,所以只在增量(有 date_from)時用。
async fn upsert_show_episodes(state: &AppState, item: &Value) -> u32 {
let Some(show) = item.get("show").filter(|v| !v.is_null()) else { return 0 };
let Some(series) = show.get("title").and_then(|v| v.as_str()) else { return 0 };
let tmdb = as_i64(show.pointer("/ids/tmdb"));
let poster = poster_for(tmdb, show.get("poster").and_then(|v| v.as_str()));
let mut n = 0u32;
for season in show.get("seasons").and_then(|v| v.as_array()).map_or(&[][..], std::vec::Vec::as_slice) {
let s_num = as_i64(season.get("number")).unwrap_or(0);
for ep in season.get("episodes").and_then(|v| v.as_array()).map_or(&[][..], std::vec::Vec::as_slice) {
let e_num = as_i64(ep.get("number")).unwrap_or(0);
let label = format!("S{s_num:02}E{e_num:02}");
// 逐集的 watched_at;沒有就退回整部劇的 last_watched_at
let watched = iso_to_date(ep.get("watched_at").and_then(|v| v.as_str()))
.or_else(|| iso_to_date(item.get("last_watched_at").and_then(|v| v.as_str())));
let r = sqlx::query(
"INSERT OR IGNORE INTO tv_history \
(series_name, episode_label, watched_date, source, tmdb_id, poster_url) \
VALUES (?, ?, ?, 'simkl', ?, ?)",
)
.bind(series)
.bind(&label)
.bind(&watched)
.bind(tmdb)
.bind(&poster)
.execute(&state.pool)
.await;
match r {
Ok(res) if res.rows_affected() > 0 => n += 1,
Ok(_) => {}
Err(e) => tracing::warn!("[Simkl] tv_history 寫入失敗 ({series} {label}): {e}"),
}
}
}
n
}
/// 跑一次同步。回傳 (新增電影數, 新增集數);沒有變動時回 (0, 0) 且不打 all-items。
pub async fn sync_once(state: &AppState) -> (u32, u32) {
if client_id().is_empty() || access_token().is_empty() {
tracing::warn!("[Simkl] 缺 SIMKL_CLIENT_ID / SIMKL_ACCESS_TOKEN — 跳過");
return (0, 0);
}
// 步驟 1:先問 activities(官方規則的第一步)
let Some(act) = simkl_get(state, "/sync/activities").await else {
tracing::warn!("[Simkl] /sync/activities 失敗 — 跳過這次");
return (0, 0);
};
let Some(latest) = act.get("all").and_then(|v| v.as_str()) else {
// 帳號還沒有任何紀錄時 `all` 是 null,這是正常狀態不是錯誤
tracing::info!("[Simkl] 帳號目前沒有任何觀看紀錄");
return (0, 0);
};
// 步驟 2:比對游標。相同就結束——大部分的輪詢都會停在這裡。
let cursor = load_cursor(state).await;
if cursor.as_deref() == Some(latest) {
tracing::debug!("[Simkl] 沒有變動(游標 {latest})");
return (0, 0);
}
// 步驟 3:有變才拉。有游標就走增量;沒有就是首次同步(Phase 1)。
let path = if let Some(from) = cursor.as_deref() {
format!("/sync/all-items/?extended=full&episode_watched_at=yes&date_from={from}")
} else {
tracing::info!("[Simkl] 首次同步(無游標)— 拉完整清單");
"/sync/all-items/?extended=full".to_string()
};
let Some(data) = simkl_get(state, &path).await else {
// 沒拿到就不要動游標,下次重試同一段
tracing::warn!("[Simkl] all-items 失敗 — 保留游標下次重試");
return (0, 0);
};
let mut films = 0u32;
let mut episodes = 0u32;
for item in data.get("movies").and_then(|v| v.as_array()).map_or(&[][..], std::vec::Vec::as_slice) {
if upsert_film(state, item).await {
films += 1;
}
}
// shows 與 anime 的結構相同(都用 `show` 鍵),分開回傳而已
for key in ["shows", "anime"] {
for item in data.get(key).and_then(|v| v.as_array()).map_or(&[][..], std::vec::Vec::as_slice) {
episodes += upsert_show_episodes(state, item).await;
}
}
// 只有真的處理完才推進游標——中途失敗時寧可下次重拉,也不要漏資料
save_cursor(state, latest).await;
tracing::info!("[Simkl] 同步完成:+{films} 部電影、+{episodes} 集(游標 → {latest})");
(films, episodes)
}
/// 輪詢週期(秒),預設 6 小時。
///
/// 這個數字直接關係到會不會被停權:Simkl 明文禁止「無條件的背景輪詢」,
/// 而我們的做法是「低頻檢查 activities、有變才拉」。把 6 小時算錯成一小時
/// 就等於把頻率提高六倍,而**資料照樣是對的**——直到 client_id 被停用。
pub(crate) fn period_secs(raw: Option<&str>) -> u64 {
crate::worker::secs_or(raw, 6 * 3600)
}
/// 啟動後第一次跑之前的延遲(秒),預設 45——讓伺服器先把啟動的事做完。
pub(crate) fn delay_secs(raw: Option<&str>) -> u64 {
crate::worker::secs_or(raw, 45)
}
/// 啟動 Simkl 同步 worker(`ENABLE_SIMKL_SYNC=1` 才啟動);沒啟用時回 `None`。
///
/// 週期預設 6 小時,但每次只會打一個很輕的 /sync/activities;只有時間戳變了才拉資料。
/// 這是官方 "Never run unconditional background polling timers" 那條規則的做法——
/// 被禁止的是無條件全量輪詢,不是定期檢查有沒有變動。
pub fn spawn_sync(state: AppState) -> Option<tokio::task::JoinHandle<()>> {
let delay = delay_secs(std::env::var("SIMKL_SYNC_DELAY_SECS").ok().as_deref());
let period = period_secs(std::env::var("SIMKL_SYNC_PERIOD_SECS").ok().as_deref());
crate::worker::spawn_periodic(state, "Simkl", "ENABLE_SIMKL_SYNC", delay, period, |s| async move {
let _ = sync_once(&s).await;
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn iso_to_date_只取日期部分() {
assert_eq!(iso_to_date(Some("2026-08-01T17:32:03Z")).as_deref(), Some("2026-08-01"));
assert_eq!(iso_to_date(Some("2026-08-01")).as_deref(), Some("2026-08-01"));
}
#[test]
fn iso_to_date_壞資料回_none_而不是假日期() {
// 來源沒給日期時要存 NULL,不要塞一個看起來像真的的值
assert_eq!(iso_to_date(None), None);
assert_eq!(iso_to_date(Some("")), None);
assert_eq!(iso_to_date(Some("not-a-date")), None);
assert_eq!(iso_to_date(Some("2026/08/01")), None);
}
#[test]
fn as_i64_同時吃數字與字串() {
// Simkl 的 ids.tmdb 是字串("1011985"),year 是數字——同一支程式要兩種都收
assert_eq!(as_i64(Some(&serde_json::json!(2024))), Some(2024));
assert_eq!(as_i64(Some(&serde_json::json!("1011985"))), Some(1_011_985));
assert_eq!(as_i64(Some(&serde_json::json!(null))), None);
assert_eq!(as_i64(Some(&serde_json::json!("abc"))), None);
assert_eq!(as_i64(None), None);
}
#[test]
fn poster_url_組出完整網址_空值回_none() {
let u = poster_url(Some("15/15189563adfbde5fe9")).unwrap();
assert!(u.contains("simkl.in/posters/15/15189563adfbde5fe9"), "{u}");
assert_eq!(poster_url(Some("")), None);
assert_eq!(poster_url(None), None);
}
#[test]
fn 有_tmdb_id_就不寫_simkl_海報_留給_tmdb_補圖() {
// 這是重點:填了 Simkl 海報會讓 films_recent 的補圖被跳過,連帶 backdrop 永遠是
// NULL,橫幅只好拿直式海報拉寬 → 糊。有 tmdb_id 就一定要讓路。
assert_eq!(poster_for(Some(1011985), Some("15/15189563adfbde5fe9")), None);
// 沒有 tmdb_id 時 TMDb 補不了,這時 Simkl 的圖有總比沒有好
let u = poster_for(None, Some("15/15189563adfbde5fe9")).unwrap();
assert!(u.contains("simkl.in"), "{u}");
// 兩邊都沒有就是沒有
assert_eq!(poster_for(None, None), None);
assert_eq!(poster_for(None, Some("")), None);
}
#[test]
fn 週期預設六小時_算錯就是提高輪詢頻率() {
// 6 * 3600 而不是 6 + 3600(1h)或 6 / 3600(0)——Simkl 會因為過度輪詢停權,
// 而這種錯誤不會讓資料變錯,只會讓帳號某天被停掉
assert_eq!(period_secs(None), 21_600);
assert_eq!(period_secs(Some("")), 21_600, "空字串當成沒設");
assert_eq!(period_secs(Some("not-a-number")), 21_600, "壞值退回預設而不是 0");
assert_eq!(period_secs(Some("900")), 900);
}
#[test]
fn 啟動延遲預設四十五秒() {
assert_eq!(delay_secs(None), 45);
assert_eq!(delay_secs(Some("abc")), 45);
assert_eq!(delay_secs(Some("5")), 5);
}
#[test]
fn 必要參數一定會被帶上() {
// 官方要求每個請求都要有 client_id / app-name / app-version,漏了會被視為違規
unsafe { std::env::set_var("SIMKL_CLIENT_ID", "TESTID") };
let a = with_required_params("/sync/activities");
assert!(a.contains("?client_id=TESTID"), "{a}");
assert!(a.contains("&app-name=koimsurai") && a.contains("&app-version="), "{a}");
// 已經有 query string 時要用 & 接,不能再來一個 ?
let b = with_required_params("/sync/all-items/?extended=full");
assert!(b.contains("?extended=full&client_id=TESTID"), "{b}");
assert_eq!(b.matches('?').count(), 1, "只能有一個問號: {b}");
}
}