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

package/README.md

@@ -0,0 +1,319 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-05T12:53:11.363Z
+-->
+
+# @molecule/api-code-sandbox-docker
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Docker code-sandbox provider for molecule.dev.
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-code-sandbox-docker @molecule/api-bond @molecule/api-code-sandbox @molecule/api-i18n
+```
+
+## API
+
+### Interfaces
+
+#### `ContainerInfo`
+
+Container Info interface.
+
+```typescript
+interface ContainerInfo {
+  id: string
+  name: string
+  status: string
+  ports: Array<{ host: number; container: number }>
+}
+```
+
+#### `DockerConfig`
+
+Configuration for docker.
+
+```typescript
+interface DockerConfig {
+  /**
+   * Docker unix-socket path. Defaults to `/var/run/docker.sock` (or the
+   * `DOCKER_SOCKET_PATH` env var). This is the default transport; it is ignored
+   * when a TCP endpoint is selected via `host`/`port` or a `tcp://` `DOCKER_HOST`.
+   */
+  socketPath?: string
+  /**
+   * Connect to a remote/TCP Docker daemon at this host instead of the unix
+   * socket. When set, the provider issues all Docker Engine API calls over
+   * plain TCP to `host:port` (`port` defaults to 2375) and `socketPath` is
+   * ignored. Also honored via `DOCKER_HOST` (`tcp://host:port`). Plain
+   * (unencrypted) TCP only — for a TLS-protected daemon (2376) front it with a
+   * local socket proxy and point `socketPath` at that.
+   */
+  host?: string
+  /** TCP port for `host` (default 2375). Ignored unless `host` (or a `tcp://` `DOCKER_HOST`) selects a TCP endpoint. */
+  port?: number
+  /** Base image for sandbox containers. Defaults to node:22-slim. Must already be present on the host — the provider never pulls images. */
+  baseImage?: string
+  /** Default CPU allocation (cores). */
+  defaultCpu?: number
+  /** Default memory allocation (MB). */
+  defaultMemoryMB?: number
+  /**
+   * Docker network the sandbox containers attach to (sets each container's
+   * `NetworkMode`). Overrides the `SANDBOX_DOCKER_NETWORK` env var. Defaults to
+   * the ICC-off isolated `molecule-sandbox` network, auto-created on first use so
+   * tenants are L2-isolated by default. Setting it to the shared `bridge` gives NO
+   * cross-tenant isolation and is refused in production. [C1-1]
+   */
+  network?: string
+  /** Container label prefix for identification. */
+  labelPrefix?: string
+  /** Preview URL template. Use {port} placeholder. */
+  previewUrlTemplate?: string
+  /**
+   * Docker repository holding sandbox TEMPLATES — one tag per template id.
+   * Defaults to `molecule-sandbox-template` (or `SANDBOX_TEMPLATE_REPOSITORY`).
+   *
+   * Deliberately NOT the base image's repository. Sharing one repository between
+   * the base image and every template makes `docker images <repo>` and any
+   * cleanup written against it operate on both, and the only thing standing
+   * between a template sweep and the base image is a tag-prefix convention.
+   */
+  templateRepository?: string
+  /**
+   * Registry host for sharing templates across hosts, e.g. `registry.example.com`
+   * (or `SANDBOX_TEMPLATE_REGISTRY`). When unset, `publishTemplate`/`fetchTemplate`
+   * throw with an actionable message: the daemon CAN talk to a registry, so the
+   * capability is present and only the address is missing.
+   */
+  templateRegistry?: string
+  /**
+   * Base64-encoded Docker `X-Registry-Auth` value for {@link DockerConfig.templateRegistry}
+   * (or `SANDBOX_TEMPLATE_REGISTRY_AUTH`). Defaults to an empty credential set,
+   * which is what an anonymous or already-logged-in daemon needs.
+   */
+  templateRegistryAuth?: string
+}
+```
+
+#### `ProcessEnv`
+
+Environment variables the Docker sandbox provider reads.
+
+```typescript
+interface ProcessEnv {
+  /** Unix-socket path for the Docker daemon (default `/var/run/docker.sock`). Overridden by `config.socketPath`. */
+  DOCKER_SOCKET_PATH?: string
+  /** Docker daemon endpoint, docker-client style: `tcp://host:port` or `unix:///path/to/docker.sock`. Overridden by `config.host`/`config.socketPath`. */
+  DOCKER_HOST?: string
+  /** Docker network sandbox containers attach to (default `molecule-sandbox`, ICC-off). Overridden by `config.network`. [C1-1] */
+  SANDBOX_DOCKER_NETWORK?: string
+  /** Docker repository holding sandbox templates (default `molecule-sandbox-template`). Overridden by `config.templateRepository`. */
+  SANDBOX_TEMPLATE_REPOSITORY?: string
+  /** Registry host for sharing templates across hosts. Overridden by `config.templateRegistry`. */
+  SANDBOX_TEMPLATE_REGISTRY?: string
+  /** Base64 `X-Registry-Auth` value for `SANDBOX_TEMPLATE_REGISTRY`. Overridden by `config.templateRegistryAuth`. */
+  SANDBOX_TEMPLATE_REGISTRY_AUTH?: string
+}
+```
+
+### Functions
+
+#### `createProvider(config)`
+
+Creates a new `DockerSandboxProvider` instance with the given configuration.
+
+```typescript
+function createProvider(config?: DockerConfig): SandboxProvider
+```
+
+- `config` — Optional Docker-specific configuration: daemon endpoint (`socketPath`, or `host`/`port` for a TCP daemon; `DOCKER_HOST` is also honored), `baseImage`, CPU/memory defaults, and the sandbox `network`.
+
+**Returns:** A `SandboxProvider` that manages Docker containers as sandboxes.
+
+#### `resolvePublishPorts(ports)`
+
+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.
+
+```typescript
+function resolvePublishPorts(ports?: number[]): number[]
+```
+
+- `ports` — Ports inside the sandbox the caller wants reachable.
+
+**Returns:** The ports to expose and bind.
+
+#### `withTransientRetry(op, opts)`
+
+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,
+not the request malformed. This is the fix for the observed "first cold boot of a
+concurrent batch dies on `Docker API timeout: POST /containers/create`" failure:
+a single 30 s create timeout under daemon load currently kills the whole boot.
+
+HTTP error responses (4xx/5xx) are deliberately NOT retried — those are real
+answers (no-such-image, name conflict), not transient network faults. Bounded
+attempts with linear backoff.
+
+`onRetry` is the idempotency guard: a create that TIMED OUT client-side may have
+still succeeded server-side, so before re-issuing it the caller can adopt the
+already-created resource (looked up by a unique label) instead of leaking a
+duplicate container. If `onRetry` returns non-null, that value is used and the
+operation is not re-issued.
+
+```typescript
+function withTransientRetry(
+  op: () => Promise<T>,
+  opts: {
+    label: string
+    attempts?: number
+    onRetry?: () => Promise<T | null>
+    delayMs?: (attempt: number) => number
+    log?: { warn: (message: string, meta?: unknown) => void }
+  },
+): Promise<T>
+```
+
+- `op` — the operation to attempt.
+- `opts` — tuning + the optional adopt-on-retry guard.
+- `opts.label` — short operation name for log lines.
+- `opts.attempts` — max attempts (default 3).
+- `opts.onRetry` — adopt-an-existing-resource guard, run before each retry.
+- `opts.delayMs` — backoff for attempt N (default `400 * N` ms).
+- `opts.log` — optional logger for retry warnings.
+
+**Returns:** the operation's result, or an adopted result from `onRetry`.
+
+### Constants
+
+#### `provider`
+
+The provider implementation.
+
+```typescript
+const provider: SandboxProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-code-sandbox` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/api-code-sandbox'
+import { provider } from '@molecule/api-code-sandbox-docker'
+
+export function setupCodeSandboxDocker(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-code-sandbox` ^1.0.1
+- `@molecule/api-i18n` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-code-sandbox`
+- `@molecule/api-i18n`
+
+**Tenant network isolation (secure default).** Each sandbox is placed on a dedicated
+user-defined Docker network created with inter-container communication DISABLED
+(`com.docker.network.bridge.enable_icc=false`), so one tenant's sandbox cannot reach another
+tenant's Vite/API dev-server ports by IP. Do NOT set `SANDBOX_DOCKER_NETWORK="bridge"` — the
+shared docker bridge has ICC enabled (no cross-tenant isolation) and is REFUSED in production.
+Override `SANDBOX_DOCKER_NETWORK` only to point at another dedicated ICC-off network. This is
+an L2 isolation control; pair it with host-layer default-deny egress filtering (operator-
+provisioned) for full isolation. [C1-1]
+
+**Prerequisites.** A reachable Docker daemon and the base image already pulled
+on the host. The daemon is reached over a unix socket by default
+(`config.socketPath` ?? `DOCKER_SOCKET_PATH` ?? `/var/run/docker.sock`); a
+remote or rootless daemon can be selected with `config.host`/`config.port` or a
+`DOCKER_HOST` (`tcp://host:port` or `unix:///path`). Only PLAIN (unencrypted)
+TCP is supported — front a TLS-protected daemon (2376) with a local socket
+proxy. The provider never pulls images, so `create()` fails with a no-such-image
+error if the base image (default `node:22-slim`, or `config.baseImage`) is
+absent. The isolated sandbox network is auto-created on first use; it is NOT a
+prerequisite.
+
+**No per-sandbox disk quota.** The Docker API cannot portably cap a
+container/volume size (it needs specific storage drivers — e.g. overlay2 on xfs
+with `pquota` — and errors on the common overlay2/ext4 host), so this provider
+enforces none. The core `resources.diskMB` is accepted but not applied here; cap
+disk at the host / volume level instead. `setResources({ diskMB })` THROWS
+rather than accepting a ceiling it cannot enforce.
+
+**Templates are not `commit` alone, and that is not an optimization.**
+`commitTemplate` copies the caller-named `capturePaths` into a throwaway,
+volume-less container and commits THAT. A sandbox keeps the project on a
+volume, and a volume is not part of a container's writable layer — so
+committing a sandbox directly yields an image that builds, tags, and boots
+with an empty workspace, with no error anywhere. The throwaway container
+handles tenant-authored bytes and is committed into something other tenants
+boot, so it runs with `--network none`, `CapDrop: ALL` plus the three
+capabilities extraction needs, a memory cap and a process cap, and setuid/setgid
+bits are stripped from the extracted tree afterwards.
+
+Templates live in their OWN repository (`templateRepository`, default
+`molecule-sandbox-template`) rather than sharing the base image's, so nothing
+written to sweep templates can reach the base image. `publishTemplate` /
+`fetchTemplate` use a Docker registry and require `templateRegistry`; without
+it they THROW rather than returning "not found", because "there is no shared
+store" and "the shared store does not have it" are different answers.
+
+**`hibernate()`/`resume()` report which mechanism ran.** A CRIU checkpoint
+preserves the process tree; a stop does not, and whether CRIU is available is a
+property of the host (the daemon's experimental flag plus the `criu` package),
+discovered at runtime. A sandbox that runs its dev servers as detached exec
+processes comes back from a stop-style wake alive and serving nothing, so
+callers must branch on `processesPreserved` — never on `status`, which says
+`running` either way. The first response that shows CRIU is unavailable
+disables it for the rest of the process.
+
+**`find()` costs one request per match.** Docker's container LIST omits
+`State.StartedAt`, which is the only field distinguishing an interrupted
+creation (`startedAt: null` — holds storage forever, will never run) from an
+ordinary stopped sandbox, so each match is then inspected. Narrow with
+`labels`; an unfiltered query on a busy host inspects every container.
+
+**`capacity()` measures THIS host, so it reports nothing for a TCP daemon.**
+Over a `tcp://` endpoint the daemon writes to a different machine's storage,
+and returning this machine's numbers would be a confident wrong answer — so it
+returns empty `headroom` and says why. On a local socket it reports free bytes
+and free inodes on the daemon's `DockerRootDir` plus `MemAvailable`. Inodes are
+omitted (not reported as zero) on filesystems with dynamic inode allocation.
+`admits` is always `null`: Docker has no quota of its own to consult, so the
+floors and the refusal stay with the caller.
+
+## Translations
+
+Translation strings are provided by `@molecule/api-locales-code-sandbox-docker`.

package/dist/archive.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Bulk file transfer in and out of a Docker sandbox, as POSIX tar streams.
+ *
+ * The Engine API has a first-class endpoint pair for this
+ * (`GET`/`PUT /containers/{id}/archive`), so the bond does not need to
+ * orchestrate `tar` through an exec. That matters beyond tidiness: an exec-based
+ * pipe has to survive two hijacked sockets and gives no status code you can
+ * trust, which is how a workspace capture ends up "succeeding" with half a tree.
+ *
+ * Nothing is buffered. A project tree is gigabytes across hundreds of thousands
+ * of files; reading one into this process to hand it to the next call would trade
+ * a slow transfer for a dead API.
+ *
+ * **Extraction does not restore ownership or setuid bits.** `copyUIDGID` is left
+ * off, and callers capturing a tenant-authored tree into something another tenant
+ * boots must additionally strip setuid/setgid — `commitTemplate` does. An archive
+ * is data, and honoring the mode bits in data is how it becomes an escalation.
+ *
+ * @module
+ */
+import type { DockerDownload, DockerUpload } from './request.js';
+/** What the archive capability needs from the provider. */
+export interface ArchiveContext {
+    download: DockerDownload;
+    upload: DockerUpload;
+}
+/**
+ * Stream a directory tree out of a sandbox as a POSIX tar archive.
+ *
+ * The archive is rooted at the LAST segment of `path` — an export of
+ * `/workspace` yields entries under `workspace/` — which is what makes it
+ * extractable into the parent directory on the way back in.
+ *
+ * @param ctx - Archive context.
+ * @param containerId - The sandbox to read from.
+ * @param path - Absolute path inside the sandbox.
+ * @returns A tar byte stream.
+ */
+export declare function exportContainerFiles(ctx: ArchiveContext, containerId: string, path: string): Promise<AsyncIterable<Uint8Array>>;
+/**
+ * Stream a POSIX tar archive into a sandbox, extracting it at `path`.
+ *
+ * @param ctx - Archive context.
+ * @param containerId - The sandbox to write to.
+ * @param path - Absolute destination directory inside the sandbox.
+ * @param archive - The tar byte stream to extract.
+ */
+export declare function importContainerFiles(ctx: ArchiveContext, containerId: string, path: string, archive: AsyncIterable<Uint8Array>): Promise<void>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhE,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAA;IACxB,MAAM,EAAE,YAAY,CAAA;CACrB;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAMpC;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/archive.js

@@ -0,0 +1,61 @@
+/**
+ * Bulk file transfer in and out of a Docker sandbox, as POSIX tar streams.
+ *
+ * The Engine API has a first-class endpoint pair for this
+ * (`GET`/`PUT /containers/{id}/archive`), so the bond does not need to
+ * orchestrate `tar` through an exec. That matters beyond tidiness: an exec-based
+ * pipe has to survive two hijacked sockets and gives no status code you can
+ * trust, which is how a workspace capture ends up "succeeding" with half a tree.
+ *
+ * Nothing is buffered. A project tree is gigabytes across hundreds of thousands
+ * of files; reading one into this process to hand it to the next call would trade
+ * a slow transfer for a dead API.
+ *
+ * **Extraction does not restore ownership or setuid bits.** `copyUIDGID` is left
+ * off, and callers capturing a tenant-authored tree into something another tenant
+ * boots must additionally strip setuid/setgid — `commitTemplate` does. An archive
+ * is data, and honoring the mode bits in data is how it becomes an escalation.
+ *
+ * @module
+ */
+/** Generous by design: this moves whole project trees, not files. */
+const TRANSFER_TIMEOUT_MS = 600_000;
+/**
+ * Reject a path that is not a plain absolute path.
+ *
+ * @param path - Candidate path.
+ * @throws {Error} When the path is relative or contains a traversal segment.
+ */
+function assertAbsolutePath(path) {
+    if (!path.startsWith('/') || path.includes('..') || path.includes('\0')) {
+        throw new Error(`Invalid sandbox path ${JSON.stringify(path.slice(0, 64))}: must be absolute and free of ".." segments`);
+    }
+}
+/**
+ * Stream a directory tree out of a sandbox as a POSIX tar archive.
+ *
+ * The archive is rooted at the LAST segment of `path` — an export of
+ * `/workspace` yields entries under `workspace/` — which is what makes it
+ * extractable into the parent directory on the way back in.
+ *
+ * @param ctx - Archive context.
+ * @param containerId - The sandbox to read from.
+ * @param path - Absolute path inside the sandbox.
+ * @returns A tar byte stream.
+ */
+export async function exportContainerFiles(ctx, containerId, path) {
+    assertAbsolutePath(path);
+    return ctx.download(`/containers/${containerId}/archive?path=${encodeURIComponent(path)}`, TRANSFER_TIMEOUT_MS);
+}
+/**
+ * Stream a POSIX tar archive into a sandbox, extracting it at `path`.
+ *
+ * @param ctx - Archive context.
+ * @param containerId - The sandbox to write to.
+ * @param path - Absolute destination directory inside the sandbox.
+ * @param archive - The tar byte stream to extract.
+ */
+export async function importContainerFiles(ctx, containerId, path, archive) {
+    assertAbsolutePath(path);
+    await ctx.upload(`/containers/${containerId}/archive?path=${encodeURIComponent(path)}`, archive, TRANSFER_TIMEOUT_MS);
+}

package/dist/capacity.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What this Docker host can still fit.
+ *
+ * A sandbox is admitted long before it is expensive: creating one populates a
+ * fresh volume with a dependency tree, and by the time that fails the host is
+ * already out of something and every OTHER sandbox on it is failing too. So the
+ * caller wants to refuse the boot while it can still say so cleanly — and to do
+ * that it needs a measurement only the provider can take.
+ *
+ * Three axes, because they run out separately and independently:
+ *
+ * - **Blocks.** The obvious one.
+ * - **Inodes.** A populated `node_modules` is hundreds of thousands of tiny
+ *   files. On a filesystem with a fixed inode table this exhausts first, and
+ *   every file creation on the host then fails with `ENOSPC` while `df -h`
+ *   reports gigabytes free — a failure that looks like nothing else.
+ * - **Memory.** Each running sandbox holds a live container resident, and unlike
+ *   disk this is NOT reclaimed by idle hibernation on any useful timescale. A
+ *   burst of simultaneously-active users oversubscribes the host until the OOM
+ *   killer starts choosing victims among sandboxes that were working fine.
+ *
+ * `MemAvailable` from `/proc/meminfo`, not `os.freemem()`. The kernel's estimate
+ * counts reclaimable page cache; `MemFree` does not, and on any warm host it
+ * understates free memory badly enough to reject boots the host could serve.
+ *
+ * **This measures the host THIS PROCESS runs on**, which is only the right host
+ * when the daemon is local. Over a TCP endpoint the numbers would describe the
+ * wrong machine, so the answer is `inconclusive`-shaped instead: no headroom
+ * fields, and a `detail` that says why. Reporting a comfortable local number for
+ * a remote daemon is the exact conflation this codebase refuses everywhere else.
+ *
+ * @module
+ */
+import type { SandboxCapacity } from '@molecule/api-code-sandbox';
+import type { DockerRequest } from './request.js';
+/** The subset of `fs.StatsFs` this module uses. */
+export interface FilesystemStats {
+    /** Block size in bytes. */
+    bsize: number;
+    /** Blocks available to an unprivileged process. */
+    bavail: number;
+    /** Free file nodes, or `-1`/`0` on filesystems without a fixed inode table. */
+    ffree: number;
+}
+/** What the capacity capability needs from the provider. */
+export interface CapacityContext {
+    request: DockerRequest;
+    /**
+     * Whether the daemon is reached over a local unix socket. Only then does this
+     * process's filesystem describe the storage the daemon writes to.
+     */
+    daemonIsLocal: boolean;
+    /** Filesystem statistics for a path. Injected so this is testable without a disk. */
+    statfs: (path: string) => Promise<FilesystemStats>;
+    /** Available memory in bytes, or `null` when it cannot be read. */
+    availableMemoryBytes: () => Promise<number | null>;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Measure what the host backing this daemon can still fit.
+ *
+ * `admits` is always `null`: Docker has no admission opinion of its own — it has
+ * no quota, no plan, and no notion of "too many". The caller compares the
+ * headroom against its own floors. A provider that DID have such an opinion
+ * (an account quota, a rate limit) would answer here instead.
+ *
+ * @param ctx - Capacity context.
+ * @returns Measured headroom and an explanation of anything unmeasurable.
+ */
+export declare function measureDockerCapacity(ctx: CapacityContext): Promise<SandboxCapacity>;
+//# sourceMappingURL=capacity.d.ts.map

package/dist/capacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacity.d.ts","sourceRoot":"","sources":["../src/capacity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAA;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAA;IACtB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAA;IACtB,qFAAqF;IACrF,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA;IAClD,mEAAmE;IACnE,oBAAoB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAClD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACjE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAuD1F"}

package/dist/capacity.js

@@ -0,0 +1,98 @@
+/**
+ * What this Docker host can still fit.
+ *
+ * A sandbox is admitted long before it is expensive: creating one populates a
+ * fresh volume with a dependency tree, and by the time that fails the host is
+ * already out of something and every OTHER sandbox on it is failing too. So the
+ * caller wants to refuse the boot while it can still say so cleanly — and to do
+ * that it needs a measurement only the provider can take.
+ *
+ * Three axes, because they run out separately and independently:
+ *
+ * - **Blocks.** The obvious one.
+ * - **Inodes.** A populated `node_modules` is hundreds of thousands of tiny
+ *   files. On a filesystem with a fixed inode table this exhausts first, and
+ *   every file creation on the host then fails with `ENOSPC` while `df -h`
+ *   reports gigabytes free — a failure that looks like nothing else.
+ * - **Memory.** Each running sandbox holds a live container resident, and unlike
+ *   disk this is NOT reclaimed by idle hibernation on any useful timescale. A
+ *   burst of simultaneously-active users oversubscribes the host until the OOM
+ *   killer starts choosing victims among sandboxes that were working fine.
+ *
+ * `MemAvailable` from `/proc/meminfo`, not `os.freemem()`. The kernel's estimate
+ * counts reclaimable page cache; `MemFree` does not, and on any warm host it
+ * understates free memory badly enough to reject boots the host could serve.
+ *
+ * **This measures the host THIS PROCESS runs on**, which is only the right host
+ * when the daemon is local. Over a TCP endpoint the numbers would describe the
+ * wrong machine, so the answer is `inconclusive`-shaped instead: no headroom
+ * fields, and a `detail` that says why. Reporting a comfortable local number for
+ * a remote daemon is the exact conflation this codebase refuses everywhere else.
+ *
+ * @module
+ */
+/**
+ * Measure what the host backing this daemon can still fit.
+ *
+ * `admits` is always `null`: Docker has no admission opinion of its own — it has
+ * no quota, no plan, and no notion of "too many". The caller compares the
+ * headroom against its own floors. A provider that DID have such an opinion
+ * (an account quota, a rate limit) would answer here instead.
+ *
+ * @param ctx - Capacity context.
+ * @returns Measured headroom and an explanation of anything unmeasurable.
+ */
+export async function measureDockerCapacity(ctx) {
+    if (!ctx.daemonIsLocal) {
+        return {
+            admits: null,
+            detail: 'The Docker daemon is reached over a TCP endpoint, so this process cannot measure the ' +
+                'storage or memory the daemon actually writes to. No headroom is reported rather than ' +
+                "reporting this machine's numbers for a different machine.",
+            headroom: {},
+        };
+    }
+    const notes = [];
+    const headroom = {};
+    let rootDir = '/var/lib/docker';
+    try {
+        const info = (await ctx.request('/info'));
+        if (info?.DockerRootDir)
+            rootDir = info.DockerRootDir;
+    }
+    catch (error) {
+        // Not fatal: the default root is right on the overwhelming majority of
+        // hosts, and a wrong path surfaces as a statfs failure below rather than as
+        // a confident wrong number.
+        ctx.warn?.('Could not read DockerRootDir from the daemon — assuming the default', { error });
+        notes.push(`could not read the daemon's storage root, assumed ${rootDir}`);
+    }
+    try {
+        const stats = await ctx.statfs(rootDir);
+        headroom.diskBytes = stats.bavail * stats.bsize;
+        // A filesystem with dynamic inodes (btrfs, xfs) reports 0 or -1 free nodes.
+        // That is "not applicable", not "exhausted", so it is omitted rather than
+        // reported as zero — a caller comparing against a floor would refuse every
+        // boot on such a host.
+        if (stats.ffree > 0)
+            headroom.inodes = stats.ffree;
+    }
+    catch (error) {
+        ctx.warn?.('Could not measure free space on the daemon storage root', { rootDir, error });
+        notes.push(`free space on ${rootDir} is unmeasurable`);
+    }
+    const memoryBytes = await ctx.availableMemoryBytes();
+    if (memoryBytes === null) {
+        notes.push('available memory is unreadable on this platform');
+    }
+    else {
+        headroom.memoryBytes = memoryBytes;
+    }
+    return {
+        admits: null,
+        detail: notes.length > 0
+            ? `Measured the host backing the local Docker daemon (${rootDir}); ${notes.join('; ')}.`
+            : `Measured the host backing the local Docker daemon (${rootDir}).`,
+        headroom,
+    };
+}

package/dist/egress.d.ts

@@ -0,0 +1,49 @@
+import type { EgressVerdict } from '@molecule/api-code-sandbox';
+import type { DockerRequest } from './request.js';
+/** Inputs the probe needs from the provider. */
+export interface EgressProbeContext {
+    request: DockerRequest;
+    /** The sandbox network name — the probe must be subject to the same rules. */
+    network: string;
+    /** Image to run the probe in; needs a `node` binary. */
+    baseImage: string;
+    /** Label namespace, used for the orphan sweep. */
+    labelPrefix: string;
+    /** Optional logger for cleanup failures. */
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * The client program: raw `net.connect` to each target.
+ *
+ * Raw sockets, never `fetch` — proxy env is blanked AND a raw connect ignores it
+ * regardless, so this exercises the DIRECT path the proxy does not cover and only
+ * the firewall stops.
+ *
+ * @param targets - Destinations to attempt.
+ * @param timeoutMs - Per-connection timeout.
+ * @returns Program source.
+ */
+export declare function buildProbeScript(targets: Array<{
+    host: string;
+    port: number;
+}>, timeoutMs: number): string;
+/**
+ * The host-netns listener program for leg 2.
+ *
+ * @param port - Port to bind.
+ * @param timeoutMs - How long to wait for a connection.
+ * @returns Program source.
+ */
+export declare function buildListenerScript(port: number, timeoutMs: number): string;
+/**
+ * Run BOTH legs and combine them into one verdict.
+ *
+ * A `filtered` verdict requires both legs to be denied. Either leg observing a
+ * successful connection is conclusive `open`; anything that could not be observed
+ * is `inconclusive`.
+ *
+ * @param ctx - Probe context.
+ * @returns The combined verdict.
+ */
+export declare function verifyDockerEgress(ctx: EgressProbeContext): Promise<EgressVerdict>;
+//# sourceMappingURL=egress.d.ts.map

package/dist/egress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../src/egress.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,aAAa,CAAA;IACtB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAA;IACnB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACjE;AAoFD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9C,SAAS,EAAE,MAAM,GAChB,MAAM,CAUR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAU3E;AA2OD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CA6ExF"}