space-data-module-sdk 0.2.5 → 0.2.7

package/src/compiler/emceptionNode.js

@@ -16,8 +16,6 @@ const FILE_URL_FETCH_PATCH_FLAG =
   "__spaceDataModuleSdkFileUrlFetchPatched";
 
 let patchedEmceptionRootPromise = null;
-let emceptionInstancePromise = null;
-let emceptionExecutionQueue = Promise.resolve();
 
 function installNodeRuntimeShims() {
   if (typeof globalThis.require !== "function") {
@@ -175,43 +173,62 @@ async function preparePatchedEmceptionRoot() {
   return patchedEmceptionRootPromise;
 }
 
-export async function loadEmception() {
-  if (!emceptionInstancePromise) {
-    emceptionInstancePromise = (async () => {
-      installNodeRuntimeShims();
-      const patchedRoot = await preparePatchedEmceptionRoot();
-      const moduleUrl = pathToFileURL(path.join(patchedRoot, "emception.mjs")).href;
-      const { default: Emception } = await import(moduleUrl);
-      const emception = new Emception({
-        baseUrl: pathToFileURL(`${patchedRoot}${path.sep}`).href,
+class EmceptionController {
+  #instancePromise = null;
+  #executionQueue = Promise.resolve();
+
+  async load() {
+    if (!this.#instancePromise) {
+      this.#instancePromise = (async () => {
+        installNodeRuntimeShims();
+        const patchedRoot = await preparePatchedEmceptionRoot();
+        const moduleUrl = pathToFileURL(path.join(patchedRoot, "emception.mjs")).href;
+        const { default: Emception } = await import(moduleUrl);
+        const emception = new Emception({
+          baseUrl: pathToFileURL(`${patchedRoot}${path.sep}`).href,
+        });
+        await emception.init();
+        return emception;
+      })().catch((error) => {
+        this.#instancePromise = null;
+        throw error;
       });
-      await emception.init();
-      return emception;
-    })().catch((error) => {
-      emceptionInstancePromise = null;
-      throw error;
+    }
+
+    return this.#instancePromise;
+  }
+
+  async withLock(task) {
+    const previous = this.#executionQueue;
+    let release = () => {};
+    this.#executionQueue = new Promise((resolve) => {
+      release = resolve;
     });
+    await previous.catch(() => {});
+    try {
+      const emception = await this.load().catch((error) => {
+        if (!error.code) {
+          error.code = "EMCEPTION_LOAD_FAILED";
+        }
+        throw error;
+      });
+      return await task(emception);
+    } finally {
+      release();
+    }
   }
+}
+
+const sharedEmceptionController = new EmceptionController();
 
-  return emceptionInstancePromise;
+export function getSharedEmceptionController() {
+  return sharedEmceptionController;
+}
+
+export async function loadEmception() {
+  return sharedEmceptionController.load();
 }
 
 export async function runWithEmceptionLock(task) {
-  const previous = emceptionExecutionQueue;
-  let release = () => {};
-  emceptionExecutionQueue = new Promise((resolve) => {
-    release = resolve;
-  });
-  await previous.catch(() => {});
-  try {
-    const emception = await loadEmception().catch((error) => {
-      if (!error.code) {
-        error.code = "EMCEPTION_LOAD_FAILED";
-      }
-      throw error;
-    });
-    return await task(emception);
-  } finally {
-    release();
-  }
+  return sharedEmceptionController.withLock(task);
 }

package/src/compiler/index.d.ts

@@ -0,0 +1,24 @@
+export type {
+  CompilationResult,
+  ProtectedArtifact,
+} from "../index.js";
+
+export {
+  cleanupCompilation,
+  compileModuleFromSource,
+  createRecipientKeypairHex,
+  protectModuleArtifact,
+} from "../index.js";
+
+export type {
+  EmceptionCommandResult,
+  SharedEmceptionFileContent,
+  SharedEmceptionHandle,
+  SharedEmceptionSession,
+} from "./emception.js";
+
+export {
+  createSharedEmceptionSession,
+  loadSharedEmception,
+  withSharedEmception,
+} from "./emception.js";

package/src/compiler/index.js

@@ -5,3 +5,8 @@ export {
   protectModuleArtifact,
 } from "./compileModule.js";
 
+export {
+  createSharedEmceptionSession,
+  loadSharedEmception,
+  withSharedEmception,
+} from "./emception.js";

package/src/compliance/pluginCompliance.js

@@ -8,6 +8,8 @@ import {
   ExternalInterfaceDirection,
   ExternalInterfaceKind,
   InvokeSurface,
+  ProtocolRole,
+  ProtocolTransportKind,
   RuntimeTarget,
 } from "../runtime/constants.js";
 
@@ -59,6 +61,8 @@ const ExternalInterfaceDirectionSet = new Set(
   Object.values(ExternalInterfaceDirection),
 );
 const ExternalInterfaceKindSet = new Set(Object.values(ExternalInterfaceKind));
+const ProtocolRoleSet = new Set(Object.values(ProtocolRole));
+const ProtocolTransportKindSet = new Set(Object.values(ProtocolTransportKind));
 const BrowserIncompatibleCapabilitySet = new Set([
   "filesystem",
   "pipe",
@@ -120,6 +124,57 @@ function hasNonEmptyByteSequence(value) {
   return false;
 }
 
+function normalizeTypeIdentityString(value) {
+  if (!isNonEmptyString(value)) {
+    return null;
+  }
+  return value.trim().toLowerCase();
+}
+
+function normalizeTypeIdentityBytes(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  const bytes = ArrayBuffer.isView(value)
+    ? Array.from(value)
+    : Array.isArray(value)
+      ? value
+      : null;
+  if (!bytes || bytes.length === 0) {
+    return null;
+  }
+  return bytes
+    .map((entry) => Number(entry).toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function allowedTypesReferToSameLogicalSchema(left, right) {
+  const leftSchemaName = normalizeTypeIdentityString(left?.schemaName);
+  const rightSchemaName = normalizeTypeIdentityString(right?.schemaName);
+  if (leftSchemaName && rightSchemaName && leftSchemaName === rightSchemaName) {
+    return true;
+  }
+
+  const leftFileIdentifier = normalizeTypeIdentityString(left?.fileIdentifier);
+  const rightFileIdentifier = normalizeTypeIdentityString(right?.fileIdentifier);
+  if (
+    leftFileIdentifier &&
+    rightFileIdentifier &&
+    leftFileIdentifier === rightFileIdentifier
+  ) {
+    return true;
+  }
+
+  const leftSchemaHash = normalizeTypeIdentityBytes(left?.schemaHash);
+  const rightSchemaHash = normalizeTypeIdentityBytes(right?.schemaHash);
+  if (leftSchemaHash && rightSchemaHash && leftSchemaHash === rightSchemaHash) {
+    return true;
+  }
+
+  return false;
+}
+
 function normalizePayloadWireFormatName(value) {
   if (value === undefined || value === null || value === "") {
     return "flatbuffer";
@@ -151,7 +206,13 @@ function validateStringField(issues, value, location, label) {
   return true;
 }
 
-function validateIntegerField(issues, value, location, label, { min = null } = {}) {
+function validateIntegerField(
+  issues,
+  value,
+  location,
+  label,
+  { min = null, max = null } = {},
+) {
   if (!Number.isInteger(value)) {
     pushIssue(issues, "error", "invalid-integer", `${label} must be an integer.`, location);
     return false;
@@ -166,6 +227,16 @@ function validateIntegerField(issues, value, location, label, { min = null } = {
     );
     return false;
   }
+  if (max !== null && value > max) {
+    pushIssue(
+      issues,
+      "error",
+      "integer-range",
+      `${label} must be less than or equal to ${max}.`,
+      location,
+    );
+    return false;
+  }
   return true;
 }
 
@@ -182,6 +253,61 @@ function validateOptionalIntegerField(
   return validateIntegerField(issues, value, location, label, options);
 }
 
+function validateOptionalBooleanField(issues, value, location, label) {
+  if (value === undefined || value === null) {
+    return true;
+  }
+  if (typeof value !== "boolean") {
+    pushIssue(
+      issues,
+      "error",
+      "invalid-boolean",
+      `${label} must be a boolean when present.`,
+      location,
+    );
+    return false;
+  }
+  return true;
+}
+
+function validateOptionalStringField(issues, value, location, label) {
+  if (value === undefined || value === null) {
+    return true;
+  }
+  return validateStringField(issues, value, location, label);
+}
+
+function normalizeProtocolTransportKind(value) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized === "websocket") {
+    return ProtocolTransportKind.WS;
+  }
+  if (normalized === "pipe") {
+    return ProtocolTransportKind.WASI_PIPE;
+  }
+  return normalized;
+}
+
+function normalizeProtocolRole(value) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized === "handler") {
+    return ProtocolRole.HANDLE;
+  }
+  return normalized;
+}
+
 function validateAllowedType(type, issues, location) {
   if (!type || typeof type !== "object" || Array.isArray(type)) {
     pushIssue(issues, "error", "invalid-type-record", "Allowed type entries must be objects.", location);
@@ -307,6 +433,35 @@ function validateAcceptedTypeSet(typeSet, issues, location) {
   typeSet.allowedTypes.forEach((allowedType, index) => {
     validateAllowedType(allowedType, issues, `${location}.allowedTypes[${index}]`);
   });
+
+  const regularConcreteTypes = [];
+  const alignedTypes = [];
+
+  typeSet.allowedTypes.forEach((allowedType, index) => {
+    const wireFormat = normalizePayloadWireFormatName(allowedType?.wireFormat);
+    if (wireFormat === "aligned-binary") {
+      alignedTypes.push({ allowedType, index });
+      return;
+    }
+    if (wireFormat === "flatbuffer" && allowedType?.acceptsAnyFlatbuffer !== true) {
+      regularConcreteTypes.push({ allowedType, index });
+    }
+  });
+
+  alignedTypes.forEach(({ allowedType, index }) => {
+    const hasRegularFallback = regularConcreteTypes.some(({ allowedType: regularType }) =>
+      allowedTypesReferToSameLogicalSchema(allowedType, regularType),
+    );
+    if (!hasRegularFallback) {
+      pushIssue(
+        issues,
+        "error",
+        "missing-flatbuffer-fallback",
+        "Aligned-binary allowed types must be paired with a regular flatbuffer fallback for the same schema in the same acceptedTypeSet.",
+        `${location}.allowedTypes[${index}]`,
+      );
+    }
+  });
 }
 
 function validatePort(port, issues, location, label) {
@@ -576,6 +731,85 @@ function validateProtocol(protocol, issues, location, methodLookup, declaredCapa
       );
     }
   }
+  const wireIdValid = validateStringField(
+    issues,
+    protocol.wireId,
+    `${location}.wireId`,
+    "Protocol wireId",
+  );
+  const normalizedTransportKind = normalizeProtocolTransportKind(
+    protocol.transportKind,
+  );
+  if (!validateStringField(
+    issues,
+    protocol.transportKind,
+    `${location}.transportKind`,
+    "Protocol transportKind",
+  )) {
+    // already reported
+  } else if (!ProtocolTransportKindSet.has(normalizedTransportKind)) {
+    pushIssue(
+      issues,
+      "error",
+      "unknown-protocol-transport-kind",
+      `Protocol "${protocol.protocolId ?? "protocol"}" transportKind must be one of: ${Array.from(ProtocolTransportKindSet).join(", ")}.`,
+      `${location}.transportKind`,
+    );
+  }
+  const normalizedRole = normalizeProtocolRole(protocol.role);
+  if (!validateStringField(
+    issues,
+    protocol.role,
+    `${location}.role`,
+    "Protocol role",
+  )) {
+    // already reported
+  } else if (!ProtocolRoleSet.has(normalizedRole)) {
+    pushIssue(
+      issues,
+      "error",
+      "unknown-protocol-role",
+      `Protocol "${protocol.protocolId ?? "protocol"}" role must be one of: ${Array.from(ProtocolRoleSet).join(", ")}.`,
+      `${location}.role`,
+    );
+  }
+  validateOptionalStringField(
+    issues,
+    protocol.specUri,
+    `${location}.specUri`,
+    "Protocol specUri",
+  );
+  validateOptionalStringField(
+    issues,
+    protocol.discoveryKey,
+    `${location}.discoveryKey`,
+    "Protocol discoveryKey",
+  );
+  validateOptionalBooleanField(
+    issues,
+    protocol.autoInstall,
+    `${location}.autoInstall`,
+    "Protocol autoInstall",
+  );
+  validateOptionalBooleanField(
+    issues,
+    protocol.advertise,
+    `${location}.advertise`,
+    "Protocol advertise",
+  );
+  validateOptionalBooleanField(
+    issues,
+    protocol.requireSecureTransport,
+    `${location}.requireSecureTransport`,
+    "Protocol requireSecureTransport",
+  );
+  validateOptionalIntegerField(
+    issues,
+    protocol.defaultPort,
+    `${location}.defaultPort`,
+    "Protocol defaultPort",
+    { min: 0, max: 65535 },
+  );
   if (
     protocolIdValid &&
     Array.isArray(declaredCapabilities) &&
@@ -590,6 +824,77 @@ function validateProtocol(protocol, issues, location, methodLookup, declaredCapa
       location,
     );
   }
+  if (
+    protocolIdValid &&
+    normalizedRole &&
+    (normalizedRole === ProtocolRole.HANDLE ||
+      normalizedRole === ProtocolRole.BOTH) &&
+    Array.isArray(declaredCapabilities) &&
+    !declaredCapabilities.includes("protocol_handle")
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-handle-protocol-capability",
+      `Protocol "${protocol.protocolId}" with role "${normalizedRole}" requires the "protocol_handle" capability.`,
+      location,
+    );
+  }
+  if (
+    protocolIdValid &&
+    normalizedRole &&
+    (normalizedRole === ProtocolRole.DIAL ||
+      normalizedRole === ProtocolRole.BOTH) &&
+    Array.isArray(declaredCapabilities) &&
+    !declaredCapabilities.includes("protocol_dial")
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-dial-protocol-capability",
+      `Protocol "${protocol.protocolId}" with role "${normalizedRole}" requires the "protocol_dial" capability.`,
+      location,
+    );
+  }
+  if (
+    protocol.advertise === true &&
+    normalizedRole === ProtocolRole.DIAL
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "protocol-advertise-role-conflict",
+      `Protocol "${protocol.protocolId ?? "protocol"}" cannot advertise when role is "dial".`,
+      `${location}.advertise`,
+    );
+  }
+  if (
+    normalizedTransportKind === ProtocolTransportKind.LIBP2P &&
+    Array.isArray(declaredCapabilities) &&
+    !declaredCapabilities.includes("ipfs")
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-ipfs-capability",
+      `Protocol "${protocol.protocolId ?? "protocol"}" with transportKind "libp2p" requires the "ipfs" capability.`,
+      location,
+    );
+  }
+  if (
+    wireIdValid &&
+    normalizedTransportKind === ProtocolTransportKind.WS &&
+    protocol.defaultPort === 443 &&
+    protocol.requireSecureTransport !== true
+  ) {
+    pushIssue(
+      issues,
+      "warning",
+      "insecure-secure-port-hint",
+      `Protocol "${protocol.protocolId ?? "protocol"}" uses defaultPort 443 without requireSecureTransport=true.`,
+      `${location}.defaultPort`,
+    );
+  }
 }
 
 function validateRuntimeTargets(runtimeTargets, declaredCapabilities, issues, sourceName) {