xonecas.io
8356
Wx

www-xonecas-io / commit e503210

assets are linked with a content hash, so a rebuild never leaves a stale site.css (1026)

Co-Authored-By: Claude Opus 5.5

Sean Caetano Martin2026-11-08 e50321033fabcdd0c058c43e1fd394bca82afe2a parent ebc49a5

8 files changed

internal/site/assets.go+59−0
@@ -0,0 +1,59 @@
1+package site
2+
3+import (
4+ "crypto/sha256"
5+ "fmt"
6+ "io/fs"
7+ "os"
8+ "os/exec"
9+ "path/filepath"
10+ "strings"
11+)
12+
13+// versions maps each asset's path to a hash of its content. Pages link an asset with ?v=<hash>,
14+// so a rebuild that changes it gives it a new address, and browsers fetch it again.
15+var versions = map[string]string{}
16+
17+// asset is the address of the asset at p, with its version.
18+func asset(p string) string {
19+ if v, ok := versions[strings.TrimPrefix(p, "/")]; ok {
20+ return p + "?v=" + v
21+ }
22+ return p
23+}
24+
25+// writeAssets copies the static files into out, compiles site.css with a tailwind binary, and hashes them all.
26+func writeAssets(out, tailwind string) error {
27+ if err := os.MkdirAll(out, 0o755); err != nil {
28+ return err
29+ }
30+ names := []string{"site.css"}
31+ err := fs.WalkDir(static, "static", func(path string, d fs.DirEntry, err error) error {
32+ if err != nil || d.IsDir() {
33+ return err
34+ }
35+ b, err := static.ReadFile(path)
36+ if err != nil {
37+ return err
38+ }
39+ names = append(names, strings.TrimPrefix(path, "static/"))
40+ return os.WriteFile(filepath.Join(out, names[len(names)-1]), b, 0o644)
41+ })
42+ if err != nil {
43+ return err
44+ }
45+ if tailwind != "" {
46+ cmd := exec.Command(tailwind, "-i", "internal/site/assets/site.css", "-o", filepath.Join(out, "site.css"), "--minify")
47+ cmd.Stderr = os.Stderr
48+ if err := cmd.Run(); err != nil {
49+ return err
50+ }
51+ }
52+ versions = map[string]string{}
53+ for _, name := range names {
54+ if b, err := os.ReadFile(filepath.Join(out, name)); err == nil {
55+ versions[name] = fmt.Sprintf("%x", sha256.Sum256(b))[:10]
56+ }
57+ }
58+ return nil
59+}
internal/site/build.go+10−26
@@ -7,9 +7,7 @@ import (
77 "errors"
88 "fmt"
99 "html/template"
10- "io/fs"
1110 "os"
12- "os/exec"
1311 "path/filepath"
1412 "slices"
1513 "strconv"
@@ -34,6 +32,7 @@ var funcs = template.FuncMap{
3432 }
3533 return s
3634 },
35+ "asset": asset,
3736 "inc": func(i int) int { return i + 1 },
3837 "maxDiff": func() int { return MaxDiffLines },
3938 "dec": func(i int) int { return i - 1 },
@@ -56,7 +55,10 @@ var pages = template.Must(template.New("").Funcs(funcs).ParseFS(templates, "temp
5655 func Build(projects []project.Project, out, tailwind string) error {
5756 shown := slices.DeleteFunc(slices.Clone(projects), func(p project.Project) bool { return p.Hidden != "" })
5857 rows := Rows(shown)
59- stamp, fresh, err := readStamp(out)
58+ if err := writeAssets(out, tailwind); err != nil {
59+ return err
60+ }
61+ stamp, fresh, err := readStamp(out, fmt.Sprint(versions))
6062 if err != nil {
6163 return err
6264 }
@@ -96,17 +98,12 @@ func Build(projects []project.Project, out, tailwind string) error {
9698 return err
9799 }
98100 }
99- if err := copyStatic(out); err != nil || tailwind == "" {
100- return err
101- }
102- cmd := exec.Command(tailwind, "-i", "internal/site/assets/site.css", "-o", filepath.Join(out, "site.css"), "--minify")
103- cmd.Stderr = os.Stderr
104- return cmd.Run()
101+ return nil
105102 }
106103
107-// readStamp hashes this program, which holds every template, and says whether out was built by it.
108-// Pages that never change, such as commits, are only rendered again by a different program.
109-func readStamp(out string) (stamp string, fresh bool, err error) {
104+// readStamp hashes this program, which holds every template, with the asset versions, and says whether out was built by them.
105+// Pages that never change, such as commits, are only rendered again by a different program or new assets.
106+func readStamp(out, assets string) (stamp string, fresh bool, err error) {
110107 exe, err := os.Executable()
111108 if err != nil {
112109 return "", false, err
@@ -115,7 +112,7 @@ func readStamp(out string) (stamp string, fresh bool, err error) {
115112 if err != nil {
116113 return "", false, err
117114 }
118- stamp = fmt.Sprintf("%x", sha256.Sum256(b))
115+ stamp = fmt.Sprintf("%x %s", sha256.Sum256(b), assets)
119116 old, _ := os.ReadFile(filepath.Join(out, ".stamp"))
120117 return stamp, string(old) == stamp, nil
121118 }
@@ -131,16 +128,3 @@ func render(path, name string, data any) error {
131128 defer f.Close()
132129 return pages.ExecuteTemplate(f, name, data)
133130 }
134-
135-func copyStatic(out string) error {
136- return fs.WalkDir(static, "static", func(path string, d fs.DirEntry, err error) error {
137- if err != nil || d.IsDir() {
138- return err
139- }
140- b, err := static.ReadFile(path)
141- if err != nil {
142- return err
143- }
144- return os.WriteFile(filepath.Join(out, strings.TrimPrefix(path, "static/")), b, 0o644)
145- })
146-}
internal/site/build_test.go+4−0
@@ -74,6 +74,10 @@ func TestBuild(t *testing.T) {
7474 t.Errorf("projects/hello/index.html is missing %q", want)
7575 }
7676 }
77+ page, err = os.ReadFile(filepath.Join(out, "index.html"))
78+ if err != nil || !strings.Contains(string(page), `src="/egg.js?v=`) {
79+ t.Errorf("home page links egg.js without its version: %v", err)
80+ }
7781 page, err = os.ReadFile(filepath.Join(out, "activity/index.html"))
7882 if err != nil || !strings.Contains(string(page), `href="/projects/hello/commit/`) {
7983 t.Errorf("activity page does not list hello's commit: %v", err)
internal/site/templates/activity.html+1−1
@@ -22,5 +22,5 @@
2222 <nav class="pager" aria-label="Pages" data-page="{{.Page}}" data-pages="{{.Pages}}" data-href="/activity/{{.Year}}/{n}" hidden></nav>
2323 </div>
2424 </main>
25-<script src="/pager.js"></script>
25+<script src="{{asset "/pager.js"}}"></script>
2626 {{template "foot"}}{{end}}
internal/site/templates/components.html+1−1
@@ -2,7 +2,7 @@
22
33 {{define "nav"}}
44 <header class="border-b-[1.5px] border-ink"><div class="flex flex-wrap items-center gap-x-6 gap-y-2 px-4 sm:px-8 py-3 max-w-[1440px] mx-auto">
5- <a href="/" id="face" class="group relative flex items-center gap-2 font-bold text-xl"><img src="/logo.svg" alt="" width="32" height="32" class="rounded-[2px]">xonecas.io
5+ <a href="/" id="face" class="group relative flex items-center gap-2 font-bold text-xl"><img src="{{asset "/logo.svg"}}" alt="" width="32" height="32" class="rounded-[2px]">xonecas.io
66 <span id="quip" role="tooltip" class="pointer-events-none absolute left-0 top-full mt-2 z-10 hidden group-hover:block group-focus-visible:block w-max max-w-[18rem] rounded-[2px] bg-ink text-paper px-2 py-1 text-xs font-normal">Don't click!</span></a>
77 <nav class="flex gap-5 font-semibold">
88 {{range $l := list "Overview" "Projects" "Activity"}}<a href="{{if eq $l "Overview"}}/{{else}}/{{lower $l}}/{{end}}" class="{{if eq $l $}}underline underline-offset-[6px] decoration-[3px]{{else}}no-underline{{end}}">{{$l}}</a>{{end}}
internal/site/templates/layout.html+3−3
@@ -3,10 +3,10 @@
33 <meta charset="utf-8">
44 <meta name="viewport" content="width=device-width,initial-scale=1">
55 <title>{{.}} · xonecas.io</title>
6-<link rel="icon" href="/logo.svg" type="image/svg+xml">
6+<link rel="icon" href="{{asset "/logo.svg"}}" type="image/svg+xml">
77 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
88 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=IBM+Plex+Sans+Condensed:wght@400;600;700&family=IBM+Plex+Serif:ital@1&display=swap">
9-<link rel="stylesheet" href="/site.css">
9+<link rel="stylesheet" href="{{asset "/site.css"}}">
1010 <script>/* The saved theme, before the first paint; #theme flips it. With none saved, the system decides. */
1111 const root = document.documentElement, mode = () => root.dataset.theme || (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
1212 try { if (localStorage.theme) root.dataset.theme = localStorage.theme; } catch {}
@@ -16,7 +16,7 @@ addEventListener("click", e => {
1616 try { localStorage.theme = root.dataset.theme; } catch {}
1717 });
1818 </script>
19-<script src="/egg.js" defer></script>
19+<script src="{{asset "/egg.js"}}" defer></script>
2020 <body class="bg-paper text-ink font-sans text-[15.5px] leading-snug">
2121 {{end}}
2222 {{define "foot"}}</body>
internal/site/templates/projects.html+2−2
@@ -20,6 +20,6 @@
2020 <p id="none" hidden class="py-6 text-soft">No project matches.</p>
2121 <nav class="pager" aria-label="Pages" hidden></nav>
2222 </main>
23-<script src="/pager.js"></script>
24-<script src="/projects.js"></script>
23+<script src="{{asset "/pager.js"}}"></script>
24+<script src="{{asset "/projects.js"}}"></script>
2525 {{template "foot"}}{{end}}
tickets/1026-browsers-keep-a-stale-site-css-after-a-rebuild.md+19−2
@@ -2,14 +2,31 @@
22 id: 1026
33 title: Browsers keep a stale site.css after a rebuild
44 type: bug
5-status: inbox
5+status: review
66 priority: p2
77 area: site
88 created: 2026-11-08T04:16:55Z
9-updated: 2026-11-08T04:16:55Z
9+updated: 2026-11-08T05:23:59Z
1010 source: agent
11+moves: 2026-11-08T05:07:40Z inbox doing drag; 2026-11-08T05:23:59Z doing review agent
1112 ---
1213
1314 After 'make build' changed site.css, agent-browser kept using the old one on reload: the 1020 slider rendered unstyled until I re-fetched /site.css with cache: 'reload'. Pages link a fixed /site.css, and the dev server sends Last-Modified with no Cache-Control, so browsers cache it heuristically. The same will hit visitors after a deploy.
1415
1516 Seen: once, in the VM's agent-browser on 192.168.122.10:8080. Not checked: other static files (projects.js, egg.js), and how Caddy would send them.
17+
18+## Notes
19+
20+- 2026-11-08 05:23Z (agent): Fixed: every page links its assets with a content hash, e.g. /site.css?v=274e0b6425, /egg.js?v=88ac0c5d7a. When a rebuild changes a file, its address changes, so a browser can't use a stale cached copy. This covers site.css, egg.js, pager.js, projects.js and logo.svg (both the favicon and the header image).
21+
22+ How:
23+ - New internal/site/assets.go. writeAssets copies the static files, runs Tailwind and hashes the results (sha256, first 10 hex), and the template func 'asset' adds the ?v=. copyStatic and the Tailwind step moved out of build.go to the start of Build, so the hashes exist before any page renders.
24+ - The asset versions are now part of public/.stamp. Otherwise commit pages, which are skipped when the build stamp hasn't changed, would keep linking an old version.
25+
26+ The cost: a rebuild that changes CSS or JS re-renders all 2,830 commit pages, about 65s. A rebuild with no changes stays at about 7s. Any template or Go change already did a full re-render, and most CSS changes come with a template change.
27+
28+ Checked:
29+ - go vet and go test pass. TestBuild now checks that the home page links egg.js with a version.
30+ - In agent-browser I loaded /, added a rule to assets/site.css (dt colour rgb(1,2,3)), ran make build and did a plain reload with no cache tricks. The new colour applied. I reverted the CSS and rebuilt, and a plain reload shows the old colour again.
31+
32+ Not checked: the HTML pages themselves can still be cached heuristically by browsers, since the dev server sends no Cache-Control. Caddy wasn't checked either.