site: add Fathom analytics, and fix the caching rule it sits beside

Two changes to what the live site sends.

Analytics: Fathom's tag goes in every template's <head>, deferred. It is
cookieless and collects nothing about a person, so no consent banner —
but it is a third party, so the CSP names cdn.usefathom.com for script
and connect rather than opening the door generally, and the tests that
said 'no script at all' now say 'no script this site depends on, and no
origin nobody chose'.

Caching: the host concatenates a header two matching rules both set
rather than overriding, so /* and /static/* each setting Cache-Control
sent 'max-age=0, must-revalidate, max-age=31536000, immutable' on the
stylesheet — first max-age wins, and the year-long cache never happened.
Measured on the live site, which is where the from-memory assumption in
task 32 said to check it. Now /static/* is the only rule that sets it
and HTML takes the host's revalidating default; the post-deploy checks
in site/README.md verify both ends.
This commit is contained in:
istos
2026-07-31 15:39:46 +02:00
parent fbd273a6ae
commit 662ecc001f
9 changed files with 127 additions and 60 deletions
+27 -12
View File
@@ -77,6 +77,7 @@ widening the page, and that the site still ships no JavaScript.
| Worker | `bench-site` |
| Route | `bench.12vectors.com`, a **custom domain** — Cloudflare owns the hostname at the zone level and creates the DNS record itself |
| Served from | `site/dist/`, uploaded whole on every deploy |
| Analytics | [Fathom](https://usefathom.com), site `ZPKDEHCV` — cookieless, no personal data, no consent banner. The only third party the pages touch |
| Config | `site/wrangler.jsonc` (routing) and `site/root/_headers` (caching, security) |
Deploys are run by hand, by a person, exactly as releases are
@@ -129,7 +130,12 @@ answers rather than files:
page **with a 404 status**, not the landing page with a 200.
4. `curl -sI https://bench.12vectors.com/` shows
`x-content-type-options`, `referrer-policy`,
`strict-transport-security` and a `cache-control` that revalidates.
`strict-transport-security` and a `cache-control` that revalidates —
the last one coming from the host's default now, not from `_headers`,
which is exactly why it is checked rather than assumed. Then
`curl -sI https://bench.12vectors.com/static/site.css` must show
`max-age=31536000, immutable` **once**, with no second `max-age`
beside it.
## How it is served
@@ -141,17 +147,26 @@ answers rather than files:
with a 404 status. That page is a normal manifest entry (`/404.html`,
layout `notfound`) — the site's own design, its own nav, and a link
back to the landing page.
- **Two caching policies, because there are two kinds of file.** HTML
revalidates on every view, so a deploy is visible on the next reload
with nobody clearing anything. Everything under `/static/` is kept for
a year and never re-checked, which is only safe because the stylesheet
and the icon are linked with a `?v=<hash>` of their own contents:
change the file and the url changes with it.
- **Baseline headers, no third parties.** `nosniff`, a referrer policy,
a year of HSTS, `X-Frame-Options`, and a Content-Security-Policy of
`default-src 'none'` with `'self'` for styles, fonts and images. The
site collects nothing and loads nothing from anywhere else; the CSP is
that promise in a form the browser enforces.
- **One rule sets `Cache-Control`, and it is `/static/*`.** The host
*concatenates* a header two matching rules both set — it does not
override, whatever the ordering suggests. Measured live: `/*` and
`/static/*` each setting `Cache-Control` produced
`max-age=0, must-revalidate, max-age=31536000, immutable` on the
stylesheet, and the first `max-age` wins in every browser, so the
year-long cache never happened. Now only `/static/*` sets it — safe
because the stylesheet and the icon are linked with a `?v=<hash>` of
their own contents — and HTML takes the host's own revalidating
default, which check 4 below confirms after every deploy.
- **Baseline headers, and one third party by choice.** `nosniff`, a
referrer policy, a year of HSTS, `X-Frame-Options`, and a
Content-Security-Policy of `default-src 'none'` with `'self'` for
styles, fonts and images. The one origin named besides this one is
`cdn.usefathom.com`: Fathom serves the analytics script and receives
its pageviews. It sets no cookie and collects nothing about a person,
which is why the site still needs no consent banner — but it is a
third party, and the policy names it rather than opening the door
generally. A second one would fail
`tests/test_site_deploy.py` rather than slip in.
## What is where
+26 -13
View File
@@ -5,9 +5,18 @@
# site/build.py, because the host looks for it at the root of the build
# and nowhere else.
#
# Rules apply in order and a later rule wins on a header it repeats. The
# two blocks below are written so that even a host that merged them
# instead would land on the safe side: HTML would still revalidate.
# Rules do NOT override each other: a header two matching rules both set
# arrives concatenated. Measured on the live site, not assumed —
# /* and /static/* both setting Cache-Control produced
#
# cache-control: public, max-age=0, must-revalidate, public,
# max-age=31536000, immutable
#
# on the stylesheet, and the first max-age wins in every browser, so the
# year-long cache never happened. So exactly one rule may set a given
# header: Cache-Control is set on /static/* alone, and HTML is left to
# the host's own default, which is the revalidating one. Check #4 after a
# deploy is what keeps that honest.
# Everything, so that no page can ever forget one of these.
#
@@ -17,26 +26,30 @@
# `preload`: that is a submission to browser
# vendors and a commitment this card did not make
# X-Frame-Options nothing here is meant to be framed
# CSP the runtime form of the site's own promise —
# no analytics, no font CDN, no third-party
# anything. `default-src 'none'` means an asset
# must be named below to load at all, and no
# CSP the runtime form of the site's own promise.
# `default-src 'none'` means an asset must be
# named below to load at all, and no
# 'unsafe-inline' anywhere means an injected
# <script> does not run
# Cache-Control HTML revalidates on every view, so a deploy is
# visible on the next reload. The ETag makes that
# a 304 rather than a re-download
# <script> does not run. One origin besides
# 'self' is named: cdn.usefathom.com, which
# serves the analytics script and receives its
# pageviews. Fathom sets no cookie and collects
# nothing about a person, which is why it needs
# no banner — but it is a third party, and the
# policy says so out loud rather than quietly
# allowing everything
/*
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Frame-Options: DENY
Content-Security-Policy: default-src 'none'; style-src 'self'; font-src 'self'; img-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
Cache-Control: public, max-age=0, must-revalidate
Content-Security-Policy: default-src 'none'; style-src 'self'; font-src 'self'; img-src 'self'; script-src https://cdn.usefathom.com; connect-src https://cdn.usefathom.com; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
# The stylesheet and the icon are linked with a ?v=<hash> of their own
# contents (site/build.py, stamp()), and the fonts never change under a
# given filename. All of it is safe to keep for a year and never check:
# a deploy that changes the stylesheet changes the url that asks for it.
# The only rule in this file that sets Cache-Control, for the reason at
# the top — a second one would concatenate rather than lose.
/static/*
Cache-Control: public, max-age=31536000, immutable
+4
View File
@@ -21,6 +21,10 @@
<link rel="canonical" href="$canonical">
<link rel="icon" href="$icon">
<link rel="stylesheet" href="$stylesheet">
<!-- Fathom — cookieless analytics: pageviews only, nothing about a
person, so no banner. The one third-party request this site makes;
root/_headers names cdn.usefathom.com in the CSP for exactly it. -->
<script src="https://cdn.usefathom.com/script.js" data-site="ZPKDEHCV" defer></script>
</head>
<body class="page-article">
+4
View File
@@ -35,6 +35,10 @@
<meta name="twitter:card" content="summary">
<link rel="icon" href="$icon">
<link rel="stylesheet" href="$stylesheet">
<!-- Fathom — cookieless analytics: pageviews only, nothing about a
person, so no banner. The one third-party request this site makes;
root/_headers names cdn.usefathom.com in the CSP for exactly it. -->
<script src="https://cdn.usefathom.com/script.js" data-site="ZPKDEHCV" defer></script>
</head>
<body class="page-home">
+4
View File
@@ -20,6 +20,10 @@
<meta name="robots" content="noindex">
<link rel="icon" href="$icon">
<link rel="stylesheet" href="$stylesheet">
<!-- Fathom — cookieless analytics: pageviews only, nothing about a
person, so no banner. The one third-party request this site makes;
root/_headers names cdn.usefathom.com in the CSP for exactly it. -->
<script src="https://cdn.usefathom.com/script.js" data-site="ZPKDEHCV" defer></script>
</head>
<body class="page-notfound">
+10 -7
View File
@@ -194,12 +194,15 @@ class TheRealSiteBuilds(unittest.TestCase):
self.assertIn('href="/concepts/claiming-a-card/"', article)
self.assertIn("Concepts", article)
def test_nothing_the_pages_load_is_third_party(self):
"""The acceptance criterion, mechanised: every asset a browser
would fetch — stylesheet, icon, script, font — is same-origin,
and nothing preconnects anywhere. A <link rel=canonical> is a
statement about this page, not a fetch, so it is not one of
these; anything that makes the browser open a connection is."""
def test_the_only_third_party_is_the_one_that_was_chosen(self):
"""Every asset a browser would fetch — stylesheet, icon, font —
is same-origin, and nothing preconnects anywhere. The single
exception is the analytics script, named here and in the CSP, so
a second third party has to be a deliberate edit to this list
rather than something that slipped into a template. A <link
rel=canonical> is a statement about this page, not a fetch, so it
is not one of these; anything that opens a connection is."""
chosen = ("https://cdn.usefathom.com/",)
fetching = {"stylesheet", "icon", "shortcut icon", "preload",
"prefetch", "preconnect", "dns-prefetch", "manifest",
"modulepreload"}
@@ -217,7 +220,7 @@ class TheRealSiteBuilds(unittest.TestCase):
r"""<(?:script|img|iframe)\b[^>]*\bsrc=["']([^"']+)""",
html, re.IGNORECASE):
self.assertTrue(
url.startswith("/"),
url.startswith("/") or url.startswith(chosen),
f'{entry["path"]} loads {url} from somewhere else')
css = (self.out / "static" / "site.css").read_text("utf-8")
+35 -21
View File
@@ -242,13 +242,22 @@ class TheHeaderPolicyTravelsWithTheBuild(Built):
def test_no_page_needs_what_the_policy_forbids(self):
"""The CSP carries no 'unsafe-inline', so an inline <script> or a
style="" attribute is a page that renders right in every test
here and wrong in production. The only place that can be caught
before a deploy is the build output."""
here and wrong in production. A script with a src is fine only
if the policy names where it comes from. The only place that can
be caught before a deploy is the build output."""
allowed = re.findall(r"https://[^\s;]+",
rule("/*")["Content-Security-Policy"])
for path in sorted(self.out.rglob("*.html")):
html = path.read_text("utf-8")
where = path.relative_to(self.out)
self.assertNotIn("<script", html.lower(),
f"{where} has a script the CSP would block")
for tag in re.findall(r"<script[^>]*>", html, re.I):
src = re.search(r'src="([^"]+)"', tag)
self.assertIsNotNone(
src, f"{where} has an inline script the CSP would block")
self.assertTrue(
src.group(1).startswith("/")
or any(src.group(1).startswith(o) for o in allowed),
f"{where} loads {src.group(1)}, which the CSP forbids")
self.assertNotRegex(
html, r"""\sstyle\s*=\s*["']""",
f"{where} has an inline style the CSP would block")
@@ -270,39 +279,44 @@ class EveryResponseCarriesTheBaseline(unittest.TestCase):
"preload is a submission to browser vendors, "
"not a header to set in passing")
def test_nothing_third_party_can_load(self):
"""The site's promise — no analytics, no font CDN — as something
the browser enforces rather than something a test asserted once
at build time."""
def test_only_the_analytics_origin_can_load(self):
"""The site's promise as something the browser enforces rather
than something a test asserted once at build time. Exactly one
third party is named — the cookieless analytics — and the day a
second one appears, this fails rather than shrugging."""
policy = self.everything["Content-Security-Policy"]
self.assertIn("default-src 'none'", policy)
self.assertNotIn("unsafe-inline", policy)
self.assertNotIn("unsafe-eval", policy)
self.assertNotIn("*", policy)
self.assertNotIn("//", policy, "the policy names another origin")
self.assertEqual({"https://cdn.usefathom.com"},
set(re.findall(r"https://[^\s;]+", policy)),
"the policy names an origin nobody decided on")
self.assertNotIn("font-src https", policy,
"the fonts are self-hosted and stay that way")
class TheTwoKindsOfFileAreCachedDifferently(unittest.TestCase):
"""The edge case in the task: a stale HTML page must not survive a
deploy, while the assets it links may live for a year."""
def test_html_revalidates_on_every_view(self):
value = rule("/*")["Cache-Control"]
self.assertIn("max-age=0", value)
self.assertIn("must-revalidate", value)
self.assertNotIn("immutable", value)
def test_fingerprinted_assets_are_kept_for_a_year(self):
value = rule("/static/*")["Cache-Control"]
self.assertIn("max-age=31536000", value)
self.assertIn("immutable", value)
def test_the_general_rule_comes_first(self):
"""Order is the whole argument: /static/* overrides /* on
Cache-Control, and a host that merged them instead of overriding
would land on max-age=0 — the safe side."""
patterns = [pattern for pattern, _ in read_headers(HEADERS)]
self.assertLess(patterns.index("/*"), patterns.index("/static/*"))
def test_exactly_one_rule_sets_cache_control(self):
"""The host concatenates a header two matching rules both set,
it does not override — measured on the live site, where /* and
/static/* together produced 'max-age=0, must-revalidate,
max-age=31536000, immutable' and the first max-age won. So the
year-long rule must be the only one, and HTML takes the host's
own revalidating default."""
setters = [pattern for pattern, headers in read_headers(HEADERS)
if "Cache-Control" in headers]
self.assertEqual(["/static/*"], setters,
"a second Cache-Control rule would concatenate "
"with this one rather than lose to it")
# ── fingerprinting ────────────────────────────────────────────────────
+9 -1
View File
@@ -190,7 +190,15 @@ class WhatThePageMayNotSay(LandingCase):
for page in self.manifest["pages"]:
html_text = text_of(BUILDER.target_for(self.out, page["path"]))
with self.subTest(page=page["path"]):
self.assertNotIn("<script", html_text.lower())
# The analytics tag is deferred and nothing reads it back:
# every word, link and menu works with scripting off. Any
# *other* script would be the page needing one.
scripts = re.findall(r"<script\b[^>]*>", html_text, re.I)
for tag in scripts:
self.assertIn("cdn.usefathom.com", tag,
"a script the page would depend on")
self.assertIn("defer", tag,
"even analytics waits for the page")
self.assertNotIn("<noscript", html_text.lower())
self.assertIsNone(
re.search(r"\son[a-z]+=", html_text, re.IGNORECASE),
+8 -6
View File
@@ -324,15 +324,17 @@ class TheBuiltPagesCarryTheMenus(unittest.TestCase):
if "toc-link" in self.CONTENTS.search(html).group(1)]
self.assertTrue(filled, "no article page's contents strip has links")
def test_the_site_ships_no_script(self):
"""One menu that opens and closes is a <details>. Nothing on this
site justifies the first line of JavaScript on it — and the
Content-Security-Policy in site/root/_headers forbids one."""
def test_the_menus_need_no_script(self):
"""One menu that opens and closes is a <details>. The site ships
no JavaScript of its own — the only script on a page is the
third-party analytics tag, which no menu, link or word depends
on, and the CSP in site/root/_headers names it explicitly."""
self.assertEqual([], sorted(self.out.rglob("*.js")))
for entry in self.manifest["pages"]:
html = BUILDER.target_for(self.out, entry["path"]).read_text("utf-8")
self.assertNotIn("<script", html.lower(),
f'{entry["path"]} loads a script')
for tag in re.findall(r"<script\b[^>]*>", html, re.I):
self.assertIn("cdn.usefathom.com", tag,
f'{entry["path"]} loads a script of its own')
def test_every_built_page_declares_the_viewport(self):
for entry in self.manifest["pages"]: