@eryx-org/eryx 0.0.0 → 0.15.1

package/README.md

@@ -1,7 +1,284 @@
 # @eryx-org/eryx
 
-A Python sandbox powered by WebAssembly, for browser and Node.js. This is the
-new name of [`@bsull/eryx`](https://www.npmjs.com/package/@bsull/eryx).
+A Python sandbox powered by WebAssembly, for browser and Node.js.
 
-This 0.0.0 is a placeholder, published so the release workflow could be set
-up; it has no code. Use the latest version.
+Eryx runs **CPython 3.14** inside a WASM sandbox with full isolation — no network, no filesystem, no system access unless you explicitly allow it. Variables persist across calls, state can be snapshotted/restored, and execution can be traced line-by-line.
+
+## Install
+
+```bash
+npm install @eryx-org/eryx
+```
+
+**Requirements:** Chrome 133+ or Node.js 24+ (requires [JSPI](https://v8.dev/blog/jspi); Node.js 24–25 need `--experimental-wasm-jspi`, Node.js 26+ has it on by default).
+
+## Usage
+
+```js
+import { Sandbox } from "@eryx-org/eryx";
+
+const sandbox = new Sandbox();
+const result = await sandbox.execute('print("Hello from Python!")');
+console.log(result.stdout); // "Hello from Python!"
+```
+
+### Returning a structured result
+
+Assign a variable named `result` and it is JSON-serialized and returned as
+`result.result` — a structured channel separate from `stdout`:
+
+```js
+const result = await sandbox.execute('result = {"answer": 42, "items": [1, 2, 3]}');
+console.log(result.result); // { answer: 42, items: [ 1, 2, 3 ] }
+```
+
+If the value is not JSON-serializable, `result.result` is `undefined` and
+`result.resultError` explains why (execution still succeeds). Use
+`sandbox.setResultVariable("name")` to capture a different variable name.
+
+### Persistent state
+
+Variables, functions, and imports persist across `execute()` calls:
+
+```js
+await sandbox.execute("x = 42");
+await sandbox.execute("import math");
+const result = await sandbox.execute("print(math.sqrt(x))");
+console.log(result.stdout); // "6.48074069840786"
+```
+
+### Snapshots
+
+Save and restore interpreter state:
+
+```js
+await sandbox.execute("data = [1, 2, 3]");
+const snapshot = await sandbox.snapshotState();
+
+await sandbox.clearState();
+await sandbox.restoreState(snapshot);
+
+const result = await sandbox.execute("print(data)");
+console.log(result.stdout); // "[1, 2, 3]"
+```
+
+### Callbacks
+
+Sandboxed code can `await` functions you provide, called with its keyword
+arguments. They can be async, and what they return must be JSON:
+
+```js
+import { Sandbox } from "@eryx-org/eryx";
+
+const sandbox = new Sandbox({
+  callbacks: {
+    get_weather: {
+      description: "Get current weather for a city", // shown by list_callbacks()
+      handler: async ({ city }) => ({ temp: 72, unit: "F", city }),
+    },
+    now: () => Date.now(), // no description
+  },
+});
+await sandbox.execute(`
+weather = await get_weather(city="NYC")
+print(f"Temperature in {weather['city']}: {weather['temp']}°{weather['unit']}")
+`);
+```
+
+If a callback throws, the code gets a `RuntimeError` with its message
+(`"RangeError: no such city"`). `BigInt`s are returned exactly, and so is a
+value wrapped in `JSON.rawJSON` (`JSON.rawJSON("1.0")` stays a float).
+
+This is the same `callbacks` option as eryx.run's client,
+[`@eryx-org/eryx-run`](https://www.npmjs.com/package/@eryx-org/eryx-run),
+which runs the code on eryx.run instead. Both share their error classes and
+`ExecuteResult`, so code written against one works with the other.
+
+`traceHandler` and `outputHandler` can be set per sandbox too, or for every
+sandbox with `setTraceHandler()` and `setOutputHandler()`.
+
+### Networking
+
+Networking is off by default. Enable it with a host policy (same rules as the Rust crate's `NetConfig`; localhost and private ranges stay blocked unless you override `blockedHosts`, IP addresses are checked against `blockedNetworks`, and in Node.js so are the addresses a name resolves to, with `allowedNetworks` and `internalHosts` as exceptions). At most `maxConnections` (default 10) are open at once, timeouts are capped by `connectTimeoutMs` and `ioTimeoutMs`, and connections are closed when each call into the sandbox finishes. Browsers resolve names themselves, so a name that points at a private address can't be refused there: use `allowedHosts` rather than `allowAllHosts` in browsers.
+
+```js
+import { Sandbox, setNetConfig } from "@eryx-org/eryx";
+
+const sandbox = new Sandbox({ netConfig: { allowedHosts: ["api.github.com", "*.example.com"] } });
+await sandbox.execute(`
+import json, urllib.request
+repo = json.load(urllib.request.urlopen("https://api.github.com/repos/eryx-org/eryx"))
+print(repo["stargazers_count"])
+`);
+
+// Or set the default that sandboxes created afterwards start with.
+setNetConfig({ allowedHosts: ["api.github.com"] });
+```
+
+Each sandbox has its own policy: `netConfig` sets it at creation, and `sandbox.setNetConfig()` replaces it for connections opened afterwards. A sandbox without `netConfig` copies the default from the module-level `setNetConfig()` when it is created, so a later `setNetConfig()` call changes only sandboxes created after it (and the default sandbox behind the module-level `execute()`).
+
+In Node.js, sandboxed code gets real TCP and TLS sockets. Browsers can't open sockets, so there each request is replayed through `fetch()`: only HTTP(S) works, one request per connection, and the server must allow cross-origin requests.
+
+### Callback replay & suspension
+
+Journal callback results so a re-run of the same script replays them instead of calling your handler again, and let a handler suspend execution until it can answer:
+
+```js
+import { Sandbox, SuspendCallback } from "@eryx-org/eryx";
+
+const sandbox = new Sandbox({
+  callbacks: {
+    approve: ({ action }) => {
+      if (!isApproved(action)) throw new SuspendCallback("awaiting approval"); // halts the script
+      return true;
+    },
+  },
+});
+const first = await sandbox.executeWithJournal(code);
+if (first.suspended) {
+  save(first.journal); // a JSON string; store it as-is to resume later
+}
+
+// Later: completed callbacks replay from the journal; the rest run live.
+const resumed = await sandbox.executeWithJournal(code, { journal: load() });
+```
+
+See the [Callback Replay & Suspension guide](https://docs.eryx.run/latest/guide/callback-replay.html) for the matching rules and caveats.
+
+### Streaming output
+
+Get stdout/stderr in real-time instead of waiting for execution to complete:
+
+```js
+import { Sandbox, setOutputHandler } from "@eryx-org/eryx";
+
+setOutputHandler((stream, data) => {
+  const prefix = stream === 0 ? "stdout" : "stderr";
+  process.stdout.write(`[${prefix}] ${data}`);
+});
+
+const sandbox = new Sandbox();
+await sandbox.execute(`
+for i in range(5):
+    print(f"Step {i}")
+`);
+```
+
+### Errors
+
+A run that fails rejects with the same errors as eryx.run's client: code that
+raises rejects with a `PythonExceptionError`, whose `message` is the
+traceback and whose `stdout` and `stderr` hold the output before it, and a
+run past `timeoutMs` with a `TimeoutError`. Both are `EryxError`s, and say
+how long the run took (`durationMs`) and how many callback calls it made
+(`callbackInvocations`), as a result does.
+
+```js
+import { PythonExceptionError } from "@eryx-org/eryx";
+
+try {
+  await sandbox.execute("raise ValueError('bad input')");
+} catch (e) {
+  if (e instanceof PythonExceptionError) console.log(e.stderr); // ends with the traceback
+}
+```
+
+### Timeouts and memory
+
+Timeouts are opt-in in JavaScript. Unlike the Rust crate and the Python bindings, which stop an execution after 30 seconds by default, nothing interrupts a call here unless you ask, so `while True: pass` never returns. Pass `timeoutMs` to run the sandbox in its own Worker (`worker_threads` in Node.js) that is terminated when a call runs too long:
+
+```js
+import { Sandbox, TimeoutError } from "@eryx-org/eryx";
+
+const sandbox = new Sandbox({ timeoutMs: 5_000 });
+try {
+  await sandbox.execute("while True: pass");
+} catch (e) {
+  console.log(e instanceof TimeoutError); // true
+}
+```
+
+The call rejects with a `TimeoutError` (or `executeWithJournal()` reports it as `outcome.error`) and the sandbox starts over with fresh Python state; the next successful result has `stateWasReset: true`. Callbacks, output and networking still run on the creating thread. The Worker costs about 70 MB on top of the sandbox's own memory, and the sandbox's `_fileTree` isn't available. `close()` terminates the Worker at once; otherwise it lives until the sandbox is garbage collected.
+
+There is no memory limit, with or without `timeoutMs` (the Rust crate and the Python bindings cap memory at 128 MB by default). A sandbox's memory grows as its code allocates, up to the WebAssembly 4 GiB maximum or what the JavaScript engine allows, and its in-memory filesystem has no size cap either. Run untrusted code that might allocate without bound in a process you can afford to lose.
+
+### Node.js and the WASI shims
+
+Under Node.js, eryx loads the in-memory (browser) build of `@bytecodealliance/preview2-shim`, because the Node.js build backs WASI with the real filesystem. Each sandbox gets its own in-memory filesystem, so state set through the shim's module-wide functions (such as `_setFileData()`) never reaches a sandbox.
+
+### Vite / webpack
+
+The package works with Vite and webpack. For Vite, you'll need cross-origin isolation headers for `SharedArrayBuffer`:
+
+```js
+// vite.config.ts
+export default defineConfig({
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
+});
+```
+
+## API
+
+### `Sandbox`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `new Sandbox(options?)` | `Sandbox` | Create an isolated sandbox; `options` can set its `callbacks`, `traceHandler`, `outputHandler`, `netConfig` and `timeoutMs` |
+| `execute(code)` | `Promise<ExecuteResult>` | Run Python code: `stdout`, `stderr`, `result`, `durationMs`, `callbackInvocations`, ... |
+| `executeWithJournal(code, { journal? })` | `Promise<ReplayOutcome>` | Run with callback journaling/replay |
+| `setResultVariable(name)` | `Promise<void>` | Change the captured result variable |
+| `setNetConfig(config)` | `void` | Replace this sandbox's network policy (`null` disables networking) |
+| `close()` | `void` | Close connections, stop a `timeoutMs` Worker, reject later calls (also `using`) |
+| `snapshotState()` | `Promise<StateSnapshot>` | Serialize interpreter state (`data`) and name the globals left out (`skippedGlobals`) |
+| `restoreState(snapshot)` | `Promise<void>` | Restore from a snapshot or its `data` |
+| `clearState()` | `Promise<void>` | Reset all user state |
+
+Each `Sandbox` is its own WebAssembly instance, with its own interpreter, filesystem, network connections, callbacks and journal; code in one can't see another's state. The compiled code is shared, but each instance has its own memory (about 20 MB idle on Node.js 24). Call `sandbox.close()` (or declare it with `using`) when you're done; a sandbox that is only dropped is freed whenever the garbage collector gets to it. The module-level `execute()`, `executeWithJournal()` and `setResultVariable()` use one default sandbox, created on first use.
+
+Calls on one sandbox run one at a time, in call order: a call made while another is running waits for it to finish. So don't await `execute()` on the same sandbox from inside one of its callbacks, since it would wait on the execution that called it. Different sandboxes run independently.
+
+### Handlers and errors
+
+| Export | Description |
+|----------|-------------|
+| `setTraceHandler(fn)` | Receive line-level execution trace events (default) |
+| `setOutputHandler(fn)` | Receive streaming stdout/stderr (default) |
+| `SuspendCallback` | Throw from a callback to suspend execution |
+| `EryxError`, `PythonExceptionError`, `TimeoutError`, ... | The errors a run rejects with, shared with `@eryx-org/eryx-run` |
+
+## Moving from `@bsull/eryx`
+
+This package was `@bsull/eryx`. Apart from the name:
+
+- `callbacks` is an object of functions by name. `setCallbacks()`,
+  `setCallbackHandler()` and the `callbackHandler` option are gone, and
+  callbacks are per sandbox (the module-level `execute()` has none).
+  Handlers take the arguments as an object and return a value, not JSON
+  text.
+- A callback that throws an `Error` raises in Python, as one that throws
+  anything else did; it no longer halts the run. `SuspendCallback` still
+  does.
+- Code that raises rejects with a `PythonExceptionError` (`stdout` and
+  `stderr` are strings), and `TimeoutError` is `@eryx-org/eryx-run`'s, with
+  `message` rather than a `timeoutMs` constructor argument.
+- Results also have `durationMs`, `callbackInvocations` and
+  `unsavedVariables` (always empty here).
+
+## How it works
+
+Eryx compiles CPython 3.14 to WebAssembly (WASI) using [componentize-py](https://github.com/bytecodealliance/componentize-py), then pre-initializes the interpreter so startup is fast. The JavaScript bindings are generated by [jco](https://github.com/bytecodealliance/jco) and use JSPI for async interop.
+
+## Links
+
+- [Documentation](https://docs.eryx.run)
+- [GitHub](https://github.com/eryx-org/eryx)
+- [Live demo](https://demo.eryx.run)
+
+## License
+
+MIT OR Apache-2.0

package/eryx-sandbox.d.ts

@@ -0,0 +1,185 @@
+// world root:component/root
+export interface CallbackInfo {
+  name: string,
+  description: string,
+  parametersSchemaJson: string,
+}
+export interface ExecutionOptions {
+  pythonTracing: boolean,
+  reuseEmptyCallbacks: boolean,
+}
+export interface ExecuteOutput {
+  stdout: Uint8Array,
+  stderr: Uint8Array,
+  resultJson: string,
+  resultError: string,
+}
+export interface ExecuteError {
+  message: string,
+  stdout: Uint8Array,
+  stderr: Uint8Array,
+}
+export interface StateSnapshot {
+  data: Uint8Array,
+  skippedGlobals: Array<string>,
+}
+import type * as EryxNetTcp from './interfaces/eryx-net-tcp.js'; // eryx:net/tcp@0.1.0
+import type * as EryxNetTls from './interfaces/eryx-net-tls.js'; // eryx:net/tls@0.1.0
+import type * as WasiCliEnvironment from './interfaces/wasi-cli-environment.js'; // wasi:cli/environment@0.2.0
+import type * as WasiCliExit from './interfaces/wasi-cli-exit.js'; // wasi:cli/exit@0.2.0
+import type * as WasiCliStderr from './interfaces/wasi-cli-stderr.js'; // wasi:cli/stderr@0.2.0
+import type * as WasiCliStdin from './interfaces/wasi-cli-stdin.js'; // wasi:cli/stdin@0.2.0
+import type * as WasiCliStdout from './interfaces/wasi-cli-stdout.js'; // wasi:cli/stdout@0.2.0
+import type * as WasiCliTerminalInput from './interfaces/wasi-cli-terminal-input.js'; // wasi:cli/terminal-input@0.2.0
+import type * as WasiCliTerminalOutput from './interfaces/wasi-cli-terminal-output.js'; // wasi:cli/terminal-output@0.2.0
+import type * as WasiCliTerminalStderr from './interfaces/wasi-cli-terminal-stderr.js'; // wasi:cli/terminal-stderr@0.2.0
+import type * as WasiCliTerminalStdin from './interfaces/wasi-cli-terminal-stdin.js'; // wasi:cli/terminal-stdin@0.2.0
+import type * as WasiCliTerminalStdout from './interfaces/wasi-cli-terminal-stdout.js'; // wasi:cli/terminal-stdout@0.2.0
+import type * as WasiClocksMonotonicClock from './interfaces/wasi-clocks-monotonic-clock.js'; // wasi:clocks/monotonic-clock@0.2.0
+import type * as WasiClocksWallClock from './interfaces/wasi-clocks-wall-clock.js'; // wasi:clocks/wall-clock@0.2.0
+import type * as WasiFilesystemPreopens from './interfaces/wasi-filesystem-preopens.js'; // wasi:filesystem/preopens@0.2.0
+import type * as WasiFilesystemTypes from './interfaces/wasi-filesystem-types.js'; // wasi:filesystem/types@0.2.0
+import type * as WasiIoError from './interfaces/wasi-io-error.js'; // wasi:io/error@0.2.0
+import type * as WasiIoPoll from './interfaces/wasi-io-poll.js'; // wasi:io/poll@0.2.0
+import type * as WasiIoStreams from './interfaces/wasi-io-streams.js'; // wasi:io/streams@0.2.0
+import type * as WasiRandomRandom from './interfaces/wasi-random-random.js'; // wasi:random/random@0.2.0
+import type * as WasiSocketsInstanceNetwork from './interfaces/wasi-sockets-instance-network.js'; // wasi:sockets/instance-network@0.2.0
+import type * as WasiSocketsIpNameLookup from './interfaces/wasi-sockets-ip-name-lookup.js'; // wasi:sockets/ip-name-lookup@0.2.0
+import type * as WasiSocketsNetwork from './interfaces/wasi-sockets-network.js'; // wasi:sockets/network@0.2.0
+import type * as WasiSocketsTcpCreateSocket from './interfaces/wasi-sockets-tcp-create-socket.js'; // wasi:sockets/tcp-create-socket@0.2.0
+import type * as WasiSocketsTcp from './interfaces/wasi-sockets-tcp.js'; // wasi:sockets/tcp@0.2.0
+import type * as WasiSocketsUdpCreateSocket from './interfaces/wasi-sockets-udp-create-socket.js'; // wasi:sockets/udp-create-socket@0.2.0
+import type * as WasiSocketsUdp from './interfaces/wasi-sockets-udp.js'; // wasi:sockets/udp@0.2.0
+export interface ImportObject {
+  invoke: {
+    /**
+    * @throws {string} To return the error of the result, throw it, or an `Error` that has it as its `payload`.
+    */
+    "default"(name: string, argumentsJson: string): Promise<string>,
+  },
+  sleep: {
+    "default"(durationNs: bigint): Promise<void>,
+  },
+  "list-callbacks": {
+    "default"(): Array<CallbackInfo>,
+  },
+  "get-execution-options": {
+    "default"(): ExecutionOptions,
+  },
+  "report-trace": {
+    "default"(lineno: number, eventJson: string, contextJson: string): void,
+  },
+  "report-output": {
+    "default"(streamId: number, data: Uint8Array): void,
+  },
+  "eryx:net/tcp@0.1.0": typeof EryxNetTcp,
+  "eryx:net/tls@0.1.0": typeof EryxNetTls,
+  "wasi:cli/environment@0.2.0": typeof WasiCliEnvironment,
+  "wasi:cli/exit@0.2.0": typeof WasiCliExit,
+  "wasi:cli/stderr@0.2.0": typeof WasiCliStderr,
+  "wasi:cli/stdin@0.2.0": typeof WasiCliStdin,
+  "wasi:cli/stdout@0.2.0": typeof WasiCliStdout,
+  "wasi:cli/terminal-input@0.2.0": typeof WasiCliTerminalInput,
+  "wasi:cli/terminal-output@0.2.0": typeof WasiCliTerminalOutput,
+  "wasi:cli/terminal-stderr@0.2.0": typeof WasiCliTerminalStderr,
+  "wasi:cli/terminal-stdin@0.2.0": typeof WasiCliTerminalStdin,
+  "wasi:cli/terminal-stdout@0.2.0": typeof WasiCliTerminalStdout,
+  "wasi:clocks/monotonic-clock@0.2.0": typeof WasiClocksMonotonicClock,
+  "wasi:clocks/wall-clock@0.2.0": typeof WasiClocksWallClock,
+  "wasi:filesystem/preopens@0.2.0": typeof WasiFilesystemPreopens,
+  "wasi:filesystem/types@0.2.0": typeof WasiFilesystemTypes,
+  "wasi:io/error@0.2.0": typeof WasiIoError,
+  "wasi:io/poll@0.2.0": typeof WasiIoPoll,
+  "wasi:io/streams@0.2.0": typeof WasiIoStreams,
+  "wasi:random/random@0.2.0": typeof WasiRandomRandom,
+  "wasi:sockets/instance-network@0.2.0": typeof WasiSocketsInstanceNetwork,
+  "wasi:sockets/ip-name-lookup@0.2.0": typeof WasiSocketsIpNameLookup,
+  "wasi:sockets/network@0.2.0": typeof WasiSocketsNetwork,
+  "wasi:sockets/tcp-create-socket@0.2.0": typeof WasiSocketsTcpCreateSocket,
+  "wasi:sockets/tcp@0.2.0": typeof WasiSocketsTcp,
+  "wasi:sockets/udp-create-socket@0.2.0": typeof WasiSocketsUdpCreateSocket,
+  "wasi:sockets/udp@0.2.0": typeof WasiSocketsUdp,
+}
+export interface Root {
+  /**
+  * @throws {Error & { payload: ExecuteError }} The error of the result, as the `payload` of the thrown error.
+  */
+  execute(code: string): Promise<ExecuteOutput>,
+  /**
+  * @throws {Error & { payload: string }} The error of the result, as the `payload` of the thrown error.
+  */
+  snapshotState(): Promise<StateSnapshot>,
+  /**
+  * @throws {Error & { payload: string }} The error of the result, as the `payload` of the thrown error.
+  */
+  restoreState(data: Uint8Array): Promise<void>,
+  clearState(): Promise<void>,
+  finalizePreinit(): void,
+  setResultVariable(name: string): Promise<void>,
+  /** Permanently stop this instance and dispose guest-owned host resources. */
+  readonly _util: { stop(): void; whenIdle(): Promise<void>;  /** Test whether a value is a declared WIT result error from this instance. */
+  isComponentError(value: unknown): value is Error & { readonly payload: unknown }; };
+}
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };
+
+/**
+* Options accepted by `instantiate`.
+*/
+export interface InstantiateOptions {
+  /**
+  * Called with each trap of this instance as it happens, in whichever
+  * task: including one a guest left running, which no call of the host's
+  * would otherwise fail for. Not called for stopping the instance, which
+  * it may do itself.
+  */
+  onTrap?: (error: WebAssembly.RuntimeError) => void;
+  /** Runtime overrides for this instance. */
+  shim?: {
+    /** Platform globals used instead of those on `globalThis`. */
+    globals?: {
+      /**
+      * The WebAssembly implementation used by this instance,
+      * including by the default `instantiateCore`. Defaults to
+      * `globalThis.WebAssembly`.
+      */
+      WebAssembly?: typeof WebAssembly;
+    };
+  };
+}
+
+
+/**
+* Instantiates this component with the provided imports and
+* returns a map of all the exports of the component.
+*
+* This function is intended to be similar to the
+* `WebAssembly.Instantiate` constructor. The second `imports`
+* argument is the "import object" for wasm, except here it
+* uses component-model-layer types instead of core wasm
+* integers/numbers/etc.
+*
+* The first argument to this function, `getCoreModule`, is
+* used to compile core wasm modules within the component.
+* Components are composed of core wasm modules and this callback
+* will be invoked per core wasm module. The caller of this
+* function is responsible for reading the core wasm module
+* identified by `path` and returning its compiled
+* `WebAssembly.Module` object. This would use the
+* `WebAssembly.Module` constructor on the web, for example.
+*
+* The optional `options` argument configures instantiation; see
+* `InstantiateOptions`.
+*/
+export function instantiate(
+getCoreModule: (path: string) => WebAssembly.Module,
+imports: ImportObject,
+instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance,
+options?: InstantiateOptions
+): Root;
+export function instantiate(
+getCoreModule: (path: string) => WebAssembly.Module | Promise<WebAssembly.Module>,
+imports: ImportObject,
+instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance | Promise<WebAssembly.Instance>,
+options?: InstantiateOptions
+): Root | Promise<Root>;
+