space-data-module-sdk 0.5.15 → 0.5.19

package/src/testing/browserModuleHarness.js

@@ -0,0 +1,275 @@
+/**
+ * Browser-side module harness.
+ *
+ * Loads the same standalone WASI .wasm artifact that WasmEdge runs,
+ * instantiating it in the browser with the WASI shim + optional sdn_host
+ * bridge. Matches the createModuleHarness() API surface.
+ *
+ * Supports two invoke paths:
+ *   1. "direct" — call plugin_invoke_stream(ptr, len, &outLen) and read
+ *      the FlatBuffer response from WASM memory.
+ *   2. "command" — call _start() with stdin piped via WASI shim, read
+ *      stdout for the response bytes.
+ */
+
+import { createBrowserWasiShim, WasiExitError } from "../host/wasiShim.js";
+import { createBrowserHost } from "../host/browserHost.js";
+import {
+  createJsonHostcallBridge,
+  createNodeHostSyncDispatcher,
+  DEFAULT_HOSTCALL_IMPORT_MODULE,
+} from "../host/abi.js";
+import {
+  DefaultInvokeExports,
+  DefaultManifestExports,
+} from "../runtime/constants.js";
+import {
+  encodePluginInvokeRequest,
+  decodePluginInvokeResponse,
+} from "../invoke/codec.js";
+
+/**
+ * Detect artifact profile from WebAssembly.Module imports.
+ * Returns "standalone" (WASI-only), "sdn-abi" (WASI + sdn_host),
+ * or "emscripten" (env.* with invoke trampolines).
+ */
+export function detectArtifactProfile(wasmModule) {
+  const imports = WebAssembly.Module.imports(wasmModule);
+  const moduleNames = new Set(imports.map((i) => i.module));
+
+  if (moduleNames.has("env")) {
+    const envImports = imports.filter((i) => i.module === "env");
+    const hasInvokeTrampolines = envImports.some((i) => i.name.startsWith("invoke_"));
+    const hasPthreads = envImports.some(
+      (i) => i.name.includes("pthread") || i.name.includes("thread"),
+    );
+    if (hasInvokeTrampolines || hasPthreads) {
+      return "emscripten";
+    }
+  }
+
+  if (moduleNames.has(DEFAULT_HOSTCALL_IMPORT_MODULE)) {
+    return "sdn-abi";
+  }
+
+  if (moduleNames.has("wasi_snapshot_preview1") || moduleNames.has("wasi_unstable")) {
+    return "standalone";
+  }
+
+  return "unknown";
+}
+
+async function compileWasmModule(source) {
+  if (source instanceof WebAssembly.Module) {
+    return source;
+  }
+  if (source instanceof Response) {
+    return WebAssembly.compileStreaming(source);
+  }
+  if (typeof source === "string") {
+    return WebAssembly.compileStreaming(fetch(source));
+  }
+  const bytes = source instanceof ArrayBuffer ? new Uint8Array(source) : source;
+  return WebAssembly.compile(bytes);
+}
+
+async function instantiateBrowserModule(options = {}) {
+  const wasi = createBrowserWasiShim({
+    args: options.args ?? [],
+    env: options.env ?? {},
+    stdinBytes: options.stdinBytes ?? new Uint8Array(),
+    logOutput: options.logOutput === true,
+    performance: options.performance,
+  });
+  const importObject = { ...wasi.imports };
+  const moduleImports = WebAssembly.Module.imports(options.wasmModule);
+  const needsHostBridge = moduleImports.some(
+    (entry) => entry.module === DEFAULT_HOSTCALL_IMPORT_MODULE,
+  );
+
+  let instance = null;
+  let bridge = null;
+  if (needsHostBridge) {
+    const dispatch = createNodeHostSyncDispatcher(options.host);
+    bridge = createJsonHostcallBridge({
+      dispatch,
+      getMemory: () => instance.exports.memory,
+    });
+    Object.assign(importObject, bridge.imports);
+  }
+
+  instance = await WebAssembly.instantiate(options.wasmModule, importObject);
+  if (instance.exports.memory) {
+    wasi.setMemory(instance.exports.memory);
+  }
+  if (instance.exports._initialize) {
+    instance.exports._initialize();
+  }
+
+  return {
+    instance,
+    bridge,
+    wasi,
+  };
+}
+
+/**
+ * Create a browser-side module harness for a standalone WASI artifact.
+ *
+ * @param {Object} options
+ * @param {Uint8Array|ArrayBuffer|Response|string} options.wasmSource
+ *   WASM bytes, ArrayBuffer, fetch Response, or URL string.
+ * @param {Object} [options.host] - BrowserHost instance (created if omitted).
+ * @param {string[]} [options.args] - WASI args passed to the module.
+ * @param {Object} [options.env] - WASI environment variables.
+ * @param {string} [options.surface] - "direct" or "command" (default: auto-detect).
+ */
+export async function createBrowserModuleHarness(options = {}) {
+  const host = options.host ?? createBrowserHost(options.hostOptions);
+  const wasmModule = await compileWasmModule(options.wasmSource);
+
+  const profile = detectArtifactProfile(wasmModule);
+  const moduleExports = WebAssembly.Module.exports(wasmModule);
+  const exportNames = new Set(moduleExports.map((e) => e.name));
+
+  const hasDirectInvoke = exportNames.has(DefaultInvokeExports.invokeSymbol);
+  const hasCommand = exportNames.has(DefaultInvokeExports.commandSymbol);
+  const surface =
+    options.surface ?? (hasDirectInvoke ? "direct" : hasCommand ? "command" : "direct");
+  if (profile === "emscripten") {
+    throw new Error(
+      "Browser harness only supports standalone WASI or sdn_host artifacts. " +
+        'Compile shared browser/WasmEdge modules with runtimeTargets: ["browser", "wasmedge"] ' +
+        'or override threadModel to "single-thread".',
+    );
+  }
+
+  const activeContext = await instantiateBrowserModule({
+    wasmModule,
+    host,
+    args: options.args,
+    env: options.env,
+    performance: options.performance ?? host?.performance,
+    logOutput: options.logOutput === true,
+  });
+  const { instance, bridge, wasi } = activeContext;
+
+  // --- Invoke helpers ---
+  function invokeDirectRaw(requestBytes) {
+    const alloc = instance.exports[DefaultInvokeExports.allocSymbol];
+    const free = instance.exports[DefaultInvokeExports.freeSymbol];
+    const invokeStream = instance.exports[DefaultInvokeExports.invokeSymbol];
+    const memory = instance.exports.memory;
+    if (
+      typeof alloc !== "function" ||
+      typeof free !== "function" ||
+      typeof invokeStream !== "function" ||
+      !memory
+    ) {
+      throw new Error(
+        "Direct browser invoke requires plugin_alloc, plugin_free, plugin_invoke_stream, and memory exports.",
+      );
+    }
+    const reqLen = requestBytes.length;
+    const reqPtr = alloc(reqLen);
+    if (!reqPtr) throw new Error("plugin_alloc returned null for request.");
+
+    new Uint8Array(memory.buffer, reqPtr, reqLen).set(requestBytes);
+
+    // Allocate space for the response length output
+    const outLenPtr = alloc(4);
+    if (!outLenPtr) throw new Error("plugin_alloc returned null for response length.");
+
+    new DataView(memory.buffer).setUint32(outLenPtr, 0, true);
+
+    const resPtr = invokeStream(reqPtr, reqLen, outLenPtr);
+    const resLen = new DataView(memory.buffer).getUint32(outLenPtr, true);
+
+    free(reqPtr, reqLen);
+    free(outLenPtr, 4);
+
+    if (!resPtr || !resLen) {
+      throw new Error("plugin_invoke_stream returned null response.");
+    }
+
+    const responseBytes = new Uint8Array(memory.buffer, resPtr, resLen).slice();
+    free(resPtr, resLen);
+    return responseBytes;
+  }
+
+  async function invokeCommandRaw(stdinBytes) {
+    const commandContext = await instantiateBrowserModule({
+      wasmModule,
+      host,
+      args: options.args,
+      env: options.env,
+      stdinBytes,
+      performance: options.performance ?? host?.performance,
+      logOutput: false,
+    });
+    try {
+      const commandExport = commandContext.instance.exports[DefaultInvokeExports.commandSymbol];
+      if (typeof commandExport !== "function") {
+        throw new Error(
+          `Command-surface browser invoke requires the ${DefaultInvokeExports.commandSymbol} export.`,
+        );
+      }
+      commandExport();
+    } catch (error) {
+      if (!(error instanceof WasiExitError) || error.code !== 0) {
+        throw error;
+      }
+    }
+    return commandContext.wasi.stdout;
+  }
+
+  // --- Public API ---
+
+  async function invokeRaw(requestBytes) {
+    if (surface === "command") {
+      return invokeCommandRaw(requestBytes);
+    }
+    return invokeDirectRaw(requestBytes);
+  }
+
+  async function invoke(request) {
+    const requestBytes = encodePluginInvokeRequest(request);
+    const responseBytes = await invokeRaw(requestBytes);
+    return decodePluginInvokeResponse(responseBytes);
+  }
+
+  function readManifest() {
+    const getBytesExport =
+      instance.exports[DefaultManifestExports.pluginBytesSymbol];
+    const getSizeExport =
+      instance.exports[DefaultManifestExports.pluginSizeSymbol];
+    if (!getBytesExport || !getSizeExport) return null;
+
+    const ptr = getBytesExport();
+    const size = getSizeExport();
+    if (!ptr || !size) return null;
+
+    return new Uint8Array(instance.exports.memory.buffer, ptr, size).slice();
+  }
+
+  function destroy() {
+    wasi.flushOutput();
+  }
+
+  return {
+    runtime: {
+      kind: "browser",
+      profile,
+      surface,
+    },
+    instance,
+    module: wasmModule,
+    host,
+    bridge,
+    wasi,
+    invoke,
+    invokeRaw,
+    readManifest,
+    destroy,
+  };
+}

package/src/testing/buildWasmEdgeRunner.js

@@ -1,5 +1,6 @@
 import { accessSync, existsSync } from "node:fs";
 import { execFile } from "node:child_process";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
@@ -63,12 +64,50 @@ export function resolveWasmEdgeRunnerSourcePath() {
   );
 }
 
+function resolveDefaultWasmEdgeInstall() {
+  const home = os.homedir();
+  const candidates = [
+    {
+      includeDir: path.join(home, ".wasmedge", "include"),
+      libDir: path.join(home, ".wasmedge", "lib"),
+    },
+    {
+      includeDir: "/opt/homebrew/include",
+      libDir: "/opt/homebrew/opt/wasmedge/lib",
+    },
+    {
+      includeDir: "/usr/local/include",
+      libDir: "/usr/local/lib",
+    },
+  ];
+  for (const candidate of candidates) {
+    const header = path.join(
+      candidate.includeDir,
+      "wasmedge",
+      "enum_configure.h",
+    );
+    const library = path.join(
+      candidate.libDir,
+      resolveWasmEdgeSharedLibraryFilename(),
+    );
+    if (existsSync(header) && existsSync(library)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
 export function resolveWasmEdgeRunnerBuildPlan(options = {}) {
+  const detectedInstall = resolveDefaultWasmEdgeInstall();
   const requestedIncludeDir = normalizeResolvedPath(
-    options.wasmedgeIncludeDir ?? process.env.WASMEDGE_INCLUDE_DIR,
+    options.wasmedgeIncludeDir ??
+      process.env.WASMEDGE_INCLUDE_DIR ??
+      detectedInstall?.includeDir,
   );
   const wasmedgeLibDir = normalizeResolvedPath(
-    options.wasmedgeLibDir ?? process.env.WASMEDGE_LIB_DIR,
+    options.wasmedgeLibDir ??
+      process.env.WASMEDGE_LIB_DIR ??
+      detectedInstall?.libDir,
   );
   const outputPath = normalizeResolvedPath(
     options.outputPath ?? options.output,

package/src/testing/index.d.ts

@@ -131,7 +131,55 @@ export interface PluginInvokeProcessLaunchPlan {
   args: string[];
   env?: Record<string, string | undefined>;
   cwd?: string;
-  wasmPath?: string;
+  wasmPath?: string | null;
+  hostProfile?: "runtime-host";
+}
+
+export interface RuntimeHostTestModuleDefinition {
+  moduleId: string;
+  wasmPath?: string | null;
+  metadata?: unknown;
+  [key: string]: unknown;
+}
+
+export interface RuntimeHostInstalledModule {
+  moduleId: string;
+  metadata: unknown;
+  methodIds: string[];
+}
+
+export interface RuntimeHostRowHandle {
+  schemaFileId: string;
+  rowId: number;
+}
+
+export interface RuntimeHostRowView {
+  handle: RuntimeHostRowHandle;
+  payload: unknown;
+}
+
+export interface RuntimeHostRowQueryResult {
+  columns: string[];
+  rows: unknown[][];
+  rowCount: number;
+}
+
+export interface RuntimeHostRegionDescriptor {
+  regionId: number;
+  layoutId: string;
+  recordByteLength: number;
+  alignment: number;
+  recordCount: number;
+}
+
+export interface RuntimeHostRegionRecord {
+  regionId: number;
+  recordIndex: number;
+  layoutId: string;
+  recordByteLength: number;
+  alignment: number;
+  byteLength: number;
+  bytes: Uint8Array;
 }
 
 export interface PluginInvokeProcessClient {
@@ -140,12 +188,42 @@ export interface PluginInvokeProcessClient {
   invoke(request: {
     methodId?: string | null;
     inputs?: HarnessInputFrame[];
+  }): Promise<{
+      statusCode: number;
+      errorCode?: string | null;
+      errorMessage?: string | null;
+      outputs: HarnessInputFrame[];
+  }>;
+  installModule(definition: RuntimeHostTestModuleDefinition): Promise<RuntimeHostInstalledModule>;
+  listModules(): Promise<RuntimeHostInstalledModule[]>;
+  unloadModule(moduleId: string): Promise<boolean>;
+  invokeModule(requestModuleId: string, request: {
+    methodId?: string | null;
+    inputs?: HarnessInputFrame[];
   }): Promise<{
     statusCode: number;
     errorCode?: string | null;
     errorMessage?: string | null;
     outputs: HarnessInputFrame[];
   }>;
+  appendRow(options: {
+    schemaFileId: string;
+    payload?: unknown;
+  }): Promise<RuntimeHostRowHandle>;
+  listRows(schemaFileId?: string | null): Promise<RuntimeHostRowView[]>;
+  resolveRow(handle: RuntimeHostRowHandle): Promise<RuntimeHostRowView | null>;
+  queryRows(sql: string): Promise<RuntimeHostRowQueryResult>;
+  allocateRegion(options: {
+    layoutId: string;
+    recordByteLength: number;
+    alignment?: number;
+    initialRecords?: Array<Uint8Array | ArrayBuffer | ArrayBufferView | null | undefined>;
+  }): Promise<RuntimeHostRegionDescriptor>;
+  describeRegion(regionId: number): Promise<RuntimeHostRegionDescriptor | null>;
+  resolveRecord(query: {
+    regionId: number;
+    recordIndex: number;
+  }): Promise<RuntimeHostRegionRecord | null>;
   destroy(): Promise<void>;
 }
 
@@ -160,6 +238,10 @@ export interface ModuleHarnessRuntimeDescriptor {
   wasmEdgeBinary?: string;
   wasmEdgeRunnerBinary?: string;
   enableThreads?: boolean;
+  hostProfile?: "runtime-host";
+  modules?: RuntimeHostTestModuleDefinition[];
+  defaultModuleId?: string;
+  metadata?: unknown;
 }
 
 export interface ModuleHarness {
@@ -169,12 +251,42 @@ export interface ModuleHarness {
   invoke(request: {
     methodId?: string | null;
     inputs?: HarnessInputFrame[];
+  }): Promise<{
+      statusCode: number;
+      errorCode?: string | null;
+      errorMessage?: string | null;
+      outputs: HarnessInputFrame[];
+  }>;
+  installModule(definition: RuntimeHostTestModuleDefinition): Promise<RuntimeHostInstalledModule>;
+  listModules(): Promise<RuntimeHostInstalledModule[]>;
+  unloadModule(moduleId: string): Promise<boolean>;
+  invokeModule(moduleId: string, request: {
+    methodId?: string | null;
+    inputs?: HarnessInputFrame[];
   }): Promise<{
     statusCode: number;
     errorCode?: string | null;
     errorMessage?: string | null;
     outputs: HarnessInputFrame[];
   }>;
+  appendRow(options: {
+    schemaFileId: string;
+    payload?: unknown;
+  }): Promise<RuntimeHostRowHandle>;
+  listRows(schemaFileId?: string | null): Promise<RuntimeHostRowView[]>;
+  resolveRow(handle: RuntimeHostRowHandle): Promise<RuntimeHostRowView | null>;
+  queryRows(sql: string): Promise<RuntimeHostRowQueryResult>;
+  allocateRegion(options: {
+    layoutId: string;
+    recordByteLength: number;
+    alignment?: number;
+    initialRecords?: Array<Uint8Array | ArrayBuffer | ArrayBufferView | null | undefined>;
+  }): Promise<RuntimeHostRegionDescriptor>;
+  describeRegion(regionId: number): Promise<RuntimeHostRegionDescriptor | null>;
+  resolveRecord(query: {
+    regionId: number;
+    recordIndex: number;
+  }): Promise<RuntimeHostRegionRecord | null>;
   destroy(): Promise<void>;
 }
 
@@ -205,6 +317,40 @@ export function createPublicationProtectionDemoSummary(options?: {
   };
 }): Promise<PublicationProtectionDemoSummary>;
 
+export interface BrowserModuleHarness {
+  runtime: {
+    kind: "browser";
+    profile: string;
+    surface: string;
+  };
+  instance: WebAssembly.Instance;
+  module: WebAssembly.Module;
+  host: unknown;
+  bridge: unknown;
+  wasi: {
+    imports: Record<string, Record<string, (...args: number[]) => number>>;
+    setMemory(mem: { buffer: ArrayBuffer | SharedArrayBuffer }): void;
+    getMemory(): { buffer: ArrayBuffer | SharedArrayBuffer } | null;
+    flushOutput(): void;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+  };
+  invokeRaw(
+    requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView,
+  ): Promise<Uint8Array>;
+  invoke(request: {
+    methodId?: string | null;
+    inputs?: HarnessInputFrame[];
+  }): Promise<{
+    statusCode: number;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    outputs: HarnessInputFrame[];
+  }>;
+  readManifest(): Uint8Array | null;
+  destroy(): void;
+}
+
 export function generateManifestHarnessPlan(options: {
   manifest: PluginManifest;
   includeOptionalInputs?: boolean;
@@ -234,12 +380,13 @@ export function buildWasmEdgeSpawnEnv(
 ): Record<string, string | undefined>;
 
 export function resolveWasmEdgePluginLaunchPlan(options: {
-  wasmPath: string;
+  wasmPath?: string;
   wasmEdgeBinary?: string;
   wasmEdgeRunnerBinary?: string;
   enableThreads?: boolean;
   invokeArgs?: string[];
   env?: Record<string, string | undefined>;
+  hostProfile?: "runtime-host";
 }): PluginInvokeProcessLaunchPlan;
 
 export function createPluginInvokeProcessClient(options: {
@@ -250,10 +397,34 @@ export function createPluginInvokeProcessClient(options: {
   cwd?: string;
 }): Promise<PluginInvokeProcessClient>;
 
+export function createWasmEdgeStreamProcessClient(options: {
+  launchPlan?: PluginInvokeProcessLaunchPlan;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+}): Promise<PluginInvokeProcessClient>;
+
 export function resolveModuleHarnessLaunchPlan(options: {
   runtime?: ModuleHarnessRuntimeDescriptor;
 } | ModuleHarnessRuntimeDescriptor): PluginInvokeProcessLaunchPlan;
 
+export function detectArtifactProfile(wasmModule: WebAssembly.Module): string;
+
+export function createBrowserModuleHarness(options?: {
+  wasmSource: Uint8Array | ArrayBuffer | string | WebAssembly.Module | unknown;
+  host?: unknown;
+  hostOptions?: unknown;
+  args?: string[];
+  env?: Record<string, string>;
+  surface?: "direct" | "command";
+  performance?: {
+    now(): number;
+    timeOrigin: number;
+  };
+  logOutput?: boolean;
+}): Promise<BrowserModuleHarness>;
+
 export function createModuleHarness(options: {
   runtime?: ModuleHarnessRuntimeDescriptor;
 } | ModuleHarnessRuntimeDescriptor): Promise<ModuleHarness>;

package/src/testing/index.js

@@ -7,9 +7,14 @@ export {
   createPublicationProtectionDemoManifest,
   createPublicationProtectionDemoSummary,
 } from "./publicationProtectionDemo.js";
+export {
+  createBrowserModuleHarness,
+  detectArtifactProfile,
+} from "./browserModuleHarness.js";
 export {
   buildWasmEdgeSpawnEnv,
   createPluginInvokeProcessClient,
+  createWasmEdgeStreamProcessClient,
   resolveWasmEdgePluginLaunchPlan,
 } from "./processInvoke.js";
 export {