@molecule/api-code-sandbox-docker 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-code-sandbox-docker` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-code-sandbox-docker is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Docker code-sandbox provider for molecule.dev.
+ *
+ * @remarks
+ * **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.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './types.js';
+import type { SandboxProvider } from '@molecule/api-code-sandbox';
+/**
+ * The provider implementation.
+ */
+export declare const provider: SandboxProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}

package/dist/index.js

@@ -0,0 +1,54 @@
+/**
+ * Docker code-sandbox provider for molecule.dev.
+ *
+ * @remarks
+ * **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.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './types.js';
+import { createProvider } from './provider.js';
+/** Lazily-initialized provider singleton. Defers creation until first use so that env vars / secrets are resolved. */
+let _provider = null;
+/**
+ * The provider implementation.
+ */
+export const provider = new Proxy({}, {
+    get(_, prop, receiver) {
+        if (!_provider)
+            _provider = createProvider();
+        return Reflect.get(_provider, prop, receiver);
+    },
+    // set trap: methods run with `this` bound to the proxy — without it, instance-state writes land on the dummy target and are lost (see api-push-notifications-web-push)
+    set(_, prop, value) {
+        if (!_provider)
+            _provider = createProvider();
+        return Reflect.set(_provider, prop, value);
+    },
+});

package/dist/provider.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Docker implementation of SandboxProvider.
+ *
+ * Uses the Docker Engine API via HTTP to manage containers.
+ * Each sandbox runs as an isolated Docker container with resource limits.
+ *
+ * @module
+ */
+import type { SandboxProvider } from '@molecule/api-code-sandbox';
+import type { DockerConfig } from './types.js';
+/**
+ * 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.
+ *
+ * @param op - the operation to attempt.
+ * @param opts - tuning + the optional adopt-on-retry guard.
+ * @param opts.label - short operation name for log lines.
+ * @param opts.attempts - max attempts (default 3).
+ * @param opts.onRetry - adopt-an-existing-resource guard, run before each retry.
+ * @param opts.delayMs - backoff for attempt N (default `400 * N` ms).
+ * @param opts.log - optional logger for retry warnings.
+ * @returns the operation's result, or an adopted result from `onRetry`.
+ */
+export declare function withTransientRetry<T>(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>;
+/**
+ * Creates a new `DockerSandboxProvider` instance with the given configuration.
+ * @param 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.
+ */
+export declare function createProvider(config?: DockerConfig): SandboxProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAOV,eAAe,EAEhB,MAAM,4BAA4B,CAAA;AAOnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA8I9C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAo3BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}