space-data-module-sdk 0.5.14 → 0.5.18

package/src/testing/index.d.ts

@@ -57,10 +57,266 @@ export interface ManifestHarnessPlan {
   scenarios: Array<HarnessInvokeScenario | HarnessRawScenario>;
 }
 
+export interface PublicationProtectionDemoAlignedType {
+  methodId: string | null;
+  portId: string | null;
+  setId: string | null;
+  schemaName: string | null;
+  fileIdentifier: string | null;
+  rootTypeName: string | null;
+  byteLength: number | null;
+  requiredAlignment: number | null;
+  hasFlatbufferFallback: boolean;
+}
+
+export interface PublicationProtectionDemoSummary {
+  manifest: PluginManifest;
+  recTrailer: {
+    fileIdentifier: string;
+    version: string | null;
+    recordCount: number;
+    recordStandards: Array<string | null>;
+    usesStandardsFlatbuffers: boolean;
+    records: Array<Record<string, unknown>>;
+  };
+  alignedBinaryContract: PublicationProtectionDemoAlignedType[];
+  signedOnly: {
+    artifactId: string;
+    encrypted: boolean;
+    trailer: PublicationProtectionDemoSummary["recTrailer"];
+    recordStandards: Array<string | null>;
+    pnm: {
+      fileName: string | null;
+      fileId: string | null;
+      cid: string | null;
+      hasSignature: boolean;
+      signatureType: string | null;
+      publishTimestamp: string | null;
+    } | null;
+    enc: null;
+    envelope: null;
+  };
+  encryptedDelivery: {
+    artifactId: string;
+    encrypted: boolean;
+    trailer: PublicationProtectionDemoSummary["recTrailer"];
+    recordStandards: Array<string | null>;
+    pnm: {
+      fileName: string | null;
+      fileId: string | null;
+      cid: string | null;
+      hasSignature: boolean;
+      signatureType: string | null;
+      publishTimestamp: string | null;
+    } | null;
+    enc: {
+      context: string | null;
+      rootType: string | null;
+      keyExchange: string | null;
+      symmetric: string | null;
+      keyDerivation: string | null;
+      nonceLength: number;
+      ephemeralPublicKeyLength: number;
+    } | null;
+    envelope: {
+      scheme: string | null;
+      hasEncRecord: boolean;
+      hasPnmRecord: boolean;
+    } | null;
+  };
+}
+
+export interface PluginInvokeProcessLaunchPlan {
+  command: string;
+  args: string[];
+  env?: Record<string, string | undefined>;
+  cwd?: 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 {
+  launchPlan: PluginInvokeProcessLaunchPlan;
+  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[];
+  }>;
+  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>;
+}
+
+export interface ModuleHarnessRuntimeDescriptor {
+  kind?: "process" | "wasmedge";
+  launchPlan?: PluginInvokeProcessLaunchPlan;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  wasmPath?: string;
+  wasmEdgeBinary?: string;
+  wasmEdgeRunnerBinary?: string;
+  enableThreads?: boolean;
+  hostProfile?: "runtime-host";
+  modules?: RuntimeHostTestModuleDefinition[];
+  defaultModuleId?: string;
+  metadata?: unknown;
+}
+
+export interface ModuleHarness {
+  runtime: ModuleHarnessRuntimeDescriptor & { kind: "process" | "wasmedge" };
+  launchPlan: PluginInvokeProcessLaunchPlan;
+  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[];
+  }>;
+  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>;
+}
+
+export interface WasmEdgeRunnerBuildPlan {
+  runnerSourcePath: string;
+  requestedIncludeDir: string;
+  wasmedgeIncludeDir: string;
+  wasmedgeLibDir: string;
+  wasmedgeSharedLibraryPath: string;
+  outputPath: string;
+  compilerCommand: string;
+  compilerArgs: string[];
+}
+
 export function describeCapabilityRuntimeSurface(
   capability: string,
 ): CapabilityRuntimeSurface;
 
+export function createPublicationProtectionDemoManifest(): PluginManifest;
+
+export function createPublicationProtectionDemoSummary(options?: {
+  manifest?: PluginManifest;
+  wasmBytes?: Uint8Array;
+  mnemonic?: string | null;
+  recipient?: {
+    publicKeyHex: string;
+    privateKeyHex: string;
+  };
+}): Promise<PublicationProtectionDemoSummary>;
+
 export function generateManifestHarnessPlan(options: {
   manifest: PluginManifest;
   includeOptionalInputs?: boolean;
@@ -84,3 +340,58 @@ export function materializeHarnessScenario(
 };
 
 export function serializeHarnessPlan(plan: ManifestHarnessPlan): unknown;
+
+export function buildWasmEdgeSpawnEnv(
+  baseEnv?: Record<string, string | undefined>,
+): Record<string, string | undefined>;
+
+export function resolveWasmEdgePluginLaunchPlan(options: {
+  wasmPath?: string;
+  wasmEdgeBinary?: string;
+  wasmEdgeRunnerBinary?: string;
+  enableThreads?: boolean;
+  invokeArgs?: string[];
+  env?: Record<string, string | undefined>;
+  hostProfile?: "runtime-host";
+}): PluginInvokeProcessLaunchPlan;
+
+export function createPluginInvokeProcessClient(options: {
+  launchPlan?: PluginInvokeProcessLaunchPlan;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string | undefined>;
+  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 createModuleHarness(options: {
+  runtime?: ModuleHarnessRuntimeDescriptor;
+} | ModuleHarnessRuntimeDescriptor): Promise<ModuleHarness>;
+
+export function resolveWasmEdgeRunnerSourcePath(): string;
+
+export function resolveWasmEdgeRunnerBuildPlan(options: {
+  outputPath: string;
+  wasmedgeIncludeDir?: string;
+  wasmedgeLibDir?: string;
+  output?: string;
+}): WasmEdgeRunnerBuildPlan;
+
+export function buildWasmEdgeEmscriptenPthreadRunner(options: {
+  outputPath: string;
+  wasmedgeIncludeDir?: string;
+  wasmedgeLibDir?: string;
+  output?: string;
+  cwd?: string;
+}): Promise<string>;

package/src/testing/index.js

@@ -1,6 +1,27 @@
+import { Buffer } from "node:buffer";
+
 import { encodePluginInvokeRequest } from "../invoke/codec.js";
 import { normalizeInvokeSurfaces } from "../invoke/index.js";
 import { selectPreferredPayloadTypeRef } from "../manifest/typeRefs.js";
+export {
+  createPublicationProtectionDemoManifest,
+  createPublicationProtectionDemoSummary,
+} from "./publicationProtectionDemo.js";
+export {
+  buildWasmEdgeSpawnEnv,
+  createPluginInvokeProcessClient,
+  createWasmEdgeStreamProcessClient,
+  resolveWasmEdgePluginLaunchPlan,
+} from "./processInvoke.js";
+export {
+  buildWasmEdgeEmscriptenPthreadRunner,
+  resolveWasmEdgeRunnerBuildPlan,
+  resolveWasmEdgeRunnerSourcePath,
+} from "./buildWasmEdgeRunner.js";
+export {
+  createModuleHarness,
+  resolveModuleHarnessLaunchPlan,
+} from "./moduleHarness.js";
 
 const CapabilitySurfaceMatrix = Object.freeze({
   logging: Object.freeze({

package/src/testing/moduleHarness.js

@@ -0,0 +1,163 @@
+import {
+  createPluginInvokeProcessClient,
+  createWasmEdgeStreamProcessClient,
+  resolveWasmEdgePluginLaunchPlan,
+} from "./processInvoke.js";
+
+function normalizeRuntimeDescriptor(options = {}) {
+  if (options.runtime && typeof options.runtime === "object") {
+    return options.runtime;
+  }
+  return options;
+}
+
+function isRuntimeHostProfile(runtime = {}) {
+  return (
+    String(runtime.hostProfile ?? "").trim().toLowerCase() === "runtime-host" ||
+    Array.isArray(runtime.modules) ||
+    (typeof runtime.defaultModuleId === "string" &&
+      runtime.defaultModuleId.trim().length > 0)
+  );
+}
+
+export function resolveModuleHarnessLaunchPlan(options = {}) {
+  const runtime = normalizeRuntimeDescriptor(options);
+  if (runtime.launchPlan && typeof runtime.launchPlan === "object") {
+    return runtime.launchPlan;
+  }
+
+  const kind = String(runtime.kind ?? "process").trim().toLowerCase();
+  if (kind === "wasmedge") {
+    return resolveWasmEdgePluginLaunchPlan(runtime);
+  }
+  if (kind === "process") {
+    if (typeof runtime.command !== "string" || runtime.command.trim().length === 0) {
+      throw new Error(
+        "resolveModuleHarnessLaunchPlan requires runtime.command for process runtimes.",
+      );
+    }
+    return {
+      command: runtime.command,
+      args: Array.isArray(runtime.args) ? runtime.args : [],
+      env: runtime.env,
+      cwd: runtime.cwd,
+    };
+  }
+
+  throw new Error(`Unsupported module harness runtime kind: ${kind}`);
+}
+
+export async function createModuleHarness(options = {}) {
+  const runtime = normalizeRuntimeDescriptor(options);
+  const kind = String(runtime.kind ?? "process").trim().toLowerCase();
+  const launchPlan = resolveModuleHarnessLaunchPlan(options);
+  const runtimeHost = isRuntimeHostProfile(runtime);
+  const processClient =
+    kind === "wasmedge"
+      ? await createWasmEdgeStreamProcessClient({ launchPlan })
+      : await createPluginInvokeProcessClient({ launchPlan });
+  const configuredModules = Array.isArray(runtime.modules) ? [...runtime.modules] : [];
+  if (
+    kind === "wasmedge" &&
+    runtimeHost &&
+    configuredModules.length === 0 &&
+    typeof runtime.wasmPath === "string" &&
+    runtime.wasmPath.trim().length > 0
+  ) {
+    configuredModules.push({
+      moduleId:
+        typeof runtime.defaultModuleId === "string" &&
+        runtime.defaultModuleId.trim().length > 0
+          ? runtime.defaultModuleId.trim()
+          : "default",
+      wasmPath: runtime.wasmPath,
+      metadata: runtime.metadata ?? null,
+    });
+  }
+
+  for (const moduleDefinition of configuredModules) {
+    await processClient.installModule(moduleDefinition);
+  }
+
+  let defaultModuleId =
+    typeof runtime.defaultModuleId === "string" && runtime.defaultModuleId.trim().length > 0
+      ? runtime.defaultModuleId.trim()
+      : configuredModules[0]?.moduleId ?? null;
+
+  return {
+    runtime: {
+      ...runtime,
+      kind,
+      hostProfile: runtimeHost ? "runtime-host" : runtime.hostProfile,
+    },
+    launchPlan,
+    invokeRaw(requestBytes) {
+      return processClient.invokeRaw(requestBytes);
+    },
+    invoke(request) {
+      if (runtimeHost) {
+        if (!defaultModuleId) {
+          throw new Error(
+            "Runtime-host invoke() requires an installed defaultModuleId.",
+          );
+        }
+        return processClient.invokeModule(defaultModuleId, request);
+      }
+      return processClient.invoke(request);
+    },
+    async installModule(definition) {
+      const installed = await processClient.installModule(definition);
+      if (
+        runtimeHost &&
+        (!defaultModuleId || defaultModuleId.trim().length === 0) &&
+        typeof installed?.moduleId === "string" &&
+        installed.moduleId.trim().length > 0
+      ) {
+        defaultModuleId = installed.moduleId.trim();
+      }
+      return installed;
+    },
+    listModules() {
+      return processClient.listModules();
+    },
+    async unloadModule(moduleId) {
+      const unloaded = await processClient.unloadModule(moduleId);
+      if (unloaded && moduleId === defaultModuleId) {
+        if (runtimeHost) {
+          const remainingModules = await processClient.listModules();
+          defaultModuleId = remainingModules[0]?.moduleId ?? null;
+        } else {
+          defaultModuleId = null;
+        }
+      }
+      return unloaded;
+    },
+    invokeModule(moduleId, request) {
+      return processClient.invokeModule(moduleId, request);
+    },
+    appendRow(options) {
+      return processClient.appendRow(options);
+    },
+    listRows(schemaFileId = null) {
+      return processClient.listRows(schemaFileId);
+    },
+    resolveRow(handle) {
+      return processClient.resolveRow(handle);
+    },
+    queryRows(sql) {
+      return processClient.queryRows(sql);
+    },
+    allocateRegion(options) {
+      return processClient.allocateRegion(options);
+    },
+    describeRegion(regionId) {
+      return processClient.describeRegion(regionId);
+    },
+    resolveRecord(query) {
+      return processClient.resolveRecord(query);
+    },
+    destroy() {
+      return processClient.destroy();
+    },
+  };
+}