space-data-module-sdk 0.1.0

package/src/manifest/normalize.js

@@ -0,0 +1,275 @@
+import {
+  AcceptedTypeSetT,
+  BuildArtifactT,
+  CapabilityKind,
+  DrainPolicy as ManifestDrainPolicy,
+  HostCapabilityT,
+  MethodManifestT,
+  PluginFamily,
+  PluginManifestT,
+  PortManifestT,
+  ProtocolSpecT,
+  TimerSpecT,
+} from "../generated/orbpro/manifest.js";
+import { FlatBufferTypeRefT } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
+
+const pluginFamilyByName = Object.freeze({
+  sensor: PluginFamily.SENSOR,
+  propagator: PluginFamily.PROPAGATOR,
+  renderer: PluginFamily.RENDERER,
+  analysis: PluginFamily.ANALYSIS,
+  data_source: PluginFamily.DATA_SOURCE,
+  datasource: PluginFamily.DATA_SOURCE,
+  comms: PluginFamily.COMMS,
+  shader: PluginFamily.SHADER,
+  sdf: PluginFamily.SDF,
+  infrastructure: PluginFamily.INFRASTRUCTURE,
+  flow: PluginFamily.FLOW,
+  bridge: PluginFamily.BRIDGE,
+});
+
+const drainPolicyByName = Object.freeze({
+  "single-shot": ManifestDrainPolicy.SINGLE_SHOT,
+  "drain-until-yield": ManifestDrainPolicy.DRAIN_UNTIL_YIELD,
+  "drain-to-empty": ManifestDrainPolicy.DRAIN_TO_EMPTY,
+});
+
+const capabilityKindByName = Object.freeze({
+  clock: CapabilityKind.CLOCK,
+  random: CapabilityKind.RANDOM,
+  logging: CapabilityKind.LOGGING,
+  timers: CapabilityKind.TIMERS,
+  pubsub: CapabilityKind.PUBSUB,
+  protocol_dial: CapabilityKind.PROTOCOL_DIAL,
+  protocol_handle: CapabilityKind.PROTOCOL_HANDLE,
+  storage_query: CapabilityKind.STORAGE_QUERY,
+  scene_access: CapabilityKind.SCENE_ACCESS,
+  entity_access: CapabilityKind.ENTITY_ACCESS,
+  render_hooks: CapabilityKind.RENDER_HOOKS,
+});
+
+function normalizeSchemaHash(value) {
+  if (!value) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.map((byte) => Number(byte) & 0xff);
+  }
+  const normalized = String(value).trim().replace(/^0x/i, "");
+  if (normalized.length === 0 || normalized.length % 2 !== 0) {
+    return [];
+  }
+  const bytes = [];
+  for (let index = 0; index < normalized.length; index += 2) {
+    bytes.push(parseInt(normalized.slice(index, index + 2), 16));
+  }
+  return bytes;
+}
+
+function normalizePluginFamily(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  const normalized = String(value ?? "analysis")
+    .trim()
+    .toLowerCase();
+  return pluginFamilyByName[normalized] ?? PluginFamily.ANALYSIS;
+}
+
+function normalizeDrainPolicy(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  const normalized = String(value ?? "drain-until-yield")
+    .trim()
+    .toLowerCase();
+  return (
+    drainPolicyByName[normalized] ?? ManifestDrainPolicy.DRAIN_UNTIL_YIELD
+  );
+}
+
+function normalizeCapabilityKind(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  return capabilityKindByName[normalized] ?? null;
+}
+
+function toFlatBufferTypeRefT(value = {}) {
+  if (value instanceof FlatBufferTypeRefT) {
+    return value;
+  }
+  return new FlatBufferTypeRefT(
+    value.schemaName ?? null,
+    value.fileIdentifier ?? null,
+    normalizeSchemaHash(value.schemaHash),
+    value.acceptsAnyFlatbuffer === true,
+  );
+}
+
+function toAcceptedTypeSetT(value = {}) {
+  if (value instanceof AcceptedTypeSetT) {
+    return value;
+  }
+  return new AcceptedTypeSetT(
+    value.setId ?? null,
+    Array.isArray(value.allowedTypes)
+      ? value.allowedTypes.map((entry) => toFlatBufferTypeRefT(entry))
+      : [],
+    value.description ?? null,
+  );
+}
+
+function toPortManifestT(value = {}) {
+  if (value instanceof PortManifestT) {
+    return value;
+  }
+  return new PortManifestT(
+    value.portId ?? null,
+    value.displayName ?? null,
+    Array.isArray(value.acceptedTypeSets)
+      ? value.acceptedTypeSets.map((entry) => toAcceptedTypeSetT(entry))
+      : [],
+    Number(value.minStreams ?? 1),
+    Number(value.maxStreams ?? 1),
+    value.required !== false,
+    value.description ?? null,
+  );
+}
+
+function toMethodManifestT(value = {}) {
+  if (value instanceof MethodManifestT) {
+    return value;
+  }
+  return new MethodManifestT(
+    value.methodId ?? null,
+    value.displayName ?? null,
+    Array.isArray(value.inputPorts)
+      ? value.inputPorts.map((entry) => toPortManifestT(entry))
+      : [],
+    Array.isArray(value.outputPorts)
+      ? value.outputPorts.map((entry) => toPortManifestT(entry))
+      : [],
+    Number(value.maxBatch ?? 1),
+    normalizeDrainPolicy(value.drainPolicy),
+    value.description ?? null,
+  );
+}
+
+function toBuildArtifactT(value = {}) {
+  if (value instanceof BuildArtifactT) {
+    return value;
+  }
+  return new BuildArtifactT(
+    value.artifactId ?? null,
+    value.kind ?? null,
+    value.path ?? null,
+    value.target ?? null,
+    value.entrySymbol ?? null,
+  );
+}
+
+function toTimerSpecT(value = {}) {
+  if (value instanceof TimerSpecT) {
+    return value;
+  }
+  return new TimerSpecT(
+    value.timerId ?? null,
+    value.methodId ?? null,
+    value.inputPortId ?? null,
+    BigInt(value.defaultIntervalMs ?? 0),
+    value.description ?? null,
+  );
+}
+
+function toProtocolSpecT(value = {}) {
+  if (value instanceof ProtocolSpecT) {
+    return value;
+  }
+  return new ProtocolSpecT(
+    value.protocolId ?? null,
+    value.methodId ?? null,
+    value.inputPortId ?? null,
+    value.outputPortId ?? null,
+    value.description ?? null,
+  );
+}
+
+function toHostCapabilityT(value, warnings) {
+  if (value instanceof HostCapabilityT) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const capability = normalizeCapabilityKind(value);
+    if (capability === null) {
+      warnings.push(
+        `Capability "${value}" is not representable in the current embedded FlatBuffer manifest schema and was omitted.`,
+      );
+      return null;
+    }
+    return new HostCapabilityT(capability, null, true, null);
+  }
+  const capability = normalizeCapabilityKind(value?.capability);
+  if (capability === null) {
+    warnings.push(
+      `Capability "${value?.capability ?? "unknown"}" is not representable in the current embedded FlatBuffer manifest schema and was omitted.`,
+    );
+    return null;
+  }
+  return new HostCapabilityT(
+    capability,
+    value?.scope ?? null,
+    value?.required !== false,
+    value?.description ?? null,
+  );
+}
+
+export function toEmbeddedPluginManifest(input = {}) {
+  if (input instanceof PluginManifestT) {
+    return { manifest: input, warnings: [] };
+  }
+
+  const warnings = [];
+  if (Array.isArray(input.externalInterfaces) && input.externalInterfaces.length > 0) {
+    warnings.push(
+      "externalInterfaces are not yet representable in the embedded FlatBuffer manifest schema and were omitted from the compiled artifact.",
+    );
+  }
+
+  const capabilities = Array.isArray(input.capabilities)
+    ? input.capabilities
+        .map((entry) => toHostCapabilityT(entry, warnings))
+        .filter(Boolean)
+    : [];
+
+  return {
+    manifest: new PluginManifestT(
+      input.pluginId ?? null,
+      input.name ?? null,
+      input.version ?? null,
+      normalizePluginFamily(input.pluginFamily),
+      Array.isArray(input.methods)
+        ? input.methods.map((entry) => toMethodManifestT(entry))
+        : [],
+      capabilities,
+      Array.isArray(input.timers)
+        ? input.timers.map((entry) => toTimerSpecT(entry))
+        : [],
+      Array.isArray(input.protocols)
+        ? input.protocols.map((entry) => toProtocolSpecT(entry))
+        : [],
+      Array.isArray(input.schemasUsed)
+        ? input.schemasUsed.map((entry) => toFlatBufferTypeRefT(entry))
+        : [],
+      Array.isArray(input.buildArtifacts)
+        ? input.buildArtifacts.map((entry) => toBuildArtifactT(entry))
+        : [],
+      Number(input.abiVersion ?? 1),
+    ),
+    warnings,
+  };
+}
+

package/src/runtime/bufferLike.js

@@ -0,0 +1,28 @@
+function getObjectTag(value) {
+  return Object.prototype.toString.call(value);
+}
+
+export function isArrayBufferLike(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const tag = getObjectTag(value);
+  return tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]";
+}
+
+export function hasByteAddressableBuffer(value) {
+  return isArrayBufferLike(value?.buffer);
+}
+
+export function toUint8Array(value) {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (isArrayBufferLike(value)) {
+    return new Uint8Array(value);
+  }
+  return null;
+}

package/src/runtime/constants.js

@@ -0,0 +1,34 @@
+export const DrainPolicy = Object.freeze({
+  SINGLE_SHOT: "single-shot",
+  DRAIN_UNTIL_YIELD: "drain-until-yield",
+  DRAIN_TO_EMPTY: "drain-to-empty",
+});
+
+export const ExternalInterfaceDirection = Object.freeze({
+  INPUT: "input",
+  OUTPUT: "output",
+  BIDIRECTIONAL: "bidirectional",
+});
+
+export const ExternalInterfaceKind = Object.freeze({
+  CLOCK: "clock",
+  RANDOM: "random",
+  TIMER: "timer",
+  PUBSUB: "pubsub",
+  PROTOCOL: "protocol",
+  HTTP: "http",
+  FILESYSTEM: "filesystem",
+  PIPE: "pipe",
+  NETWORK: "network",
+  DATABASE: "database",
+  LOCAL_RUNTIME: "local-runtime",
+  HOST_SERVICE: "host-service",
+});
+
+export const DefaultManifestExports = Object.freeze({
+  pluginBytesSymbol: "plugin_get_manifest_flatbuffer",
+  pluginSizeSymbol: "plugin_get_manifest_flatbuffer_size",
+  flowBytesSymbol: "flow_get_manifest_flatbuffer",
+  flowSizeSymbol: "flow_get_manifest_flatbuffer_size",
+});
+

package/src/standards/index.js

@@ -0,0 +1,153 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+import { sharedModuleCatalog } from "./sharedCatalog.js";
+
+const require = createRequire(import.meta.url);
+let standardsCatalogPromise = null;
+let knownTypeCatalogPromise = null;
+
+function normalizeSchemaStem(value) {
+  const trimmed = String(value ?? "")
+    .trim()
+    .replace(/\\/g, "/")
+    .split("/")
+    .pop();
+  if (!trimmed) {
+    return "";
+  }
+  const withoutExtension = /\.(bfbs|fbs|json)$/i.test(trimmed)
+    ? trimmed.replace(/\.[^.]+$/, "")
+    : trimmed;
+  return withoutExtension.split(".").pop().toUpperCase();
+}
+
+function normalizeFileIdentifier(value) {
+  return String(value ?? "")
+    .trim()
+    .replace(/^\$/, "")
+    .toUpperCase();
+}
+
+function parseStandardsEntry([schemaCode, entry]) {
+  const idl = String(entry?.IDL ?? "");
+  const fileIdentifierMatch = idl.match(/file_identifier\s+"([^"]+)"/i);
+  const hashMatch = idl.match(/\/\/ Hash:\s*([a-f0-9]+)/i);
+  const versionMatch = idl.match(/\/\/ Version:\s*([^\n]+)/i);
+  return {
+    schemaCode: schemaCode.toUpperCase(),
+    schemaName: `${schemaCode.toUpperCase()}.fbs`,
+    fileIdentifier: fileIdentifierMatch
+      ? normalizeFileIdentifier(fileIdentifierMatch[1])
+      : null,
+    hash: hashMatch ? hashMatch[1].toLowerCase() : null,
+    version: versionMatch ? versionMatch[1].trim() : null,
+    files: Array.isArray(entry?.files) ? entry.files : [],
+  };
+}
+
+export async function loadStandardsCatalog() {
+  if (!standardsCatalogPromise) {
+    standardsCatalogPromise = (async () => {
+      const packageEntry = require.resolve("spacedatastandards.org");
+      const packageRoot = path.dirname(packageEntry);
+      const manifestPath = path.join(packageRoot, "dist", "manifest.json");
+      const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+      return Object.entries(manifest?.STANDARDS ?? {})
+        .map(parseStandardsEntry)
+        .sort((left, right) => left.schemaCode.localeCompare(right.schemaCode));
+    })();
+  }
+  return standardsCatalogPromise;
+}
+
+export async function loadKnownTypeCatalog() {
+  if (!knownTypeCatalogPromise) {
+    knownTypeCatalogPromise = loadStandardsCatalog().then((catalog) => [
+      ...catalog,
+      ...sharedModuleCatalog,
+    ]);
+  }
+  return knownTypeCatalogPromise;
+}
+
+export function resolveStandardsTypeRef(typeRef, catalog = []) {
+  const schemaStem = normalizeSchemaStem(typeRef?.schemaName);
+  const fileIdentifier = normalizeFileIdentifier(typeRef?.fileIdentifier);
+  if (!schemaStem && !fileIdentifier) {
+    return null;
+  }
+  return (
+    catalog.find((entry) => {
+      if (schemaStem && entry.schemaCode === schemaStem) {
+        return true;
+      }
+      if (fileIdentifier && entry.fileIdentifier === fileIdentifier) {
+        return true;
+      }
+      return false;
+    }) ?? null
+  );
+}
+
+function collectTypeRefs(manifest) {
+  const refs = [];
+  for (const method of Array.isArray(manifest?.methods) ? manifest.methods : []) {
+    for (const portsKey of ["inputPorts", "outputPorts"]) {
+      for (const port of Array.isArray(method?.[portsKey]) ? method[portsKey] : []) {
+        for (const typeSet of Array.isArray(port?.acceptedTypeSets)
+          ? port.acceptedTypeSets
+          : []) {
+          for (const allowedType of Array.isArray(typeSet?.allowedTypes)
+            ? typeSet.allowedTypes
+            : []) {
+            refs.push({
+              source: `${method?.methodId ?? "method"}.${port?.portId ?? "port"}`,
+              typeRef: allowedType,
+            });
+          }
+        }
+      }
+    }
+  }
+  for (const typeRef of Array.isArray(manifest?.schemasUsed)
+    ? manifest.schemasUsed
+    : []) {
+    refs.push({
+      source: "schemasUsed",
+      typeRef,
+    });
+  }
+  return refs;
+}
+
+export async function validateManifestAgainstStandardsCatalog(
+  manifest,
+  options = {},
+) {
+  const catalog = options.catalog ?? (await loadKnownTypeCatalog());
+  const sourceName = options.sourceName ?? "manifest";
+  const issues = [];
+  for (const { source, typeRef } of collectTypeRefs(manifest)) {
+    if (typeRef?.acceptsAnyFlatbuffer === true) {
+      continue;
+    }
+    const resolved = resolveStandardsTypeRef(typeRef, catalog);
+    if (!resolved) {
+      issues.push({
+        severity: "warning",
+        code: "unresolved-standards-type",
+        message:
+          `Type reference from ${source} does not resolve to a known ` +
+          "shared-module or `spacedatastandards.org` schema by schemaName " +
+          "or fileIdentifier.",
+        location: `${sourceName}.${source}`,
+      });
+    }
+  }
+  return {
+    catalog,
+    issues,
+  };
+}

package/src/standards/sharedCatalog.js

@@ -0,0 +1,196 @@
+const sharedModuleCatalogEntries = [
+  {
+    schemaCode: "TIMERTICK",
+    schemaName: "TimerTick.fbs",
+    fileIdentifier: "TICK",
+    source: "shared-module-runtime",
+  },
+  {
+    schemaCode: "HTTPREQUEST",
+    schemaName: "HttpRequest.fbs",
+    fileIdentifier: "HREQ",
+    source: "shared-module-runtime",
+  },
+  {
+    schemaCode: "HTTPRESPONSE",
+    schemaName: "HttpResponse.fbs",
+    fileIdentifier: "HRSP",
+    source: "shared-module-runtime",
+  },
+  {
+    schemaCode: "DETACHEDSIGNATURE",
+    schemaName: "DetachedSignature.fbs",
+    fileIdentifier: "SIGD",
+    source: "shared-module-security",
+  },
+  {
+    schemaCode: "FIELDPROTECTIONREQUEST",
+    schemaName: "FieldProtectionRequest.fbs",
+    fileIdentifier: "FPRQ",
+    source: "shared-module-security",
+  },
+  {
+    schemaCode: "FIELDSELECTIONBUNDLE",
+    schemaName: "FieldSelectionBundle.fbs",
+    fileIdentifier: "FSLB",
+    source: "shared-module-security",
+  },
+  {
+    schemaCode: "ENCRYPTEDFIELDSET",
+    schemaName: "EncryptedFieldSet.fbs",
+    fileIdentifier: "EFLD",
+    source: "shared-module-security",
+  },
+  {
+    schemaCode: "ANCHORRADIUSQUERY",
+    schemaName: "AnchorRadiusQuery.fbs",
+    fileIdentifier: "ARQY",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "OBSERVATIONBATCH",
+    schemaName: "ObservationBatch.fbs",
+    fileIdentifier: "OBSV",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "ASSOCIATIONBATCH",
+    schemaName: "AssociationBatch.fbs",
+    fileIdentifier: "ASSC",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "SAMPLEDORBIT",
+    schemaName: "SampledOrbit.fbs",
+    fileIdentifier: "SAMP",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "SENSORINPUT",
+    schemaName: "SensorInput.fbs",
+    fileIdentifier: "SENS",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "SENSORRESULT",
+    schemaName: "SensorResult.fbs",
+    fileIdentifier: "SRES",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "STATEVECTOR",
+    schemaName: "StateVector.fbs",
+    fileIdentifier: "STVC",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "STOREDRECORDREF",
+    schemaName: "StoredRecordRef.fbs",
+    fileIdentifier: "STRF",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "ALIGNEDRECORDBATCH",
+    schemaName: "AlignedRecordBatch.fbs",
+    fileIdentifier: "RECS",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "SQLQUERYREQUEST",
+    schemaName: "SqlQueryRequest.fbs",
+    fileIdentifier: "SQLQ",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "SQLQUERYRESULT",
+    schemaName: "SqlQueryResult.fbs",
+    fileIdentifier: "SQLR",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "PROTECTEDCATALOGENTRY",
+    schemaName: "ProtectedCatalogEntry.fbs",
+    fileIdentifier: "PRTC",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "PROXIMITYSELECTION",
+    schemaName: "ProximitySelection.fbs",
+    fileIdentifier: "PRXY",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "CIDREF",
+    schemaName: "CidRef.fbs",
+    fileIdentifier: "CIDR",
+    source: "shared-module-data",
+  },
+  {
+    schemaCode: "UDPDATAGRAM",
+    schemaName: "UdpDatagram.fbs",
+    fileIdentifier: "UDPG",
+    source: "shared-module-runtime",
+  },
+  {
+    schemaCode: "STATEREQUEST",
+    schemaName: "StateRequest.fbs",
+    fileIdentifier: "SREQ",
+    source: "shared-module-runtime",
+  },
+  {
+    schemaCode: "GRAPHDEFINITION",
+    schemaName: "GraphDefinition.fbs",
+    fileIdentifier: "FGDF",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "WEIGHTEDEDGELIST",
+    schemaName: "WeightedEdgeList.fbs",
+    fileIdentifier: "FELT",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "CSRGRAPH",
+    schemaName: "CSRGraph.fbs",
+    fileIdentifier: "FCSR",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "SHORTESTPATHREQUEST",
+    schemaName: "ShortestPathRequest.fbs",
+    fileIdentifier: "FSPR",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "SHORTESTPATHRESULT",
+    schemaName: "ShortestPathResult.fbs",
+    fileIdentifier: "FSPS",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "PATHREQUEST",
+    schemaName: "PathRequest.fbs",
+    fileIdentifier: "FPTR",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "PATHRESULT",
+    schemaName: "PathResult.fbs",
+    fileIdentifier: "FPTH",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "CATALOGQUERYREQUEST",
+    schemaName: "CatalogQueryRequest.fbs",
+    fileIdentifier: "CQRQ",
+    source: "orbpro-legacy",
+  },
+  {
+    schemaCode: "CATALOGQUERYRESULT",
+    schemaName: "CatalogQueryResult.fbs",
+    fileIdentifier: "CQRS",
+    source: "orbpro-legacy",
+  },
+];
+
+export const sharedModuleCatalog = Object.freeze(sharedModuleCatalogEntries);

package/src/transport/index.js

@@ -0,0 +1,8 @@
+export {
+  decryptBytesFromEnvelope,
+  decryptJsonFromEnvelope,
+  encryptBytesForRecipient,
+  encryptJsonForRecipient,
+  generateX25519Keypair,
+} from "./pki.js";
+