hyperbrane 0.1.0

package/dist/lib/docker-api.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/lib/docker.d.ts

@@ -0,0 +1,77 @@
+import type { components, operations } from "./docker-api.ts";
+import type { Sandbox } from "../sandbox/api.ts";
+/** Engine API version the client speaks. After changing it, run `bun run generate:docker-api`. */
+export declare const DOCKER_API_VERSION = "v1.44";
+type Schemas = components["schemas"];
+export type ContainerInspect = operations["ContainerInspect"]["responses"][200]["content"]["application/json"];
+export type ContainerStatus = NonNullable<NonNullable<Schemas["ContainerState"]>["Status"]>;
+export type ContainerSummary = Schemas["ContainerSummary"];
+export type ContainerCreateSpec = operations["ContainerCreate"]["requestBody"]["content"]["application/json"];
+export type ImageSummary = Schemas["ImageSummary"];
+export type DockerEvent = Schemas["EventMessage"];
+export type ContainerResources = Pick<Schemas["Resources"], "Memory" | "MemorySwap" | "NanoCpus">;
+export type ContainerStats = {
+    /** Bytes, excluding reclaimable page cache (same number `docker stats` shows). */
+    memoryUsage: number;
+    /** Cores in use, e.g. 0.25 = a quarter of one core. */
+    cpuUsage: number;
+};
+export type ExecOptions = {
+    cmd: string[];
+    user?: string;
+    env?: Record<string, string>;
+    /** Defaults to the container's working directory. */
+    workdir?: string;
+};
+export type ExecResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type BuildOptions = {
+    tag: string;
+    /** Build context: file path inside the context -> file contents. Must include "Dockerfile". */
+    context: Record<string, string>;
+    labels?: Record<string, string>;
+};
+export interface DockerClient {
+    imageExists(image: string): Promise<boolean>;
+    buildImage(options: BuildOptions): Promise<void>;
+    /** Filters use docker's syntax, e.g. { label: ["hyperbrane"], reference: ["hyperbrane-dimension"] }. */
+    listImages(filters: Record<string, string[]>): Promise<ImageSummary[]>;
+    /** Removes a tag (and the image, once untagged). No-op if missing; DockerError 409 while a container uses it. */
+    removeImage(image: string): Promise<void>;
+    inspectContainer(name: string): Promise<ContainerInspect | null>;
+    listContainers(label: string): Promise<ContainerSummary[]>;
+    /** Throws DockerError with status 409 if a container with this name already exists. */
+    createContainer(name: string, spec: ContainerCreateSpec): Promise<void>;
+    /** No-op if the container is already running. */
+    startContainer(name: string): Promise<void>;
+    /** No-op if the container is already stopped. */
+    stopContainer(name: string): Promise<void>;
+    /** Stops the container (if running) and starts it again. */
+    restartContainer(name: string): Promise<void>;
+    /** Force-removes the container and its anonymous volumes. No-op if it doesn't exist. */
+    removeContainer(name: string): Promise<void>;
+    containerStats(name: string): Promise<ContainerStats>;
+    /** Changes a container's resource limits in place: no restart. */
+    updateContainer(name: string, resources: ContainerResources): Promise<void>;
+    exec(name: string, options: ExecOptions): Promise<ExecResult>;
+    /**
+     * Extracts `files` (path relative to `directory` -> contents) into the container, owned by root.
+     * `directory` must exist. DockerError 404 if the container or the directory doesn't.
+     */
+    putArchive(name: string, directory: string, files: Record<string, string | Uint8Array>): Promise<void>;
+    /**
+     * Streams events as they happen, e.g. filters { type: ["container"], event: ["start"] }. Ends when
+     * `signal` aborts (quietly) or the daemon drops the connection.
+     */
+    events(filters: Record<string, string[]>, signal: AbortSignal): AsyncIterable<DockerEvent>;
+}
+export declare class DockerError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Talks to the docker daemon whose API socket is at `socketPath` inside `sandbox`. */
+export declare function createDockerClient(sandbox: Sandbox, socketPath?: string): DockerClient;
+export {};

package/dist/lib/docker.js

@@ -0,0 +1,214 @@
+import createClient from "openapi-fetch";
+import { createTar } from "./tar.js";
+/** Engine API version the client speaks. After changing it, run `bun run generate:docker-api`. */
+export const DOCKER_API_VERSION = "v1.44";
+export class DockerError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "DockerError";
+    }
+}
+/** Returns the data of a successful call (or of one whose status is listed in `allowed`), else throws DockerError. */
+function unwrap({ data, error, response }, allowed = []) {
+    if (response.ok || allowed.includes(response.status))
+        return data;
+    const message = error?.message ?? response.statusText;
+    throw new DockerError(response.status, message);
+}
+/** Talks to the docker daemon whose API socket is at `socketPath` inside `sandbox`. */
+export function createDockerClient(sandbox, socketPath = "/var/run/docker.sock") {
+    function sandboxFetch(timeout) {
+        return async (request) => sandbox.fetch(request.url, {
+            method: request.method,
+            headers: Object.fromEntries(request.headers),
+            body: request.body ? new Uint8Array(await request.arrayBuffer()) : undefined,
+            unix: socketPath,
+            signal: request.signal,
+            timeout,
+        });
+    }
+    const api = createClient({ baseUrl: `http://docker/${DOCKER_API_VERSION}`, fetch: sandboxFetch() });
+    async function imageExists(image) {
+        const result = await api.GET("/images/{name}/json", { params: { path: { name: image } } });
+        unwrap(result, [404]);
+        return result.response.status !== 404;
+    }
+    async function buildImage({ tag, context, labels = {} }) {
+        const tar = createTar(context);
+        const result = await api.POST("/build", {
+            params: { query: { t: tag, labels: JSON.stringify(labels), rm: true, forcerm: true } },
+            headers: { "Content-type": "application/x-tar" },
+            // The spec models the binary tar stream as a string.
+            body: tar,
+            bodySerializer: (body) => body,
+            parseAs: "text",
+        });
+        // The build streams JSON lines; failures arrive in-band with HTTP 200.
+        const log = [];
+        for (const line of (unwrap(result) ?? "").split("\n").filter(Boolean)) {
+            const event = JSON.parse(line);
+            if (event.stream)
+                log.push(event.stream);
+            if (event.error) {
+                throw new DockerError(500, `build ${tag} failed: ${event.error}\n${log.join("").slice(-2000)}`);
+            }
+        }
+    }
+    async function listImages(filters) {
+        const result = await api.GET("/images/json", { params: { query: { filters: JSON.stringify(filters) } } });
+        return unwrap(result);
+    }
+    async function removeImage(image) {
+        unwrap(await api.DELETE("/images/{name}", { params: { path: { name: image } } }), [404]);
+    }
+    async function inspectContainer(name) {
+        const result = await api.GET("/containers/{id}/json", { params: { path: { id: name } } });
+        if (result.response.status === 404)
+            return null;
+        return unwrap(result);
+    }
+    async function listContainers(label) {
+        const filters = JSON.stringify({ label: [label] });
+        return unwrap(await api.GET("/containers/json", { params: { query: { all: true, filters } } }));
+    }
+    async function createContainer(name, spec) {
+        unwrap(await api.POST("/containers/create", { params: { query: { name } }, body: spec }));
+    }
+    async function startContainer(name) {
+        unwrap(await api.POST("/containers/{id}/start", { params: { path: { id: name } } }), [304]);
+    }
+    async function stopContainer(name) {
+        unwrap(await api.POST("/containers/{id}/stop", { params: { path: { id: name } } }), [304]);
+    }
+    async function restartContainer(name) {
+        unwrap(await api.POST("/containers/{id}/restart", { params: { path: { id: name } } }));
+    }
+    async function removeContainer(name) {
+        const params = { path: { id: name }, query: { force: true, v: true } };
+        unwrap(await api.DELETE("/containers/{id}", { params }), [404]);
+    }
+    async function updateContainer(name, resources) {
+        unwrap(await api.POST("/containers/{id}/update", { params: { path: { id: name } }, body: resources }));
+    }
+    async function containerStats(name) {
+        // stream=false without one-shot waits for two samples, which the CPU delta needs.
+        const result = await api.GET("/containers/{id}/stats", {
+            params: { path: { id: name }, query: { stream: false } },
+        });
+        return toContainerStats(unwrap(result));
+    }
+    async function exec(name, { cmd, user, env = {}, workdir }) {
+        const created = await api.POST("/containers/{id}/exec", {
+            params: { path: { id: name } },
+            body: {
+                Cmd: cmd,
+                User: user,
+                WorkingDir: workdir,
+                Env: Object.entries(env).map(([key, value]) => `${key}=${value}`),
+                AttachStdout: true,
+                AttachStderr: true,
+            },
+        });
+        const { Id } = unwrap(created);
+        const started = await api.POST("/exec/{id}/start", {
+            params: { path: { id: Id } },
+            body: { Detach: false, Tty: false },
+            parseAs: "arrayBuffer",
+        });
+        const { stdout, stderr } = demuxStream(new Uint8Array(unwrap(started)));
+        const inspected = unwrap(await api.GET("/exec/{id}/json", { params: { path: { id: Id } } }));
+        return { exitCode: inspected.ExitCode ?? -1, stdout, stderr };
+    }
+    async function putArchive(name, directory, files) {
+        const tar = createTar(files);
+        const result = await api.PUT("/containers/{id}/archive", {
+            params: { path: { id: name }, query: { path: directory } },
+            headers: { "Content-type": "application/x-tar" },
+            // The spec models the binary tar stream as a string.
+            body: tar,
+            bodySerializer: (body) => body,
+            parseAs: "text",
+        });
+        unwrap(result);
+    }
+    async function* events(filters, signal) {
+        try {
+            const result = await api.GET("/events", {
+                params: { query: { filters: JSON.stringify(filters) } },
+                parseAs: "stream",
+                signal,
+                // The stream stays silent while nothing happens; an idle timeout would cut it.
+                fetch: sandboxFetch(false),
+            });
+            const body = unwrap(result);
+            if (!body)
+                return;
+            // One JSON object per line.
+            const decoder = new TextDecoder();
+            let buffered = "";
+            for await (const chunk of body) {
+                buffered += decoder.decode(chunk, { stream: true });
+                let newline;
+                while ((newline = buffered.indexOf("\n")) >= 0) {
+                    const line = buffered.slice(0, newline).trim();
+                    buffered = buffered.slice(newline + 1);
+                    if (line)
+                        yield JSON.parse(line);
+                }
+            }
+        }
+        catch (error) {
+            if (!signal.aborted)
+                throw error;
+        }
+    }
+    return {
+        imageExists,
+        buildImage,
+        listImages,
+        removeImage,
+        inspectContainer,
+        listContainers,
+        createContainer,
+        startContainer,
+        stopContainer,
+        restartContainer,
+        removeContainer,
+        containerStats,
+        updateContainer,
+        exec,
+        putArchive,
+        events,
+    };
+}
+function toContainerStats(raw) {
+    const memory = raw.memory_stats;
+    const cache = memory.stats?.inactive_file ?? memory.stats?.total_inactive_file ?? 0;
+    const memoryUsage = Math.max(0, (memory.usage ?? 0) - cache);
+    const cpuDelta = raw.cpu_stats.cpu_usage.total_usage - raw.precpu_stats.cpu_usage.total_usage;
+    const systemDelta = (raw.cpu_stats.system_cpu_usage ?? 0) - (raw.precpu_stats.system_cpu_usage ?? 0);
+    const cpus = raw.cpu_stats.online_cpus ?? raw.cpu_stats.cpu_usage.percpu_usage?.length ?? 1;
+    const cpuUsage = systemDelta > 0 && cpuDelta > 0 ? (cpuDelta / systemDelta) * cpus : 0;
+    return { memoryUsage, cpuUsage };
+}
+/** Splits docker's multiplexed attach stream: 8-byte header (stream id, 3 pad, uint32 BE size) per frame. */
+function demuxStream(bytes) {
+    const decoder = new TextDecoder();
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let stdout = "";
+    let stderr = "";
+    let offset = 0;
+    while (offset + 8 <= bytes.length) {
+        const stream = bytes[offset];
+        const size = view.getUint32(offset + 4);
+        const chunk = decoder.decode(bytes.subarray(offset + 8, offset + 8 + size));
+        if (stream === 2)
+            stderr += chunk;
+        else
+            stdout += chunk;
+        offset += 8 + size;
+    }
+    return { stdout, stderr };
+}

package/dist/lib/image.d.ts

@@ -0,0 +1,14 @@
+import { type DockerClient } from "./docker.ts";
+export type ImageSpec = {
+    repository: string;
+    /** Bump whenever the build context changes; the tag is how an existing build is recognised. */
+    version: string;
+    /** Build context: file path -> contents. Must include "Dockerfile". */
+    context: Record<string, string>;
+};
+export interface ManagedImage {
+    readonly tag: string;
+    /** Builds the image if it isn't present yet, removes outdated versions, and returns its tag. */
+    ensure(): Promise<string>;
+}
+export declare function createManagedImage(docker: DockerClient, { repository, version, context }: ImageSpec): ManagedImage;

package/dist/lib/image.js

@@ -0,0 +1,29 @@
+import { DockerError } from "./docker.js";
+export function createManagedImage(docker, { repository, version, context }) {
+    const tag = `${repository}:${version}`;
+    // Concurrent builds of the same tag (from any process) are harmless: they produce the same image.
+    async function ensure() {
+        if (!(await docker.imageExists(tag))) {
+            await docker.buildImage({ tag, context, labels: { hyperbrane: "true", "hyperbrane.image.version": version } });
+        }
+        await removeOutdatedImages().catch((error) => console.warn(`removing outdated ${repository} images failed:`, error));
+        return tag;
+    }
+    // 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: [repository] });
+        const outdated = images
+            .flatMap((image) => image.RepoTags ?? [])
+            .filter((imageTag) => imageTag.startsWith(`${repository}:`) && imageTag !== tag);
+        for (const imageTag of outdated) {
+            try {
+                await docker.removeImage(imageTag);
+            }
+            catch (error) {
+                if (!(error instanceof DockerError && error.status === 409))
+                    throw error;
+            }
+        }
+    }
+    return { tag, ensure };
+}

package/dist/lib/jsonDirectory.d.ts

@@ -0,0 +1,28 @@
+import { type Sandbox } from "../sandbox/api.ts";
+/**
+ * One JSON file per record in a sandbox directory, 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 JsonDirectory<T> {
+    /** Null if missing. */
+    read(name: string): Promise<T | null>;
+    /** Stores the record unless one with that name exists; returns whichever record is stored afterwards. */
+    insert(name: string, record: T): Promise<T>;
+    /** Replaces the record. */
+    save(name: string, record: T): Promise<void>;
+    /** No-op if missing. */
+    remove(name: string): Promise<void>;
+    /** Empty if the directory doesn't exist yet. */
+    list(): Promise<T[]>;
+    /** list, each record with its name. */
+    entries(): Promise<[string, T][]>;
+}
+export declare class InvalidNameError extends Error {
+    name: string;
+}
+/** Throws InvalidNameError unless `name` is safe to use as a path segment. */
+export declare function checkName(name: string): string;
+/** `dir` resolves to a sandbox path; it's re-resolved per call so it can depend on the sandbox's home. */
+export declare function createJsonDirectory<T>(sandbox: Sandbox, dir: () => Promise<string>): JsonDirectory<T>;
+/** ~/.local/share/hyperbrane of the sandbox's user. */
+export declare function defaultDataDir(sandbox: Sandbox): Promise<string>;

package/dist/lib/jsonDirectory.js

@@ -0,0 +1,102 @@
+import { SandboxNotFoundError } from "../sandbox/api.js";
+const EXTENSION = ".json";
+// Same alphabet as dimension names; keeps names safe to use as file and directory names.
+const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$/;
+export class InvalidNameError extends Error {
+    name = "InvalidNameError";
+}
+/** Throws InvalidNameError unless `name` is safe to use as a path segment. */
+export function checkName(name) {
+    if (!NAME_PATTERN.test(name)) {
+        throw new InvalidNameError(`Invalid name "${name}": use letters, digits, "_", "." and "-", up to 63 characters`);
+    }
+    return name;
+}
+/** `dir` resolves to a sandbox path; it's re-resolved per call so it can depend on the sandbox's home. */
+export function createJsonDirectory(sandbox, dir) {
+    async function pathFor(name) {
+        return `${await dir()}/${checkName(name)}${EXTENSION}`;
+    }
+    function serialize(record) {
+        return JSON.stringify(record, null, 2) + "\n";
+    }
+    async function readPath(path) {
+        try {
+            return JSON.parse(new TextDecoder().decode(await sandbox.readFile(path)));
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return null;
+            throw error;
+        }
+    }
+    async function read(name) {
+        return readPath(await pathFor(name));
+    }
+    async function insert(name, record) {
+        const path = await pathFor(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 readPath(path)) ?? insert(name, record);
+    }
+    async function save(name, record) {
+        await sandbox.writeFile(await pathFor(name), serialize(record));
+    }
+    async function remove(name) {
+        await sandbox.removeFile(await pathFor(name));
+    }
+    // One command for the whole directory: over SSH or Boat, a call per record adds up. Falls back to
+    // listing and reading where the command can't run.
+    async function entries() {
+        const path = await dir();
+        const all = await sandbox.runCommand(["sh", "-c", LIST_SCRIPT, "sh", path]).catch(() => null);
+        if (all?.exitCode === MISSING)
+            return [];
+        if (all?.exitCode === 0) {
+            return all.stdout
+                .split(RECORD_END)
+                .filter((text) => text.trim())
+                .flatMap((text) => {
+                const newline = text.indexOf("\n");
+                try {
+                    return [[text.slice(0, newline).slice(0, -EXTENSION.length), JSON.parse(text.slice(newline + 1))]];
+                }
+                catch {
+                    return [];
+                }
+            });
+        }
+        let files;
+        try {
+            files = await sandbox.listDirectory(path);
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return [];
+            throw error;
+        }
+        // A record removed between listing and reading is simply skipped.
+        const records = await Promise.all(files
+            .filter((file) => file.endsWith(EXTENSION))
+            .map(async (file) => [file.slice(0, -EXTENSION.length), await readPath(`${path}/${file}`)]));
+        return records.filter((entry) => entry[1] !== null);
+    }
+    async function list() {
+        return (await entries()).map(([, record]) => record);
+    }
+    return { read, insert, save, remove, list, entries };
+}
+/** list's command exits with it when the directory doesn't exist. */
+const MISSING = 44;
+/** Ends each record list's command prints (its file name, a newline, its JSON): a record separator, which JSON escapes inside strings. */
+const RECORD_END = "\n\x1e\n";
+const LIST_SCRIPT = `cd "$1" 2>/dev/null || exit ${MISSING}
+for file in *${EXTENSION}; do
+  [ -f "$file" ] || continue
+  printf '%s\\n' "$file" && cat "$file" && printf '\\n\\036\\n'
+done`;
+/** ~/.local/share/hyperbrane of the sandbox's user. */
+export async function defaultDataDir(sandbox) {
+    return `${await sandbox.homeDirectory()}/.local/share/hyperbrane`;
+}

package/dist/lib/sleep.d.ts

@@ -0,0 +1,2 @@
+/** Resolves after `ms` milliseconds. Portable stand-in for Bun.sleep, so the services run under Node too. */
+export declare function sleep(ms: number): Promise<void>;

package/dist/lib/sleep.js

@@ -0,0 +1,4 @@
+/** Resolves after `ms` milliseconds. Portable stand-in for Bun.sleep, so the services run under Node too. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/lib/tar.d.ts

@@ -0,0 +1,2 @@
+/** Packs `files` (path -> contents) into a tar archive. Files are mode 0644, owned by root. */
+export declare function createTar(files: Record<string, string | Uint8Array>): Uint8Array<ArrayBuffer>;

package/dist/lib/tar.js

@@ -0,0 +1,65 @@
+// A minimal tar (ustar) writer: regular files only, which is all a docker build context or
+// putArchive needs (docker creates missing parent directories). Portable stand-in for Bun.Archive,
+// so the services run under Node too.
+const BLOCK = 512;
+function octal(value, width) {
+    // width includes the trailing NUL.
+    return value.toString(8).padStart(width - 1, "0") + "\0";
+}
+function header(name, size, mode, mtime) {
+    const encoder = new TextEncoder();
+    const block = new Uint8Array(BLOCK);
+    const put = (text, offset, width) => {
+        const bytes = encoder.encode(text);
+        if (bytes.length > width)
+            throw new Error(`tar: "${name}" is too long for the header`);
+        block.set(bytes, offset);
+    };
+    let path = name;
+    let prefix = "";
+    if (encoder.encode(name).length > 100) {
+        // ustar splits long paths at a "/" into prefix (155) and name (100).
+        const cut = name.lastIndexOf("/", 155);
+        if (cut <= 0)
+            throw new Error(`tar: "${name}" is too long`);
+        prefix = name.slice(0, cut);
+        path = name.slice(cut + 1);
+    }
+    put(path, 0, 100);
+    put(octal(mode, 8), 100, 8);
+    put(octal(0, 8), 108, 8); // uid
+    put(octal(0, 8), 116, 8); // gid
+    put(octal(size, 12), 124, 12);
+    put(octal(mtime, 12), 136, 12);
+    put("        ", 148, 8); // checksum placeholder: eight spaces while summing
+    put("0", 156, 1); // regular file
+    put("ustar\0", 257, 6);
+    put("00", 263, 2);
+    put(prefix, 345, 155);
+    let sum = 0;
+    for (const byte of block)
+        sum += byte;
+    put(sum.toString(8).padStart(6, "0") + "\0 ", 148, 8);
+    return block;
+}
+/** Packs `files` (path -> contents) into a tar archive. Files are mode 0644, owned by root. */
+export function createTar(files) {
+    const encoder = new TextEncoder();
+    const mtime = Math.floor(Date.now() / 1000);
+    const parts = [];
+    for (const [name, content] of Object.entries(files)) {
+        const data = typeof content === "string" ? encoder.encode(content) : content;
+        parts.push(header(name.replace(/^\/+/, ""), data.length, 0o644, mtime), data);
+        const padding = (BLOCK - (data.length % BLOCK)) % BLOCK;
+        if (padding)
+            parts.push(new Uint8Array(padding));
+    }
+    parts.push(new Uint8Array(BLOCK * 2)); // end of archive
+    const out = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}

package/dist/lib/version.d.ts

@@ -0,0 +1 @@
+export declare const HYPERBRANE_VERSION = "v1";

package/dist/lib/version.js

@@ -0,0 +1 @@
+export const HYPERBRANE_VERSION = "v1";

package/dist/portal-gateway/api.d.ts

@@ -0,0 +1,98 @@
+import type { UpstreamDefinition } from "./upstream.ts";
+export type Portal = {
+    name: string;
+    dimensionName: string;
+    gatewayName: string;
+};
+export type Gateway = {
+    name: string;
+    /**
+     * Registered when the gateway is created: the built-in upstreams (upstreams/) unless given, `[]`
+     * for none. A gateway that doesn't know an upstream passes its tokens to dimensions untouched.
+     */
+    upstreams?: Upstream[];
+};
+export type Upstream = UpstreamDefinition;
+/**
+ * Never the secret: "<upstream>.oauth" for a captured sign-in, "<upstream>.key.<key>" per API key,
+ * with the key's fake, which is what a client in a dimension is given in place of the key.
+ */
+export type GatewayCredential = {
+    name: string;
+    gatewayName: string;
+    type: "oauth" | "apiKey";
+    fake?: string;
+};
+/**
+ * Applies to traffic arriving through the gateway's portals. "tcp://<address>:<port>" covers every
+ * TCP connection by its destination, before any byte is sent: address is "*", an IPv4 address or a
+ * CIDR, port is "*" or a number ("tcp://10.0.0.0/8:*", "tcp://*:22"). Anything else is a glob over
+ * every HTTP(S) request's host:port/path?query, whatever its scheme: "https://github.com/*",
+ * "http://github.com/*" and "github.com" all cover github.com over HTTP and HTTPS, since a mask
+ * without a port matches any port and one without a path any path. "github.com:80/*" is plain HTTP
+ * only; "*.github.com/api/*" the API on any subdomain. Rules are checked in name order and the first
+ * match decides.
+ */
+export type TrafficRule = {
+    name: string;
+    urlMask: string;
+    action: "BLOCK" | "DELAY" | "ASK" | "INTERCEPT";
+    delayMs: number;
+};
+export interface PortalGatewayClient {
+    /** POST /v1/gateways — also replaces a container made from an older gateway image, keeping its state. */
+    createGateway(gateway: Gateway): Promise<Gateway>;
+    /** DELETE /v1/gateways/:gatewayName */
+    destroyGateway(gatewayName: string): Promise<void>;
+    /** GET /v1/gateways */
+    listGateways(): Promise<Gateway[]>;
+    /** POST /v1/gateways/:gatewayName/restart — resolves once it intercepts again; its portals are re-wired by the portal watcher. */
+    restartGateway(gatewayName: string): Promise<void>;
+    /** GET /v1/gateways/:gatewayName/credentials */
+    listCredentials(gatewayName: string): Promise<GatewayCredential[]>;
+    /** DELETE /v1/gateways/:gatewayName/credentials/:credentialName */
+    deleteCredential(gatewayName: string, credentialName: string): Promise<void>;
+    /** PUT /v1/gateways/:gatewayName/upstreams/:upstreamName — adds or replaces the definition. */
+    registerUpstream(gatewayName: string, upstream: Upstream): Promise<Upstream>;
+    /** GET /v1/gateways/:gatewayName/upstreams */
+    listUpstreams(gatewayName: string): Promise<Upstream[]>;
+    /** DELETE /v1/gateways/:gatewayName/upstreams/:upstreamName — with its credentials. */
+    removeUpstream(gatewayName: string, upstreamName: string): Promise<void>;
+    /**
+     * PUT /v1/gateways/:gatewayName/upstreams/:upstreamName/api-keys/:keyName — returns the key's fake,
+     * to give the client in the dimension (e.g. as its API key env var) in place of the key.
+     */
+    setApiKey(gatewayName: string, upstreamName: string, keyName: string, key: string): Promise<{
+        fake: string;
+    }>;
+    /** DELETE /v1/gateways/:gatewayName/upstreams/:upstreamName/api-keys/:keyName */
+    deleteApiKey(gatewayName: string, upstreamName: string, keyName: string): Promise<void>;
+    /** POST /v1/gateways/:gatewayName/traffic-rules */
+    createTrafficRule(gatewayName: string, rule: TrafficRule): Promise<TrafficRule>;
+    /** PUT /v1/gateways/:gatewayName/traffic-rules/:ruleName */
+    updateTrafficRule(gatewayName: string, rule: TrafficRule): Promise<TrafficRule>;
+    /** DELETE /v1/gateways/:gatewayName/traffic-rules/:ruleName */
+    deleteTrafficRule(gatewayName: string, ruleName: string): Promise<void>;
+    /** GET /v1/gateways/:gatewayName/traffic-rules */
+    listTrafficRules(gatewayName: string): Promise<TrafficRule[]>;
+    /** POST /v1/gateways/:gatewayName/traffic-rules/:ruleName/respond — releases the requests an ASK rule is holding. */
+    trafficRuleRespond(gatewayName: string, ruleName: string, action: "ALLOW" | "DENY"): Promise<void>;
+    /** POST /v1/portals */
+    createPortal(portal: Portal): Promise<Portal>;
+    /** DELETE /v1/portals/:portalName */
+    destroyPortal(portalName: string): Promise<void>;
+    /** GET /v1/portals */
+    listPortals(): Promise<Portal[]>;
+}
+/** The request can't be satisfied as sent (bad name, unsupported action, ...). */
+export declare class GatewayInvalidError extends Error {
+    name: string;
+}
+/** The name is taken with a different spec, or by a container hyperbrane doesn't own. */
+export declare class GatewayConflictError extends Error {
+    name: string;
+}
+/** A gateway, rule, dimension or portal the request refers to doesn't exist. */
+export declare class GatewayNotFoundError extends Error {
+    name: string;
+}