Shadowzzh

upstream_cache.rs

upstream_cache.rs
//! 第三方代理的回應快取(GitHub/WakaTime/Steam/Spotify 那幾支 GET)。
//!
//! 在這之前那些端點每個請求都直接打上游:`/api/github/events` 一次 7–10 秒、
//! contributions 將近 1 秒,而且上游一抖就原樣把 5xx 傳給讀者(實測 Steam 那幾支
//! 一起回 500/503)。這層做三件事,各支 handler 不用自己寫:
//!
//! 1. **TTL 快取**:key 是 path + query,依路由給不同的 TTL。
//! 2. **出錯時回舊值**:上游回 5xx/429 而手上有舊資料(不超過 [`MAX_STALE_MS`])就回舊的,
//!    標 `x-upstream-cache: stale`。讀者看到的是幾分鐘前的資料,而不是一片錯誤。
//! 3. **同一個 key 只放一個請求去打上游**:快取過期的那一刻湧進來的請求,排在同一把鎖後面,
//!    第一個抓完其他人直接拿結果。
//!
//! 只收 2xx;4xx(使用者不存在之類)照原樣回、不快取。
//! key 有上限([`MAX_ENTRIES`]):`{username}` 這類參數來自公開網址,不設上限的話任何人
//! 換參數就能把 map 撐到無限大。

use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

use axum::body::{Body, Bytes};
use axum::extract::{Request, State};
use axum::http::{HeaderValue, StatusCode, header};
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use parking_lot::Mutex;

use crate::util::now_ms;

const MAX_ENTRIES: usize = 256;
/// 上游出錯時,多舊的資料還願意拿出來回。
pub const MAX_STALE_MS: i64 = 24 * 60 * 60 * 1000;
/// 單筆回應的大小上限;超過就照原樣回、不快取(這些端點實際都在幾十 KB 以內)。
const MAX_BODY: usize = 2 * 1024 * 1024;
const LOCK_SHARDS: usize = 32;

#[derive(Clone)]
struct Entry {
    status: StatusCode,
    content_type: Option<HeaderValue>,
    body: Bytes,
    fetched_at: i64,
}

pub struct UpstreamCache {
    entries: Mutex<HashMap<String, Entry>>,
    // 每個 key 一把鎖的話鎖本身也要清;固定幾把、依 key 雜湊分配就好
    locks: [tokio::sync::Mutex<()>; LOCK_SHARDS],
}

impl Default for UpstreamCache {
    fn default() -> Self {
        Self {
            entries: Mutex::new(HashMap::new()),
            locks: std::array::from_fn(|_| tokio::sync::Mutex::new(())),
        }
    }
}

impl UpstreamCache {
    fn get(&self, key: &str) -> Option<Entry> {
        self.entries.lock().get(key).cloned()
    }

    fn put(&self, key: String, entry: Entry) {
        let mut map = self.entries.lock();
        if map.len() >= MAX_ENTRIES && !map.contains_key(&key) {
            // 滿了就丟掉最舊的那筆
            if let Some(oldest) = map.iter().min_by_key(|(_, e)| e.fetched_at).map(|(k, _)| k.clone()) {
                map.remove(&oldest);
            }
        }
        map.insert(key, entry);
    }

    fn lock_for(&self, key: &str) -> &tokio::sync::Mutex<()> {
        use std::hash::{Hash, Hasher};
        // DefaultHasher::new() 的種子是固定的,同一個 key 一定落在同一把鎖
        let mut h = std::hash::DefaultHasher::new();
        key.hash(&mut h);
        #[expect(clippy::cast_possible_truncation, reason = "取餘數之後必定小於 LOCK_SHARDS")]
        let i = (h.finish() % LOCK_SHARDS as u64) as usize;
        &self.locks[i]
    }
}

/// 掛在路由上的設定:同一個 [`UpstreamCache`],各路由自己的 TTL。
#[derive(Clone)]
pub struct CachePolicy {
    pub cache: Arc<UpstreamCache>,
    pub ttl: Duration,
}

fn respond(e: &Entry, tag: &'static str) -> Response {
    let mut res = (e.status, e.body.clone()).into_response();
    if let Some(ct) = &e.content_type {
        res.headers_mut().insert(header::CONTENT_TYPE, ct.clone());
    }
    res.headers_mut().insert("x-upstream-cache", HeaderValue::from_static(tag));
    res
}

fn ttl_ms(p: &CachePolicy) -> i64 {
    i64::try_from(p.ttl.as_millis()).unwrap_or(i64::MAX)
}

pub async fn layer(State(policy): State<CachePolicy>, req: Request, next: Next) -> Response {
    let key = req.uri().path_and_query().map_or_else(|| req.uri().path().to_string(), ToString::to_string);
    let fresh = |e: &Entry| now_ms() - e.fetched_at < ttl_ms(&policy);

    if let Some(e) = policy.cache.get(&key).filter(fresh) {
        return respond(&e, "hit");
    }
    let _guard = policy.cache.lock_for(&key).lock().await;
    // 排隊的時候前一個人可能已經抓好了
    let cached = policy.cache.get(&key);
    if let Some(e) = cached.as_ref().filter(|e| fresh(e)) {
        return respond(e, "hit");
    }

    let res = next.run(req).await;
    let status = res.status();

    if status.is_success() {
        let (parts, body) = res.into_parts();
        let Ok(bytes) = axum::body::to_bytes(body, MAX_BODY).await else {
            return (StatusCode::BAD_GATEWAY, "upstream response too large").into_response();
        };
        let entry = Entry {
            status,
            content_type: parts.headers.get(header::CONTENT_TYPE).cloned(),
            body: bytes.clone(),
            fetched_at: now_ms(),
        };
        policy.cache.put(key, entry);
        let mut res = Response::from_parts(parts, Body::from(bytes));
        res.headers_mut().insert("x-upstream-cache", HeaderValue::from_static("miss"));
        return res;
    }

    let upstream_failed = status.is_server_error() || status == StatusCode::TOO_MANY_REQUESTS;
    if upstream_failed && let Some(e) = cached.filter(|e| now_ms() - e.fetched_at < MAX_STALE_MS) {
        tracing::warn!(path = %key, %status, "上游出錯,回快取的舊資料");
        return respond(&e, "stale");
    }
    res
}

#[cfg(test)]
mod tests {
    use super::*;
    use axum::Router;
    use axum::routing::get;
    use std::sync::atomic::{AtomicU16, AtomicUsize, Ordering};
    use tower::ServiceExt;

    /// 一支假的上游:記被呼叫幾次,回應的狀態碼可以中途改。
    struct Upstream {
        calls: AtomicUsize,
        status: AtomicU16,
    }

    fn app(ttl_secs: u64) -> (Router, Arc<Upstream>, Arc<UpstreamCache>) {
        let up = Arc::new(Upstream { calls: AtomicUsize::new(0), status: AtomicU16::new(200) });
        let cache = Arc::new(UpstreamCache::default());
        let u = up.clone();
        let handler = move |axum::extract::Path(name): axum::extract::Path<String>| {
            let u = u.clone();
            async move {
                let n = u.calls.fetch_add(1, Ordering::SeqCst) + 1;
                // 模擬慢上游,讓「同時湧入」的測試真的同時
                tokio::time::sleep(Duration::from_millis(20)).await;
                let status = StatusCode::from_u16(u.status.load(Ordering::SeqCst)).expect("合法狀態碼");
                (status, axum::Json(serde_json::json!({ "name": name, "call": n })))
            }
        };
        let policy = CachePolicy { cache: cache.clone(), ttl: Duration::from_secs(ttl_secs) };
        let router = Router::new()
            .route("/x/{name}", get(handler).layer(axum::middleware::from_fn_with_state(policy, layer)));
        (router, up, cache)
    }

    async fn call(app: &Router, path: &str) -> (StatusCode, String, serde_json::Value) {
        let res = app
            .clone()
            .oneshot(Request::get(path).body(Body::empty()).expect("request"))
            .await
            .expect("oneshot");
        let status = res.status();
        let tag = res
            .headers()
            .get("x-upstream-cache")
            .map(|v| v.to_str().unwrap_or("").to_string())
            .unwrap_or_default();
        let bytes = axum::body::to_bytes(res.into_body(), MAX_BODY).await.expect("body");
        (status, tag, serde_json::from_slice(&bytes).unwrap_or_default())
    }

    #[tokio::test]
    async fn ttl_內同一個網址只打一次上游() {
        let (app, up, _) = app(60);
        let (_, tag, body) = call(&app, "/x/a").await;
        assert_eq!((tag.as_str(), body["call"].as_i64()), ("miss", Some(1)));
        let (_, tag, body) = call(&app, "/x/a").await;
        assert_eq!((tag.as_str(), body["call"].as_i64()), ("hit", Some(1)), "第二次要拿快取");
        call(&app, "/x/a?page=2").await;
        assert_eq!(up.calls.load(Ordering::SeqCst), 2, "query 不同是不同的 key");
    }

    #[tokio::test]
    async fn 過期之後重抓() {
        let (app, up, _) = app(0);
        call(&app, "/x/a").await;
        call(&app, "/x/a").await;
        assert_eq!(up.calls.load(Ordering::SeqCst), 2);
    }

    #[tokio::test]
    async fn 上游出錯時回舊資料_沒有舊資料就照原樣回錯() {
        let (app, up, _) = app(0);
        up.status.store(500, Ordering::SeqCst);
        let (status, _, _) = call(&app, "/x/a").await;
        assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR, "沒有舊資料可回時就是錯誤");

        up.status.store(200, Ordering::SeqCst);
        call(&app, "/x/a").await; // 存進一份好的(call = 2)
        for bad in [500, 503, 429] {
            up.status.store(bad, Ordering::SeqCst);
            let (status, tag, body) = call(&app, "/x/a").await;
            assert_eq!(status, StatusCode::OK, "{bad} 時要回舊資料");
            assert_eq!(tag, "stale");
            assert_eq!(body["call"], 2, "回的是上一次成功的那份");
        }
    }

    #[tokio::test]
    async fn 四開頭的錯誤不快取也不拿舊資料蓋掉() {
        let (app, up, _) = app(0);
        call(&app, "/x/a").await;
        up.status.store(404, Ordering::SeqCst);
        let (status, _, _) = call(&app, "/x/a").await;
        assert_eq!(status, StatusCode::NOT_FOUND, "404 是真的答案,不是上游壞掉");
    }

    #[tokio::test]
    async fn 同時湧入的請求只放一個去打上游() {
        let (app, up, _) = app(60);
        let reqs = (0..8).map(|_| {
            let app = app.clone();
            async move { call(&app, "/x/a").await }
        });
        let results = futures_join_all(reqs).await;
        assert_eq!(up.calls.load(Ordering::SeqCst), 1, "其他七個要排隊拿第一個的結果");
        assert!(results.iter().all(|(s, _, b)| *s == StatusCode::OK && b["call"] == 1));
    }

    #[tokio::test]
    async fn key_數量有上限() {
        let (app, _, cache) = app(60);
        for i in 0..MAX_ENTRIES + 10 {
            call(&app, &format!("/x/{i}")).await;
        }
        assert_eq!(cache.entries.lock().len(), MAX_ENTRIES, "公開參數換來換去不能把 map 撐爆");
    }

    /// 沒有 futures crate:用 JoinSet 一起跑,照原順序收回來。
    async fn futures_join_all<F, T>(futs: impl Iterator<Item = F>) -> Vec<T>
    where
        F: std::future::Future<Output = T> + Send + 'static,
        T: Send + 'static,
    {
        let mut set = tokio::task::JoinSet::new();
        for (i, f) in futs.enumerate() {
            set.spawn(async move { (i, f.await) });
        }
        let mut out: Vec<(usize, T)> = Vec::new();
        while let Some(r) = set.join_next().await {
            out.push(r.expect("task"));
        }
        out.sort_by_key(|(i, _)| *i);
        out.into_iter().map(|(_, t)| t).collect()
    }
}