feat: Initial JS sandbox primitives. (#1753)

Author: jsantell

deno.json

@@ -11,6 +11,7 @@
     "./packages/iframe-sandbox",
     "./packages/integration",
     "./packages/js-runtime",
+    "./packages/js-sandbox",
     "./packages/schema-generator",
     "./packages/llm",
     "./packages/memory",

deno.lock

@@ -0,0 +1,24 @@
+export default {
+  include: {
+    "../static/assets": "static",
+  },
+  esbuildConfig: {
+    supported: {
+      using: false,
+    },
+    external: [
+      "jsdom",
+      "source-map-support",
+      "canvas",
+      "inspector",
+    ],
+    tsconfigRaw: {
+      compilerOptions: {
+        // `useDefineForClassFields` is critical when using Lit
+        // with esbuild, even when not using decorators.
+        useDefineForClassFields: false,
+        experimentalDecorators: true,
+      },
+    },
+  },
+};

packages/js-sandbox/deno-web-test.config.ts

@@ -0,0 +1,20 @@
+{
+  "name": "@commontools/js-sandbox",
+  "tasks": {
+    "test": {
+      "dependencies": [
+        "deno-test",
+        "browser-test"
+      ]
+    },
+    "deno-test": "deno test --unstable-raw-imports --allow-env --allow-read test/*.test.ts",
+    "browser-test": "deno run --allow-env --allow-read --allow-write --allow-run --allow-net ../deno-web-test/cli.ts test/*.test.ts"
+  },
+  "imports": {
+    "quickjs-emscripten-core": "npm:quickjs-emscripten-core",
+    "@jitl/quickjs-singlefile-mjs-debug-sync": "npm:@jitl/quickjs-singlefile-mjs-debug-sync"
+  },
+  "exports": {
+    ".": "./mod.ts"
+  }
+}

packages/js-sandbox/deno.json

@@ -0,0 +1,3 @@
+export { RecipeSandbox } from "./recipe-sandbox.ts";
+export type { SandboxConfig, SandboxStats } from "./sandbox/mod.ts";
+export * from "./types.ts";

packages/js-sandbox/mod.ts

@@ -0,0 +1,83 @@
+import { QuickJSHandle } from "./sandbox/quick.ts";
+import { type JsScript } from "@commontools/js-runtime";
+import { GuestMessage, SandboxValue } from "./types.ts";
+import { Sandbox, SandboxConfig, SandboxStats } from "./sandbox/mod.ts";
+
+type SandboxState = "unloaded" | "loaded" | "disposed";
+
+// A VM to execute recipe code.
+//
+// Before usage, `await RecipeSandbox.initialize()`
+// must be called at least once.
+//
+// Each sandbox can load a single recipe compiled with
+// `js-runtime`, and then loaded via `sandbox.load(..)`.
+// Functions exported by the typescript modules can be
+// then be invoked.
+export class RecipeSandbox {
+  #state: SandboxState;
+  #sandbox: Sandbox;
+  // Bundle function return value containing
+  // "main" property, and "exportMap" property.
+  #exports?: QuickJSHandle;
+
+  constructor(config: SandboxConfig = {}) {
+    this.#sandbox = new Sandbox(config);
+    this.#state = "unloaded";
+  }
+
+  messages(): GuestMessage[] {
+    return this.#sandbox.messages();
+  }
+
+  // Invoke function exported by load script.
+  invoke(
+    exportFile: string,
+    exportName: string,
+    args: SandboxValue[],
+  ): unknown {
+    if (this.#state !== "loaded" || !this.#exports) {
+      throw new Error(`Cannot invoke a non-loaded sandbox.`);
+    }
+    const vm = this.#sandbox.vm();
+    using exportMap = vm.getProp(this.#exports, "exportMap");
+    using fileExports = vm.getProp(exportMap, exportFile);
+    using fn = vm.getProp(fileExports, exportName);
+
+    return this.#sandbox.invoke(fn, vm.undefined, args);
+  }
+
+  // Load and evaluate a compiled recipe script within the sandbox.
+  load(module: JsScript): unknown {
+    if (this.#state !== "unloaded") {
+      throw new Error(`Cannot load script in ${this.#state} sandbox.`);
+    }
+    const vm = this.#sandbox.vm();
+    using result = this.#sandbox.loadRaw(module);
+    this.#exports = this.#sandbox.invokeRaw(result, vm.undefined, [{}]);
+    using main = vm.getProp(this.#exports, "main");
+    this.#state = "loaded";
+    return this.#sandbox.fromVm(main);
+  }
+
+  stats(): SandboxStats {
+    return this.#sandbox.stats();
+  }
+
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+
+  dispose() {
+    if (this.#state === "disposed") {
+      return;
+    }
+    this.#state = "disposed";
+    if (this.#exports) this.#exports.dispose();
+    this.#sandbox.dispose();
+  }
+
+  static async initialize() {
+    await Sandbox.initialize();
+  }
+}

packages/js-sandbox/recipe-sandbox.ts

@@ -0,0 +1,110 @@
+import { GuestMessage, isGuestMessage, SandboxValue } from "../../types.ts";
+import { QuickJSContext, QuickJSHandle } from "../quick.ts";
+import Script_00_Primordials from "./environment/00_primordials.js" with {
+  type: "text",
+};
+import Script_01_Console from "./environment/01_console.js" with {
+  type: "text",
+};
+import { fromVm, toVm } from "./encoding.ts";
+import { Primordials } from "./primordials.ts";
+
+// Order of scripts to be injected. Primordials
+// must be registered first, as they're used as args
+// for later injected scripts.
+const injectScripts = [
+  Script_01_Console,
+];
+
+export class Bindings {
+  #vm: QuickJSContext;
+  #primordials: Primordials;
+  #messages: GuestMessage[] = [];
+
+  constructor(vm: QuickJSContext) {
+    this.#vm = vm;
+
+    // Create IPC
+    using ipc = vm.newObject();
+    using sendHandle = vm.newFunction("send", (data) => {
+      this.#onGuestMessage(this.fromVm(data));
+    });
+    vm.setProp(ipc, "send", sendHandle);
+    vm.setProp(vm.global, "__ipc", ipc);
+
+    // Register primordials
+    this.#primordials = new Primordials(
+      vm,
+      vm.unwrapResult(
+        vm.evalCode(Script_00_Primordials),
+      ),
+    );
+
+    // Register other scripts
+    for (const script of injectScripts) {
+      using handle = vm.unwrapResult(
+        vm.evalCode(script),
+      );
+      vm.unwrapResult(
+        vm.callFunction(handle, vm.null, [this.#primordials.handle()]),
+      )
+        .dispose();
+    }
+  }
+
+  primordials(): Primordials {
+    return this.#primordials;
+  }
+
+  vm(): QuickJSContext {
+    return this.#vm;
+  }
+
+  drainMessages(): GuestMessage[] {
+    const messages = [...this.#messages];
+    this.#messages.length = 0;
+    return messages;
+  }
+
+  // Cast a value into the VM, returning an owned handle.
+  toVm(value: SandboxValue): QuickJSHandle {
+    return toVm(this, value);
+  }
+
+  // Cast a value from the VM.
+  fromVm(value: QuickJSHandle): SandboxValue {
+    return fromVm(this, value);
+  }
+
+  #onGuestMessage = (message: unknown) => {
+    if (!isGuestMessage(message)) {
+      let formatted;
+      try {
+        formatted = JSON.stringify(message);
+      } catch (e) {
+        if (
+          message && typeof message === "object" && "toString" in message &&
+          typeof message.toString === "function"
+        ) {
+          formatted = message.toString() as string;
+        } else {
+          formatted = message;
+        }
+      }
+      this.#messages.push({
+        type: "error",
+        error: `Received invalid message: ${formatted}`,
+      });
+      return;
+    }
+    this.#messages.push(message);
+  };
+
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+
+  dispose() {
+    this.#primordials.dispose();
+  }
+}