space-data-module-sdk 0.2.6 → 0.2.7

package/src/manifest/index.js

@@ -6,6 +6,13 @@ export {
 } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
 export { decodePluginManifest, encodePluginManifest } from "./codec.js";
 export { toEmbeddedPluginManifest } from "./normalize.js";
+export {
+  clonePayloadTypeRef,
+  getPayloadTypeWireFormat,
+  normalizePayloadWireFormatName,
+  payloadTypeRefsMatch,
+  selectPreferredPayloadTypeRef,
+} from "./typeRefs.js";
 export {
   generateEmbeddedManifestSource,
   writeEmbeddedManifestArtifacts,

package/src/manifest/normalize.js

@@ -13,6 +13,7 @@ import {
   TimerSpecT,
 } from "../generated/orbpro/manifest.js";
 import { FlatBufferTypeRefT } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
+import { ProtocolRole, ProtocolTransportKind } from "../runtime/constants.js";
 
 const pluginFamilyByName = Object.freeze({
   sensor: PluginFamily.SENSOR,
@@ -81,6 +82,31 @@ const invokeSurfaceByName = Object.freeze({
   command: InvokeSurface.COMMAND,
 });
 
+const protocolTransportKindByName = Object.freeze({
+  libp2p: ProtocolTransportKind.LIBP2P,
+  http: ProtocolTransportKind.HTTP,
+  ws: ProtocolTransportKind.WS,
+  websocket: ProtocolTransportKind.WS,
+  "wasi-pipe": ProtocolTransportKind.WASI_PIPE,
+  wasi_pipe: ProtocolTransportKind.WASI_PIPE,
+  pipe: ProtocolTransportKind.WASI_PIPE,
+});
+
+const protocolRoleByName = Object.freeze({
+  handle: ProtocolRole.HANDLE,
+  handler: ProtocolRole.HANDLE,
+  dial: ProtocolRole.DIAL,
+  both: ProtocolRole.BOTH,
+});
+
+function normalizeOptionalString(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value).trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
 function normalizeSchemaHash(value) {
   if (!value) {
     return [];
@@ -177,6 +203,41 @@ function normalizeInvokeSurfaces(value) {
   return normalized;
 }
 
+function normalizeBoolean(value, fallback = false) {
+  if (value === undefined || value === null) {
+    return fallback;
+  }
+  return value === true;
+}
+
+function normalizeProtocolTransportKind(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized.length === 0) {
+    return null;
+  }
+  return protocolTransportKindByName[normalized] ?? normalized;
+}
+
+function normalizeProtocolRole(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized.length === 0) {
+    return null;
+  }
+  return protocolRoleByName[normalized] ?? normalized;
+}
+
 function toFlatBufferTypeRefT(value = {}) {
   if (value instanceof FlatBufferTypeRefT) {
     return value;
@@ -274,11 +335,20 @@ function toProtocolSpecT(value = {}) {
     return value;
   }
   return new ProtocolSpecT(
-    value.protocolId ?? null,
-    value.methodId ?? null,
-    value.inputPortId ?? null,
-    value.outputPortId ?? null,
-    value.description ?? null,
+    normalizeOptionalString(value.protocolId),
+    normalizeOptionalString(value.methodId),
+    normalizeOptionalString(value.inputPortId),
+    normalizeOptionalString(value.outputPortId),
+    normalizeOptionalString(value.description),
+    normalizeOptionalString(value.wireId),
+    normalizeProtocolTransportKind(value.transportKind),
+    normalizeProtocolRole(value.role),
+    normalizeOptionalString(value.specUri),
+    normalizeBoolean(value.autoInstall, true),
+    normalizeBoolean(value.advertise, false),
+    normalizeOptionalString(value.discoveryKey),
+    normalizeUnsignedInteger(value.defaultPort),
+    normalizeBoolean(value.requireSecureTransport, false),
   );
 }
 

package/src/manifest/typeRefs.js

@@ -0,0 +1,143 @@
+function cloneSchemaHash(value) {
+  if (value instanceof Uint8Array) {
+    return new Uint8Array(value);
+  }
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  return value ?? undefined;
+}
+
+export function clonePayloadTypeRef(value = null) {
+  if (!value || typeof value !== "object") {
+    return { acceptsAnyFlatbuffer: true };
+  }
+  return {
+    schemaName: value.schemaName ?? value.schema_name ?? undefined,
+    fileIdentifier: value.fileIdentifier ?? value.file_identifier ?? undefined,
+    schemaHash: cloneSchemaHash(value.schemaHash ?? value.schema_hash),
+    acceptsAnyFlatbuffer: Boolean(
+      value.acceptsAnyFlatbuffer ?? value.accepts_any_flatbuffer ?? false,
+    ),
+    wireFormat: value.wireFormat ?? value.wire_format ?? undefined,
+    rootTypeName: value.rootTypeName ?? value.root_type_name ?? undefined,
+    fixedStringLength:
+      value.fixedStringLength ?? value.fixed_string_length ?? undefined,
+    byteLength: value.byteLength ?? value.byte_length ?? undefined,
+    requiredAlignment:
+      value.requiredAlignment ?? value.required_alignment ?? undefined,
+  };
+}
+
+export function normalizePayloadWireFormatName(value) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  const normalized = String(value).trim().toLowerCase().replace(/_/g, "-");
+  if (normalized === "aligned-binary") {
+    return "aligned-binary";
+  }
+  if (normalized === "flatbuffer") {
+    return "flatbuffer";
+  }
+  return null;
+}
+
+export function getPayloadTypeWireFormat(typeRef = {}) {
+  return normalizePayloadWireFormatName(typeRef.wireFormat) ?? "flatbuffer";
+}
+
+function schemaHashMatches(expected, actual) {
+  if (!Array.isArray(expected) && !(expected instanceof Uint8Array)) {
+    return true;
+  }
+  const expectedArray = Array.from(expected);
+  if (expectedArray.length === 0) {
+    return true;
+  }
+  const actualArray =
+    Array.isArray(actual) || actual instanceof Uint8Array
+      ? Array.from(actual)
+      : null;
+  if (!actualArray || actualArray.length !== expectedArray.length) {
+    return false;
+  }
+  for (let index = 0; index < expectedArray.length; index += 1) {
+    if (expectedArray[index] !== actualArray[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function optionalScalarMatches(expected, actual) {
+  return expected === undefined || expected === null || expected === actual;
+}
+
+export function payloadTypeRefsMatch(expectedTypeRef = {}, actualTypeRef = {}) {
+  const expected = clonePayloadTypeRef(expectedTypeRef);
+  const actual = clonePayloadTypeRef(actualTypeRef);
+  const expectedWireFormat = getPayloadTypeWireFormat(expected);
+  const actualWireFormat = getPayloadTypeWireFormat(actual);
+
+  if (expected.acceptsAnyFlatbuffer === true) {
+    return actualWireFormat === "flatbuffer";
+  }
+  if (expectedWireFormat !== actualWireFormat) {
+    return false;
+  }
+  if (expected.schemaName && expected.schemaName !== actual.schemaName) {
+    return false;
+  }
+  if (
+    expected.fileIdentifier &&
+    expected.fileIdentifier !== actual.fileIdentifier
+  ) {
+    return false;
+  }
+  if (!schemaHashMatches(expected.schemaHash, actual.schemaHash)) {
+    return false;
+  }
+  if (expectedWireFormat === "aligned-binary") {
+    if (!optionalScalarMatches(expected.rootTypeName, actual.rootTypeName)) {
+      return false;
+    }
+    if (!optionalScalarMatches(expected.fixedStringLength, actual.fixedStringLength)) {
+      return false;
+    }
+    if (!optionalScalarMatches(expected.byteLength, actual.byteLength)) {
+      return false;
+    }
+    if (
+      !optionalScalarMatches(expected.requiredAlignment, actual.requiredAlignment)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function selectPreferredPayloadTypeRef(port = {}, options = {}) {
+  const preferredWireFormat = normalizePayloadWireFormatName(
+    options.preferredWireFormat,
+  );
+  let fallback = null;
+  for (const typeSet of Array.isArray(port.acceptedTypeSets) ? port.acceptedTypeSets : []) {
+    const allowedTypes = Array.isArray(typeSet.allowedTypes)
+      ? typeSet.allowedTypes
+      : [];
+    for (const allowedType of allowedTypes) {
+      const candidate = clonePayloadTypeRef(allowedType);
+      if (fallback === null) {
+        fallback = candidate;
+      }
+      if (
+        preferredWireFormat !== null &&
+        getPayloadTypeWireFormat(candidate) === preferredWireFormat
+      ) {
+        return candidate;
+      }
+    }
+  }
+  return fallback ?? clonePayloadTypeRef(null);
+}

package/src/runtime/constants.js

@@ -48,6 +48,19 @@ export const InvokeSurface = Object.freeze({
   COMMAND: "command",
 });
 
+export const ProtocolTransportKind = Object.freeze({
+  LIBP2P: "libp2p",
+  HTTP: "http",
+  WS: "ws",
+  WASI_PIPE: "wasi-pipe",
+});
+
+export const ProtocolRole = Object.freeze({
+  HANDLE: "handle",
+  DIAL: "dial",
+  BOTH: "both",
+});
+
 export const DefaultManifestExports = Object.freeze({
   pluginBytesSymbol: "plugin_get_manifest_flatbuffer",
   pluginSizeSymbol: "plugin_get_manifest_flatbuffer_size",

package/src/runtime/index.d.ts

@@ -5,6 +5,8 @@ export {
   ExternalInterfaceDirection,
   ExternalInterfaceKind,
   InvokeSurface,
+  ProtocolRole,
+  ProtocolTransportKind,
   RuntimeTarget,
 } from "../index.js";
 

package/src/testing/index.d.ts

@@ -0,0 +1,84 @@
+import type {
+  InvokeSurface,
+  PayloadTypeRef,
+  PayloadWireFormat,
+  PluginManifest,
+} from "../index.js";
+
+export interface HarnessInputFrame {
+  portId?: string | null;
+  typeRef?: PayloadTypeRef | null;
+  payload?: Uint8Array | ArrayBuffer | ArrayBufferView | string | null;
+}
+
+export interface HarnessInvokeScenario {
+  id: string;
+  kind: "invoke";
+  surface: InvokeSurface;
+  methodId: string;
+  displayName?: string | null;
+  inputs?: HarnessInputFrame[];
+  requiredPortIds?: string[];
+  expectedStatusCode?: number;
+  notes?: string[];
+}
+
+export interface HarnessRawScenario {
+  id: string;
+  kind: string;
+  stdinBytes?: Uint8Array | ArrayBuffer | ArrayBufferView | string | null;
+  notes?: string[];
+}
+
+export interface CapabilityRuntimeSurface {
+  capability: string;
+  wasi: boolean;
+  syncHostcall: boolean;
+  nodeHostApi: boolean;
+  notes: string[];
+}
+
+export interface ManifestHarnessPlan {
+  moduleKind: "module" | "flow";
+  pluginId: string | null;
+  name: string | null;
+  version: string | null;
+  invokeSurfaces: InvokeSurface[];
+  methods: Array<{
+    methodId: string | null;
+    displayName: string | null;
+    inputPorts: number;
+    outputPorts: number;
+  }>;
+  capabilities: CapabilityRuntimeSurface[];
+  generatedCases: HarnessInvokeScenario[];
+  scenarios: Array<HarnessInvokeScenario | HarnessRawScenario>;
+}
+
+export function describeCapabilityRuntimeSurface(
+  capability: string,
+): CapabilityRuntimeSurface;
+
+export function generateManifestHarnessPlan(options: {
+  manifest: PluginManifest;
+  includeOptionalInputs?: boolean;
+  expectedStatusCode?: number;
+  preferredWireFormat?: PayloadWireFormat;
+  payloadForPort?: (context: {
+    methodId: string | null;
+    portId: string | null;
+    port: unknown;
+    required: boolean;
+    typeRef: PayloadTypeRef;
+  }) => Uint8Array | ArrayBuffer | ArrayBufferView | string | null | undefined;
+  scenarios?: Array<HarnessInvokeScenario | HarnessRawScenario>;
+}): ManifestHarnessPlan;
+
+export function materializeHarnessScenario(
+  scenario: HarnessInvokeScenario | HarnessRawScenario,
+): (HarnessInvokeScenario | HarnessRawScenario) & {
+  stdinBytes?: Uint8Array;
+  requestBytes?: Uint8Array;
+};
+
+export function serializeHarnessPlan(plan: ManifestHarnessPlan): unknown;