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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-08-04T01:47:54.321Z
6
+ Generated: 2026-08-05T12:53:11.363Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-code-sandbox-docker
@@ -82,6 +82,29 @@ interface DockerConfig {
82
82
  labelPrefix?: string
83
83
  /** Preview URL template. Use {port} placeholder. */
84
84
  previewUrlTemplate?: string
85
+ /**
86
+ * Docker repository holding sandbox TEMPLATES — one tag per template id.
87
+ * Defaults to `molecule-sandbox-template` (or `SANDBOX_TEMPLATE_REPOSITORY`).
88
+ *
89
+ * Deliberately NOT the base image's repository. Sharing one repository between
90
+ * the base image and every template makes `docker images <repo>` and any
91
+ * cleanup written against it operate on both, and the only thing standing
92
+ * between a template sweep and the base image is a tag-prefix convention.
93
+ */
94
+ templateRepository?: string
95
+ /**
96
+ * Registry host for sharing templates across hosts, e.g. `registry.example.com`
97
+ * (or `SANDBOX_TEMPLATE_REGISTRY`). When unset, `publishTemplate`/`fetchTemplate`
98
+ * throw with an actionable message: the daemon CAN talk to a registry, so the
99
+ * capability is present and only the address is missing.
100
+ */
101
+ templateRegistry?: string
102
+ /**
103
+ * Base64-encoded Docker `X-Registry-Auth` value for {@link DockerConfig.templateRegistry}
104
+ * (or `SANDBOX_TEMPLATE_REGISTRY_AUTH`). Defaults to an empty credential set,
105
+ * which is what an anonymous or already-logged-in daemon needs.
106
+ */
107
+ templateRegistryAuth?: string
85
108
  }
86
109
  ```
87
110
 
@@ -97,6 +120,12 @@ interface ProcessEnv {
97
120
  DOCKER_HOST?: string
98
121
  /** Docker network sandbox containers attach to (default `molecule-sandbox`, ICC-off). Overridden by `config.network`. [C1-1] */
99
122
  SANDBOX_DOCKER_NETWORK?: string
123
+ /** Docker repository holding sandbox templates (default `molecule-sandbox-template`). Overridden by `config.templateRepository`. */
124
+ SANDBOX_TEMPLATE_REPOSITORY?: string
125
+ /** Registry host for sharing templates across hosts. Overridden by `config.templateRegistry`. */
126
+ SANDBOX_TEMPLATE_REGISTRY?: string
127
+ /** Base64 `X-Registry-Auth` value for `SANDBOX_TEMPLATE_REGISTRY`. Overridden by `config.templateRegistryAuth`. */
128
+ SANDBOX_TEMPLATE_REGISTRY_AUTH?: string
100
129
  }
101
130
  ```
102
131
 
@@ -114,6 +143,24 @@ function createProvider(config?: DockerConfig): SandboxProvider
114
143
 
115
144
  **Returns:** A `SandboxProvider` that manages Docker containers as sandboxes.
116
145
 
146
+ #### `resolvePublishPorts(ports)`
147
+
148
+ Validate the ports a caller asked to publish, falling back to this provider's
149
+ historical API + Vite pair when it named none.
150
+
151
+ Rejects rather than filters: a caller that asked for a port it cannot have
152
+ needs to hear so, because the alternative is a dev server running inside a
153
+ sandbox that nothing on the outside can ever reach — which looks like a broken
154
+ application, not a bad argument.
155
+
156
+ ```typescript
157
+ function resolvePublishPorts(ports?: number[]): number[]
158
+ ```
159
+
160
+ - `ports` — Ports inside the sandbox the caller wants reachable.
161
+
162
+ **Returns:** The ports to expose and bind.
163
+
117
164
  #### `withTransientRetry(op, opts)`
118
165
 
119
166
  Retry a Docker API operation that failed with a TRANSIENT fault — a request
@@ -222,7 +269,50 @@ prerequisite.
222
269
  container/volume size (it needs specific storage drivers — e.g. overlay2 on xfs
223
270
  with `pquota` — and errors on the common overlay2/ext4 host), so this provider
224
271
  enforces none. The core `resources.diskMB` is accepted but not applied here; cap
225
- disk at the host / volume level instead.
272
+ disk at the host / volume level instead. `setResources({ diskMB })` THROWS
273
+ rather than accepting a ceiling it cannot enforce.
274
+
275
+ **Templates are not `commit` alone, and that is not an optimization.**
276
+ `commitTemplate` copies the caller-named `capturePaths` into a throwaway,
277
+ volume-less container and commits THAT. A sandbox keeps the project on a
278
+ volume, and a volume is not part of a container's writable layer — so
279
+ committing a sandbox directly yields an image that builds, tags, and boots
280
+ with an empty workspace, with no error anywhere. The throwaway container
281
+ handles tenant-authored bytes and is committed into something other tenants
282
+ boot, so it runs with `--network none`, `CapDrop: ALL` plus the three
283
+ capabilities extraction needs, a memory cap and a process cap, and setuid/setgid
284
+ bits are stripped from the extracted tree afterwards.
285
+
286
+ Templates live in their OWN repository (`templateRepository`, default
287
+ `molecule-sandbox-template`) rather than sharing the base image's, so nothing
288
+ written to sweep templates can reach the base image. `publishTemplate` /
289
+ `fetchTemplate` use a Docker registry and require `templateRegistry`; without
290
+ it they THROW rather than returning "not found", because "there is no shared
291
+ store" and "the shared store does not have it" are different answers.
292
+
293
+ **`hibernate()`/`resume()` report which mechanism ran.** A CRIU checkpoint
294
+ preserves the process tree; a stop does not, and whether CRIU is available is a
295
+ property of the host (the daemon's experimental flag plus the `criu` package),
296
+ discovered at runtime. A sandbox that runs its dev servers as detached exec
297
+ processes comes back from a stop-style wake alive and serving nothing, so
298
+ callers must branch on `processesPreserved` — never on `status`, which says
299
+ `running` either way. The first response that shows CRIU is unavailable
300
+ disables it for the rest of the process.
301
+
302
+ **`find()` costs one request per match.** Docker's container LIST omits
303
+ `State.StartedAt`, which is the only field distinguishing an interrupted
304
+ creation (`startedAt: null` — holds storage forever, will never run) from an
305
+ ordinary stopped sandbox, so each match is then inspected. Narrow with
306
+ `labels`; an unfiltered query on a busy host inspects every container.
307
+
308
+ **`capacity()` measures THIS host, so it reports nothing for a TCP daemon.**
309
+ Over a `tcp://` endpoint the daemon writes to a different machine's storage,
310
+ and returning this machine's numbers would be a confident wrong answer — so it
311
+ returns empty `headroom` and says why. On a local socket it reports free bytes
312
+ and free inodes on the daemon's `DockerRootDir` plus `MemAvailable`. Inodes are
313
+ omitted (not reported as zero) on filesystems with dynamic inode allocation.
314
+ `admits` is always `null`: Docker has no quota of its own to consult, so the
315
+ floors and the refusal stay with the caller.
226
316
 
227
317
  ## Translations
228
318
 
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Bulk file transfer in and out of a Docker sandbox, as POSIX tar streams.
3
+ *
4
+ * The Engine API has a first-class endpoint pair for this
5
+ * (`GET`/`PUT /containers/{id}/archive`), so the bond does not need to
6
+ * orchestrate `tar` through an exec. That matters beyond tidiness: an exec-based
7
+ * pipe has to survive two hijacked sockets and gives no status code you can
8
+ * trust, which is how a workspace capture ends up "succeeding" with half a tree.
9
+ *
10
+ * Nothing is buffered. A project tree is gigabytes across hundreds of thousands
11
+ * of files; reading one into this process to hand it to the next call would trade
12
+ * a slow transfer for a dead API.
13
+ *
14
+ * **Extraction does not restore ownership or setuid bits.** `copyUIDGID` is left
15
+ * off, and callers capturing a tenant-authored tree into something another tenant
16
+ * boots must additionally strip setuid/setgid — `commitTemplate` does. An archive
17
+ * is data, and honoring the mode bits in data is how it becomes an escalation.
18
+ *
19
+ * @module
20
+ */
21
+ import type { DockerDownload, DockerUpload } from './request.js';
22
+ /** What the archive capability needs from the provider. */
23
+ export interface ArchiveContext {
24
+ download: DockerDownload;
25
+ upload: DockerUpload;
26
+ }
27
+ /**
28
+ * Stream a directory tree out of a sandbox as a POSIX tar archive.
29
+ *
30
+ * The archive is rooted at the LAST segment of `path` — an export of
31
+ * `/workspace` yields entries under `workspace/` — which is what makes it
32
+ * extractable into the parent directory on the way back in.
33
+ *
34
+ * @param ctx - Archive context.
35
+ * @param containerId - The sandbox to read from.
36
+ * @param path - Absolute path inside the sandbox.
37
+ * @returns A tar byte stream.
38
+ */
39
+ export declare function exportContainerFiles(ctx: ArchiveContext, containerId: string, path: string): Promise<AsyncIterable<Uint8Array>>;
40
+ /**
41
+ * Stream a POSIX tar archive into a sandbox, extracting it at `path`.
42
+ *
43
+ * @param ctx - Archive context.
44
+ * @param containerId - The sandbox to write to.
45
+ * @param path - Absolute destination directory inside the sandbox.
46
+ * @param archive - The tar byte stream to extract.
47
+ */
48
+ export declare function importContainerFiles(ctx: ArchiveContext, containerId: string, path: string, archive: AsyncIterable<Uint8Array>): Promise<void>;
49
+ //# sourceMappingURL=archive.d.ts.map
@@ -0,0 +1 @@
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"}
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Bulk file transfer in and out of a Docker sandbox, as POSIX tar streams.
3
+ *
4
+ * The Engine API has a first-class endpoint pair for this
5
+ * (`GET`/`PUT /containers/{id}/archive`), so the bond does not need to
6
+ * orchestrate `tar` through an exec. That matters beyond tidiness: an exec-based
7
+ * pipe has to survive two hijacked sockets and gives no status code you can
8
+ * trust, which is how a workspace capture ends up "succeeding" with half a tree.
9
+ *
10
+ * Nothing is buffered. A project tree is gigabytes across hundreds of thousands
11
+ * of files; reading one into this process to hand it to the next call would trade
12
+ * a slow transfer for a dead API.
13
+ *
14
+ * **Extraction does not restore ownership or setuid bits.** `copyUIDGID` is left
15
+ * off, and callers capturing a tenant-authored tree into something another tenant
16
+ * boots must additionally strip setuid/setgid — `commitTemplate` does. An archive
17
+ * is data, and honoring the mode bits in data is how it becomes an escalation.
18
+ *
19
+ * @module
20
+ */
21
+ /** Generous by design: this moves whole project trees, not files. */
22
+ const TRANSFER_TIMEOUT_MS = 600_000;
23
+ /**
24
+ * Reject a path that is not a plain absolute path.
25
+ *
26
+ * @param path - Candidate path.
27
+ * @throws {Error} When the path is relative or contains a traversal segment.
28
+ */
29
+ function assertAbsolutePath(path) {
30
+ if (!path.startsWith('/') || path.includes('..') || path.includes('\0')) {
31
+ throw new Error(`Invalid sandbox path ${JSON.stringify(path.slice(0, 64))}: must be absolute and free of ".." segments`);
32
+ }
33
+ }
34
+ /**
35
+ * Stream a directory tree out of a sandbox as a POSIX tar archive.
36
+ *
37
+ * The archive is rooted at the LAST segment of `path` — an export of
38
+ * `/workspace` yields entries under `workspace/` — which is what makes it
39
+ * extractable into the parent directory on the way back in.
40
+ *
41
+ * @param ctx - Archive context.
42
+ * @param containerId - The sandbox to read from.
43
+ * @param path - Absolute path inside the sandbox.
44
+ * @returns A tar byte stream.
45
+ */
46
+ export async function exportContainerFiles(ctx, containerId, path) {
47
+ assertAbsolutePath(path);
48
+ return ctx.download(`/containers/${containerId}/archive?path=${encodeURIComponent(path)}`, TRANSFER_TIMEOUT_MS);
49
+ }
50
+ /**
51
+ * Stream a POSIX tar archive into a sandbox, extracting it at `path`.
52
+ *
53
+ * @param ctx - Archive context.
54
+ * @param containerId - The sandbox to write to.
55
+ * @param path - Absolute destination directory inside the sandbox.
56
+ * @param archive - The tar byte stream to extract.
57
+ */
58
+ export async function importContainerFiles(ctx, containerId, path, archive) {
59
+ assertAbsolutePath(path);
60
+ await ctx.upload(`/containers/${containerId}/archive?path=${encodeURIComponent(path)}`, archive, TRANSFER_TIMEOUT_MS);
61
+ }
@@ -0,0 +1,71 @@
1
+ /**
2
+ * What this Docker host can still fit.
3
+ *
4
+ * A sandbox is admitted long before it is expensive: creating one populates a
5
+ * fresh volume with a dependency tree, and by the time that fails the host is
6
+ * already out of something and every OTHER sandbox on it is failing too. So the
7
+ * caller wants to refuse the boot while it can still say so cleanly — and to do
8
+ * that it needs a measurement only the provider can take.
9
+ *
10
+ * Three axes, because they run out separately and independently:
11
+ *
12
+ * - **Blocks.** The obvious one.
13
+ * - **Inodes.** A populated `node_modules` is hundreds of thousands of tiny
14
+ * files. On a filesystem with a fixed inode table this exhausts first, and
15
+ * every file creation on the host then fails with `ENOSPC` while `df -h`
16
+ * reports gigabytes free — a failure that looks like nothing else.
17
+ * - **Memory.** Each running sandbox holds a live container resident, and unlike
18
+ * disk this is NOT reclaimed by idle hibernation on any useful timescale. A
19
+ * burst of simultaneously-active users oversubscribes the host until the OOM
20
+ * killer starts choosing victims among sandboxes that were working fine.
21
+ *
22
+ * `MemAvailable` from `/proc/meminfo`, not `os.freemem()`. The kernel's estimate
23
+ * counts reclaimable page cache; `MemFree` does not, and on any warm host it
24
+ * understates free memory badly enough to reject boots the host could serve.
25
+ *
26
+ * **This measures the host THIS PROCESS runs on**, which is only the right host
27
+ * when the daemon is local. Over a TCP endpoint the numbers would describe the
28
+ * wrong machine, so the answer is `inconclusive`-shaped instead: no headroom
29
+ * fields, and a `detail` that says why. Reporting a comfortable local number for
30
+ * a remote daemon is the exact conflation this codebase refuses everywhere else.
31
+ *
32
+ * @module
33
+ */
34
+ import type { SandboxCapacity } from '@molecule/api-code-sandbox';
35
+ import type { DockerRequest } from './request.js';
36
+ /** The subset of `fs.StatsFs` this module uses. */
37
+ export interface FilesystemStats {
38
+ /** Block size in bytes. */
39
+ bsize: number;
40
+ /** Blocks available to an unprivileged process. */
41
+ bavail: number;
42
+ /** Free file nodes, or `-1`/`0` on filesystems without a fixed inode table. */
43
+ ffree: number;
44
+ }
45
+ /** What the capacity capability needs from the provider. */
46
+ export interface CapacityContext {
47
+ request: DockerRequest;
48
+ /**
49
+ * Whether the daemon is reached over a local unix socket. Only then does this
50
+ * process's filesystem describe the storage the daemon writes to.
51
+ */
52
+ daemonIsLocal: boolean;
53
+ /** Filesystem statistics for a path. Injected so this is testable without a disk. */
54
+ statfs: (path: string) => Promise<FilesystemStats>;
55
+ /** Available memory in bytes, or `null` when it cannot be read. */
56
+ availableMemoryBytes: () => Promise<number | null>;
57
+ warn?: (message: string, meta?: Record<string, unknown>) => void;
58
+ }
59
+ /**
60
+ * Measure what the host backing this daemon can still fit.
61
+ *
62
+ * `admits` is always `null`: Docker has no admission opinion of its own — it has
63
+ * no quota, no plan, and no notion of "too many". The caller compares the
64
+ * headroom against its own floors. A provider that DID have such an opinion
65
+ * (an account quota, a rate limit) would answer here instead.
66
+ *
67
+ * @param ctx - Capacity context.
68
+ * @returns Measured headroom and an explanation of anything unmeasurable.
69
+ */
70
+ export declare function measureDockerCapacity(ctx: CapacityContext): Promise<SandboxCapacity>;
71
+ //# sourceMappingURL=capacity.d.ts.map
@@ -0,0 +1 @@
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"}
@@ -0,0 +1,98 @@
1
+ /**
2
+ * What this Docker host can still fit.
3
+ *
4
+ * A sandbox is admitted long before it is expensive: creating one populates a
5
+ * fresh volume with a dependency tree, and by the time that fails the host is
6
+ * already out of something and every OTHER sandbox on it is failing too. So the
7
+ * caller wants to refuse the boot while it can still say so cleanly — and to do
8
+ * that it needs a measurement only the provider can take.
9
+ *
10
+ * Three axes, because they run out separately and independently:
11
+ *
12
+ * - **Blocks.** The obvious one.
13
+ * - **Inodes.** A populated `node_modules` is hundreds of thousands of tiny
14
+ * files. On a filesystem with a fixed inode table this exhausts first, and
15
+ * every file creation on the host then fails with `ENOSPC` while `df -h`
16
+ * reports gigabytes free — a failure that looks like nothing else.
17
+ * - **Memory.** Each running sandbox holds a live container resident, and unlike
18
+ * disk this is NOT reclaimed by idle hibernation on any useful timescale. A
19
+ * burst of simultaneously-active users oversubscribes the host until the OOM
20
+ * killer starts choosing victims among sandboxes that were working fine.
21
+ *
22
+ * `MemAvailable` from `/proc/meminfo`, not `os.freemem()`. The kernel's estimate
23
+ * counts reclaimable page cache; `MemFree` does not, and on any warm host it
24
+ * understates free memory badly enough to reject boots the host could serve.
25
+ *
26
+ * **This measures the host THIS PROCESS runs on**, which is only the right host
27
+ * when the daemon is local. Over a TCP endpoint the numbers would describe the
28
+ * wrong machine, so the answer is `inconclusive`-shaped instead: no headroom
29
+ * fields, and a `detail` that says why. Reporting a comfortable local number for
30
+ * a remote daemon is the exact conflation this codebase refuses everywhere else.
31
+ *
32
+ * @module
33
+ */
34
+ /**
35
+ * Measure what the host backing this daemon can still fit.
36
+ *
37
+ * `admits` is always `null`: Docker has no admission opinion of its own — it has
38
+ * no quota, no plan, and no notion of "too many". The caller compares the
39
+ * headroom against its own floors. A provider that DID have such an opinion
40
+ * (an account quota, a rate limit) would answer here instead.
41
+ *
42
+ * @param ctx - Capacity context.
43
+ * @returns Measured headroom and an explanation of anything unmeasurable.
44
+ */
45
+ export async function measureDockerCapacity(ctx) {
46
+ if (!ctx.daemonIsLocal) {
47
+ return {
48
+ admits: null,
49
+ detail: 'The Docker daemon is reached over a TCP endpoint, so this process cannot measure the ' +
50
+ 'storage or memory the daemon actually writes to. No headroom is reported rather than ' +
51
+ "reporting this machine's numbers for a different machine.",
52
+ headroom: {},
53
+ };
54
+ }
55
+ const notes = [];
56
+ const headroom = {};
57
+ let rootDir = '/var/lib/docker';
58
+ try {
59
+ const info = (await ctx.request('/info'));
60
+ if (info?.DockerRootDir)
61
+ rootDir = info.DockerRootDir;
62
+ }
63
+ catch (error) {
64
+ // Not fatal: the default root is right on the overwhelming majority of
65
+ // hosts, and a wrong path surfaces as a statfs failure below rather than as
66
+ // a confident wrong number.
67
+ ctx.warn?.('Could not read DockerRootDir from the daemon — assuming the default', { error });
68
+ notes.push(`could not read the daemon's storage root, assumed ${rootDir}`);
69
+ }
70
+ try {
71
+ const stats = await ctx.statfs(rootDir);
72
+ headroom.diskBytes = stats.bavail * stats.bsize;
73
+ // A filesystem with dynamic inodes (btrfs, xfs) reports 0 or -1 free nodes.
74
+ // That is "not applicable", not "exhausted", so it is omitted rather than
75
+ // reported as zero — a caller comparing against a floor would refuse every
76
+ // boot on such a host.
77
+ if (stats.ffree > 0)
78
+ headroom.inodes = stats.ffree;
79
+ }
80
+ catch (error) {
81
+ ctx.warn?.('Could not measure free space on the daemon storage root', { rootDir, error });
82
+ notes.push(`free space on ${rootDir} is unmeasurable`);
83
+ }
84
+ const memoryBytes = await ctx.availableMemoryBytes();
85
+ if (memoryBytes === null) {
86
+ notes.push('available memory is unreadable on this platform');
87
+ }
88
+ else {
89
+ headroom.memoryBytes = memoryBytes;
90
+ }
91
+ return {
92
+ admits: null,
93
+ detail: notes.length > 0
94
+ ? `Measured the host backing the local Docker daemon (${rootDir}); ${notes.join('; ')}.`
95
+ : `Measured the host backing the local Docker daemon (${rootDir}).`,
96
+ headroom,
97
+ };
98
+ }
@@ -0,0 +1,49 @@
1
+ import type { EgressVerdict } from '@molecule/api-code-sandbox';
2
+ import type { DockerRequest } from './request.js';
3
+ /** Inputs the probe needs from the provider. */
4
+ export interface EgressProbeContext {
5
+ request: DockerRequest;
6
+ /** The sandbox network name — the probe must be subject to the same rules. */
7
+ network: string;
8
+ /** Image to run the probe in; needs a `node` binary. */
9
+ baseImage: string;
10
+ /** Label namespace, used for the orphan sweep. */
11
+ labelPrefix: string;
12
+ /** Optional logger for cleanup failures. */
13
+ warn?: (message: string, meta?: Record<string, unknown>) => void;
14
+ }
15
+ /**
16
+ * The client program: raw `net.connect` to each target.
17
+ *
18
+ * Raw sockets, never `fetch` — proxy env is blanked AND a raw connect ignores it
19
+ * regardless, so this exercises the DIRECT path the proxy does not cover and only
20
+ * the firewall stops.
21
+ *
22
+ * @param targets - Destinations to attempt.
23
+ * @param timeoutMs - Per-connection timeout.
24
+ * @returns Program source.
25
+ */
26
+ export declare function buildProbeScript(targets: Array<{
27
+ host: string;
28
+ port: number;
29
+ }>, timeoutMs: number): string;
30
+ /**
31
+ * The host-netns listener program for leg 2.
32
+ *
33
+ * @param port - Port to bind.
34
+ * @param timeoutMs - How long to wait for a connection.
35
+ * @returns Program source.
36
+ */
37
+ export declare function buildListenerScript(port: number, timeoutMs: number): string;
38
+ /**
39
+ * Run BOTH legs and combine them into one verdict.
40
+ *
41
+ * A `filtered` verdict requires both legs to be denied. Either leg observing a
42
+ * successful connection is conclusive `open`; anything that could not be observed
43
+ * is `inconclusive`.
44
+ *
45
+ * @param ctx - Probe context.
46
+ * @returns The combined verdict.
47
+ */
48
+ export declare function verifyDockerEgress(ctx: EgressProbeContext): Promise<EgressVerdict>;
49
+ //# sourceMappingURL=egress.d.ts.map
@@ -0,0 +1 @@
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"}