@vantran-se/openchamber-web 2.0.3 → 2.0.5

package/server/lib/spaces/places/server.docker.live.test.js

@@ -5,6 +5,7 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 import { createSpaceId, hashProjectDirectory, toolsKeyFromVolumeName } from '../labels.js';
 import { SPACE_SERVER_PORT, SPACE_TOKEN_PATH, TOOLS_MOUNT_PATH } from '../layout.js';
+import { createGatekeeperChannel } from '../gatekeeper-channel.js';
 import { createSpaceServerChannel } from '../space-server.js';
 import { createRegistryToolsSource, readHostToolVersions } from '../tools.js';
 import { LIVE_DOCKER_ENABLED, createLiveDockerPlace } from './docker-live-support.js';
@@ -51,11 +52,12 @@ setTimeout(() => finish({ error: 'timeout' }), 30000);
 })().catch((error) => finish({ error: String(error) }));
 `;
 
-const HELLO_TOOL = `import { tool } from "@opencode/plugin"
-export default tool({
-  description: "Says hello",
-  args: { name: tool.schema.string() },
-  async execute(args) { return "hello " + args.name },
+// A project plugin in the form OpenCode 2 loads from `.opencode/plugins/`. It imports the
+// plugin package, which is the import that needs the link above the projects.
+const HELLO_PLUGIN = `import { Plugin } from "@opencode/plugin"
+export default Plugin.define({
+  id: "hello",
+  setup: async () => {},
 })
 `;
 
@@ -69,6 +71,7 @@ describe.skipIf(!LIVE_DOCKER_ENABLED)('server inside a space: docker (live)', ()
   };
   const repo = `/spaces/${spec.id}/repo`;
   const link = `/spaces/${spec.id}/link-to-repo`;
+  const plugin = `${repo}/.opencode/plugins/hello.ts`;
   let place;
   let placeWith;
   let host;
@@ -88,6 +91,14 @@ describe.skipIf(!LIVE_DOCKER_ENABLED)('server inside a space: docker (live)', ()
     return login.headers['set-cookie'][0].split(';')[0];
   };
   const health = async () => JSON.parse((await server.request(spec.id, { path: '/health' })).body);
+  // OpenCode 2 answers with the record under `data`.
+  const api = async (path, { method = 'GET', body } = {}) => {
+    const answer = await server.request(spec.id, { method, path, headers: body === undefined ? { Cookie: cookie } : { ...JSON_HEADERS, Cookie: cookie }, body });
+    expect(answer.status, `${method} ${path}: ${answer.body}`).toBe(200);
+    return JSON.parse(answer.body).data;
+  };
+  const createSession = (directory) => api('/api/session', { method: 'POST', body: JSON.stringify({ location: { directory } }) });
+  const listSessions = async (directory) => (await api(`/api/session?directory=${encodeURIComponent(directory)}`)).map((entry) => entry.id);
 
   beforeAll(async () => {
     ({ place, placeWith, host, owner, dispose } = createLiveDockerPlace());
@@ -115,45 +126,70 @@ describe.skipIf(!LIVE_DOCKER_ENABLED)('server inside a space: docker (live)', ()
     expect(await shell('tr "\\0" "\\n" < /proc/1/environ')).not.toContain('OPENCHAMBER_UI_PASSWORD');
   });
 
-  // The open question of stage 0: does OpenCode report the space path unchanged?
+  // The open question of stage 0: does OpenCode report the space path unchanged? OpenCode 2
+  // takes the directory from `location` in the body. It ignores `?directory=` on this route, and
+  // such a session lands in HOME, so the dispatcher must never rely on the query here.
   it('reports the directory of a session byte for byte as the space path', async () => {
     await shell(`mkdir -p ${repo} && cd ${repo} && git init -q . && git -c user.email=space@example.invalid -c user.name=Space commit -q --allow-empty -m init`);
 
-    const created = await server.request(spec.id, { method: 'POST', path: `/api/session?directory=${encodeURIComponent(repo)}`, headers: { ...JSON_HEADERS, Cookie: cookie }, body: '{}' });
-    expect(created.status).toBe(200);
-    const session = JSON.parse(created.body);
-    expect(session.directory).toBe(repo);
-
-    const readBack = await server.request(spec.id, { path: `/api/session/${session.id}?directory=${encodeURIComponent(repo)}`, headers: { Cookie: cookie } });
-    expect(JSON.parse(readBack.body).directory).toBe(repo);
+    const session = await createSession(repo);
+    expect(session.location.directory).toBe(repo);
+    expect((await api(`/api/session/${session.id}`)).location.directory).toBe(repo);
+    expect(await listSessions(repo)).toEqual([session.id]);
 
-    const listed = await server.request(spec.id, { path: `/api/session?directory=${encodeURIComponent(repo)}`, headers: { Cookie: cookie } });
-    expect(JSON.parse(listed.body).map((entry) => entry.directory)).toEqual([repo]);
+    const byQuery = await api(`/api/session?directory=${encodeURIComponent(repo)}`, { method: 'POST', body: '{}' });
+    expect(byQuery.location.directory).toBe('/home/space');
+    expect(await listSessions(repo)).toEqual([session.id]);
   });
 
-  // Recorded, not wished for: OpenCode 1.18.31 resolves a symlink and reports the real path.
-  // The dispatcher stage must therefore hand OpenCode real paths only.
-  it('reports the real path for a directory that was reached through a symlink', async () => {
+  // Recorded, not wished for. OpenCode 1.18.31 resolved a symlink and reported the real path.
+  // OpenCode 2 keeps the link path, says how it relates to the project in `subpath`, and leaves
+  // the session out of the list for the real path. OpenCode no longer normalises anything, so
+  // handing it real paths only is the whole defence, and the dispatcher stage must do it.
+  it('reports the link path for a directory that was reached through a symlink', async () => {
     await shell(`ln -sfn ${repo} ${link}`);
+    const before = await listSessions(repo);
 
-    const created = await server.request(spec.id, { method: 'POST', path: `/api/session?directory=${encodeURIComponent(link)}`, headers: { ...JSON_HEADERS, Cookie: cookie }, body: '{}' });
-    expect(created.status).toBe(200);
-    expect(JSON.parse(created.body).directory).toBe(repo);
+    const session = await createSession(link);
+    expect(session.location.directory).toBe(link);
+    expect(session.subpath).toBe('../link-to-repo');
+    expect(await listSessions(repo)).toEqual(before);
   });
 
-  it('lists a project tool that imports @opencode/plugin, without waiting for a download that cannot happen', async () => {
-    await shell(`mkdir -p ${repo}/.opencode/tool && cat > ${repo}/.opencode/tool/hello.ts`, HELLO_TOOL);
-    // Only the plugin is linked above the projects, not the whole tools node_modules.
-    expect(await shell(`ls /spaces/${spec.id}/node_modules /spaces/${spec.id}/node_modules/@opencode`)).toBe(`/spaces/${spec.id}/node_modules:\n@opencode\n\n/spaces/${spec.id}/node_modules/@opencode:\nplugin\n`);
-    // The instance of the earlier tests loaded before the tool existed.
-    await server.request(spec.id, { method: 'POST', path: `/api/instance/dispose?directory=${encodeURIComponent(repo)}`, headers: { Cookie: cookie } });
+  // With no network, a project plugin that imports @opencode/plugin must load from the link above
+  // the projects. OpenCode 2 does not download the package for a local plugin: without the link
+  // the plugin fails at once with "Cannot find package". OpenCode 1 waited 131 seconds for a
+  // background install instead. The state check is what turns red when the link goes.
+  it('loads a project plugin that imports @opencode/plugin, without a download', async () => {
+    await shell(`mkdir -p "$(dirname ${plugin})" && cat > ${plugin}`, HELLO_PLUGIN);
+    const location = `location%5Bdirectory%5D=${encodeURIComponent(repo)}`;
 
     const started = Date.now();
-    const answer = await server.request(spec.id, { path: `/api/experimental/tool/ids?directory=${encodeURIComponent(repo)}`, headers: { Cookie: cookie } });
-    expect(answer.status).toBe(200);
-    expect(JSON.parse(answer.body)).toContain('hello');
-    // Without npm_config_fetch_retries=0 this took 131 seconds.
+    // The location of the earlier tests loaded before the plugin existed.
+    const reload = await server.request(spec.id, { method: 'POST', path: '/api/location/reload', headers: { Cookie: cookie } });
+    expect(reload.status).toBe(204);
+    // OpenCode loads plugins in the background, so the list can show this one before it has
+    // loaded, or not yet at all. Only `active` or `failed` is an answer.
+    let entry;
+    for (;;) {
+      entry = (await api(`/api/plugin?${location}`)).find((candidate) => candidate.source?.path === plugin);
+      if (['active', 'failed'].includes(entry?.state?.status) || Date.now() - started >= 15_000) break;
+      await new Promise((resolve) => { setTimeout(resolve, 250); });
+    }
+    expect(entry, 'OpenCode never listed the project plugin').toBeDefined();
+    // OpenCode answers a failure with a generic text and a ref. Its log has the cause under that ref.
+    const cause = entry.state?.ref
+      ? (await place.exec(spec.id, ['sh', '-c', 'grep -h -F -- "$1" "$HOME"/.local/share/opencode/log/*.log | tail -1', 'sh', entry.state.ref])).stdout.trim()
+      : '';
+    expect(entry.state, cause).toEqual({ status: 'active' });
     expect(Date.now() - started).toBeLessThan(15_000);
+
+    // Nothing tried to fetch a package for it.
+    const journal = await createGatekeeperChannel({ exec: place.exec }).readJournal(spec.id);
+    expect(journal.records.filter((record) => /npm/i.test(record.host))).toEqual([]);
+
+    // Only the plugin is linked above the projects, not the whole tools node_modules.
+    expect(await shell(`ls /spaces/${spec.id}/node_modules /spaces/${spec.id}/node_modules/@opencode`)).toBe(`/spaces/${spec.id}/node_modules:\n@opencode\n\n/spaces/${spec.id}/node_modules/@opencode:\nplugin\n`);
   }, 60_000);
 
   it('runs commands in a terminal as uid 1000, through the terminal WebSocket', async () => {
@@ -173,7 +209,7 @@ describe.skipIf(!LIVE_DOCKER_ENABLED)('server inside a space: docker (live)', ()
 
     expect(await health()).toMatchObject({ isOpenCodeReady: true });
     expect(await server.readToken(spec.id)).toBe(tokenBefore);
-    expect(await shell(`cat ${repo}/.opencode/tool/hello.ts`)).toBe(HELLO_TOOL);
+    expect(await shell(`cat ${plugin}`)).toBe(HELLO_PLUGIN);
     expect(await place.verify(spec.id)).toEqual([]);
   }, 5 * 60_000);
 
@@ -197,7 +233,7 @@ describe.skipIf(!LIVE_DOCKER_ENABLED)('server inside a space: docker (live)', ()
     expect(await updatedPlace.verify(spec.id)).toEqual([]);
     expect(await health()).toMatchObject({ isOpenCodeReady: true });
     expect(await server.readToken(spec.id)).toBe(tokenBefore);
-    expect(await shell(`cat ${repo}/.opencode/tool/hello.ts`)).toBe(HELLO_TOOL);
+    expect(await shell(`cat ${plugin}`)).toBe(HELLO_PLUGIN);
     expect(await updatedPlace.list()).toMatchObject([{ id: spec.id, state: 'running', damaged: false }]);
     // No container mounts the old tools volume any more, so it is gone.
     expect((await host.volumes()).filter((name) => name.startsWith('openchamber-tools-'))).toEqual([after]);

package/server/lib/spaces/places/sessions.docker.live.test.js

@@ -0,0 +1,222 @@
+// Sessions and events of a real space on a real Docker daemon. Runs only with
+// OPENCHAMBER_TEST_DOCKER=1. The host of `host.js` is mounted the way `server/index.js` mounts
+// it: the dispatcher and the socket forwarder in front of an Express app, the real OpenCode
+// proxy with a stand-in for the host's own OpenCode, and the real event hub.
+
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+
+import express from 'express';
+import { WebSocket } from 'ws';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createGlobalMessageStreamHub } from '../../event-stream/global-hub.js';
+import { registerOpenCodeProxy } from '../../opencode/proxy.js';
+import { runCommand } from '../run-command.js';
+import { createSpacesHost } from '../host.js';
+import { ROLE_SPACE, createSpaceId, hashProjectDirectory, spaceResourceName } from '../labels.js';
+import { LIVE_DOCKER_ENABLED, createLiveDockerPlace } from './docker-live-support.js';
+
+const CREATE_TIMEOUT_MS = 25 * 60_000;
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const until = async (check, timeoutMs = 10_000) => {
+  const deadline = Date.now() + timeoutMs;
+  while (!check() && Date.now() < deadline) await sleep(50);
+  return check();
+};
+const listen = (app) => new Promise((resolve) => {
+  const server = http.createServer(app);
+  server.listen(0, '127.0.0.1', () => resolve(server));
+});
+const frame = (payload) => Buffer.concat([Buffer.from([1]), Buffer.from(JSON.stringify(payload), 'utf8')]);
+
+describe.skipIf(!LIVE_DOCKER_ENABLED)('sessions and events of a real space: docker (live)', () => {
+  const spec = {
+    id: createSpaceId(),
+    name: 'Sessions live',
+    project: hashProjectDirectory('/sessions/live/project'),
+    created: new Date().toISOString(),
+    memoryBytes: 2 * 1024 * 1024 * 1024,
+  };
+  const repo = `/spaces/${spec.id}/repo`;
+  const hostSession = { id: 'ses_host_1', location: { directory: '/home/me/project' }, title: 'Host session' };
+  let place;
+  let dispose = async () => {};
+  let dataDir;
+  let host;
+  let hub;
+  let upstream;
+  let server;
+  let hostRouteRuns = 0;
+  const received = [];
+  const url = (suffix) => `http://127.0.0.1:${server.address().port}${suffix}`;
+  const wsUrl = (suffix) => `ws://127.0.0.1:${server.address().port}${suffix}`;
+  const shell = async (script) => {
+    const result = await place.exec(spec.id, ['sh', '-c', script]);
+    expect(result.code, `${script}: ${result.stderr}`).toBe(0);
+    return result.stdout;
+  };
+
+  beforeAll(async () => {
+    ({ place, dispose } = createLiveDockerPlace());
+    await place.create(spec);
+    await shell(`mkdir -p ${repo} && cd ${repo} && git init -q . && git -c user.email=space@example.invalid -c user.name=Space commit -q --allow-empty -m init`);
+    dataDir = temporary('openchamber-sessions-live-');
+    host = createSpacesHost({ dataDir, place, logger: { warn: () => {} } });
+
+    // The host's own OpenCode: one session, an event stream that stays open.
+    const upstreamApp = express();
+    upstreamApp.get('/api/session', (_req, res) => res.json({ data: [hostSession], cursor: {} }));
+    upstreamApp.get('/api/event', (_req, res) => {
+      res.setHeader('content-type', 'text/event-stream');
+      res.flushHeaders();
+      res.write(`data: ${JSON.stringify({ id: 'host-e1', type: 'server.connected', data: {} })}\n\n`);
+    });
+    upstream = await listen(upstreamApp);
+    const upstreamPort = upstream.address().port;
+    hub = createGlobalMessageStreamHub({ buildOpenCodeUrl: (p) => `http://127.0.0.1:${upstreamPort}${p}`, getOpenCodeAuthHeaders: () => ({}), deltaCoalesceWindowMs: 0 });
+    hub.subscribeEvent((event) => received.push(event), { spaces: true });
+
+    const app = express();
+    app.use(host.middleware);
+    app.all('/api/git/status', (req, res) => { hostRouteRuns += 1; res.json({ ranOnHost: true, directory: req.query.directory ?? null }); });
+    registerOpenCodeProxy(app, {
+      fs: {}, os: {}, path, OPEN_CODE_READY_GRACE_MS: 0,
+      getRuntime: () => ({ openCodePort: upstreamPort, isOpenCodeReady: true, openCodeNotReadySince: 0, isRestartingOpenCode: false }),
+      getOpenCodeAuthHeaders: () => ({}),
+      buildOpenCodeUrl: (p) => `http://127.0.0.1:${upstreamPort}${p}`,
+      ensureOpenCodeApiPrefix: () => {},
+      mergeSpaceSessionList: (payload) => host.mergeSessionList(payload),
+      spaceEventHub: hub,
+    });
+    server = await listen(app);
+    host.prepareUpgrades({ uiAuthController: { enabled: false }, isRequestOriginAllowed: async () => true });
+    server.on('upgrade', host.upgradeHandler);
+    await host.startEvents(hub);
+  }, CREATE_TIMEOUT_MS);
+
+  afterAll(async () => {
+    host?.close();
+    hub?.stop();
+    for (const running of [server, upstream]) {
+      await new Promise((resolve) => { if (running) { running.closeAllConnections?.(); running.close(() => resolve()); } else resolve(); });
+    }
+    await dispose();
+    if (dataDir) fs.rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('runs a command inside as uid 1000 over the terminal socket under the prefix', async () => {
+    const created = await fetch(url(`/api/spaces/${spec.id}/terminal/create`), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ cwd: repo, cols: 80, rows: 24 }) });
+    expect(created.status, await created.clone().text()).toBe(200);
+    const { sessionId } = await created.json();
+    const socket = new WebSocket(wsUrl(`/api/spaces/${spec.id}/terminal/ws`), { headers: { origin: 'http://app.test' } });
+    let output = '';
+    let backend = null;
+    const done = new Promise((resolve, reject) => {
+      socket.on('error', reject);
+      socket.on('open', () => socket.send(frame({ t: 'attach', v: 3, s: sessionId })));
+      socket.on('message', (raw) => {
+        const message = JSON.parse(raw.subarray(1).toString('utf8'));
+        if (message.t === 'snapshot') {
+          backend = message.ptyBackend;
+          socket.send(frame({ t: 'write', v: 3, s: sessionId, d: 'echo space-$((40+2)); id -u\r' }));
+        }
+        if (message.t === 'output') output += message.d;
+        if (/space-42[\s\S]*\n1000\r?\n/.test(output)) resolve();
+      });
+      setTimeout(() => reject(new Error(`no answer from the terminal in time; output so far: ${output}`)), 30_000).unref();
+    });
+    await done;
+    expect(backend).toBe('node-pty');
+    expect(output).toMatch(/space-42\r?\n1000\r?\n/);
+    socket.close();
+    expect((await fetch(url(`/api/spaces/${spec.id}/terminal/${sessionId}`), { method: 'DELETE' })).status).toBe(200);
+  }, 90_000);
+
+  it('lists a session of the space in the merged list with its directory, and carries its events to the host\'s streams', async () => {
+    const controller = new AbortController();
+    const sse = await fetch(url('/api/global/event'), { headers: { accept: 'text/event-stream' }, signal: controller.signal });
+    expect(sse.status).toBe(200);
+    const reader = sse.body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    const readInBackground = (async () => {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        text += decoder.decode(value, { stream: true });
+      }
+    })().catch(() => {});
+    expect(await until(() => text.includes('host-e1'))).toBe(true);
+    // The space's stream is connected before its events can be trusted to arrive.
+    expect(await until(() => received.some((event) => event.payload.type === 'openchamber:space-stream' && event.payload.properties.status === 'connected'), 30_000)).toBe(true);
+
+    const created = await fetch(url(`/api/spaces/${spec.id}/session`), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ location: { directory: repo }, title: 'Inside the space' }) });
+    expect(created.status, await created.clone().text()).toBe(200);
+    const session = (await created.json()).data;
+    expect(session.location.directory).toBe(repo);
+
+    const merged = await (await fetch(url('/api/session'))).json();
+    const ids = merged.data.map((entry) => entry.id);
+    expect(ids).toContain(hostSession.id);
+    expect(ids).toContain(session.id);
+    expect(merged.data.find((entry) => entry.id === session.id).location.directory).toBe(repo);
+    // Since 4c each space entry carries its name and the project it was made for; this space's
+    // project is not one the host registered, so both of those are null here.
+    expect(merged.spaces).toEqual([{ id: spec.id, name: spec.name, projectDirectory: null, directory: null, state: 'complete', sessions: expect.any(Number) }]);
+
+    expect(await until(() => received.some((event) => event.spaceId === spec.id && event.payload.type === 'session.created' && event.payload.data?.sessionID === session.id), 30_000)).toBe(true);
+    expect(await until(() => text.includes(session.id), 30_000)).toBe(true);
+    controller.abort();
+    await readInBackground;
+  }, 120_000);
+
+  it('keeps a stopped space\'s last list as stale, and the host\'s list whole', async () => {
+    await place.stop(spec.id);
+    // The last accepted list is served for two seconds without asking; after that the space is asked and does not answer.
+    await sleep(2_100);
+    const merged = await (await fetch(url('/api/session'))).json();
+    expect(merged.data.map((entry) => entry.id)).toContain(hostSession.id);
+    expect(merged.spaces).toEqual([{ id: spec.id, name: spec.name, projectDirectory: null, directory: null, state: 'stale', sessions: expect.any(Number) }]);
+    expect(merged.spaces[0].sessions).toBeGreaterThan(0);
+    const socket = await new Promise((resolve) => {
+      const attempt = new WebSocket(wsUrl(`/api/spaces/${spec.id}/terminal/ws`), { headers: { origin: 'http://app.test' } });
+      attempt.on('unexpected-response', (_request, response) => resolve({ status: response.statusCode }));
+      attempt.on('error', () => {});
+    });
+    expect(socket.status).toBe(503);
+
+    await place.start(spec.id);
+    expect(await until(async () => (await (await fetch(url('/api/session'))).json()).spaces[0].state === 'complete', 60_000)).toBe(true);
+  }, 5 * 60_000);
+
+  // The check of the 4b row in STAGES.md: the space killed in the middle of its work.
+  it('leaves the host\'s sessions and routes untouched when the space is killed under an open socket', async () => {
+    const created = await fetch(url(`/api/spaces/${spec.id}/terminal/create`), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ cwd: repo, cols: 80, rows: 24 }) });
+    expect(created.status).toBe(200);
+    const { sessionId } = await created.json();
+    const socket = new WebSocket(wsUrl(`/api/spaces/${spec.id}/terminal/ws`), { headers: { origin: 'http://app.test' } });
+    await new Promise((resolve, reject) => { socket.on('open', resolve); socket.on('error', reject); });
+    socket.send(frame({ t: 'attach', v: 3, s: sessionId }));
+    socket.send(frame({ t: 'write', v: 3, s: sessionId, d: 'sleep 600\r' }));
+    const closed = new Promise((resolve) => socket.on('close', (code, reason) => resolve({ code, reason: reason.toString('utf8') })));
+
+    const kill = await runCommand('docker', ['kill', spaceResourceName(spec.id, ROLE_SPACE)]);
+    expect(kill.code, kill.stderr).toBe(0);
+    expect(await closed).toMatchObject({ code: expect.any(Number) });
+    await sleep(2_100);
+
+    const merged = await (await fetch(url('/api/session'))).json();
+    expect(merged.data.map((entry) => entry.id)).toContain(hostSession.id);
+    expect(merged.spaces[0]).toMatchObject({ id: spec.id, state: 'stale' });
+    const ordinary = await fetch(url('/api/git/status?directory=/tmp'));
+    expect(ordinary.status).toBe(200);
+    expect(hostRouteRuns).toBe(1);
+    // The host's own stream is still the host's: no space event of the dead space is invented.
+    expect(received.filter((event) => event.spaceId === spec.id && event.payload.type === 'openchamber:space-stream').at(-1).payload.properties.status).toBe('disconnected');
+  }, 120_000);
+});
+
+const temporary = (prefix) => fs.mkdtempSync(path.join(os.tmpdir(), prefix));

package/server/lib/spaces/routes.js

@@ -0,0 +1,216 @@
+// The host's own routes of the isolated-spaces journey, under `/api/openchamber/spaces`: a
+// namespace of the host's, never forwarded, beside `/api/openchamber/tunnel`. A request to the
+// server inside a space is `/api/spaces/<id>/...` and belongs to the dispatcher; nothing here
+// touches that shape.
+//
+// Every route but the switch exists only while the switch is on: `getJourney()` answers null
+// while it is off, and then the journey routes say so with 404 and `isolated_spaces_off`, the same
+// answer a route that does not exist would give. The switch itself is the one thing reachable
+// while the feature is off, because turning it on is what makes the feature exist (decision 19).
+// `/api/openchamber/spaces` is on the JSON-body allowlist of `core-routes.js`.
+
+import { z } from 'zod';
+
+import { SpaceError } from './errors.js';
+import { isSpaceId } from './labels.js';
+
+export const SPACES_ROUTE = '/api/openchamber/spaces';
+
+// Which HTTP status a refusal of the journey gets. Everything not named here is 502 when it comes
+// from the place or the space, and 500 when it is not a `SpaceError` at all.
+const STATUS_BY_CODE = new Map([
+  ['space_not_found', 404],
+  ['place_not_found', 404],
+  ['project_not_registered', 400],
+  ['invalid_space_name', 400],
+  ['invalid_project_directory', 400],
+  ['invalid_snapshot_mode', 400],
+  ['invalid_network', 400],
+  ['invalid_apply_request', 400],
+  ['invalid_branch_name', 400],
+  ['invalid_space_id', 400],
+  ['invalid_request_body', 400],
+  ['invalid_grant_request', 400],
+  ['provider_not_supported', 400],
+  ['secret_source_missing', 409],
+  ['space_record_unreadable', 409],
+  ['space_preparing', 409],
+  ['space_creation_failed', 409],
+  ['space_busy', 409],
+  ['isolated_spaces_off', 404],
+  ['space_not_running', 409],
+  ['branch_exists', 409],
+  ['changes_do_not_apply', 409],
+  ['changes_route_closed', 409],
+  ['changes_partly_applied', 409],
+  ['changes_undecided', 409],
+  ['changes_too_large', 409],
+  ['changes_blocked_by_link', 409],
+  ['name_not_allowed_here', 409],
+  ['case_only_rename', 409],
+  ['patch_not_possible', 409],
+  ['nothing_to_apply', 409],
+  ['place_cannot_restrict_network', 409],
+  ['space_remove_incomplete', 502],
+]);
+
+/** One JSON answer per failure, with a stable code. Details travel as data; a stack never does. */
+export const answerFailure = (res, error) => {
+  if (error instanceof SpaceError) {
+    res.status(STATUS_BY_CODE.get(error.code) ?? 502).json({ code: error.code, message: error.message, details: error.details ?? null });
+    return;
+  }
+  res.status(500).json({ code: 'space_journey_failed', message: error?.message ?? String(error), details: null });
+};
+
+const isObjectRecord = (value) => value instanceof Object && !Array.isArray(value);
+const switchBodySchema = z.object({ enabled: z.boolean() });
+
+/**
+ * The switch as `index.js` runs it. `getHost()` and `setHost(host)` read and replace the running
+ * host, `buildHost()` makes one as the start would, `startHost(host)` connects it, and
+ * `persist(enabled)` writes the setting. One change runs at a time: a second request waits for
+ * the first and then sees what it left, so a double click builds one host and never two.
+ */
+export function createSwitchController({ getHost, setHost, buildHost, startHost, persist }) {
+  let turning = Promise.resolve();
+  const inTurn = (work) => {
+    const next = turning.then(work, work);
+    turning = next.catch(() => {});
+    return next;
+  };
+
+  const readSwitch = async () => {
+    const host = getHost();
+    if (!host) return { enabled: false, spaces: [] };
+    try {
+      const spaces = await host.journey.listSpaces();
+      return { enabled: true, spaces: spaces.map(({ id, name, state }) => ({ id, name, state })) };
+    } catch (error) {
+      // The place cannot be asked, Docker being down among the reasons. The switch is still on and
+      // must still be reachable, so the answer says that the list is unknown rather than failing.
+      return { enabled: true, spaces: null, failure: { code: error instanceof SpaceError ? error.code : 'space_journey_failed', message: error?.message ?? String(error) } };
+    }
+  };
+
+  // Off: every space is stopped and its files kept, then the feature goes; a space that could not
+  // be stopped is reported as still running (decision 18). On: the setting is written and the
+  // feature comes up, as it would at the next start.
+  const setSwitch = (enabled) => inTurn(async () => {
+    const host = getHost();
+    if (enabled === Boolean(host)) return { enabled, stopped: [], stillRunning: [] };
+    if (!enabled) {
+      const outcome = await host.journey.stopAllSpaces();
+      try {
+        await persist(false);
+      } catch (error) {
+        host.journey.reopen();
+        throw error;
+      }
+      setHost(null);
+      host.close();
+      return { enabled: false, ...outcome };
+    }
+    await persist(true);
+    const made = buildHost();
+    startHost(made);
+    setHost(made);
+    return { enabled: true, stopped: [], stillRunning: [] };
+  });
+
+  return { readSwitch, setSwitch };
+}
+
+/**
+ * `getJourney()` is the journey of the running host or null, `getPlaces()` the places to check,
+ * `readSwitch()` and `setSwitch(enabled)` the switch: `setSwitch(false)` stops the spaces and takes
+ * the feature down, `setSwitch(true)` brings it up, and each resolves what the client shows.
+ */
+export function registerSpaceRoutes(app, { getJourney, getPlaces = () => [], readSwitch, setSwitch }) {
+  const withJourney = (handler) => async (req, res) => {
+    const journey = getJourney();
+    if (!journey) {
+      res.status(404).json({ code: 'isolated_spaces_off', message: 'Isolated spaces are turned off.', details: null });
+      return;
+    }
+    try {
+      await handler(journey, req, res);
+    } catch (error) {
+      answerFailure(res, error);
+    }
+  };
+
+  const spaceIdOf = (req) => {
+    const id = String(req.params.id ?? '');
+    if (!isSpaceId(id)) throw new SpaceError('space_not_found', `There is no space ${id}`);
+    return id;
+  };
+
+  const requireBody = (req) => {
+    if (!isObjectRecord(req.body)) throw new SpaceError('invalid_request_body', 'The body is a JSON object.');
+    return req.body;
+  };
+
+  // The switch: what it is and, while on, what turning it off would stop, for the banner of decision 18.
+  app.get(`${SPACES_ROUTE}/switch`, async (_req, res) => {
+    try {
+      res.json(await readSwitch());
+    } catch (error) {
+      answerFailure(res, error);
+    }
+  });
+  app.put(`${SPACES_ROUTE}/switch`, async (req, res) => {
+    try {
+      const body = switchBodySchema.safeParse(req.body);
+      if (!body.success) throw new SpaceError('invalid_request_body', 'The switch takes `enabled`, true or false.');
+      res.json(await setSwitch(body.data.enabled));
+    } catch (error) {
+      answerFailure(res, error);
+    }
+  });
+
+  // The places funnel: each place asked what it can do, now, because the user is looking.
+  app.get(`${SPACES_ROUTE}/places`, withJourney(async (_journey, _req, res) => {
+    const places = await Promise.all(getPlaces().map(async (place) => ({ id: place.id, ...(await place.check()) })));
+    res.json({ places });
+  }));
+
+  app.get(SPACES_ROUTE, withJourney(async (journey, _req, res) => {
+    res.json({ spaces: await journey.listSpaces({ access: true }) });
+  }));
+
+  // Answers as soon as the space has an id; the steps follow as `openchamber:space-progress` events.
+  app.post(SPACES_ROUTE, withJourney(async (journey, req, res) => {
+    res.status(202).json(await journey.createSpace(requireBody(req)));
+  }));
+
+  app.post(`${SPACES_ROUTE}/:id/start`, withJourney(async (journey, req, res) => {
+    res.json(await journey.startSpace(spaceIdOf(req)));
+  }));
+
+  app.post(`${SPACES_ROUTE}/:id/stop`, withJourney(async (journey, req, res) => {
+    res.json(await journey.stopSpace(spaceIdOf(req)));
+  }));
+
+  app.delete(`${SPACES_ROUTE}/:id`, withJourney(async (journey, req, res) => {
+    res.json(await journey.removeSpace(spaceIdOf(req)));
+  }));
+
+  // A grant for a running space; the key in the body goes to the gatekeeper and nowhere else.
+  app.post(`${SPACES_ROUTE}/:id/grants`, withJourney(async (journey, req, res) => {
+    res.json(await journey.grantAccess(spaceIdOf(req), requireBody(req)));
+  }));
+
+  app.get(`${SPACES_ROUTE}/:id/journal`, withJourney(async (journey, req, res) => {
+    res.json(await journey.readJournal(spaceIdOf(req)));
+  }));
+
+  // Brings the work out and says what an apply would do; nothing of the user's is written.
+  app.get(`${SPACES_ROUTE}/:id/apply`, withJourney(async (journey, req, res) => {
+    res.json(await journey.previewApply(spaceIdOf(req)));
+  }));
+
+  app.post(`${SPACES_ROUTE}/:id/apply`, withJourney(async (journey, req, res) => {
+    res.json(await journey.applySpace(spaceIdOf(req), requireBody(req)));
+  }));
+}