@runko/sandbox-cloudflare 0.1.0

package/dist/worker.js

@@ -0,0 +1,278 @@
+import { c as execRequestSchema, f as mkdirRequestSchema, g as readdirRequestSchema, i as NDJSON_CONTENT_TYPE, m as readRequestSchema, r as ENDPOINTS, s as execExitEventSchema, u as globRequestSchema, v as rmRequestSchema, x as writeRequestSchema, y as statRequestSchema } from "./protocol-Dj8Yv54w.js";
+import { basename, dirname, matchesGlob, normalizePath } from "@runko/virtual-fs";
+import "zod";
+//#region src/worker.ts
+/**
+* `./worker`：Cloudflare Sandbox 网关（部署在宿主自己的 wrangler 项目里）。
+* 把 `src/protocol.ts` 的八个端点翻译成对注入的 `CfSandboxLike` 的调用——本文件
+* **零 `@cloudflare/sandbox` import**（该包加载依赖 `cloudflare:workers` 内置模块，
+* Node 下不可加载，见 docs/tech/sandbox.md §8.2/§4"包本体零
+* cloudflare import"）：`CfSandboxLike` 是以该包 0.12.3 版本 `ISandbox` d.ts 为
+* 蓝本手写的结构化最小子集，真实装配（`getSandbox(env.Sandbox, id)` 返回值天然
+* 结构兼容本接口）留给宿主项目经 `createSandboxGateway({ getSandbox })` 注入。
+*
+* ---- 路径锚定：虚拟根 "/" ↔ 沙盒默认 cwd（工单裁量，见协议表 §8.3 附近注释）----
+*
+* `@cloudflare/sandbox` 的文件/目录方法把"/"开头的路径当作容器真实绝对路径、
+* 把不带前导斜杠的路径当作相对于沙盒自身默认工作目录（其官方文档称之为
+* "/workspace"）解析——这与 E2B/Vercel 适配器"client 端 `opts.root` 选项做
+* 虚拟根↔真实目录换算"的形状不同：Cloudflare 网关没有 root 配置（`cloudflareWorkspace`
+* 的选项里也确实没有 root 字段），换算发生在**网关**这一侧、且是隐式的——
+* `toSandboxPath()` 把客户端送来的虚拟绝对路径（`normalizePath()` 产出，形如
+* "/" 或 "/a/b.txt"）去掉前导斜杠变成沙盒相对路径（"." 或 "a/b.txt"），从而让
+* 沙盒自己的默认工作目录天然充当虚拟根——不需要任何一侧显式配置真实目录。
+*/
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function jsonResponse(body, status = 200) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+function errorResponse(status, code, message) {
+	return jsonResponse({
+		code,
+		message
+	}, status);
+}
+/** 虚拟绝对路径 → 沙盒路径：见文件头"路径锚定"注释。 */
+function toSandboxPath(virtualPath) {
+	return virtualPath === "/" ? "." : virtualPath.slice(1);
+}
+function normalizeOrBadRequest(rawPath) {
+	try {
+		return {
+			ok: true,
+			path: normalizePath(rawPath)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			response: errorResponse(400, "bad_request", `invalid path "${rawPath}": ${describeError(error)}`)
+		};
+	}
+}
+async function withValidatedBody(request, schema, handler) {
+	let raw;
+	try {
+		raw = await request.json();
+	} catch {
+		return errorResponse(400, "bad_request", "request body is not valid JSON");
+	}
+	const parsed = schema.safeParse(raw);
+	if (!parsed.success) return errorResponse(400, "bad_request", `request body failed validation: ${parsed.error.message}`);
+	return handler(parsed.data);
+}
+/** `read/mkdir/readdir/stat` 四个 `{ path }` 形状的端点共用：先校验+规范化 path 再交给业务 handler。 */
+async function withNormalizedPath(body, handler) {
+	const normalized = normalizeOrBadRequest(body.path);
+	if (!normalized.ok) return normalized.response;
+	return handler(normalized.path, body);
+}
+/** stat("/") 没有对应的"父目录条目"可查——合成一个恒为目录的条目代表虚拟根本身。 */
+const ROOT_ENTRY = {
+	name: "",
+	relativePath: "",
+	type: "directory",
+	size: 0,
+	modifiedAt: (/* @__PURE__ */ new Date(0)).toISOString()
+};
+/** 工单要求的 "stat 经 listFiles(dirname) 找条目" 策略——stat/readdir/rm 三个端点共用。 */
+async function findEntry(sandbox, virtualPath) {
+	if (virtualPath === "/") return {
+		found: true,
+		entry: ROOT_ENTRY
+	};
+	const parentVirtual = dirname(virtualPath);
+	let listing;
+	try {
+		listing = await sandbox.listFiles(toSandboxPath(parentVirtual), { recursive: false });
+	} catch {
+		return { found: false };
+	}
+	const name = basename(virtualPath);
+	const entry = listing.files.find((f) => f.name === name);
+	return entry === void 0 ? { found: false } : {
+		found: true,
+		entry
+	};
+}
+/** `CfFileInfo.type` → `FileStat.type`：沙盒工作区没有 reference 概念（§3.1），symlink/other 一律按 file 呈现。 */
+function mapEntryType(type) {
+	return type === "directory" ? "dir" : "file";
+}
+function toStatResponse(entry) {
+	const type = mapEntryType(entry.type);
+	const mtimeMs = Date.parse(entry.modifiedAt);
+	return {
+		type,
+		...type === "file" ? { size: entry.size } : {},
+		...Number.isFinite(mtimeMs) ? { mtime: mtimeMs } : {}
+	};
+}
+/** existence/kind 查不出更具体原因时的兜底翻译：找不到→404，是目录→400 not_dir，否则→500 sandbox_error。 */
+async function translateFsError(sandbox, virtualPath, error) {
+	const lookup = await findEntry(sandbox, virtualPath);
+	if (!lookup.found) return errorResponse(404, "not_found", `no such file or directory: "${virtualPath}"`);
+	if (lookup.entry.type === "directory") return errorResponse(400, "not_dir", `"${virtualPath}" is a directory: ${describeError(error)}`);
+	return errorResponse(500, "sandbox_error", `sandbox operation failed for "${virtualPath}": ${describeError(error)}`);
+}
+async function handleRead(sandbox, virtualPath) {
+	try {
+		return jsonResponse({ dataBase64: (await sandbox.readFile(toSandboxPath(virtualPath), { encoding: "base64" })).content });
+	} catch (error) {
+		return translateFsError(sandbox, virtualPath, error);
+	}
+}
+async function handleWrite(sandbox, virtualPath, dataBase64) {
+	try {
+		await sandbox.mkdir(toSandboxPath(dirname(virtualPath)), { recursive: true });
+		await sandbox.writeFile(toSandboxPath(virtualPath), dataBase64, { encoding: "base64" });
+		return jsonResponse({ ok: true });
+	} catch (error) {
+		return translateFsError(sandbox, virtualPath, error);
+	}
+}
+async function handleMkdir(sandbox, virtualPath) {
+	try {
+		await sandbox.mkdir(toSandboxPath(virtualPath), { recursive: true });
+		return jsonResponse({ ok: true });
+	} catch (error) {
+		return translateFsError(sandbox, virtualPath, error);
+	}
+}
+async function handleReaddir(sandbox, virtualPath) {
+	const lookup = await findEntry(sandbox, virtualPath);
+	if (!lookup.found) return errorResponse(404, "not_found", `no such file or directory: "${virtualPath}"`);
+	if (lookup.entry.type !== "directory") return errorResponse(400, "not_dir", `"${virtualPath}" is not a directory`);
+	try {
+		return jsonResponse({ entries: (await sandbox.listFiles(toSandboxPath(virtualPath), { recursive: false })).files.map((f) => ({
+			name: f.name,
+			type: mapEntryType(f.type)
+		})) });
+	} catch (error) {
+		return errorResponse(500, "sandbox_error", `failed to list "${virtualPath}": ${describeError(error)}`);
+	}
+}
+async function handleStat(sandbox, virtualPath) {
+	const lookup = await findEntry(sandbox, virtualPath);
+	if (!lookup.found) return errorResponse(404, "not_found", `no such file or directory: "${virtualPath}"`);
+	return jsonResponse(toStatResponse(lookup.entry));
+}
+async function handleGlob(sandbox, pattern) {
+	try {
+		return jsonResponse({ paths: (await sandbox.listFiles(".", { recursive: true })).files.filter((f) => f.type !== "directory").map((f) => `/${f.relativePath}`).filter((virtualPath) => matchesGlob(pattern, virtualPath)).sort() });
+	} catch (error) {
+		return errorResponse(500, "sandbox_error", `glob failed for pattern "${pattern}": ${describeError(error)}`);
+	}
+}
+async function handleRm(sandbox, virtualPath, recursive) {
+	if (virtualPath === "/") return errorResponse(400, "bad_request", "cannot remove the virtual root \"/\"");
+	const lookup = await findEntry(sandbox, virtualPath);
+	if (!lookup.found) return errorResponse(404, "not_found", `no such file or directory: "${virtualPath}"`);
+	const sandboxPath = toSandboxPath(virtualPath);
+	if (lookup.entry.type === "directory" && recursive !== true) {
+		let childCount = 0;
+		try {
+			childCount = (await sandbox.listFiles(sandboxPath, { recursive: false })).files.length;
+		} catch {
+			childCount = 0;
+		}
+		if (childCount > 0) return errorResponse(409, "dir_not_empty", `directory not empty (pass { recursive: true } to delete): "${virtualPath}"`);
+	}
+	try {
+		await sandbox.deleteFile(sandboxPath);
+		return jsonResponse({ ok: true });
+	} catch (error) {
+		return errorResponse(500, "sandbox_error", `failed to delete "${virtualPath}": ${describeError(error)}`);
+	}
+}
+const textEncoder = new TextEncoder();
+function ndjsonLine(event) {
+	return textEncoder.encode(`${JSON.stringify(event)}\n`);
+}
+/**
+* `/exec`：NDJSON 流式响应。响应对象立即返回（`readable` 端交给 `Response`），
+* 真正跑命令的工作在一个不 await 的后台 IIFE 里进行，通过 `TransformStream` 的
+* `writable` 端把 N 个 output 事件 + 1 个终块 exit 事件逐行写入——客户端读到
+* 流结束（`writer.close()`）即视为命令完成。
+*/
+async function handleExec(sandbox, body, requestSignal) {
+	let sandboxCwd;
+	if (body.cwd !== void 0) {
+		const normalized = normalizeOrBadRequest(body.cwd);
+		if (!normalized.ok) return normalized.response;
+		sandboxCwd = toSandboxPath(normalized.path);
+	}
+	const { readable, writable } = new TransformStream();
+	const writer = writable.getWriter();
+	const writeEvent = (event) => {
+		writer.write(ndjsonLine(event)).catch(() => {});
+	};
+	(async () => {
+		const start = Date.now();
+		try {
+			const result = await sandbox.exec(body.command, {
+				cwd: sandboxCwd,
+				timeout: body.timeoutMs,
+				signal: requestSignal,
+				stream: true,
+				onOutput: (stream, data) => writeEvent({
+					type: "output",
+					stream,
+					data
+				})
+			});
+			const exitEvent = execExitEventSchema.parse({
+				type: "exit",
+				exitCode: result.exitCode,
+				stdout: result.stdout,
+				stderr: result.stderr,
+				durationMs: result.duration
+			});
+			writeEvent(exitEvent);
+		} catch (error) {
+			writeEvent({
+				type: "exit",
+				exitCode: 1,
+				stdout: "",
+				stderr: `sandbox exec failed: ${describeError(error)}`,
+				durationMs: Date.now() - start
+			});
+		} finally {
+			await writer.close().catch(() => {});
+		}
+	})();
+	return new Response(readable, {
+		status: 200,
+		headers: { "content-type": NDJSON_CONTENT_TYPE }
+	});
+}
+function createSandboxGateway(opts) {
+	return { async fetch(request) {
+		if (request.headers.get("authorization") !== `Bearer ${opts.token}`) return errorResponse(401, "unauthorized", "missing or invalid bearer token");
+		const sandboxId = request.headers.get("x-runko-sandbox") ?? "default";
+		let sandbox;
+		try {
+			sandbox = await opts.getSandbox(sandboxId);
+		} catch (error) {
+			return errorResponse(500, "sandbox_error", `getSandbox("${sandboxId}") failed: ${describeError(error)}`);
+		}
+		const pathname = new URL(request.url).pathname;
+		switch (pathname) {
+			case ENDPOINTS.read: return withValidatedBody(request, readRequestSchema, (body) => withNormalizedPath(body, (path) => handleRead(sandbox, path)));
+			case ENDPOINTS.write: return withValidatedBody(request, writeRequestSchema, (body) => withNormalizedPath(body, (path, b) => handleWrite(sandbox, path, b.dataBase64)));
+			case ENDPOINTS.rm: return withValidatedBody(request, rmRequestSchema, (body) => withNormalizedPath(body, (path, b) => handleRm(sandbox, path, b.recursive)));
+			case ENDPOINTS.mkdir: return withValidatedBody(request, mkdirRequestSchema, (body) => withNormalizedPath(body, (path) => handleMkdir(sandbox, path)));
+			case ENDPOINTS.readdir: return withValidatedBody(request, readdirRequestSchema, (body) => withNormalizedPath(body, (path) => handleReaddir(sandbox, path)));
+			case ENDPOINTS.stat: return withValidatedBody(request, statRequestSchema, (body) => withNormalizedPath(body, (path) => handleStat(sandbox, path)));
+			case ENDPOINTS.glob: return withValidatedBody(request, globRequestSchema, (body) => handleGlob(sandbox, body.pattern));
+			case ENDPOINTS.exec: return withValidatedBody(request, execRequestSchema, (body) => handleExec(sandbox, body, request.signal));
+			default: return errorResponse(404, "not_found", `unknown endpoint: ${pathname}`);
+		}
+	} };
+}
+//#endregion
+export { createSandboxGateway };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@runko/sandbox-cloudflare",
+  "version": "0.1.0",
+  "description": "RunkoFS & RunkoExec 同源工作区：适配 Cloudflare Sandbox（网关形态——`.` 纯 fetch 客户端跑在任意 Node，`./worker` 网关部署在宿主 wrangler 项目）",
+  "type": "module",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./worker": {
+      "import": {
+        "types": "./dist/worker.d.ts",
+        "default": "./dist/worker.js"
+      },
+      "require": {
+        "types": "./dist/worker.d.cts",
+        "default": "./dist/worker.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@runko/core": "^0.1.0",
+    "@runko/virtual-fs": "^0.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/sandbox": "^0.12.3",
+    "@types/node": "^24.13.3",
+    "ai": "^7.0.20",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
+  }
+}