Merge pull request #27 from 12vectors/task/32-serve-bench-12vectors-com-from-a-worker

32 — Serve bench.12vectors.com from a Cloudflare Worker
This commit is contained in:
Ronald Ashri
2026-07-31 11:51:41 +02:00
committed by GitHub
11 changed files with 818 additions and 17 deletions
+96 -5
View File
@@ -18,13 +18,98 @@ python3 site/build.py # → site/dist/
```
`site/dist/` is gitignored — it is output, rebuilt on every deploy.
Deployment is task 32's; this directory only has to produce the files.
`site/` never reaches a host repo: releases ship exactly what
`../manager/core/release-manifest` lists, and it does not list this
directory. `tests/test_release_artifact.py` asserts that out loud rather
than leaving it to inference.
## Where the site lives
| | |
| --- | --- |
| Host | Cloudflare Workers, [static assets](https://developers.cloudflare.com/workers/static-assets/) — no script, no KV, no database |
| Account | the Cloudflare account holding the `12vectors.com` zone. `npx wrangler whoami` must list it before a deploy will work |
| 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 |
| Config | `site/wrangler.jsonc` (routing) and `site/root/_headers` (caching, security) |
Deploys are run by hand, by a person, exactly as releases are
(`../release.sh`). There is no deploy pipeline and no Cloudflare token in
repository secrets; adding a GitHub Action on merge to `main` is a
separate decision with a separate cost, and a follow-up card.
## Deploying
From a clean checkout, four commands. Re-running the whole sequence is
safe: the build empties and rewrites `dist/`, and `wrangler deploy`
replaces the Worker's assets rather than adding to them.
```bash
python3 -m pip install -r site/requirements.txt # once per machine
python3 site/fetch-fonts.py # once per checkout
python3 site/build.py # → site/dist/
npx wrangler@4 deploy --config site/wrangler.jsonc
```
`npx wrangler@4 login` first, once per machine, against an account that
can see the `12vectors.com` zone. Paths inside `wrangler.jsonc` are
relative to that file, so the command works from anywhere in the repo.
The first deploy is the one that takes the hostname over. It creates the
DNS record for `bench.12vectors.com` and routes it to the Worker;
anything else answering on that name stops answering. Every deploy after
it is an asset upload.
### Preview it locally
```bash
python3 site/build.py
npx wrangler@4 dev --config site/wrangler.jsonc # → http://localhost:8787
```
`dev` serves `dist/` through the same static-assets router as production,
so trailing-slash redirects and the 404 page behave as they will live.
The custom domain is ignored locally.
### After a deploy, check these four
The things this repository's tests cannot reach, because they are
answers rather than files:
1. `https://bench.12vectors.com/` serves the landing page over TLS.
2. `https://bench.12vectors.com/concepts/claiming-a-card` redirects to
the same path with a trailing slash, and no url anywhere ends in
`.html`.
3. A path that does not exist — `/nope/` — renders the site's own 404
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.
## How it is served
- **One url per page.** `html_handling: "force-trailing-slash"` redirects
`/concepts/claiming-a-card` to `/concepts/claiming-a-card/`, which is
what the pages link and what `<link rel=canonical>` names. Pages are
written as `<route>/index.html`, so no url ends in `.html`.
- **A real 404.** `not_found_handling: "404-page"` serves `dist/404.html`
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.
## What is where
| Path | What it is |
@@ -33,6 +118,8 @@ than leaving it to inference.
| `build.py` | The generator — slicing, drift detection, rendering, links |
| `templates/` | One `string.Template` per layout (`$name`, `$$` for a literal dollar) |
| `static/` | Copied to `dist/static/` verbatim: the stylesheet, the icon, the fonts |
| `root/` | Copied to the **top** of `dist/` verbatim: `_headers`, which the host reads and never serves |
| `wrangler.jsonc` | The Worker: assets directory, url handling, 404, custom domain |
| `requirements.txt` | `markdown-it-py`, pinned. The only dependency |
| `fetch-fonts.py` | Downloads the self-hosted woff2 files, once |
@@ -51,12 +138,15 @@ than leaving it to inference.
}
```
- **`path`** starts and ends with `/`; `/x/y/` is written to
`dist/x/y/index.html`.
- **`path`** starts with `/` and ends with `/`; `/x/y/` is written to
`dist/x/y/index.html`. A route that names an `.html` file instead is
written to exactly that path — `/404.html` is the only one, and it
exists because the host looks for that literal filename.
- **`layout`** names a file in `templates/`.
- **`section`** groups the page in the nav and the sidebar. The IA is
read out of this file in this file's order — nothing is derived from
the directory layout.
the directory layout. A `null` section keeps the page out of both,
which is how the 404 page stays off the nav.
- **`source`** is repo-relative, or `null` for a landing page whose body
is authored in its template rather than sliced.
- **`from`** is the heading the slice starts at. It is matched on the
@@ -78,7 +168,8 @@ Each of these exits non-zero with a message naming the route:
- a slice that comes out empty;
- a markdown link to a repo path that does not exist, or that escapes
the repo — a dead relative link must never reach the site;
- a template placeholder the builder does not supply.
- a template placeholder the builder does not supply;
- a file in `root/` that a route would also write.
Repo-relative links that *do* resolve are rewritten: to a site route if
`link_routes` maps the file to one, otherwise to the file on GitHub.
+109 -6
View File
@@ -28,9 +28,23 @@ the manifest, and a body that repeated it would say it twice.
Templates are `string.Template`, so placeholders are `$name` and a literal
dollar is `$$` — `str.format` was not an option with a stylesheet's worth
of braces in play.
## What the host needs from the build
Two things here exist for the way the site is served (site/wrangler.jsonc,
Cloudflare Workers static assets), and both are documented where they are
implemented below:
- `site/root/` is copied verbatim to the TOP of the output, because
`_headers` — the caching and security policy — is read by the host from
the root and nowhere else.
- the stylesheet and the icon are linked with a `?v=<hash>` of their own
contents (see `stamp`), which is what lets `_headers` cache them for a
year without a deploy ever going unseen.
"""
import argparse
import hashlib
import json
import os
import re
@@ -48,6 +62,16 @@ REPO = SITE.parent
# something else refuses rather than deleting a stranger's files.
MARKER = ".bench-site"
# Copied verbatim to the TOP of the build, unlike static/ which lands in
# a subdirectory of its own. These are files the host reads rather than
# pages it serves — `_headers` is the whole list — and they have to sit
# at the root because that is where Cloudflare looks for them.
ROOT = "root"
# The assets a template links directly, and the placeholder each one is
# offered under. See stamp() for why they carry a query string.
STAMPED = {"stylesheet": "static/site.css", "icon": "static/favicon.svg"}
ATX = re.compile(r"^(#{1,6})[ \t]+(.*?)[ \t]*#*[ \t]*$")
FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
CSS_URL = re.compile(r"""url\(\s*["']?([^"')]+)["']?\s*\)""")
@@ -301,7 +325,31 @@ def load_template(name: str, site: Path) -> Template:
return Template(path.read_text(encoding="utf-8"))
def render_page(page: dict, manifest: dict, *, site: Path, repo: Path) -> str:
def stamp(site: Path) -> dict:
"""`{"stylesheet": "/static/site.css?v=<hash>", …}` — the urls the
templates link the stylesheet and the icon by.
Nothing in static/ is renamed by the build: `site.css` stays
`site.css`, which is what anyone reading the tree (and the host's
own `_headers` globs) can rely on. So the fingerprint rides in the
query string instead. Caches key on the whole url, which is what
makes `immutable` in site/root/_headers safe: edit the stylesheet
and the deploy publishes it under a url nothing has ever cached,
while the year-long cache still holds for everyone else."""
urls = {}
for name, rel in STAMPED.items():
path = site / rel
if not path.is_file():
# Absent is missing_assets()' story to tell, not a crash here.
urls[name] = "/" + rel
continue
digest = hashlib.sha256(path.read_bytes()).hexdigest()[:10]
urls[name] = f"/{rel}?v={digest}"
return urls
def render_page(page: dict, manifest: dict, *, site: Path, repo: Path,
stamps: dict = None) -> str:
source = page.get("source")
if source:
body, contents = render_markdown(
@@ -314,7 +362,10 @@ def render_page(page: dict, manifest: dict, *, site: Path, repo: Path) -> str:
config = manifest["site"]
blob = config["blob_base"].rstrip("/") + "/"
stamps = stamps if stamps is not None else stamp(site)
fields = {
"stylesheet": stamps["stylesheet"],
"icon": stamps["icon"],
"title": escape(page["title"]),
"description": escape(page.get("description")
or config.get("description", "")),
@@ -371,9 +422,12 @@ def load_manifest(site: Path) -> dict:
raise BuildError(f'pages.json: an entry has no "{key}": '
f"{json.dumps(page)}")
route = page["path"]
if not route.startswith("/") or not route.endswith("/"):
raise BuildError(f'pages.json: route "{route}" must start and '
f'end with "/"')
if not route.startswith("/") or not (route.endswith("/")
or route.endswith(".html")):
raise BuildError(
f'pages.json: route "{route}" must start with "/" and '
f'either end with "/" (a directory index) or name an '
f'.html file (as /404.html does)')
if route in seen:
raise BuildError(f'pages.json: route "{route}" appears twice')
seen.add(route)
@@ -408,6 +462,17 @@ def clear(out: Path) -> None:
shutil.rmtree(out)
def target_for(out: Path, route: str) -> Path:
"""Where a route is written. `/x/y/` is a directory index, the shape
every page has; `/404.html` is that literal file, because Cloudflare's
not-found handling looks for a `404.html` and would never find a
`404/index.html`."""
if not route.endswith("/"):
return out / route.lstrip("/")
inner = route.strip("/")
return (out / inner / "index.html") if inner else (out / "index.html")
def copy_static(site: Path, out: Path) -> None:
static = site / "static"
if static.is_dir():
@@ -415,6 +480,29 @@ def copy_static(site: Path, out: Path) -> None:
ignore=shutil.ignore_patterns(".DS_Store"))
def root_files(site: Path) -> list:
"""Everything under site/root/, as (source, path relative to the
output root). The tree is copied verbatim to the top of the build:
these are files the *host* reads — `_headers` — rather than pages the
site serves, and Cloudflare only looks for them at the root."""
source = site / ROOT
if not source.is_dir():
return []
return [(path, path.relative_to(source))
for path in sorted(source.rglob("*"))
if path.is_file() and path.name != ".DS_Store"]
def copy_root(site: Path, out: Path) -> list:
written = []
for path, relative in root_files(site):
target = out / relative
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(path, target)
written.append(target)
return written
def missing_assets(out: Path) -> list:
"""Every same-origin url() a stylesheet asks for that is not in the
output. The fonts are self-hosted on purpose — the shipped site makes
@@ -437,8 +525,21 @@ def build(*, repo: Path = REPO, site: Path = None, out: Path = None,
site = site or (repo / "site")
out = out or (site / "dist")
manifest = load_manifest(site)
stamps = stamp(site)
pages = [(page, render_page(page, manifest, site=site, repo=repo))
# A file in root/ that a route also claims would be silently replaced
# by whichever is written last, so it is a build failure instead.
claimed = {str(target_for(Path(), page["path"])): page["path"]
for page in manifest["pages"]}
for _, relative in root_files(site):
route = claimed.get(str(relative))
if route:
raise BuildError(
f'site/{ROOT}/{relative} and the route "{route}" both write '
f"{relative}. Rename one — the build will not pick a winner.")
pages = [(page, render_page(page, manifest, site=site, repo=repo,
stamps=stamps))
for page in manifest["pages"]]
clear(out)
@@ -446,10 +547,12 @@ def build(*, repo: Path = REPO, site: Path = None, out: Path = None,
(out / MARKER).write_text(
"written by site/build.py; safe to delete\n", encoding="utf-8")
copy_static(site, out)
for target in copy_root(site, out):
log(f" {'(root)':<34} {target.relative_to(out)}")
written = []
for page, html in pages:
target = out / page["path"].strip("/") / "index.html"
target = target_for(out, page["path"])
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(html, encoding="utf-8")
written.append(target)
+8
View File
@@ -32,6 +32,14 @@
"source": "AGENTS.md",
"from": "## Claiming a card",
"to": "## Syncing boards"
},
{
"path": "/404.html",
"title": "Not found",
"layout": "notfound",
"section": null,
"description": "That path is not a page on this site.",
"source": null
}
]
}
+42
View File
@@ -0,0 +1,42 @@
# Response headers for bench.12vectors.com.
#
# Read by Cloudflare Workers static assets at deploy time — the file is
# consumed, never served — and copied here from site/root/ by
# 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.
# Everything, so that no page can ever forget one of these.
#
# nosniff a text/plain file must not become a script
# Referrer-Policy a full url is never sent to another origin
# HSTS one year, this host and anything below it. No
# `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
# '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
/*
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
# 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.
/static/*
Cache-Control: public, max-age=31536000, immutable
+13
View File
@@ -285,6 +285,19 @@ a:hover{color:var(--text);text-decoration:underline}
.door-dark .door-text{color:#a9c4c9}
.door .mono{font-size:var(--t-code)}
/* ── 404 (layout "notfound") ── */
.lost{
display:flex;flex-direction:column;align-items:flex-start;gap:18px;
padding:76px 44px 96px;max-width:60ch;
}
.lost-code{
font-size:11px;letter-spacing:.14em;color:var(--alarm);
}
.lost h1{
margin:0;font:600 var(--t-hero)/1.05 var(--display);
letter-spacing:-.025em;text-wrap:balance;
}
/* ── narrow ── */
@media (max-width:1080px){
.shell{grid-template-columns:220px minmax(0,1fr)}
+2 -2
View File
@@ -12,8 +12,8 @@
<title>$title · $site_title</title>
<meta name="description" content="$description">
<link rel="canonical" href="$canonical">
<link rel="icon" href="/static/favicon.svg">
<link rel="stylesheet" href="/static/site.css">
<link rel="icon" href="$icon">
<link rel="stylesheet" href="$stylesheet">
</head>
<body class="page-article">
+2 -2
View File
@@ -16,8 +16,8 @@
<title>$site_title · $site_tagline</title>
<meta name="description" content="$description">
<link rel="canonical" href="$canonical">
<link rel="icon" href="/static/favicon.svg">
<link rel="stylesheet" href="/static/site.css">
<link rel="icon" href="$icon">
<link rel="stylesheet" href="$stylesheet">
</head>
<body class="page-home">
+72
View File
@@ -0,0 +1,72 @@
<!doctype html>
<!-- Layout "notfound" — the page Cloudflare serves, with a 404 status,
for any path the build did not write (site/wrangler.jsonc:
not_found_handling "404-page"). It is the site's own design and the
site's own nav, so a wrong url is a wrong turn rather than a dead
end.
Two things it deliberately does not have: a <link rel=canonical>,
because a 404 is not a page anyone should canonicalise to, and a
contents gutter, because there is nothing to list.
Placeholders are string.Template's; a literal dollar in the markup
would have to be doubled. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>$title · $site_title</title>
<meta name="description" content="$description">
<meta name="robots" content="noindex">
<link rel="icon" href="$icon">
<link rel="stylesheet" href="$stylesheet">
</head>
<body class="page-notfound">
<div class="topbar">
<span class="topbar-org">12vectors</span>
<span class="topbar-sep">/</span>
<span class="topbar-repo">bench</span>
<span class="spacer"></span>
<span>$version</span>
</div>
<header class="masthead masthead-flat">
<a class="wordmark" href="/">
<span class="wordmark-name">$site_title</span>
<span class="wordmark-tag">$site_tagline</span>
</a>
<span class="spacer"></span>
<nav class="nav">
$nav
</nav>
<a class="button" href="$repo_url">GitHub ↗</a>
</header>
<section class="lost">
<span class="mono lost-code">404</span>
<h1>Nothing on this path.</h1>
<p class="lede">Every page here is generated from a heading in the
repository's own markdown, so a url that does not resolve is a url
that was never built — a stale link, or a typo.</p>
<div class="hero-actions">
<a class="button button-solid button-lg" href="/">Back to the landing page</a>
<a class="button button-lg" href="$issues_url">Report a broken link ↗</a>
</div>
</section>
<footer class="footer">
<pre class="footer-mark"> ___________________
|___________________|
|| ||
|| ||</pre>
<div class="footer-id">
<span class="footer-name">$site_title</span>
<span class="mono">a 12vectors product · built in the open</span>
</div>
<span class="spacer"></span>
<a class="mono footer-repo" href="$repo_url">github.com/12vectors/bench</a>
</footer>
</body>
</html>
+43
View File
@@ -0,0 +1,43 @@
// bench.12vectors.com — the built minisite, served as static assets.
//
// There is no `main`: this Worker has no script at all. site/dist/ is
// plain files and Cloudflare's static-assets router serves them, so the
// cheapest correct thing is to give it nothing to run. Anything that
// would need a fetch handler (an api, a redirect that depends on state)
// is a different card.
//
// npx wrangler@4 deploy --config site/wrangler.jsonc
//
// See site/README.md for the whole sequence, the account, and what the
// domain currently points at.
{
"name": "bench-site",
"compatibility_date": "2026-07-01",
"assets": {
// Relative to this file. site/build.py writes it; it is gitignored,
// so a deploy from a clean checkout builds first.
"directory": "./dist",
// /concepts/claiming-a-card -> 301 -> /concepts/claiming-a-card/,
// which is the url the pages link and the one <link rel=canonical>
// names. One page, one address: the slashless form redirects rather
// than serving a second copy, and no url ever ends in .html.
"html_handling": "force-trailing-slash",
// An unknown path gets dist/404.html with a 404 status — the site's
// own not-found page, in the site's own design. Not "single-page-
// application", which would answer 200 with the landing page and
// tell a crawler every typo is a real url.
"not_found_handling": "404-page"
},
// The hostname, taken over at the zone level: Cloudflare points
// bench.12vectors.com at this Worker and creates the DNS record. It
// touches nothing else on 12vectors.com.
"routes": [
{ "pattern": "bench.12vectors.com", "custom_domain": true }
],
"observability": { "enabled": true }
}
+17 -2
View File
@@ -8,6 +8,7 @@ and not one third-party request.
python3 -m unittest discover -s tests
"""
import importlib.util
import json
import re
import shutil
@@ -21,6 +22,20 @@ REPO = Path(__file__).resolve().parents[1]
SITE = REPO / "site"
BUILD = SITE / "build.py"
def builder():
"""site/build.py as a module, so a test asking "where does this route
land?" asks the builder rather than keeping its own copy of the rule.
Its top-level imports are stdlib only; the markdown parser is
imported inside the function that needs it."""
spec = importlib.util.spec_from_file_location("bench_site_build", BUILD)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
BUILDER = builder()
# The sources every page is cut from. A scratch repo needs these and
# nothing else to build the real manifest.
SOURCES = ["AGENTS.md", "README.md"]
@@ -109,11 +124,11 @@ class TheRealSiteBuilds(unittest.TestCase):
shutil.rmtree(cls.out, ignore_errors=True)
def page(self, route: str) -> str:
return (self.out / route.strip("/") / "index.html").read_text("utf-8")
return BUILDER.target_for(self.out, route).read_text("utf-8")
def test_one_page_per_manifest_entry(self):
for entry in self.manifest["pages"]:
target = self.out / entry["path"].strip("/") / "index.html"
target = BUILDER.target_for(self.out, entry["path"])
self.assertTrue(target.is_file(),
f'{entry["path"]} produced no page')
+414
View File
@@ -0,0 +1,414 @@
"""bench.12vectors.com is a Cloudflare Worker serving site/dist/ as
static assets. What can be tested here is everything the deploy depends
on *before* it reaches Cloudflare: that the config says what the site
needs it to say, that the build produces the files that config names,
and that the three of them — wrangler.jsonc, pages.json, README.md —
cannot drift apart about which domain this is.
What cannot be tested here is a live response. `not_found_handling` is
asserted as configuration plus the 404.html it points at; that a request
to a missing path comes back 404 is Cloudflare's half, and the deploy
checklist in site/README.md is where a person confirms it.
python3 -m unittest discover -s tests
"""
import json
import re
import shutil
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
from urllib.parse import urlparse
REPO = Path(__file__).resolve().parents[1]
SITE = REPO / "site"
WRANGLER = SITE / "wrangler.jsonc"
HEADERS = SITE / "root" / "_headers"
README = SITE / "README.md"
# Set on every response, whatever it is. The task's three, plus the two
# that come free with them.
BASELINE = ("X-Content-Type-Options", "Referrer-Policy",
"Strict-Transport-Security")
try:
import markdown_it # noqa: F401
HAS_MARKDOWN_IT = True
except ImportError: # pragma: no cover - environment
HAS_MARKDOWN_IT = False
# ── reading the two config formats by hand ────────────────────────────
COMMENT = re.compile(r'"(?:\\.|[^"\\])*"|//[^\n]*|/\*.*?\*/', re.DOTALL)
def read_jsonc(path: Path) -> dict:
"""wrangler.jsonc is JSON with comments, and comments are how that
file explains itself. Strings are matched first so a `//` inside one
survives."""
def keep(match):
text = match.group(0)
return text if text.startswith('"') else " "
return json.loads(COMMENT.sub(keep, path.read_text(encoding="utf-8")))
def read_headers(path: Path) -> list:
"""`_headers` as [(pattern, {header: value})], in file order — an
unindented line opens a rule, an indented one adds a header to it."""
rules, current = [], None
for line in path.read_text(encoding="utf-8").splitlines():
if not line.strip() or line.lstrip().startswith("#"):
continue
if not line.startswith((" ", "\t")):
current = (line.strip(), {})
rules.append(current)
elif current is not None:
name, _, value = line.strip().partition(":")
current[1][name.strip()] = value.strip()
return rules
def readme_text() -> str:
return README.read_text(encoding="utf-8")
def rule(pattern: str) -> dict:
for found, headers in read_headers(HEADERS):
if found == pattern:
return headers
raise AssertionError(f"_headers has no rule for {pattern}")
def run_build(repo: Path, out: Path) -> subprocess.CompletedProcess:
return subprocess.run(
[sys.executable, str(repo / "site" / "build.py"), "--out", str(out)],
capture_output=True, text=True, cwd=repo)
class Built(unittest.TestCase):
"""The real site, built once into a scratch directory."""
@classmethod
def setUpClass(cls):
if not HAS_MARKDOWN_IT:
raise unittest.SkipTest("markdown-it-py is not installed")
cls.out = Path(tempfile.mkdtemp(prefix="bench-deploy-")).resolve()
result = run_build(REPO, cls.out)
if result.returncode != 0: # not assert: must survive python -O
raise RuntimeError(
f"site/build.py failed:\n{result.stdout}{result.stderr}")
@classmethod
def tearDownClass(cls):
if hasattr(cls, "out"):
shutil.rmtree(cls.out, ignore_errors=True)
# ── the worker config ─────────────────────────────────────────────────
class TheWorkerServesTheBuild(unittest.TestCase):
"""site/wrangler.jsonc, read the way wrangler reads it."""
def setUp(self):
self.config = read_jsonc(WRANGLER)
self.assets = self.config.get("assets", {})
def test_the_assets_directory_is_what_the_builder_writes(self):
"""Paths in wrangler config are relative to the config file, so
this one has to resolve to site/dist and not to a sibling of the
repo root."""
directory = (WRANGLER.parent / self.assets["directory"]).resolve()
self.assertEqual(directory, (SITE / "dist").resolve())
def test_there_is_no_worker_script(self):
"""The site is files. A `main` would mean a fetch handler to
maintain, and nothing here needs one."""
self.assertNotIn("main", self.config)
def test_a_url_has_exactly_one_form(self):
"""force-trailing-slash: /x redirects to /x/, which is the url
the pages link and the one rel=canonical names. Anything else
leaves two urls serving one page."""
self.assertEqual("force-trailing-slash",
self.assets.get("html_handling"))
def test_an_unknown_path_gets_the_sites_own_404(self):
"""Not single-page-application, which answers 200 with the
landing page and tells a crawler every typo is a real url."""
self.assertEqual("404-page", self.assets.get("not_found_handling"))
def test_the_route_is_a_custom_domain(self):
routes = self.config.get("routes", [])
self.assertEqual(1, len(routes), "expected exactly one route")
self.assertTrue(routes[0].get("custom_domain"),
"the route is not a custom domain")
def test_the_worker_is_named(self):
self.assertTrue(self.config.get("name"))
def test_a_compatibility_date_is_pinned(self):
self.assertRegex(self.config.get("compatibility_date", ""),
r"^\d{4}-\d{2}-\d{2}$")
class TheDomainIsWrittenDownOnce(unittest.TestCase):
"""Three files name this site's address. They are allowed to say it
three times; they are not allowed to disagree."""
def setUp(self):
self.config = read_jsonc(WRANGLER)
self.manifest = json.loads(
(SITE / "pages.json").read_text(encoding="utf-8"))
def test_the_route_is_the_host_the_pages_canonicalise_to(self):
"""A rel=canonical pointing somewhere the Worker does not answer
is worse than none at all."""
canonical = urlparse(self.manifest["site"]["base_url"])
self.assertEqual("https", canonical.scheme)
self.assertEqual(canonical.netloc,
self.config["routes"][0]["pattern"])
def test_the_readme_names_the_worker_and_the_route(self):
"""Acceptance: the next person should not have to guess where
the site lives."""
readme = README.read_text(encoding="utf-8")
self.assertIn(self.config["name"], readme)
self.assertIn(self.config["routes"][0]["pattern"], readme)
def test_the_readme_names_the_deploy_command(self):
self.assertRegex(readme_text(), r"wrangler[^\n]*\bdeploy\b")
def test_the_readme_names_the_account(self):
self.assertRegex(readme_text(), r"(?i)\baccount\b")
# ── the 404 page ──────────────────────────────────────────────────────
class TheNotFoundPageIsAPage(Built):
"""`not_found_handling: "404-page"` is half of it. The other half is
that a 404.html exists, looks like the rest of the site, and offers a
way out."""
def setUp(self):
self.page = (self.out / "404.html").read_text("utf-8")
def test_it_is_written_where_the_host_looks(self):
"""A 404/index.html would never be found: the host wants a file
called 404.html at the root of the assets directory."""
self.assertTrue((self.out / "404.html").is_file())
self.assertFalse((self.out / "404" / "index.html").exists())
def test_it_wears_the_sites_design(self):
self.assertIn('rel="stylesheet" href="/static/site.css', self.page)
self.assertIn("404", self.page)
def test_it_offers_the_way_back(self):
self.assertIn('href="/"', self.page)
def test_it_claims_no_canonical_url(self):
"""A 404 is not a page to canonicalise to, and telling a crawler
to index it is worse still."""
self.assertNotIn('rel="canonical"', self.page)
self.assertIn('name="robots" content="noindex"', self.page)
def test_it_stays_out_of_the_nav_and_the_sidebar(self):
home = (self.out / "index.html").read_text("utf-8")
article = (self.out / "concepts" / "claiming-a-card"
/ "index.html").read_text("utf-8")
for html in (home, article):
self.assertNotIn("404.html", html)
# ── headers ───────────────────────────────────────────────────────────
class TheHeaderPolicyTravelsWithTheBuild(Built):
"""site/root/_headers is the policy; the build has to carry it to
the root of dist/ or the host never reads it."""
def test_it_reaches_the_root_of_the_build(self):
shipped = self.out / "_headers"
self.assertTrue(shipped.is_file())
self.assertEqual(HEADERS.read_text("utf-8"), shipped.read_text("utf-8"))
def test_it_is_not_also_served_as_a_page(self):
"""The host consumes _headers rather than serving it, but the
build must not have made a route out of it either."""
self.assertFalse((self.out / "_headers" / "index.html").exists())
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."""
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")
self.assertNotRegex(
html, r"""\sstyle\s*=\s*["']""",
f"{where} has an inline style the CSP would block")
class EveryResponseCarriesTheBaseline(unittest.TestCase):
def setUp(self):
self.everything = rule("/*")
def test_the_three_headers_a_public_page_owes(self):
for name in BASELINE:
self.assertIn(name, self.everything)
def test_hsts_is_a_year_and_does_not_preload(self):
value = self.everything["Strict-Transport-Security"]
self.assertIn("max-age=31536000", value)
self.assertNotIn("preload", value,
"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."""
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")
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/*"))
# ── fingerprinting ────────────────────────────────────────────────────
class Scratch(unittest.TestCase):
"""A copy of site/ plus the markdown it reads, so a test can edit the
stylesheet without touching the real one."""
def setUp(self):
if not HAS_MARKDOWN_IT:
raise unittest.SkipTest("markdown-it-py is not installed")
self.root = Path(tempfile.mkdtemp(prefix="bench-deploy-")).resolve()
self.addCleanup(shutil.rmtree, self.root, True)
shutil.copytree(SITE, self.root / "site",
ignore=shutil.ignore_patterns("dist", "__pycache__"))
for name in ("AGENTS.md", "README.md"):
shutil.copy(REPO / name, self.root / name)
self.out = self.root / "site" / "dist"
def build(self):
return run_build(self.root, self.out)
def home(self) -> str:
return (self.out / "index.html").read_text("utf-8")
class TheStylesheetUrlFollowsTheStylesheet(Scratch):
"""`immutable` for a year is only safe because the url changes when
the file does. That is the claim under test."""
STAMP = re.compile(r'href="(/static/site\.css\?v=([0-9a-f]{10}))"')
def test_the_pages_link_a_stamped_url(self):
self.assertEqual(0, self.build().returncode)
self.assertRegex(self.home(), self.STAMP.pattern)
def test_the_file_still_sits_at_its_plain_path(self):
"""Only the link carries the stamp — nothing in static/ is
renamed, so the /static/* glob in _headers still matches and the
tree stays readable."""
self.assertEqual(0, self.build().returncode)
self.assertTrue((self.out / "static" / "site.css").is_file())
def test_editing_the_stylesheet_changes_the_stamp(self):
self.assertEqual(0, self.build().returncode)
before = self.STAMP.search(self.home()).group(2)
css = self.root / "site" / "static" / "site.css"
css.write_text(css.read_text("utf-8") + "\n.lost{color:red}\n",
encoding="utf-8")
self.assertEqual(0, self.build().returncode)
after = self.STAMP.search(self.home()).group(2)
self.assertNotEqual(before, after,
"a changed stylesheet kept its url, so a "
"year-long cache would keep the old one")
def test_a_rebuild_that_changes_nothing_keeps_the_stamp(self):
"""The other half: a deploy that did not touch the stylesheet
must not invalidate everyone's cache."""
self.assertEqual(0, self.build().returncode)
before = self.STAMP.search(self.home()).group(2)
self.assertEqual(0, self.build().returncode)
self.assertEqual(before, self.STAMP.search(self.home()).group(2))
class TheRootTreeIsCopiedVerbatim(Scratch):
def test_a_root_file_lands_at_the_top_of_the_build(self):
(self.root / "site" / "root" / "robots.txt").write_text(
"User-agent: *\n", encoding="utf-8")
self.assertEqual(0, self.build().returncode)
self.assertEqual("User-agent: *\n",
(self.out / "robots.txt").read_text("utf-8"))
def test_a_root_file_a_route_also_claims_stops_the_build(self):
"""Both would be written, one would win, and which one is not
something a person should have to work out from a diff."""
(self.root / "site" / "root" / "404.html").write_text(
"mine", encoding="utf-8")
result = self.build()
self.assertNotEqual(0, result.returncode)
self.assertIn("404.html", result.stderr)
class TheDeployIsInTheRepository(unittest.TestCase):
"""The two facts about deployment that live outside a config file."""
def test_the_worker_config_and_the_headers_are_tracked(self):
tracked = subprocess.run(
["git", "check-ignore", "site/wrangler.jsonc", "site/root/_headers"],
capture_output=True, text=True, cwd=REPO)
self.assertNotEqual(tracked.returncode, 0,
"the deploy config is gitignored")
def test_the_release_artifact_still_does_not_ship_the_site(self):
"""A Worker config in site/ must not start travelling into host
projects with a release."""
manifest = (REPO / "manager" / "core" / "release-manifest"
).read_text("utf-8")
for line in manifest.splitlines():
if line.strip().startswith("#") or not line.strip():
continue
self.assertNotIn("site", line.split(None, 1)[1],
f"the release manifest names site/: {line}")
if __name__ == "__main__":
unittest.main()