diff --git a/registry/components/code/DESIGN.md b/registry/components/code/DESIGN.md index af884fb..15a7297 100644 --- a/registry/components/code/DESIGN.md +++ b/registry/components/code/DESIGN.md @@ -1,6 +1,6 @@ # `code` 零件 —— 沙箱設計小結(Arcrun#10) -> 狀態:設計 + PoC(Node/vitest 綠燈),**未部署 leo21c**。live 前需總管與 leo 過寫入/部署閘。 +> 狀態:**Workers 就緒(裁定 A,可部署)**,Node/vitest 12/12 綠燈,**未部署 leo21c**。live 前需總管與 leo 過寫入/部署閘。封裝=A(quickjs-emscripten singlefile variant);B(自建 QuickJS+wasi-sdk)列後續技術債。 ## 0. arcrun 零件 runtime 真相(先摸清再設計) @@ -28,10 +28,19 @@ Cloudflare Worker isolate(V8) - **input 穿越邊界**:以 JSON 字串 marshal,沙箱內 `JSON.parse` —— host 與 guest **不共享物件圖**,杜絕 prototype/引用逃逸。 - **user code 形狀**:當「函式體」跑(可含 `const`/`function` 宣告、以 `return` 回值),綁定唯一入參 `input`。回值 `JSON.stringify` 後交回 host。 -## 2. 生產路徑(PoC → live 的差異) +## 2. 生產路徑(裁定 A,已就緒) -- **PoC**(本目錄 `sandbox.mjs` + `test/`):用 `quickjs-emscripten`(預編 QuickJS wasm)在 **Node/vitest** 跑,證明沙箱**語義**。`sha256` 以 Node `node:crypto` 實作。**12 測試全綠**,含 card→envelope 全等。 -- **live(Worker)**:`quickjs-emscripten` 有 Cloudflare Workers 相容 variant,可直接在零件 Worker 內用。**唯一要改**:`sha256` 不用 host function(Worker 的 Web Crypto `crypto.subtle.digest` 是 async,跟 QuickJS 同步 host-call 不合),改成**把純 JS SHA-256 當 prelude 字串注入沙箱**(無 host call、Node/Worker 皆決定性)。這也讓「curated builtin = 純演算法字串」成為往後加 builtin 的標準做法。 +`sandbox.mjs` 為 **runtime-agnostic 核心**,Node 測試與 CF Worker **共用同一份**: + +- **封裝**:`@jitl/quickjs-singlefile-mjs-release-sync` variant(wasm 內嵌 base64、同步載入) + —— CF Workers 相容 loading 路徑(不靠 fetch/fs 取 .wasm),bundler 友善、無需 `[[wasm_modules]]`。 +- **`sha256` curated builtin**:以**純 JS SHA-256 字串 prelude** 注入沙箱(不呼叫 host、不用 async + Web Crypto、不需 `nodejs_compat`),Node/Worker 皆決定性;與 Node crypto sha256 逐字等價 + (測試 ⑤ 對 card 全文比對 content_hash 相同)。「curated builtin = 純演算法字串」定為往後標準。 +- **Worker host**:`index.ts`(Hono,POST /→`runCode`),自足 Worker,不走 TinyGo 模板流程。 +- **測試**:`sandbox.mjs` + `test/` 在 **Node/vitest 12/12 全綠**(含 card→envelope 全等)。 +- **與 B 的差**:B(自建 QuickJS+wasi-sdk→preview1 wasm,跑現有 WASI host shim)最同構,但需 + wasi-sdk 工具鏈(本環境無 sysroot)+維護 C harness,列後續技術債。 ## 3. 資源限制(防跑飛)