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:
+96
-5
@@ -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
@@ -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)
|
||||
|
||||
@@ -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
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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
|
||||
@@ -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)}
|
||||
|
||||
@@ -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">
|
||||
|
||||
|
||||
@@ -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">
|
||||
|
||||
|
||||
@@ -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>
|
||||
@@ -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 }
|
||||
}
|
||||
@@ -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')
|
||||
|
||||
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user