@vantran-se/openchamber-web 1.24.4 → 2.0.1

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

@@ -0,0 +1,7 @@
+import { LIVE_DOCKER_ENABLED, createLiveDockerPlace } from './docker-live-support.js';
+import { runEscapeSuite } from './escape-suite.js';
+
+runEscapeSuite('docker (live)', {
+  enabled: LIVE_DOCKER_ENABLED,
+  setup: async () => createLiveDockerPlace(),
+});

package/server/lib/spaces/places/fake-docker.js

@@ -0,0 +1,375 @@
+// Test support. A fake command runner that answers like the docker CLI for the
+// few subcommands the Docker place uses, and records every call.
+
+import { SpaceError } from '../errors.js';
+import { GATEKEEPER_PROGRAM_PATH, IMAGE_CAT, IMAGE_CURL, IMAGE_SH, SPACE_HOME, SPACE_TOKEN_PATH, TOOLS_MOUNT_PATH } from '../layout.js';
+
+const ok = (stdout = '') => ({ code: 0, stdout, stderr: '' });
+const failed = (stderr, stdout = '') => ({ code: 1, stdout, stderr });
+
+const NOT_FOUND_TEXT = {
+  container: (name) => `Error response from daemon: No such container: ${name}`,
+  network: (name) => `Error response from daemon: network ${name} not found`,
+  volume: (name) => `Error response from daemon: get ${name}: no such volume`,
+  image: (name) => `Error response from daemon: No such image: ${name}`,
+};
+
+const ISOLATED_GATEWAY_OPTION = 'com.docker.network.bridge.gateway_mode_ipv4';
+
+const readPairs = (args, flag) => {
+  const pairs = {};
+  args.forEach((arg, index) => {
+    if (arg === flag) {
+      const pair = args[index + 1];
+      pairs[pair.slice(0, pair.indexOf('='))] = pair.slice(pair.indexOf('=') + 1);
+    }
+  });
+  return pairs;
+};
+
+const readFlag = (args, flag) => args[args.indexOf(flag) + 1];
+
+let nextContainerId = 1;
+// Like a real id: hex, and never equal to a container name.
+const newContainerId = () => (nextContainerId++).toString(16).padStart(64, 'f');
+
+const volumeMountEntry = ({ volume, destination, readOnly = false }) => ({
+  Type: 'volume',
+  Name: volume,
+  Source: `/var/lib/docker/volumes/${volume}/_data`,
+  Destination: destination,
+  RW: !readOnly,
+});
+
+/**
+ * A `docker inspect` entry for a container that matches the requested hardening.
+ * `volumes` are the volumes of the space, `toolsVolume` is mounted read-only at the tools path.
+ * `mounts`, as `{ volume, destination, readOnly }`, replaces both when the test needs exact destinations.
+ * `aliases` are the network aliases on `network`, as a gatekeeper has.
+ */
+export function hardenedContainerEntry({
+  name,
+  labels,
+  network,
+  volumes = [],
+  toolsVolume = null,
+  mounts = null,
+  env = ['HOME=/home/space'],
+  running = true,
+  memoryBytes = 4294967296,
+  tmpfs = '/tmp:rw,exec,nosuid,size=256m',
+  aliases = [],
+}) {
+  const mountList = mounts ?? [
+    ...volumes.map((volume) => ({ volume, destination: `/mnt/${volume}` })),
+    ...(toolsVolume ? [{ volume: toolsVolume, destination: TOOLS_MOUNT_PATH, readOnly: true }] : []),
+  ];
+  const [tmpfsPath, tmpfsOptions] = String(tmpfs).split(':');
+  return {
+    Id: newContainerId(),
+    Name: `/${name}`,
+    State: { Running: running, Status: running ? 'running' : 'created' },
+    Config: { User: '1000:1000', Labels: labels, Env: env },
+    HostConfig: {
+      ReadonlyRootfs: true,
+      Privileged: false,
+      CapDrop: ['ALL'],
+      CapAdd: null,
+      SecurityOpt: ['no-new-privileges'],
+      Init: true,
+      PidsLimit: 512,
+      Memory: memoryBytes,
+      MemorySwap: memoryBytes,
+      ShmSize: 67108864,
+      LogConfig: { Type: 'local', Config: { compress: 'false', 'max-file': '1', 'max-size': '10m' } },
+      Tmpfs: { [tmpfsPath]: tmpfsOptions },
+      Binds: null,
+      VolumesFrom: null,
+      PidMode: '',
+      IpcMode: 'private',
+      UTSMode: '',
+      UsernsMode: '',
+      CgroupnsMode: 'private',
+      NetworkMode: network,
+      Runtime: 'runc',
+      Devices: [],
+      PortBindings: {},
+    },
+    Mounts: mountList.map(volumeMountEntry),
+    NetworkSettings: { Networks: { [network]: aliases.length > 0 ? { Aliases: aliases } : {} } },
+  };
+}
+
+/** A `docker network inspect` entry for an internal network with no address on the host. */
+export const internalNetworkEntry = ({ name, labels, options = { [ISOLATED_GATEWAY_OPTION]: 'isolated' } }) => ({
+  Name: name,
+  Internal: true,
+  EnableIPv6: false,
+  // Like the real engine: no gateway address in isolated mode.
+  IPAM: { Config: [options[ISOLATED_GATEWAY_OPTION] === 'isolated' ? { Subnet: '172.19.0.0/16' } : { Subnet: '172.19.0.0/16', Gateway: '172.19.0.1' }] },
+  Options: options,
+  Labels: labels,
+});
+
+/** A `docker network inspect` entry for an ordinary bridge, as the outer network of a space is. */
+export const bridgeNetworkEntry = ({ name, labels }) => ({
+  Name: name,
+  Internal: false,
+  EnableIPv6: false,
+  IPAM: { Config: [{ Subnet: '172.20.0.0/16', Gateway: '172.20.0.1' }] },
+  Options: {},
+  Labels: labels,
+});
+
+const HEALTHY_ANSWER = 'HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\r\n{"status":"ok","isOpenCodeReady":true}';
+const jsonAnswer = (body) => `HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\r\n${body}`;
+const CONTROL_ANSWERS = {
+  '/health': jsonAnswer('{"ready":true,"mode":"allowlist","domains":0,"grants":0}'),
+  '/journal': jsonAnswer('{"records":[],"dropped":0}'),
+  '/network': jsonAnswer('{"ok":true}'),
+  '/grants': jsonAnswer('{"ok":true}'),
+};
+
+const roleOf = (args) => readPairs(args, '--label')['openchamber.space.role'];
+
+const readMounts = (args) => args
+  .filter((arg, index) => args[index - 1] === '--mount')
+  .map((arg) => {
+    const fields = arg.split(',');
+    const field = (name) => fields.find((part) => part.startsWith(`${name}=`)).slice(name.length + 1);
+    return { volume: field('src'), destination: field('dst'), readOnly: fields.includes('readonly') };
+  });
+
+/**
+ * `failAt(args)` returns true for the call that must fail. `timeoutAt(args)` returns
+ * true for the call whose CLI is killed by the timeout: the runner rejects, and the
+ * daemon finishes the step later, when the place calls `wait`. `interruptionCode` is the
+ * code of that rejection. `resources` seeds
+ * existing containers, networks and volumes as `{ kind, name, entry }`. A seeded tools volume
+ * with `filled: true` holds its fill marker, and a seeded home volume with `token` holds that server token.
+ * `alterContainer(entry)` changes what inspect reports for a new space container.
+ * `serverReady: false` makes the server inside every space refuse connections, and
+ * `gatekeeperReady: false` does the same for every gatekeeper's control channel.
+ * `start` is where the clock of `now()` begins. `wait(ms)` moves that clock, so nothing here sleeps.
+ * `beforeFill()` runs before a tools fill ends, so a test can hold it open.
+ */
+export function createFakeDocker({
+  failAt = () => false,
+  timeoutAt = () => false,
+  interruptionCode = 'command_timeout',
+  resources = [],
+  imagePresent = true,
+  alterContainer = (entry) => entry,
+  serverReady = true,
+  gatekeeperReady = true,
+  beforeFill = async () => {},
+  start = new Date('2026-09-20T08:00:00.000Z'),
+} = {}) {
+  let clock = start.getTime();
+  const calls = [];
+  const late = [];
+  const state = new Map(resources.map((resource) => [`${resource.kind}:${resource.name}`, resource]));
+  // Volume name to the key in its fill marker. A tools volume name ends with its key.
+  const filled = new Map(resources.filter((resource) => resource.filled).map((resource) => [resource.name, resource.name.slice(-16)]));
+  // The token is a file in the home volume, so it outlives the container.
+  const tokens = new Map(resources.filter((resource) => resource.token).map((resource) => [resource.name, resource.token]));
+  // The gatekeeper's program is a file in its tmpfs, so it is gone when the container stops.
+  const programs = new Map();
+  const homeOf = (container) => state.get(`container:${container}`)?.entry.Mounts.find((mount) => mount.Destination === SPACE_HOME)?.Name ?? container;
+  const add = (kind, name, entry) => state.set(`${kind}:${name}`, { kind, name, entry });
+  // The docker CLI takes a container name or a container id.
+  const containerKey = (nameOrId) => (state.has(`container:${nameOrId}`)
+    ? `container:${nameOrId}`
+    : Array.from(state.keys()).find((key) => key.startsWith('container:') && state.get(key).entry.Id === nameOrId));
+  const nameConflict = (name) => failed(`Error response from daemon: Conflict. The container name "/${name}" is already in use by container "${state.get(`container:${name}`).entry.Id}". You have to remove (or rename) that container to be able to reuse that name.`);
+  const ofKind = (kind) => Array.from(state.values()).filter((resource) => resource.kind === kind);
+
+  const matchesFilters = (resource, args) => {
+    const labels = (resource.kind === 'container' ? resource.entry.Config?.Labels : resource.entry.Labels) ?? {};
+    return args.every((arg, index) => {
+      if (args[index - 1] !== '--filter') return true;
+      const pair = arg.slice('label='.length);
+      return labels[pair.slice(0, pair.indexOf('='))] === pair.slice(pair.indexOf('=') + 1);
+    });
+  };
+
+  // Like the real CLI: entries that exist go to stdout even when another name is missing.
+  const inspect = (kind, names) => {
+    const keyOf = (name) => (kind === 'container' ? containerKey(name) : `${kind}:${name}`);
+    const found = names.map((name) => state.get(keyOf(name))).filter(Boolean).map((resource) => resource.entry);
+    const missing = names.filter((name) => !state.has(keyOf(name)));
+    const stdout = JSON.stringify(found);
+    return missing.length === 0 ? ok(stdout) : failed(missing.map(NOT_FOUND_TEXT[kind]).join('\n'), stdout);
+  };
+
+  const addContainer = (args, { running }) => {
+    const name = readFlag(args, '--name');
+    // Like the real engine: a name that is in use is refused, and nothing is made.
+    if (state.has(`container:${name}`)) return nameConflict(name);
+    const mounts = readMounts(args);
+    // Like the real engine: a missing `src=` volume is created on the spot, without labels.
+    for (const { volume } of mounts) {
+      if (!state.has(`volume:${volume}`)) add('volume', volume, { Name: volume, Labels: null });
+    }
+    const entry = hardenedContainerEntry({
+      name,
+      labels: readPairs(args, '--label'),
+      network: readFlag(args, '--network'),
+      mounts,
+      env: args.filter((arg, index) => args[index - 1] === '--env'),
+      running,
+      memoryBytes: Number(readFlag(args, '--memory')),
+      tmpfs: args.includes('--tmpfs') ? readFlag(args, '--tmpfs') : undefined,
+      aliases: args.includes('--network-alias') ? [readFlag(args, '--network-alias')] : [],
+    });
+    add('container', name, args[0] === 'create' ? alterContainer(entry) : entry);
+    // `docker create` prints the id of the new container.
+    return ok(`${entry.Id}\n`);
+  };
+
+  // What runs inside a space. The server inside answers once its token is there.
+  // A gatekeeper answers on its control channel once its program is there.
+  const execInside = (args, stdin) => {
+    const container = args[args.indexOf('--user') + 2];
+    const argv = args.slice(args.indexOf('--user') + 3);
+    if (!state.get(`container:${container}`)?.entry.State.Running) return failed(`Error response from daemon: container ${container} is not running`);
+    if (state.get(`container:${container}`).entry.Config.Labels?.['openchamber.space.role'] === 'gatekeeper') {
+      if (argv[0] === IMAGE_SH && argv[2].includes(`${GATEKEEPER_PROGRAM_PATH}.new`)) {
+        programs.set(container, String(stdin));
+        return ok();
+      }
+      if (argv[0] !== IMAGE_CURL) return ok();
+      if (!gatekeeperReady || !programs.has(container)) return { code: 7, stdout: '', stderr: 'curl: (7) Failed to connect' };
+      const path = Object.keys(CONTROL_ANSWERS).find((candidate) => String(stdin).includes(`${candidate}"`));
+      return path ? ok(CONTROL_ANSWERS[path]) : ok('HTTP/1.1 404 Not Found\r\n\r\n{"error":"no such control endpoint"}');
+    }
+    const home = homeOf(container);
+    if (argv[0] === IMAGE_CURL) return serverReady && tokens.has(home) ? ok(HEALTHY_ANSWER) : { code: 7, stdout: '', stderr: 'curl: (7) Failed to connect' };
+    if (argv[0] === IMAGE_SH && argv[2].includes(`${SPACE_TOKEN_PATH}.new`)) {
+      tokens.set(home, String(stdin));
+      return ok();
+    }
+    if (argv[0] === IMAGE_CAT && argv[1] === SPACE_TOKEN_PATH) return ok(`${tokens.get(home)}\n`);
+    if (argv[0] === IMAGE_SH) return ok();
+    return ok('1000\n');
+  };
+
+  // The three one-shots: volume ownership, the tools filler, and the fill marker check.
+  const runOneShot = (args, { stuck, fails }) => {
+    const role = roleOf(args);
+    const [toolsMount] = readMounts(args);
+    // Measured with CLI 29.3.0: a docker CLI that cannot reach the daemon exits with 1.
+    if (role === 'tools-check' && fails) return failed('failed to connect to the docker API at tcp://127.0.0.1:1');
+    if (role === 'tools-check') {
+      // The check script exits with 42 for a missing marker, and prints the marker otherwise.
+      const key = filled.get(toolsMount.volume);
+      return key ? ok(key) : { code: 42, stdout: '', stderr: '' };
+    }
+    // The one-shot removes itself when it ends. A stuck one is still there.
+    const result = addContainer(args, { running: true });
+    if (result.code !== 0) return result;
+    if (!stuck) state.delete(`container:${readFlag(args, '--name')}`);
+    if (fails) return failed('Error response from daemon: simulated failure');
+    if (role === 'tools-fill' && !stuck) filled.set(toolsMount.volume, readPairs(args, '--label')['openchamber.space.tools.key']);
+    return result;
+  };
+
+  const answer = (args, { stuck = false, fails = false, stdin = '' } = {}) => {
+    const [first, second] = args;
+    if (first === 'run') return runOneShot(args, { stuck, fails });
+    // A failed `docker create` can still leave the container behind.
+    if (first === 'create') return fails ? (addContainer(args, { running: false }), failed('Error response from daemon: simulated failure')) : addContainer(args, { running: false });
+    if (fails) return failed('Error response from daemon: simulated failure');
+    if (first === 'inspect') return inspect('container', args.slice(3));
+    if (first === 'image' && second === 'inspect') return imagePresent ? ok('[{}]') : failed(NOT_FOUND_TEXT.image(args[2]), '[]');
+    if (first === 'pull') return ok();
+    if (first === 'ps') return ok(ofKind('container').filter((resource) => matchesFilters(resource, args)).map((resource) => resource.name).join('\n'));
+    if (first === 'rm') {
+      const name = args[args.length - 1];
+      // Like the real engine: without --force a running container stays.
+      if (!args.includes('--force') && state.get(containerKey(name))?.entry.State.Running) {
+        return failed(`Error response from daemon: cannot remove container "/${name}": container is running: stop the container before removing or force remove`);
+      }
+      return state.delete(containerKey(name)) ? ok(name) : failed(NOT_FOUND_TEXT.container(name));
+    }
+    if (first === 'stop' || first === 'start') {
+      const resource = state.get(containerKey(second));
+      if (!resource) return failed(NOT_FOUND_TEXT.container(second));
+      resource.entry.State.Running = first === 'start';
+      // A tmpfs is empty again after a stop, so the gatekeeper's program is gone with it.
+      if (first === 'stop') programs.delete(resource.name);
+      return ok(second);
+    }
+    if (first === 'rename') {
+      const [, from, to] = args;
+      const resource = state.get(`container:${from}`);
+      if (!resource) return failed(NOT_FOUND_TEXT.container(from));
+      if (state.has(`container:${to}`)) return nameConflict(to);
+      state.delete(`container:${from}`);
+      add('container', to, { ...resource.entry, Name: `/${to}` });
+      return ok();
+    }
+    if (first === 'exec') return execInside(args, stdin);
+    if (first === 'network' && second === 'connect') {
+      const [, , network, container] = args;
+      const resource = state.get(containerKey(container));
+      if (!resource) return failed(NOT_FOUND_TEXT.container(container));
+      if (!state.has(`network:${network}`)) return failed(NOT_FOUND_TEXT.network(network));
+      resource.entry.NetworkSettings.Networks[network] = {};
+      return ok();
+    }
+    if (first === 'network' || first === 'volume') {
+      const name = args[args.length - 1];
+      if (second === 'inspect') return inspect(first, args.slice(2));
+      if (second === 'ls') return ok(ofKind(first).filter((resource) => matchesFilters(resource, args)).map((resource) => resource.name).join('\n'));
+      if (second === 'rm') {
+        // Like the real engine: a volume that a container mounts cannot go.
+        const user = first === 'volume' && ofKind('container').find((resource) => resource.entry.Mounts.some((mount) => mount.Name === name));
+        if (user) return failed(`Error response from daemon: remove ${name}: volume is in use - [${user.name}]`);
+        filled.delete(name);
+        tokens.delete(name);
+        return state.delete(`${first}:${name}`) ? ok(name) : failed(NOT_FOUND_TEXT[first](name));
+      }
+      if (second === 'create') {
+        const labels = readPairs(args, '--label');
+        if (first === 'volume') {
+          add(first, name, { Name: name, Labels: labels });
+        } else {
+          add(first, name, args.includes('--internal')
+            ? internalNetworkEntry({ name, labels, options: readPairs(args, '--opt') })
+            : bridgeNetworkEntry({ name, labels }));
+        }
+        return ok(name);
+      }
+    }
+    throw new Error(`fake docker has no answer for: ${args.join(' ')}`);
+  };
+
+  const runCommand = async (file, args, options) => {
+    calls.push({ file, args, options });
+    if (timeoutAt(args)) {
+      late.push(args);
+      throw new SpaceError(interruptionCode, `docker ${args[0]} was stopped before it finished`);
+    }
+    if (args[0] === 'run' && roleOf(args) === 'tools-fill') await beforeFill();
+    return answer(args, { fails: failAt(args), stdin: options?.stdin });
+  };
+
+  /** Give this to the place as `wait`. Time passes, the daemon finishes the timed-out steps, and a one-shot stays running. */
+  const wait = async (milliseconds = 0) => {
+    clock += milliseconds;
+    for (const args of late.splice(0)) {
+      answer(args, { stuck: true });
+    }
+  };
+
+  return {
+    runCommand,
+    wait,
+    /** Give this to the place as `now`. */
+    now: () => new Date(clock),
+    calls,
+    names: () => Array.from(state.keys()),
+    token: (container) => tokens.get(homeOf(container)),
+  };
+}

package/server/lib/spaces/places/memory-place.js

@@ -0,0 +1,103 @@
+// Test support. A place that keeps spaces in a Map, for the contract suite and the manager tests.
+//
+// It models the two containers of a space, the space and its gatekeeper, because the contract
+// suite is meant to fail a place that has no gatekeeper. A place that answered both targets from
+// one container would pass nothing here.
+
+import crypto from 'node:crypto';
+
+import { SpaceError } from '../errors.js';
+import { ROLE_GATEKEEPER, ROLE_SPACE, requireSpaceId } from '../labels.js';
+
+const TARGETS = [ROLE_SPACE, ROLE_GATEKEEPER];
+
+// What `execArgv` hands out: a one-line Node program that answers for one container, the way
+// `exec` below does. The container's hostname is its first argument and the command follows.
+// One line, because the argv may go into a git `ext::` URL, which cannot carry a newline.
+const CONTAINER_PROGRAM = [
+  'const [hostname, ...command] = process.argv.slice(1);',
+  'const line = command.join(" ");',
+  'if (line === "cat /etc/hostname") process.stdout.write(hostname + "\\n");',
+  'else process.exitCode = 127;',
+].join(' ');
+
+export function createMemoryPlace({ id = 'memory' } = {}) {
+  const spaces = new Map();
+  // Every container of every space that was ever made here, by `<space id>:<role>`.
+  const containers = new Map();
+
+  const requireSpace = (spaceId) => {
+    const space = spaces.get(requireSpaceId(spaceId));
+    if (!space) {
+      throw new SpaceError('space_not_found', `Space ${spaceId} does not exist`);
+    }
+    return space;
+  };
+
+  const requireContainer = (spaceId, target = ROLE_SPACE) => {
+    if (!TARGETS.includes(target)) {
+      throw new SpaceError('invalid_exec_target', `A command runs in the space or in its gatekeeper, not in '${target}'`);
+    }
+    const container = containers.get(`${requireSpaceId(spaceId)}:${target}`);
+    if (!container) {
+      throw new SpaceError(target === ROLE_GATEKEEPER ? 'gatekeeper_missing' : 'space_not_found', `Space ${spaceId} has no ${target} container`);
+    }
+    return container;
+  };
+
+  return {
+    id,
+    check: async () => ({ available: true, version: 'memory', os: 'none', arch: 'none', hostIsolation: true }),
+    create: async ({ id: spaceId, name, project, created }) => {
+      if (spaces.has(requireSpaceId(spaceId))) {
+        throw new SpaceError('space_name_taken', `Space ${spaceId} already exists`);
+      }
+      spaces.set(spaceId, { id: spaceId, name, project, created, state: 'running', orphans: [], damaged: false, missing: [] });
+      for (const target of TARGETS) {
+        // A container has a hostname of its own, as a real one does, so a caller can tell them apart.
+        containers.set(`${spaceId}:${target}`, { hostname: crypto.randomBytes(6).toString('hex') });
+      }
+    },
+    list: async () => Array.from(spaces.values(), (space) => ({ ...space })),
+    exec: async (spaceId, argv, options = {}) => {
+      // The container, and not the space record: a place that removed the space and left its
+      // gatekeeper running would still answer here, and the contract suite must see that.
+      const container = requireContainer(spaceId, options.target);
+      const command = argv.join(' ');
+      if (command === 'id -u') {
+        return { code: 0, stdout: '1000\n', stderr: '' };
+      }
+      if (command === 'cat /etc/hostname') {
+        return { code: 0, stdout: `${container.hostname}\n`, stderr: '' };
+      }
+      // The work directory of the space is in the space and not in its gatekeeper.
+      if (command === `test -d /spaces/${spaceId}`) {
+        return { code: options.target === ROLE_GATEKEEPER ? 1 : 0, stdout: '', stderr: '' };
+      }
+      return { code: 127, stdout: '', stderr: 'not found' };
+    },
+    // Added in stage 3a. The space container only, and refused like `exec` when it is gone.
+    execArgv: async (spaceId) => {
+      const { hostname } = requireContainer(spaceId);
+      if (requireSpace(spaceId).state !== 'running') {
+        throw new SpaceError('space_not_running', `Space ${spaceId} is stopped`);
+      }
+      return [process.execPath, '-e', CONTAINER_PROGRAM, hostname];
+    },
+    stop: async (spaceId) => { requireSpace(spaceId).state = 'exited'; },
+    start: async (spaceId) => { requireSpace(spaceId).state = 'running'; },
+    remove: async (spaceId) => {
+      const removed = [];
+      for (const target of TARGETS) {
+        if (containers.delete(`${requireSpaceId(spaceId)}:${target}`)) removed.push({ kind: 'container', name: `${spaceId}-${target}` });
+      }
+      if (spaces.delete(spaceId)) removed.push({ kind: 'space', name: spaceId });
+      return { removed, failed: [] };
+    },
+    verify: async (spaceId) => {
+      requireSpace(spaceId);
+      requireContainer(spaceId, ROLE_GATEKEEPER);
+      return [];
+    },
+  };
+}

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

@@ -0,0 +1,77 @@
+// A development build inside a space: the local `web` and `sdk` packages, packed and installed
+// by the filler. Runs only with OPENCHAMBER_TEST_DOCKER_PACKED=1, because it compiles the sdk
+// and needs the workspace dependencies installed.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createSpaceId, hashProjectDirectory } from '../labels.js';
+import { TOOLS_MOUNT_PATH } from '../layout.js';
+import { runCommand } from '../run-command.js';
+import { createSpaceServerChannel } from '../space-server.js';
+import { packLocalTools } from '../tools-pack.js';
+import { createPackedToolsSource, readHostToolVersions } from '../tools.js';
+import { createLiveDockerPlace } from './docker-live-support.js';
+
+const PACKED_ENABLED = process.env.OPENCHAMBER_TEST_DOCKER_PACKED === '1';
+const CREATE_TIMEOUT_MS = 25 * 60_000;
+
+describe.skipIf(!PACKED_ENABLED)('development build inside a space: docker (live)', () => {
+  const spec = {
+    id: createSpaceId(),
+    name: 'Development build',
+    project: hashProjectDirectory('/development/build/project'),
+    created: new Date().toISOString(),
+    memoryBytes: 2 * 1024 * 1024 * 1024,
+  };
+  let directory;
+  let place;
+  let host;
+  let dispose = async () => {};
+
+  beforeAll(async () => {
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-packed-test-'));
+    const tarballs = await packLocalTools({ runCommand, outputDirectory: directory });
+    const toolsSource = createPackedToolsSource({ ...tarballs, openCodeVersion: readHostToolVersions().openCodeVersion });
+    ({ place, host, dispose } = createLiveDockerPlace({ toolsSource }));
+    await place.create(spec);
+  }, CREATE_TIMEOUT_MS);
+
+  afterAll(async () => {
+    await dispose();
+    if (directory) fs.rmSync(directory, { recursive: true, force: true });
+  });
+
+  it('is healthy and verifies clean', async () => {
+    const health = await createSpaceServerChannel({ exec: place.exec }).request(spec.id, { path: '/health' });
+    expect(JSON.parse(health.body)).toMatchObject({ isOpenCodeReady: true });
+    expect(await place.verify(spec.id)).toEqual([]);
+  });
+
+  it('labels the tools volume as a development build', async () => {
+    const [volume] = (await host.volumes()).filter((name) => name.startsWith('openchamber-tools-'));
+    const inspect = await runCommand('docker', ['volume', 'inspect', volume]);
+    expect(JSON.parse(inspect.stdout)[0].Labels['openchamber.space.tools.description']).toBe('development build');
+  });
+
+  it('runs the local sdk everywhere in the tree, not the published one with the same version', async () => {
+    const sdk = fs.readFileSync(new URL('../../../../../sdk/package.json', import.meta.url), 'utf8');
+    const copies = await place.exec(spec.id, ['sh', '-c', `find ${TOOLS_MOUNT_PATH}/node_modules -type d -path '*/@openchamber/sdk' -not -path '*/sdk/*'`]);
+    expect(copies.stdout).toBe(`${TOOLS_MOUNT_PATH}/node_modules/@openchamber/sdk\n`);
+
+    // The lock file names where each package came from: the sdk from the local tarball, never from the registry.
+    const lock = JSON.parse((await place.exec(spec.id, ['cat', `${TOOLS_MOUNT_PATH}/package-lock.json`])).stdout);
+    const installed = lock.packages['node_modules/@openchamber/sdk'];
+    expect(installed.version).toBe(JSON.parse(sdk).version);
+    expect(installed.resolved).toMatch(/^file:.*openchamber-sdk\.tgz$/);
+    expect(lock.packages['node_modules/@openchamber/web'].resolved).toMatch(/^file:.*openchamber-web\.tgz$/);
+  });
+
+  it('leaves the tarballs out of the volume', async () => {
+    const found = await place.exec(spec.id, ['sh', '-c', `find ${TOOLS_MOUNT_PATH} -maxdepth 1 -name '*.tgz'`]);
+    expect(found).toMatchObject({ code: 0, stdout: '' });
+  });
+});

package/server/lib/spaces/places/registry.js

@@ -0,0 +1,43 @@
+export const REQUIRED_PLACE_METHODS = ['check', 'create', 'list', 'exec', 'execArgv', 'stop', 'start', 'remove', 'verify'];
+
+export function createPlaceRegistry(initialPlaces = []) {
+  const places = new Map();
+  let sealed = false;
+
+  const register = (place) => {
+    if (sealed) {
+      throw new Error('Place registry is sealed; no further registrations allowed');
+    }
+    const key = String(place?.id ?? '').trim().toLowerCase();
+    if (key.length === 0) {
+      throw new Error('Place must define a non-empty id');
+    }
+    for (const method of REQUIRED_PLACE_METHODS) {
+      if (!(place[method] instanceof Function)) {
+        throw new Error(`Place '${key}' must implement ${method}()`);
+      }
+    }
+    if (places.has(key)) {
+      throw new Error(`Place '${key}' is already registered`);
+    }
+    places.set(key, place);
+    return place;
+  };
+
+  const get = (placeId) => places.get(String(placeId ?? '').trim().toLowerCase()) ?? null;
+
+  const list = () => Array.from(places.values());
+
+  for (const place of initialPlaces) {
+    register(place);
+  }
+
+  const seal = () => { sealed = true; };
+
+  return {
+    register,
+    get,
+    list,
+    seal,
+  };
+}

package/server/lib/spaces/places/registry.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { REQUIRED_PLACE_METHODS, createPlaceRegistry } from './registry.js';
+
+const createPlace = (id) => ({
+  id,
+  ...Object.fromEntries(REQUIRED_PLACE_METHODS.map((method) => [method, async () => null])),
+});
+
+describe('createPlaceRegistry', () => {
+  it('registers places and finds them by id, ignoring case and spaces', () => {
+    const docker = createPlace('docker');
+    const registry = createPlaceRegistry([docker]);
+
+    expect(registry.get(' Docker ')).toBe(docker);
+    expect(registry.list()).toEqual([docker]);
+  });
+
+  it('returns null for an unknown or missing id', () => {
+    const registry = createPlaceRegistry([createPlace('docker')]);
+
+    expect(registry.get('cluster')).toBeNull();
+    expect(registry.get(undefined)).toBeNull();
+  });
+
+  it('rejects a place without an id', () => {
+    expect(() => createPlaceRegistry([createPlace('  ')])).toThrow('non-empty id');
+    expect(() => createPlaceRegistry([null])).toThrow('non-empty id');
+  });
+
+  it.each(REQUIRED_PLACE_METHODS)('rejects a place without %s()', (method) => {
+    const place = createPlace('docker');
+    delete place[method];
+
+    expect(() => createPlaceRegistry([place])).toThrow(`must implement ${method}()`);
+  });
+
+  it('rejects a second place with the same id', () => {
+    const registry = createPlaceRegistry([createPlace('docker')]);
+
+    expect(() => registry.register(createPlace('DOCKER'))).toThrow('already registered');
+  });
+
+  it('accepts nothing after it is sealed', () => {
+    const registry = createPlaceRegistry();
+    registry.seal();
+
+    expect(() => registry.register(createPlace('docker'))).toThrow('sealed');
+  });
+});