hyperbrane 0.1.0

package/dist/dimension/service.js

@@ -0,0 +1,242 @@
+import { isAbsolute, posix } from "node:path";
+import { DockerError } from "../lib/docker.js";
+import { SandboxNotFoundError } from "../sandbox/api.js";
+import { sleep } from "../lib/sleep.js";
+import { HYPERBRANE_VERSION } from "../lib/version.js";
+import { DimensionConflictError, DimensionInvalidError, DimensionNotFoundError, } from "./api.js";
+import { RUN_PATH, STATE_PATH, WORKSPACE_PATH } from "./paths.js";
+export { RUN_PATH, STATE_PATH, WORKSPACE_PATH };
+// Docker's container-name alphabet; also keeps names safe to use as storage file names.
+const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$/;
+export function containerName(dimensionName) {
+    return `hyb-${dimensionName}`;
+}
+/**
+ * `host` is the machine the docker daemon runs on, rooted at "/" so dimension directories
+ * (bind-mount sources) resolve the same way docker resolves them.
+ */
+export function createDimensionService(storage, docker, image, host) {
+    async function getDimensions() {
+        return Promise.all((await storage.getDimensions()).map(describeDimension));
+    }
+    async function describeDimension({ state, ...dimension }) {
+        if (state === "creating")
+            return withoutUsage(dimension, "creating");
+        const container = await docker.inspectContainer(containerName(dimension.name));
+        if (!container)
+            return withoutUsage(dimension, "missing");
+        const containerState = container.State;
+        if (!containerState?.Running || !containerState.StartedAt) {
+            return withoutUsage(dimension, containerState?.Status ?? "exited");
+        }
+        try {
+            const stats = await docker.containerStats(containerName(dimension.name));
+            return {
+                ...dimension,
+                status: "running",
+                uptimeSeconds: Math.max(0, Math.floor((Date.now() - Date.parse(containerState.StartedAt)) / 1000)),
+                memoryUsage: stats.memoryUsage,
+                cpuUsage: stats.cpuUsage,
+            };
+        }
+        catch (error) {
+            if (error instanceof DockerError && error.status === 404)
+                return withoutUsage(dimension, "missing");
+            throw error;
+        }
+    }
+    // Keeps no state between calls: every step re-reads storage or docker and uses operations that are
+    // atomic across processes, so a create that crashed halfway, or runs twice at once, converges.
+    // A relative directory ("work", "~/work") is the host user's: resolved against their home, and
+    // recorded resolved. A missing one is made.
+    async function createDimension(requested) {
+        assertValidName(requested.name);
+        const dimension = { ...requested, directory: await resolveDirectory(requested.directory) };
+        const owner = await directoryOwner(dimension.directory);
+        const existing = await docker.inspectContainer(containerName(dimension.name));
+        if (existing)
+            assertOwnedContainer(existing, dimension.name);
+        const record = await storage.insertDimension({ ...dimension, state: "creating" });
+        assertSameSpec(record, dimension);
+        const imageTag = await image.ensure();
+        const runDirectory = await storage.ensureRunDirectory(dimension.name);
+        const stateDirectory = await storage.ensureStateDirectory(dimension.name);
+        await ensureContainer(dimension, owner, imageTag, runDirectory, stateDirectory);
+        await docker.startContainer(containerName(dimension.name));
+        await ensureUser(dimension, owner);
+        if (record.state !== "ready")
+            await storage.saveDimension({ ...dimension, state: "ready" });
+    }
+    async function ensureContainer(dimension, owner, imageTag, runDirectory, stateDirectory) {
+        const name = containerName(dimension.name);
+        const existing = await docker.inspectContainer(name);
+        if (existing)
+            return assertOwnedContainer(existing, dimension.name);
+        try {
+            await docker.createContainer(name, {
+                Image: imageTag,
+                Cmd: ["sleep", "infinity"],
+                Hostname: name,
+                User: `${owner.uid}:${owner.gid}`,
+                WorkingDir: WORKSPACE_PATH,
+                Labels: {
+                    hyperbrane: "true",
+                    "hyperbrane.version": HYPERBRANE_VERSION,
+                    "hyperbrane.dimension": dimension.name,
+                },
+                HostConfig: {
+                    Binds: [`${dimension.directory}:${WORKSPACE_PATH}`, `${runDirectory}:${RUN_PATH}`, `${stateDirectory}:${STATE_PATH}`],
+                    // dmesg: docker drops CAP_SYSLOG, and its seccomp profile refuses the syslog call without it.
+                    // The log is the host's kernel log, shared by every dimension.
+                    CapAdd: ["SYSLOG"],
+                    ...containerResources(dimension),
+                    NetworkMode: "none",
+                    // Without a network docker doesn't map the hostname, and sudo warns on every call.
+                    ExtraHosts: [`${name}:127.0.1.1`],
+                    Init: true,
+                    RestartPolicy: { Name: "unless-stopped" },
+                },
+            });
+        }
+        catch (error) {
+            // Lost a race with another creator: fine as long as the winner is ours.
+            if (!(error instanceof DockerError && error.status === 409))
+                throw error;
+            assertOwnedContainer(await awaitContainer(name, error), dimension.name);
+        }
+    }
+    // Docker reserves the name before the winner's container becomes inspectable, so give it a moment.
+    async function awaitContainer(name, conflict) {
+        for (let attempt = 0; attempt < 50; attempt++) {
+            const container = await docker.inspectContainer(name);
+            if (container)
+                return container;
+            await sleep(100);
+        }
+        throw conflict;
+    }
+    async function ensureUser(dimension, owner) {
+        const result = await docker.exec(containerName(dimension.name), {
+            cmd: ["hyb-ensure-user"],
+            user: "root",
+            env: { HYB_UID: String(owner.uid), HYB_GID: String(owner.gid) },
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(`user setup in ${containerName(dimension.name)} failed: ${result.stderr.trim()}`);
+        }
+    }
+    // Container first: if this crashes before the record is removed, the dimension still shows up
+    // (as "missing") and the destroy can be retried. Its run and state directories go with the record,
+    // emptied from inside first: what a dimension running as root left there (an agent worker's socket
+    // and log) the host user couldn't remove.
+    async function destroyDimension(dimensionName) {
+        assertValidName(dimensionName);
+        const name = containerName(dimensionName);
+        const existing = await docker.inspectContainer(name);
+        if (existing) {
+            assertOwnedContainer(existing, dimensionName);
+            if (!existing.State?.Running)
+                await docker.startContainer(name).catch(() => { });
+            // Best effort: if it fails, removing them from the host below says why.
+            await docker
+                .exec(name, { cmd: ["sh", "-c", 'find "$R" "$S" -mindepth 1 -delete'], user: "root", env: { R: RUN_PATH, S: STATE_PATH } })
+                .catch(() => { });
+            await docker.removeContainer(name);
+        }
+        await storage.removeRunDirectory(dimensionName);
+        await storage.removeStateDirectory(dimensionName);
+        await storage.removeDimension(dimensionName);
+    }
+    // Same container, so the user and anything installed outside the workspace survive; the workspace
+    // is a bind mount either way.
+    async function restartDimension(dimensionName) {
+        assertValidName(dimensionName);
+        if (!(await storage.getDimensions()).some((dimension) => dimension.name === dimensionName)) {
+            throw new DimensionNotFoundError(`dimension ${dimensionName} does not exist`);
+        }
+        const existing = await docker.inspectContainer(containerName(dimensionName));
+        if (!existing)
+            throw new DimensionNotFoundError(`dimension ${dimensionName} has no container; create it again`);
+        assertOwnedContainer(existing, dimensionName);
+        await docker.restartContainer(containerName(dimensionName));
+    }
+    // Container first: a limit docker refuses leaves the record as it was.
+    async function updateDimension(dimensionName, limits) {
+        assertValidName(dimensionName);
+        for (const [name, value] of Object.entries(limits)) {
+            if (value !== undefined && !(typeof value === "number" && value > 0))
+                throw new DimensionInvalidError(`${name} must be positive`);
+        }
+        const record = (await storage.getDimensions()).find((dimension) => dimension.name === dimensionName);
+        if (!record)
+            throw new DimensionNotFoundError(`dimension ${dimensionName} does not exist`);
+        const existing = await docker.inspectContainer(containerName(dimensionName));
+        if (!existing)
+            throw new DimensionNotFoundError(`dimension ${dimensionName} has no container; create it again`);
+        assertOwnedContainer(existing, dimensionName);
+        const { state, ...current } = record;
+        const updated = {
+            ...current,
+            memoryLimit: limits.memoryLimit ?? record.memoryLimit,
+            cpuLimit: limits.cpuLimit ?? record.cpuLimit,
+        };
+        await docker.updateContainer(containerName(dimensionName), containerResources(updated));
+        await storage.saveDimension({ ...updated, state });
+        return updated;
+    }
+    async function resolveDirectory(directory) {
+        if (!directory.trim())
+            throw new DimensionInvalidError("directory is required");
+        if (isAbsolute(directory))
+            return directory;
+        const relative = directory === "~" ? "." : directory.replace(/^~\//, "");
+        return posix.join(await host.homeDirectory(), relative);
+    }
+    async function directoryOwner(directory) {
+        if (!isAbsolute(directory))
+            throw new DimensionInvalidError(`directory must be absolute: ${directory}`);
+        // A missing one is made, by the host user: theirs, so the dimension runs as them.
+        const info = await host.stat(directory).catch(async (error) => {
+            if (!(error instanceof SandboxNotFoundError))
+                throw error;
+            await host.createDirectory(directory).catch((cause) => {
+                throw new DimensionInvalidError(`directory ${directory} doesn't exist and can't be made: ${cause.message}`);
+            });
+            return host.stat(directory);
+        });
+        if (info.type !== "directory")
+            throw new DimensionInvalidError(`not a directory: ${directory}`);
+        return { uid: info.uid, gid: info.gid };
+    }
+    async function getDimensionNames() {
+        return (await storage.getDimensions()).map((dimension) => dimension.name);
+    }
+    return { getDimensions, getDimensionNames, createDimension, destroyDimension, restartDimension, updateDimension };
+}
+function assertValidName(dimensionName) {
+    if (!NAME_PATTERN.test(dimensionName)) {
+        throw new DimensionInvalidError(`invalid dimension name "${dimensionName}": use letters, digits, "_", "." or "-", starting with a letter or digit`);
+    }
+}
+function assertSameSpec(existing, requested) {
+    const differs = existing.directory !== requested.directory ||
+        existing.memoryLimit !== requested.memoryLimit ||
+        existing.cpuLimit !== requested.cpuLimit ||
+        [...(existing.portals ?? [])].sort().join("\0") !== [...(requested.portals ?? [])].sort().join("\0");
+    if (differs) {
+        throw new DimensionConflictError(`dimension ${requested.name} already exists with a different spec`);
+    }
+}
+function assertOwnedContainer(container, dimensionName) {
+    if (container.Config?.Labels?.["hyperbrane.dimension"] !== dimensionName) {
+        throw new DimensionConflictError(`container ${containerName(dimensionName)} exists but is not managed by hyperbrane`);
+    }
+}
+// Swap stays at twice the memory, which is what docker gives a container created with only a
+// memory limit; setting both keeps an update valid whichever way the limit moves.
+function containerResources({ memoryLimit, cpuLimit }) {
+    return { Memory: memoryLimit, MemorySwap: memoryLimit * 2, NanoCpus: Math.round(cpuLimit * 1e9) };
+}
+function withoutUsage(dimension, status) {
+    return { ...dimension, status, uptimeSeconds: null, memoryUsage: null, cpuUsage: null };
+}

package/dist/dimension/storage.d.ts

@@ -0,0 +1,39 @@
+import { type Sandbox } from "../sandbox/api.ts";
+import type { Dimension } from "./api.ts";
+/** "creating" until provisioning has finished once; a create that crashed stays "creating" until retried. */
+export type DimensionRecord = Dimension & {
+    state: "creating" | "ready";
+};
+/**
+ * One JSON file per dimension, so no operation rewrites a shared file and every write is a single
+ * atomic sandbox operation. Safe to use from several processes at once.
+ */
+export interface Storage {
+    getDimensions(): Promise<DimensionRecord[]>;
+    /** Stores the record unless one with that name exists; returns whichever record is stored afterwards. */
+    insertDimension(record: DimensionRecord): Promise<DimensionRecord>;
+    /** Replaces the record. */
+    saveDimension(record: DimensionRecord): Promise<void>;
+    /** No-op if the record doesn't exist. */
+    removeDimension(dimensionName: string): Promise<void>;
+    /**
+     * Sandbox path of the dimension's run directory, mounted into it at RUN_PATH so processes on both
+     * sides can meet at unix sockets in it (the agent session worker). Creates it.
+     */
+    ensureRunDirectory(dimensionName: string): Promise<string>;
+    /** Removes the run directory and everything in it. No-op if missing. */
+    removeRunDirectory(dimensionName: string): Promise<void>;
+    /**
+     * Sandbox path of the dimension's state directory, mounted into it at STATE_PATH: what hyperbrane
+     * keeps for what runs in the dimension (the agent session worker's records), on the host with the
+     * rest of its storage. Creates it.
+     */
+    ensureStateDirectory(dimensionName: string): Promise<string>;
+    /** Removes the state directory and everything in it. No-op if missing. */
+    removeStateDirectory(dimensionName: string): Promise<void>;
+}
+/**
+ * `dir` is a sandbox path; defaults to ~/.local/share/hyperbrane/dimensions of the sandbox's user.
+ * Run and state directories go next to it, in dimension-run/<dimension> and dimension-state/<dimension>.
+ */
+export declare function createFileStorage(sandbox: Sandbox, dir?: string): Storage;

package/dist/dimension/storage.js

@@ -0,0 +1,78 @@
+import { dirname } from "node:path";
+import { createJsonDirectory } from "../lib/jsonDirectory.js";
+import { SandboxNotFoundError } from "../sandbox/api.js";
+const EXTENSION = ".json";
+/**
+ * `dir` is a sandbox path; defaults to ~/.local/share/hyperbrane/dimensions of the sandbox's user.
+ * Run and state directories go next to it, in dimension-run/<dimension> and dimension-state/<dimension>.
+ */
+export function createFileStorage(sandbox, dir) {
+    async function storageDir() {
+        return dir ?? `${await sandbox.homeDirectory()}/.local/share/hyperbrane/dimensions`;
+    }
+    async function pathFor(dimensionName) {
+        return `${await storageDir()}/${dimensionName}${EXTENSION}`;
+    }
+    function serialize(record) {
+        return JSON.stringify(record, null, 2) + "\n";
+    }
+    async function readRecord(path) {
+        try {
+            return JSON.parse(new TextDecoder().decode(await sandbox.readFile(path)));
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return null;
+            throw error;
+        }
+    }
+    // All at once (lib/jsonDirectory.ts): a call per record adds up on a remote machine.
+    async function getDimensions() {
+        return createJsonDirectory(sandbox, storageDir).list();
+    }
+    async function insertDimension(record) {
+        const path = await pathFor(record.name);
+        if (await sandbox.writeFileExclusive(path, serialize(record)))
+            return record;
+        // Lost to an existing record; if that one was removed in the meantime, try again.
+        return (await readRecord(path)) ?? insertDimension(record);
+    }
+    async function saveDimension(record) {
+        await sandbox.writeFile(await pathFor(record.name), serialize(record));
+    }
+    async function removeDimension(dimensionName) {
+        await sandbox.removeFile(await pathFor(dimensionName));
+    }
+    async function runDirectory(dimensionName) {
+        return `${dirname(await storageDir())}/dimension-run/${dimensionName}`;
+    }
+    async function ensureRunDirectory(dimensionName) {
+        const path = await runDirectory(dimensionName);
+        await sandbox.createDirectory(path);
+        return path;
+    }
+    async function removeRunDirectory(dimensionName) {
+        await sandbox.removeDirectory(await runDirectory(dimensionName));
+    }
+    async function stateDirectory(dimensionName) {
+        return `${dirname(await storageDir())}/dimension-state/${dimensionName}`;
+    }
+    async function ensureStateDirectory(dimensionName) {
+        const path = await stateDirectory(dimensionName);
+        await sandbox.createDirectory(path);
+        return path;
+    }
+    async function removeStateDirectory(dimensionName) {
+        await sandbox.removeDirectory(await stateDirectory(dimensionName));
+    }
+    return {
+        getDimensions,
+        insertDimension,
+        saveDimension,
+        removeDimension,
+        ensureRunDirectory,
+        removeRunDirectory,
+        ensureStateDirectory,
+        removeStateDirectory,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./sandbox/api.ts";
+export * from "./dimension/api.ts";
+export * from "./portal-gateway/api.ts";
+export * from "./agent/api.ts";
+export { createServices, type Services } from "./cli/services.ts";
+export { createLocalSandbox, type LocalSandboxOptions } from "./sandbox/localService.ts";
+export { createSshSandbox, type SshSandboxOptions } from "./sandbox/sshService.ts";
+export { createContainerSandbox, type ContainerSandboxOptions } from "./sandbox/containerService.ts";
+export { BOAT_API_URL, BoatError, archiveBoatMachine, authorizeBoatSshKey, boatHostPortAuth, createBoatApi, createBoatMachine, createBoatSandbox, ensureBoatRunning, type BoatSandboxOptions, } from "./sandbox/boatService.ts";
+export { parseAccessibleHost, proxyCredentialsAuth, type SandboxEndpointAuth, type SandboxEndpointsOptions } from "./sandbox/endpointProxy.ts";
+export { exeDevProxyAuth, type ExeDevAuthOptions } from "./sandbox/exeDevAuth.ts";
+export { EndpointLoginRequiredError, endpointRequest, exeDevLoginUrl, openSseConnection, type EndpointAccess } from "./sandbox/sseConnection.ts";
+export { createWorkerClient, type WorkerClient } from "./agent/session/client.ts";
+export { workerSseConnector, type WorkerEndpoint } from "./agent/session/workerSseConnection.ts";
+export { sharedConnector, type SharedConnector } from "./agent/session/sharedConnection.ts";
+export { createDockerClient, DockerError, type DockerClient } from "./lib/docker.ts";
+export { BUILTIN_UPSTREAMS } from "./upstreams/index.ts";
+export { HYPERBRANE_VERSION } from "./lib/version.ts";

package/dist/index.js

@@ -0,0 +1,25 @@
+// The hyperbrane SDK's entry point: what an application drives a server with. Everything else is
+// reachable by its path too (`hyperbrane/sandbox/sshService`, ...).
+// The APIs: types, errors and helpers of each part.
+export * from "./sandbox/api.js";
+export * from "./dimension/api.js";
+export * from "./portal-gateway/api.js";
+export * from "./agent/api.js";
+// All of a machine's services over one sandbox (this machine by default).
+export { createServices } from "./cli/services.js";
+// Sandboxes: the machine the services drive, however it is reached.
+export { createLocalSandbox } from "./sandbox/localService.js";
+export { createSshSandbox } from "./sandbox/sshService.js";
+export { createContainerSandbox } from "./sandbox/containerService.js";
+export { BOAT_API_URL, BoatError, archiveBoatMachine, authorizeBoatSshKey, boatHostPortAuth, createBoatApi, createBoatMachine, createBoatSandbox, ensureBoatRunning, } from "./sandbox/boatService.js";
+// Accessible endpoints: how they are authenticated, and reaching them.
+export { parseAccessibleHost, proxyCredentialsAuth } from "./sandbox/endpointProxy.js";
+export { exeDevProxyAuth } from "./sandbox/exeDevAuth.js";
+export { EndpointLoginRequiredError, endpointRequest, exeDevLoginUrl, openSseConnection } from "./sandbox/sseConnection.js";
+// An agent's worker, reached through its endpoint (AgentService.exposeAgent), from a server or a browser.
+export { createWorkerClient } from "./agent/session/client.js";
+export { workerSseConnector } from "./agent/session/workerSseConnection.js";
+export { sharedConnector } from "./agent/session/sharedConnection.js";
+export { createDockerClient, DockerError } from "./lib/docker.js";
+export { BUILTIN_UPSTREAMS } from "./upstreams/index.js";
+export { HYPERBRANE_VERSION } from "./lib/version.js";