sandboxedjs 0.2.12 → 0.2.13

package/dist/python/runtime.json

@@ -18,9 +18,9 @@
   "artifacts": {
     "moduleUrl": "./python.js",
     "hashes": {
-      "python.js": "sha256-ba225e5b4900449d493f213dc67263ed1afa7497f36582c43d778ccc282fe749",
-      "python.wasm": "sha256-a971913c97e671ec281c92c2922e0c64b3e2c9565c58a466a9dda78df5bb8e7a",
-      "python.data": "sha256-98d1fd943b6530e6ac7dd816420efe81082510da14c49bdc06fa60f5b08b924e",
+      "python.js": "sha256-2077b7c944097fa32fd80ffdd2575d5877a75bea77a0083f3dce93e7d2ab2976",
+      "python.wasm": "sha256-03f5cb9889a26d5f0b5a3e9d7310e2c5d9f2e8d1c4f9673b061ee19fcbe759c1",
+      "python.data": "sha256-c6e6bcf4afd43d12b50c6a0d013d400868434bbfd37341d4642ea40ad69cacd3",
       "python.worker.js": "sha256-63bb1df52c4e3a95eae7b2d77c98554188fcc5925e72628ea0c34d5c573977a5"
     }
   },

package/dist/python-worker.js

@@ -802,6 +802,7 @@ async function runPythonProcess(start, port) {
   )).default;
   let exitCode = 0;
   let guestMemory;
+  let threadBridgeName;
   const guestHeap = () => {
     const exported = config.HEAPU8;
     if (exported && exported.byteLength > 0) return exported;
@@ -886,6 +887,7 @@ async function runPythonProcess(start, port) {
           if (!guestMemory && result.instance.exports.memory instanceof WebAssembly.Memory) {
             guestMemory = result.instance.exports.memory;
           }
+          threadBridgeName = result.instance.exports.sbx_thread_bridge_name;
           receiveInstance(result.instance, result.module);
         } catch (error) {
           config.onAbort?.(error);
@@ -903,6 +905,13 @@ async function runPythonProcess(start, port) {
       mountContainer(config.FS, client, start.mounts, config.ERRNO_CODES ?? {});
       bindStdio(config.FS, client, start.isTty);
       for (const [key, value] of Object.entries(start.env)) config.ENV[key] = value;
+      if (start.threadChannel && typeof threadBridgeName === "function") {
+        const bytes = new TextEncoder().encode(start.threadChannel + "\0");
+        if (bytes.length > 128) throw new Error("Python thread channel name is too long");
+        guestHeap().set(bytes, threadBridgeName());
+        port.postMessage({ type: "thread-memory", memory: guestMemory });
+        config.ENV.SBX_THREAD_HOST_CALLS = "1";
+      }
       try {
         config.FS.chdir(start.cwd);
       } catch {

package/docs/browser-runtime-architecture.md

@@ -99,44 +99,34 @@ carry a TLS handshake this transport cannot terminate. A page's `fetch` is also
 subject to CORS, so a cross-origin target must send the headers that let the
 page read the response; that is a browser rule, not a container policy.
 
-## Blocking syscalls stop every thread
-
-Threads in this runtime are real and run in parallel: a worker thread happily
-burns CPU while the main thread sits in `time.sleep`, which releases the GIL.
-What they cannot do is make a syscall while another thread is inside one.
-
-The cause is in the interpreter image, not in this package. It is built with
-`-sPROXY_TO_PTHREAD` over a JavaScript-backed filesystem, so every syscall made
-on a thread is forwarded to the single thread that owns that filesystem -- the
-generated glue is full of `if (ENVIRONMENT_IS_PTHREAD) return
-proxyToMainThread(...)`. That thread answers a host call by blocking in
-`Atomics.wait`. While it is blocked it cannot service anybody else's proxied
-syscall, so one thread parked in a blocking read freezes every other thread's
-I/O until it returns.
-
-`asyncio.to_thread` is the case that meets this head-on: the loop parks in a
-blocking `select`, and waking it requires the worker thread to make a syscall
-that the parked thread would have to service. Neither completes.
-`to_thread` now raises immediately, naming the limitation, instead of hanging
-until the process is killed. That is a mitigation, not a fix.
-
-Three earlier explanations of this were wrong and are recorded here so the next
-person does not re-derive them: it is not a single control slot in the transport
-(threads do run concurrently), it is not the file-scope statics in `sbx_call`
-(they are downstream of the proxying), and it is not a missing per-thread
-channel on its own (a channel per thread does nothing while the syscalls are
-still funnelled to one thread).
-
-Fixing it is a change to how the runtime image is built, and there are two
-routes, neither small:
-
-- Stack switching. Suspend the wasm stack on a blocking call and return to the
-  event loop, instead of holding the thread in `Atomics.wait`. This is what the
-  Pyodide backend did through `run_sync`, and it is why that backend did not
-  have this problem. It needs JSPI and a transport rewritten around suspension.
-- Unproxied per-thread syscalls. Give each thread its own channel and host
-  server and stop routing syscalls through one thread. This fights the
-  JavaScript filesystem the image is built on, since that filesystem lives on
-  one thread by construction.
-
-Both are runtime-image work measured in days, not a patch plus a rebuild.
+## Python thread offloads
+
+The bundled pthread interpreter supports standard `asyncio.to_thread`,
+`run_in_executor`, and AnyIO's thread pool, including synchronous FastAPI routes.
+These execute on real Python worker threads, preserving context propagation,
+exceptions, and cancellation of the awaiting task.
+
+Native socket calls release the GIL and send requests directly from each pthread
+to the process supervisor over a private BroadcastChannel. Every outstanding
+request owns a shared response buffer, so a waiting interpreter cannot prevent
+another thread from completing network I/O. The supervisor still applies the
+same descriptor ownership and outbound network policy.
+
+Emscripten filesystem operations still proxy through the interpreter thread.
+While other Python threads exist, the asyncio selector limits each wait to
+10 ms and briefly yields, allowing those queued operations to run. This prevents
+the old deadlock between a sleeping selector and a worker trying to wake it.
+It adds polling overhead while the thread pool is alive.
+
+Deploy the matching `python-worker.js` and the complete `python/` runtime directory
+together. The worker detects the native bridge before enabling this behavior.
+Older custom interpreter images retain the previous explicit `to_thread` error
+and inline AnyIO fallback rather than silently entering a known deadlock.
+
+Regression coverage includes context variables, exceptions, cancellation, file
+I/O, simultaneous thread HTTP calls into an asyncio server, executor shutdown,
+and FastAPI synchronous endpoints. The browser fixture also offloads a file read
+and an outbound HTTPX request from a FastAPI streaming endpoint. This does not
+certify arbitrary native extensions or indefinite blocking filesystem operations;
+thread churn and long-running cleanup soak remain release gates. Browser egress
+restrictions still apply independently of threading.

package/docs/python/release-gates.md

@@ -13,7 +13,7 @@ are proposed targets, not measured results.
 | M5 | native packages | Pydantic core and one small extension survive repeated import/exit | **done for the current ABI** — C and PyO3 side-module wheels load through ordinary CPython imports; `pydantic==2.9.0` selects and runs with `pydantic-core==2.23.2` |
 | M6 | local networking | echo server, concurrent connections, timeouts, port reuse | **partial** — the host-owned virtual TCP stack (`src/net/virtual-socket.ts`), its socket ABI family (`1792`), and router integration are done and cover `box.request()` to a non-JS listener plus cross-stack `EADDRINUSE` (`test/virtual-socket.test.ts`, `test/python-socket-abi.test.ts`, `test/universal-server.test.ts`); the CPython `_sbx_socket` adapter and `socket`/`selectors` patches are written but not yet built into the interpreter, so no Python process has bound a port through it |
 | M7 | web serving | FastAPI validation, streaming, WebSocket, shutdown | **partial** — a real FastAPI/Pydantic 2 application validates and answers through ASGI; Uvicorn cannot yet serve through `box.request()` |
-| M8 | threads | sync endpoints, AnyIO operations, thread cleanup | **partial** — pthread CPython, `asyncio.to_thread()`, and a synchronous FastAPI endpoint pass; churn/cleanup soak is outstanding |
+| M8 | threads | sync endpoints, AnyIO operations, thread cleanup | **partial** — pthread CPython, `asyncio.to_thread()`, context/cancellation/file I/O, concurrent thread sockets, executor shutdown, and synchronous FastAPI endpoints pass; browser full-stack coverage is in `test/fixtures/fullstack-browser`; churn/cleanup soak is outstanding |
 | M9 | persistence | recovery after an interrupted write or install | not started |
 | M10 | ML | correct inference, bounded memory, cancellation | not started |
 | M11 | source builds | compile, install and import a representative C extension in-browser | not started |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandboxedjs",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "A Linux-like container that runs entirely inside Node.js — POSIX shell, ~140 coreutils, Node.js and Python runtimes, virtual filesystem and networking. No Docker, no VM, no native modules.",
   "type": "module",
   "license": "MIT",
@@ -94,6 +94,7 @@
     "process": "^0.11.10",
     "querystring-es3": "^0.2.1",
     "resolve.exports": "^2.0.3",
+    "sandboxedjs": "^0.2.12",
     "semver": "^7.8.5",
     "set-cookie-parser": "^3.1.2",
     "stream-browserify": "^3.0.0",