sdn-flow 0.2.0

package/src/host/constants.js

@@ -0,0 +1,55 @@
+export const HostedRuntimeKind = Object.freeze({
+  FLOW: "flow",
+  PLUGIN: "plugin",
+  SERVICE: "service",
+});
+
+export const HostedRuntimeAuthority = Object.freeze({
+  LOCAL: "local",
+  REMOTE: "remote",
+});
+
+export const HostedRuntimeStartupPhase = Object.freeze({
+  BOOTSTRAP: "bootstrap",
+  EARLY: "early",
+  SESSION: "session",
+  ON_DEMAND: "on-demand",
+});
+
+export const HostedRuntimeBindingDirection = Object.freeze({
+  LISTEN: "listen",
+  DIAL: "dial",
+});
+
+export const HostedRuntimeTransport = Object.freeze({
+  SAME_APP: "same-app",
+  DIRECT: "direct",
+  WEBRTC: "webrtc",
+  SDN_PROTOCOL: "sdn-protocol",
+  HTTP: "http",
+});
+
+export const HostedRuntimeAdapter = Object.freeze({
+  SDN_JS: "sdn-js",
+  HOST_INTERNAL: "host-internal",
+  GO_SDN: "go-sdn",
+});
+
+export const HostedRuntimeEngine = Object.freeze({
+  NODE: "node",
+  DENO: "deno",
+  BUN: "bun",
+  BROWSER: "browser",
+  WASI: "wasi",
+  GO: "go",
+});
+
+export default {
+  HostedRuntimeAdapter,
+  HostedRuntimeEngine,
+  HostedRuntimeAuthority,
+  HostedRuntimeBindingDirection,
+  HostedRuntimeKind,
+  HostedRuntimeStartupPhase,
+  HostedRuntimeTransport,
+};

package/src/host/dependencyRuntime.js

@@ -0,0 +1,227 @@
+import { bindCompiledDescriptorAbi } from "./descriptorAbi.js";
+
+function resolveDependencyImportObject(imports, descriptor) {
+  if (typeof imports === "function") {
+    return imports(descriptor) ?? {};
+  }
+  if (imports instanceof Map) {
+    return (
+      imports.get(descriptor.dependencyId) ??
+      imports.get(descriptor.pluginId) ??
+      imports.get("default") ??
+      {}
+    );
+  }
+  if (imports && typeof imports === "object") {
+    return (
+      imports[descriptor.dependencyId] ??
+      imports[descriptor.pluginId] ??
+      imports.default ??
+      {}
+    );
+  }
+  return {};
+}
+
+function resolveNamedExport(exports, symbol) {
+  if (!symbol) {
+    return null;
+  }
+  return exports?.[symbol] ?? exports?.[`_${symbol}`] ?? null;
+}
+
+function toUint8Array(data) {
+  if (data instanceof Uint8Array) {
+    return data;
+  }
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  throw new TypeError("Expected Uint8Array, ArrayBufferView, or ArrayBuffer.");
+}
+
+function cloneBytes(memory, offset, size) {
+  const base = Number(offset) >>> 0;
+  const length = Number(size) >>> 0;
+  if (length === 0) {
+    return new Uint8Array();
+  }
+  return new Uint8Array(new Uint8Array(memory.buffer, base, length));
+}
+
+function writeBytes(memory, pointer, data) {
+  const bytes = new Uint8Array(memory.buffer);
+  bytes.set(toUint8Array(data), Number(pointer) >>> 0);
+}
+
+function getWasmExports(instanceResult) {
+  if (instanceResult?.instance?.exports) {
+    return instanceResult.instance.exports;
+  }
+  if (instanceResult?.exports) {
+    return instanceResult.exports;
+  }
+  return {};
+}
+
+function createRawStreamInvoker(dependency) {
+  const { resolvedExports, memory } = dependency;
+  if (
+    typeof resolvedExports?.streamInvoke !== "function" ||
+    typeof resolvedExports?.malloc !== "function" ||
+    typeof resolvedExports?.free !== "function" ||
+    !memory
+  ) {
+    return null;
+  }
+  return function invokeRawStream(requestBytes) {
+    const request = toUint8Array(requestBytes);
+    const requestSize = request.length;
+    const requestPointer =
+      requestSize > 0 ? Number(resolvedExports.malloc(requestSize)) >>> 0 : 0;
+    const sizePointer = Number(resolvedExports.malloc(4)) >>> 0;
+    const view = new DataView(memory.buffer);
+    try {
+      if (requestSize > 0) {
+        writeBytes(memory, requestPointer, request);
+      }
+      view.setUint32(sizePointer, 0, true);
+      const responsePointer =
+        Number(
+          resolvedExports.streamInvoke(requestPointer, requestSize, sizePointer),
+        ) >>> 0;
+      const responseSize = view.getUint32(sizePointer, true);
+      const responseBytes =
+        responsePointer !== 0 && responseSize > 0
+          ? cloneBytes(memory, responsePointer, responseSize)
+          : new Uint8Array();
+      if (responsePointer !== 0) {
+        resolvedExports.free(responsePointer);
+      }
+      return responseBytes;
+    } finally {
+      if (requestPointer !== 0) {
+        resolvedExports.free(requestPointer);
+      }
+      resolvedExports.free(sizePointer);
+    }
+  };
+}
+
+export async function instantiateEmbeddedDependencies({
+  artifact,
+  instance = null,
+  wasmExports = null,
+  memory = null,
+  imports = {},
+  instantiate = WebAssembly.instantiate,
+} = {}) {
+  if (typeof instantiate !== "function") {
+    throw new TypeError(
+      "instantiateEmbeddedDependencies requires an instantiate function.",
+    );
+  }
+  const bound = await bindCompiledDescriptorAbi({
+    artifact,
+    instance,
+    wasmExports,
+    memory,
+  });
+  const descriptors = bound.readAllDependencyDescriptors();
+  const instantiated = [];
+  for (let index = 0; index < descriptors.length; index += 1) {
+    const descriptor = descriptors[index];
+    const importObject = resolveDependencyImportObject(imports, descriptor);
+    const instantiatedModule = await instantiate(descriptor.wasmBytes, importObject);
+    const exports = getWasmExports(instantiatedModule);
+    instantiated.push({
+      index,
+      dependencyId: descriptor.dependencyId,
+      pluginId: descriptor.pluginId,
+      descriptor,
+      importObject,
+      module: instantiatedModule?.module ?? null,
+      instance: instantiatedModule?.instance ?? instantiatedModule ?? null,
+      exports,
+      resolvedExports: {
+        init: resolveNamedExport(exports, descriptor.initSymbol),
+        destroy: resolveNamedExport(exports, descriptor.destroySymbol),
+        malloc: resolveNamedExport(exports, descriptor.mallocSymbol),
+        free: resolveNamedExport(exports, descriptor.freeSymbol),
+        streamInvoke: resolveNamedExport(exports, descriptor.streamInvokeSymbol),
+        manifestBytes: resolveNamedExport(
+          exports,
+          descriptor.manifestBytesSymbol,
+        ),
+        manifestSize: resolveNamedExport(exports, descriptor.manifestSizeSymbol),
+      },
+      memory: exports?.memory ?? null,
+    });
+    instantiated[index].invokeRawStream = createRawStreamInvoker(instantiated[index]);
+    instantiated[index].cloneBytes = (offset, size) =>
+      cloneBytes(instantiated[index].memory, offset, size);
+    instantiated[index].release = (pointer) => {
+      if (!pointer || typeof instantiated[index].resolvedExports.free !== "function") {
+        return null;
+      }
+      return instantiated[index].resolvedExports.free(Number(pointer) >>> 0);
+    };
+  }
+  return {
+    ...bound,
+    descriptors,
+    instantiated,
+    byDependencyId: new Map(
+      instantiated.map((dependency) => [dependency.dependencyId, dependency]),
+    ),
+    byPluginId: new Map(
+      instantiated.map((dependency) => [dependency.pluginId, dependency]),
+    ),
+    getDependency(binding = {}) {
+      if (binding.dependencyId && this.byDependencyId.has(binding.dependencyId)) {
+        return this.byDependencyId.get(binding.dependencyId);
+      }
+      if (binding.pluginId && this.byPluginId.has(binding.pluginId)) {
+        return this.byPluginId.get(binding.pluginId);
+      }
+      const normalizedIndex = Number(binding.index ?? binding.dependencyIndex);
+      if (Number.isInteger(normalizedIndex) && normalizedIndex >= 0) {
+        return this.instantiated[normalizedIndex] ?? null;
+      }
+      return null;
+    },
+    initializeDependency(binding = {}, ...args) {
+      const dependency = this.getDependency(binding);
+      if (!dependency?.resolvedExports?.init) {
+        return null;
+      }
+      return dependency.resolvedExports.init(...args);
+    },
+    destroyDependency(binding = {}, ...args) {
+      const dependency = this.getDependency(binding);
+      if (!dependency?.resolvedExports?.destroy) {
+        return null;
+      }
+      return dependency.resolvedExports.destroy(...args);
+    },
+    initializeAll(...args) {
+      return this.instantiated.map((dependency) =>
+        dependency.resolvedExports.init
+          ? dependency.resolvedExports.init(...args)
+          : null,
+      );
+    },
+    destroyAll(...args) {
+      return this.instantiated.map((dependency) =>
+        dependency.resolvedExports.destroy
+          ? dependency.resolvedExports.destroy(...args)
+          : null,
+      );
+    },
+  };
+}
+
+export default instantiateEmbeddedDependencies;

package/src/host/descriptorAbi.js

@@ -0,0 +1,351 @@
+import {
+  bindCompiledRuntimeAbi,
+  DefaultRequiredRuntimeExportRoles,
+} from "./runtimeAbi.js";
+import {
+  FlowNodeDispatchDescriptorLayout,
+  SignedArtifactDependencyDescriptorLayout,
+} from "../generated/runtimeAbiLayouts.js";
+
+export {
+  FlowNodeDispatchDescriptorLayout,
+  SignedArtifactDependencyDescriptorLayout,
+};
+
+export const DefaultRequiredDescriptorExportRoles = Object.freeze([
+  ...DefaultRequiredRuntimeExportRoles,
+  "nodeDispatchDescriptorsSymbol",
+  "nodeDispatchDescriptorCountSymbol",
+  "dependencyDescriptorsSymbol",
+  "dependencyCountSymbol",
+]);
+
+function resolveMemory(bound, explicitMemory = null) {
+  const memory =
+    explicitMemory ??
+    bound?.wasmExports?.memory ??
+    bound?.artifact?.wasmMemory ??
+    null;
+  if (!memory || !(memory.buffer instanceof ArrayBuffer)) {
+    throw new Error(
+      "Compiled descriptor ABI requires a WebAssembly.Memory export.",
+    );
+  }
+  return memory;
+}
+
+function readCString(memory, pointer) {
+  if (!pointer) {
+    return null;
+  }
+  const bytes = new Uint8Array(memory.buffer);
+  let end = pointer >>> 0;
+  while (end < bytes.length && bytes[end] !== 0) {
+    end += 1;
+  }
+  return new TextDecoder().decode(bytes.subarray(pointer >>> 0, end));
+}
+
+function cloneBytes(memory, offset, size) {
+  const base = Number(offset) >>> 0;
+  const length = Number(size) >>> 0;
+  if (length === 0) {
+    return new Uint8Array();
+  }
+  const bytes = new Uint8Array(memory.buffer, base, length);
+  return new Uint8Array(bytes);
+}
+
+function readNodeDispatchDescriptor(memory, pointer) {
+  if (!pointer) {
+    return null;
+  }
+  const view = new DataView(memory.buffer);
+  const base = pointer >>> 0;
+  const nodeIdPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.nodeIdPointer.offset,
+    true,
+  );
+  const dependencyIdPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.dependencyIdPointer.offset,
+    true,
+  );
+  const pluginIdPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.pluginIdPointer.offset,
+    true,
+  );
+  const methodIdPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.methodIdPointer.offset,
+    true,
+  );
+  const dispatchModelPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.dispatchModelPointer.offset,
+    true,
+  );
+  const entrypointPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.entrypointPointer.offset,
+    true,
+  );
+  const manifestBytesSymbolPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.manifestBytesSymbolPointer.offset,
+    true,
+  );
+  const manifestSizeSymbolPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.manifestSizeSymbolPointer.offset,
+    true,
+  );
+  const initSymbolPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.initSymbolPointer.offset,
+    true,
+  );
+  const destroySymbolPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.destroySymbolPointer.offset,
+    true,
+  );
+  const mallocSymbolPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.mallocSymbolPointer.offset,
+    true,
+  );
+  const freeSymbolPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.freeSymbolPointer.offset,
+    true,
+  );
+  const streamInvokeSymbolPointer = view.getUint32(
+    base + FlowNodeDispatchDescriptorLayout.fields.streamInvokeSymbolPointer.offset,
+    true,
+  );
+  return {
+    nodeIdPointer,
+    nodeIndex: view.getUint32(
+      base + FlowNodeDispatchDescriptorLayout.fields.nodeIndex.offset,
+      true,
+    ),
+    dependencyIdPointer,
+    dependencyIndex: view.getUint32(
+      base + FlowNodeDispatchDescriptorLayout.fields.dependencyIndex.offset,
+      true,
+    ),
+    pluginIdPointer,
+    methodIdPointer,
+    dispatchModelPointer,
+    entrypointPointer,
+    manifestBytesSymbolPointer,
+    manifestSizeSymbolPointer,
+    initSymbolPointer,
+    destroySymbolPointer,
+    mallocSymbolPointer,
+    freeSymbolPointer,
+    streamInvokeSymbolPointer,
+    nodeId: readCString(memory, nodeIdPointer),
+    dependencyId: readCString(memory, dependencyIdPointer),
+    pluginId: readCString(memory, pluginIdPointer),
+    methodId: readCString(memory, methodIdPointer),
+    dispatchModel: readCString(memory, dispatchModelPointer),
+    entrypoint: readCString(memory, entrypointPointer),
+    manifestBytesSymbol: readCString(memory, manifestBytesSymbolPointer),
+    manifestSizeSymbol: readCString(memory, manifestSizeSymbolPointer),
+    initSymbol: readCString(memory, initSymbolPointer),
+    destroySymbol: readCString(memory, destroySymbolPointer),
+    mallocSymbol: readCString(memory, mallocSymbolPointer),
+    freeSymbol: readCString(memory, freeSymbolPointer),
+    streamInvokeSymbol: readCString(memory, streamInvokeSymbolPointer),
+  };
+}
+
+function readSignedArtifactDependencyDescriptor(memory, pointer) {
+  if (!pointer) {
+    return null;
+  }
+  const view = new DataView(memory.buffer);
+  const base = pointer >>> 0;
+  const dependencyIdPointer = view.getUint32(
+    base +
+      SignedArtifactDependencyDescriptorLayout.fields.dependencyIdPointer.offset,
+    true,
+  );
+  const pluginIdPointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.pluginIdPointer.offset,
+    true,
+  );
+  const versionPointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.versionPointer.offset,
+    true,
+  );
+  const sha256Pointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.sha256Pointer.offset,
+    true,
+  );
+  const signaturePointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.signaturePointer.offset,
+    true,
+  );
+  const signerPublicKeyPointer = view.getUint32(
+    base +
+      SignedArtifactDependencyDescriptorLayout.fields.signerPublicKeyPointer.offset,
+    true,
+  );
+  const entrypointPointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.entrypointPointer.offset,
+    true,
+  );
+  const manifestBytesSymbolPointer = view.getUint32(
+    base +
+      SignedArtifactDependencyDescriptorLayout.fields.manifestBytesSymbolPointer.offset,
+    true,
+  );
+  const manifestSizeSymbolPointer = view.getUint32(
+    base +
+      SignedArtifactDependencyDescriptorLayout.fields.manifestSizeSymbolPointer.offset,
+    true,
+  );
+  const initSymbolPointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.initSymbolPointer.offset,
+    true,
+  );
+  const destroySymbolPointer = view.getUint32(
+    base +
+      SignedArtifactDependencyDescriptorLayout.fields.destroySymbolPointer.offset,
+    true,
+  );
+  const mallocSymbolPointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.mallocSymbolPointer.offset,
+    true,
+  );
+  const freeSymbolPointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.freeSymbolPointer.offset,
+    true,
+  );
+  const streamInvokeSymbolPointer = view.getUint32(
+    base +
+      SignedArtifactDependencyDescriptorLayout.fields.streamInvokeSymbolPointer.offset,
+    true,
+  );
+  const wasmBytesPointer = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.wasmBytesPointer.offset,
+    true,
+  );
+  const wasmSize = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.wasmSize.offset,
+    true,
+  );
+  const manifestBytesPointer = view.getUint32(
+    base +
+      SignedArtifactDependencyDescriptorLayout.fields.manifestBytesPointer.offset,
+    true,
+  );
+  const manifestSize = view.getUint32(
+    base + SignedArtifactDependencyDescriptorLayout.fields.manifestSize.offset,
+    true,
+  );
+  return {
+    dependencyIdPointer,
+    pluginIdPointer,
+    versionPointer,
+    sha256Pointer,
+    signaturePointer,
+    signerPublicKeyPointer,
+    entrypointPointer,
+    manifestBytesSymbolPointer,
+    manifestSizeSymbolPointer,
+    initSymbolPointer,
+    destroySymbolPointer,
+    mallocSymbolPointer,
+    freeSymbolPointer,
+    streamInvokeSymbolPointer,
+    wasmBytesPointer,
+    wasmSize,
+    manifestBytesPointer,
+    manifestSize,
+    dependencyId: readCString(memory, dependencyIdPointer),
+    pluginId: readCString(memory, pluginIdPointer),
+    version: readCString(memory, versionPointer),
+    sha256: readCString(memory, sha256Pointer),
+    signature: readCString(memory, signaturePointer),
+    signerPublicKey: readCString(memory, signerPublicKeyPointer),
+    entrypoint: readCString(memory, entrypointPointer),
+    manifestBytesSymbol: readCString(memory, manifestBytesSymbolPointer),
+    manifestSizeSymbol: readCString(memory, manifestSizeSymbolPointer),
+    initSymbol: readCString(memory, initSymbolPointer),
+    destroySymbol: readCString(memory, destroySymbolPointer),
+    mallocSymbol: readCString(memory, mallocSymbolPointer),
+    freeSymbol: readCString(memory, freeSymbolPointer),
+    streamInvokeSymbol: readCString(memory, streamInvokeSymbolPointer),
+    wasmBytes: cloneBytes(memory, wasmBytesPointer, wasmSize),
+    manifestBytes: cloneBytes(memory, manifestBytesPointer, manifestSize),
+  };
+}
+
+export async function bindCompiledDescriptorAbi({
+  artifact,
+  instance = null,
+  wasmExports = null,
+  memory = null,
+  requiredRoles = DefaultRequiredDescriptorExportRoles,
+} = {}) {
+  const bound = await bindCompiledRuntimeAbi({
+    artifact,
+    instance,
+    wasmExports,
+    requiredRoles,
+  });
+  const resolvedMemory = resolveMemory(bound, memory);
+
+  return {
+    ...bound,
+    memory: resolvedMemory,
+    readNodeDispatchDescriptor(pointer) {
+      return readNodeDispatchDescriptor(resolvedMemory, pointer);
+    },
+    readDependencyDescriptor(pointer) {
+      return readSignedArtifactDependencyDescriptor(resolvedMemory, pointer);
+    },
+    getNodeDispatchDescriptorsPointer() {
+      return Number(bound.resolvedByRole.nodeDispatchDescriptorsSymbol()) >>> 0;
+    },
+    getNodeDispatchDescriptorCount() {
+      return (
+        Number(bound.resolvedByRole.nodeDispatchDescriptorCountSymbol()) >>> 0
+      );
+    },
+    getDependencyDescriptorsPointer() {
+      return Number(bound.resolvedByRole.dependencyDescriptorsSymbol()) >>> 0;
+    },
+    getDependencyDescriptorCount() {
+      return Number(bound.resolvedByRole.dependencyCountSymbol()) >>> 0;
+    },
+    readNodeDispatchDescriptorAt(index) {
+      const normalizedIndex = Number(index) >>> 0;
+      if (normalizedIndex >= this.getNodeDispatchDescriptorCount()) {
+        return null;
+      }
+      return this.readNodeDispatchDescriptor(
+        this.getNodeDispatchDescriptorsPointer() +
+          normalizedIndex * FlowNodeDispatchDescriptorLayout.size,
+      );
+    },
+    readDependencyDescriptorAt(index) {
+      const normalizedIndex = Number(index) >>> 0;
+      if (normalizedIndex >= this.getDependencyDescriptorCount()) {
+        return null;
+      }
+      return this.readDependencyDescriptor(
+        this.getDependencyDescriptorsPointer() +
+          normalizedIndex * SignedArtifactDependencyDescriptorLayout.size,
+      );
+    },
+    readAllNodeDispatchDescriptors() {
+      return Array.from(
+        { length: this.getNodeDispatchDescriptorCount() },
+        (_unused, index) => this.readNodeDispatchDescriptorAt(index),
+      );
+    },
+    readAllDependencyDescriptors() {
+      return Array.from(
+        { length: this.getDependencyDescriptorCount() },
+        (_unused, index) => this.readDependencyDescriptorAt(index),
+      );
+    },
+  };
+}
+
+export default bindCompiledDescriptorAbi;