@runeditrun/rer 0.1.1 → 0.2.1

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()]; },
+ };
+}

package/global/launch/dev.mjs

@@ -14,6 +14,7 @@ import { dispatcher } from '../checkout.mjs';
 import { delegate } from '../delegate.mjs';
 import { ownRoot } from '../package-info.mjs';
 import { LaunchFailure } from './failure.mjs';
+import { describeCheckout } from './facts.mjs';
 import { prepare } from './prepare.mjs';
 import { printer } from './render.mjs';
 import { stopLaunch } from './stop.mjs';
@@ -24,7 +25,14 @@ const workerPath = fileURLToPath(new URL('./worker.mjs', import.meta.url));
 export async function launchDev(target) {
  const args = target.args.slice(1);
  if (args.includes('--detach') && args.includes('--foreground')) { process.stderr.write('Choose one of --detach and --foreground.\n'); return 2; }
- const devArgs = args.filter(arg => arg !== '--detach' && arg !== '--foreground');
+ // --door-start: the front door is starting this checkout (internal).
+ const doorStart = args.includes('--door-start');
+ const devArgs = args.filter(arg => !['--detach', '--foreground', '--door-start'].includes(arg));
+ // A pin from before the front door cannot move to it: say so in one line.
+ if ((devArgs.includes('--door') || devArgs.includes('--direct')) && !await doorCapable(target.root)) {
+  process.stderr.write('This checkout\'s pinned Base has no front-door support, so it stays direct. Refresh its Base to serve it through the door; rer door add still lists it and starts it on a visit.\n');
+  return 2;
+ }
  // An invocation the pinned dispatcher refuses goes straight to it, so the
  // refusal is its own, with nothing prepared first.
  if (!await accepted(target.root, devArgs)) return delegate(target, ['dev', ...devArgs]);
@@ -34,9 +42,13 @@ export async function launchDev(target) {
   catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; process.stderr.write(failure.message + '\n'); return failure.exitCode; }
  }
  const here = await realpath(process.cwd()).catch(() => undefined);
- const out = printer({ json: devArgs.includes('--json'), login: devArgs.includes('--login'), stopHint: `rer dev --stop${here === checkout ? '' : ` --cwd ${JSON.stringify(checkout)}`}` });
+ const out = printer({ json: devArgs.includes('--json'), login: devArgs.includes('--login'), stopHint: `rer dev --stop${here === checkout ? '' : ` --cwd ${JSON.stringify(checkout)}`}`, keyless: doorStart });
  const detach = args.includes('--detach') || (!args.includes('--foreground') && !process.stdout.isTTY);
- return detach ? detached(target, devArgs, directory, out) : foreground(target, devArgs, directory, out);
+ return detach ? detached(target, devArgs, directory, out, doorStart) : foreground(target, devArgs, directory, out, doorStart);
+}
+
+async function doorCapable(root) {
+ try { return Boolean((await describeCheckout(root, dispatcher(root).entry, process.env)).door); } catch { return true; }
 }
 
 async function accepted(root, devArgs) {
@@ -45,7 +57,7 @@ async function accepted(root, devArgs) {
  try { (await import(pathToFileURL(parser).href)).parse(['dev', ...devArgs], process.cwd()); return true; } catch { return false; }
 }
 
-async function foreground(target, devArgs, directory, out) {
+async function foreground(target, devArgs, directory, out, doorStart) {
  const holder = await liveWorker(directory);
  if (holder) {
   out.attaching(holder.startedAt);
@@ -56,21 +68,22 @@ async function foreground(target, devArgs, directory, out) {
  let prepared;
  // The same progress lines as a detached launch while install or setup runs.
  const heartbeat = setInterval(() => out.heartbeat(), 1000);
- try { prepared = await prepare({ root: target.root, args: devArgs, env: process.env, report: fields => out.phase(fields), directory, log: text => log.write(text + '\n'), children: new Set() }); }
+ try { prepared = await prepare({ root: target.root, args: devArgs, env: process.env, report: fields => out.phase(fields), directory, log: text => log.write(text + '\n'), children: new Set(), doorStart }); }
  catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; out.failure(failure); return failure.exitCode; }
  finally { clearInterval(heartbeat); log.end(); }
  Object.assign(process.env, prepared.added);
  return delegate(target, ['dev', ...devArgs]);
 }
 
-async function detached(target, devArgs, directory, out) {
+async function detached(target, devArgs, directory, out, doorStart) {
  let token, worker;
  const holder = await liveWorker(directory);
  if (holder) { token = holder.token; out.attaching(holder.startedAt); }
  else {
   token = randomUUID();
   // The worker ends itself for a stop that ran after this command started.
-  worker = spawn(process.execPath, [workerPath, target.root, token, JSON.stringify(devArgs.filter(arg => arg !== '--json')), String(performance.timeOrigin)], { cwd: target.root, env: process.env, detached: true, stdio: 'ignore' });
+  worker = spawn(process.execPath, [workerPath, target.root, token, JSON.stringify(devArgs.filter(arg => arg !== '--json')), String(performance.timeOrigin), ...(doorStart ? ['door-start'] : [])], { cwd: target.root, env: process.env, detached: true, stdio: 'ignore' });
+  worker.once('error', () => {});
   worker.unref();
  }
  return follow(directory, token, out, { worker });
@@ -82,6 +95,7 @@ async function follow(directory, token, out, { worker, quiet = false }) {
  const path = join(directory, `events-${token}.jsonl`);
  let offset = 0, rest = '', exited = false, missingSince, polls = 0;
  worker?.once('exit', () => { exited = true; });
+ worker?.once('error', () => { exited = true; });
  for (;;) {
   let size = 0;
   try { size = (await stat(path)).size; } catch (error) { if (error.code !== 'ENOENT') throw error; }

package/global/launch/door.mjs

@@ -0,0 +1,36 @@
+// What the front door means for one `rer dev`. With the door enabled, a fresh
+// checkout whose pin supports it is set up at its door origin; a checkout
+// already there needs the door running, which `rer dev` brings back only for
+// the registry the door recorded (a fleet agent or a test with its own
+// RER_DOOR_DIR or RER_SERVERS_DIR never starts the owner's door). --port,
+// --host and --direct always mean direct mode.
+import { doorProtocol, doorSite, readDoorState, runningDoor } from '../../cli/door.mjs';
+import { startDoor } from '../door/control.mjs';
+import { ownsRegistry } from '../door/policy.mjs';
+import { LaunchFailure } from './failure.mjs';
+
+const has = (args, flag) => args.includes(flag);
+
+export async function doorPlan(described, args, env) {
+ const capable = described?.door?.protocol === doorProtocol;
+ const direct = has(args, '--direct') || has(args, '--port') || has(args, '--host');
+ const state = await readDoorState(env).catch(() => undefined), door = state?.door;
+ const running = door?.enabled ? await runningDoor(env).catch(() => undefined) : undefined;
+ const protocol = running?.protocol ?? door?.protocol;
+ const known = Boolean(door?.enabled) && protocol === doorProtocol;
+ const note = door?.enabled && !known ? `The front door speaks protocol ${protocol}, which this rer does not know, so this checkout stays direct. Run rer door restart.` : undefined;
+ const saved = Boolean(described?.local?.origin && doorSite(described.local.origin));
+ return { door, known, note, freshAtDoor: known && capable && !direct, atDoor: !direct && (saved || has(args, '--door')) };
+}
+
+// Bring an enabled door back before a door-mode checkout starts.
+export async function bringBackDoor(plan, env, report) {
+ if (!plan.atDoor || !plan.door?.enabled || !plan.known) return;
+ if (await runningDoor(env)) return;
+ if (!ownsRegistry(plan.door, env)) {
+  report({ phase: 'note', message: 'the front door is not running and this shell uses another RER_DOOR_DIR or RER_SERVERS_DIR than the one it recorded, so it was not started' });
+  return;
+ }
+ report({ phase: 'door', message: 'starting the front door (it was not running)' });
+ try { await startDoor(env); } catch (error) { throw new LaunchFailure(error.exitCode ?? 1, error.message); }
+}

package/global/launch/install-pinned.mjs

@@ -0,0 +1,22 @@
+// A checkout that pins the @runeditrun/rer package runs its own rer once
+// node_modules holds the pinned version; until then none of it can run (its
+// adapter imports the package). So its first dependency install is this
+// launcher's: the frozen pnpm install that `rer install` runs.
+import { spawn } from 'node:child_process';
+import { pinnedPackage } from '../checkout.mjs';
+import { packageName } from '../package-info.mjs';
+import { LaunchFailure } from './failure.mjs';
+
+export async function installPinned(root, { env = process.env, output = text => process.stderr.write(text), children, signal } = {}) {
+ signal?.throwIfAborted();
+ const child = spawn('pnpm', ['install', '--frozen-lockfile'], { cwd: root, env: { ...env, CI: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
+ children?.add(child);
+ if (signal?.aborted) child.kill('SIGTERM');
+ let tail = '';
+ for (const stream of [child.stdout, child.stderr]) stream.on('data', data => { tail = (tail + data).slice(-4096); output(String(data)); });
+ const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('close', (exit, name) => resolve(exit ?? (name ? 128 : 1))); });
+ children?.delete(child);
+ if (code !== 0) throw new LaunchFailure(code, `pnpm install --frozen-lockfile failed in ${root} (exit ${code}):\n${tail.trim().split('\n').slice(-8).join('\n')}`);
+ const pinned = pinnedPackage(root);
+ if (!pinned?.ready) throw new LaunchFailure(3, `${root} pins ${packageName} ${pinned?.declared}, but after pnpm install node_modules holds ${pinned?.installed ?? 'no copy of it'}. Correct the pin or the lockfile (pnpm install), then run rer again.`);
+}