@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/workspace.js

@@ -0,0 +1,500 @@
+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 };
+}