Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

32.7 KB
Raw Blame
// three.ws production server — Cloud Run replacement for the Vercel runtime.
// -------------------------------------------------------------------------
// Serves the ENTIRE platform from one Express process:
//
//  1. The 1,000+ route table from vercel.json (`routes`) — security headers,
//     clean-URL rewrites (/3d → /3d.html), redirects, /cdn/* → API rewrites,
//     and the 404 fallback — interpreted with Vercel's legacy-routes
//     semantics (phase-1 rules → filesystem → post-filesystem rules).
//  2. The static frontend from dist/ (Vite build output).
//  3. Every serverless handler under api/** with Vercel filesystem-routing
//     semantics, so handlers run unmodified:
//        /api/foo          → api/foo.js        (or api/foo/index.js)
//        /api/agents/abc   → api/agents/[id].js  (params merged into req.query)
//        /api/v1/x/a/b/c   → api/v1/x/[...slug].js (slug = "a/b/c")
//     Precedence per segment: exact file > exact dir > [param].js > [param]/
//     > [...catchall].js. Names starting with `_` or `.` are never routable.
//
// Request/response parity notes:
//  - req.url is the original path + query, EXCEPT behind a dest rewrite that
//    carries query captures ("/oracle/coin/x" → "/api/oracle-share?mint=$1"):
//    there req.url becomes the rewritten path + merged query, as on Vercel,
//    because handlers parse their params from req.url.
//  - req.query merges URL search params (repeated keys → array), then
//    dest-rewrite query params, then route params — later wins, as on Vercel.
//  - req.body is pre-parsed for JSON / urlencoded / text / octet-stream at
//    an 8 MB limit (Cloud Run's ceiling is 32 MB); multipart and other types
//    stay unconsumed so upload handlers can read the raw stream.
//  - SSE and other live streams work: compression skips text/event-stream and
//    any response marked `x-accel-buffering: no`, and the HTTP server's
//    idle timeouts are lifted (Cloud Run enforces the real deadline).
//
// Run locally:  node server/index.mjs   (PORT defaults to 8080)

import express from 'express';
import compression from 'compression';
import { shouldCompress } from './compression-filter.mjs';
import { statSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { pathToFileURL, fileURLToPath } from 'node:url';
import { isSsrRoute, renderSsrPage } from './ssr-pages.mjs';
import { hasSeoRoute, renderSeoHead, CANONICAL_ORIGIN } from './seo-head.mjs';
import { createCreationHeadRenderer, creationIdFromPath, loadPublicCreation } from './creation-head.mjs';
import { renderCrawlerBody } from './crawler-body.mjs';
import { isMissingShellPage } from './shell-pages.mjs';
import { hardenHeaderBag, hardenOnEnd } from './csp-hashes.mjs';
import { cronEdgeAuth } from './cron-edge-auth.mjs';
import { setBounded, touchBounded } from './bounded-cache.mjs';
import { runWithRequestContext } from '../api/_lib/request-context.js';
// Route resolution lives in its own module so the audit scripts
// (scripts/audit-cron-liveness.mjs) exercise the SAME resolver production runs,
// instead of a copy that can silently drift from it.
import {
	loadRouteTable,
	substitute,
	isExternalDest,
	hasMatches,
	isRoutable,
	resolveApi,
} from './route-resolve.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(__dirname, '..');
const API_ROOT = path.join(ROOT, 'api');
const DIST_ROOT = path.join(ROOT, 'dist');
// Per-creation head for /m/:id, reading the creation straight from the
// database with the same visibility rules as GET /api/forge-creation.
const renderCreationHead = createCreationHeadRenderer({ loadCreation: loadPublicCreation, origin: CANONICAL_ORIGIN });
const PORT = Number(process.env.PORT) || 8080;
// 8 MB fits the 6 M-char base64 token image build-metadata's schema accepts
// (base64 inflates raw bytes by 4/3, so the old Vercel-era 4.5 MB limit
// rejected images the schema allowed). Cloud Run's own ceiling is 32 MB.
const BODY_LIMIT = '8mb';

// ---------------------------------------------------------------------------
// vercel.json route table, split at the {handle: "filesystem"} marker.
// ---------------------------------------------------------------------------

const { config: vercelConfig, phase1Routes, postFsRoutes } = loadRouteTable(
	path.join(ROOT, 'vercel.json'),
);

// ---------------------------------------------------------------------------
// External-URL dests (reverse proxy), e.g. /ingest/* → PostHog.
// ---------------------------------------------------------------------------
// Vercel proxies any route whose dest is an absolute URL. This middleware
// replicates that, and MUST run before the body parsers so POST bodies stream
// through unconsumed. It walks the same phase-1 rules with the same first-match
// semantics: only when the first non-continue dest for a path is external does
// it proxy; otherwise it falls through untouched.

// Hop-by-hop headers (RFC 9110 §7.6.1) plus fields the proxied hop recomputes,
// plus `authorization` — this app's bearer/session credential must never leak to
// an external analytics upstream (PostHog). Node lowercases header keys.
const PROXY_SKIP_REQ = new Set([
	'host', 'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
	'te', 'trailer', 'transfer-encoding', 'upgrade', 'content-length', 'accept-encoding',
	'authorization',
]);
const PROXY_SKIP_RES = new Set([
	'connection', 'keep-alive', 'transfer-encoding', 'content-encoding', 'content-length',
]);

async function proxyExternal(req, res, dest) {
	const headers = {};
	for (const [k, v] of Object.entries(req.headers)) {
		if (!PROXY_SKIP_REQ.has(k)) headers[k] = v;
	}
	// Forward only PostHog's own cookies to the analytics upstream; the app's
	// session (`__Host-sid`) and CSRF cookies must never reach an external host.
	const safeCookie = (req.headers.cookie || '')
		.split(';').map((c) => c.trim()).filter(Boolean)
		.filter((c) => c.startsWith('ph_') || /^__ph/i.test(c))
		.join('; ');
	if (safeCookie) headers.cookie = safeCookie;
	else delete headers.cookie;
	const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
	try {
		const upstream = await fetch(dest, {
			method: req.method,
			headers,
			body: hasBody ? req : undefined,
			duplex: hasBody ? 'half' : undefined,
			redirect: 'manual',
			signal: AbortSignal.timeout(30_000),
		});
		res.status(upstream.status);
		for (const [k, v] of upstream.headers) {
			if (!PROXY_SKIP_RES.has(k)) res.setHeader(k, v);
		}
		if (upstream.body) {
			const { Readable } = await import('node:stream');
			const { pipeline } = await import('node:stream/promises');
			// `.pipe()` does not propagate source errors — an upstream reset
			// mid-body would emit an unhandled 'error' and crash the instance.
			// `pipeline` forwards errors and tears both sides down cleanly.
			await pipeline(Readable.fromWeb(upstream.body), res);
		} else {
			res.end();
		}
	} catch (err) {
		// Client aborts and mid-stream upstream resets land here once the body
		// has begun streaming; the status/headers are already sent, so just end
		// the response. Only a pre-stream failure can still emit a 502.
		if (!res.headersSent) {
			console.error(`[proxy] ${req.method} ${req.url} → ${new URL(dest).host} failed:`, err.message);
			res.status(502).json({ error: 'bad_gateway', message: 'Upstream request failed.' });
		} else if (!res.writableEnded) {
			res.end();
		}
	}
}

// ---------------------------------------------------------------------------
// API route resolution (Vercel filesystem semantics) with caches.
// ---------------------------------------------------------------------------

/** @type {Map<string, {file: string, params: Record<string, string>} | null>} */
const routeCache = new Map();
// Keyed by request path, misses included, so it is capped (LRU) rather than
// letting unique junk paths grow it for the life of the instance.
const ROUTE_CACHE_MAX = 5000;
/** @type {Map<string, Promise<any>>} */
const moduleCache = new Map();

async function dispatchApi(req, res, pathname, extraQuery) {
	// Route-table dests may target the file directly ("/api/x402/service.js").
	const apiPath = pathname.endsWith('.js') ? pathname.slice(0, -3) : pathname;
	let segments;
	try {
		segments = apiPath.slice(5).split('/').filter(Boolean).map(decodeURIComponent);
	} catch {
		res.status(400).json({ error: 'bad_request', message: 'Malformed URL encoding.' });
		return true;
	}
	// Reject empty, non-routable ("_"/"."-prefixed), and traversal segments.
	// decodeURIComponent runs per-segment, so a legit segment can never hold a
	// raw "/" or "\" — an embedded separator means an encoded "%2f"/"%5c" was
	// used to smuggle a compound path past the split. Rejecting it here (and the
	// containment check below) stops "%2f..%2f..%2fvite.config" from escaping
	// API_ROOT to import() an arbitrary server-side .js.
	if (
		segments.length === 0 ||
		segments.some(
			(s) => !isRoutable(s) || s === '..' || s.includes('/') || s.includes('\\'),
		)
	)
		return false;

	const cacheKey = segments.join('/');
	let route = touchBounded(routeCache, cacheKey);
	if (route === undefined) {
		route = resolveApi(API_ROOT, segments, {});
		// Defense in depth: never route to a file that resolved outside API_ROOT.
		if (route && !route.file.startsWith(API_ROOT + path.sep)) route = null;
		setBounded(routeCache, cacheKey, route, ROUTE_CACHE_MAX);
	}
	if (!route) return false;

	// req.query: search params (repeated keys → array), then dest-rewrite
	// query, then route params — later wins, matching Vercel. Express 5
	// defines `query` as a prototype getter, so shadow it.
	const url = new URL(req.url, 'http://internal');
	const query = {};
	for (const key of new Set(url.searchParams.keys())) {
		const all = url.searchParams.getAll(key);
		query[key] = all.length > 1 ? all : all[0];
	}
	Object.assign(query, extraQuery, route.params);
	Object.defineProperty(req, 'query', { value: query, writable: true, configurable: true });

	try {
		let mod = moduleCache.get(route.file);
		if (!mod) {
			mod = import(pathToFileURL(route.file).href);
			moduleCache.set(route.file, mod);
		}
		const handler = (await mod).default;
		if (typeof handler !== 'function') {
			console.error(`[api] ${route.file} has no default-export handler`);
			res.status(500).json({ error: 'internal_error', message: 'Handler misconfigured.' });
			return true;
		}
		// A handler that renders HTML or SVG gets the same inline-script CSP
		// hardening a static page gets (server/csp-hashes.mjs).
		hardenOnEnd(res);
		// Every helper under the handler can read the caller's address from the
		// request context (api/_lib/request-context.js): a key's IP allowlist is
		// enforced inside authenticateBearer, whatever route called it.
		await runWithRequestContext({ req }, () => handler(req, res));
	} catch (err) {
		console.error(`[api] ${req.method} ${pathname} failed:`, err);
		if (!res.headersSent) {
			res.status(500).json({
				error: 'internal_error',
				message: 'The request failed unexpectedly.',
			});
		} else if (!res.writableEnded) {
			res.end();
		}
	}
	return true;
}

// ---------------------------------------------------------------------------
// Static file serving from dist/ (the filesystem phase).
// ---------------------------------------------------------------------------

function resolveStatic(pathname) {
	let rel;
	try {
		rel = decodeURIComponent(pathname);
	} catch {
		return null;
	}
	const abs = path.normalize(path.join(DIST_ROOT, rel));
	if (!abs.startsWith(DIST_ROOT + path.sep) && abs !== DIST_ROOT) return null; // traversal guard
	let target = abs;
	try {
		let st = statSync(target);
		if (st.isDirectory()) {
			target = path.join(target, 'index.html');
			st = statSync(target);
		}
		return st.isFile() ? target : null;
	} catch {
		return null;
	}
}

// Static HTML gets its CSP tightened to the inline scripts it actually
// contains (see server/csp-hashes.mjs). In production dist/ is immutable for
// the lifetime of a deploy, so each file is read and hashed at most once; the
// response itself still streams from res.sendFile.
//
// The cache is keyed by the file's size and mtime rather than its path alone,
// because "immutable" is only true of the container. Run this server against a
// working tree and a rebuild rewrites dist/ underneath it: sendFile then
// streams the new bytes while the header still carries the old file's hashes,
// and every inline script on that page is blocked. That is a page-blanking
// failure produced entirely by a stale cache, and one statSync per HTML
// response is a cheap way to never see it again.
const staticCspCache = new Map();

function cspForStaticHtml(file) {
	let stamp = '';
	try {
		const st = statSync(file);
		stamp = `${st.size}:${st.mtimeMs}`;
	} catch {
		// Unreadable stat: fall through to a read, which reports its own failure.
	}
	const hit = staticCspCache.get(file);
	if (hit && hit.stamp === stamp) return hit.html;
	let html = null;
	try {
		html = readFileSync(file, 'utf8');
	} catch (err) {
		console.error(`[csp] could not read ${file} for hashing:`, err.message);
	}
	staticCspCache.set(file, { stamp, html });
	return html;
}

function serveFile(req, res, file, headers, status) {
	if (file.endsWith('.html')) {
		const html = cspForStaticHtml(file);
		if (html !== null) hardenHeaderBag(headers, html);
	}
	res.set(headers);
	if (status) res.status(status);
	// The mime table maps .cjs to application/node, and with nosniff a browser
	// refuses to execute that from a <script> tag, so the documented UMD embed
	// (/agent-3d/<v>/agent-3d.umd.cjs) silently never ran. send() keeps a
	// content-type that is already set.
	if (file.endsWith('.cjs')) res.type('text/javascript');
	// Android Digital Asset Links (and the other RFC 8615 discovery files) are
	// re-fetched by Google and by devices on a schedule; a day-long edge TTL
	// means a rotated release key stays unverified for up to 24 hours after a
	// deploy. Google's own guidance caps the TTL at an hour.
	if (file.includes(`${path.sep}.well-known${path.sep}`) && !res.get('cache-control')) {
		res.set('cache-control', 'public, max-age=3600');
	}
	// RFC 8615 discovery files (agent-card.json, ai-plugin.json, security.txt)
	// live under the `.well-known` dot-directory, which Express's dotfiles guard
	// would reject as Forbidden — allow exactly that directory and keep every
	// other dot-segment denied. resolveStatic() already confined `file` to
	// DIST_ROOT, so this loosens nothing else.
	const dotfiles = file.includes(`${path.sep}.well-known${path.sep}`) ? 'allow' : 'deny';
	// Send a path RELATIVE to DIST_ROOT. Given an absolute path and no root,
	// Express applies the dotfiles policy to EVERY segment, including the ones
	// above dist/ that no request can influence. Served from a checkout under a
	// dot-directory (every deploy worktree here is named `.deploy-wt*`), that
	// denied every static file as Forbidden and answered 500, 404.html included,
	// so a whole site read as broken for a reason nothing in the URL explained.
	// The policy is about the URL; a root is what scopes it there.
	const rel = path.relative(DIST_ROOT, file);
	return new Promise((resolvePromise) => {
		res.sendFile(rel, { dotfiles, root: DIST_ROOT }, (err) => {
			if (err && !res.headersSent) {
				// send() reports a request it cannot honour with that request's own
				// 4xx: 412 when an If-Match / If-Unmodified-Since precondition fails
				// (Cloud CDN revalidating a fill after a deploy changed the file), 416
				// for an unsatisfiable range. Those are answers, not server faults;
				// flattening them to 500 put /robots.txt and /hdri/studio.hdr in the
				// 5xx log 14 times in a week and handed the edge an error to cache.
				const status = Number(err.status || err.statusCode);
				if (status >= 400 && status < 500) {
					res.status(status).end();
				} else {
					console.error(`[static] ${req.method} ${req.url} → ${file} failed:`, err.message);
					res.status(500).end();
				}
			}
			resolvePromise();
		});
	});
}

// ---------------------------------------------------------------------------
// Express app
// ---------------------------------------------------------------------------

const app = express();
app.set('trust proxy', true); // Cloud Run sits behind Google front ends
app.disable('x-powered-by');

// The default filter skips non-compressible types (text/event-stream, images,
// GLB); shouldCompress also passes through any response that marked itself
// `x-accel-buffering: no`, so a live text stream is not held until it ends.
app.use(compression({ filter: shouldCompress }));

// Canonical host. `www.three.ws` resolves to the same load balancer as the apex
// and serves the identical app, but the apex is the only origin the platform
// declares: seo-head.mjs pins every canonical URL to it, and the media bucket's
// CORS read rule allowlists it alone. So a visitor on the www host got a page
// that looked right and then failed every cross-origin media read, because the
// browser sent `Origin: https://www.three.ws` and the bucket answered with no
// Access-Control-Allow-Origin. Measured 2026-09-09 against the live bucket: the
// apex gets its origin echoed on the same object, www gets nothing, so every
// GLB load (fetch/XHR, unlike an <img>) is blocked there and 3D silently dies.
// Collapsing the duplicate host fixes that without widening a bucket policy we
// cannot reach, and removes the duplicate-content host at the same time.
// 308 rather than 301 off the safe methods, so a POST keeps its method and body.
const CANONICAL_HOST = new URL(CANONICAL_ORIGIN).host;
const WWW_HOST = `www.${CANONICAL_HOST}`;

app.use((req, res, next) => {
	const host = String(req.headers.host || '').toLowerCase().split(':')[0];
	if (host !== WWW_HOST) return next();
	// Re-parse rather than concatenating req.url: absolute-form request targets
	// are legal on the wire, and only the path and query may cross over.
	const target = new URL(req.url, CANONICAL_ORIGIN);
	const safeMethod = req.method === 'GET' || req.method === 'HEAD';
	res.redirect(safeMethod ? 301 : 308, `${CANONICAL_ORIGIN}${target.pathname}${target.search}`);
});

// Custom domains. A host a user registered and connected here
// (api/_lib/domain-connect.js, table web_domain_hosts) serves that agent's
// public page at its root. Everything else on the host (assets, /api, the
// agent page's own subpaths) resolves as on the apex, so the page works as it
// does on three.ws. Only the root document is rewritten.
app.use(async (req, res, next) => {
	const host = String(req.headers.host || '').toLowerCase().split(':')[0];
	if (!host || host === CANONICAL_HOST || host === WWW_HOST || host.endsWith('.run.app') || host === 'localhost') return next();
	if (req.method !== 'GET' && req.method !== 'HEAD') return next();
	try {
		const { agentForHost } = await import('../api/_lib/domain-connect.js');
		const agentId = await agentForHost(host);
		if (agentId && (req.path === '/' || req.path === '')) {
			const q = req.url.indexOf('?');
			req.url = `/agents/${agentId}${q === -1 ? '' : req.url.slice(q)}`;
		}
	} catch (err) {
		console.error('[server] custom-domain lookup failed:', err?.message || err);
	}
	next();
});

// External-dest proxy: before the body parsers (see proxyExternal above).
app.use((req, res, next) => {
	const url = new URL(req.url, 'http://internal');
	const pathname = url.pathname;
	for (const route of phase1Routes) {
		const m = route.re.exec(pathname);
		if (!m) continue;
		if (!hasMatches(route, req, url)) continue;
		if (route.continue) continue;
		if (!route.dest || !isExternalDest(route.dest)) break; // a local rule wins — fall through
		const search = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
		proxyExternal(req, res, substitute(route.dest, m) + search);
		return;
	}
	next();
});

// Vercel-parity body parsing. Types not listed (multipart, image/*, …) are
// left unparsed so handlers can consume the raw request stream.
//
// `verify` stashes the exact raw bytes on req.rawBody before they're parsed —
// a handful of handlers (webhook signature verification: api/webhooks/*.js)
// need the byte-for-byte body, which a re-serialized req.body can't
// reconstruct (whitespace/key-order differ). Every other handler reads the
// body via api/_lib/http.js readJson()/readBody(), which prefers req.rawBody
// (falling back to reconstructing from req.body) instead of re-reading the
// stream — reading the stream here already fully drains it, so a second read
// downstream would hang forever waiting for 'data'/'end' events that already
// fired.
const captureRawBody = (req, _res, buf) => { req.rawBody = buf; };
app.use(express.json({ limit: BODY_LIMIT, verify: captureRawBody }));
app.use(express.urlencoded({ extended: true, limit: BODY_LIMIT, verify: captureRawBody }));
app.use(express.text({ type: 'text/*', limit: BODY_LIMIT }));
app.use(express.raw({ type: 'application/octet-stream', limit: BODY_LIMIT }));

// Second lock on /api/cron/*, ahead of the route table so no rewritten dest can
// carry an unauthenticated caller past it. Every handler there still runs its
// own requireCron; this exists so that ONE handler forgetting the line is not
// the same thing as publishing a money-moving sweep to the internet. It accepts
// the CRON_SECRET the handlers already validate and, when
// CRON_OIDC_AUDIENCE + CRON_OIDC_SERVICE_ACCOUNT are set, a Cloud Scheduler
// OIDC token. See server/cron-edge-auth.mjs.
app.use(cronEdgeAuth());

app.use(async (req, res) => {
	const url = new URL(req.url, 'http://internal');
	let currentPath = url.pathname;
	const collected = {};
	const extraQuery = {};
	let fileStatus = null;

	// The route table serves /x and /x/ identically via duplicated entries, so
	// every page exists at two URLs and crawlers see duplicate content held
	// together only by canonical tags. Collapse the slash variant permanently.
	// API paths keep their exact form and the root is already bare.
	if (
		(req.method === 'GET' || req.method === 'HEAD') &&
		currentPath.length > 1 &&
		currentPath.endsWith('/') &&
		!currentPath.startsWith('/api/')
	) {
		// Leading slashes collapse too: dot segments (`/.//evil.com/`) parse to a
		// pathname of `//evil.com/`, and a Location of `//evil.com` is a
		// protocol-relative redirect off this origin.
		const bare = currentPath.replace(/\/+$/, '').replace(/^\/+/, '/') || '/';
		res.redirect(301, bare + url.search);
		return;
	}

	// Phase 1: rules before {handle: "filesystem"}.
	for (const route of phase1Routes) {
		const m = route.re.exec(currentPath);
		if (!m) continue;
		if (!hasMatches(route, req, url)) continue;
		if (route.headers) {
			for (const [k, v] of Object.entries(route.headers)) collected[k] = substitute(v, m);
		}
		if (route.continue) continue;
		if (route.status && !route.dest) {
			res.status(route.status).set(collected).end();
			return;
		}
		if (route.dest) {
			const dest = substitute(route.dest, m);
			const qIdx = dest.indexOf('?');
			currentPath = qIdx === -1 ? dest : dest.slice(0, qIdx);
			if (qIdx !== -1) {
				for (const [k, v] of new URLSearchParams(dest.slice(qIdx + 1))) extraQuery[k] = v;
			}
			if (route.status) fileStatus = route.status;
			break; // non-continue dest ends phase-1 matching
		}
	}

	// CORS preflight for the static media routes. Those rules advertise
	// `access-control-allow-methods: GET, HEAD, OPTIONS`, but the filesystem
	// phase below only serves GET/HEAD, so an OPTIONS request fell through to
	// the 404 and every cross-origin fetch carrying a non-safelisted header
	// (a GLTFLoader with setRequestHeader, a fetch with an auth or tracing
	// header) was blocked by the browser even though the GET itself is
	// world-open. Answer the preflight from the headers the route already
	// collected. /api/ paths are excluded: their handlers own their own CORS.
	if (
		req.method === 'OPTIONS' &&
		!currentPath.startsWith('/api/') &&
		collected['access-control-allow-methods']
	) {
		const requested = req.headers['access-control-request-headers'];
		res
			.status(204)
			.set(collected)
			.set({
				'access-control-allow-headers': requested || '*',
				'access-control-max-age': '86400',
				// The route's own long cache-control belongs to the asset, not to
				// this negotiation: a shared cache holding one preflight would
				// answer it for a different requested-header set.
				'cache-control': 'no-store',
				vary: 'Origin, Access-Control-Request-Headers',
			})
			.end();
		return;
	}

	// Functions phase: anything routed under /api/ is a serverless handler.
	if (currentPath.startsWith('/api/')) {
		// Vercel parity: a handler behind a dest rewrite sees the dest's query
		// params on req.url (many handlers — api/oracle-share.js,
		// api/agent-share.js — parse new URL(req.url) rather than req.query), but
		// keeps the ORIGINAL request pathname. Using the dest path here breaks
		// every handler behind a "[param].js"-style dest that routes by path
		// segment: /api/marketplace/categories → dest
		// /api/marketplace/[action]?action=categories made api/marketplace/[action].js
		// parse the literal segment "[action]" as its action and 404
		// (/marketplace, /skills, /economy all lost their category/theme/list
		// calls). Merge the dest query onto the original pathname instead —
		// both handler styles read what they expect.
		if (Object.keys(extraQuery).length > 0) {
			const merged = new URLSearchParams(url.search);
			for (const [k, v] of Object.entries(extraQuery)) merged.set(k, v);
			req.url = `${url.pathname}?${merged.toString()}`;
		}
		res.set(collected);
		if (await dispatchApi(req, res, currentPath, extraQuery)) return;
		res.status(404).json({
			error: 'not_found',
			message: `No API route matches ${currentPath}.`,
		});
		return;
	}

	// Filesystem phase (GET/HEAD only, like a static host).
	if (req.method === 'GET' || req.method === 'HEAD') {
		// /docs/* and /tutorials/* rewrite every slug to one shell, so a typo used
		// to answer 200 with an empty shell instead of a 404. When the article the
		// shell would fetch does not exist, this is not a page: serve whatever the
		// raw path names on disk (/docs/<dir>/index.html), and otherwise skip the
		// filesystem phase so the request lands on the designed 404 below.
		const shellMiss = isMissingShellPage(DIST_ROOT, currentPath, url.pathname);
		const file = shellMiss ? resolveStatic(url.pathname) : resolveStatic(currentPath);
		if (file) {
			// A few directory pages render their whole body from client JS, which
			// leaves crawlers and no-JS visitors an empty shell. For those routes we
			// inject the page's own first view before sending it. Any failure inside
			// falls through to the untouched file, so this can never break a page.
			if (req.method === 'GET' && isSsrRoute(currentPath) && !url.search) {
				try {
					const shell = readFileSync(file, 'utf8');
					const html = await renderSsrPage(currentPath, shell, `http://127.0.0.1:${PORT}`);
					if (html) {
						// Hash the body we are actually sending, not the shell on disk:
						// the injected block carries its own JSON-LD.
						res.set(hardenHeaderBag(collected, html));
						if (fileStatus) res.status(fileStatus);
						res.set('content-type', 'text/html; charset=utf-8');
						// Same freshness the static shell gets from the CDN, but the
						// injected block is only as fresh as its own cache TTL.
						res.set('cache-control', 'public, max-age=60, s-maxage=300');
						res.send(html);
						return;
					}
				} catch (err) {
					console.error(`[ssr] ${currentPath} fell back to the static shell:`, err.message);
				}
			}
			// /m/:id is one shell for every forge creation. Give each its own
			// title, canonical, summary_large_image card (the PNG render of the
			// model) and 3DModel JSON-LD, for every User-Agent: see the header
			// of server/creation-head.mjs. Any miss serves the plain shell.
			if (req.method === 'GET' && file.endsWith('.html') && creationIdFromPath(url.pathname)) {
				const html = await renderCreationHead(url.pathname, readFileSync(file, 'utf8'));
				if (html) {
					res.set(hardenHeaderBag(collected, html));
					if (fileStatus) res.status(fileStatus);
					res.set('content-type', 'text/html; charset=utf-8');
					res.set('cache-control', 'public, max-age=60, s-maxage=300');
					res.send(html);
					return;
				}
			}
			// Shared-shell routes (/docs/*, /tutorials/*) all resolve to one HTML
			// file whose static head names the shell's own route. Rewrite the head
			// for the page actually requested so each route presents its own
			// canonical, title, social card and JSON-LD. Uses the ORIGINAL request
			// path: currentPath is already the dest rewrite (/docs/index.html).
			if (req.method === 'GET' && file.endsWith('.html') && hasSeoRoute(url.pathname)) {
				const head = renderSeoHead(url.pathname, file);
				// /tutorials/* and /walkthroughs/* fetch their content client-side,
				// so the shell alone carries no text for a crawler to read. Render
				// the body too; the player replaces it on load.
				const html = renderCrawlerBody(url.pathname, head) || head;
				if (html) {
					// The rewritten head swaps in this route's own JSON-LD block, so
					// the policy has to describe the rewritten bytes.
					res.set(hardenHeaderBag(collected, html));
					if (fileStatus) res.status(fileStatus);
					res.set('content-type', 'text/html; charset=utf-8');
					res.set('cache-control', 'public, max-age=60, s-maxage=300');
					res.send(html);
					return;
				}
			}
			await serveFile(req, res, file, collected, fileStatus);
			return;
		}
	}

	// Post-filesystem rules (the 404.html fallback). A cache policy collected in
	// phase 1 described the file that rule expected to find, not this miss:
	// /agent-3d/<unreleased version>/ inherited `max-age=31536000, immutable`,
	// and the CDN then held that 404 for a year after the version was cut.
	for (const key of Object.keys(collected)) {
		if (key.toLowerCase() === 'cache-control') delete collected[key];
	}
	for (const route of postFsRoutes) {
		const m = route.re.exec(currentPath);
		if (!m) continue;
		if (!hasMatches(route, req, url)) continue;
		if (route.headers) {
			for (const [k, v] of Object.entries(route.headers)) collected[k] = substitute(v, m);
		}
		if (route.dest) {
			const file = resolveStatic(substitute(route.dest, m));
			if (file) {
				await serveFile(req, res, file, collected, route.status || 404);
				return;
			}
		}
		if (route.status) {
			res.status(route.status).set(collected).end();
			return;
		}
	}

	res.status(404).set(collected).type('text/plain').send('Not found');
});

// Body-parser failures (malformed JSON, over-limit payloads) → clean 4xx.
app.use((err, req, res, next) => {
	if (res.headersSent) return next(err);
	const status = err?.status || err?.statusCode;
	if (status && status >= 400 && status < 500) {
		// body-parser tags over-limit payloads with type 'entity.too.large'.
		// Surface a specific code + human message so client error paths (which
		// read error/error_description) say something actionable.
		if (err?.type === 'entity.too.large' || status === 413) {
			// Quote BODY_LIMIT rather than a literal: this said "under 4 MB" long
			// after the cap moved to 8 MB, so a caller inside the real limit was
			// told to shrink a payload that was already small enough.
			res.status(413).json({
				error: 'payload_too_large',
				error_description: `Request body is too large. Keep it under ${BODY_LIMIT.toUpperCase().replace('MB', ' MB')}.`,
				message: err.message,
			});
			return;
		}
		// Same reason as the 413 branch above: client error paths read
		// error/error_description, so a body-parser rejection that carried only
		// `message` rendered as an empty reason next to every handler-emitted
		// 4xx on the same endpoint.
		res.status(status).json({
			error: 'bad_request',
			error_description: err.message,
			message: err.message,
		});
		return;
	}
	console.error('[server] unexpected middleware error:', err);
	res.status(500).json({ error: 'internal_error', message: 'The request failed unexpectedly.' });
});

process.on('unhandledRejection', (reason) => {
	console.error('[server] unhandled rejection:', reason);
});

// Last-resort backstop: a stray synchronous throw or an un-listened stream
// 'error' (e.g. an upstream socket reset outside the proxy's own await path)
// must not terminate the container — it would drop every other in-flight
// request. Log and keep serving; Cloud Run recycles unhealthy instances.
process.on('uncaughtException', (err) => {
	console.error('[server] uncaught exception:', err);
});

const server = app.listen(PORT, () => {
	console.log(
		`[server] three-ws listening on :${PORT} (api: ${API_ROOT}, static: ${DIST_ROOT}, routes: ${phase1Routes.length}+${postFsRoutes.length})`,
	);
});
// SSE endpoints hold connections open; keep Node's idle timeouts out of the way
// (Cloud Run enforces the real request deadline).
server.requestTimeout = 0;
server.headersTimeout = 65_000;
server.keepAliveTimeout = 620_000;

// Cloud Run sends SIGTERM before scale-down; finish in-flight work, then exit.
process.on('SIGTERM', () => {
	console.log('[server] SIGTERM received, draining…');
	server.close(() => process.exit(0));
	setTimeout(() => process.exit(0), 10_000).unref();
});