sandboxedjs 0.2.11 → 0.2.13

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="assets/logo.png" alt="SandboxedJS" width="140" />
+<img src="https://cdn.jsdelivr.net/npm/sandboxedjs@latest/assets/logo.png" alt="SandboxedJS" width="140" />
 
 # SandboxedJS
 
@@ -117,7 +117,9 @@ terminal.start();
 This is the case most people arrive for: a Vite frontend and a Python backend, in one container, in
 a tab — the frontend calling `http://localhost:8000`, the backend calling a real API.
 
-Two different problems hide in that sentence, and SandboxedJS solves them in two different ways.
+The frontend-to-backend hop and the backend-to-internet hop have different requirements.
+See the [full-stack deployment guide](docs/fullstack-deployment.md) for production asset staging,
+Cloudflare Pages, Vercel, Node/serverless lifetimes, and troubleshooting.
 
 ### 1. Frontend → backend: nothing to configure
 
@@ -149,10 +151,14 @@ await box.exec("npm install", { cwd: "/app/frontend", timeoutMs: 600_000 });
 
 box.spawn("fastapi run", { cwd: "/app/backend" });
 box.spawn("npm run dev", { cwd: "/app/frontend" });
-await box.waitForPort(3000, { timeoutMs: 60_000 });
-
-const preview = await createPreview(box); // null where service workers are unavailable
-iframe.src = preview!.urlFor(3000);
+if (!(await box.waitForPort(8000, { timeoutMs: 60_000 })) ||
+    !(await box.waitForPort(3000, { timeoutMs: 60_000 }))) {
+  throw new Error("Check backend and frontend startup logs");
+}
+
+const preview = await createPreview(box);
+if (!preview) throw new Error("Preview requires a working service worker");
+iframe.src = preview.urlFor(3000);
 ```
 
 It works between preview pages and from another tab of the same browser while the owner page is
@@ -172,13 +178,14 @@ browser's rule about _pages_, not a container limit, and the only way through it
 somewhere a page is not. So add one to the project you already deploy:
 
 ```bash
-npx sandboxedjs-egress init --allow ollama.com,api.openai.com
+npx sandboxedjs-egress init --target cloudflare --allow ollama.com,api.openai.com
 ```
 
 That writes a single function file at the path your host serves — Cloudflare Pages, Vercel and
 Netlify are detected, `--target` names one. Nothing else changes: a container in a browser probes
-its own origin for that proxy before giving up, so **no project passes a `proxy` option and no
-project is configured twice.**
+its own origin for that proxy before giving up. The guest project needs no proxy setting;
+the host must deploy the generated function. For a separate relay, set `network.proxy`.
+A host serving only static files cannot relay APIs that reject browser requests.
 
 | Where you are                     | What to do                                                                          |
 | --------------------------------- | ----------------------------------------------------------------------------------- |
@@ -249,6 +256,11 @@ from source where a wheel does not exist; browsers have no compiler, so they ask
 `npx sandboxedjs-build-wheels 4180`. See [docs/python/build-on-miss.md](docs/python/build-on-miss.md)
 and [compatibility](docs/python/compatibility.md).
 
+**Python thread offloads work in the bundled runtime:** `asyncio.to_thread`,
+`run_in_executor`, and synchronous FastAPI routes use real worker threads.
+For browser deployments, update `python-worker.js` and the entire `python/`
+directory together. See [threading architecture and limits](docs/browser-runtime-architecture.md#python-thread-offloads).
+
 **What does not work in a browser:** `copyIn()` / `copyOut()` and `expose()` (they need a real
 filesystem and a real socket), and the CLI. They fail only if you call them.
 

package/bin/sandboxedjs-egress.mjs

@@ -45,7 +45,7 @@ const TARGETS = {
 ${allow}
 /* Cloudflare Pages serves this file at /__sandboxedjs__/egress, which is where
  * a container in this site's pages looks for its way out. */
-export const onRequest = ({ request }) => handleEgressRequest(request, options);
+export const onRequest = ({ request }: { request: Request }) => handleEgressRequest(request, options);
 `,
   },
   vercel: {
@@ -57,7 +57,7 @@ export const config = { runtime: "edge" };
 
 /* Vercel serves this file at /api/__sandboxedjs__/egress, which is one of the
  * paths a container in this site's pages probes for its way out. */
-export default (request) => handleEgressRequest(request, options);
+export default (request: Request) => handleEgressRequest(request, options);
 `,
   },
   netlify: {
@@ -67,7 +67,7 @@ export default (request) => handleEgressRequest(request, options);
 ${allow}
 export const config = { path: "/.netlify/functions/sandboxedjs-egress" };
 
-export default (request) => handleEgressRequest(request, options);
+export default (request: Request) => handleEgressRequest(request, options);
 `,
   },
 };
@@ -90,13 +90,28 @@ async function detectTarget(root) {
 }
 
 async function init(argv) {
-  const root = argv.find((a) => !a.startsWith("-")) ?? process.cwd();
-  const at = argv.indexOf("--target");
-  const allowAt = argv.indexOf("--allow");
-  const allowed = allowAt === -1
-    ? null
-    : (argv[allowAt + 1] ?? "").split(",").map((h) => h.trim()).filter(Boolean);
-  const name = at === -1 ? await detectTarget(root) : argv[at + 1];
+  let directory;
+  let targetName;
+  let allowed = null;
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (argument === "--target" || argument === "--allow") {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) {
+        console.error(`sandboxedjs-egress init: ${argument} requires a value`);
+        process.exitCode = 1;
+        return;
+      }
+      if (argument === "--target") targetName = value;
+      else allowed = value.split(",").map((host) => host.trim()).filter(Boolean);
+    } else if (argument.startsWith("-") || directory !== undefined) {
+      console.error(`sandboxedjs-egress init: unexpected argument ${argument}`);
+      process.exitCode = 1;
+      return;
+    } else directory = argument;
+  }
+  const root = directory ?? process.cwd();
+  const name = targetName ?? await detectTarget(root);
   if (!name || !TARGETS[name]) {
     console.error(
       name

package/dist/index.cjs

@@ -20027,7 +20027,7 @@ var CAPABILITIES = ["files", "descriptors", "pipes", "readiness", "time", "ident
 var OP_NAMES = Object.fromEntries(
   Object.entries(Op).map(([name, code]) => [code, name])
 );
-Object.fromEntries(
+var ERRNO_NAMES = Object.fromEntries(
   Object.entries(Errno).map(([name, code]) => [code, name])
 );
 
@@ -21103,7 +21103,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.11"};
+  version: "0.2.13"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {
@@ -21863,6 +21863,59 @@ var FileService = class {
 init_signals();
 init_binary();
 
+// src/python/thread-transport.ts
+init_binary();
+async function createThreadTransport(generation, handle) {
+  const crypto2 = globalThis.crypto ?? (await nodeBuiltin("crypto")).webcrypto;
+  const name = `sbx-python-${crypto2.randomUUID()}`;
+  const channel = new BroadcastChannel(name);
+  const pending = /* @__PURE__ */ new Set();
+  let closed = false;
+  let memory;
+  let memoryReady;
+  const ready = new Promise((resolve3) => {
+    memoryReady = resolve3;
+  });
+  channel.onmessage = async ({ data }) => {
+    if (closed || !(data?.request instanceof Uint8Array) || data.request.length < 16 || !Number.isSafeInteger(data.offset) || data.offset < 0 || data.offset % 4 || !Number.isSafeInteger(data.capacity) || data.capacity < 84) return;
+    await ready;
+    if (closed || !memory || data.offset + data.capacity > memory.buffer.byteLength) return;
+    const control = new Int32Array(memory.buffer, data.offset, 1);
+    const output = new Uint8Array(memory.buffer, data.offset, data.capacity);
+    pending.add(control);
+    try {
+      const request = data.request.slice();
+      new DataView(request.buffer).setUint32(8, generation, true);
+      const response = await handle(request);
+      if (closed) return;
+      if (response.length > output.length - 64) throw new Error("thread response exceeds capacity");
+      output.set(response, 64);
+      const status = new DataView(response.buffer, response.byteOffset).getInt32(12, true);
+      if (status < 0) output.set(new TextEncoder().encode(ERRNO_NAMES[-status] ?? "EIO"), 4);
+      Atomics.store(control, 0, response.length);
+    } catch {
+      Atomics.store(control, 0, -1);
+    } finally {
+      pending.delete(control);
+      Atomics.notify(control, 0);
+    }
+  };
+  return { name, setMemory(value) {
+    if (!(value.buffer instanceof SharedArrayBuffer)) throw new Error("Python thread memory must be shared");
+    memory = value;
+    memoryReady();
+  }, close() {
+    closed = true;
+    memoryReady();
+    channel.close();
+    for (const control of pending) {
+      Atomics.store(control, 0, -1);
+      Atomics.notify(control, 0);
+    }
+    pending.clear();
+  } };
+}
+
 // src/python/protocol.ts
 var ProtocolError = class extends Error {
   code = "ERR_SBX_ABI_PROTOCOL";
@@ -23109,6 +23162,7 @@ async function startPythonProcess(options) {
     sockets: options.sockets,
     processes: options.processes
   });
+  const threads = await createThreadTransport(generation, handle);
   const buffers = createHostTransportBuffers();
   let fault = null;
   const server = new HostCallServer(buffers, handle, (error) => {
@@ -23127,8 +23181,10 @@ async function startPythonProcess(options) {
   const cleanup = () => {
     if (done) return;
     done = true;
+    controller.abort();
     options.signal.removeEventListener("abort", abort);
     server.close();
+    threads.close();
     table.closeAll();
     try {
       worker?.terminate();
@@ -23143,6 +23199,10 @@ async function startPythonProcess(options) {
   }
   worker.onMessage((message) => {
     const detail = message;
+    if (detail?.type === "thread-memory" && detail.memory) {
+      threads.setMemory(detail.memory);
+      return;
+    }
     if (detail?.type === "wake") {
       void server.pump();
       return;
@@ -23175,6 +23235,7 @@ async function startPythonProcess(options) {
       type: "start",
       buffers,
       generation,
+      threadChannel: threads.name,
       moduleUrl: options.manifest.artifacts.moduleUrl,
       argv: options.argv,
       env: options.env,
@@ -25301,7 +25362,30 @@ if _egress:
     sys.meta_path.insert(0, _SbxHttpxHook())
 
 
-if os.environ.get("SBX_SERIAL_HOST_CALLS") == "1":
+if os.environ.get("SBX_THREAD_HOST_CALLS") == "1":
+    import selectors as _selectors
+    import threading as _threading
+    import time as _time
+
+    class _SbxThreadSelector(_selectors.SelectSelector):
+        """Let Emscripten service filesystem calls proxied by Python threads.
+
+        Native socket calls have an independent channel per request. Filesystem
+        calls still use the main runtime thread, so it must periodically leave
+        its host poll and yield whenever other Python threads are alive. Keep
+        the standard asyncio executor, context propagation and cancellation.
+        """
+        def select(self, timeout=None):
+            threaded = _threading.active_count() > 1
+            if threaded:
+                timeout = 0.01 if timeout is None else min(max(timeout, 0), 0.01)
+            ready = super().select(timeout)
+            if threaded:
+                _time.sleep(0.001)
+            return ready
+
+    _selectors.DefaultSelector = _SbxThreadSelector
+elif os.environ.get("SBX_SERIAL_HOST_CALLS") == "1":
     import asyncio
 
     async def _to_thread(func, /, *args, **kwargs):

package/dist/index.js

@@ -20010,7 +20010,7 @@ var CAPABILITIES = ["files", "descriptors", "pipes", "readiness", "time", "ident
 var OP_NAMES = Object.fromEntries(
   Object.entries(Op).map(([name, code]) => [code, name])
 );
-Object.fromEntries(
+var ERRNO_NAMES = Object.fromEntries(
   Object.entries(Errno).map(([name, code]) => [code, name])
 );
 
@@ -21086,7 +21086,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.11"};
+  version: "0.2.13"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {
@@ -21846,6 +21846,59 @@ var FileService = class {
 init_signals();
 init_binary();
 
+// src/python/thread-transport.ts
+init_binary();
+async function createThreadTransport(generation, handle) {
+  const crypto2 = globalThis.crypto ?? (await nodeBuiltin("crypto")).webcrypto;
+  const name = `sbx-python-${crypto2.randomUUID()}`;
+  const channel = new BroadcastChannel(name);
+  const pending = /* @__PURE__ */ new Set();
+  let closed = false;
+  let memory;
+  let memoryReady;
+  const ready = new Promise((resolve3) => {
+    memoryReady = resolve3;
+  });
+  channel.onmessage = async ({ data }) => {
+    if (closed || !(data?.request instanceof Uint8Array) || data.request.length < 16 || !Number.isSafeInteger(data.offset) || data.offset < 0 || data.offset % 4 || !Number.isSafeInteger(data.capacity) || data.capacity < 84) return;
+    await ready;
+    if (closed || !memory || data.offset + data.capacity > memory.buffer.byteLength) return;
+    const control = new Int32Array(memory.buffer, data.offset, 1);
+    const output = new Uint8Array(memory.buffer, data.offset, data.capacity);
+    pending.add(control);
+    try {
+      const request = data.request.slice();
+      new DataView(request.buffer).setUint32(8, generation, true);
+      const response = await handle(request);
+      if (closed) return;
+      if (response.length > output.length - 64) throw new Error("thread response exceeds capacity");
+      output.set(response, 64);
+      const status = new DataView(response.buffer, response.byteOffset).getInt32(12, true);
+      if (status < 0) output.set(new TextEncoder().encode(ERRNO_NAMES[-status] ?? "EIO"), 4);
+      Atomics.store(control, 0, response.length);
+    } catch {
+      Atomics.store(control, 0, -1);
+    } finally {
+      pending.delete(control);
+      Atomics.notify(control, 0);
+    }
+  };
+  return { name, setMemory(value) {
+    if (!(value.buffer instanceof SharedArrayBuffer)) throw new Error("Python thread memory must be shared");
+    memory = value;
+    memoryReady();
+  }, close() {
+    closed = true;
+    memoryReady();
+    channel.close();
+    for (const control of pending) {
+      Atomics.store(control, 0, -1);
+      Atomics.notify(control, 0);
+    }
+    pending.clear();
+  } };
+}
+
 // src/python/protocol.ts
 var ProtocolError = class extends Error {
   code = "ERR_SBX_ABI_PROTOCOL";
@@ -23092,6 +23145,7 @@ async function startPythonProcess(options) {
     sockets: options.sockets,
     processes: options.processes
   });
+  const threads = await createThreadTransport(generation, handle);
   const buffers = createHostTransportBuffers();
   let fault = null;
   const server = new HostCallServer(buffers, handle, (error) => {
@@ -23110,8 +23164,10 @@ async function startPythonProcess(options) {
   const cleanup = () => {
     if (done) return;
     done = true;
+    controller.abort();
     options.signal.removeEventListener("abort", abort);
     server.close();
+    threads.close();
     table.closeAll();
     try {
       worker?.terminate();
@@ -23126,6 +23182,10 @@ async function startPythonProcess(options) {
   }
   worker.onMessage((message) => {
     const detail = message;
+    if (detail?.type === "thread-memory" && detail.memory) {
+      threads.setMemory(detail.memory);
+      return;
+    }
     if (detail?.type === "wake") {
       void server.pump();
       return;
@@ -23158,6 +23218,7 @@ async function startPythonProcess(options) {
       type: "start",
       buffers,
       generation,
+      threadChannel: threads.name,
       moduleUrl: options.manifest.artifacts.moduleUrl,
       argv: options.argv,
       env: options.env,
@@ -25284,7 +25345,30 @@ if _egress:
     sys.meta_path.insert(0, _SbxHttpxHook())
 
 
-if os.environ.get("SBX_SERIAL_HOST_CALLS") == "1":
+if os.environ.get("SBX_THREAD_HOST_CALLS") == "1":
+    import selectors as _selectors
+    import threading as _threading
+    import time as _time
+
+    class _SbxThreadSelector(_selectors.SelectSelector):
+        """Let Emscripten service filesystem calls proxied by Python threads.
+
+        Native socket calls have an independent channel per request. Filesystem
+        calls still use the main runtime thread, so it must periodically leave
+        its host poll and yield whenever other Python threads are alive. Keep
+        the standard asyncio executor, context propagation and cancellation.
+        """
+        def select(self, timeout=None):
+            threaded = _threading.active_count() > 1
+            if threaded:
+                timeout = 0.01 if timeout is None else min(max(timeout, 0), 0.01)
+            ready = super().select(timeout)
+            if threaded:
+                _time.sleep(0.001)
+            return ready
+
+    _selectors.DefaultSelector = _SbxThreadSelector
+elif os.environ.get("SBX_SERIAL_HOST_CALLS") == "1":
     import asyncio
 
     async def _to_thread(func, /, *args, **kwargs):