hyperbrane 0.1.1 → 0.2.0

package/dist/cli/table.js

@@ -1,4 +1,3 @@
-// Output in the style of the docker CLI (its tabwriter: min width 10, padding 3).
 const MIN_WIDTH = 10;
 const PADDING = 3;
 export function formatTable(headers, rows) {
@@ -11,7 +10,6 @@ export function formatTable(headers, rows) {
         .join("\n");
 }
 const BYTE_UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
-/** 268435456 -> "256MiB", 1597440 -> "1.523MiB" (docker's units.BytesSize). */
 export function formatBytes(bytes) {
     let value = bytes;
     let unit = 0;
@@ -21,11 +19,9 @@ export function formatBytes(bytes) {
     }
     return `${Number(value.toPrecision(4))}${BYTE_UNITS[unit]}`;
 }
-/** 0.0512 cores -> "5.12%" (docker stats' CPU %: 100% is one full core). */
 export function formatCpuPercent(cores) {
     return `${(cores * 100).toFixed(2)}%`;
 }
-/** Seconds -> "3 minutes", "About an hour", ... (docker's units.HumanDuration). */
 export function formatDuration(seconds) {
     const minutes = seconds / 60;
     const hours = minutes / 60;

package/dist/dimension/api.d.ts

@@ -1,27 +1,19 @@
+export { dimensionLayout } from "./paths.ts";
 export type MemoryLimit = number & {
     readonly __brand: "MemoryLimit";
 };
 export type CPULimit = number & {
     readonly __brand: "CPULimit";
 };
-/** Bytes. Accepts "512", "10M", "1.5G", "10Mi", "10MB", "10MiB" (binary units, like docker). */
 export declare function MemoryLimit(value: string): MemoryLimit;
-/** Cores. Accepts "2", "0.5", or kubernetes-style millicores "500m". */
 export declare function CPULimit(value: string): CPULimit;
 export type Dimension = {
     name: string;
-    /**
-     * The host directory mounted as its workspace. Relative ("work", "~/work") is the host user's,
-     * under their home: resolved when the dimension is created, and recorded resolved. Made (by the
-     * host user) if it doesn't exist.
-     */
     directory: string;
     memoryLimit: MemoryLimit;
     cpuLimit: CPULimit;
     portals?: string[];
 };
-/** "creating": provisioning in progress. "missing": recorded but no container (retry create). Otherwise docker's container state. */
-/** What `updateDimension` can change on a running dimension; omitted limits stay as they are. */
 export type DimensionLimits = {
     memoryLimit?: MemoryLimit;
     cpuLimit?: CPULimit;
@@ -29,40 +21,60 @@ export type DimensionLimits = {
 export type DimensionStatus = "creating" | "missing" | "created" | "running" | "paused" | "restarting" | "removing" | "exited" | "dead";
 export type DimensionInfo = Dimension & {
     readonly status: DimensionStatus;
-    /** Null unless running. */
     readonly uptimeSeconds: number | null;
-    /** Bytes. Null unless running. */
-    readonly memoryUsage: number | null;
-    /** Cores. Null unless running. */
-    readonly cpuUsage: number | null;
 };
+export type DimensionFileInfo = {
+    readonly type: "file" | "directory" | "other";
+    readonly size: number;
+};
+export type DimensionUsage = {
+    readonly name: string;
+    readonly memoryUsage: number;
+    readonly cpuUsage: number;
+};
+export declare function isDimensionName(name: string): boolean;
+export declare function dimensionShellCommand(dimensionName: string, { env, command }?: {
+    env?: Record<string, string>;
+    command?: string;
+}): string;
+export declare const DimensionState: {
+    readonly running: 0;
+    readonly stopped: 1;
+    readonly missing: 2;
+};
+export declare function dimensionStateCommand(dimensionName: string): string;
+/** @sealed */
+export interface DimensionLayout {
+    containerName(dimensionName: string): string;
+    workspacePath(): string;
+    runPath(): string;
+    statePath(): string;
+    caBundlePath(): string;
+    runDirectory(dataDirectory: string, dimensionName: string): string;
+    stateDirectory(dataDirectory: string, dimensionName: string): string;
+    transportSocketPath(dataDirectory: string, dimensionName: string): string;
+}
 /** @sealed */
 export interface DimensionClient {
-    /** POST /v1/dimensions */
     createDimension(dimension: Dimension): Promise<Dimension>;
-    /** DELETE /v1/dimensions/:dimensionName */
     destroyDimension(dimensionName: string): Promise<void>;
-    /** POST /v1/dimensions/:dimensionName/restart */
     restartDimension(dimensionName: string): Promise<void>;
-    /** PATCH /v1/dimensions/:dimensionName — changes its limits in place, without a restart. */
     updateDimension(dimensionName: string, limits: DimensionLimits): Promise<Dimension>;
-    /** GET /v1/dimensions */
     listDimensions(): Promise<DimensionInfo[]>;
+    getDimensionUsage(): Promise<DimensionUsage[]>;
+    readFile(dimensionName: string, path: string, options?: {
+        offset?: number;
+        length?: number;
+    }): Promise<ReadableStream<Uint8Array>>;
+    writeFile(dimensionName: string, path: string, data: Uint8Array | ReadableStream<Uint8Array>): Promise<void>;
+    statFile(dimensionName: string, path: string): Promise<DimensionFileInfo>;
 }
-/** The request can't be satisfied as sent (bad directory, ...). */
 export declare class DimensionInvalidError extends Error {
     name: string;
 }
-/** No dimension (or no container for it) by that name. */
 export declare class DimensionNotFoundError extends Error {
     name: string;
 }
-/** The name is taken by a dimension with a different spec, or by a container hyperbrane doesn't own. */
 export declare class DimensionConflictError extends Error {
     name: string;
 }
-export declare class DimensionApiError extends Error {
-    readonly status: number;
-    constructor(status: number, message: string);
-}
-export declare function createDimensionClient(baseUrl: string): DimensionClient;

package/dist/dimension/api.js

@@ -1,3 +1,5 @@
+import { containerName } from "./paths.js";
+export { dimensionLayout } from "./paths.js";
 const MEMORY_UNITS = {
     "": 1,
     K: 1024,
@@ -5,7 +7,6 @@ const MEMORY_UNITS = {
     G: 1024 ** 3,
     T: 1024 ** 4,
 };
-/** Bytes. Accepts "512", "10M", "1.5G", "10Mi", "10MB", "10MiB" (binary units, like docker). */
 export function MemoryLimit(value) {
     const match = /^(\d+(?:\.\d+)?)\s*([KMGT]?)(?:iB|i|B)?$/i.exec(value.trim());
     if (!match)
@@ -15,7 +16,6 @@ export function MemoryLimit(value) {
         throw new Error(`Memory limit must be positive: "${value}"`);
     return bytes;
 }
-/** Cores. Accepts "2", "0.5", or kubernetes-style millicores "500m". */
 export function CPULimit(value) {
     const match = /^(\d+(?:\.\d+)?)\s*(m?)$/.exec(value.trim());
     if (!match)
@@ -25,57 +25,38 @@ export function CPULimit(value) {
         throw new Error(`CPU limit must be positive: "${value}"`);
     return cores;
 }
-/** The request can't be satisfied as sent (bad directory, ...). */
+const DIMENSION_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$/;
+export function isDimensionName(name) {
+    return DIMENSION_NAME.test(name);
+}
+const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+function checkedContainer(dimensionName) {
+    if (!isDimensionName(dimensionName))
+        throw new DimensionInvalidError(`invalid dimension name "${dimensionName}"`);
+    return containerName(dimensionName);
+}
+export function dimensionShellCommand(dimensionName, { env = {}, command } = {}) {
+    const container = checkedContainer(dimensionName);
+    const vars = Object.entries(env).map(([name, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw new DimensionInvalidError(`invalid variable name "${name}"`);
+        return ` -e ${quote(`${name}=${value}`)}`;
+    });
+    return command === undefined
+        ? `docker exec -it${vars.join("")} ${container} bash -l`
+        : `docker exec -i${vars.join("")} ${container} bash -lc ${quote(command)}`;
+}
+export const DimensionState = { running: 0, stopped: 1, missing: 2 };
+export function dimensionStateCommand(dimensionName) {
+    const container = checkedContainer(dimensionName);
+    return `{ s="$(docker inspect -f '{{.State.Status}}' ${container} 2>/dev/null)" || exit ${DimensionState.missing}; [ "$s" = running ] || exit ${DimensionState.stopped}; }`;
+}
 export class DimensionInvalidError extends Error {
     name = "DimensionInvalidError";
 }
-/** No dimension (or no container for it) by that name. */
 export class DimensionNotFoundError extends Error {
     name = "DimensionNotFoundError";
 }
-/** The name is taken by a dimension with a different spec, or by a container hyperbrane doesn't own. */
 export class DimensionConflictError extends Error {
     name = "DimensionConflictError";
 }
-export class DimensionApiError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.status = status;
-        this.name = "DimensionApiError";
-    }
-}
-export function createDimensionClient(baseUrl) {
-    async function request(method, path, body) {
-        const res = await fetch(new URL(path, baseUrl), {
-            method,
-            headers: body === undefined ? undefined : { "content-type": "application/json" },
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
-        if (res.ok)
-            return res;
-        const text = await res.text();
-        let message = text;
-        try {
-            message = JSON.parse(text).error ?? text;
-        }
-        catch { }
-        throw new DimensionApiError(res.status, `${method} ${path} -> ${res.status}: ${message}`);
-    }
-    async function createDimension(dimension) {
-        return (await request("POST", "/v1/dimensions", dimension)).json();
-    }
-    async function destroyDimension(dimensionName) {
-        await request("DELETE", `/v1/dimensions/${encodeURIComponent(dimensionName)}`);
-    }
-    async function restartDimension(dimensionName) {
-        await request("POST", `/v1/dimensions/${encodeURIComponent(dimensionName)}/restart`);
-    }
-    async function listDimensions() {
-        return (await request("GET", "/v1/dimensions")).json();
-    }
-    async function updateDimension(dimensionName, limits) {
-        return (await request("PATCH", `/v1/dimensions/${encodeURIComponent(dimensionName)}`, limits)).json();
-    }
-    return { createDimension, destroyDimension, restartDimension, listDimensions, updateDimension };
-}

package/dist/dimension/client.d.ts

@@ -0,0 +1,5 @@
+import type { Sandbox } from "../sandbox/api.ts";
+import type { DimensionClient } from "./api.ts";
+export declare function createDimensionClient(sandbox: Sandbox, options?: {
+    dataDirectory?: string;
+}): DimensionClient;

package/dist/dimension/client.js

@@ -0,0 +1,4 @@
+import { createDimensionService } from "./service.js";
+export function createDimensionClient(sandbox, options = {}) {
+    return createDimensionService(sandbox, options);
+}

package/dist/dimension/control.d.ts

@@ -0,0 +1,21 @@
+import { type ControlOptions } from "../lib/control.ts";
+import type { Sandbox } from "../sandbox/api.ts";
+import { type Dimension, type DimensionLimits, type DimensionStatus, type DimensionUsage } from "./api.ts";
+export type { ControlOptions };
+export type DimensionRecord = Dimension & {
+    state: "creating" | "ready";
+};
+export type DimensionState = {
+    record: DimensionRecord;
+    status: DimensionStatus;
+    startedAt: string | null;
+};
+export declare function createDimensionScript(host: Sandbox, dimension: Dimension, options?: ControlOptions): Promise<DimensionRecord | false>;
+export declare function destroyDimensionScript(host: Sandbox, dimensionName: string, options?: ControlOptions): Promise<void>;
+export declare function restartDimensionScript(host: Sandbox, dimensionName: string, options?: ControlOptions): Promise<void>;
+export declare function updateDimensionScript(host: Sandbox, dimensionName: string, limits: DimensionLimits, options?: ControlOptions): Promise<DimensionRecord>;
+export declare function listDimensionsScript(host: Sandbox, options?: ControlOptions): Promise<DimensionState[]>;
+export declare function dimensionUsageScript(host: Sandbox, options?: ControlOptions): Promise<DimensionUsage[]>;
+export declare function startTransportScript(host: Sandbox, dimensionName: string, options: ControlOptions, { restart, }: {
+    restart: boolean;
+}): Promise<void>;

package/dist/dimension/control.js

@@ -0,0 +1,328 @@
+import { exitEnv, records, runControl } from "../lib/control.js";
+import { sh } from "../lib/sh.js";
+import { HYPERBRANE_VERSION } from "../lib/version.js";
+import { DimensionConflictError, DimensionInvalidError, DimensionNotFoundError } from "./api.js";
+import { DIMENSION_IMAGE, DIMENSION_IMAGE_REPOSITORY } from "./image.js";
+import { RUN_PATH, STATE_PATH, TRANSPORT_SOCKET, WORKSPACE_PATH, containerName } from "./paths.js";
+import { dimensionTransportBundle } from "./transportBundle.js";
+import { TRANSPORT_LOG, TRANSPORT_READY } from "./transportProtocol.js";
+const EXIT = { invalid: 40, conflict: 41, notFound: 42, needImage: 43, needBundle: 44, thirdUser: 45 };
+export async function createDimensionScript(host, dimension, options = {}) {
+    const portals = dimension.portals?.map((portal) => JSON.stringify(portal));
+    const env = {
+        ...dimensionEnv(dimension.name, options),
+        DIRECTORY: dimension.directory,
+        MEMORY: String(dimension.memoryLimit),
+        CPUS: String(dimension.cpuLimit),
+        SWAP: String(dimension.memoryLimit * 2),
+        PORTALS: portals ? [...portals].sort().join(",") : "",
+        PORTALS_LINE: portals ? `  "portals": ${JSON.stringify(dimension.portals)},\n` : "",
+        IMAGE: DIMENSION_IMAGE,
+        IMAGE_REPOSITORY: DIMENSION_IMAGE_REPOSITORY,
+        VERSION: HYPERBRANE_VERSION,
+        WORKSPACE_PATH,
+    };
+    const result = await run(host, CREATE_DIMENSION, env);
+    if (result.exitCode === EXIT.needImage)
+        return false;
+    return JSON.parse(check(result, `creating dimension ${dimension.name}`).stdout);
+}
+export async function destroyDimensionScript(host, dimensionName, options = {}) {
+    check(await run(host, DESTROY_DIMENSION, dimensionEnv(dimensionName, options)), `destroying dimension ${dimensionName}`);
+}
+export async function restartDimensionScript(host, dimensionName, options = {}) {
+    check(await run(host, RESTART_DIMENSION, dimensionEnv(dimensionName, options)), `restarting dimension ${dimensionName}`);
+}
+export async function updateDimensionScript(host, dimensionName, limits, options = {}) {
+    const env = { ...dimensionEnv(dimensionName, options), MEMORY: String(limits.memoryLimit ?? ""), CPUS: String(limits.cpuLimit ?? "") };
+    const result = check(await run(host, UPDATE_DIMENSION, env), `updating dimension ${dimensionName}`);
+    return JSON.parse(result.stdout);
+}
+export async function listDimensionsScript(host, options = {}) {
+    const result = check(await run(host, LIST_DIMENSIONS, dataEnv(options)), "listing dimensions");
+    const [recordsPart = "", containersPart = ""] = result.stdout.split(CONTAINERS_START);
+    const containers = new Map(containersPart
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [name = "", status = "", startedAt = ""] = line.split("|");
+        return [name.replace(/^\//, ""), { status: status, startedAt }];
+    }));
+    return records(recordsPart).map(([, record]) => {
+        if (record.state === "creating")
+            return { record, status: "creating", startedAt: null };
+        const container = containers.get(containerName(record.name));
+        if (!container)
+            return { record, status: "missing", startedAt: null };
+        return { record, status: container.status, startedAt: container.status === "running" ? container.startedAt : null };
+    });
+}
+export async function dimensionUsageScript(host, options = {}) {
+    const result = check(await run(host, DIMENSION_USAGE, dataEnv(options)), "reading dimensions' usage");
+    return result.stdout
+        .split("\n")
+        .filter(Boolean)
+        .flatMap((line) => {
+        const [container = "", cpu = "", memory = ""] = line.split("\t");
+        const memoryUsage = bytes(memory.split("/")[0].trim());
+        const cpuUsage = Number.parseFloat(cpu) / 100;
+        if (memoryUsage === null || Number.isNaN(cpuUsage))
+            return [];
+        return [{ name: container.slice(containerName("").length), memoryUsage, cpuUsage }];
+    });
+}
+function bytes(text) {
+    const match = /^([\d.]+)\s*([KMGT]?)(i?)B$/i.exec(text);
+    if (!match)
+        return null;
+    const power = "_KMGT".indexOf(match[2].toUpperCase() || "_");
+    return Math.round(Number(match[1]) * (match[3] ? 1024 : 1000) ** power);
+}
+export async function startTransportScript(host, dimensionName, options, { restart, }) {
+    const { source, build } = await dimensionTransportBundle();
+    const env = {
+        ...dimensionEnv(dimensionName, options),
+        BUILD: build,
+        RESTART: restart ? "1" : "",
+        WORKSPACE_PATH,
+        TRANSPORT_SOCKET,
+        TRANSPORT_READY,
+        TRANSPORT_LOG,
+    };
+    let result = await run(host, START_TRANSPORT, env);
+    if (result.exitCode === EXIT.needBundle) {
+        await host.writeFile(`${result.stdout.trim()}/.transport-${build}.js`, source);
+        result = await run(host, START_TRANSPORT, env);
+    }
+    check(result, `starting dimension ${dimensionName}'s transport worker`);
+}
+function dataEnv({ dataDirectory }) {
+    return { ...(dataDirectory === undefined ? {} : { DATA: dataDirectory }), CONTAINER_PREFIX: containerName(""), RUN_PATH, STATE_PATH };
+}
+function dimensionEnv(dimensionName, options) {
+    return { ...dataEnv(options), DIMENSION: dimensionName };
+}
+function run(host, script, env) {
+    return runControl(host, PRELUDE, script, { ...exitEnv(EXIT), ...env }, {});
+}
+function check(result, what) {
+    const said = result.stderr.trim();
+    switch (result.exitCode) {
+        case 0:
+            return result;
+        case EXIT.invalid:
+            throw new DimensionInvalidError(said);
+        case EXIT.conflict:
+            throw new DimensionConflictError(said);
+        case EXIT.notFound:
+            throw new DimensionNotFoundError(said);
+        default:
+            throw new Error(`${what} failed (exit ${result.exitCode}): ${said || result.stdout.trim()}`);
+    }
+}
+const CONTAINERS_START = "\n\x1d\n";
+const PRELUDE = sh `
+# shellcheck disable=SC2034
+dimension_paths() {
+  RECORD="$DATA/dimensions/$DIMENSION.json"
+  CONTAINER="$CONTAINER_PREFIX$DIMENSION"
+  RUN="$DATA/dimension-run/$DIMENSION"
+  STATE="$DATA/dimension-state/$DIMENSION"
+}
+
+# shellcheck disable=SC2034
+container_exists() {
+  info="$(docker inspect -f '{{index .Config.Labels "hyperbrane.dimension"}}|{{.State.Running}}' "$CONTAINER" 2>/dev/null)" || return 1
+  label="\${info%|*}"
+  RUNNING="\${info##*|}"
+  [ "$label" = "$DIMENSION" ] || refuse "$E_CONFLICT" "container $CONTAINER exists but is not managed by hyperbrane"
+}
+
+require_dimension() {
+  [ -f "$RECORD" ] || refuse "$E_NOT_FOUND" "dimension $DIMENSION does not exist"
+  container_exists || refuse "$E_NOT_FOUND" "dimension $DIMENSION has no container; create it again"
+}
+`;
+const CREATE_DIMENSION = sh `
+set -eu
+dimension_paths
+
+# shellcheck disable=SC2153
+case "$DIRECTORY" in
+  /*) directory="$DIRECTORY" ;;
+  \~) directory="$HOME" ;;
+  \~/*) directory="$HOME/\${DIRECTORY#\~/}" ;;
+  *) directory="$HOME/$DIRECTORY" ;;
+esac
+if [ ! -e "$directory" ] && ! made="$(mkdir -p "$directory" 2>&1)"; then
+  refuse "$E_INVALID" "directory $directory doesn't exist and can't be made: $made"
+fi
+[ -d "$directory" ] || refuse "$E_INVALID" "not a directory: $directory"
+# shellcheck disable=SC2012
+owner="$(ls -nd "$directory" | awk '{ print $3 ":" $4 }')"
+
+container_exists || true
+
+directory_json="$(printf '%s' "$directory" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+dimension_record() {
+  printf '{\n  "name": "%s",\n  "directory": "%s",\n  "memoryLimit": %s,\n  "cpuLimit": %s,\n%s  "state": "%s"\n}\n' \
+    "$DIMENSION" "$directory_json" "$MEMORY" "$CPUS" "$PORTALS_LINE" "$1"
+}
+mkdir -p "$DATA/dimensions"
+if [ ! -f "$RECORD" ]; then
+  dimension_record creating > "$RECORD.$$"
+  ln "$RECORD.$$" "$RECORD" 2>/dev/null || true
+  rm -f "$RECORD.$$"
+fi
+recorded_portals="$(tr -d ' \n' < "$RECORD" | sed -n 's/.*"portals":\[\([^]]*\)\].*/\1/p' | tr ',' '\n' | LC_ALL=C sort | paste -sd, -)"
+# shellcheck disable=SC2153
+if [ "$(record_field "$RECORD" directory)" != "\"$directory_json\"" ] ||
+  [ "$(record_field "$RECORD" memoryLimit)" != "$MEMORY" ] ||
+  [ "$(record_field "$RECORD" cpuLimit)" != "$CPUS" ] ||
+  [ "$recorded_portals" != "$PORTALS" ]; then
+  refuse "$E_CONFLICT" "dimension $DIMENSION already exists with a different spec"
+fi
+
+docker image inspect "$IMAGE" > /dev/null 2>&1 || exit "$E_NEED_IMAGE"
+
+mkdir -p "$RUN" "$STATE"
+if ! container_exists; then
+  if ! created="$(docker create --name "$CONTAINER" --hostname "$CONTAINER" --user "$owner" --workdir "$WORKSPACE_PATH" \
+    --label hyperbrane=true --label "hyperbrane.version=$VERSION" --label "hyperbrane.dimension=$DIMENSION" \
+    --volume "$directory:$WORKSPACE_PATH" --volume "$RUN:$RUN_PATH" --volume "$STATE:$STATE_PATH" \
+    --cap-add SYSLOG --memory "$MEMORY" --memory-swap "$SWAP" --cpus "$CPUS" --network none \
+    --add-host "$CONTAINER:127.0.1.1" --init --restart unless-stopped \
+    "$IMAGE" sleep infinity 2>&1)"; then
+    case "$created" in
+      *"already in use"*) ;;
+      *) refuse 1 "$created" ;;
+    esac
+    waited=0
+    until container_exists; do
+      [ "$waited" -lt 50 ] || refuse 1 "$created"
+      sleep 0.1
+      waited=$((waited + 1))
+    done
+  fi
+fi
+docker start "$CONTAINER" > /dev/null
+docker exec -u root -e HYB_UID="\${owner%:*}" -e HYB_GID="\${owner#*:}" "$CONTAINER" hyb-ensure-user
+grep -q '"state": "ready"' "$RECORD" || dimension_record ready | write_whole "$RECORD"
+
+docker images --filter label=hyperbrane --filter "reference=$IMAGE_REPOSITORY" --format '{{.Repository}}:{{.Tag}}' |
+  while read -r tag; do
+    [ "$tag" = "$IMAGE" ] || docker rmi "$tag" > /dev/null 2>&1 || true
+  done
+cat "$RECORD"
+`;
+const DESTROY_DIMENSION = sh `
+set -eu
+dimension_paths
+if container_exists; then
+  [ "$RUNNING" = true ] || docker start "$CONTAINER" > /dev/null 2>&1 || true
+  docker exec -u root -e R="$RUN_PATH" -e S="$STATE_PATH" "$CONTAINER" sh -c 'find "$R" "$S" -mindepth 1 -delete' > /dev/null 2>&1 || true
+  if ! removed="$(docker rm -f "$CONTAINER" 2>&1)" && docker inspect "$CONTAINER" > /dev/null 2>&1; then refuse 1 "$removed"; fi
+fi
+rm -rf "$RUN" "$STATE"
+rm -f "$RECORD"
+`;
+const START_TRANSPORT = sh `
+set -eu
+dimension_paths
+require_dimension
+[ "$RUNNING" = true ] || refuse "$E_CONFLICT" "dimension $DIMENSION is not running"
+mkdir -p "$RUN"
+exec 8> "$RUN/.transport.lock"
+flock -w 60 8
+
+transport_running() {
+  TRANSPORT_PID=""
+  TRANSPORT_BUILD=""
+  [ -f "$RUN/$TRANSPORT_READY" ] && [ -S "$RUN/$TRANSPORT_SOCKET" ] || return 1
+  read -r TRANSPORT_PID TRANSPORT_BUILD < "$RUN/$TRANSPORT_READY" || return 1
+  docker exec -u 0 "$CONTAINER" grep -qs transport "/proc/$TRANSPORT_PID/cmdline"
+}
+
+if [ -z "$RESTART" ] && transport_running && [ "$TRANSPORT_BUILD" = "$BUILD" ]; then exit 0; fi
+[ -f "$RUN/.transport-$BUILD.js" ] || { printf '%s\n' "$RUN"; exit "$E_NEED_BUNDLE"; }
+
+user="$(docker inspect -f '{{.Config.User}}' "$CONTAINER")"
+user="\${user:-0}"
+socket_owner=""
+if [ "\${user%%:*}" = 0 ]; then
+  socket_owner="$(id -u):$(id -g)"
+elif [ "\${user%%:*}" != "$(id -u)" ]; then
+  refuse "$E_THIRD_USER" "dimension $DIMENSION runs as uid \${user%%:*}, whose transport socket uid $(id -u) can't connect to"
+fi
+
+if transport_running; then
+  docker exec -u 0 "$CONTAINER" kill "$TRANSPORT_PID" 2> /dev/null || true
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    docker exec -u 0 "$CONTAINER" kill -0 "$TRANSPORT_PID" 2> /dev/null || break
+    sleep 0.5
+  done
+  docker exec -u 0 "$CONTAINER" kill -9 "$TRANSPORT_PID" 2> /dev/null || true
+fi
+rm -f "$RUN/$TRANSPORT_READY"
+# shellcheck disable=SC2016
+docker exec -d -u "$user" -e HYB_WORKSPACE="$WORKSPACE_PATH" -e HYB_TRANSPORT_SOCKET="$RUN_PATH/$TRANSPORT_SOCKET" \
+  -e HYB_TRANSPORT_READY="$RUN_PATH/$TRANSPORT_READY" -e HYB_TRANSPORT_BUILD="$BUILD" -e HYB_SOCKET_OWNER="$socket_owner" \
+  -e SCRIPT="$RUN_PATH/.transport-$BUILD.js" -e LOG="$RUN_PATH/$TRANSPORT_LOG" \
+  "$CONTAINER" sh -c 'exec bun "$SCRIPT" >> "$LOG" 2>&1 < /dev/null'
+
+waited=0
+until transport_running && [ "$TRANSPORT_BUILD" = "$BUILD" ]; do
+  if [ "$waited" -ge 100 ]; then
+    echo "dimension $DIMENSION's transport worker did not come up:" >&2
+    tail -c 2000 "$RUN/$TRANSPORT_LOG" >&2 2> /dev/null || true
+    exit 1
+  fi
+  sleep 0.2
+  waited=$((waited + 1))
+done
+find "$RUN" -maxdepth 1 -name '.transport-*.js' ! -name ".transport-$BUILD.js" -exec rm -f {} + 2> /dev/null || true
+`;
+const RESTART_DIMENSION = sh `
+set -eu
+dimension_paths
+require_dimension
+docker restart "$CONTAINER" > /dev/null
+`;
+const UPDATE_DIMENSION = sh `
+set -eu
+dimension_paths
+require_dimension
+MEMORY="\${MEMORY:-$(record_field "$RECORD" memoryLimit)}"
+CPUS="\${CPUS:-$(record_field "$RECORD" cpuLimit)}"
+SWAP=$((MEMORY * 2))
+docker update --memory "$MEMORY" --memory-swap "$SWAP" --cpus "$CPUS" "$CONTAINER" > /dev/null
+sed 's/^  "memoryLimit": .*,$/  "memoryLimit": '"$MEMORY"',/; s/^  "cpuLimit": .*,$/  "cpuLimit": '"$CPUS"',/' "$RECORD" | write_whole "$RECORD"
+cat "$RECORD"
+`;
+const LIST_DIMENSIONS = sh `
+containers=""
+for record in "$DATA"/dimensions/*.json; do
+  [ -f "$record" ] || continue
+  name="\${record##*/}"
+  name="\${name%.json}"
+  printf '%s\n' "$name"
+  cat "$record"
+  printf '\n\036\n'
+  containers="$containers $CONTAINER_PREFIX$name"
+done
+printf '\n\035\n'
+# shellcheck disable=SC2086
+[ -z "$containers" ] || docker inspect -f '{{.Name}}|{{.State.Status}}|{{.State.StartedAt}}' $containers 2>/dev/null || true
+`;
+const DIMENSION_USAGE = sh `
+running="$(docker ps --filter label=hyperbrane.dimension --format '{{.Names}}')"
+containers=""
+for record in "$DATA"/dimensions/*.json; do
+  [ -f "$record" ] || continue
+  name="\${record##*/}"
+  container="$CONTAINER_PREFIX\${name%.json}"
+  if printf '%s\n' "$running" | grep -qx "$container"; then containers="$containers $container"; fi
+done
+# shellcheck disable=SC2086
+[ -z "$containers" ] || docker stats --no-stream --format '{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}' $containers
+`;

package/dist/dimension/image.d.ts

@@ -1,13 +1,8 @@
 import { type DockerClient } from "../lib/docker.ts";
-/**
- * Bump whenever anything under ./image changes (and run `bun run embed:images`); the tag is how an
- * existing build is recognised.
- */
 export declare const DIMENSION_IMAGE_VERSION = "v6";
 export declare const DIMENSION_IMAGE_REPOSITORY = "hyperbrane-dimension";
 export declare const DIMENSION_IMAGE = "hyperbrane-dimension:v6";
 export interface DimensionImage {
-    /** Builds the base image if it isn't present yet, removes outdated ones, and returns its tag. */
     ensure(): Promise<string>;
 }
 export declare function createDimensionImage(docker: DockerClient): DimensionImage;

package/dist/dimension/image.js

@@ -1,17 +1,10 @@
 import { DockerError } from "../lib/docker.js";
-// The files under ./image, as strings (scripts/embed-image-files.ts), so they travel inside the module
-// graph under any runtime or bundler instead of being looked up on disk at runtime.
 import { IMAGE_FILES } from "./imageFiles.generated.js";
-/**
- * Bump whenever anything under ./image changes (and run `bun run embed:images`); the tag is how an
- * existing build is recognised.
- */
 export const DIMENSION_IMAGE_VERSION = "v6";
 export const DIMENSION_IMAGE_REPOSITORY = "hyperbrane-dimension";
 export const DIMENSION_IMAGE = `${DIMENSION_IMAGE_REPOSITORY}:${DIMENSION_IMAGE_VERSION}`;
 const BUILD_CONTEXT = IMAGE_FILES;
 export function createDimensionImage(docker) {
-    // Concurrent builds of the same tag (from any process) are harmless: they produce the same image.
     async function ensure() {
         if (!(await docker.imageExists(DIMENSION_IMAGE))) {
             await docker.buildImage({
@@ -23,7 +16,6 @@ export function createDimensionImage(docker) {
         await removeOutdatedImages().catch((error) => console.warn("removing outdated dimension images failed:", error));
         return DIMENSION_IMAGE;
     }
-    // Images still used by a container are skipped (docker answers 409) and retried on a later ensure().
     async function removeOutdatedImages() {
         const images = await docker.listImages({ label: ["hyperbrane"], reference: [DIMENSION_IMAGE_REPOSITORY] });
         const outdated = images

package/dist/dimension/imageFiles.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/embed-image-files.ts from dimension/image/ — do not edit; run `bun run embed:images`.
 export const IMAGE_FILES = {
     "Dockerfile": "# bun runs the agent session worker (agent/session/), and the agent CLIs it installs.\nFROM oven/bun:1.3.13-slim AS bun\nFROM debian:13-slim\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends bash sudo git jq curl wget iputils-ping ca-certificates procps \\\n && rm -rf /var/lib/apt/lists/*\nCOPY --from=bun /usr/local/bin/bun /usr/local/bin/bun\nCOPY ensure-user.sh /usr/local/bin/hyb-ensure-user\nRUN chmod 0755 /usr/local/bin/hyb-ensure-user\nWORKDIR /workspace\nCMD [\"sleep\", \"infinity\"]\n",
-    "ensure-user.sh": "#!/bin/sh\n# Creates the dimension user for HYB_UID/HYB_GID (the host directory owner) with passwordless sudo.\n# Safe to re-run: every step checks before it acts, and concurrent runs are serialized by the lock.\nset -eu\n\nexec 9>/run/hyb-ensure-user.lock\nflock 9\n\nuid=\"$HYB_UID\"\ngid=\"$HYB_GID\"\n[ \"$uid\" = 0 ] && exit 0\n\ngroup=\"$(getent group \"$gid\" | cut -d: -f1 || true)\"\nif [ -z \"$group\" ]; then\n  groupadd -g \"$gid\" dimension\n  group=dimension\nfi\n\nif ! getent passwd \"$uid\" >/dev/null; then\n  useradd -m -u \"$uid\" -g \"$group\" -d /home/dimension -s /bin/bash dimension\nfi\n\necho \"#$uid ALL=(ALL) NOPASSWD: ALL\" > /etc/sudoers.d/dimension\nchmod 0440 /etc/sudoers.d/dimension\n",
+    "ensure-user.sh": "#!/bin/sh\nset -eu\n\nexec 9>/run/hyb-ensure-user.lock\nflock 9\n\nuid=\"$HYB_UID\"\ngid=\"$HYB_GID\"\n[ \"$uid\" = 0 ] && exit 0\n\ngroup=\"$(getent group \"$gid\" | cut -d: -f1 || true)\"\nif [ -z \"$group\" ]; then\n  groupadd -g \"$gid\" dimension\n  group=dimension\nfi\n\nif ! getent passwd \"$uid\" >/dev/null; then\n  useradd -m -u \"$uid\" -g \"$group\" -d /home/dimension -s /bin/bash dimension\nfi\n\necho \"#$uid ALL=(ALL) NOPASSWD: ALL\" > /etc/sudoers.d/dimension\nchmod 0440 /etc/sudoers.d/dimension\n",
 };