shadowzzh

revalidate.rs

revalidate.rs
use axum::{extract::Request, middleware::Next, response::Response};
use std::time::Duration;

// 文章內容變更後,通知前端清掉 ISR 快取(nitro routeRules 的 swr;文章頁 TTL 1h、列表 5min)。
//
// 刻意做成 middleware 而非在各 handler 內呼叫:posts 的寫入散在 posts.rs / admin.rs / opencc.rs
// 共 14 處,逐一掛必然會漏 —— 而且漏掉不會報錯,只會安靜地讓讀者看到舊內容。
// 這裡只認「寫入方法 + 動到文章本體的路徑 + 回應成功」,新增端點自動涵蓋。

// 這些子路徑是高頻互動,絕不能觸發清快取:
// /view 是每次有人瀏覽文章都會打 —— 若也清快取,等於每有一次瀏覽就把全站 ISR 清空,
// ISR 直接失效且不斷重複重生。like/reactions/comments 同理,而且它們的內容是 client 端
// 才 render 的(不在 SSR HTML 裡),清了也沒意義。
const NON_CONTENT_ACTIONS: &[&str] = &["view", "like", "unlike", "reactions", "comments", "send-newsletter"];

fn is_content_mutation(path: &str) -> bool {
    if !path.starts_with("/api/posts") && !path.starts_with("/api/admin/posts") {
        return false;
    }
    // 末段是高頻互動動作就跳過;其餘(/api/posts/:id/status、/api/admin/posts/:id、
    // /api/admin/posts/:id/generate-zh-cn …)都算文章本體變更。
    let last = path.rsplit('/').next().unwrap_or("");
    !NON_CONTENT_ACTIONS.contains(&last)
}

pub async fn notify_on_post_write(req: Request, next: Next) -> Response {
    let is_write = matches!(req.method().as_str(), "POST" | "PUT" | "PATCH" | "DELETE");
    let should_notify = is_write && is_content_mutation(req.uri().path());

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

    if should_notify && res.status().is_success() {
        tokio::spawn(fire()); // fire-and-forget:不拖慢寫入回應
    }
    res
}

/// 請前端清 ISR 快取。不是經過 HTTP 寫入文章的地方(排程 worker)要自己呼叫。
pub async fn fire() {
    // 兩個 env 都要有值才啟用;缺任一 = 功能沒開,安靜跳過。
    // 注意要擋空字串:compose 用 ${REVALIDATE_SECRET:-} 替換,未設定時傳進來的是空字串而非「不存在」,
    // env::var 會回 Ok("") —— 不擋的話每次發文都會送出空密鑰、被前端擋掉,然後在 log 噴 warn。
    let (Ok(url), Ok(secret)) =
        (std::env::var("FRONTEND_REVALIDATE_URL"), std::env::var("REVALIDATE_SECRET"))
    else {
        return;
    };
    if url.is_empty() || secret.is_empty() {
        return;
    }

    let res = reqwest::Client::new()
        .post(&url)
        .header("x-revalidate-secret", secret)
        .timeout(Duration::from_secs(3))
        .send()
        .await;

    // 通知失敗不影響已完成的寫入,最壞情況只是等 TTL 過期 → 記 warn 供排查,不往上拋。
    match res {
        Ok(r) if r.status().is_success() => tracing::debug!("ISR 快取已請前端清除"),
        Ok(r) => tracing::warn!("前端 revalidate 回應 {}", r.status()),
        Err(e) => tracing::warn!("前端 revalidate 打不通: {e}"),
    }
}

#[cfg(test)]
mod tests {
    use super::{is_content_mutation, notify_on_post_write};
    use axum::{Router, body::Body, http::Request, routing::put};
    use tokio::io::{AsyncReadExt, AsyncWriteExt};
    use tower::ServiceExt;

    // 假前端:收一個請求就把整包原始 HTTP 內容送回來,用來驗證通知真的送出且帶對標頭。
    async fn mock_frontend() -> (String, tokio::sync::oneshot::Receiver<String>) {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let port = listener.local_addr().unwrap().port();
        let (tx, rx) = tokio::sync::oneshot::channel();
        tokio::spawn(async move {
            if let Ok((mut sock, _)) = listener.accept().await {
                let mut buf = vec![0u8; 2048];
                let n = sock.read(&mut buf).await.unwrap_or(0);
                let req = String::from_utf8_lossy(&buf[..n]).to_string();
                let _ = sock.write_all(b"HTTP/1.1 200 OK\r\ncontent-length: 2\r\n\r\nok").await;
                let _ = tx.send(req);
            }
        });
        (format!("http://127.0.0.1:{port}/_revalidate"), rx)
    }

    fn app() -> Router {
        Router::new()
            .route("/api/posts/{id}", put(|| async { "ok" }))
            .route("/api/posts/{id}/view", put(|| async { "ok" }))
            .layer(axum::middleware::from_fn(notify_on_post_write))
    }

    // 正負兩案寫在同一個測試:env var 是 process 全域的,分成兩個平行測試會互相干擾。
    #[tokio::test]
    async fn 內容變更會實際發出通知_瀏覽則不會() {
        let (url, rx) = mock_frontend().await;
        // FIXME: Audit that the environment access only happens in single-threaded code.
        unsafe { std::env::set_var("FRONTEND_REVALIDATE_URL", &url) };
        // FIXME: Audit that the environment access only happens in single-threaded code.
        unsafe { std::env::set_var("REVALIDATE_SECRET", "s3cret") };

        // 1) 高頻瀏覽端點:不該發通知
        let res = app()
            .oneshot(Request::builder().method("PUT").uri("/api/posts/39/view").body(Body::empty()).unwrap())
            .await
            .unwrap();
        assert!(res.status().is_success());

        // 2) 文章本體變更:該發通知
        let res = app()
            .oneshot(Request::builder().method("PUT").uri("/api/posts/39").body(Body::empty()).unwrap())
            .await
            .unwrap();
        assert!(res.status().is_success());

        // 注意:這裡分辨不出通知是哪個請求觸發的(兩者發出的通知內容完全相同)。
        // 「/view 不可觸發」由上面的 高頻互動不可清快取 單元測試把關;
        // 本測試負責的是「middleware 真的有跑、狀態碼判斷正確、通知確實帶密鑰送達」。
        let got = tokio::time::timeout(std::time::Duration::from_secs(5), rx)
            .await
            .expect("逾時:前端沒收到任何 revalidate 通知")
            .expect("通道關閉");
        assert!(got.starts_with("POST /_revalidate"), "收到的是: {got}");
        assert!(got.to_lowercase().contains("x-revalidate-secret: s3cret"), "缺少密鑰標頭: {got}");
    }

    #[test]
    fn 文章本體變更要清快取() {
        for p in [
            "/api/posts",
            "/api/posts/39",
            "/api/posts/39/status",
            "/api/admin/posts",
            "/api/admin/posts/39",
            "/api/admin/posts/39/generate-zh-cn",
        ] {
            assert!(is_content_mutation(p), "{p} 應該要清快取");
        }
    }

    #[test]
    fn 高頻互動不可清快取() {
        // 這幾條若誤判成 true,每次有人看文章就會清光全站 ISR 快取
        for p in [
            "/api/posts/39/view",
            "/api/posts/39/like",
            "/api/posts/39/unlike",
            "/api/posts/39/reactions",
            "/api/posts/39/comments",
            "/api/admin/posts/39/send-newsletter",
        ] {
            assert!(!is_content_mutation(p), "{p} 不該清快取");
        }
    }

    #[test]
    fn 無關路徑不受影響() {
        for p in ["/api/thoughts", "/api/books", "/api/admin/users/1/role", "/"] {
            assert!(!is_content_mutation(p), "{p} 不該清快取");
        }
    }
}