@eryx-org/eryx 0.0.0 → 0.15.0

package/shims/callbacks.js

@@ -0,0 +1,469 @@
+/**
+ * Callback shims for the eryx sandbox.
+ *
+ * These provide the host-side implementations of the sandbox's callback imports:
+ * - invoke: call a registered callback by name with JSON arguments
+ * - sleep: back the sandbox event loop's timers (asyncio.sleep, wait_for)
+ * - listCallbacks: list all registered callbacks
+ * - getExecutionOptions: return per-execution behavior options
+ * - reportTrace: receive trace events from the Python runtime
+ * - reportOutput: receive streaming stdout/stderr output from the Python runtime
+ *
+ * Each sandbox instance gets its own set from createCallbackHost(), with its
+ * own replay state and output decoders. Its callbacks come from that
+ * sandbox's `callbacks` option; trace and output handlers from its options,
+ * falling back to the module-wide defaults set by setTraceHandler() and
+ * setOutputHandler().
+ */
+
+import { parseJson } from "./raw-json.js";
+
+/**
+ * Module-wide handlers, used by every sandbox that doesn't set its own.
+ * @type {{traceHandler: ((lineno: number, eventJson: string, contextJson: string) => void) | null, outputHandler: ((stream: number, data: string) => void) | null}}
+ */
+const defaults = {
+  traceHandler: null,
+  outputHandler: null,
+};
+
+/** A JSON.stringify replacer writing BigInts as exact integers */
+const exactBigInts = (_key, value) =>
+  typeof value === "bigint" && JSON.rawJSON ? JSON.rawJSON(value.toString()) : value;
+
+/**
+ * A sandbox's callbacks, from the `callbacks` option: what `list_callbacks()`
+ * shows the code, and the handler the host calls with each call's name and
+ * arguments JSON, which answers with the result's JSON.
+ * @param {import("@eryx-org/eryx-run/shared").Callbacks} callbacks
+ */
+function fromCallbacks(callbacks) {
+  if (Array.isArray(callbacks) || typeof callbacks !== "object" || callbacks === null) {
+    throw new TypeError(
+      "callbacks is an object of functions by name, e.g. { get_user: async ({ id }) => ... } " +
+        "(the list of {name, description} with a callbackHandler is gone)",
+    );
+  }
+  const handlers = new Map();
+  const infos = [];
+  for (const [name, callback] of Object.entries(callbacks)) {
+    const fn = typeof callback === "function" ? callback : callback?.handler;
+    if (typeof fn !== "function") {
+      throw new TypeError(`callback ${JSON.stringify(name)} isn't a function or { handler }`);
+    }
+    handlers.set(name, fn);
+    const description = typeof callback === "function" ? "" : (callback.description ?? "");
+    infos.push({ name, description, parametersSchemaJson: "{}" });
+  }
+  /** @param {string} name @param {string} argsJson */
+  const handler = async (name, argsJson) => {
+    try {
+      const fn = handlers.get(name);
+      if (!fn) throw new Error(`no callback ${name}`);
+      // undefined isn't JSON. A BigInt is written exactly, and so is what a
+      // handler wraps in JSON.rawJSON (e.g. "1.0", to stay a float)
+      return JSON.stringify((await fn(JSON.parse(argsJson))) ?? null, exactBigInts);
+    } catch (e) {
+      if (e instanceof SuspendCallback) throw e;
+      // What the handler threw, or a result JSON can't hold (a cycle), is an
+      // exception in Python, as on eryx.run: `RuntimeError("RangeError: ...")`
+      return { tag: "err", val: e instanceof Error ? `${e.name}: ${e.message}` : String(e) };
+    }
+  };
+  return { infos, handler };
+}
+
+/**
+ * Set the default handler for trace events from the Python runtime.
+ *
+ * @param {((lineno: number, eventJson: string, contextJson: string) => void) | null} handler
+ */
+export function setTraceHandler(handler) {
+  defaults.traceHandler = handler;
+}
+
+/**
+ * Set the default handler for streaming output (stdout/stderr) from the Python
+ * runtime.
+ *
+ * The handler is called in real-time as Python code writes to stdout or stderr,
+ * rather than waiting for execution to complete.
+ *
+ * @param {((stream: number, data: string) => void) | null} handler
+ *   stream: 0 = stdout, 1 = stderr
+ *   data: the text written
+ */
+export function setOutputHandler(handler) {
+  defaults.outputHandler = handler;
+}
+
+/**
+ * Thrown by a callback handler to suspend execution ("retry later").
+ *
+ * The guest halts immediately: no further Python runs and no further callbacks
+ * dispatch. Under executeWithJournal() the suspension is surfaced as
+ * `outcome.suspended` and the call is not journaled, so it re-runs live when the
+ * recorded journal is replayed. Under plain execute() it rejects like any error.
+ */
+export class SuspendCallback extends Error {
+  /** @param {string} reason - Opaque reason, surfaced to the caller */
+  constructor(reason) {
+    super(reason);
+    this.name = "SuspendCallback";
+    this.reason = reason;
+  }
+}
+
+/**
+ * A recorded callback outcome. `ok` is the handler's exact JSON result text (not
+ * re-parsed, so replay returns byte-for-byte what Python saw live); `err` is a
+ * Python-visible error message, or the message of a thrown Error when `thrown`.
+ * @typedef {{ok: string} | {err: string, thrown?: boolean}} RecordedResult
+ */
+
+/**
+ * Replay state for an executeWithJournal() run. Mirrors the Rust `ReplayState`
+ * (crates/eryx/src/replay.rs): cached results bucketed by (name, canonical
+ * args) as a FIFO multiset, a sticky divergence guard, and a gate that rejects
+ * every call after a suspension.
+ * @typedef {{cached: Map<string, RecordedResult[]>, liveMode: boolean, nextSeq: number, entries: Array<{name: string, argsJson: string, result: RecordedResult}|undefined>, suspended: Object|null, suspendSeq: number|null, replayedCount: number}} ReplayState
+ */
+
+/**
+ * Parse a serialized journal into its entries.
+ *
+ * Parsed with {@link parseJson} rather than `JSON.parse` so each `Ok` value
+ * keeps its exact text (`1.0` stays a float, large integers stay exact).
+ * @param {string} journal
+ * @returns {Array<{name: string, argsJson: string, result: RecordedResult}>}
+ */
+function _parseJournal(journal) {
+  if (typeof journal !== "string") {
+    throw new TypeError(
+      "journal must be the JSON string from a previous executeWithJournal() outcome",
+    );
+  }
+  const invalid = () =>
+    new TypeError("journal is not a valid callback journal");
+  const field = (node, key, kind) => {
+    const value = node?.kind === "object" ? node.value.get(key) : undefined;
+    if (value?.kind !== kind) throw invalid();
+    return value;
+  };
+  const entries = field(parseJson(journal), "entries", "array").value;
+  return entries.map((entry) => {
+    const result = field(entry, "result", "object").value;
+    const ok = result.get("Ok");
+    const err = result.get("Err");
+    if (!(ok || err?.kind === "string")) throw invalid();
+    return {
+      name: field(entry, "name", "string").value,
+      argsJson: field(entry, "args_json", "string").value,
+      result: ok
+        ? { ok: ok.raw }
+        : { err: err.value, thrown: entry.value.get("thrown")?.raw === "true" },
+    };
+  });
+}
+
+/**
+ * Build the replay state for a run, replaying results from `journal` if given.
+ * @param {string} [journal] - A journal string from a previous outcome
+ * @returns {ReplayState}
+ */
+function _newReplay(journal) {
+  const cached = new Map();
+  for (const entry of journal === undefined ? [] : _parseJournal(journal)) {
+    const key = `${entry.name}\0${entry.argsJson}`;
+    if (!cached.has(key)) cached.set(key, []);
+    cached.get(key).push(entry.result);
+  }
+  return {
+    cached,
+    liveMode: false,
+    nextSeq: 0,
+    entries: [],
+    suspended: null,
+    suspendSeq: null,
+    replayedCount: 0,
+  };
+}
+
+/** 64-bit FNV-1a, matching the Rust journal's `args_hash`. */
+function _fnv1a64(text) {
+  let hash = 0xcbf29ce484222325n;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * 0x100000001b3n);
+  }
+  return hash;
+}
+
+/**
+ * Serialize what a run recorded.
+ *
+ * The journal is serialized in the Rust `CallbackJournal` serde shape. Entries
+ * keep dispatch order and, if a callback suspended, everything dispatched at or
+ * after the suspending call is dropped so the journal is a clean prefix ending
+ * before the suspension point.
+ * @param {ReplayState} state
+ * @param {string} code - The script that produced the journal
+ */
+function _finishReplay(state, code) {
+  const entries = [];
+  state.entries.forEach((entry, index) => {
+    if (entry === undefined) return;
+    if (state.suspendSeq !== null && index >= state.suspendSeq) return;
+    const { name, argsJson, result } = entry;
+    const recorded =
+      "ok" in result
+        ? `{"Ok":${result.ok}}`
+        : `{"Err":${JSON.stringify(result.err)}}`;
+    // `thrown` is a JS-only extension (serde ignores unknown fields): the Error
+    // halted the guest instead of reaching Python, so replay throws it again.
+    const thrown = result.thrown ? `,"thrown":true` : "";
+    entries.push(
+      `{"index":${index},"name":${JSON.stringify(name)},"args_hash":${_fnv1a64(argsJson)},` +
+        `"args_json":${JSON.stringify(argsJson)},"result":${recorded}${thrown}}`,
+    );
+  });
+  return {
+    journal: `{"code":${JSON.stringify(code)},"entries":[${entries.join(",")}]}`,
+    replayedCallbacks: state.replayedCount,
+    suspended: state.suspended ?? undefined,
+  };
+}
+
+/** Deliver a recorded result to the guest exactly as it was delivered live. */
+function _replayResult(result) {
+  if ("ok" in result) return result.ok;
+  if (result.thrown) throw new Error(result.err);
+  return { tag: "err", val: result.err };
+}
+
+/**
+ * Run a live callback, recording its outcome into `state` at `seq`.
+ *
+ * Every outcome of a call that actually ran is journaled, so replay never runs
+ * it twice: a JSON result as `Ok` (its exact text), an `{tag: "err"}` result or
+ * thrown non-Error as `Err`, and a thrown Error as `Err` marked `thrown` (it
+ * halts the guest; replay halts it the same way). Only a SuspendCallback is not
+ * journaled: the call re-runs live on resume, as in Rust.
+ */
+async function _invokeLive(handler, state, seq, name, argsJson) {
+  const record = (result) => {
+    state.entries[seq] = { name, argsJson, result };
+  };
+  let ret;
+  try {
+    ret = await handler(name, argsJson);
+  } catch (e) {
+    if (e instanceof SuspendCallback) {
+      if (state.suspended === null) {
+        state.suspended = { name, argsJson, reason: e.reason };
+        state.suspendSeq = seq;
+      }
+    } else if (e instanceof Error) {
+      record({ err: e.message, thrown: true });
+    } else {
+      record({ err: String(e) });
+    }
+    throw e;
+  }
+  if (ret !== null && typeof ret === "object" && ret.tag === "err") {
+    record({ err: String(ret.val) });
+  } else {
+    const json = ret !== null && typeof ret === "object" ? ret.val : ret;
+    try {
+      parseJson(json);
+      record({ ok: json });
+    } catch {
+      // ponytail: a non-JSON result breaks the handler contract and can't be
+      // stored as an `Ok` value, so it stays unjournaled (re-runs on replay).
+    }
+  }
+  return ret;
+}
+
+/** Longest delay setTimeout accepts; larger values fire immediately. */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+
+/**
+ * Complete after the given number of nanoseconds.
+ * This backs the sandbox event loop's timers (asyncio.sleep, wait_for, ...).
+ *
+ * @param {bigint} durationNs - Delay in nanoseconds
+ * @returns {Promise<void>}
+ */
+export function sleep(durationNs) {
+  // Round up so a timer never fires early.
+  const ms = Number((BigInt(durationNs) + 999_999n) / 1_000_000n);
+  return new Promise((resolve) =>
+    setTimeout(resolve, Math.min(ms, MAX_TIMEOUT_MS)),
+  );
+}
+
+const _decoderOpts = { fatal: false, ignoreBOM: true };
+
+/**
+ * Create the callback imports for one sandbox instance.
+ *
+ * Each handler option overrides the module-wide default from the matching
+ * setter; an omitted (undefined) option follows the default, including later
+ * changes to it. Replay state and streaming output decoders belong to the
+ * returned host alone.
+ *
+ * @internal Used by index.js for each Sandbox.
+ * @param {{callbacks?: import("@eryx-org/eryx-run/shared").Callbacks, traceHandler?: ((lineno: number, eventJson: string, contextJson: string) => void) | null, outputHandler?: ((stream: number, data: string) => void) | null}} [options]
+ */
+export function createCallbackHost(options = {}) {
+  const { infos: callbacks, handler } = fromCallbacks(options.callbacks ?? {});
+  /** Calls the code made since takeInvocations() last ran */
+  let invocations = 0;
+  const pick = (key) => (options[key] === undefined ? defaults[key] : options[key]);
+
+  /** @type {ReplayState | null} */
+  let replay = null;
+
+  // Streaming decoders, tied to the output handler they were created under so
+  // an incomplete multi-byte sequence written under one handler isn't carried
+  // into the next.
+  let decodersFor = null;
+  let stdoutDecoder = new TextDecoder("utf-8", _decoderOpts);
+  let stderrDecoder = new TextDecoder("utf-8", _decoderOpts);
+  const outputHandler = () => {
+    const handler = pick("outputHandler");
+    if (handler !== decodersFor) {
+      decodersFor = handler;
+      stdoutDecoder = new TextDecoder("utf-8", _decoderOpts);
+      stderrDecoder = new TextDecoder("utf-8", _decoderOpts);
+    }
+    return handler;
+  };
+
+  /**
+   * Invoke a callback by name with JSON arguments.
+   * This is called by the sandbox runtime when Python code calls invoke().
+   *
+   * @param {string} name - Callback name
+   * @param {string} argumentsJson - JSON-encoded arguments
+   * @returns {Promise<string>} JSON-encoded result
+   */
+  // Always async: jco 1.41 doesn't turn a synchronous throw from an async-lowered
+  // import into an `err` result, leaving the guest stuck mid-invoke so the next
+  // execute panics ("RefCell already borrowed"). A rejection is handled correctly.
+  async function invoke(name, argumentsJson) {
+    invocations++;
+    const state = replay;
+    if (!state) {
+      return handler(name, argumentsJson);
+    }
+
+    // Decide synchronously, before any await, exactly as the Rust ReplayCallback.
+    if (state.suspended !== null) {
+      throw new SuspendCallback(
+        "execution already suspended by a previous callback",
+      );
+    }
+    const seq = state.nextSeq++;
+    if (!state.liveMode) {
+      // Key on the guest's canonical args text verbatim, as the Rust host does.
+      const result = state.cached.get(`${name}\0${argumentsJson}`)?.shift();
+      if (result !== undefined) {
+        state.replayedCount++;
+        state.entries[seq] = { name, argsJson: argumentsJson, result };
+        return _replayResult(result);
+      }
+      // First miss: the run has diverged from the journal, so this call and every
+      // later one runs live (prevents replaying a now-stale cached result).
+      state.liveMode = true;
+    }
+    return _invokeLive(handler, state, seq, name, argumentsJson);
+  }
+
+  return {
+    imports: {
+      invoke,
+      sleep,
+      /**
+       * List all registered callbacks.
+       * This is called by the sandbox runtime when Python code calls list_callbacks().
+       */
+      listCallbacks: () => callbacks,
+      /**
+       * Return execution behavior options for the JavaScript host.
+       *
+       * JavaScript instances may execute repeatedly with different callbacks, so
+       * callback setup is not reused. Tracing is enabled only while a trace
+       * handler is registered.
+       */
+      getExecutionOptions: () => ({
+        pythonTracing: pick("traceHandler") !== null,
+        reuseEmptyCallbacks: false,
+      }),
+      /** Report a trace event from the Python runtime's sys.settrace hook. */
+      reportTrace(lineno, eventJson, contextJson) {
+        pick("traceHandler")?.(lineno, eventJson, contextJson);
+      },
+      /**
+       * Report streaming output from the Python runtime.
+       * This is called by the sandbox runtime on every sys.stdout/stderr.write().
+       *
+       * @param {number} stream - 0 = stdout, 1 = stderr
+       * @param {Uint8Array} data - The raw bytes written
+       */
+      reportOutput(stream, data) {
+        const handler = outputHandler();
+        if (handler) {
+          const decoder = stream === 0 ? stdoutDecoder : stderrDecoder;
+          handler(stream, decoder.decode(data, { stream: true }));
+        }
+      },
+    },
+
+    /**
+     * Start journaling callbacks, replaying results from `journal` if given.
+     * @param {string} [journal] - A journal string from a previous outcome
+     */
+    beginReplay(journal) {
+      replay = _newReplay(journal);
+    },
+
+    /**
+     * Stop journaling and return what was recorded.
+     * @param {string} code - The script that produced the journal
+     */
+    endReplay(code) {
+      const state = replay;
+      replay = null;
+      return _finishReplay(state, code);
+    },
+
+    /**
+     * Deliver any incomplete multi-byte sequence left at the end of an
+     * execution (as U+FFFD) and reset the decoders, so it can't merge with the
+     * next execution's output. Only call it between executions: mid-run it
+     * would cut a character the guest is still writing.
+     */
+    /** How many callback calls the code made since this was last called. */
+    takeInvocations() {
+      const count = invocations;
+      invocations = 0;
+      return count;
+    },
+
+    flushOutput() {
+      const handler = outputHandler();
+      const stdoutTail = stdoutDecoder.decode();
+      const stderrTail = stderrDecoder.decode();
+      if (!handler) return;
+      if (stdoutTail) handler(0, stdoutTail);
+      if (stderrTail) handler(1, stderrTail);
+    },
+  };
+}
+
+// Imports bound to the module-wide defaults, for embedders that instantiate the
+// low-level component themselves.
+const _defaultHost = createCallbackHost();
+export const { invoke, listCallbacks, getExecutionOptions, reportTrace, reportOutput } =
+  _defaultHost.imports;

package/shims/ip.js

@@ -0,0 +1,46 @@
+/**
+ * IP address parsing shared by the network transports.
+ */
+
+/** Bytes of an IPv4 address in dotted decimal, or null. */
+export function ipv4Bytes(addr) {
+  const parts = addr.split(".");
+  if (parts.length !== 4 || !parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255)) return null;
+  return parts.map(Number);
+}
+
+/** Bytes of an IPv6 address (with an optional dotted IPv4 tail), or null. */
+export function ipv6Bytes(addr) {
+  const tail = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(addr);
+  if (tail) {
+    const b = ipv4Bytes(tail[2]);
+    if (!b) return null;
+    addr = `${tail[1]}${((b[0] << 8) | b[1]).toString(16)}:${((b[2] << 8) | b[3]).toString(16)}`;
+  }
+  const halves = addr.split("::");
+  if (halves.length > 2) return null;
+  const groups = (s) => (s ? s.split(":") : []);
+  const head = groups(halves[0]);
+  const rest = halves.length === 2 ? groups(halves[1]) : [];
+  const fill = 8 - head.length - rest.length;
+  if (halves.length === 2 ? fill < 1 : fill !== 0) return null;
+  const all = [...head, ...Array(halves.length === 2 ? fill : 0).fill("0"), ...rest];
+  if (!all.every((g) => /^[0-9a-f]{1,4}$/i.test(g))) return null;
+  return all.flatMap((g) => [parseInt(g, 16) >> 8, parseInt(g, 16) & 255]);
+}
+
+/**
+ * The bytes of the IPv4 address that IPv6 address bytes `b` stand for on the
+ * wire, or null, like the Rust crate's `embedded_ipv4`: IPv4-mapped
+ * (`::ffff:a.b.c.d`), IPv4-compatible (`::a.b.c.d`), well-known-prefix NAT64
+ * (`64:ff9b::a.b.c.d`, RFC 6052), or the client address of a Teredo address
+ * (`2001::/32`, RFC 4380: the last 32 bits, inverted).
+ */
+export function embeddedIPv4(b) {
+  const zero = (from, to) => b.slice(from, to).every((x) => x === 0);
+  if (zero(0, 10) && b[10] === 255 && b[11] === 255) return b.slice(12);
+  const nat64 = b[0] === 0 && b[1] === 0x64 && b[2] === 0xff && b[3] === 0x9b;
+  if ((nat64 || zero(0, 4)) && zero(4, 12)) return b.slice(12);
+  if (b[0] === 0x20 && b[1] === 0x01 && b[2] === 0 && b[3] === 0) return b.slice(12).map((x) => ~x & 255);
+  return null;
+}