space-data-module-sdk 0.8.4 → 0.8.5

package/src/host/sabHostcallChannel.js

@@ -0,0 +1,206 @@
+/**
+ * SharedArrayBuffer hostcall channel — the async in-WASM host bridge.
+ *
+ * Guest WASM modules issue synchronous `space_data_module_host.call`
+ * invocations, but browser host capabilities (http/ipfs/storage/pubsub/...)
+ * are async. This channel lets a guest running inside a Worker block while
+ * the async host operation resolves on the controlling thread:
+ *
+ *   worker (guest thread)                     controlling thread (host)
+ *   ─────────────────────                     ─────────────────────────
+ *   dispatch(op, params):
+ *     state ← PENDING
+ *     postRequest({operation, params}) ────▶  onmessage:
+ *     Atomics.wait(state == PENDING)            value = await dispatch(op, params)
+ *                                               write value envelope into SAB
+ *                                               state ← DONE; Atomics.notify
+ *     read + decode value envelope  ◀────────┘
+ *     return value (or throw on error status)
+ *
+ * The worker-side dispatch is synchronous, so it plugs directly into
+ * `createHostcallBridge({ dispatch })` (src/host/abi.js) — the existing
+ * envelope/error machinery is reused unchanged. `Atomics.wait` is illegal on
+ * the main thread, so the guest MUST run in a Worker (see
+ * src/testing/workerModuleHarness.js).
+ *
+ * Payloads cross the channel as hostcall value envelopes (hostcallWire.js),
+ * so binary leaves (Uint8Array) survive without base64/JSON round-trips.
+ */
+
+import {
+  decodeHostcallValueEnvelope,
+  encodeHostcallValueEnvelope,
+} from "./hostcallWire.js";
+
+// Int32 header slots at the front of the SharedArrayBuffer.
+const SLOT_STATE = 0;
+const SLOT_STATUS = 1;
+const SLOT_LENGTH = 2;
+const HEADER_INT32S = 4; // one reserved slot keeps the data region 16-byte aligned
+
+const STATE_IDLE = 0;
+const STATE_PENDING = 1;
+const STATE_DONE = 2;
+
+export const SAB_HOSTCALL_STATUS_OK = 0;
+export const SAB_HOSTCALL_STATUS_ERROR = 1;
+export const SAB_HOSTCALL_DATA_OFFSET = HEADER_INT32S * 4;
+export const DEFAULT_SAB_HOSTCALL_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+function assertSharedArrayBuffer(buffer) {
+  if (
+    typeof SharedArrayBuffer !== "function" ||
+    !(buffer instanceof SharedArrayBuffer)
+  ) {
+    throw new TypeError(
+      "SAB hostcall channel requires a SharedArrayBuffer (cross-origin isolation in browsers).",
+    );
+  }
+}
+
+function serializeChannelError(error, operation) {
+  return {
+    name: error?.name ?? "Error",
+    message: error?.message ?? String(error),
+    code: error?.code ?? null,
+    operation: error?.operation ?? operation ?? null,
+    capability: error?.capability ?? null,
+  };
+}
+
+/**
+ * Allocate the shared buffer backing one hostcall channel.
+ */
+export function createSabHostcallBuffer(options = {}) {
+  if (typeof SharedArrayBuffer !== "function") {
+    throw new Error(
+      "SharedArrayBuffer is unavailable; the async hostcall bridge requires it " +
+        "(browsers additionally require cross-origin isolation: COOP+COEP).",
+    );
+  }
+  const maxResponseBytes = Number.isInteger(options.maxResponseBytes)
+    ? options.maxResponseBytes
+    : DEFAULT_SAB_HOSTCALL_RESPONSE_BYTES;
+  if (maxResponseBytes <= 0) {
+    throw new RangeError("maxResponseBytes must be a positive integer.");
+  }
+  return new SharedArrayBuffer(SAB_HOSTCALL_DATA_OFFSET + maxResponseBytes);
+}
+
+/**
+ * Worker-side half: a synchronous dispatch(operation, params) that blocks on
+ * Atomics.wait until the controlling thread services the request.
+ *
+ * options.postRequest({ operation, params }) must deliver the request to the
+ * controlling thread (postMessage). params/results are structured values with
+ * Uint8Array leaves.
+ */
+export function createSabHostcallClientDispatch(options = {}) {
+  assertSharedArrayBuffer(options.buffer);
+  const postRequest = options.postRequest;
+  if (typeof postRequest !== "function") {
+    throw new TypeError(
+      "createSabHostcallClientDispatch requires a postRequest function.",
+    );
+  }
+  const timeoutMs =
+    Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+      ? options.timeoutMs
+      : 120_000;
+  const header = new Int32Array(options.buffer, 0, HEADER_INT32S);
+  const capacity = options.buffer.byteLength - SAB_HOSTCALL_DATA_OFFSET;
+
+  return function sabHostcallDispatch(operation, params = null) {
+    Atomics.store(header, SLOT_STATE, STATE_PENDING);
+    postRequest({ operation, params });
+    const outcome = Atomics.wait(header, SLOT_STATE, STATE_PENDING, timeoutMs);
+    if (outcome === "timed-out") {
+      Atomics.store(header, SLOT_STATE, STATE_IDLE);
+      throw new Error(
+        `Hostcall "${operation}" timed out after ${timeoutMs}ms waiting for the controlling thread.`,
+      );
+    }
+    const status = Atomics.load(header, SLOT_STATUS);
+    const length = Atomics.load(header, SLOT_LENGTH);
+    if (length < 0 || length > capacity) {
+      Atomics.store(header, SLOT_STATE, STATE_IDLE);
+      throw new RangeError(
+        `Hostcall "${operation}" response length ${length} exceeds channel capacity ${capacity}.`,
+      );
+    }
+    // Copy out of the SAB before decoding — decode keeps subarray views.
+    const bytes = new Uint8Array(length);
+    bytes.set(new Uint8Array(options.buffer, SAB_HOSTCALL_DATA_OFFSET, length));
+    Atomics.store(header, SLOT_STATE, STATE_IDLE);
+    const value = decodeHostcallValueEnvelope(bytes);
+    if (status !== SAB_HOSTCALL_STATUS_OK) {
+      const error = new Error(
+        value?.message ?? `Hostcall "${operation}" failed on the host thread.`,
+      );
+      error.name = value?.name ?? "Error";
+      error.code = value?.code ?? null;
+      error.operation = value?.operation ?? operation;
+      error.capability = value?.capability ?? null;
+      throw error;
+    }
+    return value;
+  };
+}
+
+/**
+ * Controlling-thread half: services one request at a time against an async
+ * dispatch (e.g. createAsyncHostDispatcher(host)) and wakes the worker.
+ */
+export function createSabHostcallServer(options = {}) {
+  assertSharedArrayBuffer(options.buffer);
+  const dispatch = options.dispatch;
+  if (typeof dispatch !== "function") {
+    throw new TypeError("createSabHostcallServer requires a dispatch function.");
+  }
+  const header = new Int32Array(options.buffer, 0, HEADER_INT32S);
+  const capacity = options.buffer.byteLength - SAB_HOSTCALL_DATA_OFFSET;
+  const data = new Uint8Array(options.buffer, SAB_HOSTCALL_DATA_OFFSET, capacity);
+
+  function complete(status, bytes) {
+    data.set(bytes, 0);
+    Atomics.store(header, SLOT_STATUS, status);
+    Atomics.store(header, SLOT_LENGTH, bytes.length);
+    Atomics.store(header, SLOT_STATE, STATE_DONE);
+    Atomics.notify(header, SLOT_STATE);
+  }
+
+  async function handleRequest(request = {}) {
+    const operation = request.operation;
+    let status = SAB_HOSTCALL_STATUS_OK;
+    let value;
+    try {
+      value = await dispatch(operation, request.params ?? null);
+      if (value === undefined) value = null;
+    } catch (error) {
+      status = SAB_HOSTCALL_STATUS_ERROR;
+      value = serializeChannelError(error, operation);
+    }
+    let bytes;
+    try {
+      bytes = encodeHostcallValueEnvelope(value);
+    } catch (error) {
+      status = SAB_HOSTCALL_STATUS_ERROR;
+      bytes = encodeHostcallValueEnvelope(serializeChannelError(error, operation));
+    }
+    if (bytes.length > capacity) {
+      status = SAB_HOSTCALL_STATUS_ERROR;
+      bytes = encodeHostcallValueEnvelope(
+        serializeChannelError(
+          new RangeError(
+            `Hostcall response (${bytes.length} bytes) exceeds the channel capacity (${capacity} bytes); ` +
+              "raise maxHostcallResponseBytes on the worker harness.",
+          ),
+          operation,
+        ),
+      );
+    }
+    complete(status, bytes);
+  }
+
+  return { handleRequest };
+}

package/src/host/timerDriver.js

@@ -0,0 +1,203 @@
+/**
+ * Browser cron/timer driver (WS6.3).
+ *
+ * The node runtime re-invokes a module's manifest TIMERS through
+ * plugin_invoke_stream on a schedule (Go plugins.Manager.scheduleCronMethods).
+ * This is the browser-side counterpart: it reads the module's TIMERS
+ * (decoded PLG manifest), schedules an interval per enabled timer, and
+ * invokes the timer's method through the harness invoke surface
+ * (createBrowserModuleHarness / createWorkerModuleHarness `invoke`, i.e.
+ * plugin_invoke_stream).
+ *
+ *   const driver = createModuleTimerDriver({
+ *     harness,                     // or invoke: (request) => Promise
+ *     manifestBytes,               // or timers: [...] / manifest: {...}
+ *     schedules: { "starlink-pull": { intervalMs: 1000 } },
+ *   });
+ *   driver.start();
+ *   ...
+ *   driver.stop();
+ *
+ * Semantics mirror the Go manager: one schedule per timer, runs are recorded
+ * ({trigger:"scheduled"|"manual", status:"ok"|"error"}), and runs of the same
+ * timer are serialized — a tick that lands while the previous invocation is
+ * still in flight is skipped (recorded as "skipped"). Unlike the Go manager,
+ * explicit schedule overrides are trusted (clamped only by minIntervalMs,
+ * default 1s) so tests and UIs can shorten long default cadences.
+ */
+
+// Import the codec leaf, not manifest/index.js — the index pulls
+// embeddedManifest.js (node:fs) and would break browser bundles.
+import { decodePluginManifest } from "../manifest/codec.js";
+
+const DEFAULT_MIN_INTERVAL_MS = 1_000;
+const DEFAULT_MAX_RUN_HISTORY = 50;
+
+function toIntervalMs(value) {
+  if (typeof value === "bigint") return Number(value);
+  const n = Number(value ?? 0);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function normalizeTimer(timer) {
+  const timerId = String(timer?.timerId ?? timer?.timer_id ?? "").trim();
+  const methodId = String(timer?.methodId ?? timer?.method_id ?? "").trim();
+  if (!timerId || !methodId) return null;
+  return {
+    timerId,
+    methodId,
+    defaultIntervalMs: toIntervalMs(
+      timer.defaultIntervalMs ?? timer.default_interval_ms ?? 0,
+    ),
+    description: timer.description ?? "",
+  };
+}
+
+function resolveTimers(options) {
+  if (Array.isArray(options.timers)) {
+    return options.timers.map(normalizeTimer).filter(Boolean);
+  }
+  const manifest =
+    options.manifest ??
+    (options.manifestBytes ? decodePluginManifest(options.manifestBytes) : null);
+  const timers = Array.isArray(manifest?.timers) ? manifest.timers : [];
+  return timers.map(normalizeTimer).filter(Boolean);
+}
+
+export function createModuleTimerDriver(options = {}) {
+  const invoke =
+    typeof options.invoke === "function"
+      ? options.invoke
+      : typeof options.harness?.invoke === "function"
+        ? (request) => options.harness.invoke(request)
+        : null;
+  if (!invoke) {
+    throw new TypeError(
+      "createModuleTimerDriver requires an invoke function or a harness with invoke().",
+    );
+  }
+  const timers = resolveTimers(options);
+  const schedules =
+    options.schedules && typeof options.schedules === "object"
+      ? options.schedules
+      : {};
+  const minIntervalMs = Number.isFinite(options.minIntervalMs)
+    ? Math.max(1, options.minIntervalMs)
+    : DEFAULT_MIN_INTERVAL_MS;
+  const maxRunHistory = Number.isInteger(options.maxRunHistory)
+    ? options.maxRunHistory
+    : DEFAULT_MAX_RUN_HISTORY;
+  const setIntervalImpl = options.setIntervalImpl ?? globalThis.setInterval.bind(globalThis);
+  const clearIntervalImpl =
+    options.clearIntervalImpl ?? globalThis.clearInterval.bind(globalThis);
+  const now = typeof options.now === "function" ? options.now : () => Date.now();
+  const onRun = typeof options.onRun === "function" ? options.onRun : null;
+
+  const state = new Map(); // timerId -> { timer, intervalMs, enabled, handle, inFlight, runs }
+  for (const timer of timers) {
+    const override = schedules[timer.timerId] ?? {};
+    const enabled = override.enabled !== false;
+    const requested = toIntervalMs(override.intervalMs ?? timer.defaultIntervalMs);
+    const intervalMs = Math.max(minIntervalMs, requested);
+    state.set(timer.timerId, {
+      timer,
+      intervalMs,
+      enabled,
+      handle: null,
+      inFlight: false,
+      runs: [],
+    });
+  }
+
+  function record(entry, run) {
+    entry.runs.push(run);
+    if (entry.runs.length > maxRunHistory) {
+      entry.runs.splice(0, entry.runs.length - maxRunHistory);
+    }
+    if (onRun) onRun(run);
+  }
+
+  async function fire(entry, trigger) {
+    if (entry.inFlight) {
+      record(entry, {
+        timerId: entry.timer.timerId,
+        methodId: entry.timer.methodId,
+        trigger,
+        status: "skipped",
+        startedAt: now(),
+        finishedAt: now(),
+        message: "previous run still in flight",
+      });
+      return null;
+    }
+    entry.inFlight = true;
+    const run = {
+      timerId: entry.timer.timerId,
+      methodId: entry.timer.methodId,
+      trigger,
+      status: "running",
+      startedAt: now(),
+    };
+    try {
+      const response = await invoke({ methodId: entry.timer.methodId, inputs: [] });
+      run.status = "ok";
+      run.finishedAt = now();
+      return response;
+    } catch (error) {
+      run.status = "error";
+      run.message = error?.message ?? String(error);
+      run.finishedAt = now();
+      return null;
+    } finally {
+      entry.inFlight = false;
+      record(entry, run);
+    }
+  }
+
+  let started = false;
+
+  return {
+    listTimers() {
+      return [...state.values()].map((entry) => ({
+        timerId: entry.timer.timerId,
+        methodId: entry.timer.methodId,
+        description: entry.timer.description,
+        defaultIntervalMs: entry.timer.defaultIntervalMs,
+        intervalMs: entry.intervalMs,
+        enabled: entry.enabled,
+        scheduled: entry.handle !== null,
+      }));
+    },
+    runHistory(timerId) {
+      const entry = state.get(String(timerId ?? "").trim());
+      return entry ? entry.runs.map((run) => ({ ...run })) : [];
+    },
+    start() {
+      if (started) return this.listTimers();
+      started = true;
+      for (const entry of state.values()) {
+        if (!entry.enabled) continue;
+        entry.handle = setIntervalImpl(() => {
+          void fire(entry, "scheduled");
+        }, entry.intervalMs);
+      }
+      return this.listTimers();
+    },
+    async runNow(timerId) {
+      const entry = state.get(String(timerId ?? "").trim());
+      if (!entry) {
+        throw new Error(`Unknown timer: ${timerId}`);
+      }
+      return fire(entry, "manual");
+    },
+    stop() {
+      for (const entry of state.values()) {
+        if (entry.handle !== null) {
+          clearIntervalImpl(entry.handle);
+          entry.handle = null;
+        }
+      }
+      started = false;
+    },
+  };
+}

package/src/host/wasiShim.js

@@ -5,10 +5,14 @@
  * WASI modules (the same .wasm that runs in WasmEdge) can be instantiated
  * directly in the browser via WebAssembly.instantiate().
  *
- * Covers the 11 imports observed across all SDN plugin standalone builds:
+ * Covers the preview1 imports observed across SDN plugin standalone builds:
  *   clock_time_get, fd_write, fd_read, fd_close, fd_seek, fd_fdstat_get,
+ *   fd_fdstat_set_flags, fd_prestat_get, fd_prestat_dir_name, path_open,
  *   environ_sizes_get, environ_get, proc_exit, args_get, args_sizes_get,
  *   random_get
+ *
+ * No filesystem is exposed: prestat/path_open report no preopened
+ * directories, so wasi-libc file APIs fail cleanly inside the guest.
  */
 
 const ERRNO_SUCCESS = 0;
@@ -156,6 +160,28 @@ export function createBrowserWasiShim(options = {}) {
     return ERRNO_SUCCESS;
   }
 
+  function fd_fdstat_set_flags(fd, _flags) {
+    if (fd <= 2) return ERRNO_SUCCESS;
+    return ERRNO_BADF;
+  }
+
+  // This browser shim exposes no ambient preopened directories. Toolchains
+  // commonly probe these preview1 calls during startup; returning BADF is
+  // the fail-closed WASI result and lets the guest continue without filesystem
+  // authority.
+  function fd_prestat_get(_fd, _bufPtr) {
+    return ERRNO_BADF;
+  }
+
+  function fd_prestat_dir_name(_fd, _pathPtr, _pathLen) {
+    return ERRNO_BADF;
+  }
+
+  function path_open() {
+    return ERRNO_BADF;
+  }
+
+
   function environ_sizes_get(countPtr, bufSizePtr) {
     const dv = view();
     dv.setUint32(countPtr, encodedEnvEntries.length, true);
@@ -223,6 +249,15 @@ export function createBrowserWasiShim(options = {}) {
     throw new WasiExitError(code);
   }
 
+  // wasm32-wasip1-threads (isomorphic-pthreads) modules import sched_yield —
+  // pthread spin/backoff loops call it. A cooperative no-op (yield to the
+  // engine) is the correct browser/Node semantics: real preemption is the
+  // host's job. Present on every shim so a threaded artifact instantiates
+  // (a missing import would fail instantiation for the whole module).
+  function sched_yield() {
+    return ERRNO_SUCCESS;
+  }
+
   // --- Output helpers ---
 
   function flushOutput() {
@@ -265,12 +300,17 @@ export function createBrowserWasiShim(options = {}) {
         fd_close,
         fd_seek,
         fd_fdstat_get,
+        fd_fdstat_set_flags,
+        fd_prestat_get,
+        fd_prestat_dir_name,
+        path_open,
         environ_sizes_get,
         environ_get,
         args_sizes_get,
         args_get,
         random_get,
         proc_exit,
+        sched_yield,
       },
     },
     setMemory,

package/src/host/wasiThreadBrowserWorker.mjs

@@ -0,0 +1,48 @@
+import { createWasiThreadWorkerRuntime } from "./wasiThreadWorkerRuntime.js";
+
+let wasmModule = null;
+let memory = null;
+let hostcallChannel = null;
+let runtime = null;
+
+self.onmessage = (event) => {
+  const message = event.data ?? {};
+  if (message.t === "probe") {
+    wasmModule = message.wasmModule;
+    memory = message.memory;
+    hostcallChannel = message.hostcallChannel ?? null;
+    try {
+      runtime = createWasiThreadWorkerRuntime({
+        wasmModule,
+        memory,
+        hostcallChannel,
+      });
+      runtime.instantiate();
+      self.postMessage({ t: "ready", ok: true });
+    } catch (error) {
+      runtime?.close();
+      runtime = null;
+      self.postMessage({
+        t: "ready",
+        ok: false,
+        error: String(error?.message ?? error),
+      });
+    }
+    return;
+  }
+  if (message.t !== "run") return;
+
+  try {
+    const instance = runtime.instantiate();
+    instance.exports.wasi_thread_start(message.tid, message.startArg);
+  } catch (error) {
+    if (!(error && error.name === "WasiExitError")) {
+      self.postMessage({
+        t: "error",
+        tid: message.tid,
+        error: String(error?.message ?? error),
+      });
+    }
+  }
+  self.postMessage({ t: "exit", tid: message.tid });
+};