@eryx-org/eryx 0.0.0 → 0.15.0

package/instance.js

@@ -0,0 +1,174 @@
+/**
+ * Building one sandbox instance: the shared stdlib template, compiled core
+ * modules and WASI imports, and per-instance filesystem and callback wiring.
+ * Used by index.js in-thread and by worker.js inside a Worker.
+ */
+
+// The jco-generated component, transpiled with `--instantiation async` so each
+// Sandbox gets its own instance and imports.
+import { instantiate } from "./eryx-sandbox.js";
+
+import {
+  environment,
+  exit,
+  stderr,
+  stdin,
+  stdout,
+  terminalInput,
+  terminalOutput,
+  terminalStderr,
+  terminalStdin,
+  terminalStdout,
+} from "#preview2/cli";
+import { monotonicClock, wallClock } from "#preview2/clocks";
+import { createFilesystem, InMemoryFilesystemAdapter } from "#preview2/filesystem";
+import { error, poll, streams } from "#preview2/io";
+import { random } from "#preview2/random";
+import * as sockets from "./shims/sockets.js";
+
+// Import stdlib loader
+import { loadStdlib } from "./stdlib-loader.js";
+
+// Load the Python stdlib once; every Sandbox gets its own copy-on-access view of it.
+const stdlibTree = await loadStdlib();
+
+// The stdlib tar extracts to python-stdlib/*, but the WASM expects
+// files at the root of the preopen (mounted as /python-stdlib).
+const stdlibDir = stdlibTree.dir?.["python-stdlib"] || stdlibTree;
+
+/**
+ * The template file tree each new Sandbox copies: the stdlib and an empty
+ * site-packages directory. Files added here are visible to sandboxes created
+ * afterwards; use a Sandbox's own `_fileTree` to change one that exists.
+ */
+export const _fileTree = {
+  dir: { "python-stdlib": stdlibDir, "site-packages": { dir: {} } },
+};
+
+/**
+ * Copy a file tree for one instance. Directories are copied up front; a file's
+ * bytes are copied the first time the instance touches them, so writes (which
+ * the in-memory filesystem makes in place) never reach the template or another
+ * instance, and untouched stdlib files cost nothing.
+ * @param {Object} node
+ * @returns {Object}
+ */
+export function forkTree(node) {
+  if (node.dir) {
+    const dir = {};
+    for (const [name, child] of Object.entries(node.dir)) dir[name] = forkTree(child);
+    return { ...node, dir };
+  }
+  if (!("source" in node)) return { ...node };
+  const shared = node.source;
+  let own;
+  return {
+    get source() {
+      // Not `slice()`: on a Node Buffer that returns a view, not a copy.
+      return (own ??= typeof shared === "string" ? shared : new Uint8Array(shared));
+    },
+    set source(value) {
+      own = value;
+    },
+  };
+}
+
+export const isNode =
+  typeof globalThis.process !== "undefined" &&
+  typeof globalThis.process.versions?.node !== "undefined";
+
+/** Compiled core modules, shared by every instance. */
+const _coreModules = new Map();
+
+/**
+ * Compile (once) a core wasm module of the component.
+ * @param {string} name
+ * @returns {Promise<WebAssembly.Module>}
+ */
+export function getCoreModule(name) {
+  if (!_coreModules.has(name)) {
+    const url = new URL(`./${name}`, import.meta.url);
+    _coreModules.set(
+      name,
+      isNode
+        ? import(/* webpackIgnore: true */ "node:fs/promises").then(async (fs) =>
+            WebAssembly.compile(await fs.readFile(url)),
+          )
+        : WebAssembly.compileStreaming(fetch(url)),
+    );
+  }
+  return _coreModules.get(name);
+}
+
+const _sockets = {
+  "wasi:sockets/instance-network": sockets.instanceNetwork,
+  "wasi:sockets/ip-name-lookup": sockets.ipNameLookup,
+  "wasi:sockets/network": sockets.network,
+  "wasi:sockets/tcp": sockets.tcp,
+  "wasi:sockets/tcp-create-socket": sockets.tcpCreateSocket,
+  "wasi:sockets/udp": sockets.udp,
+  "wasi:sockets/udp-create-socket": sockets.udpCreateSocket,
+};
+
+/**
+ * Instantiate the component with its own filesystem and callback imports, then
+ * finish the pre-initialized interpreter's setup.
+ * @param {Object} fileTree - The instance's own file tree
+ * @param {ReturnType<typeof import("./shims/callbacks.js").createCallbackHost>["imports"]} cb - Callback imports
+ * @param {{tcp: Object, tls: Object}} net - The instance's eryx:net imports
+ * @param {(name: string) => WebAssembly.Module | Promise<WebAssembly.Module>} [getModule] -
+ *   Core-module source, when not this thread's cache
+ */
+export async function instantiateSandbox(fileTree, cb, net, getModule = getCoreModule) {
+  const fs = createFilesystem({
+    adapter: new InMemoryFilesystemAdapter(),
+    preopens: { "/": fileTree },
+  });
+  const instance = await instantiate(getModule, {
+    invoke: { default: cb.invoke },
+    sleep: { default: cb.sleep },
+    "list-callbacks": { default: cb.listCallbacks },
+    "get-execution-options": { default: cb.getExecutionOptions },
+    "report-trace": { default: cb.reportTrace },
+    "report-output": { default: cb.reportOutput },
+    "eryx:net/tcp": net.tcp,
+    "eryx:net/tls": net.tls,
+    "wasi:cli/environment": environment,
+    "wasi:cli/exit": exit,
+    "wasi:cli/stderr": stderr,
+    "wasi:cli/stdin": stdin,
+    "wasi:cli/stdout": stdout,
+    "wasi:cli/terminal-input": terminalInput,
+    "wasi:cli/terminal-output": terminalOutput,
+    "wasi:cli/terminal-stderr": terminalStderr,
+    "wasi:cli/terminal-stdin": terminalStdin,
+    "wasi:cli/terminal-stdout": terminalStdout,
+    "wasi:clocks/monotonic-clock": monotonicClock,
+    "wasi:clocks/wall-clock": wallClock,
+    "wasi:filesystem/preopens": fs.preopens,
+    "wasi:filesystem/types": fs.types,
+    "wasi:io/error": error,
+    "wasi:io/poll": poll,
+    "wasi:io/streams": streams,
+    "wasi:random/random": random,
+    ..._sockets,
+  });
+  // The pre-initialized WASM has Python's core state baked in, but
+  // finalizePreinit() must still be called to finish setup.
+  instance.finalizePreinit();
+  return instance;
+}
+
+
+/** Turn a thrown value into something structured clone keeps intact. */
+export function encodeError(e) {
+  return e instanceof Error ? { error: { name: e.name, message: e.message } } : { thrown: e };
+}
+
+/** Rebuild a value thrown on the other side of the channel. */
+export function decodeError(reply) {
+  if (!reply.error) return reply.thrown;
+  const error = new Error(reply.error.message);
+  error.name = reply.error.name;
+  return error;
+}

package/interfaces/eryx-net-tcp.d.ts

@@ -0,0 +1,30 @@
+/** @module Interface eryx:net/tcp@0.1.0 **/
+export function connect(host: string, port: number, timeoutMs: number): TcpHandle;
+export function read(handle: TcpHandle, len: number, timeoutMs: number): Uint8Array;
+export function write(handle: TcpHandle, timeoutMs: number, data: Uint8Array): number;
+export function close(handle: TcpHandle): void;
+export type TcpHandle = number;
+export type TcpError = TcpErrorConnectionRefused | TcpErrorConnectionReset | TcpErrorTimedOut | TcpErrorHostNotFound | TcpErrorIoError | TcpErrorNotPermitted | TcpErrorInvalidHandle;
+export interface TcpErrorConnectionRefused {
+  tag: 'connection-refused',
+}
+export interface TcpErrorConnectionReset {
+  tag: 'connection-reset',
+}
+export interface TcpErrorTimedOut {
+  tag: 'timed-out',
+}
+export interface TcpErrorHostNotFound {
+  tag: 'host-not-found',
+}
+export interface TcpErrorIoError {
+  tag: 'io-error',
+  val: string,
+}
+export interface TcpErrorNotPermitted {
+  tag: 'not-permitted',
+  val: string,
+}
+export interface TcpErrorInvalidHandle {
+  tag: 'invalid-handle',
+}

package/interfaces/eryx-net-tls.d.ts

@@ -0,0 +1,24 @@
+/** @module Interface eryx:net/tls@0.1.0 **/
+export function upgrade(tcp: TcpHandle, hostname: string, timeoutMs: number): TlsHandle;
+export function read(handle: TlsHandle, len: number, timeoutMs: number): Uint8Array;
+export function write(handle: TlsHandle, timeoutMs: number, data: Uint8Array): number;
+export function close(handle: TlsHandle): void;
+export type TcpHandle = import('./eryx-net-tcp.js').TcpHandle;
+export type TlsHandle = number;
+export type TcpError = import('./eryx-net-tcp.js').TcpError;
+export type TlsError = TlsErrorTcp | TlsErrorHandshakeFailed | TlsErrorCertificateError | TlsErrorInvalidHandle;
+export interface TlsErrorTcp {
+  tag: 'tcp',
+  val: TcpError,
+}
+export interface TlsErrorHandshakeFailed {
+  tag: 'handshake-failed',
+  val: string,
+}
+export interface TlsErrorCertificateError {
+  tag: 'certificate-error',
+  val: string,
+}
+export interface TlsErrorInvalidHandle {
+  tag: 'invalid-handle',
+}

package/interfaces/wasi-cli-environment.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/environment@0.2.0 **/
+export function getEnvironment(): Array<[string, string]>;
+export function getArguments(): Array<string>;

package/interfaces/wasi-cli-exit.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/exit@0.2.0 **/
+export function exit(status: Result<void, void>): void;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/interfaces/wasi-cli-stderr.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/stderr@0.2.0 **/
+export function getStderr(): OutputStream;
+export type OutputStream = import('./wasi-io-streams.js').OutputStream;

package/interfaces/wasi-cli-stdin.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/stdin@0.2.0 **/
+export function getStdin(): InputStream;
+export type InputStream = import('./wasi-io-streams.js').InputStream;

package/interfaces/wasi-cli-stdout.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/stdout@0.2.0 **/
+export function getStdout(): OutputStream;
+export type OutputStream = import('./wasi-io-streams.js').OutputStream;

package/interfaces/wasi-cli-terminal-input.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:cli/terminal-input@0.2.0 **/
+
+export class TerminalInput {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+}

package/interfaces/wasi-cli-terminal-output.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:cli/terminal-output@0.2.0 **/
+
+export class TerminalOutput {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+}

package/interfaces/wasi-cli-terminal-stderr.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/terminal-stderr@0.2.0 **/
+export function getTerminalStderr(): TerminalOutput | undefined;
+export type TerminalOutput = import('./wasi-cli-terminal-output.js').TerminalOutput;

package/interfaces/wasi-cli-terminal-stdin.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/terminal-stdin@0.2.0 **/
+export function getTerminalStdin(): TerminalInput | undefined;
+export type TerminalInput = import('./wasi-cli-terminal-input.js').TerminalInput;

package/interfaces/wasi-cli-terminal-stdout.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/terminal-stdout@0.2.0 **/
+export function getTerminalStdout(): TerminalOutput | undefined;
+export type TerminalOutput = import('./wasi-cli-terminal-output.js').TerminalOutput;

package/interfaces/wasi-clocks-monotonic-clock.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:clocks/monotonic-clock@0.2.0 **/
+export function now(): Instant;
+export function resolution(): Duration;
+export function subscribeInstant(when: Instant): Pollable;
+export function subscribeDuration(when: Duration): Pollable;
+export type Duration = bigint;
+export type Instant = bigint;
+export type Pollable = import('./wasi-io-poll.js').Pollable;

package/interfaces/wasi-clocks-wall-clock.d.ts

@@ -0,0 +1,7 @@
+/** @module Interface wasi:clocks/wall-clock@0.2.0 **/
+export function now(): Datetime;
+export function resolution(): Datetime;
+export interface Datetime {
+  seconds: bigint,
+  nanoseconds: number,
+}

package/interfaces/wasi-filesystem-preopens.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:filesystem/preopens@0.2.0 **/
+export function getDirectories(): Array<[Descriptor, string]>;
+export type Descriptor = import('./wasi-filesystem-types.js').Descriptor;

package/interfaces/wasi-filesystem-types.d.ts

@@ -0,0 +1,207 @@
+/** @module Interface wasi:filesystem/types@0.2.0 **/
+export function filesystemErrorCode(err: Error): ErrorCode | undefined;
+export type Filesize = bigint;
+/**
+ * # Variants
+ * 
+ * ## `"normal"`
+ * 
+ * ## `"sequential"`
+ * 
+ * ## `"random"`
+ * 
+ * ## `"will-need"`
+ * 
+ * ## `"dont-need"`
+ * 
+ * ## `"no-reuse"`
+ */
+export type Advice = "normal" | "sequential" | "random" | "will-need" | "dont-need" | "no-reuse";
+/**
+ * # Variants
+ * 
+ * ## `"access"`
+ * 
+ * ## `"would-block"`
+ * 
+ * ## `"already"`
+ * 
+ * ## `"bad-descriptor"`
+ * 
+ * ## `"busy"`
+ * 
+ * ## `"deadlock"`
+ * 
+ * ## `"quota"`
+ * 
+ * ## `"exist"`
+ * 
+ * ## `"file-too-large"`
+ * 
+ * ## `"illegal-byte-sequence"`
+ * 
+ * ## `"in-progress"`
+ * 
+ * ## `"interrupted"`
+ * 
+ * ## `"invalid"`
+ * 
+ * ## `"io"`
+ * 
+ * ## `"is-directory"`
+ * 
+ * ## `"loop"`
+ * 
+ * ## `"too-many-links"`
+ * 
+ * ## `"message-size"`
+ * 
+ * ## `"name-too-long"`
+ * 
+ * ## `"no-device"`
+ * 
+ * ## `"no-entry"`
+ * 
+ * ## `"no-lock"`
+ * 
+ * ## `"insufficient-memory"`
+ * 
+ * ## `"insufficient-space"`
+ * 
+ * ## `"not-directory"`
+ * 
+ * ## `"not-empty"`
+ * 
+ * ## `"not-recoverable"`
+ * 
+ * ## `"unsupported"`
+ * 
+ * ## `"no-tty"`
+ * 
+ * ## `"no-such-device"`
+ * 
+ * ## `"overflow"`
+ * 
+ * ## `"not-permitted"`
+ * 
+ * ## `"pipe"`
+ * 
+ * ## `"read-only"`
+ * 
+ * ## `"invalid-seek"`
+ * 
+ * ## `"text-file-busy"`
+ * 
+ * ## `"cross-device"`
+ */
+export type ErrorCode = "access" | "would-block" | "already" | "bad-descriptor" | "busy" | "deadlock" | "quota" | "exist" | "file-too-large" | "illegal-byte-sequence" | "in-progress" | "interrupted" | "invalid" | "io" | "is-directory" | "loop" | "too-many-links" | "message-size" | "name-too-long" | "no-device" | "no-entry" | "no-lock" | "insufficient-memory" | "insufficient-space" | "not-directory" | "not-empty" | "not-recoverable" | "unsupported" | "no-tty" | "no-such-device" | "overflow" | "not-permitted" | "pipe" | "read-only" | "invalid-seek" | "text-file-busy" | "cross-device";
+/**
+ * # Variants
+ * 
+ * ## `"unknown"`
+ * 
+ * ## `"block-device"`
+ * 
+ * ## `"character-device"`
+ * 
+ * ## `"directory"`
+ * 
+ * ## `"fifo"`
+ * 
+ * ## `"symbolic-link"`
+ * 
+ * ## `"regular-file"`
+ * 
+ * ## `"socket"`
+ */
+export type DescriptorType = "unknown" | "block-device" | "character-device" | "directory" | "fifo" | "symbolic-link" | "regular-file" | "socket";
+export type Error = import('./wasi-io-streams.js').Error;
+export type InputStream = import('./wasi-io-streams.js').InputStream;
+export type OutputStream = import('./wasi-io-streams.js').OutputStream;
+export interface DescriptorFlags {
+  read?: boolean,
+  write?: boolean,
+  fileIntegritySync?: boolean,
+  dataIntegritySync?: boolean,
+  requestedWriteSync?: boolean,
+  mutateDirectory?: boolean,
+}
+export type Datetime = import('./wasi-clocks-wall-clock.js').Datetime;
+export type NewTimestamp = NewTimestampNoChange | NewTimestampNow | NewTimestampTimestamp;
+export interface NewTimestampNoChange {
+  tag: 'no-change',
+}
+export interface NewTimestampNow {
+  tag: 'now',
+}
+export interface NewTimestampTimestamp {
+  tag: 'timestamp',
+  val: Datetime,
+}
+export type LinkCount = bigint;
+export interface DescriptorStat {
+  type: DescriptorType,
+  linkCount: LinkCount,
+  size: Filesize,
+  dataAccessTimestamp?: Datetime,
+  dataModificationTimestamp?: Datetime,
+  statusChangeTimestamp?: Datetime,
+}
+export interface PathFlags {
+  symlinkFollow?: boolean,
+}
+export interface OpenFlags {
+  create?: boolean,
+  directory?: boolean,
+  exclusive?: boolean,
+  truncate?: boolean,
+}
+export interface MetadataHashValue {
+  lower: bigint,
+  upper: bigint,
+}
+export interface DirectoryEntry {
+  type: DescriptorType,
+  name: string,
+}
+
+export class Descriptor {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  readViaStream(offset: Filesize): InputStream;
+  writeViaStream(offset: Filesize): OutputStream;
+  appendViaStream(): OutputStream;
+  advise(offset: Filesize, length: Filesize, advice: Advice): void;
+  syncData(): void;
+  getFlags(): DescriptorFlags;
+  getType(): DescriptorType;
+  setSize(size: Filesize): void;
+  setTimes(dataAccessTimestamp: NewTimestamp, dataModificationTimestamp: NewTimestamp): void;
+  read(length: Filesize, offset: Filesize): [Uint8Array, boolean];
+  write(buffer: Uint8Array, offset: Filesize): Filesize;
+  readDirectory(): DirectoryEntryStream;
+  sync(): void;
+  createDirectoryAt(path: string): void;
+  stat(): DescriptorStat;
+  statAt(pathFlags: PathFlags, path: string): DescriptorStat;
+  setTimesAt(pathFlags: PathFlags, path: string, dataAccessTimestamp: NewTimestamp, dataModificationTimestamp: NewTimestamp): void;
+  linkAt(oldPathFlags: PathFlags, oldPath: string, newDescriptor: Descriptor, newPath: string): void;
+  openAt(pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: DescriptorFlags): Descriptor;
+  readlinkAt(path: string): string;
+  removeDirectoryAt(path: string): void;
+  renameAt(oldPath: string, newDescriptor: Descriptor, newPath: string): void;
+  symlinkAt(oldPath: string, newPath: string): void;
+  unlinkFileAt(path: string): void;
+  metadataHash(): MetadataHashValue;
+  metadataHashAt(pathFlags: PathFlags, path: string): MetadataHashValue;
+}
+
+export class DirectoryEntryStream {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  readDirectoryEntry(): DirectoryEntry | undefined;
+}

package/interfaces/wasi-io-error.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:io/error@0.2.0 **/
+
+export class Error {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+}

package/interfaces/wasi-io-poll.d.ts

@@ -0,0 +1,10 @@
+/** @module Interface wasi:io/poll@0.2.0 **/
+export function poll(in_: Array<Pollable>): Uint32Array;
+
+export class Pollable {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  block(): void;
+}

package/interfaces/wasi-io-streams.d.ts

@@ -0,0 +1,33 @@
+/** @module Interface wasi:io/streams@0.2.0 **/
+export type Error = import('./wasi-io-error.js').Error;
+export type Pollable = import('./wasi-io-poll.js').Pollable;
+export type StreamError = StreamErrorLastOperationFailed | StreamErrorClosed;
+export interface StreamErrorLastOperationFailed {
+  tag: 'last-operation-failed',
+  val: Error,
+}
+export interface StreamErrorClosed {
+  tag: 'closed',
+}
+
+export class InputStream {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  read(len: bigint): Uint8Array;
+  blockingRead(len: bigint): Uint8Array;
+  subscribe(): Pollable;
+}
+
+export class OutputStream {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  checkWrite(): bigint;
+  write(contents: Uint8Array): void;
+  blockingWriteAndFlush(contents: Uint8Array): void;
+  blockingFlush(): void;
+  subscribe(): Pollable;
+}

package/interfaces/wasi-random-random.d.ts

@@ -0,0 +1,2 @@
+/** @module Interface wasi:random/random@0.2.0 **/
+export function getRandomBytes(len: bigint): Uint8Array;

package/interfaces/wasi-sockets-instance-network.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:sockets/instance-network@0.2.0 **/
+export function instanceNetwork(): Network;
+export type Network = import('./wasi-sockets-network.js').Network;

package/interfaces/wasi-sockets-ip-name-lookup.d.ts

@@ -0,0 +1,15 @@
+/** @module Interface wasi:sockets/ip-name-lookup@0.2.0 **/
+export function resolveAddresses(network: Network, name: string): ResolveAddressStream;
+export type IpAddress = import('./wasi-sockets-network.js').IpAddress;
+export type ErrorCode = import('./wasi-sockets-network.js').ErrorCode;
+export type Pollable = import('./wasi-io-poll.js').Pollable;
+export type Network = import('./wasi-sockets-network.js').Network;
+
+export class ResolveAddressStream {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  resolveNextAddress(): IpAddress | undefined;
+  subscribe(): Pollable;
+}