@molecule/api-code-sandbox-docker 1.0.0 → 1.0.2

package/dist/provider.js

@@ -6,10 +6,19 @@
  *
  * @module
  */
+import { readFile, statfs } from 'fs/promises';
 import http from 'http';
+import { freemem } from 'os';
+import { Readable } from 'stream';
 import { getLogger } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
 const logger = getLogger();
+import { exportContainerFiles, importContainerFiles } from './archive.js';
+import { measureDockerCapacity } from './capacity.js';
+import { verifyDockerEgress } from './egress.js';
+import { hibernateContainer, resumeContainer } from './hibernate.js';
+import { describeContainer, findContainers, listDockerVolumes, updateContainerResources, } from './inspect.js';
+import * as templates from './templates.js';
 const DEFAULT_IMAGE = 'node:22-slim';
 /**
  * Shell-safe single-quote escaping for file paths. Prevents command injection
@@ -34,6 +43,17 @@ const LABEL_PREFIX = 'molecule-sandbox';
 const DEFAULT_SANDBOX_NETWORK = 'molecule-sandbox';
 /** Default Docker daemon TCP port for a plain (unencrypted) `tcp://` endpoint. */
 const DEFAULT_DOCKER_TCP_PORT = 2375;
+/**
+ * Repository that holds sandbox templates, kept separate from the base image's
+ * repository so a template sweep can never reach `molecule-sandbox:latest`.
+ */
+const DEFAULT_TEMPLATE_REPOSITORY = 'molecule-sandbox-template';
+/** `X-Registry-Auth` for an anonymous or already-logged-in daemon. */
+const EMPTY_REGISTRY_AUTH = Buffer.from('{}').toString('base64');
+/** Ports published for every sandbox when the caller names none. */
+const DEFAULT_PUBLISH_PORTS = [4000, 5173];
+/** Maximum processes a sandbox may hold when the caller sets no `pidsLimit`. */
+const DEFAULT_PIDS_LIMIT = 512;
 /**
  * Parse a `DOCKER_HOST`-style value into an endpoint, honoring the docker-client
  * conventions: `unix:///path/to/docker.sock` selects a socket; `tcp://host:port`
@@ -135,6 +155,63 @@ class DockerMuxParser {
         }
     }
 }
+/**
+ * Validate the ports a caller asked to publish, falling back to this provider's
+ * historical API + Vite pair when it named none.
+ *
+ * Rejects rather than filters: a caller that asked for a port it cannot have
+ * needs to hear so, because the alternative is a dev server running inside a
+ * sandbox that nothing on the outside can ever reach — which looks like a broken
+ * application, not a bad argument.
+ *
+ * @param ports - Ports inside the sandbox the caller wants reachable.
+ * @returns The ports to expose and bind.
+ * @throws {Error} When a port is not a valid TCP port number.
+ */
+export function resolvePublishPorts(ports) {
+    if (!ports || ports.length === 0)
+        return DEFAULT_PUBLISH_PORTS;
+    for (const port of ports) {
+        if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+            throw new Error(`Invalid publish port ${String(port)}: must be an integer in 1-65535`);
+        }
+    }
+    return [...new Set(ports)];
+}
+/**
+ * Available memory in bytes, or `null` when it cannot be read.
+ *
+ * Prefers Linux `MemAvailable`, which is the kernel's estimate of what a new
+ * workload can use WITHOUT swapping and counts reclaimable page cache.
+ * `os.freemem()` excludes that cache and badly understates free memory on any
+ * warm host, so it is only the off-Linux fallback — using it as the primary
+ * signal rejects boots the host could comfortably serve.
+ *
+ * @returns Available bytes, or `null` when unreadable.
+ */
+async function availableMemoryBytes() {
+    try {
+        const match = /^MemAvailable:\s+(\d+)\s+kB/m.exec(await readFile('/proc/meminfo', 'utf-8'));
+        if (match) {
+            const kb = Number.parseInt(match[1], 10);
+            if (Number.isFinite(kb) && kb > 0)
+                return kb * 1024;
+        }
+    }
+    catch (_error) {
+        // /proc/meminfo is absent on non-Linux hosts and unreadable in some
+        // sandboxes — fall through to the portable estimate rather than failing.
+    }
+    try {
+        const bytes = freemem();
+        return Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+    }
+    catch (_error) {
+        // No usable memory reading at all — report "unknown" so the caller does not
+        // mistake it for "exhausted".
+        return null;
+    }
+}
 /**
  * Retry a Docker API operation that failed with a TRANSIENT fault — a request
  * timeout or a connection-level reset, i.e. the daemon was momentarily overwhelmed,
@@ -209,6 +286,20 @@ class DockerSandboxProvider {
     configNetwork;
     /** [C1-1] Memoize the one-time ICC-off network ensure so create() pays it only once. */
     networkEnsured = false;
+    /** Explicit template repository from config; env is consulted at call time. */
+    configTemplateRepository;
+    /** Explicit template registry from config; env is consulted at call time. */
+    configTemplateRegistry;
+    /** Explicit registry credential from config; env is consulted at call time. */
+    configTemplateRegistryAuth;
+    /**
+     * Whether this host still looks capable of CRIU checkpoints. Shared by
+     * `hibernate` and `resume` for every sandbox this provider hands out, so a host
+     * without CRIU pays one rejected request per process instead of one per
+     * hibernation. Held on the instance rather than at module scope so two
+     * providers (and two tests) do not inherit each other's verdict.
+     */
+    checkpoints = { supported: true };
     constructor(config = {}) {
         this.endpoint = resolveDockerEndpoint(config);
         this.baseImage = config.baseImage ?? DEFAULT_IMAGE;
@@ -217,6 +308,48 @@ class DockerSandboxProvider {
         this.defaultCpu = config.defaultCpu ?? 1;
         this.defaultMemoryMB = config.defaultMemoryMB ?? 1024;
         this.configNetwork = config.network;
+        this.configTemplateRepository = config.templateRepository;
+        this.configTemplateRegistry = config.templateRegistry;
+        this.configTemplateRegistryAuth = config.templateRegistryAuth;
+    }
+    /**
+     * Assemble the context every template operation runs against. Env is read here
+     * rather than in the constructor, matching {@link resolveNetwork}: this
+     * provider is commonly constructed before the process has loaded its
+     * environment.
+     *
+     * @returns The template context.
+     */
+    templateContext() {
+        return {
+            request: (path, method, body, timeoutMs, headers) => this.dockerApi(path, method, body, timeoutMs, headers),
+            download: (path, timeoutMs) => this.dockerDownload(path, timeoutMs),
+            upload: (path, body, timeoutMs) => this.dockerUpload(path, body, timeoutMs),
+            baseImage: this.baseImage,
+            repository: this.configTemplateRepository ??
+                process.env.SANDBOX_TEMPLATE_REPOSITORY ??
+                DEFAULT_TEMPLATE_REPOSITORY,
+            registry: this.configTemplateRegistry ?? process.env.SANDBOX_TEMPLATE_REGISTRY ?? '',
+            registryAuth: this.configTemplateRegistryAuth ??
+                process.env.SANDBOX_TEMPLATE_REGISTRY_AUTH ??
+                EMPTY_REGISTRY_AUTH,
+            labelPrefix: this.labelPrefix,
+            warn: (message, meta) => logger.warn(message, meta),
+            debug: (message, meta) => logger.debug(message, meta),
+        };
+    }
+    /**
+     * The context shared by the inspection capabilities.
+     *
+     * @returns The inspection context.
+     */
+    inspectContext() {
+        return {
+            request: (path, method, body, timeoutMs, headers) => this.dockerApi(path, method, body, timeoutMs, headers),
+            labelPrefix: this.labelPrefix,
+            warn: (message, meta) => logger.warn(message, meta),
+            debug: (message, meta) => logger.debug(message, meta),
+        };
     }
     /**
      * Resolve the Docker network to attach containers to. Precedence:
@@ -285,7 +418,22 @@ class DockerSandboxProvider {
         await this.ensureSandboxNetwork();
         const cpu = config.resources?.cpu ?? this.defaultCpu;
         const memoryMB = config.resources?.memoryMB ?? this.defaultMemoryMB;
-        const image = config.image ?? this.baseImage;
+        let image = config.image ?? this.baseImage;
+        // Booting from a template is the caller naming a filesystem it captured. If
+        // it is gone, FAIL — falling back to the base image would hand back a
+        // healthy-looking sandbox whose contents are not the ones that were asked
+        // for, and nothing downstream would notice.
+        if (config.templateId) {
+            const template = await templates.getTemplate(this.templateContext(), config.templateId);
+            if (!template) {
+                throw new Error(t('codeSandbox.docker.error.templateMissing', { templateId: config.templateId }, {
+                    defaultValue: `Cannot create a sandbox from template "${config.templateId}": it does not exist. ` +
+                        'Commit it first, or fetch it from the shared template store.',
+                }));
+            }
+            image = template.ref;
+        }
+        const publishPorts = resolvePublishPorts(config.publishPorts);
         const env = Object.entries(config.env ?? {}).map(([k, v]) => `${k}=${v}`);
         const labels = {
             [`${this.labelPrefix}.projectId`]: config.projectId,
@@ -311,7 +459,7 @@ class DockerSandboxProvider {
             // the Memory cap does not bound swap. [C1-2]
             MemorySwap: memoryBytes * 2,
             Init: true, // Use tini init to reap zombie processes
-            PidsLimit: 512,
+            PidsLimit: config.resources?.pidsLimit ?? DEFAULT_PIDS_LIMIT,
             SecurityOpt: ['no-new-privileges'],
             CapDrop: ['ALL'],
             // Minimal caps for the dev toolchain (file ownership + tini privilege drop).
@@ -320,11 +468,10 @@ class DockerSandboxProvider {
             // bridge. Egress filtering must be enforced host-side, not in a tenant-rooted
             // container.
             CapAdd: ['CHOWN', 'SETGID', 'SETUID'],
-            // Bind ports to localhost only — prevents external access
-            PortBindings: {
-                '4000/tcp': [{ HostIp: '127.0.0.1', HostPort: '' }],
-                '5173/tcp': [{ HostIp: '127.0.0.1', HostPort: '' }],
-            },
+            // Bind ports to localhost only — prevents external access. Which ports is
+            // the caller's business (`config.publishPorts`); the historical
+            // API + Vite pair is the default so existing callers are unaffected.
+            PortBindings: Object.fromEntries(publishPorts.map((port) => [`${port}/tcp`, [{ HostIp: '127.0.0.1', HostPort: '' }]])),
             Tmpfs: { '/tmp': 'rw,noexec,nosuid,size=256m' },
             ReadonlyPaths: [
                 '/proc/asound',
@@ -366,10 +513,7 @@ class DockerSandboxProvider {
             Env: env,
             Labels: labels,
             HostConfig: hostConfig,
-            ExposedPorts: {
-                '4000/tcp': {},
-                '5173/tcp': {},
-            },
+            ExposedPorts: Object.fromEntries(publishPorts.map((port) => [`${port}/tcp`, {}])),
         };
         // Retry a transient create timeout (daemon momentarily overwhelmed under
         // concurrent boots) instead of failing the whole sandbox boot. The onRetry
@@ -737,6 +881,46 @@ class DockerSandboxProvider {
                     },
                 };
             },
+            async hibernate() {
+                const outcome = await hibernateContainer({
+                    request: (path, method, body, timeoutMs, headers) => provider.dockerApi(path, method, body, timeoutMs, headers),
+                    checkpoints: provider.checkpoints,
+                    warn: (message, meta) => logger.warn(message, meta),
+                    info: (message, meta) => logger.info(message, meta),
+                }, containerId);
+                this.status = 'sleeping';
+                return outcome;
+            },
+            async resume() {
+                const outcome = await resumeContainer({
+                    request: (path, method, body, timeoutMs, headers) => provider.dockerApi(path, method, body, timeoutMs, headers),
+                    checkpoints: provider.checkpoints,
+                    warn: (message, meta) => logger.warn(message, meta),
+                    info: (message, meta) => logger.info(message, meta),
+                }, containerId);
+                this.status = 'running';
+                return outcome;
+            },
+            async setResources(resources) {
+                await updateContainerResources({
+                    request: (path, method, body, timeoutMs, headers) => provider.dockerApi(path, method, body, timeoutMs, headers),
+                    labelPrefix: provider.labelPrefix,
+                    warn: (message, meta) => logger.warn(message, meta),
+                    debug: (message, meta) => logger.debug(message, meta),
+                }, containerId, resources);
+            },
+            async exportFiles(path) {
+                return exportContainerFiles({
+                    download: (p, timeoutMs) => provider.dockerDownload(p, timeoutMs),
+                    upload: (p, body, timeoutMs) => provider.dockerUpload(p, body, timeoutMs),
+                }, containerId, path);
+            },
+            async importFiles(path, archive) {
+                await importContainerFiles({
+                    download: (p, timeoutMs) => provider.dockerDownload(p, timeoutMs),
+                    upload: (p, body, timeoutMs) => provider.dockerUpload(p, body, timeoutMs),
+                }, containerId, path, archive);
+            },
             onFileChange(_cb) {
                 let active = true;
                 const poll = async () => {
@@ -796,6 +980,138 @@ class DockerSandboxProvider {
             return false;
         }
     }
+    /**
+     * Prove whether the host actually denies sandbox egress.
+     *
+     * Delegates to {@link verifyDockerEgress}, which runs BOTH legs — outbound
+     * (DOCKER-USER) and host-bound (INPUT). See that module for why one leg is not
+     * enough: host-gateway traffic never traverses DOCKER-USER, so an outbound-only
+     * check reports "filtered" on a host whose SSH, Redis, monitoring and admin
+     * consoles are reachable from every sandbox.
+     *
+     * @returns What was observed about egress filtering.
+     */
+    async verifyEgress() {
+        return verifyDockerEgress({
+            request: (path, method, body, timeoutMs) => this.dockerApi(path, method, body, timeoutMs),
+            network: this.resolveNetwork(),
+            baseImage: this.baseImage,
+            labelPrefix: this.labelPrefix,
+            warn: (message, meta) => logger.warn(message, meta),
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Templates
+    // ---------------------------------------------------------------------------
+    /**
+     * Capture a sandbox's filesystem as a reusable template.
+     *
+     * See `templates.ts` for why this is not a plain `commit`: a sandbox keeps the
+     * project on a volume, and a volume is not part of a container's writable
+     * layer — so committing the sandbox itself produces an image that boots
+     * successfully with an empty workspace.
+     *
+     * @param options - What to capture and what to call it.
+     * @returns The template as it now exists.
+     */
+    async commitTemplate(options) {
+        return templates.commitTemplate(this.templateContext(), options);
+    }
+    /**
+     * Read one template by the caller's identifier.
+     *
+     * @param templateId - The caller's identifier.
+     * @returns The template, or `null` when no image carries that tag.
+     */
+    async getTemplate(templateId) {
+        return templates.getTemplate(this.templateContext(), templateId);
+    }
+    /**
+     * Enumerate templates in this provider's template repository.
+     *
+     * @param options - Narrowing by id prefix.
+     * @returns Every matching template.
+     */
+    async listTemplates(options) {
+        return templates.listTemplates(this.templateContext(), options);
+    }
+    /**
+     * Delete a template, refusing while a container is still backed by it.
+     *
+     * @param templateId - The caller's identifier.
+     */
+    async removeTemplate(templateId) {
+        return templates.removeTemplate(this.templateContext(), templateId);
+    }
+    /**
+     * Push a template to the configured registry so other hosts can boot from it.
+     *
+     * @param templateId - The caller's identifier.
+     */
+    async publishTemplate(templateId) {
+        return templates.publishTemplate(this.templateContext(), templateId);
+    }
+    /**
+     * Pull a template from the configured registry onto this host.
+     *
+     * @param templateId - The caller's identifier.
+     * @returns The now-local template, or `null` when the registry does not have it.
+     */
+    async fetchTemplate(templateId) {
+        return templates.fetchTemplate(this.templateContext(), templateId);
+    }
+    // ---------------------------------------------------------------------------
+    // Inspection
+    // ---------------------------------------------------------------------------
+    /**
+     * Describe one sandbox without building a handle for it.
+     *
+     * @param id - The container id.
+     * @returns The descriptor, or `null` when no such container exists.
+     */
+    async describe(id) {
+        return describeContainer(this.inspectContext(), id);
+    }
+    /**
+     * Find sandboxes by the labels the caller put on them.
+     *
+     * @param query - Narrowing by label, status and project.
+     * @returns Descriptors for every match.
+     */
+    async find(query) {
+        return findContainers(this.inspectContext(), query);
+    }
+    /**
+     * Enumerate named volumes and whether anything still has them attached.
+     *
+     * @param options - Narrowing by name prefix and attachment.
+     * @returns Every matching volume.
+     */
+    async listVolumes(options) {
+        return listDockerVolumes(this.inspectContext(), options);
+    }
+    /**
+     * Measure what the host backing this daemon can still fit.
+     *
+     * @returns Measured headroom and an explanation of anything unmeasurable.
+     */
+    async capacity() {
+        return measureDockerCapacity({
+            request: (path, method, body, timeoutMs, headers) => this.dockerApi(path, method, body, timeoutMs, headers),
+            // Only a unix-socket daemon writes to storage this process can measure.
+            daemonIsLocal: 'socketPath' in this.endpoint,
+            statfs: async (path) => {
+                const stats = await statfs(path);
+                return {
+                    bsize: Number(stats.bsize),
+                    bavail: Number(stats.bavail),
+                    ffree: Number(stats.ffree),
+                };
+            },
+            availableMemoryBytes,
+            warn: (message, meta) => logger.warn(message, meta),
+        });
+    }
     /**
      * Makes an HTTP request to the Docker Engine API via the Unix socket.
      * @param path - The API endpoint path (e.g. `/containers/create`).
@@ -806,15 +1122,20 @@ class DockerSandboxProvider {
      *   image's contents during those calls, which scales with image size — a
      *   multi-GB `/workspace` reliably exceeds 30 s, and a client-side timeout on
      *   a create that succeeds server-side leaks a duplicate container.
+     * @param headers - Extra request headers. Registry operations need
+     *   `X-Registry-Auth`, which the daemon requires even for anonymous pulls.
      * @returns The parsed JSON response, or raw text for non-JSON responses.
      */
-    async dockerApi(path, method = 'GET', body, timeoutMs = 30_000) {
+    async dockerApi(path, method = 'GET', body, timeoutMs = 30_000, headers) {
         return new Promise((resolve, reject) => {
             const opts = {
                 ...this.endpoint,
                 path: `/v1.44${path}`,
                 method,
-                headers: body ? { 'Content-Type': 'application/json' } : undefined,
+                headers: {
+                    ...(body ? { 'Content-Type': 'application/json' } : {}),
+                    ...headers,
+                },
             };
             const req = http.request(opts, (res) => {
                 const chunks = [];
@@ -845,6 +1166,96 @@ class DockerSandboxProvider {
             req.end();
         });
     }
+    /**
+     * Issue a Docker Engine API GET and hand back the response body as a byte
+     * stream.
+     *
+     * Unbuffered on purpose: this carries whole project trees, and materializing
+     * one in this process to hand it to the next call trades a slow transfer for
+     * an out-of-memory API. The error path DOES buffer, because an error body is
+     * a sentence and the caller needs to read it.
+     *
+     * @param path - The API endpoint path.
+     * @param timeoutMs - Request timeout (default 10 min).
+     * @returns The response body as an async byte stream.
+     */
+    dockerDownload(path, timeoutMs = 600_000) {
+        return new Promise((resolve, reject) => {
+            const req = http.request({ ...this.endpoint, path: `/v1.44${path}`, method: 'GET' }, (res) => {
+                if (res.statusCode && res.statusCode >= 400) {
+                    const chunks = [];
+                    res.on('data', (chunk) => chunks.push(chunk));
+                    res.on('end', () => {
+                        reject(new Error(t('codeSandbox.docker.error.apiError', {
+                            method: 'GET',
+                            path,
+                            status: String(res.statusCode),
+                            error: Buffer.concat(chunks).toString(),
+                        }, {
+                            defaultValue: `Docker API GET ${path}: ${res.statusCode} ${Buffer.concat(chunks).toString()}`,
+                        })));
+                    });
+                    res.on('error', reject);
+                    return;
+                }
+                resolve(res);
+            });
+            req.setTimeout(timeoutMs, () => {
+                req.destroy(new Error(`Docker API timeout: GET ${path}`));
+            });
+            req.on('error', reject);
+            req.end();
+        });
+    }
+    /**
+     * Issue a Docker Engine API PUT whose request body is a byte stream.
+     *
+     * Piped rather than written in a loop so Node applies backpressure — without
+     * it, a fast source fills this process's memory with everything the socket has
+     * not drained yet, which for a project tree is the whole tree.
+     *
+     * @param path - The API endpoint path.
+     * @param body - The request body as an async byte stream.
+     * @param timeoutMs - Request timeout (default 10 min).
+     */
+    dockerUpload(path, body, timeoutMs = 600_000) {
+        return new Promise((resolve, reject) => {
+            const req = http.request({
+                ...this.endpoint,
+                path: `/v1.44${path}`,
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/x-tar' },
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(t('codeSandbox.docker.error.apiError', {
+                            method: 'PUT',
+                            path,
+                            status: String(res.statusCode),
+                            error: Buffer.concat(chunks).toString(),
+                        }, {
+                            defaultValue: `Docker API PUT ${path}: ${res.statusCode} ${Buffer.concat(chunks).toString()}`,
+                        })));
+                        return;
+                    }
+                    resolve();
+                });
+                res.on('error', reject);
+            });
+            req.setTimeout(timeoutMs, () => {
+                req.destroy(new Error(`Docker API timeout: PUT ${path}`));
+            });
+            req.on('error', reject);
+            const source = Readable.from(body);
+            source.on('error', (error) => {
+                req.destroy(error);
+                reject(error);
+            });
+            source.pipe(req);
+        });
+    }
     /**
      * Like `dockerApi` but returns the raw response Buffer without parsing.
      * Used for exec start responses which return a multiplexed binary stream.

package/dist/request.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The Docker Engine API transports every capability module is given.
+ *
+ * Each capability lives in its own module and receives its transport as a
+ * parameter rather than reaching for `http` itself. That is not decoration: a
+ * module that opens its own socket can only be tested by intercepting HTTP, and
+ * the things worth testing here — a push that reports failure inside a 200
+ * response body, an eviction that must refuse when it cannot see what is in use —
+ * are decisions about response CONTENT, not about wire mechanics. Injecting the
+ * request function makes each of those a plain function call in a test.
+ *
+ * Three transports rather than one, because the Engine API genuinely has three
+ * shapes: JSON in/JSON out, a tar stream out, and a tar stream in. Forcing the
+ * streaming pair through the JSON transport would mean buffering a whole project
+ * tree in memory, which is the thing bulk transfer exists to avoid.
+ *
+ * @module
+ */
+/**
+ * Issues a Docker Engine API request and returns the parsed JSON response (or
+ * the raw text when the body is not JSON — several endpoints stream JSON lines).
+ *
+ * Implementations MUST reject on a 4xx/5xx status. Several Engine endpoints also
+ * report failure INSIDE a 200 body; see {@link assertNoStreamError}.
+ *
+ * @param path - API path below the version prefix, e.g. `/containers/create`.
+ * @param method - HTTP method; defaults to `GET`.
+ * @param body - Optional JSON request body.
+ * @param timeoutMs - Request timeout.
+ * @param headers - Extra request headers (e.g. `X-Registry-Auth`).
+ * @returns The parsed JSON response, or raw text for non-JSON bodies.
+ */
+export type DockerRequest = (path: string, method?: string, body?: unknown, timeoutMs?: number, headers?: Record<string, string>) => Promise<unknown>;
+/**
+ * Issues a Docker Engine API GET and hands back the response body as a byte
+ * stream, unbuffered.
+ *
+ * @param path - API path below the version prefix.
+ * @param timeoutMs - Request timeout.
+ * @returns The response body as an async byte stream.
+ */
+export type DockerDownload = (path: string, timeoutMs?: number) => Promise<AsyncIterable<Uint8Array>>;
+/**
+ * Issues a Docker Engine API PUT whose request body is a byte stream,
+ * unbuffered and with backpressure.
+ *
+ * @param path - API path below the version prefix.
+ * @param body - The request body as an async byte stream.
+ * @param timeoutMs - Request timeout.
+ */
+export type DockerUpload = (path: string, body: AsyncIterable<Uint8Array>, timeoutMs?: number) => Promise<void>;
+/**
+ * Fail on an error reported inside an otherwise-successful streaming response.
+ *
+ * `/images/create` (pull), `/images/{name}/push` and friends answer `200 OK` and
+ * then stream newline-delimited JSON progress objects. A failure — no such
+ * manifest, denied credentials, a broken layer — arrives as an `error` field in
+ * that stream, LONG after the status line. Treating the 200 as success is how a
+ * fleet ends up believing every host has a template that only one host has.
+ *
+ * @param response - The value returned by a {@link DockerRequest} for a streaming endpoint.
+ * @param operation - Short description used in the thrown message.
+ * @throws {Error} When the stream carried an error object.
+ */
+export declare function assertNoStreamError(response: unknown, operation: string): void;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAA;AAErB;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,EAC/B,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAA;AAElB;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAsB9E"}

package/dist/request.js

@@ -0,0 +1,56 @@
+/**
+ * The Docker Engine API transports every capability module is given.
+ *
+ * Each capability lives in its own module and receives its transport as a
+ * parameter rather than reaching for `http` itself. That is not decoration: a
+ * module that opens its own socket can only be tested by intercepting HTTP, and
+ * the things worth testing here — a push that reports failure inside a 200
+ * response body, an eviction that must refuse when it cannot see what is in use —
+ * are decisions about response CONTENT, not about wire mechanics. Injecting the
+ * request function makes each of those a plain function call in a test.
+ *
+ * Three transports rather than one, because the Engine API genuinely has three
+ * shapes: JSON in/JSON out, a tar stream out, and a tar stream in. Forcing the
+ * streaming pair through the JSON transport would mean buffering a whole project
+ * tree in memory, which is the thing bulk transfer exists to avoid.
+ *
+ * @module
+ */
+/**
+ * Fail on an error reported inside an otherwise-successful streaming response.
+ *
+ * `/images/create` (pull), `/images/{name}/push` and friends answer `200 OK` and
+ * then stream newline-delimited JSON progress objects. A failure — no such
+ * manifest, denied credentials, a broken layer — arrives as an `error` field in
+ * that stream, LONG after the status line. Treating the 200 as success is how a
+ * fleet ends up believing every host has a template that only one host has.
+ *
+ * @param response - The value returned by a {@link DockerRequest} for a streaming endpoint.
+ * @param operation - Short description used in the thrown message.
+ * @throws {Error} When the stream carried an error object.
+ */
+export function assertNoStreamError(response, operation) {
+    if (typeof response !== 'string') {
+        // A parsed object comes from a single-JSON-document endpoint; those already
+        // surfaced failure through the status code.
+        return;
+    }
+    for (const line of response.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (_error) {
+            // A partial line from a chunked stream is not an error report; the error
+            // object, if there is one, is a complete line of its own.
+            continue;
+        }
+        const message = parsed.errorDetail?.message ?? parsed.error;
+        if (message !== undefined && message !== null && message !== '') {
+            throw new Error(`Docker ${operation} failed: ${String(message)}`);
+        }
+    }
+}