rightsize 0.1.0

package/dist/backend-docker/backend.js

@@ -0,0 +1,336 @@
+import { spawnSync } from "node:child_process";
+import { BackendError, PortBindConflictError } from "../core/errors.js";
+import { RunId } from "../core/run-id.js";
+import { DockerClient } from "./client.js";
+import { FrameDemuxer, LineAssembler } from "./frames.js";
+import { extractIds, extractNumber, extractString } from "./json.js";
+import { isPortBindConflictMessage } from "./port-conflict.js";
+import { labelFilterQuery, RUN_ID_LABEL_KEY } from "./labels.js";
+const STOP_TIMEOUT_SECS = 10;
+function encodeQueryValue(s) {
+    return encodeURIComponent(s);
+}
+/** `image` split into `[repository, tag]` for `POST /images/create?fromImage=&tag=`; a tag-less reference defaults to `latest`, matching Docker's own convention. */
+function splitRepoTag(image) {
+    if (image.includes("@")) {
+        return [image, ""];
+    }
+    // The tag separator is the LAST colon after the last slash, so a registry
+    // host:port prefix (`localhost:5000/redis`) isn't mistaken for one.
+    const slashIdx = image.lastIndexOf("/") + 1;
+    const relColon = image.slice(slashIdx).lastIndexOf(":");
+    if (relColon === -1) {
+        return [image, "latest"];
+    }
+    const colon = slashIdx + relColon;
+    return [image.slice(0, colon), image.slice(colon + 1)];
+}
+/** Builds the `POST /containers/create` JSON body: port bindings pinned to `127.0.0.1`, read-only/read-write binds, the `host.docker.internal` extra host, and the run-id label. */
+function buildCreateBody(spec) {
+    const exposedPorts = {};
+    const portBindings = {};
+    for (const p of spec.ports) {
+        const key = `${p.guestPort}/tcp`;
+        exposedPorts[key] = {};
+        portBindings[key] = [{ HostIp: "127.0.0.1", HostPort: String(p.hostPort) }];
+    }
+    const binds = spec.mounts.map((m) => `${m.hostPath}:${m.guestPath}:${m.readOnly ? "ro" : "rw"}`);
+    const body = {
+        Image: spec.image,
+        Env: spec.env.map(([k, v]) => `${k}=${v}`),
+        ExposedPorts: exposedPorts,
+        Labels: { [RUN_ID_LABEL_KEY]: spec.runId },
+        HostConfig: {
+            PortBindings: portBindings,
+            Binds: binds,
+            ExtraHosts: ["host.docker.internal:host-gateway"],
+        },
+    };
+    if (spec.command !== undefined) {
+        body.Cmd = [...spec.command];
+    }
+    if (spec.memoryLimitMb !== undefined) {
+        body.HostConfig.Memory = spec.memoryLimitMb * 1024 * 1024;
+    }
+    return body;
+}
+async function drainFrames(body, onStdout, onStderr) {
+    const demuxer = new FrameDemuxer();
+    for await (const chunk of body) {
+        const frames = demuxer.push(chunk);
+        for (const frame of frames) {
+            if (frame.streamType === "stdout") {
+                onStdout(frame.payload);
+            }
+            else if (frame.streamType === "stderr") {
+                onStderr(frame.payload);
+            }
+        }
+    }
+}
+/**
+ * Drives the Docker daemon over `DockerClient`. This is also the
+ * correctness oracle other backends are checked against, since Docker
+ * enforces semantics (read-only mounts, native networks) microsandbox only
+ * emulates.
+ *
+ * Unlike the msb backend, a `SandboxHandle` here carries no companion
+ * mutable state keyed by id: every operation is a stateless HTTP call
+ * against the daemon-assigned container id already on the handle, so
+ * there's nothing to look up in a side table.
+ */
+export class DockerBackend {
+    client;
+    /** `"docker"` — matched against `RIGHTSIZE_BACKEND`. */
+    name = "docker";
+    supportsNativeNetworks = true;
+    networkIds = new Map();
+    constructor(client) {
+        this.client = client;
+    }
+    /** Exposed for the transport regression test: the socket path this backend's client actually dials. */
+    socketPathForTest() {
+        return this.client.getSocketPath();
+    }
+    async pullIfMissing(image) {
+        const inspectPath = `/images/${encodeQueryValue(image)}/json`;
+        const inspect = await this.client.request("GET", inspectPath);
+        if (inspect.status === 200) {
+            return;
+        }
+        const [repo, tag] = splitRepoTag(image);
+        const pullPath = `/images/create?fromImage=${encodeQueryValue(repo)}&tag=${encodeQueryValue(tag)}`;
+        const resp = await this.client.request("POST", pullPath);
+        if (resp.status >= 400) {
+            throw new BackendError(`docker could not pull image '${image}' (HTTP ${resp.status}): ${resp.body.toString()}`);
+        }
+    }
+    async connectNetwork(containerId, networkId, aliases) {
+        const body = JSON.stringify({ Container: containerId, EndpointConfig: { Aliases: [...aliases] } });
+        const path = `/networks/${networkId}/connect`;
+        const resp = await this.client.request("POST", path, body);
+        if (resp.status >= 400) {
+            throw new BackendError(`docker could not connect container ${containerId} to network ${networkId} (HTTP ${resp.status}): ${resp.body.toString()}`);
+        }
+    }
+    async ensureNetworkGetId(networkId) {
+        const cached = this.networkIds.get(networkId);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const filters = JSON.stringify({ name: [networkId] });
+        const listPath = `/networks?filters=${encodeQueryValue(filters)}`;
+        const list = await this.client.request("GET", listPath);
+        if (list.status === 200) {
+            const ids = extractIds(list.body.toString());
+            if (ids.length > 0 && ids[0] !== undefined) {
+                this.networkIds.set(networkId, ids[0]);
+                return ids[0];
+            }
+        }
+        const createBody = JSON.stringify({ Name: networkId });
+        const created = await this.client.request("POST", "/networks/create", createBody);
+        if (created.status >= 400) {
+            throw new BackendError(`docker could not create network '${networkId}' (HTTP ${created.status}): ${created.body.toString()}`);
+        }
+        const id = extractString(created.body.toString(), "Id");
+        if (id === undefined) {
+            throw new BackendError(`docker's network-create response for '${networkId}' had no Id field (body: ${created.body.toString()})`);
+        }
+        this.networkIds.set(networkId, id);
+        return id;
+    }
+    async create(spec) {
+        await this.pullIfMissing(spec.image);
+        const body = JSON.stringify(buildCreateBody(spec));
+        const path = `/containers/create?name=${encodeQueryValue(spec.name)}`;
+        const resp = await this.client.request("POST", path, body);
+        if (resp.status >= 400) {
+            throw new BackendError(`docker could not create container '${spec.name}' (HTTP ${resp.status}): ${resp.body.toString()}`);
+        }
+        const id = extractString(resp.body.toString(), "Id");
+        if (id === undefined) {
+            throw new BackendError(`docker's container-create response for '${spec.name}' had no Id field (body: ${resp.body.toString()})`);
+        }
+        if (spec.networkId !== undefined) {
+            const daemonNetworkId = await this.ensureNetworkGetId(spec.networkId);
+            await this.connectNetwork(id, daemonNetworkId, spec.aliases);
+        }
+        return { id, spec };
+    }
+    async start(handle) {
+        const path = `/containers/${handle.id}/start`;
+        const resp = await this.client.request("POST", path);
+        if (resp.status === 204 || resp.status === 304) {
+            return; // 304 = already started; treated as success like the daemon intends.
+        }
+        const message = resp.body.toString();
+        if (resp.status === 500 && isPortBindConflictMessage(message)) {
+            throw new PortBindConflictError(`docker could not bind a host port for ${handle.id}: ${message}`);
+        }
+        throw new BackendError(`docker could not start container ${handle.id} (HTTP ${resp.status}): ${message}`);
+    }
+    async stop(handle) {
+        const path = `/containers/${handle.id}/stop?t=${STOP_TIMEOUT_SECS}`;
+        await this.client.request("POST", path).catch(() => { }); // best-effort
+    }
+    async remove(handle) {
+        const path = `/containers/${handle.id}?force=true`;
+        await this.client.request("DELETE", path).catch(() => { }); // best-effort
+    }
+    async exec(handle, cmd) {
+        const createBody = JSON.stringify({ AttachStdout: true, AttachStderr: true, Cmd: [...cmd] });
+        const createPath = `/containers/${handle.id}/exec`;
+        const created = await this.client.request("POST", createPath, createBody);
+        if (created.status >= 400) {
+            throw new BackendError(`docker could not create an exec for container ${handle.id} (HTTP ${created.status}): ${created.body.toString()}`);
+        }
+        const execId = extractString(created.body.toString(), "Id");
+        if (execId === undefined) {
+            throw new BackendError(`docker's exec-create response for container ${handle.id} had no Id field (body: ${created.body.toString()})`);
+        }
+        const startPath = `/exec/${execId}/start`;
+        const startBody = JSON.stringify({ Detach: false });
+        const { status, body } = await this.client.requestStream("POST", startPath, startBody);
+        if (status >= 400) {
+            throw new BackendError(`docker could not start exec ${execId} for container ${handle.id} (HTTP ${status})`);
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        await drainFrames(body, (p) => stdoutChunks.push(p), (p) => stderrChunks.push(p));
+        const inspectPath = `/exec/${execId}/json`;
+        const inspected = await this.client.request("GET", inspectPath);
+        const exitCode = extractNumber(inspected.body.toString(), "ExitCode") ?? -1;
+        return {
+            exitCode,
+            stdout: Buffer.concat(stdoutChunks).toString(),
+            stderr: Buffer.concat(stderrChunks).toString(),
+        };
+    }
+    async logs(handle) {
+        const path = `/containers/${handle.id}/logs?stdout=1&stderr=1&tail=1000`;
+        const { status, body } = await this.client.requestStream("GET", path);
+        if (status >= 400) {
+            throw new BackendError(`docker could not fetch logs for container ${handle.id} (HTTP ${status})`);
+        }
+        const assembler = new LineAssembler();
+        let out = "";
+        await drainFrames(body, (p) => {
+            for (const line of assembler.feed(p.toString())) {
+                out += line + "\n";
+            }
+        }, (p) => {
+            for (const line of assembler.feed(p.toString())) {
+                out += line + "\n";
+            }
+        });
+        const tail = assembler.flush();
+        if (tail !== undefined) {
+            out += tail + "\n";
+        }
+        return out;
+    }
+    /** Docker's stream ends cleanly on its own once the workload stops — unlike msb's `logs -f`, so no watchdog is needed here. */
+    async followLogs(handle, consumer) {
+        const path = `/containers/${handle.id}/logs?stdout=1&stderr=1&follow=1&tail=all`;
+        const { status, body } = await this.client.requestStream("GET", path);
+        if (status >= 400) {
+            throw new BackendError(`docker could not follow logs for container ${handle.id} (HTTP ${status})`);
+        }
+        let closeRequested = false;
+        const demuxer = new FrameDemuxer();
+        const assembler = new LineAssembler();
+        const readerDone = (async () => {
+            try {
+                for await (const chunk of body) {
+                    if (closeRequested) {
+                        return;
+                    }
+                    for (const frame of demuxer.push(chunk)) {
+                        if (frame.streamType !== "stdout" && frame.streamType !== "stderr") {
+                            continue;
+                        }
+                        for (const line of assembler.feed(frame.payload.toString())) {
+                            if (closeRequested) {
+                                return;
+                            }
+                            consumer(line);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Best-effort: a stream error just ends delivery.
+                return;
+            }
+            if (closeRequested) {
+                return; // stop delivery, never flush — an explicit close beat the stream to its own end.
+            }
+            const tail = assembler.flush();
+            if (tail !== undefined) {
+                consumer(tail);
+            }
+        })();
+        return {
+            close: async () => {
+                closeRequested = true;
+                body.destroy();
+                await readerDone.catch(() => { });
+            },
+        };
+    }
+    /** No-op: docker relies entirely on native networks (`ensureNetwork`/`create`'s connect step) — there is nothing to emulate here, unlike msb's exec-tunnel links. */
+    async installNetworkLinks(_handle, _links) { }
+    async ensureNetwork(networkId) {
+        await this.ensureNetworkGetId(networkId);
+    }
+    async removeNetwork(networkId) {
+        const daemonId = this.networkIds.get(networkId);
+        this.networkIds.delete(networkId);
+        if (daemonId !== undefined) {
+            await this.client.request("DELETE", `/networks/${daemonId}`).catch(() => { }); // best-effort
+        }
+    }
+    /** Removes every container carrying this run's label — the reaper safety net's normal-exit counterpart. */
+    async close() {
+        const filters = labelFilterQuery(RunId.value);
+        const path = `/containers/json?all=true&filters=${encodeQueryValue(filters)}`;
+        const listed = await this.client.request("GET", path).catch(() => undefined);
+        if (listed === undefined || listed.status !== 200) {
+            return; // best-effort: nothing more to do if even listing fails.
+        }
+        const ids = extractIds(listed.body.toString());
+        for (const id of ids) {
+            await this.client.request("DELETE", `/containers/${id}?force=true`).catch(() => { });
+        }
+    }
+    /**
+     * Synchronous, blocking teardown for the process-exit path. Node has no
+     * synchronous HTTP client, so this shells out to `curl --unix-socket` via
+     * `child_process.spawnSync` — curl ships on macOS and virtually every
+     * Linux CI image, and `spawnSync` genuinely blocks the exiting process the
+     * way the `"exit"` handler requires. If curl is unavailable, this is a
+     * silent no-op: the label-scoped orphan reaper each backend runs at
+     * startup (`close()`'s own reaping plus the next run's sweep) is the real
+     * safety net for that case, not this best-effort fast path.
+     */
+    cleanupSync(id) {
+        const socketPath = this.client.getSocketPath();
+        try {
+            spawnSync("curl", [
+                "--silent",
+                "--max-time",
+                "5",
+                "--unix-socket",
+                socketPath,
+                "-X",
+                "DELETE",
+                `http://localhost/containers/${id}?force=true`,
+            ]);
+        }
+        catch {
+            // Best-effort — see the doc above.
+        }
+    }
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend-docker/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend-docker/backend.ts"],"names":[],"mappings":"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"}

package/dist/backend-docker/client.d.ts

@@ -0,0 +1,82 @@
+import type { IncomingMessage } from "node:http";
+/**
+ * Bounds how many header bytes this client will accumulate before giving up.
+ * A well-behaved daemon's status line + header block is at most a few
+ * hundred bytes; `node:http` already enforces its own such limit internally,
+ * but this constant documents the ceiling this backend would apply if it
+ * were parsing headers by hand — kept here as the single source of truth
+ * other backend code can cite.
+ */
+export declare const MAX_HEADER_BYTES: number;
+/** A fully-buffered daemon response, returned by `DockerClient.request`. */
+export interface DockerResponse {
+    /** The HTTP status code. */
+    readonly status: number;
+    /** The full response body. */
+    readonly body: Buffer;
+}
+/** A daemon response whose body is left as a live stream, returned by `DockerClient.requestStream` for `exec`/`logs` calls. */
+export interface DockerStreamResponse {
+    /** The HTTP status code. */
+    readonly status: number;
+    /** Whether the daemon sent `Transfer-Encoding: chunked` (node:http already de-chunks it transparently either way). */
+    readonly chunked: boolean;
+    /** The `Content-Length` header value, when present and not chunked. */
+    readonly contentLength: number | undefined;
+    /** The raw, already-de-chunked response stream — `node:http` handles `Transfer-Encoding` transparently, so the frame demuxer only ever sees raw framed bytes. */
+    readonly body: IncomingMessage;
+}
+/**
+ * The pure seam `DockerClient.fromEnv` delegates to: given a `DOCKER_HOST`
+ * value (or `undefined`), returns the unix socket path this client should
+ * dial. A `tcp://`/`http://` `DOCKER_HOST` falls back to the default socket
+ * path rather than attempting a TCP connection — this client has no TCP
+ * transport at all (see the module docs on why: sharing an HTTP stack a
+ * consumer can bump is exactly the failure mode being avoided).
+ */
+export declare function socketPathFromDockerHost(host: string | undefined): string;
+/**
+ * A from-scratch HTTP client over the Docker daemon's unix socket, built on
+ * `node:http`'s `socketPath` option rather than a general-purpose Docker SDK
+ * (`dockerode`) — the point of hand-rolling is that this client can only
+ * ever dial a unix socket path, never a TCP host. A shared HTTP stack a
+ * consuming project also depends on has, on another runtime, been observed
+ * to misroute a Docker client onto TCP `localhost:2375` instead of the
+ * daemon's real unix socket; owning this client end-to-end makes that
+ * misrouting structurally impossible; see the standing regression test in
+ * `backend.test.ts`.
+ *
+ * Every daemon endpoint this backend calls returns either a small buffered
+ * JSON body (unary calls — `request`) or a stream of raw framed bytes
+ * (`exec`/`logs` — `requestStream`). Both go through `POST
+ * /exec/{id}/start`-style ordinary responses, never `/attach`'s connection
+ * hijack, so `node:http`'s `IncomingMessage` is sufficient for either case —
+ * no need to drop to a raw socket.
+ */
+export declare class DockerClient {
+    private readonly socketPath;
+    private readonly connectTimeoutMs;
+    constructor(socketPath?: string, connectTimeoutMs?: number);
+    /** Builds a client honoring `DOCKER_HOST` (a `unix://` path, a bare path, or the daemon's default socket). */
+    static fromEnv(): DockerClient;
+    /** The unix socket path this client dials — never a TCP host. */
+    getSocketPath(): string;
+    /**
+     * One request whose entire response body is read into memory before
+     * returning — every daemon call this backend makes except
+     * `exec`/`logs` streaming (`requestStream`). Bounded by
+     * `RESPONSE_TIMEOUT_MS` so a wedged daemon fails this call with a named
+     * error instead of hanging the caller forever.
+     */
+    request(method: string, path: string, body?: string): Promise<DockerResponse>;
+    /**
+     * Issues a request and returns the status plus the still-open response
+     * stream, for callers (`exec`/`logs`, the frame demuxer) that consume a
+     * de-chunked body incrementally rather than buffering it all first.
+     * Deliberately NOT wrapped in `RESPONSE_TIMEOUT_MS` — `followLogs` streams
+     * for as long as the workload runs, by design.
+     */
+    requestStream(method: string, path: string, body?: string): Promise<DockerStreamResponse>;
+    private send;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/backend-docker/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/backend-docker/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AA4BjD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,QAAW,CAAC;AAEzC,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+HAA+H;AAC/H,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sHAAsH;IACtH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,iKAAiK;IACjK,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAWzE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAK3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBALhB,UAAU,GAAE,MAA6D,EAKzE,gBAAgB,GAAE,MAA2B;IAGhE,8GAA8G;IAC9G,MAAM,CAAC,OAAO,IAAI,YAAY;IAI9B,iEAAiE;IACjE,aAAa,IAAI,MAAM;IAIvB;;;;;;OAMG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuBnF;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAU/F,OAAO,CAAC,IAAI;CAkEb"}

package/dist/backend-docker/client.js

@@ -0,0 +1,190 @@
+import * as http from "node:http";
+import { BackendError } from "../core/errors.js";
+const DEFAULT_SOCKET_PATH = "/var/run/docker.sock";
+/**
+ * Ceiling on one unary request/response cycle — connect, write, read
+ * headers, read the whole body. Deliberately NOT applied to streaming reads
+ * (`followLogs`): that call is meant to block for as long as the workload
+ * runs, so bounding it here would kill a perfectly healthy long-lived
+ * stream. Unary calls (create/start/stop/exec-inspect/logs/ls) get it
+ * because a wedged daemon must fail the caller promptly instead of hanging
+ * the whole test run.
+ */
+const RESPONSE_TIMEOUT_MS = 600_000;
+/**
+ * Ceiling on connecting to the daemon's unix socket and receiving response
+ * headers — the phase before `RESPONSE_TIMEOUT_MS`'s body-reading window
+ * even starts. Without this, a request whose connection or header phase
+ * never completes (an unresponsive daemon, a wedged socket) hangs `send()`
+ * forever with nothing else in this client ever getting the chance to time
+ * it out — `request()`'s own timer only starts once `send()` has already
+ * resolved with a response. Observed in practice: an intermittent hang here
+ * under Bun's `node:http` implementation, not merely a theoretical gap.
+ */
+const CONNECT_TIMEOUT_MS = 30_000;
+/**
+ * Bounds how many header bytes this client will accumulate before giving up.
+ * A well-behaved daemon's status line + header block is at most a few
+ * hundred bytes; `node:http` already enforces its own such limit internally,
+ * but this constant documents the ceiling this backend would apply if it
+ * were parsing headers by hand — kept here as the single source of truth
+ * other backend code can cite.
+ */
+export const MAX_HEADER_BYTES = 8 * 1024;
+/**
+ * The pure seam `DockerClient.fromEnv` delegates to: given a `DOCKER_HOST`
+ * value (or `undefined`), returns the unix socket path this client should
+ * dial. A `tcp://`/`http://` `DOCKER_HOST` falls back to the default socket
+ * path rather than attempting a TCP connection — this client has no TCP
+ * transport at all (see the module docs on why: sharing an HTTP stack a
+ * consumer can bump is exactly the failure mode being avoided).
+ */
+export function socketPathFromDockerHost(host) {
+    if (host === undefined) {
+        return DEFAULT_SOCKET_PATH;
+    }
+    if (host.startsWith("unix://")) {
+        return host.slice("unix://".length);
+    }
+    if (host.startsWith("/")) {
+        return host;
+    }
+    return DEFAULT_SOCKET_PATH;
+}
+/**
+ * A from-scratch HTTP client over the Docker daemon's unix socket, built on
+ * `node:http`'s `socketPath` option rather than a general-purpose Docker SDK
+ * (`dockerode`) — the point of hand-rolling is that this client can only
+ * ever dial a unix socket path, never a TCP host. A shared HTTP stack a
+ * consuming project also depends on has, on another runtime, been observed
+ * to misroute a Docker client onto TCP `localhost:2375` instead of the
+ * daemon's real unix socket; owning this client end-to-end makes that
+ * misrouting structurally impossible; see the standing regression test in
+ * `backend.test.ts`.
+ *
+ * Every daemon endpoint this backend calls returns either a small buffered
+ * JSON body (unary calls — `request`) or a stream of raw framed bytes
+ * (`exec`/`logs` — `requestStream`). Both go through `POST
+ * /exec/{id}/start`-style ordinary responses, never `/attach`'s connection
+ * hijack, so `node:http`'s `IncomingMessage` is sufficient for either case —
+ * no need to drop to a raw socket.
+ */
+export class DockerClient {
+    socketPath;
+    connectTimeoutMs;
+    constructor(socketPath = socketPathFromDockerHost(process.env["DOCKER_HOST"]), 
+    // Test seam: production call sites never pass this, so every real client
+    // gets the real ceiling. A fixture that wants to prove the timeout path
+    // itself fires (without actually waiting 30s) constructs with a much
+    // smaller override instead.
+    connectTimeoutMs = CONNECT_TIMEOUT_MS) {
+        this.socketPath = socketPath;
+        this.connectTimeoutMs = connectTimeoutMs;
+    }
+    /** Builds a client honoring `DOCKER_HOST` (a `unix://` path, a bare path, or the daemon's default socket). */
+    static fromEnv() {
+        return new DockerClient(socketPathFromDockerHost(process.env["DOCKER_HOST"]));
+    }
+    /** The unix socket path this client dials — never a TCP host. */
+    getSocketPath() {
+        return this.socketPath;
+    }
+    /**
+     * One request whose entire response body is read into memory before
+     * returning — every daemon call this backend makes except
+     * `exec`/`logs` streaming (`requestStream`). Bounded by
+     * `RESPONSE_TIMEOUT_MS` so a wedged daemon fails this call with a named
+     * error instead of hanging the caller forever.
+     */
+    async request(method, path, body) {
+        const { res } = await this.send(method, path, body);
+        const chunks = [];
+        await new Promise((resolveBody, rejectBody) => {
+            const timer = setTimeout(() => {
+                res.destroy();
+                rejectBody(new BackendError(`${method} ${path} to the Docker daemon did not complete within ${RESPONSE_TIMEOUT_MS / 1000}s`));
+            }, RESPONSE_TIMEOUT_MS);
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                clearTimeout(timer);
+                resolveBody();
+            });
+            res.on("error", (err) => {
+                clearTimeout(timer);
+                rejectBody(new BackendError(`reading a response from the Docker daemon: ${err.message}`));
+            });
+        });
+        return { status: res.statusCode ?? 0, body: Buffer.concat(chunks) };
+    }
+    /**
+     * Issues a request and returns the status plus the still-open response
+     * stream, for callers (`exec`/`logs`, the frame demuxer) that consume a
+     * de-chunked body incrementally rather than buffering it all first.
+     * Deliberately NOT wrapped in `RESPONSE_TIMEOUT_MS` — `followLogs` streams
+     * for as long as the workload runs, by design.
+     */
+    async requestStream(method, path, body) {
+        const { res } = await this.send(method, path, body);
+        const transferEncoding = res.headers["transfer-encoding"];
+        const chunked = typeof transferEncoding === "string" && transferEncoding.toLowerCase().includes("chunked");
+        const contentLengthHeader = res.headers["content-length"];
+        const contentLength = typeof contentLengthHeader === "string" && !chunked ? Number.parseInt(contentLengthHeader, 10) : undefined;
+        return { status: res.statusCode ?? 0, chunked, contentLength, body: res };
+    }
+    send(method, path, body) {
+        return new Promise((resolveSend, rejectSend) => {
+            const headers = {};
+            if (body !== undefined) {
+                headers["Content-Length"] = String(Buffer.byteLength(body));
+                headers["Content-Type"] = "application/json";
+            }
+            let settled = false;
+            const req = http.request({
+                socketPath: this.socketPath,
+                method,
+                path,
+                headers,
+                // No connection pooling: `http.globalAgent`'s default keep-alive
+                // behavior holds the underlying unix-socket connection open after
+                // the response completes, hoping to reuse it for a later request
+                // to the same socket path. Nothing in this client ever reuses a
+                // connection (every call opens its own), so a pooled socket just
+                // sits idle — which keeps a bare `node --test` process (or any
+                // short-lived script) alive well past its last container
+                // operation, since Node won't exit while a socket handle is open.
+                // `agent: false` makes every request its own unshared connection
+                // that node:http tears down as soon as the response ends.
+                agent: false,
+            }, (res) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(connectTimer);
+                resolveSend({ res });
+            });
+            const connectTimer = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                req.destroy();
+                rejectSend(new BackendError(`${method} ${path} to the Docker daemon at ${this.socketPath} did not connect/respond within ` +
+                    `${this.connectTimeoutMs / 1000}s — is the daemon running and responsive?`));
+            }, this.connectTimeoutMs);
+            req.on("error", (err) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(connectTimer);
+                rejectSend(new BackendError(`could not connect to the Docker daemon at ${this.socketPath} — is Docker/Podman/Colima running? (${err.message})`));
+            });
+            if (body !== undefined) {
+                req.write(body);
+            }
+            req.end();
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/backend-docker/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/backend-docker/client.ts"],"names":[],"mappings":"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"}