@runeditrun/rer 0.1.0 → 0.1.1

package/README.md

@@ -117,7 +117,10 @@ override the choice, and `--json` prints `progress` events and the ready event.
 first launch can take minutes: it prints a progress line at least every 30
 seconds, and if the calling command is killed the launch carries on; run
 `rer dev` again to reattach. A second `rer dev` reprints the ready lines.
-`rer dev --stop` stops the server.
+`rer dev --stop` stops the server, or a launch still preparing (which then
+reports that it was stopped), waits until every process they started has
+exited and says what it stopped; if any is still running it exits non-zero
+naming their PIDs.
 
 Servers started through `rer` (`rer dev`, `rer preview`) get a 10-server limit and a 12-hour idle timeout
 unless you set `RER_SERVER_LIMIT`, `RER_SERVER_IDLE_SECONDS` or `--idle-timeout`.

package/cli/server-registry.mjs

@@ -167,11 +167,16 @@ export async function serverRegistry(root,{env=process.env,memory=availableMemor
   throw refuse('The existing server is still starting. Wait for its ready output.');
  }
  return {checkout,existing,stop,reserve,serve,update,updateActivity,waitReady,custodyToken:()=>owned?.token,
+  // The sockets close even when the record cannot be removed (its registry
+  // deleted under it, say): an open listener would keep this process alive.
   close(){return closing??=(async()=>{
-   if(owned)await change(state=>{state.running=state.running.filter(item=>item.generation!==owned.generation);});
-   if(control)await new Promise(resolve=>control.close(resolve));
-   if(owned)await unlink(owned.control).catch(error=>{if(error.code!=='ENOENT')throw error;});
-   await lifetime.close();
+   try{if(owned)await change(state=>{state.running=state.running.filter(item=>item.generation!==owned.generation);});}
+   finally{
+    try{
+     if(control)await new Promise(resolve=>control.close(resolve));
+     if(owned)await unlink(owned.control).catch(error=>{if(error.code!=='ENOENT')throw error;});
+    }finally{await lifetime.close();}
+   }
   })();}
  };
 }

package/global/README.md

@@ -117,7 +117,10 @@ override the choice, and `--json` prints `progress` events and the ready event.
 first launch can take minutes: it prints a progress line at least every 30
 seconds, and if the calling command is killed the launch carries on; run
 `rer dev` again to reattach. A second `rer dev` reprints the ready lines.
-`rer dev --stop` stops the server.
+`rer dev --stop` stops the server, or a launch still preparing (which then
+reports that it was stopped), waits until every process they started has
+exited and says what it stopped; if any is still running it exits non-zero
+naming their PIDs.
 
 Servers started through `rer` (`rer dev`, `rer preview`) get a 10-server limit and a 12-hour idle timeout
 unless you set `RER_SERVER_LIMIT`, `RER_SERVER_IDLE_SECONDS` or `--idle-timeout`.

package/global/launch/dev.mjs

@@ -10,13 +10,13 @@ import { open, realpath, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { processInfo } from '../../modules/job-queue/processes.mjs';
 import { dispatcher } from '../checkout.mjs';
 import { delegate } from '../delegate.mjs';
 import { ownRoot } from '../package-info.mjs';
 import { LaunchFailure } from './failure.mjs';
 import { prepare } from './prepare.mjs';
 import { printer } from './render.mjs';
+import { stopLaunch } from './stop.mjs';
 import { launchDirectory, liveWorker } from './state.mjs';
 
 const workerPath = fileURLToPath(new URL('./worker.mjs', import.meta.url));
@@ -30,8 +30,8 @@ export async function launchDev(target) {
  if (!await accepted(target.root, devArgs)) return delegate(target, ['dev', ...devArgs]);
  const checkout = await realpath(target.root), directory = await launchDirectory(checkout);
  if (devArgs.includes('--stop')) {
-  try { await stopWorker(directory); } catch (failure) { process.stderr.write(failure.message + '\n'); return failure.exitCode ?? 1; }
-  return delegate(target, ['dev', ...devArgs]);
+  try { return await stopLaunch(target, devArgs, { checkout, directory }); }
+  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)}`}` });
@@ -69,7 +69,8 @@ async function detached(target, devArgs, directory, out) {
  if (holder) { token = holder.token; out.attaching(holder.startedAt); }
  else {
   token = randomUUID();
-  worker = spawn(process.execPath, [workerPath, target.root, token, JSON.stringify(devArgs.filter(arg => arg !== '--json'))], { cwd: target.root, env: process.env, detached: true, stdio: 'ignore' });
+  // 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.unref();
  }
  return follow(directory, token, out, { worker });
@@ -114,16 +115,3 @@ function missing(directory) {
  process.stderr.write(`rer dev: the launch stopped before it finished. Run rer dev again; its log is ${join(directory, 'launch.log')}.\n`);
  return 1;
 }
-
-// rer dev --stop also ends a preparation still running for this checkout.
-async function stopWorker(directory) {
- const holder = await liveWorker(directory);
- if (!holder) return;
- try { process.kill(holder.pid, 'SIGTERM'); } catch (error) { if (error.code === 'ESRCH') return; throw error; }
- for (let waited = 0; waited < 60000; waited += 250) {
-  const current = await processInfo(holder.pid);
-  if (!current || current.zombie || current.start !== holder.start) return;
-  await delay(250);
- }
- throw new LaunchFailure(1, `The launch worker (PID ${holder.pid}) did not stop within a minute.`);
-}

package/global/launch/facts.mjs

@@ -11,11 +11,12 @@ const run = promisify(execFile);
 async function mtime(path) { try { return (await stat(path)).mtimeMs; } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; } }
 
 // The pinned dispatcher's own read-only description.
-export async function describeCheckout(root, entry, env) {
+export async function describeCheckout(root, entry, env, signal) {
  try {
-  const { stdout } = await run(process.execPath, [entry, 'describe', '--json'], { cwd: root, env, maxBuffer: 16 * 1024 * 1024 });
+  const { stdout } = await run(process.execPath, [entry, 'describe', '--json'], { cwd: root, env, maxBuffer: 16 * 1024 * 1024, signal });
   return JSON.parse(stdout);
  } catch (error) {
+  if (signal?.aborted) throw signal.reason;
   throw new LaunchFailure(error.code ?? 1, (error.stderr?.trim() || `rer describe failed in ${root}.`));
  }
 }

package/global/launch/prepare.mjs

@@ -16,16 +16,18 @@ import { localDefaults } from './local-defaults.mjs';
 // The value given for a flag in the user's dev arguments.
 export const flagValue = (args, flag) => { const index = args.indexOf(flag); return index < 0 ? undefined : args[index + 1]; };
 
-export async function prepare({ root, args, env, report, directory, log, children }) {
+// A worker passes the signal a stop aborts: no step starts after it, and the
+// step running then is signalled through `children`.
+export async function prepare({ root, args, env, report, directory, log, children, signal }) {
  const checkout = await realpath(root), { mode, entry } = dispatcher(root);
- const described = await describeCheckout(root, entry, env);
+ const described = await describeCheckout(root, entry, env, signal);
  const pin = await pinPolicy(root, mode, described);
  const added = personEnvironment(env, args, pin), childEnv = { ...env, ...added };
  report({ phase: 'check', message: 'checking the server limit' });
  const capacity = await checkCapacity(checkout, childEnv, pin);
  if (capacity.own) return { entry, added, own: capacity.own };
  const note = message => report({ phase: 'note', message });
- const step = (record, args, fields, env = childEnv) => recorded(directory, record, () => runVerb(entry, args, { root, env, note, log, children }), fields);
+ const step = (record, args, fields, env = childEnv) => recorded(directory, record, () => runVerb(entry, args, { root, env, note, log, children, signal }), fields);
  // Only this setup fills the seed's declared local defaults.
  const setupEnv = { ...childEnv, [localDefaults]: '1' };
  if (await needsInstall(root, await installState.read(directory))) {

package/global/launch/state.mjs

@@ -6,7 +6,8 @@
 //   setup.json    whether a setup this launcher started has finished
 //   launch.log    the worker's private log (child output)
 //   server.log    the private log of the server rer started
-//   server.json   that server's PID
+//   server.json   that server's PID and start time, and the process rer spawned
+//   stop.json     when rer dev --stop last ran: a launch requested before it stops
 import { createHash } from 'node:crypto';
 import { appendFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
@@ -91,6 +92,14 @@ const stepRecord = name => ({
 });
 export const installState = stepRecord('install'), setupState = stepRecord('setup');
 
+// A stop asks every launch started before it to end. A worker reads this right
+// after it claims the launch; a stop that ran before the claim found no worker
+// to signal, so the worker ends itself here instead of starting anything.
+export const stopRequest = {
+ write: directory => writeFile(join(directory, 'stop.json'), JSON.stringify({ at: Date.now(), pid: process.pid }), { mode: 0o600 }),
+ covers: async (directory, requestedAt) => ((await readJson(join(directory, 'stop.json')))?.at ?? -Infinity) >= requestedAt,
+};
+
 export const serverRecord = {
  read: directory => readJson(join(directory, 'server.json')),
  write: (directory, record) => writeFile(join(directory, 'server.json'), JSON.stringify(record), { mode: 0o600 }),

package/global/launch/steps.mjs

@@ -21,10 +21,18 @@ export function failureFrom(code, error, output) {
  return new LaunchFailure(code || 1, error?.message ?? (output.trim().split('\n').slice(-5).join('\n') || `The command stopped with exit ${code}.`), error);
 }
 
+// A child joins the set a stop signals; one spawned as the stop arrives is
+// signalled at once rather than left to finish.
+function own(children, child, signal) {
+ children.add(child);
+ if (signal?.aborted) child.kill('SIGTERM');
+}
+
 // One bounded verb, never prompting: no stdin, --non-interactive, --json.
-export async function runVerb(entry, args, { root, env, note, log, children }) {
+export async function runVerb(entry, args, { root, env, note, log, children, signal }) {
+ signal?.throwIfAborted();
  const child = spawn(process.execPath, [entry, ...args, '--json', '--non-interactive'], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] });
- children.add(child);
+ own(children, child, signal);
  let error, output = '';
  const lines = createInterface({ input: child.stdout });
  lines.on('line', line => { const event = events(line); if (event?.event === 'error') error = event; const text = event && waitingNote(event); if (text) note(text); log(line); });
@@ -55,14 +63,15 @@ async function follow(path, from, onLine, stopped) {
 // Start `dev` detached into its own process group with its output in a private
 // log, and return its ready event once it prints one. The server outlives this
 // process and stops on rer dev --stop or its idle timeout.
-export async function startServer(entry, args, { root, env, logPath, children }) {
+export async function startServer(entry, args, { root, env, logPath, children, signal }) {
+ signal?.throwIfAborted();
  const handle = await open(logPath, 'a', 0o600), from = (await handle.stat()).size;
  let child;
  try { child = spawn(process.execPath, [entry, 'dev', ...args, '--json'], { cwd: root, env, detached: true, stdio: ['ignore', handle.fd, handle.fd] }); }
  finally { await handle.close(); }
- children.add(child);
+ own(children, child, signal);
  let exit, ready, error, output = '';
- child.once('exit', (code, signal) => { exit = code ?? (signal ? 128 : 1); });
+ child.once('exit', (code, name) => { exit = code ?? (name ? 128 : 1); });
  await follow(logPath, from, line => {
   const event = events(line);
   if (event?.event === 'ready') { ready = event; return true; }

package/global/launch/stop.mjs

@@ -0,0 +1,89 @@
+// rer dev --stop for a checkout the launcher may be preparing or serving.
+// It ends a launch still preparing (or one that has not yet claimed the
+// checkout), has the pinned dispatcher stop the registered server, and then
+// checks that every process it found -- the worker, the server rer started,
+// the registered server and everything they spawned -- has exited. It says
+// what it stopped, or exits non-zero naming what is still running.
+import { setTimeout as delay } from 'node:timers/promises';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
+import { readProcessTable, sameBirth } from '../../onboarding/process-table.mjs';
+import { delegate } from '../delegate.mjs';
+import { liveServers } from '../registry.mjs';
+import { LaunchFailure } from './failure.mjs';
+import { liveWorker, serverRecord, stopRequest } from './state.mjs';
+
+export async function stopLaunch(target, devArgs, { checkout, directory }) {
+ // Written before looking for a worker: one that claims the launch after this
+ // look reads it and ends itself (worker.mjs).
+ await stopRequest.write(directory);
+ const holder = await liveWorker(directory);
+ const launch = holder ? await tree([holder]) : [];
+ if (holder) await endWorker(holder);
+ // Only now: a worker stopped while its server came up has registered it.
+ const record = (await liveServers()).find(item => item.checkout === checkout);
+ const started = await serverRecord.read(directory);
+ const server = await tree([record?.owner, record?.runtimeProcess, started, started?.spawned]);
+ await delegate(target, ['dev', ...devArgs]);
+ if (process.exitCode) return process.exitCode;
+ const left = await exited([...launch, ...server], 15000);
+ if (left.length) {
+  const pids = left.map(item => item.pid).join(' ');
+  process.stderr.write(`rer dev --stop: ${left.length === 1 ? 'a process' : `${left.length} processes`} of this checkout's dev server ${left.length === 1 ? 'is' : 'are'} still running 15 seconds after the stop (PID ${pids}). Stop ${left.length === 1 ? 'it' : 'them'} with kill -TERM ${pids}, then run rer dev --stop again.\n`);
+  return 1;
+ }
+ if (!devArgs.includes('--json')) process.stdout.write(said({ checkout, record, started, server, holder, launch }) + '\n');
+ return 0;
+}
+
+// SIGTERM the preparing worker and wait for it to exit.
+async function endWorker(holder) {
+ try { process.kill(holder.pid, 'SIGTERM'); } catch (error) { if (error.code === 'ESRCH') return; throw error; }
+ for (let waited = 0; waited < 60000; waited += 250) {
+  const current = await processInfo(holder.pid);
+  if (!current || current.zombie || current.start !== holder.start) return;
+  await delay(250);
+ }
+ throw new LaunchFailure(1, `The launch worker (PID ${holder.pid}) did not stop within a minute.`);
+}
+
+// The live processes among these recorded identities ({pid, start}), with
+// every process descended from them, as process-table entries.
+async function tree(identities) {
+ const roots = new Set();
+ for (const identity of identities) {
+  if (!identity?.pid || !identity.start) continue;
+  const current = await processInfo(identity.pid);
+  if (current && !current.zombie && current.start === identity.start) roots.add(identity.pid);
+ }
+ if (!roots.size) return [];
+ const table = await readProcessTable(), found = table.filter(entry => roots.has(entry.pid));
+ for (let index = 0; index < found.length; index++) {
+  for (const entry of table) if (entry.ppid === found[index].pid && !found.includes(entry)) found.push(entry);
+ }
+ return found;
+}
+
+// Wait until none of these processes is running; return those still running.
+async function exited(processes, within) {
+ const deadline = Date.now() + within;
+ for (;;) {
+  const table = processes.length ? await readProcessTable() : [];
+  const left = processes.filter(item => table.some(entry => sameBirth(item, entry) && !entry.state.startsWith('Z')));
+  if (!left.length || Date.now() >= deadline) return left;
+  await delay(250);
+ }
+}
+
+function said({ checkout, record, started, server, holder, launch }) {
+ const lines = [], more = n => n > 0 ? ` with ${n} more ${n === 1 ? 'process' : 'processes'}` : '';
+ if (server.length) {
+  const pid = record?.owner?.pid ?? started?.pid ?? server[0].pid;
+  lines.push(`Stopped the dev server${record?.url ? ` at ${record.url}` : ''} for ${checkout} (PID ${pid})${more(server.length - 1)}.`);
+ }
+ if (holder) {
+  const own = launch.filter(item => !server.some(entry => sameBirth(item, entry)));
+  lines.push(`Stopped the launch still running for ${checkout} (PID ${holder.pid})${more(own.length - 1)}.`);
+ }
+ if (!lines.length) lines.push(`No dev server was running for ${checkout}.`);
+ return lines.join('\n');
+}

package/global/launch/worker.mjs

@@ -1,41 +1,60 @@
-// The detached launch worker: node worker.mjs ROOT TOKEN ARGS_JSON
+// The detached launch worker: node worker.mjs ROOT TOKEN ARGS_JSON REQUESTED_AT
+// (REQUESTED_AT: when the `rer dev` that spawned it started, epoch ms).
 // It runs in its own session, so killing the `rer dev` that started it (or that
 // command's whole process group) leaves it running; a rerun attaches to it.
+// rer dev --stop ends it: SIGTERM, or, for a stop that ran before this worker
+// claimed the launch, the stop request it reads right after claiming. Either
+// way no further step starts, the running one is signalled, and the launch
+// reports that it was stopped instead of ready.
 import { createWriteStream } from 'node:fs';
 import { realpath } from 'node:fs/promises';
 import { join } from 'node:path';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
 import { liveServers } from '../registry.mjs';
+import { LaunchFailure } from './failure.mjs';
 import { prepare } from './prepare.mjs';
-import { claimLaunch, eventLog, launchDirectory, liveWorker, releaseLaunch, serverRecord } from './state.mjs';
+import { claimLaunch, eventLog, launchDirectory, liveWorker, releaseLaunch, serverRecord, stopRequest } from './state.mjs';
 import { startServer } from './steps.mjs';
 
-const [root, token, argsJSON] = process.argv.slice(2), args = JSON.parse(argsJSON);
+const [root, token, argsJSON, requestedAtText] = process.argv.slice(2), args = JSON.parse(argsJSON), requestedAt = Number(requestedAtText);
 const checkout = await realpath(root), directory = await launchDirectory(checkout), events = eventLog(directory, token);
+// Listening before the claim: a stop may signal this worker as soon as it is the holder.
+const children = new Set(), stopping = new AbortController();
+const stop = () => { stopping.abort(); for (const child of children) child.kill('SIGTERM'); };
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, stop);
+process.on('SIGHUP', () => {});
 if (!await claimLaunch(directory, token)) {
  const holder = await liveWorker(directory);
  await events.write({ event: 'redirect', token: holder?.token });
 } else {
  const logFile = createWriteStream(join(directory, 'launch.log'), { flags: 'a', mode: 0o600 });
  const log = text => logFile.write(text + '\n');
- const children = new Set();
- for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { for (const child of children) child.kill('SIGTERM'); });
- process.on('SIGHUP', () => {});
  try {
-  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children });
+  if (await stopRequest.covers(directory, requestedAt)) stop();
+  stopping.signal.throwIfAborted();
+  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children, signal: stopping.signal });
   await events.write({ event: 'phase', phase: 'start', message: prepared.own ? 'the app is already running; checking it' : 'starting the app' });
   // A server rer started logs to server.log; asking a running one for its
   // ready lines goes to reuse.log, and names server.log only when rer started it.
   const serverLog = join(directory, 'server.log');
-  const started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children });
+  let started;
+  try { started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children, signal: stopping.signal }); }
+  finally { await prepared.release?.(); }
   const record = (await liveServers(process.env)).find(item => item.checkout === checkout);
-  await prepared.release?.();
   const pid = record?.owner?.pid ?? started.pid;
-  if (!prepared.own) await serverRecord.write(directory, { pid });
+  // The server's PID, and the process rer spawned for it (the same one unless
+  // the pin re-runs itself under its own Node), each with its start time.
+  const identity = async id => ({ pid: id, start: (await processInfo(id))?.start });
+  if (!prepared.own) await serverRecord.write(directory, { ...await identity(pid), spawned: await identity(started.pid) });
   const ours = !prepared.own || (await serverRecord.read(directory))?.pid === pid;
+  // A stop that arrived while the server came up finds it registered and
+  // stops it; this launch reports the stop rather than a server about to end.
+  stopping.signal.throwIfAborted();
   await events.write({ event: 'ready', ready: started.ready, pid, ...(ours ? { log: serverLog } : {}) });
  } catch (error) {
   log(String(error?.stack ?? error));
-  await events.write({ event: 'failed', exitCode: error.exitCode ?? 1, message: error.exitCode ? error.message : `The launch failed unexpectedly; see ${join(directory, 'launch.log')}.`, ...(error.event ? { error: error.event } : {}) });
+  const failure = stopping.signal.aborted ? new LaunchFailure(1, 'rer dev --stop stopped this launch before the app was ready.') : error;
+  await events.write({ event: 'failed', exitCode: failure.exitCode ?? 1, message: failure.exitCode ? failure.message : `The launch failed unexpectedly; see ${join(directory, 'launch.log')}.`, ...(failure.event ? { error: failure.event } : {}) });
  } finally {
   await releaseLaunch(directory, token);
   logFile.end();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runeditrun/rer",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The rer command: install, set up, run and launch Run Edit Run checkouts.",
   "license": "MIT",
   "type": "module",