@runeditrun/rer 0.1.0 → 0.2.0

package/global/door/pages.mjs

@@ -0,0 +1,49 @@
+// The door's own small pages: the index, starting, start button, failure and
+// unknown-name pages. Plain HTML; the starting page polls the door's state
+// path (a fetch, which never starts a site) and reloads, keeping the fragment.
+const escape = value => String(value).replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]);
+
+const style = `:root{color-scheme:light dark;--bg:#f7f7f5;--fg:#1d1d1b;--muted:#666;--line:#ddd;--accent:#2457c5}
+@media (prefers-color-scheme:dark){:root{--bg:#161615;--fg:#ecece8;--muted:#a3a39d;--line:#333;--accent:#8fb0ff}}
+body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,-apple-system,sans-serif}
+main{max-width:760px;margin:0 auto;padding:40px 16px}h1{font-size:20px;margin:0 0 4px}p{margin:8px 0}.muted{color:var(--muted)}
+table{width:100%;border-collapse:collapse;margin:20px 0}th,td{text-align:left;padding:8px 6px;border-bottom:1px solid var(--line);vertical-align:top}
+a{color:var(--accent)}code{font:13px ui-monospace,monospace}button{font:inherit;padding:6px 14px;border:1px solid var(--line);border-radius:6px;background:transparent;color:var(--fg);cursor:pointer}
+pre{white-space:pre-wrap;background:rgba(127,127,127,.12);padding:12px;border-radius:6px;font:13px ui-monospace,monospace}`;
+
+function page(title, body, { script = '' } = {}) {
+ return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="referrer" content="origin"><title>${escape(title)}</title><style>${style}</style></head><body><main>${body}</main>${script ? `<script>${script}</script>` : ''}</body></html>`;
+}
+
+export const rebootNote = 'After a reboot or logout the front door needs <code>rer door start</code> (or any <code>rer dev</code> in a door-mode checkout).';
+
+export function indexPage({ port, version, sites }) {
+ const rows = sites.map(site => {
+  const link = site.mode === 'door' || site.state !== 'running' ? site.doorUrl : site.url;
+  const direct = site.mode === 'direct' ? ` <span class="muted">direct${site.url && site.url !== site.doorUrl ? `: <a href="${escape(site.url)}">${escape(site.url)}</a>` : ''}</span>` : '';
+  return `<tr><td><a href="${escape(link)}/">${escape(site.name)}</a>${direct}</td><td>${escape(site.state)}</td><td class="muted"><code>${escape(site.path)}</code></td></tr>`;
+ }).join('');
+ return page('rer front door', `<h1>rer front door</h1><p class="muted">Port ${port} · rer ${escape(version)}. A site starts when you open it and stops when idle.</p>
+${sites.length ? `<table><thead><tr><th>Site</th><th>State</th><th>Checkout</th></tr></thead><tbody>${rows}</tbody></table>` : '<p>No checkouts are registered. Add one with <code>rer door add PATH</code>.</p>'}
+<p class="muted">Add a checkout with <code>rer door add PATH</code>; see sign-in links with <code>rer door status --links</code>. ${rebootNote}</p>`);
+}
+
+const poll = `const fragment=location.hash;async function check(){try{const r=await fetch('/__rer/door/state',{cache:'no-store'});const s=await r.json();
+if(s.state==='running'){if(s.redirect){location.replace(s.redirect+location.pathname+location.search+fragment);}else{location.reload();}return;}
+if(s.state==='failed'){document.getElementById('status').textContent='The site could not start:';const p=document.getElementById('reason');p.textContent=s.reason;p.hidden=false;return;}}catch{}setTimeout(check,1000);}check();`;
+
+export function startingPage(name) {
+ return page(`Starting ${name}`, `<h1>Starting ${escape(name)}…</h1><p id="status" class="muted">This page reloads when the site is ready. A first start can take a minute.</p><pre id="reason" hidden></pre>`, { script: poll });
+}
+
+export function confirmPage(name, to) {
+ return page(`Start ${name}?`, `<h1>${escape(name)} is not running</h1><p>Another site sent you here. Start it?</p><form method="post" action="/__rer/door/start?to=${encodeURIComponent(to)}"><button type="submit">Start ${escape(name)}</button></form>`);
+}
+
+export function failurePage(name, reason, to) {
+ return page(`${name} could not start`, `<h1>${escape(name)} could not start</h1><pre>${escape(reason)}</pre><form method="post" action="/__rer/door/start?to=${encodeURIComponent(to)}"><button type="submit">Try again</button></form>`);
+}
+
+export function unknownPage(name, port) {
+ return page('No such site', `<h1>No checkout is registered as ${escape(name)}</h1><p>Register a checkout with <code>rer door add PATH</code>, then open <code>http://NAME.localhost:${port}</code>. <a href="http://localhost:${port}/">All sites</a>.</p>`);
+}

package/global/door/policy.mjs

@@ -0,0 +1,49 @@
+// The door's policy is stored, never inherited: `rer door enable` records the
+// limit, the idle time and the RER_* variables in effect at that moment, and
+// every site the door starts gets exactly those on top of an allowlisted base
+// environment. Whoever later starts the door (a fleet agent, a test) cannot
+// change them by running it with another environment.
+import { resolve } from 'node:path';
+import { doorDefaults, doorDirectory } from '../../cli/door.mjs';
+import { serversDirectory } from '../registry.mjs';
+
+const base = new Set(['HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'TMPDIR', 'TERM']);
+// Set by the policy itself, so never recorded from a shell.
+const policyVariables = new Set(['RER_SERVER_LIMIT', 'RER_SERVER_IDLE_SECONDS']);
+
+export function baseEnvironment(env = process.env) {
+ return Object.fromEntries(Object.entries(env).filter(([name, value]) => value !== undefined && (base.has(name) || name.startsWith('LC_'))));
+}
+
+export function recordedEnvironment(env = process.env) {
+ return Object.fromEntries(Object.entries(env).filter(([name, value]) => value !== undefined && name.startsWith('RER_') && !policyVariables.has(name)).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function count(value, name, minimum = 1) {
+ if (!/^[0-9]+$/.test(value ?? '') || !Number.isSafeInteger(Number(value)) || Number(value) < minimum) throw Object.assign(Error(`${name} takes a whole number of at least ${minimum}.`), { exitCode: 2 });
+ return Number(value);
+}
+
+// What `rer door enable` records: flags, else the person defaults.
+export function enabledPolicy({ port, serverLimit, idleTimeout }, env = process.env) {
+ const chosen = port === undefined ? undefined : count(port, '--port');
+ if (chosen !== undefined && chosen > 65535) throw Object.assign(Error('--port takes a port from 1 to 65535.'), { exitCode: 2 });
+ return {
+  port: chosen,
+  policy: { serverLimit: serverLimit === undefined ? doorDefaults.serverLimit : count(serverLimit, '--server-limit'), idleSeconds: idleTimeout === undefined ? doorDefaults.idleSeconds : count(idleTimeout, '--idle-timeout') },
+  directory: doorDirectory(env),
+  serversDir: resolve(serversDirectory(env)),
+  environment: recordedEnvironment(env),
+ };
+}
+
+// The environment of a site the door starts.
+export function siteEnvironment(door, env = process.env) {
+ return { ...baseEnvironment(env), ...door.environment, RER_DOOR_DIR: door.directory, RER_SERVERS_DIR: door.serversDir, RER_SERVER_LIMIT: String(door.policy.serverLimit), RER_SERVER_IDLE_SECONDS: String(door.policy.idleSeconds) };
+}
+
+// The environment of the door process itself.
+export const doorProcessEnvironment = (door, env = process.env) => ({ ...baseEnvironment(env), RER_DOOR_DIR: door.directory });
+
+// `rer dev` may bring an enabled door back only for the registry it records.
+export const ownsRegistry = (door, env = process.env) => doorDirectory(env) === door.directory && resolve(serversDirectory(env)) === door.serversDir;

package/global/door/routes.mjs

@@ -0,0 +1,45 @@
+// How the door reads a request: which Host it names, and whether it may start
+// a stopped site. Measured facts behind the start rule (Chromium 140-154,
+// WebKit 26, Safari 27): only a top-level document navigation carries
+// Sec-Fetch-Mode navigate with Sec-Fetch-Dest document; iframes say iframe,
+// subresources and fetch say no-cors/cors, Chromium sends no Sec-Fetch-* on a
+// WebSocket upgrade, and an open tab's Vite ping is a fetch.
+import { isLocalhostName } from '../../modules/operator-auth/loopback.mjs';
+
+export const indexHostnames = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+// { kind: 'index' | 'site' | 'redirect' | 'foreign', name?, host?, canonical? }
+// Matching is case-insensitive: any letter case of a door Host is answered as
+// the lowercase Host is, and `host` is that canonical lowercase spelling, which
+// the door sends upstream (a site's dev server allows only lowercase
+// *.localhost). A trailing-dot Host redirects to the canonical Host.
+export function readHost(header, port) {
+ const match = /^(\[[0-9a-f:.]+\]|[^:[\]]+)(?::(\d{1,5}))?$/.exec(String(header ?? '').toLowerCase());
+ if (!match || Number(match[2] ?? 80) !== port) return { kind: 'foreign' };
+ const hostname = match[1].replace(/\.+$/, ''), host = `${hostname}:${port}`;
+ const index = indexHostnames.has(hostname);
+ if (!index && !isLocalhostName(hostname)) return { kind: 'foreign' };
+ if (hostname !== match[1]) return { kind: 'redirect', canonical: host };
+ if (index) return { kind: 'index', host };
+ // Subdomains route to their site: x.cradle.localhost is cradle.
+ return { kind: 'site', name: hostname.slice(0, -'.localhost'.length).split('.').pop(), host };
+}
+
+const refererOrigin = value => { try { return new URL(value).origin; } catch { return undefined; } };
+
+// 'start': a top-level navigation the person made (typed, bookmarked, same
+// site, from the door's own index, or a client without fetch metadata asking
+// for HTML). 'confirm': another site's navigation, which gets a Start button.
+// 'never': everything else (subresources, fetch/XHR, prefetch, OPTIONS, other
+// methods and every WebSocket upgrade).
+export function startKind(request, indexOrigins) {
+ const headers = request.headers;
+ if (headers.upgrade || !['GET', 'HEAD'].includes(request.method)) return 'never';
+ if (headers['sec-purpose'] || headers.purpose || headers['x-purpose'] || headers['x-moz'] === 'prefetch') return 'never';
+ const mode = headers['sec-fetch-mode'], dest = headers['sec-fetch-dest'], site = headers['sec-fetch-site'];
+ if (mode === undefined && dest === undefined && site === undefined) return /\btext\/html\b/i.test(headers.accept ?? '') ? 'start' : 'never';
+ if (mode !== 'navigate' || dest !== 'document') return 'never';
+ if (['none', 'same-origin', 'same-site'].includes(site)) return 'start';
+ if (indexOrigins.has(refererOrigin(headers.referer))) return 'start';
+ return 'confirm';
+}

package/global/door/server.mjs

@@ -0,0 +1,255 @@
+// The front door process: node server.mjs, with RER_DOOR_DIR set. One process
+// listens on 127.0.0.1:PORT (required) and [::1]:PORT (when IPv6 loopback
+// exists), never a wildcard address, and routes by Host:
+//   localhost, 127.0.0.1, [::1]      the index of sites (and the identity proof)
+//   NAME.localhost and subdomains    that checkout, Host preserved (lowercased;
+//                                    matching ignores letter case)
+//   a trailing-dot Host              308 to the canonical Host
+//   an unknown *.localhost           404 saying how to add a checkout
+//   anything else                    400, never proxied (the DNS-rebinding guard)
+// It never reads cookies (beyond making Domain=localhost Set-Cookie host-only,
+// on HTTP and WebSocket handshake replies alike) and never holds a dev key.
+import http from 'node:http';
+import net from 'node:net';
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
+import { changeDoorState, doorChallengeHeader, doorIdentityPath, doorProof, doorProtocol, doorSecretHeader, readDoorState, readPrivate, writePrivate } from '../../cli/door.mjs';
+import { listeners, processName } from '../../onboarding/process-diagnostics.mjs';
+import { ownManifest, ownRoot } from '../package-info.mjs';
+import { confirmPage, failurePage, indexPage, startingPage, unknownPage } from './pages.mjs';
+import { hostOnlyCookie, hostOnlyHead, splitHead } from './cookies.mjs';
+import { readHost, startKind } from './routes.mjs';
+import { doorSites } from './sites.mjs';
+
+const say = line => process.stdout.write(`${new Date().toISOString()} ${line}\n`);
+function fail(message, code = 4) { process.stderr.write(`rer door: ${message}\n`); process.exit(code); }
+
+const state = await readDoorState(process.env);
+if (!state?.door?.enabled) fail('The front door is not enabled. Run rer door enable.', 3);
+const { door } = state, port = door.port, version = ownManifest().version;
+const token = (await readPrivate(join(state.directory, 'token')))?.trim();
+if (!token) fail(`The front door's token is missing from ${state.directory}. Run rer door enable.`, 3);
+const sites = doorSites({ env: process.env, door, log: say });
+const indexOrigins = new Set(['localhost', '127.0.0.1', '[::1]'].map(host => `http://${host}:${port}`));
+const portOf = name => Number(/:(\d+)$/.exec(name)?.[1]);
+
+async function holder() {
+ const row = (await listeners()).find(item => item.pid !== process.pid && item.names.some(name => portOf(name) === port));
+ return row && `PID ${row.pid} (${await processName(row.pid)})`;
+}
+const busy = who => `Port ${port} is held by ${who}. The front door needs 127.0.0.1:${port} and [::1]:${port} to itself. Stop that process, or enable the door on another port with rer door enable --port N.`;
+
+// --- responses -------------------------------------------------------------
+const send = (res, status, type, body, headers = {}) => { res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', ...headers }); res.end(body); };
+const html = (res, status, body, headers) => send(res, status, 'text/html; charset=utf-8', body, headers);
+const text = (res, status, body, headers) => send(res, status, 'text/plain; charset=utf-8', body + '\n', headers);
+const json = (res, status, value) => send(res, status, 'application/json', JSON.stringify(value));
+
+const publicView = view => ({ name: view.name, path: view.path, mode: view.mode, state: view.state, url: view.url, ...(view.proxyPort ? { proxyPort: view.proxyPort } : {}), ...(view.reason ? { reason: view.reason } : {}) });
+
+async function index(req, res) {
+ const path = new URL(req.url, 'http://door').pathname;
+ if (path === doorIdentityPath) {
+  const challenge = String(req.headers[doorChallengeHeader] ?? '');
+  if (!/^[0-9a-f]{16,128}$/.test(challenge)) return json(res, 400, { error: 'challenge required' });
+  const address = req.socket.localAddress?.replace(/^::ffff:/, '');
+  return json(res, 200, { protocol: doorProtocol, pid: process.pid, proof: doorProof(token, challenge, address) });
+ }
+ if (path === '/__rer/door/status') return json(res, 200, { protocol: doorProtocol, pid: process.pid, port, version, sites: (await sites.views()).map(publicView) });
+ if (path !== '/' || !['GET', 'HEAD'].includes(req.method)) return text(res, 404, 'Not found.');
+ return html(res, 200, indexPage({ port, version, sites: await sites.views() }), { 'referrer-policy': 'origin' });
+}
+
+// `stale()` answers instead when the server has just stopped (the registry
+// view is cached for a second): a refused connection before any byte was sent.
+function proxy(req, res, view, host, stale) {
+ const upstream = http.request({ host: '127.0.0.1', port: view.proxyPort, method: req.method, path: req.url, headers: { ...req.headers, host, [doorSecretHeader]: view.secret }, agent: false }, reply => {
+  const raw = [];
+  for (let i = 0; i < reply.rawHeaders.length; i += 2) raw.push(reply.rawHeaders[i], reply.rawHeaders[i].toLowerCase() === 'set-cookie' ? hostOnlyCookie(reply.rawHeaders[i + 1]) : reply.rawHeaders[i + 1]);
+  res.writeHead(reply.statusCode, reply.statusMessage, raw);
+  reply.pipe(res);
+ });
+ req.once('aborted', () => upstream.destroy());
+ res.once('close', () => upstream.destroy());
+ upstream.on('error', error => {
+  sites.invalidate();
+  if (res.headersSent) return res.destroy();
+  if (error.code === 'ECONNREFUSED' && stale && ['GET', 'HEAD'].includes(req.method)) return stale();
+  text(res, 502, `${view.name} stopped answering. Reload to start it again.`);
+ });
+ if (req.readableEnded) upstream.end(); else req.pipe(upstream);
+}
+
+async function site(req, res, target, retried = false) {
+ const url = new URL(req.url, 'http://door'), registered = (await sites.list()).find(item => item.name === target.name);
+ if (!registered) { req.resume(); return html(res, 404, unknownPage(target.name, port)); }
+ // The door's own paths on a site host: its state (polled by the starting
+ // page) and the same-origin Start button.
+ if (url.pathname === '/__rer/door/state') {
+  const view = await sites.view(registered, { force: true });
+  return json(res, 200, { state: view.state, ...(view.reason ? { reason: view.reason } : {}), ...(view.state === 'running' && view.mode === 'direct' ? { redirect: view.url } : {}) });
+ }
+ if (url.pathname === '/__rer/door/start') {
+  req.resume();
+  const sameOrigin = req.headers.origin === `http://${target.host}` && ['same-origin', undefined].includes(req.headers['sec-fetch-site']);
+  if (req.method !== 'POST' || !sameOrigin) return text(res, 403, 'Start a site from its own page.');
+  sites.ensureStarted(registered);
+  const to = url.searchParams.get('to');
+  return send(res, 303, 'text/plain; charset=utf-8', '', { location: to?.startsWith('/') && !to.startsWith('//') ? to : '/' });
+ }
+ const view = await sites.view(registered, { force: retried });
+ const kind = startKind(req, indexOrigins), here = url.pathname + url.search;
+ if (view.state === 'running') {
+  if (view.mode === 'door') return proxy(req, res, view, target.host, retried ? undefined : () => site(req, res, target, true).catch(() => { if (!res.headersSent) text(res, 502, 'The front door could not answer this request.'); }));
+  // A direct-mode checkout (an old pin): send navigations to its own URL.
+  req.resume();
+  return kind === 'never' ? text(res, 404, `${view.name} is served directly at ${view.url}.`) : send(res, 302, 'text/plain; charset=utf-8', '', { location: view.url + here });
+ }
+ req.resume();
+ if (kind === 'never') return text(res, 503, `${view.name} is not running. Open http://${target.host}/ in a browser to start it.`);
+ if (view.state === 'failed') return html(res, 200, failurePage(view.name, view.reason, here));
+ if (kind === 'confirm' && view.state !== 'starting') return html(res, 200, confirmPage(view.name, here));
+ sites.ensureStarted(registered);
+ return html(res, 503, startingPage(view.name), { 'retry-after': '2' });
+}
+
+const active = new Set(), upgraded = new Set();
+async function handle(req, res) {
+ active.add(res); res.once('close', () => active.delete(res));
+ try {
+  const target = readHost(req.headers.host, port);
+  if (target.kind === 'redirect') { req.resume(); return send(res, 308, 'text/plain; charset=utf-8', '', { location: `http://${target.canonical}${req.url}` }); }
+  if (target.kind === 'index') return await index(req, res);
+  if (target.kind === 'site') return await site(req, res, target);
+  req.resume();
+  return text(res, 400, `This front door serves only localhost names on port ${port}.`);
+ } catch (error) {
+  say(`request failed: ${error.message}`);
+  if (!res.headersSent) text(res, 500, 'The front door could not answer this request.'); else res.destroy();
+ }
+}
+
+// WebSockets (Vite HMR among them) reach running door-mode sites only; an
+// upgrade never starts a site, and one whose Origin is another site's is refused.
+// An upgrade cannot follow a redirect, so a trailing-dot Host is read as its
+// canonical Host; upstream always sees the canonical (lowercase) Host.
+async function upgrade(req, socket, head) {
+ const refuse = status => socket.end(`HTTP/1.1 ${status}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+ socket.on('error', () => socket.destroy());
+ const read = readHost(req.headers.host, port);
+ const target = read.kind === 'redirect' ? readHost(read.canonical, port) : read;
+ if (target.kind !== 'site') return refuse('400 Bad Request');
+ const registered = (await sites.list()).find(item => item.name === target.name);
+ if (!registered) return refuse('404 Not Found');
+ const origin = req.headers.origin;
+ if (origin !== undefined && origin !== `http://${target.host}`) return refuse('403 Forbidden');
+ const view = await sites.view(registered);
+ if (view.state !== 'running' || view.mode !== 'door') return refuse('503 Service Unavailable');
+ const upstream = net.connect(view.proxyPort, '127.0.0.1', () => {
+  let lines = `${req.method} ${req.url} HTTP/${req.httpVersion}\r\n`;
+  for (let i = 0; i < req.rawHeaders.length; i += 2) {
+   const name = req.rawHeaders[i].toLowerCase();
+   if (name !== doorSecretHeader) lines += `${req.rawHeaders[i]}: ${name === 'host' ? target.host : req.rawHeaders[i + 1]}\r\n`;
+  }
+  upstream.write(`${lines}${doorSecretHeader}: ${view.secret}\r\n\r\n`);
+  if (head.length) upstream.write(head);
+  socket.pipe(upstream);
+  // The reply's head (101 or any other status) goes through the cookie rule;
+  // the bytes after it pass unchanged.
+  let reply = Buffer.alloc(0);
+  const readHead = chunk => {
+   reply = Buffer.concat([reply, chunk]);
+   const split = splitHead(reply);
+   if (!split) { if (reply.length > 65536) close(); return; }
+   upstream.off('data', readHead);
+   socket.write(hostOnlyHead(split.head));
+   if (split.rest.length) socket.write(split.rest);
+   upstream.pipe(socket);
+  };
+  upstream.on('data', readHead);
+ });
+ upgraded.add(socket);
+ const close = () => { upgraded.delete(socket); socket.destroy(); upstream.destroy(); };
+ upstream.on('error', close); upstream.on('close', close); socket.on('close', close);
+}
+
+// --- listening ---------------------------------------------------------------
+const servers = [];
+function listen(host) {
+ const server = http.createServer(handle);
+ server.on('upgrade', upgrade);
+ server.on('clientError', (error, socket) => socket.destroy());
+ return new Promise((resolve, reject) => {
+  server.once('error', reject);
+  server.listen({ host, port, exclusive: true, ...(host === '::1' ? { ipv6Only: true } : {}) }, () => { servers.push(server); resolve(server); });
+ });
+}
+
+const before = await holder();
+if (before) fail(busy(before));
+try { await listen('127.0.0.1'); }
+catch (error) { fail(error.code === 'EADDRINUSE' ? busy(await holder() ?? 'another process') : `Cannot listen on 127.0.0.1:${port}: ${error.code ?? error.message}.`); }
+const addresses = ['127.0.0.1'];
+try { await listen('::1'); addresses.push('::1'); }
+catch (error) {
+ // IPv6 loopback may not exist (a container, ipv6.disable=1); 127.0.0.1 alone serves then.
+ if (!['EADDRNOTAVAIL', 'EAFNOSUPPORT'].includes(error.code)) fail(error.code === 'EADDRINUSE' ? busy(await holder() ?? 'another process on [::1]') : `Cannot listen on [::1]:${port}: ${error.code ?? error.message}.`);
+}
+// Address families do not exclude each other: a wildcard listener elsewhere
+// would still answer browsers that try [::1] first.
+const after = await holder();
+if (after) fail(busy(after));
+
+const { start } = await processInfo(process.pid);
+const record = { protocol: doorProtocol, pid: process.pid, start, port, addresses, version, versionDir: ownRoot, startedAt: new Date().toISOString() };
+await writePrivate(join(state.directory, 'process.json'), JSON.stringify(record) + '\n');
+say(`front door listening on ${addresses.map(address => address === '::1' ? `[::1]:${port}` : `${address}:${port}`).join(' and ')} (PID ${process.pid}, rer ${version})`);
+
+// On SIGTERM: stop accepting and close WebSockets (open tabs reconnect through
+// HMR). During a restart (`restarting` in the state) the starts under way are
+// handed to the next door, and the process record is removed at once so that
+// door can take the port while this one finishes its requests (up to 10 s).
+// On a plain stop, starts under way get up to 25 s (inside rer door stop's 30)
+// to record their servers as door-started.
+let stopping = false;
+async function release() {
+ try { const current = JSON.parse(await readFile(join(state.directory, 'process.json'), 'utf8')); if (current.pid === process.pid) await rm(join(state.directory, 'process.json'), { force: true }); } catch {}
+}
+async function handOver() {
+ try {
+  return await changeDoorState(process.env, current => {
+   if (!current.door?.restarting) return false;
+   const names = sites.pending();
+   if (names.length) current.door.handoff = [...new Set([...(current.door.handoff ?? []), ...names])];
+   return true;
+  });
+ } catch (error) { say(`could not hand over the starts under way: ${error.message}`); return false; }
+}
+async function stop(signal) {
+ if (stopping) return; stopping = true;
+ say(`stopping (${signal})`);
+ for (const server of servers) server.close();
+ for (const socket of upgraded) socket.destroy();
+ const restarting = await handOver();
+ if (restarting) { say('handing over to the next door'); await release(); }
+ for (const started = Date.now(); (active.size && Date.now() - started < 10000) || (!restarting && sites.busy() && Date.now() - started < 25000);) await delay(100);
+ for (const server of servers) server.closeAllConnections();
+ await release();
+ process.exit(0);
+}
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => void stop(signal));
+process.on('SIGHUP', () => {});
+
+// Starts the door this one replaced handed over (rer door restart or enable):
+// each continues here, attaching to the launch already under way, so its tab
+// on the starting page reloads into the site.
+try {
+ const handed = await changeDoorState(process.env, current => { const names = current.door?.handoff ?? []; if (current.door) delete current.door.handoff; return names; });
+ const registered = await sites.list(true);
+ for (const name of handed) {
+  const site = registered.find(item => item.name === name);
+  if (site) { say(`continuing the start of ${name} from the previous door`); sites.ensureStarted(site); }
+ }
+} catch (error) { say(`could not read the starts handed over: ${error.message}`); }

package/global/door/sites.mjs

@@ -0,0 +1,192 @@
+// The door's registered sites and the servers behind them. Routes come from
+// the shared server registry the door recorded (a door-mode server lists its
+// proxy port and per-start secret there), so a door restart loses nothing.
+// The door starts a stopped site by running that checkout's own `rer dev`
+// through this package's launcher, with the site environment from its stored
+// policy, and reads only its exit status (and, on failure, the error events of
+// its private log); it never reads or holds a dev key.
+import { spawn } from 'node:child_process';
+import { open, readFile, stat } from 'node:fs/promises';
+import { createConnection } from 'node:net';
+import { join } from 'node:path';
+import { changeDoorState, doorOrigin, doorProtocol, doorSite, readDoorState } from '../../cli/door.mjs';
+import { ownRoot } from '../package-info.mjs';
+import { liveServers } from '../registry.mjs';
+import { siteEnvironment } from './policy.mjs';
+
+const rerEntry = join(ownRoot, 'global/rer.mjs');
+const startTimeoutMs = 15 * 60_000, failureShownMs = 30_000;
+
+// A registered server's own status: whether it has finished starting.
+function serverReady(record) {
+ return new Promise(resolve => {
+  const socket = createConnection(record.control);
+  let text = '';
+  socket.setTimeout(2000, () => socket.destroy());
+  socket.on('connect', () => socket.end(JSON.stringify({ token: record.token, action: 'status' })));
+  socket.on('data', chunk => { text += chunk; if (text.length > 16384) socket.destroy(); });
+  socket.on('end', () => { try { const value = JSON.parse(text); resolve(value.token === record.token && value.ready === true); } catch { resolve(false); } });
+  socket.on('error', () => resolve(false));
+  socket.on('close', () => resolve(false));
+ });
+}
+
+// { code, error }: listened for as soon as the child is spawned, because a
+// spawn that fails (its folder gone) reports it on the next tick.
+function exitOf(child) { return new Promise(resolve => { child.once('error', error => resolve({ code: 1, error })); child.once('exit', (code, signal) => resolve({ code: code ?? (signal ? 128 : 1) })); }); }
+
+// The `message` of the launcher's JSON error events, nothing else.
+async function failureReason(path, from) {
+ const lines = (await readFile(path, 'utf8')).slice(from).split('\n');
+ const reasons = [];
+ for (const line of lines) {
+  if (!line.startsWith('{')) continue;
+  try { const event = JSON.parse(line); if (event.event === 'error' && typeof event.message === 'string') reasons.push(event.message); } catch {}
+ }
+ return reasons.at(-1) ?? 'The launch stopped without a reason. Run rer dev in the checkout to see it.';
+}
+
+export function doorSites({ env, door, log = () => {} }) {
+ const doorEnv = { ...env, RER_DOOR_DIR: door.directory }, serverEnv = { ...env, RER_SERVERS_DIR: door.serversDir };
+ const starts = new Map(), failures = new Map();
+ let records = { at: 0, list: [] }, registered = { at: 0, list: [] }, started;
+
+ async function list(force = false) {
+  if (force || Date.now() - registered.at > 1000) registered = { at: Date.now(), list: (await readDoorState(doorEnv))?.sites ?? [] };
+  return registered.list;
+ }
+ async function running(force = false) {
+  if (force || Date.now() - records.at > 1000) {
+   const live = await liveServers(serverEnv);
+   records = { at: Date.now(), list: await Promise.all(live.map(async record => ({ ...record, ready: await serverReady(record) }))) };
+  }
+  return records.list;
+ }
+ // Generations of the servers this door started (kept in the door state, so
+ // they survive a door restart); only those may be stopped for capacity. A
+ // draining door waits for its starts under way to record theirs (busy()).
+ async function doorStarted() {
+  started ??= new Set((await readDoorState(doorEnv))?.door?.started ?? []);
+  return started;
+ }
+ // Liveness is read inside the state change, so a concurrent start's
+ // generation, recorded a moment earlier, is never dropped as dead.
+ async function remember(generation) {
+  await changeDoorState(doorEnv, async state => {
+   const live = new Set((await liveServers(serverEnv)).map(record => record.generation));
+   state.door.started = [...new Set([...(state.door.started ?? []), generation])].filter(item => live.has(item));
+   started = new Set(state.door.started);
+  });
+ }
+
+ async function view(site, { force = false } = {}) {
+  const record = (await running(force)).find(item => item.checkout === site.checkout);
+  const doorUrl = doorOrigin(site.name, door.port);
+  const result = { name: site.name, path: site.checkout, mode: record ? (record.door || doorSite(record.url) ? 'door' : 'direct') : site.mode === 'door' ? 'door' : 'direct', doorUrl };
+  if (record?.door && record.door.v !== doorProtocol) return { ...result, state: 'failed', url: doorUrl, reason: `This checkout's server speaks door protocol ${record.door.v}; restart the door with the installed rer (rer door restart).` };
+  // A door-mode server is routable once it has recorded its proxy and is ready.
+  if (record?.ready && (record.door ? record.port : record.url && !doorSite(record.url))) {
+   return { ...result, state: 'running', url: record.url, ...(record.door ? { proxyPort: record.port, secret: record.door.secret } : {}), record };
+  }
+  if (starts.has(site.name) || record) return { ...result, state: 'starting', url: result.mode === 'door' ? doorUrl : site.origin ?? doorUrl };
+  const failure = failures.get(site.name);
+  if (failure && Date.now() - failure.at < failureShownMs) return { ...result, state: 'failed', reason: failure.reason, url: doorUrl };
+  return { ...result, state: 'stopped', url: result.mode === 'door' ? doorUrl : site.origin ?? doorUrl };
+ }
+
+ async function runLauncher(args, site, logPath) {
+  const handle = await open(logPath, 'a', 0o600), from = (await handle.stat()).size;
+  let child, exited;
+  try { child = spawn(process.execPath, [rerEntry, ...args], { cwd: site.checkout, env: siteEnvironment(door, env), detached: true, stdio: ['ignore', handle.fd, handle.fd] }); exited = exitOf(child); }
+  finally { await handle.close(); }
+  const timer = setTimeout(() => { try { process.kill(-child.pid, 'SIGTERM'); } catch {} }, startTimeoutMs);
+  const { code, error } = await exited;
+  clearTimeout(timer);
+  return { code, from, error };
+ }
+ const launchFailure = async (site, logPath, { from, error }) => error ? `rer could not run in ${site.checkout}: ${error.code ?? error.message}.` : failureReason(logPath, from);
+
+ // A checkout whose folder was moved, renamed or deleted cannot start: say so
+ // before admission, so nothing is stopped to make room for it.
+ async function present(site) {
+  const folder = await stat(site.checkout).catch(() => undefined);
+  if (!folder?.isDirectory()) throw Error(`The checkout folder ${site.checkout} no longer exists, so ${site.name} was not started. If it moved, run rer dev in its new folder (or rer door add NEW_PATH): it keeps the name ${site.name}, its address and its sign-in. Otherwise unregister it with rer door remove ${site.name}.`);
+ }
+
+ // Admission is serial. Each start in turn counts the servers running, the
+ // starts already admitted and the servers already being stopped for one, then
+ // takes a free slot, or stops this door's own least recently active server
+ // that no other start is stopping (never one someone started with rer dev),
+ // or is refused naming what holds the cap. So concurrent visits (a browser
+ // restoring many tabs) each get their own slot or a clear refusal, and never
+ // stop the same server twice and then fail at the limit.
+ const admitted = new Set(), evicting = new Set();
+ let admission = Promise.resolve();
+ function admit(site) {
+  const turn = admission.then(() => reserve(site));
+  admission = turn.catch(() => {});
+  return turn;
+ }
+ async function reserve(site) {
+  const live = (await running(true)).filter(record => !record.journey && record.checkout !== site.checkout);
+  const cap = Math.min(door.policy.serverLimit, ...live.filter(record => record.explicit).map(record => record.limit));
+  const staying = live.filter(record => !evicting.has(record.generation)), liveCheckouts = new Set(live.map(record => record.checkout));
+  const starting = [...admitted].filter(checkout => checkout !== site.checkout && !liveCheckouts.has(checkout));
+  if (staying.length + starting.length < cap) { admitted.add(site.checkout); return undefined; }
+  const mine = await doorStarted();
+  const victim = staying.filter(record => mine.has(record.generation) && !admitted.has(record.checkout)).sort((a, b) => (a.lastActivity ?? 0) - (b.lastActivity ?? 0))[0];
+  if (!victim) throw Error([
+   `The server limit is ${cap}, and every place is held by a server someone started with rer dev or by a start already under way, so none was stopped for ${site.name}:`,
+   ...staying.map(record => `  ${record.mode} for ${record.checkout} (PID ${record.owner?.pid})${admitted.has(record.checkout) ? ', starting for another visit' : ', started with rer dev'}`),
+   ...starting.map(checkout => `  starting ${checkout} for another visit`),
+   'Stop one with rer dev --stop in its checkout, or raise the limit with rer door enable --server-limit N.',
+  ].join('\n'));
+  evicting.add(victim.generation); admitted.add(site.checkout);
+  return victim;
+ }
+ async function evict(victim, site) {
+  try {
+   const owner = (await list()).find(item => item.checkout === victim.checkout) ?? { checkout: victim.checkout, name: 'evicted' };
+   log(`stopping ${victim.checkout} (least recently active door-started server) to make room for ${site.name}`);
+   const logPath = join(door.directory, 'logs', `${owner.name}.log`), run = await runLauncher([victim.mode, '--stop', '--cwd', victim.checkout], owner, logPath);
+   if (run.code !== 0) throw Error(`The server limit is reached, and stopping ${victim.checkout} to make room failed: ${await launchFailure(owner, logPath, run)}`);
+   await running(true);
+  } finally { evicting.delete(victim.generation); }
+ }
+
+ async function start(site) {
+  const logPath = join(door.directory, 'logs', `${site.name}.log`);
+  let reserved = false;
+  try {
+   await present(site);
+   const victim = await admit(site);
+   reserved = true;
+   if (victim) await evict(victim, site);
+   log(`starting ${site.name} (${site.checkout})`);
+   const run = await runLauncher(['dev', '--cwd', site.checkout, '--detach', '--json', '--door-start'], site, logPath);
+   if (run.code !== 0) throw Error(await launchFailure(site, logPath, run));
+   const record = (await running(true)).find(item => item.checkout === site.checkout);
+   if (!record) throw Error('The site reported ready but is not in the server registry.');
+   await remember(record.generation);
+   failures.delete(site.name);
+   log(`${site.name} is running`);
+  } catch (error) {
+   failures.set(site.name, { at: Date.now(), reason: error.message });
+   log(`${site.name} did not start: ${error.message.split('\n')[0]}`);
+  } finally { if (reserved) admitted.delete(site.checkout); starts.delete(site.name); records.at = 0; }
+ }
+
+ return {
+  list, view, running,
+  async views() { return Promise.all((await list()).map(site => view(site))); },
+  // Begin a start unless one is already under way.
+  ensureStarted(site) {
+   if (!starts.has(site.name)) { failures.delete(site.name); starts.set(site.name, start(site)); }
+   return starts.get(site.name);
+  },
+  invalidate() { records.at = 0; },
+  busy() { return starts.size > 0; },
+  // The names of the sites starting now (handed to the next door on a restart).
+  pending() { return [...starts.keys()]; },
+ };
+}