space-data-module-sdk 0.5.15 → 0.5.18

package/src/runtime-host/flatsqlRuntimeStore.js

@@ -0,0 +1,217 @@
+import { DirectAccessor, FlatSQLDatabase } from "flatsql";
+
+const RUNTIME_ROW_TABLE = "RuntimeHostRow";
+const RUNTIME_ROW_SCHEMA = `
+table RuntimeHostRow {
+  schemaFileId: string;
+  rowId: ulong;
+  payloadJson: string;
+}
+`;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function clonePayload(payload) {
+  if (payload === null || payload === undefined) {
+    return payload ?? null;
+  }
+  if (typeof structuredClone === "function") {
+    return structuredClone(payload);
+  }
+  if (ArrayBuffer.isView(payload)) {
+    return payload.slice(0);
+  }
+  if (payload instanceof ArrayBuffer) {
+    return payload.slice(0);
+  }
+  if (typeof payload === "object") {
+    return JSON.parse(JSON.stringify(payload));
+  }
+  return payload;
+}
+
+function normalizeSchemaFileId(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError("schemaFileId must be a non-empty string");
+  }
+  return value.trim();
+}
+
+function normalizeRowHandle(handle) {
+  if (!handle || typeof handle !== "object") {
+    throw new TypeError("row handle is required");
+  }
+  const schemaFileId = normalizeSchemaFileId(handle.schemaFileId);
+  const rowId = Number(handle.rowId);
+  if (!Number.isInteger(rowId) || rowId <= 0) {
+    throw new TypeError("rowId must be a positive integer");
+  }
+  return { schemaFileId, rowId };
+}
+
+function escapeSqlStringLiteral(value) {
+  return String(value).replaceAll("'", "''");
+}
+
+function serializePayload(payload) {
+  if (payload === null || payload === undefined) {
+    return {
+      kind: "json",
+      value: null,
+    };
+  }
+  if (ArrayBuffer.isView(payload)) {
+    return {
+      kind: "bytes",
+      bytes: Array.from(
+        new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength),
+      ),
+    };
+  }
+  if (payload instanceof ArrayBuffer) {
+    return {
+      kind: "bytes",
+      bytes: Array.from(new Uint8Array(payload)),
+    };
+  }
+  return {
+    kind: "json",
+    value: clonePayload(payload),
+  };
+}
+
+function deserializePayload(payloadJson) {
+  const payload = JSON.parse(String(payloadJson ?? "null"));
+  if (payload?.kind === "bytes") {
+    return Uint8Array.from(payload.bytes ?? []);
+  }
+  if (payload?.kind === "json") {
+    return clonePayload(payload.value);
+  }
+  return clonePayload(payload);
+}
+
+function createRuntimeRowAccessor() {
+  const accessor = new DirectAccessor();
+  accessor.registerAccessor(RUNTIME_ROW_TABLE, (data, path) => {
+    const row = JSON.parse(decoder.decode(data));
+    let current = row;
+    for (const segment of Array.isArray(path) ? path : []) {
+      if (current === null || current === undefined) {
+        return null;
+      }
+      current = current[segment];
+    }
+    return current ?? null;
+  });
+  accessor.registerBuilder(RUNTIME_ROW_TABLE, (fields) =>
+    encoder.encode(
+      JSON.stringify({
+        schemaFileId: normalizeSchemaFileId(fields.schemaFileId),
+        rowId: Number(fields.rowId),
+        payloadJson: String(fields.payloadJson ?? "null"),
+      }),
+    ),
+  );
+  return accessor;
+}
+
+function cloneQueryResult(result) {
+  return {
+    columns: Array.from(result?.columns ?? []),
+    rows: (result?.rows ?? []).map((row) =>
+      Array.isArray(row) ? row.map((value) => clonePayload(value)) : row,
+    ),
+    rowCount: Number(result?.rowCount ?? 0),
+  };
+}
+
+function rowViewFromQueryRow(row) {
+  return {
+    handle: {
+      schemaFileId: String(row[0]),
+      rowId: Number(row[1]),
+    },
+    payload: deserializePayload(row[2]),
+  };
+}
+
+export function createFlatSqlRuntimeStore(options = {}) {
+  const accessor = options.accessor ?? createRuntimeRowAccessor();
+  const database =
+    options.database ??
+    FlatSQLDatabase.fromSchema(
+      RUNTIME_ROW_SCHEMA,
+      accessor,
+      options.databaseName ?? "runtime-host",
+    );
+  const nextRowIdBySchema = new Map();
+  const existingRows = database.query(
+    `SELECT schemaFileId, rowId FROM ${RUNTIME_ROW_TABLE} ORDER BY schemaFileId, rowId`,
+  );
+  for (const row of existingRows.rows ?? []) {
+    const schemaFileId = normalizeSchemaFileId(row[0]);
+    const rowId = Number(row[1]);
+    if (Number.isInteger(rowId) && rowId > 0) {
+      nextRowIdBySchema.set(
+        schemaFileId,
+        Math.max(nextRowIdBySchema.get(schemaFileId) ?? 0, rowId),
+      );
+    }
+  }
+
+  function appendRow({ schemaFileId, payload = null }) {
+    const normalizedSchemaFileId = normalizeSchemaFileId(schemaFileId);
+    const nextRowId = (nextRowIdBySchema.get(normalizedSchemaFileId) ?? 0) + 1;
+    nextRowIdBySchema.set(normalizedSchemaFileId, nextRowId);
+    database.insert(RUNTIME_ROW_TABLE, {
+      schemaFileId: normalizedSchemaFileId,
+      rowId: nextRowId,
+      payloadJson: JSON.stringify(serializePayload(payload)),
+    });
+    return {
+      schemaFileId: normalizedSchemaFileId,
+      rowId: nextRowId,
+    };
+  }
+
+  function resolveRow(handle) {
+    const normalizedHandle = normalizeRowHandle(handle);
+    return (
+      listRows(normalizedHandle.schemaFileId).find(
+        (row) => row.handle.rowId === normalizedHandle.rowId,
+      ) ?? null
+    );
+  }
+
+  function listRows(schemaFileId = null) {
+    const normalizedSchemaFileId =
+      schemaFileId === null || schemaFileId === undefined
+        ? null
+        : normalizeSchemaFileId(schemaFileId);
+    const result =
+      normalizedSchemaFileId === null
+        ? database.query(
+            `SELECT schemaFileId, rowId, payloadJson FROM ${RUNTIME_ROW_TABLE} ORDER BY schemaFileId, rowId`,
+          )
+        : database.query(
+            `SELECT schemaFileId, rowId, payloadJson FROM ${RUNTIME_ROW_TABLE} WHERE schemaFileId = '${escapeSqlStringLiteral(normalizedSchemaFileId)}' ORDER BY rowId`,
+          );
+    return (result.rows ?? []).map(rowViewFromQueryRow);
+  }
+
+  function query(sql) {
+    if (typeof sql !== "string" || sql.trim().length === 0) {
+      throw new TypeError("sql must be a non-empty string");
+    }
+    return cloneQueryResult(database.query(sql));
+  }
+
+  return {
+    appendRow,
+    listRows,
+    query,
+    resolveRow,
+  };
+}

package/src/runtime-host/index.js

@@ -0,0 +1,21 @@
+import { createFlatSqlRuntimeStore } from "./flatsqlRuntimeStore.js";
+import { createRuntimeRegionStore } from "./runtimeRegionStore.js";
+import { createModuleRegistry } from "./moduleRegistry.js";
+
+export function createRuntimeHost(options = {}) {
+  const rows = options.rows ?? createFlatSqlRuntimeStore();
+  const regions = options.regions ?? createRuntimeRegionStore();
+  const moduleRegistry = options.moduleRegistry ?? createModuleRegistry();
+
+  return {
+    rows,
+    regions,
+    moduleRegistry,
+  };
+}
+
+export {
+  createFlatSqlRuntimeStore,
+  createModuleRegistry,
+  createRuntimeRegionStore,
+};

package/src/runtime-host/moduleRegistry.js

@@ -0,0 +1,92 @@
+function normalizeModuleId(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError("moduleId must be a non-empty string");
+  }
+  return value.trim();
+}
+
+function cloneMetadata(value) {
+  if (value === null || value === undefined) {
+    return value ?? null;
+  }
+  if (typeof structuredClone === "function") {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function toPublicModuleRecord(moduleRecord) {
+  return {
+    moduleId: moduleRecord.moduleId,
+    metadata: cloneMetadata(moduleRecord.metadata),
+    methodIds: Object.keys(moduleRecord.methods),
+  };
+}
+
+export function createModuleRegistry() {
+  const modules = new Map();
+
+  function installModule(definition) {
+    if (!definition || typeof definition !== "object") {
+      throw new TypeError("module definition is required");
+    }
+    const moduleId = normalizeModuleId(definition.moduleId);
+    const moduleRecord = {
+      moduleId,
+      methods: {
+        ...(definition.methods ?? {}),
+      },
+      metadata: cloneMetadata(definition.metadata),
+    };
+    modules.set(moduleId, moduleRecord);
+    return toPublicModuleRecord(moduleRecord);
+  }
+
+  function loadModule(moduleId) {
+    const moduleRecord = modules.get(normalizeModuleId(moduleId));
+    if (!moduleRecord) {
+      return null;
+    }
+    return {
+      moduleId: moduleRecord.moduleId,
+      methods: {
+        ...moduleRecord.methods,
+      },
+      metadata: cloneMetadata(moduleRecord.metadata),
+    };
+  }
+
+  function unloadModule(moduleId) {
+    return modules.delete(normalizeModuleId(moduleId));
+  }
+
+  function listModules() {
+    return Array.from(modules.values(), toPublicModuleRecord);
+  }
+
+  async function invokeModule(moduleId, methodId, ...args) {
+    const moduleRecord = modules.get(normalizeModuleId(moduleId));
+    if (!moduleRecord) {
+      throw new Error(`Unknown module: ${moduleId}`);
+    }
+    const method = moduleRecord.methods?.[methodId];
+    if (typeof method !== "function") {
+      throw new Error(`Unknown module method: ${moduleId}.${methodId}`);
+    }
+    return method.call(
+      {
+        moduleId: moduleRecord.moduleId,
+        metadata: cloneMetadata(moduleRecord.metadata),
+      },
+      ...args,
+    );
+  }
+
+  return {
+    installModule,
+    invokeModule,
+    listModules,
+    loadModule,
+    unloadModule,
+  };
+}

package/src/runtime-host/runtimeRegionStore.js

@@ -0,0 +1,245 @@
+function cloneBytes(bytes) {
+  return new Uint8Array(bytes);
+}
+
+function normalizePositiveInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isInteger(normalized) || normalized < 0) {
+    throw new TypeError(`${label} must be a non-negative integer`);
+  }
+  return normalized;
+}
+
+function normalizeStrictlyPositiveInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isInteger(normalized) || normalized <= 0) {
+    throw new TypeError(`${label} must be a positive integer`);
+  }
+  return normalized;
+}
+
+function normalizeRequiredString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function normalizeOptionalFunction(value, label) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "function") {
+    throw new TypeError(`${label} must be a function`);
+  }
+  return value;
+}
+
+function toRecordBytes(value, recordByteLength) {
+  const bytes = new Uint8Array(recordByteLength);
+  if (value === null || value === undefined) {
+    return bytes;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const view = value;
+    if (view.byteLength > recordByteLength) {
+      throw new RangeError("record bytes exceed recordByteLength");
+    }
+    bytes.set(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+    return bytes;
+  }
+  if (value instanceof ArrayBuffer) {
+    if (value.byteLength > recordByteLength) {
+      throw new RangeError("record bytes exceed recordByteLength");
+    }
+    bytes.set(new Uint8Array(value));
+    return bytes;
+  }
+  throw new TypeError("runtime region records must be byte-oriented");
+}
+
+export function createRuntimeRegionStore() {
+  let nextRegionId = 1;
+  const regions = new Map();
+
+  function getRegionRecordCount(region) {
+    if (typeof region.getRecordCount === "function") {
+      return normalizePositiveInteger(
+        region.getRecordCount(region.regionId),
+        "recordCount",
+      );
+    }
+    return region.records.length;
+  }
+
+  function describeRegion(regionId) {
+    const normalizedRegionId = normalizePositiveInteger(regionId, "regionId");
+    const region = regions.get(normalizedRegionId);
+    if (!region) {
+      return null;
+    }
+    return {
+      regionId: region.regionId,
+      layoutId: region.layoutId,
+      recordByteLength: region.recordByteLength,
+      alignment: region.alignment,
+      recordCount: getRegionRecordCount(region),
+    };
+  }
+
+  function allocateRegion({
+    layoutId,
+    recordByteLength,
+    alignment = 1,
+    initialRecords = [],
+  }) {
+    const region = {
+      regionId: nextRegionId++,
+      kind: "owned",
+      layoutId: normalizeRequiredString(layoutId, "layoutId"),
+      recordByteLength: normalizeStrictlyPositiveInteger(
+        recordByteLength,
+        "recordByteLength",
+      ),
+      alignment: normalizeStrictlyPositiveInteger(alignment, "alignment"),
+      records: [],
+    };
+    region.records = Array.from(initialRecords, (record) =>
+      toRecordBytes(record, region.recordByteLength),
+    );
+    regions.set(region.regionId, region);
+    return describeRegion(region.regionId);
+  }
+
+  function registerExternalRegion({
+    layoutId,
+    recordByteLength,
+    alignment = 1,
+    recordCount = 0,
+    getRecordCount,
+    resolveRecordView,
+  }) {
+    const region = {
+      regionId: nextRegionId++,
+      kind: "external",
+      layoutId: normalizeRequiredString(layoutId, "layoutId"),
+      recordByteLength: normalizeStrictlyPositiveInteger(
+        recordByteLength,
+        "recordByteLength",
+      ),
+      alignment: normalizeStrictlyPositiveInteger(alignment, "alignment"),
+      records: [],
+      getRecordCount: normalizeOptionalFunction(getRecordCount, "getRecordCount"),
+      resolveRecordView: normalizeOptionalFunction(
+        resolveRecordView,
+        "resolveRecordView",
+      ),
+    };
+    if (region.getRecordCount === undefined) {
+      region.records.length = normalizePositiveInteger(recordCount, "recordCount");
+    }
+    regions.set(region.regionId, region);
+    return describeRegion(region.regionId);
+  }
+
+  function setRegionRecordCount(regionId, recordCount) {
+    const normalizedRegionId = normalizePositiveInteger(regionId, "regionId");
+    const region = regions.get(normalizedRegionId);
+    if (!region) {
+      return null;
+    }
+    if (typeof region.getRecordCount === "function") {
+      throw new Error("Cannot set recordCount for externally counted regions");
+    }
+    const normalizedRecordCount = normalizePositiveInteger(
+      recordCount,
+      "recordCount",
+    );
+    if (normalizedRecordCount < region.records.length) {
+      region.records.length = normalizedRecordCount;
+    } else {
+      while (region.records.length < normalizedRecordCount) {
+        region.records.push(new Uint8Array(region.recordByteLength));
+      }
+    }
+    return describeRegion(normalizedRegionId);
+  }
+
+  function resolveRecord({ regionId, recordIndex }) {
+    const normalizedRegionId = normalizePositiveInteger(regionId, "regionId");
+    const normalizedRecordIndex = normalizePositiveInteger(
+      recordIndex,
+      "recordIndex",
+    );
+    const region = regions.get(normalizedRegionId);
+    if (!region) {
+      return null;
+    }
+    if (normalizedRecordIndex >= getRegionRecordCount(region)) {
+      return null;
+    }
+    if (region.kind === "external") {
+      return null;
+    }
+    return {
+      regionId: region.regionId,
+      recordIndex: normalizedRecordIndex,
+      layoutId: region.layoutId,
+      recordByteLength: region.recordByteLength,
+      alignment: region.alignment,
+      byteLength: region.recordByteLength,
+      bytes: cloneBytes(region.records[normalizedRecordIndex]),
+    };
+  }
+
+  function resolveRecordView({ regionId, recordIndex }) {
+    const normalizedRegionId = normalizePositiveInteger(regionId, "regionId");
+    const normalizedRecordIndex = normalizePositiveInteger(
+      recordIndex,
+      "recordIndex",
+    );
+    const region = regions.get(normalizedRegionId);
+    if (!region) {
+      return null;
+    }
+    if (normalizedRecordIndex >= getRegionRecordCount(region)) {
+      return null;
+    }
+    if (region.kind !== "external") {
+      return resolveRecord({
+        regionId: normalizedRegionId,
+        recordIndex: normalizedRecordIndex,
+      });
+    }
+    if (typeof region.resolveRecordView !== "function") {
+      return null;
+    }
+    const view = region.resolveRecordView({
+      regionId: normalizedRegionId,
+      recordIndex: normalizedRecordIndex,
+      layoutId: region.layoutId,
+      recordByteLength: region.recordByteLength,
+      alignment: region.alignment,
+    });
+    if (view === null || view === undefined) {
+      return null;
+    }
+    return {
+      regionId: normalizedRegionId,
+      recordIndex: normalizedRecordIndex,
+      layoutId: region.layoutId,
+      recordByteLength: region.recordByteLength,
+      alignment: region.alignment,
+      ...view,
+    };
+  }
+
+  return {
+    allocateRegion,
+    describeRegion,
+    registerExternalRegion,
+    resolveRecord,
+    resolveRecordView,
+    setRegionRecordCount,
+  };
+}

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,