sandboxedjs 0.2.12 → 0.2.13

package/README.md

@@ -256,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/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.12"};
+  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.12"};
+  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):