@capybara-hq/testing 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/fake-e2b.d.ts

@@ -19,6 +19,21 @@
  * 本机只有一个用户，权限隔离测不了，测试改为核对请求里的用户）。进程以新会话启动（与 setsid 等价），
  * 客户端断开**不会**结束进程（与 envd 一致），只有 SendSignal、杀进程脚本或删沙箱才会。
  *
+ * - **Template build** (the routes `Template.build(Template().fromImage(image), alias)` calls, e2b 2.58.0
+ *   `buildApi`; all need `X-API-KEY`): `POST /v3/templates` (body `{name, tags?, cpuCount?, memoryMB?}`,
+ *   `name` may carry `:tag`; 202 `{templateID, buildID, names, aliases, tags, public}`),
+ *   `GET /templates/{templateID}/files/{hash}` (upload link of a COPY step; `{present: true}`),
+ *   `POST /v2/templates/{templateID}/builds/{buildID}` (body `{fromImage, steps, force, startCmd?,
+ *   readyCmd?}`; 202, and {@link FakeE2BOptions.templateBuildMs} starts counting), `GET
+ *   /templates/{templateID}/builds/{buildID}/status?logsOffset=` (`{buildID, templateID, status:
+ *   waiting | building | ready, logEntries, logs}`), `GET /templates/aliases/{alias}` (200
+ *   `{templateID, public}`, else 404). A template (including the seeded `templates`) creates
+ *   sandboxes by alias or templateID; one still building answers 404; template names never
+ *   registered are accepted as before.
+ * - **Pause**: `POST /sandboxes/{id}/pause` with `{memory: false}` (the SDK's `mode: "filesystem"`)
+ *   ends all processes and keeps the files; otherwise (also an empty body) processes stay.
+ *   {@link FakeE2BServer.removeSandbox} simulates a lost paused sandbox.
+ *
  * `connect` 带 `memory: false`（SDK 的 `onResume: "reboot"`）时结束该沙箱的全部进程（冷启动）。
  * SendSignal 只杀指定进程（不是进程组）。
  *
@@ -32,6 +47,19 @@ export interface FakeE2BOptions {
     pageSize?: number;
     /** create / connect 返回的沙箱 `domain`（默认 null，即用客户端配置的域名）。 */
     domain?: string | null;
+    /** Existing template aliases (treated as built). */
+    templates?: string[];
+    /** Milliseconds from triggering a template build to `ready` (default 0). */
+    templateBuildMs?: number;
+}
+export interface FakeE2BTemplate {
+    templateID: string;
+    alias: string;
+    /** The image it was built from (undefined for a seeded template). */
+    image?: string | undefined;
+    buildID?: string | undefined;
+    /** When it becomes `ready` (ms timestamp); undefined until the build is triggered (waiting). */
+    readyAt?: number | undefined;
 }
 export interface FakeE2BSandbox {
     id: string;
@@ -41,6 +69,8 @@ export interface FakeE2BSandbox {
     /** 当前的超时（秒）：建沙箱时给的，connect 只会把它调大。 */
     timeout: number;
     autoPause: boolean;
+    /** Whether the last pause kept memory (`pause` body `memory` is not false). */
+    pausedWithMemory?: boolean;
     /** 建沙箱请求体里的出站设置（原样记录）。 */
     allowInternetAccess?: boolean;
     network?: unknown;
@@ -71,6 +101,8 @@ export interface FakeE2BServer {
     url: string;
     apiKey: string;
     sandboxes: Map<string, FakeE2BSandbox>;
+    /** Templates by alias. */
+    templates: Map<string, FakeE2BTemplate>;
     calls: FakeE2BCall[];
     /**
      * 下一个匹配的请求回 `status`：默认 E2B 的错误格式 JSON `{code: status, message}`；`raw` 时回纯文本
@@ -90,6 +122,8 @@ export interface FakeE2BServer {
     withholdAccessToken: boolean;
     /** 沙箱直接消失（杀掉它的进程、删掉根目录）。 */
     expire(id: string): Promise<void>;
+    /** Same as {@link FakeE2BServer.expire}: simulates a lost paused sandbox (connect then answers 404). */
+    removeSandbox(id: string): Promise<void>;
     /** 沙箱内路径在本机上的位置。 */
     hostPath(id: string, sandboxPath: string): string;
     /** 沙箱里还在跑的进程（由 Start 启动、尚未退出的）。 */

package/dist/fake-e2b.js

@@ -84,6 +84,12 @@ export async function startFakeE2B(opts = {}) {
     await chmod(join(shims, "setsid"), 0o755);
     const sandboxes = new Map();
     const procs = new Map();
+    const templates = new Map();
+    for (const alias of opts.templates ?? [])
+        templates.set(alias, { templateID: `t${randomBytes(6).toString("hex")}`, alias });
+    const buildMs = opts.templateBuildMs ?? 0;
+    const templateByRef = (ref) => templates.get(ref) ?? [...templates.values()].find((t) => t.templateID === ref);
+    const ready = (t) => t.readyAt !== undefined && Date.now() >= t.readyAt;
     const calls = [];
     const fails = [];
     const reboots = new Map();
@@ -122,12 +128,13 @@ export async function startFakeE2B(opts = {}) {
     };
     const newSandbox = async (body) => {
         const id = `i${randomBytes(9).toString("hex")}`;
+        const tpl = templateByRef(String(body.templateID));
         const root = join(base, id);
         for (const d of ROOT_DIRS)
             await mkdir(join(root, d), { recursive: true });
         const s = {
             id,
-            templateID: String(body.templateID),
+            templateID: tpl?.templateID ?? String(body.templateID),
             metadata: body.metadata ?? {},
             state: "running",
             timeout: typeof body.timeout === "number" ? body.timeout : 300,
@@ -160,6 +167,11 @@ export async function startFakeE2B(opts = {}) {
                 sendJson(res, 400, { code: 400, message: "templateID is required" });
                 return;
             }
+            const tpl = templateByRef(body.templateID);
+            if (tpl?.buildID !== undefined && !ready(tpl)) {
+                sendJson(res, 404, { code: 404, message: `template '${body.templateID}' is not ready` });
+                return;
+            }
             const s = await newSandbox(body);
             sendJson(res, 201, {
                 sandboxID: s.id,
@@ -235,9 +247,89 @@ export async function startFakeE2B(opts = {}) {
                 return;
             }
             s.state = "paused";
+            s.pausedWithMemory = body.memory !== false;
+            if (!s.pausedWithMemory) {
+                // filesystem-only snapshot: the processes are gone, the files stay
+                for (const p of procs.get(s.id) ?? [])
+                    killGroup(p);
+                procs.delete(s.id);
+            }
             sendJson(res, 204);
             return;
         }
+        if (method === "POST" && path === "/v3/templates") {
+            const name = typeof body.name === "string" ? body.name : "";
+            if (name === "") {
+                sendJson(res, 400, { code: 400, message: "name is required" });
+                return;
+            }
+            const alias = name.split(":")[0];
+            const tags = Array.isArray(body.tags) ? body.tags : [];
+            const t = templates.get(alias) ?? {
+                templateID: `t${randomBytes(6).toString("hex")}`,
+                alias,
+            };
+            t.buildID = randomBytes(8).toString("hex");
+            t.readyAt = undefined;
+            t.image = undefined;
+            templates.set(alias, t);
+            sendJson(res, 202, {
+                templateID: t.templateID,
+                buildID: t.buildID,
+                names: [name],
+                aliases: [alias],
+                tags,
+                public: false,
+            });
+            return;
+        }
+        m = /^\/templates\/([^/]+)\/files\/([^/]+)$/.exec(path);
+        if (m && method === "GET") {
+            sendJson(res, 200, { present: true });
+            return;
+        }
+        m = /^\/v2\/templates\/([^/]+)\/builds\/([^/]+)$/.exec(path);
+        if (m && method === "POST") {
+            const t = templateByRef(m[1]);
+            if (!t || t.buildID !== m[2]) {
+                sendJson(res, 404, { code: 404, message: "build not found" });
+                return;
+            }
+            if (typeof body.fromImage !== "string") {
+                sendJson(res, 400, { code: 400, message: "fromImage is required" });
+                return;
+            }
+            t.image = body.fromImage;
+            t.readyAt = Date.now() + buildMs;
+            sendJson(res, 202);
+            return;
+        }
+        m = /^\/templates\/([^/]+)\/builds\/([^/]+)\/status$/.exec(path);
+        if (m && method === "GET") {
+            const t = templateByRef(m[1]);
+            if (!t || t.buildID !== m[2]) {
+                sendJson(res, 404, { code: 404, message: "build not found" });
+                return;
+            }
+            sendJson(res, 200, {
+                buildID: t.buildID,
+                templateID: t.templateID,
+                status: t.readyAt === undefined ? "waiting" : ready(t) ? "ready" : "building",
+                logEntries: [],
+                logs: [],
+            });
+            return;
+        }
+        m = /^\/templates\/aliases\/([^/]+)$/.exec(path);
+        if (m && method === "GET") {
+            const t = templates.get(decodeURIComponent(m[1]));
+            if (!t) {
+                sendJson(res, 404, { code: 404, message: `template '${m[1]}' not found` });
+                return;
+            }
+            sendJson(res, 200, { templateID: t.templateID, public: false });
+            return;
+        }
         m = /^\/sandboxes\/([^/]+)$/.exec(path);
         if (m && method === "DELETE") {
             if (!sandboxes.has(m[1]))
@@ -454,6 +546,7 @@ export async function startFakeE2B(opts = {}) {
         url,
         apiKey,
         sandboxes,
+        templates,
         calls,
         failNext(match, status, message = `fake failure ${status}`, opts = {}) {
             fails.push({ match, status, message, raw: opts.raw === true });
@@ -469,6 +562,7 @@ export async function startFakeE2B(opts = {}) {
             hangs.push(match);
         },
         expire: destroy,
+        removeSandbox: destroy,
         hostPath(id, sandboxPath) {
             const s = sandboxes.get(id);
             if (!s)

package/dist/fake-git-server.js

@@ -129,8 +129,10 @@ function serveCgi(root, req, res) {
         res.writeHead(h.status, h.headers);
         res.write(head.subarray(h.bodyStart));
     });
+    // A child that could not be spawned emits 'error' and then 'close': only the first writes a head
+    // (a second writeHead throws ERR_HTTP_HEADERS_SENT, an uncaught exception).
     p.on("close", () => {
-        if (!headDone)
+        if (!headDone && !res.headersSent)
             res.writeHead(502);
         res.end();
     });

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * package and the SDK: the database helpers and types, and model-visible texts, queue names and
  * keys the kernel owns (assert on them instead of copying their values).
  */
-export { type ConversationEvent, createDb, gatewayReplicasKey, type KernelConfig, type KernelSchemaDb, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
+export { type ConversationEvent, createDb, gatewayReplicasKey, type KernelConfig, type KernelSchemaDb, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RESTARTED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
 export { createFreshDatabase, startTestPostgres, startTestRedis, startTestS3, TEST_S3_IMAGE, type TestContainer, type TestS3, } from "./containers.js";
 export { createDualReplicaHarness, type DualReplicaOptions, type ExtraReplicaHandle, type Harness, REPLICA_HEADER, type ReplicaHandle, type ReplicaResponse, replicaOf, } from "./dual-replica.js";
 export { assertExtensionSecretsReachable, extensionDeploymentSecretValues, } from "./extension-config.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  * package and the SDK: the database helpers and types, and model-visible texts, queue names and
  * keys the kernel owns (assert on them instead of copying their values).
  */
-export { createDb, gatewayReplicasKey, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
+export { createDb, gatewayReplicasKey, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RESTARTED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
 export { createFreshDatabase, startTestPostgres, startTestRedis, startTestS3, TEST_S3_IMAGE, } from "./containers.js";
 export { createDualReplicaHarness, REPLICA_HEADER, replicaOf, } from "./dual-replica.js";
 export { assertExtensionSecretsReachable, extensionDeploymentSecretValues, } from "./extension-config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/testing",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "description": "Test helpers for Capybara: test containers, dual-replica harness and fake third-party servers",
   "license": "Apache-2.0",
   "repository": {
@@ -47,17 +47,17 @@
     "tsx": "^4.23.15",
     "ws": "^8.22.0",
     "zod": "^4.6.7",
-    "@capybara-hq/kernel": "^0.1.0-rc.4"
+    "@capybara-hq/kernel": "^0.1.0-rc.5"
   },
   "devDependencies": {
     "@types/pg": "^8.23.1",
     "@types/ws": "^8.18.2",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.2"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.3"
   },
   "peerDependencies": {
     "vitest": "^5.0.5",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.2",
-    "@capybara-hq/plugin-tools": "^0.1.0-rc.4"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.3",
+    "@capybara-hq/plugin-tools": "^0.1.0-rc.5"
   },
   "peerDependenciesMeta": {
     "@capybara-hq/plugin-tools": {