Emit versioned asset bundles for immutable caching

Author: blackopsrepl

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
         run: |
           make clean
           make assets
-          git diff --exit-code static/sf/sf.css static/sf/sf.js
+          git diff --exit-code static/sf/sf.css static/sf/sf.js static/sf/sf.*.css static/sf/sf.*.js
 
       - name: Check formatting
         run: cargo fmt --all -- --check

Makefile

@@ -23,6 +23,8 @@ RUST_VERSION := 1.75+
 # ============== Asset Sources ==============
 CSS_SRC := $(sort $(wildcard css-src/*.css))
 JS_SRC  := $(sort $(wildcard js-src/*.js))
+VERSIONED_CSS := static/sf/sf.$(VERSION).css
+VERSIONED_JS := static/sf/sf.$(VERSION).js
 
 # ============== Phony Targets ==============
 .PHONY: banner help assets build build-release test test-quick test-doc test-unit test-one \
@@ -40,16 +42,18 @@ banner:
 
 # ============== Asset Targets ==============
 
-assets: static/sf/sf.css static/sf/sf.js
+assets: static/sf/sf.css static/sf/sf.js $(VERSIONED_CSS) $(VERSIONED_JS)
 
-static/sf/sf.css: $(CSS_SRC)
+static/sf/sf.css $(VERSIONED_CSS): $(CSS_SRC)
 	@printf "$(PROGRESS) CSS  sf.css ($(words $(CSS_SRC)) files)\n"
-	@cat $(CSS_SRC) > $@
+	@cat $(CSS_SRC) > static/sf/sf.css
+	@cp static/sf/sf.css $(VERSIONED_CSS)
 	@printf "$(GREEN)$(CHECK) CSS bundled$(RESET)\n"
 
-static/sf/sf.js: $(JS_SRC)
+static/sf/sf.js $(VERSIONED_JS): $(JS_SRC)
 	@printf "$(PROGRESS) JS   sf.js ($(words $(JS_SRC)) files)\n"
-	@cat $(JS_SRC) > $@
+	@cat $(JS_SRC) > static/sf/sf.js
+	@cp static/sf/sf.js $(VERSIONED_JS)
 	@printf "$(GREEN)$(CHECK) JS bundled$(RESET)\n"
 
 # ============== Build Targets ==============
@@ -228,7 +232,7 @@ publish: banner
 clean:
 	@printf "$(ARROW) Cleaning build artifacts...\n"
 	@cargo clean
-	@rm -f static/sf/sf.css static/sf/sf.js
+	@rm -f static/sf/sf.css static/sf/sf.js static/sf/sf.*.css static/sf/sf.*.js
 	@printf "$(GREEN)$(CHECK) Clean complete$(RESET)\n"
 
 # ============== Development ==============

README.md

@@ -23,6 +23,11 @@ let app = api::router(state)
 
 That's it. Every asset is compiled into the binary via `include_dir!`.
 
+For production caching, versioned bundle filenames are also emitted as
+`/sf/sf.<crate-version>.css` and `/sf/sf.<crate-version>.js`. Those versioned
+files are served with immutable caching, while the stable `sf.css` and `sf.js`
+paths remain available for compatibility.
+
 ## Screenshots
 
 **Planner123** — Gantt chart with dependency arrows, project-colored bars, and constraint scoring:
@@ -437,6 +442,10 @@ make
 cargo build
 ```
 
+Bundling writes both stable compatibility assets (`static/sf/sf.css`,
+`static/sf/sf.js`) and versioned assets (`static/sf/sf.<version>.css`,
+`static/sf/sf.<version>.js`).
+
 ## Acknowledgments
 
 solverforge-ui builds on these excellent open-source projects:

src/lib.rs

@@ -53,5 +53,56 @@ fn mime_from_path(path: &str) -> &'static str {
 }
 
 fn is_immutable(path: &str) -> bool {
-    path.starts_with("fonts/") || path.starts_with("vendor/") || path.starts_with("img/")
+    path.starts_with("fonts/")
+        || path.starts_with("vendor/")
+        || path.starts_with("img/")
+        || is_versioned_bundle(path)
+}
+
+fn is_versioned_bundle(path: &str) -> bool {
+    path.strip_prefix("sf.")
+        .and_then(|rest| rest.rsplit_once('.'))
+        .map(|(version, ext)| {
+            !version.is_empty()
+                && version.chars().all(|ch| {
+                    ch.is_ascii_digit() || ch == '.' || ch == '-' || ch.is_ascii_alphabetic()
+                })
+                && matches!(ext, "css" | "js")
+        })
+        .unwrap_or(false)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{is_immutable, is_versioned_bundle, mime_from_path};
+
+    #[test]
+    fn versioned_bundles_are_detected() {
+        assert!(is_versioned_bundle("sf.0.1.0.css"));
+        assert!(is_versioned_bundle("sf.0.1.0.js"));
+        assert!(is_versioned_bundle("sf.0.2.0-beta.1.js"));
+        assert!(!is_versioned_bundle("sf.css"));
+        assert!(!is_versioned_bundle("sf.js"));
+        assert!(!is_versioned_bundle("vendor/sf.0.1.0.js"));
+    }
+
+    #[test]
+    fn immutable_cache_policy_includes_versioned_bundles() {
+        assert!(is_immutable("fonts/space-grotesk.woff2"));
+        assert!(is_immutable("vendor/split/split.min.js"));
+        assert!(is_immutable("img/solverforge-logo.svg"));
+        assert!(is_immutable("sf.0.1.0.css"));
+        assert!(is_immutable("sf.0.1.0.js"));
+        assert!(!is_immutable("sf.css"));
+        assert!(!is_immutable("sf.js"));
+    }
+
+    #[test]
+    fn mime_detection_still_works_for_versioned_assets() {
+        assert_eq!(mime_from_path("sf.0.1.0.css"), "text/css; charset=utf-8");
+        assert_eq!(
+            mime_from_path("sf.0.1.0.js"),
+            "application/javascript; charset=utf-8"
+        );
+    }
 }