@agentshouse/kit 0.1.0-alpha.9 → 0.2.1-alpha.1

package/src/workspace.js

@@ -1,500 +0,0 @@
-import { access, mkdir, readFile, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { readConfiguration } from "./configuration.js";
-import {
-  CGROUP_CONTROLLERS,
-  HOST_MOUNT_INFO,
-  LOOP_CONTROL,
-  WORKSPACE_ACQUIRE_MAX,
-  WORKSPACE_COMMAND_TIMEOUT_MS,
-  WORKSPACE_DISK_IMAGE,
-  WORKSPACE_DISK_MOUNT,
-  WORKSPACE_KIT_HOME,
-  WORKSPACE_MOUNT_OPTIONS,
-  WORKSPACE_LABEL,
-  WORKSPACE_MOUNT,
-  WORKSPACE_OPERATION_WITHDRAWN,
-  WORKSPACE_POLL_MS,
-  WORKSPACE_READY_ATTEMPTS,
-  WORKSPACE_READY_POLL_MS,
-  WORKSPACE_STOP_TIMEOUT_SECONDS,
-  WORKSPACE_SYSTEM_RESERVE_BYTES,
-} from "./contract.js";
-import { runCommand } from "./command.js";
-import {
-  acquireWorkspaces,
-  maintainControl,
-  openSession,
-  releaseControl,
-  reportWorkspaceOutcome,
-} from "./house.js";
-import { KitRefusal } from "./refusal.js";
-
-const REQUIRED_CONTROLLERS = ["cpu", "memory"];
-const MEMINFO = "/proc/meminfo";
-const MEM_AVAILABLE = /^MemAvailable:\s+(\d+)\s+kB$/m;
-
-export function workspaceIdentity(operation) {
-  return `house-kit-${operation.name}-${operation.environment.slice(0, 8)}`;
-}
-
-export function workspaceEnforcement(maxima) {
-  return [
-    `cgroup-v2 cpu.max at ${maxima.cpu_millicores} millicores`,
-    `memory.max and swap at ${maxima.memory_bytes} bytes`,
-    `dedicated ext4 image of ${maxima.disk_bytes} bytes mounted as the only writable workspace`,
-  ].join(", ");
-}
-
-export function workspaceDirectory(root, identity) {
-  return join(root, identity);
-}
-
-export function workspaceImagePath(root, identity) {
-  return join(root, identity, WORKSPACE_DISK_IMAGE);
-}
-
-export function workspaceMountPath(root, identity) {
-  return join(root, identity, WORKSPACE_DISK_MOUNT);
-}
-
-export function workspaceMountArguments(root, identity, image) {
-  return [
-    "run",
-    "--rm",
-    "--privileged",
-    "--pid=host",
-    "--entrypoint",
-    "nsenter",
-    image,
-    "-t",
-    "1",
-    "-m",
-    "--",
-    "mount",
-    "-o",
-    WORKSPACE_MOUNT_OPTIONS,
-    workspaceImagePath(root, identity),
-    workspaceMountPath(root, identity),
-  ];
-}
-
-export function workspaceUnmountArguments(root, identity, image) {
-  return [
-    "run",
-    "--rm",
-    "--privileged",
-    "--pid=host",
-    "--entrypoint",
-    "nsenter",
-    image,
-    "-t",
-    "1",
-    "-m",
-    "--",
-    "umount",
-    workspaceMountPath(root, identity),
-  ];
-}
-
-export function mountedPaths(document) {
-  return new Set(
-    document
-      .split("\n")
-      .map((line) => line.split(" ")[4])
-      .filter((target) => target !== undefined && target !== ""),
-  );
-}
-
-export function workspaceCreateArguments(identity, operation, image, house, root) {
-  return [
-    "create",
-    "--name",
-    identity,
-    "--label",
-    `${WORKSPACE_LABEL}=${operation.environment}`,
-    "--cpus",
-    (operation.maxima.cpu_millicores / 1000).toFixed(3),
-    "--memory",
-    `${operation.maxima.memory_bytes}b`,
-    "--memory-swap",
-    `${operation.maxima.memory_bytes}b`,
-    "--restart",
-    "no",
-    "--mount",
-    `type=bind,source=${workspaceMountPath(root, identity)},target=${WORKSPACE_MOUNT}`,
-    "--env",
-    `HOUSE_KIT_HOME=${WORKSPACE_KIT_HOME}`,
-    "--env",
-    `HOUSE_KIT_HOUSE=${house}`,
-    "--workdir",
-    WORKSPACE_MOUNT,
-    image,
-  ];
-}
-
-export function memoryAvailable(document) {
-  const found = MEM_AVAILABLE.exec(document);
-  if (found === null) throw new KitRefusal("kit_host_unmeasurable", MEMINFO);
-  return Number(found[1]) * 1024;
-}
-
-function adapter(dependencies) {
-  return {
-    run: dependencies.run ?? runCommand,
-    read: dependencies.readFile ?? ((path) => readFile(path, "utf8")),
-    reachable: dependencies.access ?? access,
-    make: dependencies.mkdir ?? mkdir,
-    remove: dependencies.rm ?? rm,
-    wait: dependencies.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
-  };
-}
-
-async function docker(host, args, stdin = "") {
-  return host.run({
-    command: ["docker", ...args],
-    environment: {},
-    stdin,
-    timeoutMs: WORKSPACE_COMMAND_TIMEOUT_MS,
-  });
-}
-
-export async function workspacePrerequisites(host, image) {
-  let controllers;
-  try {
-    controllers = await host.read(CGROUP_CONTROLLERS);
-  } catch {
-    return { supported: false, refusal: `${CGROUP_CONTROLLERS} is absent, so no cgroup v2 ceiling can be applied` };
-  }
-  const present = controllers.trim().split(/\s+/);
-  const missing = REQUIRED_CONTROLLERS.filter((controller) => !present.includes(controller));
-  if (missing.length > 0) {
-    return {
-      supported: false,
-      refusal: `the cgroup v2 controllers ${missing.join(" and ")} are not delegated to this host`,
-    };
-  }
-  try {
-    await host.reachable(LOOP_CONTROL);
-  } catch {
-    return {
-      supported: false,
-      refusal: `${LOOP_CONTROL} is absent, so no workspace volume can carry an enforced size`,
-    };
-  }
-  const version = await docker(host, ["version", "--format", "{{.Server.Version}}"]);
-  if (version.status !== 0 || version.stdout.trim() === "") {
-    return { supported: false, refusal: "the container runtime daemon did not answer a version" };
-  }
-  const formatter = await docker(host, [
-    "run",
-    "--rm",
-    "--entrypoint",
-    "sh",
-    image,
-    "-c",
-    "command -v mkfs.ext4",
-  ]);
-  if (formatter.status !== 0) {
-    return {
-      supported: false,
-      refusal: `the declared workspace image ${image} carries no mkfs.ext4, so no volume ceiling can be created`,
-    };
-  }
-  return { supported: true, runtime: `docker ${version.stdout.trim()}` };
-}
-
-function bootstrapConfiguration() {
-  return JSON.stringify({
-    availability: "continuous",
-    execution_authority: "allow",
-    migrators: [],
-    instances: [],
-    clients: [],
-    host: null,
-  });
-}
-
-function provisionArguments(root, identity, image, target, mode) {
-  return [
-    "run",
-    "--rm",
-    "--interactive",
-    "--mount",
-    `type=bind,source=${workspaceMountPath(root, identity)},target=${WORKSPACE_MOUNT}`,
-    "--entrypoint",
-    "sh",
-    image,
-    "-c",
-    `set -e; mkdir -p ${WORKSPACE_KIT_HOME}; chmod 700 ${WORKSPACE_KIT_HOME}; cat > ${target}; chmod ${mode} ${target}`,
-  ];
-}
-
-async function provisionWorkspaceState(host, root, identity, image, authority) {
-  for (const [target, mode, content] of [
-    [`${WORKSPACE_KIT_HOME}/credential`, "600", `${authority.credential}\n`],
-    [`${WORKSPACE_KIT_HOME}/kit.json`, "600", `${bootstrapConfiguration()}\n`],
-  ]) {
-    const written = await docker(
-      host,
-      provisionArguments(root, identity, image, target, mode),
-      content,
-    );
-    if (written.status !== 0) {
-      throw new KitRefusal("kit_workspace_unprovisioned", written.stderr.trim() || identity);
-    }
-  }
-}
-
-export async function workspaceMounted(host, root, identity) {
-  const target = workspaceMountPath(root, identity);
-  return mountedPaths(await host.read(HOST_MOUNT_INFO)).has(target);
-}
-
-async function mountWorkspace(host, settings, identity) {
-  if (await workspaceMounted(host, settings.root, identity)) return null;
-  const mounted = await docker(
-    host,
-    workspaceMountArguments(settings.root, identity, settings.image),
-  );
-  if (mounted.status !== 0) {
-    return `the workspace disk could not be mounted at its ceiling: ${mounted.stderr.trim()}`;
-  }
-  return null;
-}
-
-export async function createWorkspace(host, settings, operation) {
-  const prerequisites = await workspacePrerequisites(host, settings.image);
-  if (!prerequisites.supported) {
-    return { outcome: "unsupported", refusal: prerequisites.refusal };
-  }
-  const identity = workspaceIdentity(operation);
-  await host.make(workspaceMountPath(settings.root, identity), { recursive: true });
-  const formatted = await docker(host, [
-    "run",
-    "--rm",
-    "--mount",
-    `type=bind,source=${workspaceDirectory(settings.root, identity)},target=/image`,
-    "--entrypoint",
-    "sh",
-    settings.image,
-    "-c",
-    `set -e; rm -f /image/${WORKSPACE_DISK_IMAGE}; truncate -s ${operation.maxima.disk_bytes} /image/${WORKSPACE_DISK_IMAGE}; mkfs.ext4 -q -F /image/${WORKSPACE_DISK_IMAGE}`,
-  ]);
-  if (formatted.status !== 0) {
-    return {
-      outcome: "unsupported",
-      refusal: `the workspace disk image could not be created at its declared ceiling: ${formatted.stderr.trim()}`,
-    };
-  }
-  const mountRefusal = await mountWorkspace(host, settings, identity);
-  if (mountRefusal !== null) return { outcome: "unsupported", refusal: mountRefusal };
-  if (operation.authority !== undefined) {
-    await provisionWorkspaceState(host, settings.root, identity, settings.image, operation.authority);
-  }
-  const created = await docker(
-    host,
-    workspaceCreateArguments(identity, operation, settings.image, settings.house, settings.root),
-  );
-  if (created.status !== 0) {
-    return { outcome: "failed", refusal: `the workspace was refused: ${created.stderr.trim()}` };
-  }
-  return {
-    outcome: "stopped",
-    workspace: identity,
-    runtime: prerequisites.runtime,
-    enforcement: workspaceEnforcement(operation.maxima),
-  };
-}
-
-async function workspacePresent(host, identity) {
-  const inspected = await docker(host, ["container", "inspect", "--format", "{{.State.Status}}", identity]);
-  return inspected.status === 0 ? inspected.stdout.trim() : null;
-}
-
-export async function startWorkspace(host, settings, operation) {
-  const identity = operation.workspace ?? workspaceIdentity(operation);
-  if ((await workspacePresent(host, identity)) === null) return { outcome: "absent" };
-  const available = memoryAvailable(await host.read(MEMINFO));
-  if (available - operation.maxima.memory_bytes < WORKSPACE_SYSTEM_RESERVE_BYTES) {
-    return {
-      outcome: "failed",
-      refusal: `starting this workspace would leave less than the ${WORKSPACE_SYSTEM_RESERVE_BYTES} byte host reserve`,
-    };
-  }
-  const mountRefusal = await mountWorkspace(host, settings, identity);
-  if (mountRefusal !== null) return { outcome: "unsupported", refusal: mountRefusal };
-  const started = await docker(host, ["start", identity]);
-  if (started.status !== 0) {
-    return { outcome: "failed", refusal: `the workspace did not start: ${started.stderr.trim()}` };
-  }
-  const prerequisites = await workspacePrerequisites(host, settings.image);
-  if (!prerequisites.supported) {
-    return { outcome: "unsupported", refusal: prerequisites.refusal };
-  }
-  for (let attempt = 0; attempt < WORKSPACE_READY_ATTEMPTS; attempt += 1) {
-    const ready = await docker(host, [
-      "exec",
-      identity,
-      "sh",
-      "-c",
-      `test -d ${WORKSPACE_KIT_HOME}`,
-    ]);
-    if (ready.status === 0) {
-      return {
-        outcome: "ready",
-        workspace: identity,
-        runtime: prerequisites.runtime,
-        enforcement: workspaceEnforcement(operation.maxima),
-      };
-    }
-    if ((await workspacePresent(host, identity)) === null) return { outcome: "absent" };
-    await host.wait(WORKSPACE_READY_POLL_MS);
-  }
-  return { outcome: "failed", refusal: "the workspace never proved it accepts execution" };
-}
-
-export async function stopWorkspace(host, operation) {
-  const identity = operation.workspace ?? workspaceIdentity(operation);
-  if ((await workspacePresent(host, identity)) === null) return { outcome: "absent" };
-  const stopped = await docker(host, [
-    "stop",
-    "--timeout",
-    String(WORKSPACE_STOP_TIMEOUT_SECONDS),
-    identity,
-  ]);
-  if (stopped.status !== 0) {
-    return { outcome: "failed", refusal: `the workspace did not stop: ${stopped.stderr.trim()}` };
-  }
-  return {
-    outcome: "stopped",
-    workspace: identity,
-    runtime: operation.runtime ?? "docker",
-    enforcement: workspaceEnforcement(operation.maxima),
-  };
-}
-
-export async function deleteWorkspace(host, settings, operation) {
-  const identity = operation.workspace ?? workspaceIdentity(operation);
-  const present = await workspacePresent(host, identity);
-  const removed = present === null ? { status: 0 } : await docker(host, ["rm", "--force", identity]);
-  if (removed.status !== 0) {
-    return { outcome: "failed", refusal: `the workspace was not removed: ${removed.stderr.trim()}` };
-  }
-  if (await workspaceMounted(host, settings.root, identity)) {
-    const unmounted = await docker(
-      host,
-      workspaceUnmountArguments(settings.root, identity, settings.image),
-    );
-    if (unmounted.status !== 0) {
-      return {
-        outcome: "failed",
-        refusal: `the workspace disk was not unmounted: ${unmounted.stderr.trim()}`,
-      };
-    }
-  }
-  await host.remove(workspaceDirectory(settings.root, identity), { recursive: true, force: true });
-  return { outcome: "removed" };
-}
-
-export async function managedWorkspaces(host) {
-  const listed = await docker(host, [
-    "ps",
-    "--all",
-    "--filter",
-    `label=${WORKSPACE_LABEL}`,
-    "--format",
-    `{{.Names}} {{.Label "${WORKSPACE_LABEL}"}} {{.State}}`,
-  ]);
-  if (listed.status !== 0) {
-    throw new KitRefusal("kit_workspace_inventory_unavailable", listed.stderr.trim() || null);
-  }
-  return listed.stdout
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line !== "")
-    .map((line) => {
-      const [name, environment, state] = line.split(/\s+/);
-      return { name, environment, state };
-    });
-}
-
-export async function reconcileWorkspaces(host, authorized) {
-  const expected = new Map(
-    authorized.map((workspace) => [workspace.environment, workspace.expected]),
-  );
-  const stopped = [];
-  for (const managed of await managedWorkspaces(host)) {
-    if (managed.state !== "running") continue;
-    if (expected.get(managed.environment) === "running") continue;
-    const settled = await docker(host, [
-      "stop",
-      "--timeout",
-      String(WORKSPACE_STOP_TIMEOUT_SECONDS),
-      managed.name,
-    ]);
-    if (settled.status === 0) stopped.push(managed.name);
-  }
-  return stopped;
-}
-
-export async function performOperation(host, settings, operation) {
-  if (operation.kind === "create") return createWorkspace(host, settings, operation);
-  if (operation.kind === "start") return startWorkspace(host, settings, operation);
-  if (operation.kind === "stop") return stopWorkspace(host, operation);
-  return deleteWorkspace(host, settings, operation);
-}
-
-export async function serveWorkspaces(options, dependencies = {}) {
-  const configuration = await readConfiguration(options.configuration);
-  if (configuration.host === null || configuration.host.image === null) {
-    throw new KitRefusal("kit_workspace_host_unconfigured", options.configuration);
-  }
-  const host = adapter(dependencies);
-  const settings = {
-    root: configuration.host.workspace,
-    image: configuration.host.image,
-    house: options.house,
-  };
-  const session = await openSession(options, dependencies);
-  const settled = [];
-  const withdrawn = [];
-  let reconciled = [];
-  const passes = options.passes ?? Number.POSITIVE_INFINITY;
-  for (let pass = 0; pass < passes; pass += 1) {
-    const work = await maintainControl(
-      session,
-      async (signal) => {
-        const acquired = await acquireWorkspaces(session, WORKSPACE_ACQUIRE_MAX, signal);
-        reconciled = await reconcileWorkspaces(host, acquired.workspaces);
-        for (const operation of acquired.operations) {
-          let report;
-          try {
-            report = await performOperation(host, settings, operation);
-          } catch (error) {
-            if (!(error instanceof KitRefusal)) throw error;
-            report = { outcome: "failed", refusal: error.message };
-          }
-          try {
-            await reportWorkspaceOutcome(session, operation.operation, report, signal);
-          } catch (error) {
-            if (!(error instanceof KitRefusal) || error.code !== WORKSPACE_OPERATION_WITHDRAWN) {
-              throw error;
-            }
-            withdrawn.push({ operation: operation.operation, kind: operation.kind });
-            continue;
-          }
-          settled.push({ operation: operation.operation, kind: operation.kind, ...report });
-        }
-        return acquired;
-      },
-      options.signal,
-      { release: false },
-    );
-    if (pass + 1 < passes && work.operations.length === 0) {
-      await host.wait(WORKSPACE_POLL_MS);
-    }
-  }
-  await releaseControl(session);
-  return { settled, reconciled, withdrawn };
-}