Public: anyone can read this; the crew can change it.

Proper web architecture: HTML is small, cacheable and streamed; everything else is a long-lived asset #8041

Parked opened this in answer to
Closed without merging

Home is now small, cacheable HTML with its assets in hashed files, but the pull is only partly done. There are no before/after numbers from #7559, no purge, and no body streaming. I haven't run the full suite.

Notes

stopped parked by the crew deploy 8fc0e14

opened this

Home is now small, cacheable HTML with its assets in hashed files, but the pull is only partly done. There are no before/after numbers from #7559, no purge, and no body streaming. I haven't run the full suite.

What changed

  • Icons: one hashed immutable SVG sprite at /assets/i-<hash>.svg. Each <use> points at it, so no page carries a drawing.
  • Scripts and CSP: each page's inline script is now a hashed file, /assets/page-<hash>.js. The per-request nonce is gone. The CSP is script-src 'self' plus sha256- hashes for the two inline <style> blocks, so a page is the same bytes for everyone.
  • Home size: signed-out / is about 10 KB raw. The budget is 40 KB.
  • Edge cache: signed-out home, explore and a repository's front page send public, max-age=0, s-maxage=60, stale-while-revalidate=300 with an ETag and a 304 path (src/http/edge_cache.ts). Signed-in pages, and any request with a cookie, Authorization or edge-login header, stay no-cache with no ETag.
  • Early flush: every page sends Link: rel=preload for the stylesheet and scripts, which an edge can turn into 103 Early Hints.
  • Speculation rules: a Speculation-Rules header points at one hashed rules file. It prefetches on hover or pointer-down only, and skips the API, assets, raw files and archives.
  • Docs and tests: docs/web.md states the rules. test/web-budget.test.ts counts the bytes, and also checks that:
    • there is no nonce and no inline script or <symbol>;
    • the sprite is immutable and the 304 path works;
    • a signed-in page is never edge-cached;
    • there is no no-store and no unload handler.
  • Existing tests: I updated tests that read inline script text to read the script files the page names (withScripts, pageScriptOf in test/helpers/page-script.ts).

What I did not do

  • Purge by event: the edge's API credentials aren't the forge's to hold, so staleness is bounded to 60 s plus 300 s stale instead. This is in docs/web.md.
  • Chunked body streaming: the render is still one string.
  • Before/after numbers from #7559: I can't produce them from this sandbox.
  • Repository page budget: the 40 KB budget is only tested on / and /explore. A repository's front page gets the edge cache but has no byte test yet.
  • Other pages: left as the mechanical follow-up.

Checks

  • Passing: tsc and the gate are clean, and design-lint is green. The 1,014 tests across the web, page, home, render, csp, security, etag and cache files pass. The other files I touched (board, map, migrate, offline, live, live-pages, feed-page, releases-page, studio-door) pass.
  • Not run: the full suite.
  • Failing in the sandbox: security-floor-routes timed out at 9 s, with posix_spawn 'git' errors in its log. I did not check it against main, so I haven't ruled out a regression from the new asset routes. The Chromium axe test fails because Chromium offers no DevTools endpoint here.

Try it: curl -sI the signed-out / and read cache-control, link and speculation-rules. Then fetch the sprite named in the markup.

Closes #8016

3 earlier comments
commented

Home is now small, cacheable HTML with its assets in hashed files, but the pull is only partly done. There are no before/after numbers from #7559, no purge, and no body streaming. I haven't run the full suite.

What changed

  • Icons: one hashed immutable SVG sprite at /assets/i-<hash>.svg. Each <use> points at it, so no page carries a drawing.
  • Scripts and CSP: each page's inline script is now a hashed file, /assets/page-<hash>.js. The per-request nonce is gone. The CSP is script-src 'self' plus sha256- hashes for the two inline <style> blocks, so a page is the same bytes for everyone.
  • Home size: signed-out / is about 10 KB raw. The budget is 40 KB.
  • Edge cache: signed-out home, explore and a repository's front page send public, max-age=0, s-maxage=60, stale-while-revalidate=300 with an ETag and a 304 path (src/http/edge_cache.ts). Signed-in pages, and any request with a cookie, Authorization or edge-login header, stay no-cache with no ETag.
  • Early flush: every page sends Link: rel=preload for the stylesheet and scripts, which an edge can turn into 103 Early Hints.
  • Speculation rules: a Speculation-Rules header points at one hashed rules file. It prefetches on hover or pointer-down only, and skips the API, assets, raw files and archives.
  • Docs and tests: docs/web.md states the rules. test/web-budget.test.ts counts the bytes, and also checks that:
    • there is no nonce and no inline script or <symbol>;
    • the sprite is immutable and the 304 path works;
    • a signed-in page is never edge-cached;
    • there is no no-store and no unload handler.
  • Existing tests: I updated tests that read inline script text to read the script files the page names (withScripts, pageScriptOf in test/helpers/page-script.ts).

What I did not do

  • Purge by event: the edge's API credentials aren't the forge's to hold, so staleness is bounded to 60 s plus 300 s stale instead. This is in docs/web.md.
  • Chunked body streaming: the render is still one string.
  • Before/after numbers from #7559: I can't produce them from this sandbox.
  • Repository page budget: the 40 KB budget is only tested on / and /explore. A repository's front page gets the edge cache but has no byte test yet.
  • Other pages: left as the mechanical follow-up.

Checks

  • Passing: tsc and the gate are clean, and design-lint is green. The 1,014 tests across the web, page, home, render, csp, security, etag and cache files pass. The other files I touched (board, map, migrate, offline, live, live-pages, feed-page, releases-page, studio-door) pass.
  • Not run: the full suite.
  • Failing in the sandbox: security-floor-routes timed out at 9 s, with posix_spawn 'git' errors in its log. I did not check it against main, so I haven't ruled out a regression from the new asset routes. The Chromium axe test fails because Chromium offers no DevTools endpoint here.

Try it: curl -sI the signed-out / and read cache-control, link and speculation-rules. Then fetch the sprite named in the markup.

commented

The check's 14 failures had two causes, both now fixed and pushed. I reran the failing test files here and they pass, with tsc and the gate clean. I did not run the full suite; the forge's check will.

  • Docs link: docs/web.md wasn't listed under "Where the rest is" in README.md, so "every top-level docs/*.md is linked" failed. I added the link.
  • Inline-script assertions: twelve tests read script text out of the page HTML. Now that page scripts are hashed files, I changed them to fetch the script files the page names and assert on that. The files are system-stream, first-admin, studio-search, claim-link, studio-runs, confirm-app-stop, tui-limbs, pull-checks-line-route, issue-teams-doors and review-act. The code under test is unchanged.
  • tui-sshkeys: it also failed in the check (shard 9), but it passes when I run it alone. I changed nothing for it and take it to be flaky.
commented

I found no cause in the code and changed nothing, so the new commit is empty and only there to make the forge run the check again.

Here is why I think the four failures are load flakes:

  • The four tests: the MCP body-limit test and the h hold test pass on their own. They also passed on repeat runs of test/report-discovery.test.ts, test/tui-pull-hold.test.ts and the egress terminal test file, test/tui-egress.test.ts.
  • What the log shows: the two egress terminal tests in shard 51 ran for 20 s and 0.26 s, which looks like timeouts on a loaded machine. The MCP test failed in 2.6 ms, which looks like a failure before it reached the server.
  • Not tried: I didn't reproduce the full 62-shard run here.

bun scripts/gate.ts and bun x tsc --noEmit printed nothing, which I read as clean.

If the same tests fail again, the next step is to read the shard logs for the actual assertion.

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs