@vantran-se/openchamber-web 2.0.4 → 2.0.5

package/server/lib/spaces/routes.test.js

@@ -0,0 +1,213 @@
+// The routes over a stand-in journey: the shapes, the statuses per refusal, and the switch.
+
+import http from 'node:http';
+
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { SpaceError } from './errors.js';
+import { SPACES_ROUTE, answerFailure, createSwitchController, registerSpaceRoutes } from './routes.js';
+
+const ID = 'a1b2c3d4e5f6';
+const servers = [];
+
+afterEach(async () => {
+  for (const server of servers.splice(0)) await new Promise((resolve) => server.close(() => resolve()));
+});
+
+/** An app with the routes over `journey`, or with the feature off when `journey` is null. */
+const serve = async ({ journey, places = [], switchState = { enabled: true } } = {}) => {
+  const app = express();
+  app.use(express.json());
+  const calls = [];
+  const state = { journey, enabled: switchState.enabled };
+  registerSpaceRoutes(app, {
+    getJourney: () => state.journey,
+    getPlaces: () => places,
+    readSwitch: async () => ({ enabled: state.enabled, spaces: state.enabled ? [{ id: ID, name: 'One', state: 'running' }] : [] }),
+    setSwitch: async (enabled) => {
+      calls.push(['setSwitch', enabled]);
+      if (switchState.failWith) throw switchState.failWith;
+      state.enabled = enabled;
+      state.journey = enabled ? journey : null;
+      return { enabled, stopped: enabled ? [] : [{ id: ID, name: 'One' }], stillRunning: [] };
+    },
+  });
+  const server = http.createServer(app);
+  servers.push(server);
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const call = async (method, path, body) => {
+    const response = await fetch(`${base}${path}`, { method, headers: body === undefined ? {} : { 'content-type': 'application/json' }, body: body === undefined ? undefined : JSON.stringify(body) });
+    return { status: response.status, body: await response.json() };
+  };
+  return { call, calls, state };
+};
+
+const journeyOf = (overrides = {}) => {
+  const calls = [];
+  const record = (name, value) => async (...args) => { calls.push([name, ...args]); if (value instanceof Error) throw value; return value; };
+  return {
+    calls,
+    listSpaces: record('listSpaces', [{ id: ID, name: 'One', state: 'running' }]),
+    createSpace: record('createSpace', { id: ID, state: 'preparing' }),
+    startSpace: record('startSpace', { id: ID, state: 'running' }),
+    stopSpace: record('stopSpace', { id: ID, state: 'exited' }),
+    removeSpace: record('removeSpace', { id: ID, removed: true }),
+    grantAccess: record('grantAccess', { grant: { id: 'open-1' } }),
+    readJournal: record('readJournal', { records: [], dropped: 0, since: 'now' }),
+    previewApply: record('previewApply', { changedPaths: 2 }),
+    applySpace: record('applySpace', { applied: { status: 'applied' } }),
+    stopAllSpaces: record('stopAllSpaces', { stopped: [], stillRunning: [] }),
+    ...overrides,
+  };
+};
+
+describe('space routes', () => {
+  it('answers every journey route with 404 and isolated_spaces_off while the feature is off, and the switch still works', async () => {
+    const { call, calls } = await serve({ journey: null, switchState: { enabled: false } });
+    for (const [method, path] of [['GET', ''], ['POST', ''], ['GET', '/places'], ['POST', `/${ID}/start`], ['POST', `/${ID}/stop`], ['POST', `/${ID}/grants`], ['DELETE', `/${ID}`], ['GET', `/${ID}/journal`], ['GET', `/${ID}/apply`], ['POST', `/${ID}/apply`]]) {
+      expect(await call(method, `${SPACES_ROUTE}${path}`, method === 'GET' || method === 'DELETE' ? undefined : {}), `${method} ${path}`).toEqual({ status: 404, body: { code: 'isolated_spaces_off', message: 'Isolated spaces are turned off.', details: null } });
+    }
+    expect(await call('GET', `${SPACES_ROUTE}/switch`)).toEqual({ status: 200, body: { enabled: false, spaces: [] } });
+    expect(await call('PUT', `${SPACES_ROUTE}/switch`, { enabled: true })).toEqual({ status: 200, body: { enabled: true, stopped: [], stillRunning: [] } });
+    expect(calls).toEqual([['setSwitch', true]]);
+    expect(await call('PUT', `${SPACES_ROUTE}/switch`, { enabled: 'yes' })).toMatchObject({ status: 400, body: { code: 'invalid_request_body' } });
+    expect(await call('PUT', `${SPACES_ROUTE}/switch`, [])).toMatchObject({ status: 400, body: { code: 'invalid_request_body' } });
+  });
+
+  it('reports what turning the switch off would stop, and what it stopped', async () => {
+    const journey = journeyOf();
+    const { call, state } = await serve({ journey });
+    expect(await call('GET', `${SPACES_ROUTE}/switch`)).toEqual({ status: 200, body: { enabled: true, spaces: [{ id: ID, name: 'One', state: 'running' }] } });
+    expect(await call('PUT', `${SPACES_ROUTE}/switch`, { enabled: false })).toEqual({ status: 200, body: { enabled: false, stopped: [{ id: ID, name: 'One' }], stillRunning: [] } });
+    expect(state.journey).toBeNull();
+    expect(await call('GET', SPACES_ROUTE)).toMatchObject({ status: 404, body: { code: 'isolated_spaces_off' } });
+  });
+
+  it('passes a refusal of the switch on with its status', async () => {
+    const { call } = await serve({ journey: journeyOf(), switchState: { enabled: true, failWith: new SpaceError('space_preparing', 'A space is still being made.', { spaces: [ID] }) } });
+    expect(await call('PUT', `${SPACES_ROUTE}/switch`, { enabled: false })).toEqual({ status: 409, body: { code: 'space_preparing', message: 'A space is still being made.', details: { spaces: [ID] } } });
+  });
+
+  it('translates each route into the journey call it stands for', async () => {
+    const journey = journeyOf();
+    const places = [{ id: 'docker', check: async () => ({ available: true, version: '29.2.1', hostIsolation: true }) }];
+    const { call } = await serve({ journey, places });
+    expect(await call('GET', `${SPACES_ROUTE}/places`)).toEqual({ status: 200, body: { places: [{ id: 'docker', available: true, version: '29.2.1', hostIsolation: true }] } });
+    expect(await call('GET', SPACES_ROUTE)).toEqual({ status: 200, body: { spaces: [{ id: ID, name: 'One', state: 'running' }] } });
+    const request = { projectDirectory: '/home/me/project', name: 'One', start: 'clean', network: { mode: 'open' } };
+    expect(await call('POST', SPACES_ROUTE, request)).toEqual({ status: 202, body: { id: ID, state: 'preparing' } });
+    expect(await call('POST', `${SPACES_ROUTE}/${ID}/start`)).toEqual({ status: 200, body: { id: ID, state: 'running' } });
+    expect(await call('POST', `${SPACES_ROUTE}/${ID}/stop`)).toEqual({ status: 200, body: { id: ID, state: 'exited' } });
+    expect(await call('POST', `${SPACES_ROUTE}/${ID}/grants`, { kind: 'domain', upstream: 'https://registry.example.com/' })).toEqual({ status: 200, body: { grant: { id: 'open-1' } } });
+    expect(await call('GET', `${SPACES_ROUTE}/${ID}/journal`)).toEqual({ status: 200, body: { records: [], dropped: 0, since: 'now' } });
+    expect(await call('GET', `${SPACES_ROUTE}/${ID}/apply`)).toEqual({ status: 200, body: { changedPaths: 2 } });
+    expect(await call('POST', `${SPACES_ROUTE}/${ID}/apply`, { as: 'branch', branch: 'b' })).toEqual({ status: 200, body: { applied: { status: 'applied' } } });
+    expect(await call('DELETE', `${SPACES_ROUTE}/${ID}`)).toEqual({ status: 200, body: { id: ID, removed: true } });
+    expect(journey.calls).toEqual([
+      ['listSpaces', { access: true }], ['createSpace', request], ['startSpace', ID], ['stopSpace', ID], ['grantAccess', ID, { kind: 'domain', upstream: 'https://registry.example.com/' }], ['readJournal', ID], ['previewApply', ID], ['applySpace', ID, { as: 'branch', branch: 'b' }], ['removeSpace', ID],
+    ]);
+  });
+
+  it('refuses an id that is not a space id before the journey is asked, and a body that is not an object', async () => {
+    const journey = journeyOf();
+    const { call } = await serve({ journey });
+    for (const bad of ['ABCDEF012345', '0f0f0f0f0f0', 'a1b2c3d4e5f6x']) {
+      expect(await call('POST', `${SPACES_ROUTE}/${encodeURIComponent(bad)}/start`)).toMatchObject({ status: 404, body: { code: 'space_not_found' } });
+    }
+    expect(await call('POST', SPACES_ROUTE, [1])).toMatchObject({ status: 400, body: { code: 'invalid_request_body' } });
+    expect(journey.calls).toEqual([]);
+  });
+
+  it('gives each refusal of the journey the status of its code, and never a stack', async () => {
+    const answers = [];
+    const res = { status(code) { this.code = code; return this; }, json(body) { answers.push({ status: this.code, body }); } };
+    const cases = [
+      ['space_not_found', 404], ['isolated_spaces_off', 404], ['project_not_registered', 400], ['invalid_network', 400], ['space_preparing', 409], ['space_not_running', 409],
+      ['space_busy', 409], ['space_creation_failed', 409], ['invalid_grant_request', 400], ['secret_source_missing', 409], ['space_record_unreadable', 409],
+      ['branch_exists', 409], ['changes_do_not_apply', 409], ['changes_route_closed', 409], ['nothing_to_apply', 409], ['place_cannot_restrict_network', 409],
+      ['space_remove_incomplete', 502], ['docker_command_failed', 502], ['code_out_failed', 502],
+    ];
+    for (const [code, status] of cases) {
+      answerFailure(res, new SpaceError(code, `about ${code}`, { step: 'x' }));
+      expect(answers.at(-1), code).toEqual({ status, body: { code, message: `about ${code}`, details: { step: 'x' } } });
+    }
+    answerFailure(res, new TypeError('boom'));
+    expect(answers.at(-1)).toEqual({ status: 500, body: { code: 'space_journey_failed', message: 'boom', details: null } });
+    expect(JSON.stringify(answers)).not.toContain('at ');
+  });
+});
+
+describe('the switch controller', () => {
+  const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+  const hostOf = (name, { spaces = [], listFails = false } = {}) => {
+    const host = {
+      name,
+      closed: 0,
+      reopened: 0,
+      journey: {
+        listSpaces: async () => { if (listFails) throw new SpaceError('docker_command_failed', 'docker ps exited 1'); return spaces; },
+        stopAllSpaces: async () => { await sleep(30); return { stopped: spaces.map(({ id, name: spaceName }) => ({ id, name: spaceName })), stillRunning: [] }; },
+        reopen: () => { host.reopened += 1; },
+      },
+      close: () => { host.closed += 1; },
+    };
+    return host;
+  };
+  const controllerWith = ({ host = null, persistFails = false } = {}) => {
+    const state = { host, built: 0, started: [], persisted: [] };
+    const controller = createSwitchController({
+      getHost: () => state.host,
+      setHost: (next) => { state.host = next; },
+      buildHost: () => { state.built += 1; return hostOf(`built-${state.built}`); },
+      startHost: (made) => { state.started.push(made.name); },
+      persist: async (enabled) => { await sleep(10); if (persistFails) throw new Error('disk full'); state.persisted.push(enabled); },
+    });
+    return { controller, state };
+  };
+
+  it('reads the switch, and says the list is unknown rather than failing when the place cannot be asked', async () => {
+    expect(await controllerWith().controller.readSwitch()).toEqual({ enabled: false, spaces: [] });
+    const on = controllerWith({ host: hostOf('on', { spaces: [{ id: ID, name: 'One', state: 'running', extra: 1 }] }) });
+    expect(await on.controller.readSwitch()).toEqual({ enabled: true, spaces: [{ id: ID, name: 'One', state: 'running' }] });
+    const down = controllerWith({ host: hostOf('down', { listFails: true }) });
+    expect(await down.controller.readSwitch()).toEqual({ enabled: true, spaces: null, failure: { code: 'docker_command_failed', message: 'docker ps exited 1' } });
+  });
+
+  it('builds one host for two turn-ons at once, and closes the one host once for two turn-offs', async () => {
+    const { controller, state } = controllerWith();
+    const [first, second] = await Promise.all([controller.setSwitch(true), controller.setSwitch(true)]);
+    expect(first).toEqual({ enabled: true, stopped: [], stillRunning: [] });
+    expect(second).toEqual(first);
+    expect(state.built).toBe(1);
+    expect(state.started).toEqual(['built-1']);
+    expect(state.persisted).toEqual([true]);
+    const on = state.host;
+    const [offFirst, offSecond] = await Promise.all([controller.setSwitch(false), controller.setSwitch(false)]);
+    expect(offFirst).toEqual({ enabled: false, stopped: [], stillRunning: [] });
+    expect(offSecond).toEqual(offFirst);
+    expect(on.closed).toBe(1);
+    expect(state.host).toBeNull();
+    expect(state.persisted).toEqual([true, false]);
+  });
+
+  it('stops the spaces, writes the setting and only then closes the host; a setting that cannot be written leaves the feature on and open again', async () => {
+    const host = hostOf('on', { spaces: [{ id: ID, name: 'One', state: 'running' }] });
+    const failing = controllerWith({ host, persistFails: true });
+    await expect(failing.controller.setSwitch(false)).rejects.toThrow('disk full');
+    expect(host.closed).toBe(0);
+    expect(host.reopened).toBe(1);
+    expect(failing.state.host).toBe(host);
+
+    const { controller, state } = controllerWith({ host });
+    expect(await controller.setSwitch(false)).toEqual({ enabled: false, stopped: [{ id: ID, name: 'One' }], stillRunning: [] });
+    expect(host.closed).toBe(1);
+    expect(state.host).toBeNull();
+    // A turn-on that arrived while the turn-off was running builds the host after it, once.
+    const [off, on] = await Promise.all([controller.setSwitch(false), controller.setSwitch(true)]);
+    expect(off.enabled).toBe(false);
+    expect(on.enabled).toBe(true);
+    expect(state.built).toBe(1);
+  });
+});

package/server/lib/spaces/run-command.js

@@ -1,5 +1,8 @@
 import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { Duplex } from 'node:stream';
 
 import { SpaceError } from './errors.js';
 
@@ -70,6 +73,11 @@ const trackTree = (child) => {
   liveTrees.add(child);
 };
 
+/** What an abort rejects with: the caller's own SpaceError, or one of ours for any other reason. */
+const abortReason = (signal, file, args) => (signal.reason instanceof SpaceError
+  ? signal.reason
+  : new SpaceError('command_aborted', `${file} ${args[0] ?? ''} was stopped by its caller`));
+
 /**
  * Runs one executable with an argument array and resolves `{ code, stdout, stderr }`
  * for any exit code. The executable is spawned directly, never through a shell.
@@ -86,7 +94,28 @@ const trackTree = (child) => {
  * caller that cleans up afterwards does not race processes that still hold its files. Measured on
  * Windows: without the wait, removing the temporary folder failed with EBUSY and hid the timeout.
  * `options.killWaitMs` changes that bound, for the tests. While a `killTree` child runs, an exit of
- * this process kills its tree too, see `liveTrees`.
+ * this process kills its tree too, see `liveTrees`, unless `options.keepAtExit` is true: then only a
+ * timeout or an abort kills it, and it outlives an exit of this process, as a child without `killTree`
+ * does on POSIX. It is for `git apply`, which, killed in the middle of writing, leaves the user's project
+ * half changed, while left to run it finishes. Such a child also has no pipe back to this process on
+ * its output, because a pipe dies with this process, and a filter of git's that then printed got
+ * SIGPIPE and stopped the apply in the middle all the same, measured by a reviewer. Its stdout goes
+ * nowhere and resolves as empty; its stderr goes into a file this process made and removed at once,
+ * which it and the child each hold open, so no clean-up of anybody's can break the child's writes. At
+ * `close` the last `maxOutputBytes` of it are read: the same window as `keepTail`, and without
+ * `keepTail` a longer stderr is `command_output_too_large` then, after the child has ended.
+ *
+ * `options.signal` is an `AbortSignal` that lets the caller stop the child from outside: the child is
+ * killed as a timeout kills it, and the rejection is the signal's reason when that reason is a
+ * SpaceError, and `command_aborted` otherwise, so every rejection of this function is a SpaceError.
+ * The caller then knows that it stopped the child, which the exit code cannot tell: on Windows a tree
+ * ended by `taskkill` exits with code 1, not a signal. A signal that is already aborted starts nothing.
+ *
+ * `options.keepTail: true` turns the output cap into a window: past `maxOutputBytes`, each stream keeps
+ * its last `maxOutputBytes` bytes and the child runs on. It is for a child whose exit code is the answer
+ * and whose output is only shown: a `git apply --check` that fails prints a line or two for every path
+ * that does not fit, and measured by a reviewer, tens of thousands of such paths passed four megabytes,
+ * where the cap stopped the check and its answer was lost.
  *
  * Rejects with a SpaceError when the process cannot start (`command_spawn_failed`),
  * runs past `timeoutMs` (`command_timeout`), prints more than `maxOutputBytes`
@@ -96,11 +125,35 @@ const trackTree = (child) => {
 export function runCommand(file, args, options = {}) {
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const keepTail = options.keepTail === true;
   const stdin = options.stdin ?? '';
   const killTree = options.killTree === true;
+  const keepAtExit = options.keepAtExit === true;
   const killWaitMs = options.killWaitMs ?? KILL_WAIT_MS;
+  const abortSignal = options.signal;
 
   return new Promise((resolve, reject) => {
+    if (abortSignal?.aborted) {
+      reject(abortReason(abortSignal, file, args));
+      return;
+    }
+    // Where a keepAtExit child's stderr goes: a file already removed from its folder, open here and in the child.
+    let errorFile = null;
+    const closeErrorFile = () => {
+      if (errorFile === null) return;
+      try { fs.closeSync(errorFile.fd); } catch { /* already closed */ }
+      fs.rmSync(errorFile.folder, { recursive: true, force: true });
+      errorFile = null;
+    };
+    if (keepAtExit) {
+      try {
+        const folder = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-stderr-'));
+        errorFile = { folder, fd: fs.openSync(path.join(folder, 'stderr'), 'w+') };
+      } catch (error) {
+        reject(new SpaceError('command_spawn_failed', `Could not start ${file}: no file for its output: ${error.message}`, { errno: error.code ?? null }));
+        return;
+      }
+    }
     let child;
     try {
       child = spawn(file, args, {
@@ -111,18 +164,23 @@ export function runCommand(file, args, options = {}) {
         // On POSIX the child leads a process group of its own, so the kill can reach its children.
         // Never on Windows: there `detached` gives the child a console of its own.
         detached: killTree && process.platform !== 'win32',
-        stdio: ['pipe', 'pipe', 'pipe'],
+        stdio: errorFile === null ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'ignore', errorFile.fd],
       });
     } catch (error) {
+      closeErrorFile();
       reject(new SpaceError('command_spawn_failed', `Could not start ${file}: ${error.message}`, { errno: error.code ?? null }));
       return;
     }
 
-    if (killTree) trackTree(child);
+    if (killTree && !keepAtExit) trackTree(child);
+    // The child holds its own copy now; with the name gone, nothing that cleans folders can take it away.
+    // Where the system refuses to remove an open file, the folder goes at `close`.
+    if (errorFile !== null) fs.rmSync(errorFile.folder, { recursive: true, force: true });
 
     const stdoutChunks = [];
     const stderrChunks = [];
     let capturedBytes = 0;
+    const heldBytes = new Map([[stdoutChunks, 0], [stderrChunks, 0]]);
     let settled = false;
     let closed = false;
     const closeWaiters = [];
@@ -139,6 +197,7 @@ export function runCommand(file, args, options = {}) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      abortSignal?.removeEventListener('abort', stop);
       if (!killTree) {
         child.kill('SIGKILL');
         reject(error);
@@ -150,21 +209,42 @@ export function runCommand(file, args, options = {}) {
     const timer = setTimeout(() => {
       fail(new SpaceError('command_timeout', `${file} ${args[0] ?? ''} did not finish within ${timeoutMs} ms and was stopped`));
     }, timeoutMs);
+    const stop = () => fail(abortReason(abortSignal, file, args));
+    abortSignal?.addEventListener('abort', stop, { once: true });
 
-    const capture = (chunks) => (chunk) => {
+    // Only the last `maxOutputBytes` of the stream stay, and nothing fails.
+    const window = (chunks) => (chunk) => {
+      chunks.push(chunk);
+      let held = heldBytes.get(chunks) + chunk.length;
+      while (held - chunks[0].length >= maxOutputBytes) held -= chunks.shift().length;
+      if (held > maxOutputBytes) {
+        chunks[0] = chunks[0].subarray(held - maxOutputBytes);
+        held = maxOutputBytes;
+      }
+      heldBytes.set(chunks, held);
+    };
+    const capture = (chunks) => (keepTail ? window(chunks) : (chunk) => {
       capturedBytes += chunk.length;
       if (capturedBytes > maxOutputBytes) {
         fail(new SpaceError('command_output_too_large', `${file} ${args[0] ?? ''} printed more than ${maxOutputBytes} bytes and was stopped`));
         return;
       }
       chunks.push(chunk);
-    };
+    });
 
-    child.stdout.on('data', capture(stdoutChunks));
-    child.stderr.on('data', capture(stderrChunks));
+    child.stdout?.on('data', capture(stdoutChunks));
+    child.stderr?.on('data', capture(stderrChunks));
+    /** The last `maxOutputBytes` of the stderr file, and its whole length. */
+    const readErrorFile = () => {
+      const size = fs.fstatSync(errorFile.fd).size;
+      const kept = Buffer.alloc(Math.min(size, maxOutputBytes));
+      fs.readSync(errorFile.fd, kept, 0, kept.length, size - kept.length);
+      return { size, kept };
+    };
 
     child.on('error', (error) => {
       liveTrees.delete(child);
+      closeErrorFile();
       fail(new SpaceError('command_spawn_failed', `Could not start ${file}: ${error.message}`, { errno: error.code ?? null }));
     });
 
@@ -175,13 +255,34 @@ export function runCommand(file, args, options = {}) {
     child.on('close', (code, signal) => {
       closed = true;
       for (const wake of closeWaiters.splice(0)) wake();
-      if (settled) return;
+      if (settled) {
+        closeErrorFile();
+        return;
+      }
       settled = true;
       clearTimeout(timer);
+      abortSignal?.removeEventListener('abort', stop);
       if (code === null) {
+        closeErrorFile();
         reject(new SpaceError('command_killed', `${file} ${args[0] ?? ''} was stopped by signal ${signal}`));
         return;
       }
+      if (errorFile !== null) {
+        let read;
+        try {
+          read = readErrorFile();
+        } catch (error) {
+          reject(new SpaceError('command_output_unreadable', `The output of ${file} ${args[0] ?? ''} could not be read back: ${error.message}`, { exitCode: code }));
+          return;
+        } finally {
+          closeErrorFile();
+        }
+        if (!keepTail && read.size > maxOutputBytes) {
+          reject(new SpaceError('command_output_too_large', `${file} ${args[0] ?? ''} printed more than ${maxOutputBytes} bytes`));
+          return;
+        }
+        stderrChunks.push(read.kept);
+      }
       resolve({
         code,
         stdout: Buffer.concat(stdoutChunks).toString('utf8'),
@@ -259,3 +360,155 @@ export async function killProcessTree(child, {
   }
   return true;
 }
+
+// How much of a streamed command's stderr is kept for its error message.
+const STREAM_STDERR_BYTES = 4 * 1024;
+
+/**
+ * A command's stdin and stdout as one duplex stream that an `http.Agent` can use as a socket.
+ * Written for `docker exec --interactive` with the bridge inside a space, which joins the two
+ * pipes to the loopback port of the server there: the dispatcher's requests travel through
+ * this and never through a network of the space. Everything an `http` client calls on a
+ * `net.Socket` is here: `setNoDelay`, `setKeepAlive`, `setTimeout`, `ref` and `unref`, and
+ * `destroy`, which kills the command. Backpressure runs both ways through the pipes.
+ *
+ * The stream ends when the command's stdout ends. A command that exits with a code other than
+ * zero, or before it wrote anything, destroys the stream with `command_stream_failed` and the
+ * tail of its stderr, so a bridge that could not reach the server inside says so.
+ */
+class CommandStream extends Duplex {
+  #child;
+  #file;
+  #args;
+  #stderr = [];
+  #stderrBytes = 0;
+  #receivedBytes = 0;
+  #closed = false;
+  #timer = null;
+
+  constructor(child, file, args) {
+    super({ allowHalfOpen: false });
+    this.#child = child;
+    this.#file = file;
+    this.#args = args;
+    this.timeout = 0;
+    // A failure that arrives before a consumer listens must not end the process. Whoever holds
+    // the stream still gets the error; this listener only keeps it from being uncaught.
+    this.on('error', () => {});
+
+    child.stdout.on('data', (chunk) => {
+      this.#receivedBytes += chunk.length;
+      this.#touch();
+      if (!this.push(chunk)) child.stdout.pause();
+    });
+    // The readable side ends at the command's `close`, not at stdout's `end`, so that a command
+    // which failed can still end the stream with its reason rather than with a bare end.
+    child.stderr.on('data', (chunk) => {
+      if (this.#stderrBytes >= STREAM_STDERR_BYTES) return;
+      this.#stderr.push(chunk.subarray(0, STREAM_STDERR_BYTES - this.#stderrBytes));
+      this.#stderrBytes += chunk.length;
+    });
+    child.stdin.on('error', (error) => {
+      // After the command has ended, its input closing is not news.
+      if (!this.#closed) this.destroy(this.#failure(`its input closed: ${error.code ?? error.message}`));
+    });
+    child.on('error', (error) => {
+      this.#closed = true;
+      this.destroy(new SpaceError('command_spawn_failed', `Could not start ${file}: ${error.message}`, { errno: error.code ?? null }));
+    });
+    child.on('close', (code, signal) => {
+      this.#closed = true;
+      if (this.destroyed) return;
+      // A clean end: the readable side ends, the writable side follows (`allowHalfOpen: false`),
+      // and nothing is destroyed here, so what is still buffered is read.
+      if (code === 0 && this.#receivedBytes > 0) {
+        this.push(null);
+        return;
+      }
+      const why = code === null ? `stopped by signal ${signal}` : `exited with code ${code}`;
+      this.destroy(this.#failure(`${why}${this.#stderrText() ? `: ${this.#stderrText()}` : ''}`));
+    });
+  }
+
+  #stderrText() {
+    return Buffer.concat(this.#stderr).toString('utf8').trim();
+  }
+
+  #failure(what) {
+    return new SpaceError('command_stream_failed', `${this.#file} ${this.#args[0] ?? ''} ${what}`);
+  }
+
+  #touch() {
+    if (this.timeout > 0) this.setTimeout(this.timeout);
+  }
+
+  _read() {
+    this.#child.stdout.resume();
+  }
+
+  _write(chunk, _encoding, callback) {
+    this.#touch();
+    if (this.#closed) {
+      callback(this.#failure('has ended'));
+      return;
+    }
+    this.#child.stdin.write(chunk, callback);
+  }
+
+  _final(callback) {
+    if (this.#closed) {
+      callback();
+      return;
+    }
+    this.#child.stdin.end(callback);
+  }
+
+  _destroy(error, callback) {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+    this.#child.stdout.removeAllListeners('data');
+    try {
+      this.#child.kill('SIGKILL');
+    } catch {
+      // Already gone.
+    }
+    callback(error);
+  }
+
+  /** Emits `timeout` after `milliseconds` without a byte in either direction. Zero cancels it. */
+  setTimeout(milliseconds, callback) {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+    this.timeout = milliseconds;
+    if (callback) this.once('timeout', callback);
+    if (milliseconds > 0) {
+      this.#timer = setTimeout(() => { this.#timer = null; this.emit('timeout'); }, milliseconds);
+      this.#timer.unref?.();
+    }
+    return this;
+  }
+
+  setNoDelay() { return this; }
+
+  setKeepAlive() { return this; }
+
+  ref() { return this; }
+
+  unref() { return this; }
+}
+
+/**
+ * Starts one executable with an argument array and hands back its stdin and stdout as a
+ * `CommandStream`. The executable is spawned directly, never through a shell, hidden on
+ * Windows. It is the transport of the place contract's `connect`. A command that cannot be
+ * started throws `command_spawn_failed` at once.
+ */
+export function openCommandStream(file, args) {
+  let child;
+  try {
+    child = spawn(file, args, { shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch (error) {
+    throw new SpaceError('command_spawn_failed', `Could not start ${file}: ${error.message}`, { errno: error.code ?? null });
+  }
+  return new CommandStream(child, file, args);
+}