Skip to content

World's first open-source enterprise world model.

A 404 under /assets is not kept for a year (#623)

WaylandYangfb5119e7c5d9
diff --git a/Cargo.lock b/Cargo.lock
index 5f243ba7..2a464102 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5254,8 +5254,10 @@ dependencies = [
"sqlparser",
"sqlx",
"subtle",
+ "tempfile",
"thiserror 2.0.20",
"tokio",
+ "tower",
"tower-http",
"tracing",
"tracing-subscriber",
diff --git a/crates/utopia-server/Cargo.toml b/crates/utopia-server/Cargo.toml
index 1d16872b..74615028 100644
--- a/crates/utopia-server/Cargo.toml
+++ b/crates/utopia-server/Cargo.toml
@@ -51,3 +51,6 @@ subtle.workspace = true
[dev-dependencies]
wiremock = "0.6.5"
+# 静态托管那一段的单测:不连库地把请求推进 Router
+tower = { version = "0.5", features = ["util"] }
+tempfile.workspace = true
diff --git a/crates/utopia-server/src/api/mod.rs b/crates/utopia-server/src/api/mod.rs
index a9e56e37..64b7d113 100644
--- a/crates/utopia-server/src/api/mod.rs
+++ b/crates/utopia-server/src/api/mod.rs
@@ -18,6 +18,8 @@ pub(crate) mod rule_routes;
mod search_routes;
mod settings_routes;
mod sources_routes;
+#[cfg(test)]
+mod static_files_tests;
mod token_routes;
mod tools;
mod tools_graph;
@@ -41,6 +43,54 @@ use crate::state::AppState;
const MAX_UPLOAD_BYTES: usize = 100 * 1024 * 1024;
+/// 把构建产物挂上去。**单独一段、而且不带 state**,所以它可以脱开数据库单测:
+/// 这一段的契约(哪条路 404、哪条路回首页、各自的缓存指示)已经破过两次,
+/// 一次是升级白屏(#616),一次是把 404 也存一年。
+fn with_static_files(mut app: Router, web_dist: &str) -> Router {
+ /* SPA 托管。**分两条路,因为它们的失败方式不一样**:
+
+ `/assets` 下面是构建产物,文件名带内容哈希。这里的 ServeDir **不带兜底**,
+ 所以缺文件就是 404。从前它和页面共用一个带 history fallback 的服务,于是
+ 升级之后旧哈希的请求拿到的是 `200 text/html` 的首页——浏览器按模块脚本
+ 解析一张网页,光凭 MIME 就拒绝执行,界面白屏(#616)。
+
+ 缓存指示按文件名本来的含义给:带哈希的产物换了内容就换名字,可以
+ `immutable` 存一年;`index.html` 每次都要回源确认,否则它会指着一批
+ 已经不存在的哈希。少了这一条,升级要等浏览器的启发式缓存自己过期。 */
+ let index = std::path::Path::new(web_dist).join("index.html");
+ if index.exists() {
+ /* 每条路各自套自己的头。**层要挂在这一段的 Router 上,不能挂在整个
+ app 上**——挂在 app 上,API 的响应也会跟着被扣上 `immutable`。 */
+ let assets = Router::new()
+ .fallback_service(ServeDir::new(std::path::Path::new(web_dist).join("assets")))
+ /* **只有拿到东西的那一次才 `immutable`。**这个头从前是无条件套的,
+ 于是 `/assets/<不存在的文件>` 的 404 也带着「存一年」——浏览器(和
+ 中间的缓存)会把「这个文件不存在」记一年。而资源文件名带哈希,
+ 一次部署之后请求的正是新名字:上一秒刚缓存下来的那条 404 会让
+ 新版本的 js 在那台机器上整整一年拿不到。这正是 #616 要防的那条链,
+ 只是发生在另一头。拿不到的那一次给 `no-cache`,下一次照常回源。 */
+ .layer(SetResponseHeaderLayer::overriding(
+ header::CACHE_CONTROL,
+ |res: &axum::response::Response| {
+ Some(if res.status().is_success() {
+ HeaderValue::from_static("public, max-age=31536000, immutable")
+ } else {
+ HeaderValue::from_static("no-cache")
+ })
+ },
+ ));
+ let spa = Router::new()
+ .fallback_service(ServeDir::new(web_dist).fallback(ServeFile::new(index)))
+ .layer(SetResponseHeaderLayer::overriding(
+ header::CACHE_CONTROL,
+ HeaderValue::from_static("no-cache"),
+ ));
+ app = app.nest("/assets", assets).fallback_service(spa);
+ tracing::info!("已托管前端产物: {}", web_dist);
+ }
+ app
+}
+
pub fn router(state: AppState, cfg: &AppConfig) -> Router {
let api = Router::new()
.route("/health", get(health))
@@ -505,37 +555,7 @@ pub fn router(state: AppState, cfg: &AppConfig) -> Router {
.route("/api/{*rest}", any(|| async { ApiErr(AppError::NotFound) }))
.layer(cors);
- /* SPA 托管。**分两条路,因为它们的失败方式不一样**:
-
- `/assets` 下面是构建产物,文件名带内容哈希。这里的 ServeDir **不带兜底**,
- 所以缺文件就是 404。从前它和页面共用一个带 history fallback 的服务,于是
- 升级之后旧哈希的请求拿到的是 `200 text/html` 的首页——浏览器按模块脚本
- 解析一张网页,光凭 MIME 就拒绝执行,界面白屏(#616)。
-
- 缓存指示按文件名本来的含义给:带哈希的产物换了内容就换名字,可以
- `immutable` 存一年;`index.html` 每次都要回源确认,否则它会指着一批
- 已经不存在的哈希。少了这一条,升级要等浏览器的启发式缓存自己过期。 */
- let index = std::path::Path::new(&cfg.web_dist).join("index.html");
- if index.exists() {
- /* 每条路各自套自己的头。**层要挂在这一段的 Router 上,不能挂在整个
- app 上**——挂在 app 上,API 的响应也会跟着被扣上 `immutable`。 */
- let assets = Router::new()
- .fallback_service(ServeDir::new(
- std::path::Path::new(&cfg.web_dist).join("assets"),
- ))
- .layer(SetResponseHeaderLayer::overriding(
- header::CACHE_CONTROL,
- HeaderValue::from_static("public, max-age=31536000, immutable"),
- ));
- let spa = Router::new()
- .fallback_service(ServeDir::new(&cfg.web_dist).fallback(ServeFile::new(index)))
- .layer(SetResponseHeaderLayer::overriding(
- header::CACHE_CONTROL,
- HeaderValue::from_static("no-cache"),
- ));
- app = app.nest("/assets", assets).fallback_service(spa);
- tracing::info!("已托管前端产物: {}", cfg.web_dist);
- }
+ app = with_static_files(app, &cfg.web_dist);
// 最外层:先把请求来源放进 task-local,之后任何一层写审计都读得到
app.layer(TraceLayer::new_for_http())
diff --git a/crates/utopia-server/src/api/static_files_tests.rs b/crates/utopia-server/src/api/static_files_tests.rs
new file mode 100644
index 00000000..8a71fcc2
--- /dev/null
+++ b/crates/utopia-server/src/api/static_files_tests.rs
@@ -0,0 +1,89 @@
+//! 构建产物那一段的契约(#614 / #616)。不连库:`with_static_files` 不带 state。
+//!
+//! 这段代码破过两次,两次都是同一个形状——**一条路的失败被另一条路的成功语义
+//! 盖住了**。第一次是缺文件回首页(浏览器按模块脚本解析一张网页,白屏);
+//! 第二次是缺文件的 404 也被扣上 `immutable`,于是「这个文件不存在」被浏览器
+//! 记一年,而资源名带哈希,下一次部署请求的正是那个刚被记下的名字。
+//!
+//! 所以这里逐条钉的是**状态码、Content-Type 与缓存指示三者一起**:少看一样,
+//! 上面两次都能溜过去。
+use super::with_static_files;
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use axum::Router;
+use tower::ServiceExt;
+
+/// 一个最小的 dist:一张首页,一个带哈希名的产物。
+fn dist() -> tempfile::TempDir {
+ let dir = tempfile::tempdir().expect("temp dir");
+ std::fs::write(
+ dir.path().join("index.html"),
+ "<!doctype html><title>u</title>",
+ )
+ .expect("index");
+ std::fs::create_dir(dir.path().join("assets")).expect("assets dir");
+ std::fs::write(
+ dir.path().join("assets/app-d34db33f.js"),
+ "export default 1;",
+ )
+ .expect("asset");
+ dir
+}
+
+async fn get(path: &str) -> (StatusCode, Option<String>, Option<String>) {
+ let dir = dist();
+ let app = with_static_files(Router::new(), dir.path().to_str().expect("utf-8 path"));
+ let res = app
+ .oneshot(
+ Request::builder()
+ .uri(path)
+ .body(Body::empty())
+ .expect("request"),
+ )
+ .await
+ .expect("response");
+ let head = |name: &str| {
+ res.headers()
+ .get(name)
+ .and_then(|v| v.to_str().ok())
+ .map(str::to_owned)
+ };
+ (res.status(), head("content-type"), head("cache-control"))
+}
+
+#[tokio::test]
+async fn a_hashed_asset_is_served_and_may_be_kept_for_a_year() {
+ let (status, ctype, cache) = get("/assets/app-d34db33f.js").await;
+ assert_eq!(status, StatusCode::OK);
+ assert_eq!(ctype.as_deref(), Some("text/javascript"));
+ assert_eq!(
+ cache.as_deref(),
+ Some("public, max-age=31536000, immutable")
+ );
+}
+
+/// **缺掉的产物是 404,而且那条 404 不许被存起来。**
+/// 回首页会白屏(#616);把 404 存一年,则下一次部署的新哈希在那台机器上
+/// 一年拿不到——两条都要守,所以两个断言都在这里。
+#[tokio::test]
+async fn a_missing_asset_is_a_404_that_nobody_keeps() {
+ let (status, ctype, cache) = get("/assets/app-00000000.js").await;
+ assert_eq!(status, StatusCode::NOT_FOUND);
+ assert_ne!(ctype.as_deref(), Some("text/html"), "404 不许是一张网页");
+ assert_eq!(cache.as_deref(), Some("no-cache"));
+}
+
+/// 页面路由刷新拿首页——history fallback 还在,这一条是上面那条的对照。
+#[tokio::test]
+async fn a_page_route_still_gets_the_index() {
+ for path in ["/", "/graph", "/kb/anything/deep"] {
+ let (status, ctype, cache) = get(path).await;
+ assert_eq!(status, StatusCode::OK, "{path}");
+ assert_eq!(ctype.as_deref(), Some("text/html"), "{path}");
+ assert_eq!(
+ cache.as_deref(),
+ Some("no-cache"),
+ "{path} 的首页必须回源确认"
+ );
+ }
+}