sandboxedjs 0.1.10 → 0.1.11

package/README.md

@@ -45,8 +45,6 @@ Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation st
 | **Coreutils** | 154 programs — `ls cat cp mv rm mkdir grep sed awk find head tail sort uniq wc cut tr tee xargs chmod chown ln du df ps tar gzip base64 sha256sum diff curl wget` and the rest — plus 54 shell builtins |
 | **Node.js** | Real Node semantics via Nodepod — `require`, npm packages, `http`, `fs`, streams, `worker_threads` |
 | **Python** | MicroPython on WebAssembly, mounted on the *same* filesystem |
-| **WebAssembly** | Any `wasm32-wasi` binary is an executable — [drop it in `$PATH` and run it](#running-compiled-software) |
-| **x86-64 Linux** | Native ELF binaries run on an emulated CPU, with a Linux syscall layer over the same filesystem |
 | **FFmpeg** | `ffmpeg` and `ffprobe` (FFmpeg 5.1) reading and writing container files directly — [optional install](#video-and-audio) |
 | **`/proc`** | Live and synthesised — `ps`, `top`, `free` and `uptime` all read the same source |
 | **Networking** | Virtual interfaces, `/etc/hosts` resolution, in-container HTTP servers, an optional bridge to a real host port |
@@ -261,29 +259,6 @@ await box.waitForPort(3000);
 `yarn` and `pnpm` map onto the same installer. `apt`/`apt-get` reports the built-in package set
 rather than pretending to download Debian archives.
 
-#### Global installs
-
-`npm install -g` works the way it does on a real system. The package goes to
-`/usr/local/lib/node_modules`, every binary its `bin` field declares is linked into
-`/usr/local/bin`, and that directory is already on `$PATH`:
-
-```
-$ npm i -g prettier
-/usr/local/bin/prettier -> /usr/local/lib/node_modules/prettier
-
-$ prettier --version
-3.6.2
-```
-
-Install hooks (`preinstall`, `install`, `postinstall`) run, because for a good number of packages
-the hook is what generates the file `bin` points at. A hook that fails is reported and skipped
-rather than failing the install — the usual cause is a `node-gyp` build that was never going to
-work here, and the package's JavaScript is often fine without it. `--ignore-scripts` opts out, and
-`npm rebuild [-g] [package]` re-runs the hooks and redoes the links without touching the network.
-
-`npm uninstall -g`, `npm ls -g`, `npm root -g`, `npm prefix -g` and `npm bin -g` all operate on
-the same prefix.
-
 #### npx
 
 `npx` works the way you expect: it runs a local binary if there is one, and otherwise installs
@@ -442,96 +417,6 @@ The bundled standard library includes `json`, `re`, `os`, `sys`, `math`, `random
 MicroPython, not CPython — there is no `numpy`, and `pip` can install pure-Python wheels only
 (and only with outbound networking enabled).
 
-### Running compiled software
-
-Three kinds of program run here. JavaScript and WebAssembly run natively. Native **x86-64 Linux
-binaries run on an emulated CPU** — the container ships an x86-64 interpreter and a Linux syscall
-layer that reads and writes the same filesystem as everything else.
-
-```
-$ file ./mytool
-./mytool: ELF 64-bit LSB executable, x86-64, statically linked
-$ ./mytool --version
-```
-
-A statically linked binary needs nothing but the file. Build one with:
-
-```bash
-CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o mytool
-```
-
-Rust: `cargo build --target x86_64-unknown-linux-musl`. C: `musl-gcc -static`.
-
-`x86 info` reports what a binary needs before you run it, and `x86 trace` prints every syscall,
-which is how you find out where something stalls:
-
-```
-$ x86 info ./mytool
-machine:   x86-64
-linkage:   static
-runnable:  yes
-```
-
-#### Dynamically linked binaries
-
-A binary linked against glibc needs its loader and libraries — and those are **not simulated**.
-They are ordinary x86-64 code, and a machine that can run the program can run them too. Copy them
-in from any Linux system and the binary works:
-
-```
-/lib64/ld-linux-x86-64.so.2
-/lib/x86_64-linux-gnu/libc.so.6
-```
-
-That is a couple of megabytes, not a distribution. If they are missing, the failure names the exact
-file it wanted rather than failing vaguely.
-
-#### WebAssembly
-
-Anything targeting `wasm32-wasi` is also a program, with no emulation and no speed penalty:
-
-```
-$ cp jq.wasm /usr/local/bin/jq && chmod +x /usr/local/bin/jq
-$ echo '{"name":"ada"}' | jq .name
-"ada"
-```
-
-The kernel decides what a file is by its magic bytes, exactly as `binfmt_misc` does on Linux, so
-every one of these is dispatched through the same lookup as `grep` or a shell script. The name on
-`$PATH` need not match the format, `argv[0]` is the name it was invoked as, and all of them see the
-container's real filesystem — a binary's `open("data.csv")` opens the file the shell just created.
-
-`wasm info <file>` reports what a module was built for.
-
-#### What does not run, and how it tells you
-
-| File | What happens |
-|---|---|
-| Static x86-64 Linux ELF | Runs, emulated |
-| Dynamic x86-64 Linux ELF | Runs once its loader and libraries are present; names them if not |
-| `wasm32-wasi` module | Runs natively |
-| ELF for another architecture | Named by architecture and refused |
-| Mach-O / PE binary | Named as macOS or Windows; another OS is not emulated |
-| Emscripten or wasm-bindgen `.wasm` | Points at the JavaScript loader beside it |
-| WASI preview 2 component | Points at `jco transpile` |
-| `GOOS=js` build | Points at `GOOS=wasip1` |
-
-The same honesty applies to npm. A package whose `bin` is a compiled executable, whose payload
-lives in platform-gated `optionalDependencies`, or which declares a `cpu` constraint, is diagnosed
-at install time rather than at first run.
-
-#### Limits of the emulator
-
-- **Speed.** An interpreter, not a JIT — expect it to be one to two orders of magnitude slower
-  than native. Fine for a CLI, wrong for a compiler.
-- **Threads are cooperative.** `clone` creates a real thread with its own registers and stack, but
-  only one runs at a time, and switches happen at `futex`, `sched_yield` and `nanosleep`. A thread
-  that spins on memory without entering the kernel keeps the machine to itself.
-- **Integer and the common vector instructions only.** Moves, bitwise operations, byte compares
-  and scalar floating point are implemented; the wider AVX paths are not. An unimplemented
-  instruction names itself and dumps the registers instead of misbehaving quietly.
-- **No sockets, no signals, no `fork`/`exec`.** A guest cannot start another process.
-
 ### Filesystem from the host
 
 ```ts
@@ -792,13 +677,6 @@ Honest list of what does not work:
   pipeline as WebAssembly and runs fine, dev server included, as do Express, Koa, Fastify-style
   apps and plain `http` servers.
 - **Python is MicroPython**, so C extensions (`numpy`, `pandas`, `cryptography`) are unavailable.
-- **The x86-64 emulator is an interpreter**, so native binaries run one to two orders of magnitude
-  slower than they would on a real CPU, its threads are cooperative rather than parallel, and it
-  implements the integer and common vector instructions rather than all of AVX. See
-  [Running compiled software](#running-compiled-software).
-- **macOS and Windows binaries cannot run.** Another instruction set is a matter of emulation;
-  another operating system is not.
-- **No WebAssembly threads.** Modules built with shared memory are refused at startup.
 - **No real sockets.** HTTP servers work through the request proxy; raw TCP/UDP does not.
 - **No real processes.** Processes are cooperative async tasks: `kill -9` cannot interrupt a
   tight synchronous loop, and `SIGSTOP` only marks state.
@@ -871,39 +749,6 @@ await box.exec("greet there | tr a-z A-Z"); // → HELLO THERE
 
 It becomes a real file in `/usr/bin`, so `which greet`, `man greet` and shebang dispatch all work.
 
-### Adding an executable format
-
-The kernel identifies executables by magic bytes and dispatches to a registered handler, the way
-`binfmt_misc` does. WebAssembly is one such handler; so is each native format. Registering your own
-is the supported way to teach the container a new kind of binary — including plugging in an
-emulator:
-
-```ts
-import { createContainer, type ExecFormat } from "sandboxedjs";
-
-const box = await createContainer();
-
-const upx: ExecFormat = {
-  name: "upx",
-  priority: 5, // consulted before the ELF handler
-  matches: (head) => head.subarray(0, 4).toString() === "UPX!",
-  describe: () => "UPX-compressed executable",
-  run: async (ctx, path) => {
-    /* decompress, then hand off however you like */
-    return 0;
-  },
-};
-
-box.kernel.formats.register(upx);
-```
-
-A handler with no `run` is still useful: `explain(head, path)` returns the lines printed in place
-of `Exec format error`, which is how ELF, Mach-O and PE files report what they are.
-
-The x86-64 handler in `src/runtime/x86/` is the worked example: it matches on `\x7fELF` and its
-`run` boots an interpreter, a Linux syscall layer and a process image. A handler for another
-architecture would sit alongside it without the kernel changing at all.
-
 ## Examples
 
 See [`examples/`](./examples): a REPL, an Express API, a React app, a Python data pipeline, an

package/bin/sandboxedjs.mjs

@@ -184,10 +184,8 @@ async function printReplBanner(box, opts) {
     "",
     `${BOLD}sandboxedjs${RESET} — a Linux-like container inside Node.js`,
     "",
-    row("node", node, "npm, npm -g, require, http servers"),
+    row("node", node, "npm, require, http servers"),
     row("python3", python && `MicroPython`, "no C extensions (numpy, pandas)"),
-    row("wasm", "wasi p1", "wasm32-wasi binaries run as commands"),
-    row("x86-64", "emulated", "static Linux ELF binaries run too"),
     row("ffmpeg", ffmpeg, ffmpeg ? "video and audio" : "npm install @ffmpeg/core"),
     row(
       "network",
@@ -200,15 +198,11 @@ async function printReplBanner(box, opts) {
     `${DIM}Try:${RESET}`,
     "  cat /etc/os-release && ls /usr/bin | head",
     '  node -e "require(\'http\').createServer((_,r)=>r.end(\'hi\')).listen(3000)" &',
-    "  npm i -g prettier && prettier --version",
     "  npm create vite@latest app -- --template react && cd app && npm i && npm run dev",
-    "  wasm info tool.wasm && chmod +x tool.wasm && ./tool.wasm",
-    "  x86 info ./linux-binary && ./linux-binary   # native ELF, emulated",
+    "  ffmpeg -f lavfi -i testsrc=size=64x64:rate=5:duration=1 out.mp4 && ls -l out.mp4",
     "",
-    `${DIM}JavaScript and WebAssembly run natively. Static x86-64 Linux binaries run`,
-    "on an emulated CPU — slower, and threads are cooperative. Dynamically linked",
-    "ones also need their loader and libc copied in. macOS and Windows binaries",
-    `cannot run and say so by name. No raw sockets.${RESET}`,
+    `${DIM}Known limits: no native binaries, no raw sockets, and esbuild-based`,
+    `toolchains (Vite 4 and its contemporaries) cannot start. Current Vite works.${RESET}`,
     "",
     `${DIM}Ctrl-D or \`exit\` to leave.${RESET}`,
     "",