From e449d0845bebd53c90f2d4d023323e6d76a036c9 Mon Sep 17 00:00:00 2001 From: Gene Kogan <1335251+genekogan@users.noreply.github.com> Date: Mon, 16 Nov 2026 02:36:20 -0500 Subject: [PATCH 1/3] feat(launcher): soul.game can sit behind a CDN, keyed on the visitor's own address (#2513) A site file (soul-game.caddy) replaces X-Forwarded-For with exactly {client_ip}; a trust snippet imported in the Caddyfile's global options trusts CF-Connecting-IP only from the CDN's published ranges. GET /__sim/whoami answers the address the launcher keyed a request on, and deploy/caddy/check-soul-game.mjs checks six points from outside. docs/operations/cdn.md carries the ordered hands-on steps and the rollback. Co-Authored-By: Claude Opus 5.5 --- changes/cdn-front-door.md | 4 + docs/operations/cdn.md | 83 +++++++++++ tools/world-launcher/check-soul-game.test.mjs | 141 ++++++++++++++++++ .../deploy/caddy/cdn-trust.snippet | 12 ++ .../deploy/caddy/check-soul-game.mjs | 109 ++++++++++++++ .../deploy/caddy/soul-game.caddy | 18 +++ tools/world-launcher/launcher.mjs | 10 +- 7 files changed, 376 insertions(+), 1 deletion(-) create mode 100644 changes/cdn-front-door.md create mode 100644 tools/world-launcher/check-soul-game.test.mjs create mode 100644 tools/world-launcher/deploy/caddy/cdn-trust.snippet create mode 100644 tools/world-launcher/deploy/caddy/check-soul-game.mjs create mode 100644 tools/world-launcher/deploy/caddy/soul-game.caddy diff --git a/changes/cdn-front-door.md b/changes/cdn-front-door.md new file mode 100644 index 000000000..af2b56245 --- /dev/null +++ b/changes/cdn-front-door.md @@ -0,0 +1,4 @@ +--- +type: internal +--- +soul.game can sit behind a CDN with every visitor still counted by their own address, and a check proves it from outside. diff --git a/docs/operations/cdn.md b/docs/operations/cdn.md index 3ef84345e..df4e1443e 100644 --- a/docs/operations/cdn.md +++ b/docs/operations/cdn.md @@ -184,3 +184,86 @@ The god folder may name either allowed site with `/w//` or `/worlds/w//v1/edge/act` get the launcher's JSON, not a challenge), `events` (the first event of +`/w//v1/edge/events` within 5 s) and `ranges` (the snippet's ranges equal the published lists). It prints each +problem and PASS or FAIL. Tests: `node --test tools/world-launcher/check-soul-game.test.mjs` (A1/A2 need `caddy` on +`PATH` or in `$CADDY`). + +### Hands-on steps, in this order + +The release never writes Caddy's configuration. Do these once, after a release that carries both files is live. + +1. **Install the site file and the snippet** on the production host, as root. The live `https://soul.game` block + must be in no other site file (Caddy refuses a site defined twice): if it is, first move every other handler it + has into `soul-game.caddy` in a reviewed change, then delete that block in the same step as the install. First + put the import inside the global options of `/etc/caddy/Caddyfile` by hand, so it reads: + + ```caddy + { + admin 127.0.0.1:2019 + import cdn-trust.snippet + } + import sites/*.caddy + ``` + + Then: + + ```bash + bash -s <<'INSTALL' + set -uo pipefail + SRC=/srv/sim-worlds/production/tools/world-launcher/deploy/caddy + PORT="$(sed -n 's/.*--port \([0-9][0-9]*\).*/\1/p' /etc/sim-worlds/production.conf)" + [[ "$PORT" =~ ^[0-9]+$ ]] || { echo "no --port in production.conf: stopping, nothing changed"; exit 1; } + [ -f "$SRC/soul-game.caddy" ] && [ -f "$SRC/cdn-trust.snippet" ] || { echo "the live release has no soul-game.caddy: ship it first"; exit 1; } + grep -lE '^https://soul\.game[ ,{]' /etc/caddy/sites/*.caddy | grep -v '/soul-game\.caddy$' && { echo "soul.game is still defined above: move it first"; exit 1; } + grep -qE '^\s*import cdn-trust\.snippet' /etc/caddy/Caddyfile || { echo "the Caddyfile's global options do not import cdn-trust.snippet: stopping, nothing changed"; exit 1; } + for f in /etc/caddy/sites/soul-game.caddy /etc/caddy/cdn-trust.snippet; do [ -e "$f" ] && cp -a "$f" "$f.bak.$(date +%s)"; done + sed "s/@@PRODUCTION_PORT@@/$PORT/g" "$SRC/soul-game.caddy" > /etc/caddy/sites/soul-game.caddy + cp "$SRC/cdn-trust.snippet" /etc/caddy/cdn-trust.snippet + caddy validate --config /etc/caddy/Caddyfile || { echo "caddy validate failed: restore the .bak files; Caddy was NOT reloaded"; exit 1; } + systemctl reload caddy && echo "installed; Caddy reloaded" + INSTALL + ``` + + Before the record is proxied, the check fails only `address` (no trace page yet); `forged` must already pass. +2. **Turn off bot challenges and script rewriting** in the CDN zone: no Bot Fight Mode, managed challenge, Browser + Integrity Check or challenge rule on `/v1/*`, `/w/*/v1/*`, `/__sim/*` or the page, and no Rocket Loader, Email + Obfuscation, minification or injected scripts on any path. Agents' command-line clients, the release's health + checks, the walk and eyes runners and the off-box watcher are not browsers, and the page depends on its inline + script order. +3. **Keep the sign-in records unproxied** (DNS only): Clerk's records for the domain must answer from Clerk. +4. **TLS mode Full (strict)**: the CDN connects to the origin over HTTPS and checks Caddy's certificate. +5. **Switch the `soul.game` record to proxied, together with E2's cache rules** (never one without the other). +6. **Soak**: run `check-soul-game.mjs` from outside until it prints PASS, then keep it and the release's health checks + running through a busy period. The CDN restarts sockets without notice, so viewer bars are measured at the origin. +7. **Last, restrict the firewall** so ports 80 and 443 accept only the ranges in `cdn-trust.snippet`. Leave SSH as it + is. + +The deploy and backup workflows reach the host by `SIM_DEPLOY_HOST`: it must stay a name that is not proxied (or +the address), since the CDN carries only HTTP(S). + +**Rollback** is the DNS switch: set the `soul.game` record back to DNS only (if step 7 is done, first reopen 80 and +443 to everyone). The site file and snippet can stay: for a peer outside the CDN ranges `{client_ip}` is the peer +itself, which is what the launcher saw before. diff --git a/tools/world-launcher/check-soul-game.test.mjs b/tools/world-launcher/check-soul-game.test.mjs new file mode 100644 index 000000000..f8bee277d --- /dev/null +++ b/tools/world-launcher/check-soul-game.test.mjs @@ -0,0 +1,141 @@ +// soul.game behind the CDN (#2513). A1/A2: the real site file and trust snippet in a real Caddy in front of a real +// launcher (needs a `caddy` binary on PATH or in $CADDY; skipped, and so unproved, without one). A3: check-soul-game.mjs +// against a loopback stand-in of the whole stack, which passes, and fails for its own reason on each of the six points +// when that point is broken. No network beyond loopback. +import { test, after } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawn, spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { createServer } from 'node:http'; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { openLauncher } from './launcher.mjs'; +import { checkSoulGame, staticRanges, FORGED, POINTS } from './deploy/caddy/check-soul-game.mjs'; +import { testPort } from '../../apps/server/test/test-port.ts'; + +const CADDY_DIR = new URL('./deploy/caddy/', import.meta.url).pathname; +const SITE = readFileSync(join(CADDY_DIR, 'soul-game.caddy'), 'utf8'), TRUST = readFileSync(join(CADDY_DIR, 'cdn-trust.snippet'), 'utf8'); +const CADDY = process.env.CADDY ?? 'caddy'; +const hasCaddy = spawnSync(CADDY, ['version'], { encoding: 'utf8' }).status === 0; +const dir = mkdtempSync(join(tmpdir(), 'soul-game-caddy-')); +after(() => rmSync(dir, { recursive: true, force: true })); +// Caddy keeps its storage under HOME / XDG_DATA_HOME: point both into the test's own directory +const caddyEnv = { ...process.env, HOME: dir, XDG_DATA_HOME: join(dir, 'xdg-data'), XDG_CONFIG_HOME: join(dir, 'xdg-config') }; + +/** The production layout: the Caddyfile's global options import the snippet, then every site file. */ +function layout(name, { site, trust, global = 'admin off' }) { + const d = join(dir, name); mkdirSync(join(d, 'sites'), { recursive: true }); + writeFileSync(join(d, 'cdn-trust.snippet'), trust); + writeFileSync(join(d, 'sites', 'soul-game.caddy'), site); + writeFileSync(join(d, 'Caddyfile'), `{\n\t${global}\n\timport cdn-trust.snippet\n}\nimport sites/*.caddy\n`); + return join(d, 'Caddyfile'); +} + +test('A1: the site file and the trust snippet pass caddy validate in the production layout', { skip: !hasCaddy && 'no caddy binary (set $CADDY)' }, () => { + assert.ok(staticRanges(TRUST).length >= 20, 'the snippet lists the published ranges'); + assert.match(SITE, /^https:\/\/soul\.game \{$/m); + const file = layout('validate', { site: SITE.replaceAll('@@PRODUCTION_PORT@@', '4600'), trust: TRUST, global: 'admin 127.0.0.1:2019' }); + const r = spawnSync(CADDY, ['validate', '--config', file, '--adapter', 'caddyfile'], { encoding: 'utf8', env: caddyEnv }); + assert.equal(r.status, 0, r.stderr); + assert.match(r.stderr + r.stdout, /Valid configuration/); + // and every range arrives: Caddy silently drops ranges written in a { } block, which validates as trusting nobody + const json = JSON.parse(spawnSync(CADDY, ['adapt', '--config', file, '--adapter', 'caddyfile'], { encoding: 'utf8', env: caddyEnv }).stdout); + for (const srv of Object.values(json.apps.http.servers)) { + assert.deepEqual(srv.trusted_proxies?.ranges, staticRanges(TRUST)); + assert.deepEqual(srv.client_ip_headers, ['CF-Connecting-IP']); + } +}); + +test('A2: through Caddy, a trusted peer is keyed to CF-Connecting-IP whatever X-Forwarded-For says; anyone else to the peer', { skip: !hasCaddy && 'no caddy binary (set $CADDY)' }, async () => { + const base = await testPort(3), lp = base, cp = base + 1; + for (const d of ['web', 'templates']) mkdirSync(join(dir, d), { recursive: true }); + writeFileSync(join(dir, 'web', 'index.html'), 'Souls'); + const L = await openLauncher({ port: lp, range: [base + 2, base + 2], dataDir: join(dir, 'data'), webDir: join(dir, 'web'), templatesDir: join(dir, 'templates'), publicOrigin: 'http://soul.test', eager: 0, prewarm: false, log: () => {} }); + // the site file as it is, on loopback: plain http on a test port, listening on 127.0.0.1 and ::1; the snippet with one + // more trusted range, 127.0.0.1 (the stand-in CDN peer), so ::1 is an untrusted peer reaching the origin directly + const site = SITE.replaceAll('@@PRODUCTION_PORT@@', String(lp)).replace(/^https:\/\/soul\.game \{$/m, `http://:${cp} {\n\tbind 127.0.0.1 [::1]`); + const trust = TRUST.replace('trusted_proxies static ', 'trusted_proxies static 127.0.0.1/32 '); + const caddy = spawn(CADDY, ['run', '--config', layout('run', { site, trust }), '--adapter', 'caddyfile'], { env: caddyEnv, stdio: ['ignore', 'ignore', 'pipe'] }); + let err = ''; caddy.stderr.on('data', (d) => { err += d; }); + try { + const who = async (host, headers = {}) => (await (await fetch(`http://${host}:${cp}/__sim/whoami`, { headers })).json()).address; + for (let i = 0; ; i++) { try { await who('127.0.0.1'); break; } catch (e) { if (i > 100 || caddy.exitCode !== null) throw Error(`caddy did not start: ${err.slice(-2000)}`); await new Promise((r) => setTimeout(r, 100)); } } + const VISITOR = '198.51.100.23', FORGED_CF = '192.0.2.99'; + assert.equal(await who('127.0.0.1', { 'cf-connecting-ip': VISITOR, 'x-forwarded-for': `${FORGED}, 10.1.2.3` }), VISITOR, 'trusted peer: the CDN header wins over a forged X-Forwarded-For'); + assert.equal(await who('127.0.0.1', { 'cf-connecting-ip': '2001:db8::7', 'x-forwarded-for': FORGED }), '2001:db8::7', 'an IPv6 visitor'); + assert.equal(await who('127.0.0.1', { 'x-forwarded-for': FORGED }), '127.0.0.1', 'trusted peer without the CDN header: the peer, never empty, never forged'); + assert.equal(await who('127.0.0.1', { 'cf-connecting-ip': 'not-an-address', 'x-forwarded-for': FORGED }), '127.0.0.1', 'an invalid CDN header: the peer'); + assert.equal(await who('[::1]', { 'cf-connecting-ip': FORGED_CF, 'x-forwarded-for': FORGED }), '::1', 'untrusted peer: both headers ignored, the peer'); + // the launcher keys one entry: the header Caddy sends has exactly one + const r = await checkSoulGame({ origin: `http://127.0.0.1:${cp}`, points: ['forged'] }); + assert.equal(r.pass, true, r.problems.join('\n')); + } finally { caddy.kill(); await L.close(); } +}); + +// --- A3: the check against a stand-in stack -------------------------------------------------------------------------- +const VISITOR = '198.51.100.5'; +/** A minimal WebSocket server side: the RFC 6455 handshake and one unmasked text frame. */ +function wsAccept(req, socket, message) { + const key = createHash('sha1').update(req.headers['sec-websocket-key'] + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11').digest('base64'); + socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${key}\r\n\r\n`); + if (message) { const b = Buffer.from(message); socket.write(Buffer.concat([Buffer.from([0x81, b.length]), b])); } + socket.on('error', () => {}); socket.on('data', () => {}); +} +/** The CDN, Caddy and the launcher in one: answers what each point asks; `broken` breaks one. */ +function stack(broken = null) { + const ranges = staticRanges(TRUST), v4 = ranges.filter((x) => !x.includes(':')), v6 = ranges.filter((x) => x.includes(':')); + const s = createServer((req, res) => { + const path = req.url.split('?')[0], j = (st, b, h = {}) => res.writeHead(st, { 'content-type': 'application/json', ...h }).end(JSON.stringify(b)); + if (path === '/cdn-cgi/trace') return res.end(`fl=1\nh=soul.game\nip=${VISITOR}\nts=1\n`); + if (path === '/__sim/whoami') { + const xff = String(req.headers['x-forwarded-for'] ?? '').split(',')[0].trim(); + return j(200, { address: broken === 'address' ? '162.158.1.1' : broken === 'forged' && xff ? xff : VISITOR }); // 'address': keyed on the CDN + } + if (path === '/__sim/healthz') return broken === 'agent' ? res.writeHead(403, { 'content-type': 'text/html', 'cf-mitigated': 'challenge' }).end('Just a moment...') : j(200, { ok: true }); + if (path === '/w/eden/v1/edge/act' && req.method === 'POST') return j(401, { ok: false, code: 'auth.required' }); + if (path === '/w/eden/v1/edge/events') { + if (req.headers.authorization !== 'Bearer sim_check') return j(401, { ok: false }); + res.writeHead(200, { 'content-type': 'text/event-stream' }); res.write(': open\n\n'); + // 'events': buffered on the way, so the first event comes late + const t = setTimeout(() => res.write('event: hello\ndata: {}\n\n'), broken === 'events' ? 2000 : 10); req.on('close', () => clearTimeout(t)); return; + } + if (path === '/ips-v4') return res.end(`${v4.join('\n')}\n${broken === 'ranges' ? '203.0.113.0/24\n' : ''}`); + if (path === '/ips-v6') return res.end(`${v6.join('\n')}\n`); + res.writeHead(404).end(); + }); + const sockets = new Set(); + s.on('upgrade', (req, socket) => { + sockets.add(socket); + if (!req.url.startsWith('/w/eden/ws?hello=')) return socket.end('HTTP/1.1 404 Not Found\r\n\r\n'); + wsAccept(req, socket, broken === 'viewer' ? '{"t":"error","code":"proto"}' : '{"t":"welcome","proto":1}'); + }); + return new Promise((yes) => s.listen(0, '127.0.0.1', () => { const o = `http://127.0.0.1:${s.address().port}`; yes({ origin: o, published: [`${o}/ips-v4`, `${o}/ips-v6`], close: () => { for (const k of sockets) k.destroy(); s.closeAllConnections(); s.close(); } }); })); +} +const checkStack = async (broken) => { const st = await stack(broken); try { return await checkSoulGame({ origin: st.origin, published: st.published, token: 'sim_check', eventMs: 500, waitMs: 1500 }); } finally { st.close(); } }; + +test('A3: the check passes against a stack that keeps all six points', async (t) => { + const r = await checkStack(); + t.diagnostic(`check-soul-game output:\n${r.seen.map((x) => ` ${x}`).join('\n')}\n${r.pass ? 'PASS' : 'FAIL'}`); + assert.equal(r.pass, true, r.problems.join('\n')); + assert.equal(r.seen.length, 7, r.seen.join('\n')); +}); + +test('A3: each of the six points, broken alone, fails the check for its own reason', async () => { + const want = { + address: /^address: the launcher keyed 162\.158\.1\.1, the CDN saw 198\.51\.100\.5$/, + forged: /^forged: the launcher keyed the forged X-Forwarded-For 203\.0\.113\.77$/, + viewer: /^viewer: no welcome in 1500 ms$/, + agent: /^agent: GET \/__sim\/healthz: challenged \(cf-mitigated: challenge\)/, + events: /^events: no first event in 500 ms/, + ranges: /^ranges: trusted but no longer published|^ranges: published but not trusted: 203\.0\.113\.0\/24$/, + }; + for (const p of POINTS) { + const r = await checkStack(p); + assert.equal(r.pass, false, `${p} broken still passes`); + assert.equal(r.problems.length, 1, `${p}: ${r.problems.join(' | ')}`); + assert.match(r.problems[0], want[p]); + } + // no token: the event stream cannot be timed, which is a failure, not a pass + const st = await stack(); try { const r = await checkSoulGame({ origin: st.origin, published: st.published, points: ['events'] }); assert.match(r.problems.join(), /^events: no Soul token/); } finally { st.close(); } +}); diff --git a/tools/world-launcher/deploy/caddy/cdn-trust.snippet b/tools/world-launcher/deploy/caddy/cdn-trust.snippet new file mode 100644 index 000000000..8ef84408b --- /dev/null +++ b/tools/world-launcher/deploy/caddy/cdn-trust.snippet @@ -0,0 +1,12 @@ +# Lane E1 (#2513): which peers may name the visitor. Imported INSIDE the global options block of /etc/caddy/Caddyfile +# (a site file cannot hold global options), so it applies to every site on this host, and only to requests whose TCP +# peer is in these ranges: Cloudflare's published list (https://www.cloudflare.com/ips-v4 and /ips-v6). Static, because +# the dynamic `cloudflare` range module needs a custom Caddy build. For such a peer {client_ip} is the CF-Connecting-IP +# value (Cloudflare overwrites whatever a visitor sent in it); for any other peer, or a missing or invalid header, it is +# the peer itself. soul-game.caddy forwards exactly {client_ip} as X-Forwarded-For. check-soul-game.mjs (point 6) diffs +# these ranges against the published list. They stay on ONE line: Caddy reads the static source's ranges as arguments +# only, and silently drops ranges written inside a { } block (it adapts to a trusted_proxies with no ranges at all). +servers { + trusted_proxies static 173.245.48.0/20 103.21.244.0/22 103.22.200.0/22 103.31.4.0/22 141.101.64.0/18 108.162.192.0/18 190.93.240.0/20 188.114.96.0/20 197.234.240.0/22 198.41.128.0/17 162.158.0.0/15 104.16.0.0/13 104.24.0.0/14 172.64.0.0/13 131.0.72.0/22 2400:cb00::/32 2606:4700::/32 2803:f800::/32 2405:b500::/32 2405:8100::/32 2a06:98c0::/29 2c0f:f248::/32 + client_ip_headers CF-Connecting-IP +} diff --git a/tools/world-launcher/deploy/caddy/check-soul-game.mjs b/tools/world-launcher/deploy/caddy/check-soul-game.mjs new file mode 100644 index 000000000..829835814 --- /dev/null +++ b/tools/world-launcher/deploy/caddy/check-soul-game.mjs @@ -0,0 +1,109 @@ +#!/usr/bin/env node +// Checks soul.game behind the CDN from outside (#2513; the site file is soul-game.caddy beside this script, the trusted +// ranges cdn-trust.snippet): +// SOUL_CHECK_TOKEN= node tools/world-launcher/deploy/caddy/check-soul-game.mjs \ +// [--origin https://soul.game] [--world eden] [--trace /cdn-cgi/trace] +// Six points, each PASS or a PROBLEM naming it: +// address /__sim/whoami (the address the launcher keyed this request on) equals the ip= line of the CDN's trace page +// forged the same with a forged X-Forwarded-For: the same answer, never the forged value +// viewer a viewer WebSocket (/w//ws?hello=...) receives its welcome +// agent a request with no browser headers to /__sim/healthz, and a POST to /w//v1/edge/act, are answered by +// the launcher (JSON, no CDN challenge) +// events the first event of /w//v1/edge/events arrives within --event-ms (the token is read from the +// environment only, so it stays out of shell history and process lists) +// ranges the static ranges in cdn-trust.snippet equal the CDN's published lists +// Read-only: GETs, one WebSocket join, and one POST without a token that the launcher refuses before any world reads it. +// Exit 0 on PASS. +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + +export const POINTS = ['address', 'forged', 'viewer', 'agent', 'events', 'ranges']; +export const PUBLISHED = ['https://www.cloudflare.com/ips-v4', 'https://www.cloudflare.com/ips-v6']; +export const FORGED = '203.0.113.77'; // a documentation address (RFC 5737): no visitor has it +const SNIPPET = fileURLToPath(new URL('./cdn-trust.snippet', import.meta.url)); +const UA = 'souls-check-soul-game'; + +/** The ranges on the snippet's `trusted_proxies static ` line (Caddy takes them as arguments of one line). */ +export function staticRanges(text) { + const m = /^\s*trusted_proxies\s+static\s+([^\n#]+)/m.exec(text); + return m ? m[1].trim().split(/\s+/) : []; +} + +/** A CDN challenge or block page instead of the launcher's answer. */ +const challenged = (r) => r.headers.get('cf-mitigated') ? `challenged (cf-mitigated: ${r.headers.get('cf-mitigated')})` : null; +const isJson = (r) => /application\/json/.test(r.headers.get('content-type') ?? ''); + +export async function checkSoulGame({ origin = 'https://soul.game', world = 'eden', trace, token, snippet = SNIPPET, published = PUBLISHED, points = POINTS, eventMs = 5000, waitMs = 10_000, fetchImpl = fetch, WebSocketImpl = globalThis.WebSocket } = {}) { + const problems = [], seen = []; + const bad = (point, message) => problems.push(`${point}: ${message}`); + const get = (url, init = {}) => fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(waitMs), ...init, headers: { 'user-agent': UA, ...(init.headers ?? {}) } }); + const whoami = async (headers) => { const r = await get(`${origin}/__sim/whoami`, { headers }); const why = challenged(r); if (why) throw Error(why); if (r.status !== 200 || !isJson(r)) throw Error(`/__sim/whoami answered ${r.status} ${r.headers.get('content-type') ?? ''}`); return (await r.json()).address ?? null; }; + let keyed; + const run = { address: async () => { + const r = await get(trace ?? `${origin}/cdn-cgi/trace`), body = await r.text(), ip = /^ip=(.+)$/m.exec(body)?.[1]?.trim(); + if (!ip) return bad('address', `the CDN's trace page has no ip= line (${r.status}): is the name proxied?`); + keyed = await whoami(); + seen.push(`address: the CDN saw ${ip}, the launcher keyed ${keyed}`); + if (keyed !== ip) bad('address', `the launcher keyed ${keyed ?? 'no address'}, the CDN saw ${ip}`); + }, forged: async () => { + keyed ??= await whoami(); + const a = await whoami({ 'x-forwarded-for': FORGED }); + seen.push(`forged: with X-Forwarded-For ${FORGED} the launcher keyed ${a}`); + if (a === FORGED) bad('forged', `the launcher keyed the forged X-Forwarded-For ${FORGED}`); + else if (a !== keyed) bad('forged', `the launcher keyed ${a ?? 'no address'} with a forged X-Forwarded-For, ${keyed} without`); + }, viewer: async () => { + if (typeof WebSocketImpl !== 'function') return bad('viewer', 'no WebSocket in this Node'); + const url = `${origin.replace(/^http/, 'ws')}/w/${world}/ws?hello=${encodeURIComponent(JSON.stringify({ t: 'hello', proto: 1 }))}`, t0 = performance.now(); + const got = await new Promise((yes) => { + const ws = new WebSocketImpl(url), done = (v) => { clearTimeout(timer); try { ws.close(); } catch { /* closed */ } yes(v); }; + const timer = setTimeout(() => done(`no welcome in ${waitMs} ms`), waitMs); + ws.onmessage = (e) => { if (typeof e.data !== 'string') return; try { if (JSON.parse(e.data).t === 'welcome') done(null); } catch { /* not JSON */ } }; + ws.onerror = () => done('the socket failed to open (refused, challenged or not upgraded)'); + ws.onclose = (e) => done(`closed before the welcome (${e.code})`); + }); + seen.push(`viewer: ${got ?? `welcome in ${Math.round(performance.now() - t0)} ms`}`); + if (got) bad('viewer', got); + }, agent: async () => { + const h = await get(`${origin}/__sim/healthz`), hb = isJson(h) ? await h.json() : (await h.text(), null); + seen.push(`agent: GET /__sim/healthz -> ${h.status} ${h.headers.get('content-type') ?? ''}`); + const why = challenged(h); + if (why || h.status !== 200 || hb?.ok !== true) bad('agent', `GET /__sim/healthz: ${why ?? `${h.status}${hb ? '' : ' not JSON'}`}, want 200 {ok:true}`); + const p = await get(`${origin}/w/${world}/v1/edge/act`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' }); + const pb = isJson(p) ? await p.json() : (await p.text(), null), pwhy = challenged(p); + seen.push(`agent: POST /w/${world}/v1/edge/act -> ${p.status} ${pb?.code ?? p.headers.get('content-type') ?? ''}`); + if (pwhy || !pb) bad('agent', `POST /w/${world}/v1/edge/act: ${pwhy ?? `${p.status} not JSON`}, want the launcher's own JSON answer`); + }, events: async () => { + if (!token) return bad('events', 'no Soul token: set SOUL_CHECK_TOKEN to a scratch Soul\'s token'); + const ac = new AbortController(), t0 = performance.now(), timer = setTimeout(() => ac.abort(), eventMs); + try { + const r = await fetchImpl(`${origin}/w/${world}/v1/edge/events`, { headers: { 'user-agent': UA, accept: 'text/event-stream', authorization: `Bearer ${token}` }, signal: ac.signal }); + if (r.status !== 200 || !/text\/event-stream/.test(r.headers.get('content-type') ?? '')) { await r.body?.cancel(); return bad('events', `${challenged(r) ?? r.status} ${r.headers.get('content-type') ?? ''}, want 200 text/event-stream`); } + const dec = new TextDecoder(); let buf = ''; + for await (const chunk of r.body) { + buf += dec.decode(chunk, { stream: true }); + // the first event: an event: or data: line (a ": " line is a comment, a heartbeat) + if (/^(event|data):/m.test(buf)) { const ms = Math.round(performance.now() - t0); seen.push(`events: first event in ${ms} ms`); return; } + } + bad('events', 'the stream ended before its first event'); + } catch (e) { bad('events', ac.signal.aborted ? `no first event in ${eventMs} ms (buffered on the way?)` : e.message); } + finally { clearTimeout(timer); ac.abort(); } + }, ranges: async () => { + const mine = new Set(staticRanges(readFileSync(snippet, 'utf8'))), theirs = new Set(); + for (const u of published) { const r = await get(u); if (!r.ok) return bad('ranges', `${u}: ${r.status}`); for (const l of (await r.text()).split('\n')) if (l.trim()) theirs.add(l.trim()); } + const missing = [...theirs].filter((x) => !mine.has(x)), extra = [...mine].filter((x) => !theirs.has(x)); + seen.push(`ranges: ${mine.size} in the snippet, ${theirs.size} published`); + if (missing.length) bad('ranges', `published but not trusted: ${missing.join(' ')}`); + if (extra.length) bad('ranges', `trusted but no longer published: ${extra.join(' ')}`); + } }; + for (const p of points) { try { await run[p](); } catch (e) { bad(p, e.message); } } + return { pass: problems.length === 0, problems, seen }; +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + const a = process.argv.slice(2), opt = (k, d) => { const i = a.indexOf(k); return i >= 0 ? a[i + 1] : d; }; + const r = await checkSoulGame({ origin: opt('--origin', 'https://soul.game').replace(/\/$/, ''), world: opt('--world', 'eden'), trace: opt('--trace'), token: process.env.SOUL_CHECK_TOKEN, eventMs: Number(opt('--event-ms', 5000)) }); + for (const s of r.seen) console.log(` ${s}`); + for (const p of r.problems) console.log(` PROBLEM ${p}`); + console.log(r.pass ? 'PASS' : 'FAIL'); + process.exitCode = r.pass ? 0 : 1; +} diff --git a/tools/world-launcher/deploy/caddy/soul-game.caddy b/tools/world-launcher/deploy/caddy/soul-game.caddy new file mode 100644 index 000000000..f489f1350 --- /dev/null +++ b/tools/world-launcher/deploy/caddy/soul-game.caddy @@ -0,0 +1,18 @@ +# soul.game on the PRODUCTION host, behind the CDN (lane E1, #2513). Installed as /etc/caddy/sites/soul-game.caddy, +# with cdn-trust.snippet imported in the Caddyfile's global options. docs/operations/cdn.md, "The site behind the CDN", +# has the ordered steps and the rollback. The release never writes Caddy's configuration. +# +# @@PRODUCTION_PORT@@ is a placeholder, never a real value in this repository: the production launcher's loopback port, +# the --port of SIM_WORLDS_ARGS in /etc/sim-worlds/production.conf. The install substitutes it. +# +# The launcher and the worlds key every per-address limit on the FIRST X-Forwarded-For entry. For a trusted peer Caddy +# would append to the X-Forwarded-For it received, and the CDN appends to whatever the visitor sent, so the first entry +# would be the visitor's own text. Here the header is replaced, never appended: exactly one entry, {client_ip}, which is +# the CF-Connecting-IP of a peer in cdn-trust.snippet's ranges and the TCP peer for anyone else. It is never empty (an +# empty X-Forwarded-For from loopback would look like the operator's own direct request to the launcher). +# GET /__sim/whoami answers the address the launcher keyed a request on; check-soul-game.mjs compares it from outside. +https://soul.game { + reverse_proxy localhost:@@PRODUCTION_PORT@@ { + header_up X-Forwarded-For {client_ip} + } +} diff --git a/tools/world-launcher/launcher.mjs b/tools/world-launcher/launcher.mjs index bfe39b9cc..56f95f027 100644 --- a/tools/world-launcher/launcher.mjs +++ b/tools/world-launcher/launcher.mjs @@ -18,6 +18,7 @@ // POST /__sim/worlds {name, template} → creates, waits for /healthz → {slug, url} // GET /__sim/worlds/ one world + what the launcher has seen (looks, agent, previews) // GET /__sim/launcher children, ports, pids, restarts (diagnostics; direct local requests only) +// GET /__sim/whoami {address}: the address this request is keyed on (first X-Forwarded-For entry, else the peer) // GET /__sim/healthz {ok, build, worlds, running, caps, memAvailableMb} (also /healthz); clientErrorsNew = error kinds // pages first reported since this build went live (client-errors.mjs) // GET /__sim/glitches loopback: every world's recoveries and halts by rule and rung; ?world=[&limit=N] adds its records @@ -105,7 +106,7 @@ import { healthDash } from './health-dash.mjs'; import { readGlitches } from './glitches.mjs'; import { usageRollup } from './usage.mjs'; import { ownerOverview } from './owner-overview.mjs'; -import { connect } from 'node:net'; +import { connect, isIP } from 'node:net'; import { createReadStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'; import { brotliCompressSync, brotliDecompressSync, gunzipSync, gzipSync, constants as zlibConstants } from 'node:zlib'; import { dirname, extname, join, normalize, resolve, sep } from 'node:path'; @@ -1461,6 +1462,13 @@ export async function openLauncher(cfg = {}) { json(res, 200, { ok: true, worlds }); return; } if (path === '/__sim/usage' && req.method === 'GET') { json(res, ...(direct(req) ? usage.report(url.searchParams.get('days') ?? undefined, registry.worlds.filter((w) => w.test === true).map((w) => w.slug)) : [404, { ok: false, code: 'not-found' }])); return; } // #1942, loopback only + // #2513: the address this request is keyed on: the first X-Forwarded-For entry behind the proxy (as the flood guard + // and the ceilings take it), else the TCP peer. Public, since it is the caller's own address; never a header + // verbatim: anything that is not an address answers null. deploy/caddy/check-soul-game.mjs compares it from outside. + if (path === '/__sim/whoami' && (req.method === 'GET' || req.method === 'HEAD')) { + const xff = behindProxy ? String(req.headers['x-forwarded-for'] ?? '').split(',')[0].trim() : '', a = xff || (req.socket.remoteAddress ?? ''); + json(res, 200, { address: isIP(a) ? a : null }); return; + } if ((path === '/__sim/healthz' || path === '/healthz') && (req.method === 'GET' || req.method === 'HEAD')) { const running = registry.worlds.filter((w) => pool.status(w.slug).status === 'running').length; const host = hostHealth(dataDir); // deploy/host-health.mjs (timer): `hostOk` (+ short `hostCodes` when not ok) public, the numbers loopback-only From 3b984bbb4794a38439073d95c86ce784af8decd8 Mon Sep 17 00:00:00 2001 From: Gene Kogan <1335251+genekogan@users.noreply.github.com> Date: Mon, 16 Nov 2026 02:38:20 -0500 Subject: [PATCH 2/3] test(launcher): a documentation address for the stand-in CDN peer (#2513) Co-Authored-By: Claude Opus 5.5 --- tools/world-launcher/check-soul-game.test.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/world-launcher/check-soul-game.test.mjs b/tools/world-launcher/check-soul-game.test.mjs index f8bee277d..1027deb0f 100644 --- a/tools/world-launcher/check-soul-game.test.mjs +++ b/tools/world-launcher/check-soul-game.test.mjs @@ -90,7 +90,7 @@ function stack(broken = null) { if (path === '/cdn-cgi/trace') return res.end(`fl=1\nh=soul.game\nip=${VISITOR}\nts=1\n`); if (path === '/__sim/whoami') { const xff = String(req.headers['x-forwarded-for'] ?? '').split(',')[0].trim(); - return j(200, { address: broken === 'address' ? '162.158.1.1' : broken === 'forged' && xff ? xff : VISITOR }); // 'address': keyed on the CDN + return j(200, { address: broken === 'address' ? '192.0.2.10' : broken === 'forged' && xff ? xff : VISITOR }); // 'address': keyed on the CDN's own address } if (path === '/__sim/healthz') return broken === 'agent' ? res.writeHead(403, { 'content-type': 'text/html', 'cf-mitigated': 'challenge' }).end('Just a moment...') : j(200, { ok: true }); if (path === '/w/eden/v1/edge/act' && req.method === 'POST') return j(401, { ok: false, code: 'auth.required' }); @@ -123,7 +123,7 @@ test('A3: the check passes against a stack that keeps all six points', async (t) test('A3: each of the six points, broken alone, fails the check for its own reason', async () => { const want = { - address: /^address: the launcher keyed 162\.158\.1\.1, the CDN saw 198\.51\.100\.5$/, + address: /^address: the launcher keyed 192\.0\.2\.10, the CDN saw 198\.51\.100\.5$/, forged: /^forged: the launcher keyed the forged X-Forwarded-For 203\.0\.113\.77$/, viewer: /^viewer: no welcome in 1500 ms$/, agent: /^agent: GET \/__sim\/healthz: challenged \(cf-mitigated: challenge\)/, From e29b008f4c470a52485537989d3e772bdfffb0c9 Mon Sep 17 00:00:00 2001 From: Gene Kogan <1335251+genekogan@users.noreply.github.com> Date: Mon, 16 Nov 2026 02:49:16 -0500 Subject: [PATCH 3/3] feat(cdn): one cache rule for soul.game that the release's own CDN check accepts, with a check that proves the hit (#2514) The rule's paths are derived from origin-cache.mjs's hashed and stable classes plus the keyed snapshot; cdn.md carries the expression verbatim (tested), check-soul-game.mjs gains a cache point (each class twice, the second a hit; a stale snapshot key no-store), and the runbook says when to purge. Co-Authored-By: Claude Opus 5.5 --- docs/operations/cdn.md | 44 ++++++++-- docs/operations/runbook.md | 9 ++ tools/cdn/origin-cache.mjs | 31 +++++++ tools/cdn/origin-cache.test.mjs | 87 ++++++++++++++++++- .../deploy/caddy/check-soul-game.mjs | 30 ++++++- 5 files changed, 191 insertions(+), 10 deletions(-) diff --git a/docs/operations/cdn.md b/docs/operations/cdn.md index df4e1443e..2cad9727b 100644 --- a/docs/operations/cdn.md +++ b/docs/operations/cdn.md @@ -207,9 +207,41 @@ the launcher keyed that request on (an entry that is not an address answers `nul the `ip=` line of `/cdn-cgi/trace` on the same name), `forged` (the same with a forged `X-Forwarded-For`), `viewer` (a viewer WebSocket gets its welcome), `agent` (a request with no browser headers to `/__sim/healthz` and a token-less `POST /w//v1/edge/act` get the launcher's JSON, not a challenge), `events` (the first event of -`/w//v1/edge/events` within 5 s) and `ranges` (the snippet's ranges equal the published lists). It prints each -problem and PASS or FAIL. Tests: `node --test tools/world-launcher/check-soul-game.test.mjs` (A1/A2 need `caddy` on -`PATH` or in `$CADDY`). +`/w//v1/edge/events` within 5 s), `ranges` (the snippet's ranges equal the published lists) and `cache` (the +cache rule below: the world page's script bundle, its first snapshot part, a release-stable file, `--stable`, default +`/mars-assets/draco/draco_decoder.wasm`, and the snapshot under the page's own key, each requested twice with the +second a `HIT`; the snapshot under a stale key is `no-store` and never a hit). It prints each problem and PASS or FAIL; +`--points cache` runs one point. Edge caches are per site, so a hit here says nothing about other locations. Tests: +`node --test tools/world-launcher/check-soul-game.test.mjs` (A1/A2 need `caddy` on `PATH` or in `$CADDY`) and +`node --test tools/cdn/origin-cache.test.mjs` (the rule, and the `cache` point through a stand-in CDN). + +### The cache rule + +A CDN caches by file extension by default and never JSON or extension-less paths, so the content-addressed parts, +profile photos and the snapshot would read `DYNAMIC`, and the release's `cdn-walk` fails any hashed or release-stable +response that does (`tools/cdn/origin-cache.mjs`). One cache rule in the `soul.game` zone fixes that. Its paths are +`CDN_CACHE_RULE` in `origin-cache.mjs`, derived from the same classes the release checks plus the keyed snapshot; the +test checks that this page carries `cdnRuleExpression()` exactly: + +``` +http.host eq "soul.game" and ((http.request.uri.path strict wildcard "/w/*/v1/world/part/*" or http.request.uri.path strict wildcard "/w/*/v1/souls/*/profile-photo/*" or http.request.uri.path strict wildcard "/w/*/v1/world/snapshot") or ((http.request.uri.path strict wildcard "/assets/*" or http.request.uri.path strict wildcard "/w/*/assets/*" or http.request.uri.path strict wildcard "/w/*/art/*" or http.request.uri.path strict wildcard "/modular/*" or http.request.uri.path strict wildcard "/mars-assets/*" or http.request.uri.path strict wildcard "/world-assets/*" or http.request.uri.path strict wildcard "*.wasm" or http.request.uri.path strict wildcard "*.woff" or http.request.uri.path strict wildcard "*.woff2" or http.request.uri.path strict wildcard "*.ttf" or http.request.uri.path strict wildcard "*.otf") and not http.request.uri.path contains "/v1/" and not http.request.uri.path contains "/__sim/")) +``` + +| Setting | Value | +|---|---| +| Cache eligibility | Eligible for cache | +| Edge TTL | Use cache-control header if present, bypass cache if not | +| Browser TTL | Respect origin TTL | +| Cache key | The default (the query string is part of it: the snapshot's `v=` key is) | + +The rule only makes these paths eligible; the origin's `Cache-Control` decides. Bundles, stored objects, parts, art and +photos are `immutable` for a year, release-stable files keep an hour or more, and the snapshot is +`public, max-age=0, s-maxage=86400` only when `?v=` is the world's current key (`apps/server/src/edge-snapshot.ts`), +`no-store` otherwise, so a stale or invented key never enters the cache. A `no-store`, `private` or header-less answer +on an eligible path is never kept. No path that can answer per user is eligible: the static patterns never match under +`/v1/` or `/__sim/`, and the three API reads are public by design (moderation-filtered, no auth read). The page, +`/v1/config` and the world list stay outside it. Add no rule that bypasses everything else: other paths keep the CDN's +default, which also respects the origin's headers. ### Hands-on steps, in this order @@ -247,7 +279,8 @@ The release never writes Caddy's configuration. Do these once, after a release t INSTALL ``` - Before the record is proxied, the check fails only `address` (no trace page yet); `forged` must already pass. + Before the record is proxied, the check fails only `address` (no trace page yet) and `cache` (no cache status); + `forged` must already pass. 2. **Turn off bot challenges and script rewriting** in the CDN zone: no Bot Fight Mode, managed challenge, Browser Integrity Check or challenge rule on `/v1/*`, `/w/*/v1/*`, `/__sim/*` or the page, and no Rocket Loader, Email Obfuscation, minification or injected scripts on any path. Agents' command-line clients, the release's health @@ -255,7 +288,8 @@ The release never writes Caddy's configuration. Do these once, after a release t script order. 3. **Keep the sign-in records unproxied** (DNS only): Clerk's records for the domain must answer from Clerk. 4. **TLS mode Full (strict)**: the CDN connects to the origin over HTTPS and checks Caddy's certificate. -5. **Switch the `soul.game` record to proxied, together with E2's cache rules** (never one without the other). +5. **Switch the `soul.game` record to proxied, together with [the cache rule](#the-cache-rule)** (never one without + the other: without the rule the next release's `cdn-walk` fails). 6. **Soak**: run `check-soul-game.mjs` from outside until it prints PASS, then keep it and the release's health checks running through a busy period. The CDN restarts sockets without notice, so viewer bars are measured at the origin. 7. **Last, restrict the firewall** so ports 80 and 443 accept only the ranges in `cdn-trust.snippet`. Leave SSH as it diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md index 018e332b6..10a746104 100644 --- a/docs/operations/runbook.md +++ b/docs/operations/runbook.md @@ -106,6 +106,15 @@ To put a world's data back live: stop the stage, move the world's `sim.db` aside `chown simworlds:simworlds`, start the stage. Restoring data discards events accepted since the snapshot, so do it only for real data loss. Tests: `node --test tools/world-launcher/backup-restic.test.mjs` (skips without restic). +**CDN purges** (behind the CDN, [cache rule](cdn.md#the-cache-rule)): parts, uploads and art are immutable for a year at +the edge, and the origin's later refusal never reaches copies already there. Purge by prefix `soul.game/w//` where +the plan has it, otherwise purge everything: + +- **When moderation vetoes a file**, purge its URLs (`/w//assets/.`, `/w//art/.`) and + that world's parts and snapshot. +- **After a restore** of a world's data, purge that world: its snapshot key can repeat a key the edge already holds for + other contents. + Release backups (`ship.sh` step `backup`) are separate: row-verified compact copies in `/srv/sim-worlds-data/release-backups/pre-r node tools/world-launcher/deploy/caddy/check-soul-game.mjs \ -// [--origin https://soul.game] [--world eden] [--trace /cdn-cgi/trace] -// Six points, each PASS or a PROBLEM naming it: +// [--origin https://soul.game] [--world eden] [--trace /cdn-cgi/trace] [--stable ] [--points a,b] +// Seven points (the CLI runs all; checkSoulGame's default is the first six), each PASS or a PROBLEM naming it: // address /__sim/whoami (the address the launcher keyed this request on) equals the ip= line of the CDN's trace page // forged the same with a forged X-Forwarded-For: the same answer, never the forged value // viewer a viewer WebSocket (/w//ws?hello=...) receives its welcome @@ -12,6 +12,9 @@ // events the first event of /w//v1/edge/events arrives within --event-ms (the token is read from the // environment only, so it stays out of shell history and process lists) // ranges the static ranges in cdn-trust.snippet equal the CDN's published lists +// cache the cache rule (docs/operations/cdn.md): the world page's script bundle, its first snapshot part, a +// release-stable file (--stable) and the snapshot under the page's own key, each requested twice, the +// second a CDN hit; the snapshot under a stale key is no-store and never a hit // Read-only: GETs, one WebSocket join, and one POST without a token that the launcher refuses before any world reads it. // Exit 0 on PASS. import { readFileSync } from 'node:fs'; @@ -22,6 +25,7 @@ export const PUBLISHED = ['https://www.cloudflare.com/ips-v4', 'https://www.clou export const FORGED = '203.0.113.77'; // a documentation address (RFC 5737): no visitor has it const SNIPPET = fileURLToPath(new URL('./cdn-trust.snippet', import.meta.url)); const UA = 'souls-check-soul-game'; +const STABLE = '/mars-assets/draco/draco_decoder.wasm'; // every world page loads it (LiveWorld's Draco decoder) /** The ranges on the snippet's `trusted_proxies static ` line (Caddy takes them as arguments of one line). */ export function staticRanges(text) { @@ -33,7 +37,7 @@ export function staticRanges(text) { const challenged = (r) => r.headers.get('cf-mitigated') ? `challenged (cf-mitigated: ${r.headers.get('cf-mitigated')})` : null; const isJson = (r) => /application\/json/.test(r.headers.get('content-type') ?? ''); -export async function checkSoulGame({ origin = 'https://soul.game', world = 'eden', trace, token, snippet = SNIPPET, published = PUBLISHED, points = POINTS, eventMs = 5000, waitMs = 10_000, fetchImpl = fetch, WebSocketImpl = globalThis.WebSocket } = {}) { +export async function checkSoulGame({ origin = 'https://soul.game', world = 'eden', trace, token, snippet = SNIPPET, published = PUBLISHED, points = POINTS, stable = STABLE, eventMs = 5000, waitMs = 10_000, fetchImpl = fetch, WebSocketImpl = globalThis.WebSocket } = {}) { const problems = [], seen = []; const bad = (point, message) => problems.push(`${point}: ${message}`); const get = (url, init = {}) => fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(waitMs), ...init, headers: { 'user-agent': UA, ...(init.headers ?? {}) } }); @@ -94,6 +98,24 @@ export async function checkSoulGame({ origin = 'https://soul.game', world = 'ede seen.push(`ranges: ${mine.size} in the snippet, ${theirs.size} published`); if (missing.length) bad('ranges', `published but not trusted: ${missing.join(' ')}`); if (extra.length) bad('ranges', `trusted but no longer published: ${extra.join(' ')}`); + }, cache: async () => { + // what a first visit fetches, each twice: the second must be an edge hit (one edge site: the hit rate elsewhere is + // not shown here). Then the snapshot with a key that is not current: never kept. + const page = await get(`${origin}/w/${world}/`, { headers: { accept: 'text/html' } }), html = await page.text(); + if (page.status !== 200) return bad('cache', `the world page answered ${page.status}`); + const key = /__simSnapshotKey=("[0-9.]+")/.exec(html)?.[1], part = /__simSnapshotParts=\["([0-9a-f]{32})"/.exec(html)?.[1]; + const snapshot = `/w/${world}/v1/world/snapshot?defs=ref&cols=1&v=`; + const targets = { bundle: /]+src="((?:\/w\/[^/"]+)?\/assets\/[^"?#]+\.js)"/.exec(html)?.[1], part: part && `/w/${world}/v1/world/part/${part}`, stable, snapshot: key && snapshot + encodeURIComponent(JSON.parse(key)) }; + const twice = async (path) => { const st = []; for (let i = 0; i < 2; i++) { const r = await get(origin + path); await r.arrayBuffer(); st.push({ status: r.status, cf: r.headers.get('cf-cache-status') ?? 'none', cc: r.headers.get('cache-control') ?? '' }); } return st; }; + for (const [what, path] of Object.entries(targets)) { + if (!path) { bad('cache', `the world page names no ${what}`); continue; } + const [a, b] = await twice(path); + seen.push(`cache: ${what} ${path}: ${a.status} ${a.cf}, then ${b.status} ${b.cf}`); + if (b.status !== 200 || b.cf.toUpperCase() !== 'HIT') bad('cache', `${what} ${path}: the second request was ${b.status} ${b.cf}, want 200 HIT`); + } + const [a, b] = await twice(snapshot + '0'); + seen.push(`cache: stale snapshot key: ${b.status} ${b.cf} ${b.cc}`); + if (![a, b].every((x) => /no-store/i.test(x.cc)) || b.cf.toUpperCase() === 'HIT') bad('cache', `the snapshot with a stale key answered ${b.cf} (${b.cc || 'no cache-control'}), want no-store and never a hit`); } }; for (const p of points) { try { await run[p](); } catch (e) { bad(p, e.message); } } return { pass: problems.length === 0, problems, seen }; @@ -101,7 +123,7 @@ export async function checkSoulGame({ origin = 'https://soul.game', world = 'ede if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { const a = process.argv.slice(2), opt = (k, d) => { const i = a.indexOf(k); return i >= 0 ? a[i + 1] : d; }; - const r = await checkSoulGame({ origin: opt('--origin', 'https://soul.game').replace(/\/$/, ''), world: opt('--world', 'eden'), trace: opt('--trace'), token: process.env.SOUL_CHECK_TOKEN, eventMs: Number(opt('--event-ms', 5000)) }); + const r = await checkSoulGame({ origin: opt('--origin', 'https://soul.game').replace(/\/$/, ''), world: opt('--world', 'eden'), trace: opt('--trace'), token: process.env.SOUL_CHECK_TOKEN, eventMs: Number(opt('--event-ms', 5000)), stable: opt('--stable', STABLE), points: opt('--points')?.split(',') ?? [...POINTS, 'cache'] }); for (const s of r.seen) console.log(` ${s}`); for (const p of r.problems) console.log(` PROBLEM ${p}`); console.log(r.pass ? 'PASS' : 'FAIL');