@xyo-network/dapp-kit-port 2.1.4 → 2.3.0

package/dist/node/index.mjs

@@ -467,11 +467,11 @@ import {
   validatePortFrame as validatePortFrame2
 } from "@xyo-network/dapp-kit";
 function registeredOperations(options) {
-  const operations = /* @__PURE__ */ new Map();
+  const operations2 = /* @__PURE__ */ new Map();
   for (const operation of options.operations) {
-    const key = applicationPortOperationKey(operation.portId, operation.operationId);
+    const key2 = applicationPortOperationKey(operation.portId, operation.operationId);
     const grant = applicationPortOperationGrant(options.grant, operation.portId, operation.operationId);
-    if (operations.has(key)) {
+    if (operations2.has(key2)) {
       throw new ApplicationPortProxyError(
         ApplicationPortProxyErrorCode.duplicateRequest,
         `Application-port operation is registered more than once: ${operation.portId}.${operation.operationId}`
@@ -483,15 +483,18 @@ function registeredOperations(options) {
         `Registered operation conflicts with attachment grant: ${operation.portId}.${operation.operationId}`
       );
     }
-    operations.set(key, operation);
+    operations2.set(key2, operation);
   }
-  return operations;
+  return operations2;
 }
 var ApplicationPortHostInstance = class {
+  cleanupErrors = [];
+  closePromise;
   isClosed = false;
   listener;
   operations;
   options;
+  ownedRequests = /* @__PURE__ */ new Set();
   requests = /* @__PURE__ */ new Map();
   constructor(options) {
     this.options = { ...options, grant: PortAttachmentGrantZod2.parse(options.grant) };
@@ -500,19 +503,42 @@ var ApplicationPortHostInstance = class {
     options.endpoint.addMessageListener(this.listener);
     options.endpoint.start?.();
   }
-  async close() {
-    if (this.isClosed) return;
+  close() {
+    return this.drain();
+  }
+  closeAdmission() {
+    if (this.closePromise !== void 0) return;
+    const completion = Promise.withResolvers();
+    this.closePromise = completion.promise;
+    void this.closePromise.catch(() => {
+    });
     this.isClosed = true;
-    this.options.endpoint.removeMessageListener(this.listener);
-    const completions = [];
-    for (const state of this.requests.values()) {
+    try {
+      this.options.endpoint.removeMessageListener(this.listener);
+    } catch (cause) {
+      this.cleanupErrors.push(cause);
+    }
+    for (const state of this.ownedRequests) {
       state.isCancelled = true;
       state.controller.abort(ApplicationPortProxyErrorCode.detached);
-      if (state.kind === "unary" && state.completion !== void 0) completions.push(state.completion);
-      if (state.kind === "stream") this.collectStreamClosePromises(state, completions);
     }
-    await Promise.allSettled(completions);
-    this.requests.clear();
+    void Promise.resolve().then(async () => {
+      const outcomes = await Promise.allSettled([...this.ownedRequests].map(async (state) => {
+        if (state.kind === "unary") await state.completion;
+        else await this.cleanupStream(state, ApplicationPortProxyErrorCode.detached);
+      }));
+      for (const outcome of outcomes) {
+        if (outcome.status === "rejected") this.cleanupErrors.push(outcome.reason);
+      }
+      this.requests.clear();
+      if (this.cleanupErrors.length > 0) {
+        throw new AggregateError([...this.cleanupErrors], "Application-port host cleanup failed");
+      }
+    }).then(completion.resolve, completion.reject);
+  }
+  drain() {
+    this.closeAdmission();
+    return this.closePromise;
   }
   cancelAcknowledgement(frame) {
     return parseApplicationPortFrame({
@@ -534,21 +560,35 @@ var ApplicationPortHostInstance = class {
       await state.completion;
       return;
     }
-    await state.openPromise;
-    if (state.pumpPromise !== void 0) await state.pumpPromise;
-    await state.source?.cancel?.(frame.reasonCode);
+    await this.cleanupStream(state, frame.reasonCode);
     if (!this.isClosed && !state.isTerminal) {
       state.isTerminal = true;
-      this.post(this.cancelAcknowledgement(frame));
+      if (state.cleanupFailed) this.postError(frame, ApplicationPortProxyErrorCode.hostFailure);
+      else this.post(this.cancelAcknowledgement(frame));
     }
     this.requests.delete(frame.requestId);
   }
-  collectStreamClosePromises(state, completions) {
-    if (state.openPromise !== void 0) completions.push(state.openPromise);
-    if (state.pumpPromise !== void 0) completions.push(state.pumpPromise);
-    if (state.source?.cancel !== void 0) {
-      completions.push(state.source.cancel(ApplicationPortProxyErrorCode.detached));
-    }
+  cleanupStream(state, reasonCode) {
+    if (state.cleanupPromise !== void 0) return state.cleanupPromise;
+    const completion = Promise.withResolvers();
+    state.cleanupPromise = completion.promise;
+    void Promise.resolve().then(async () => {
+      for (const work of [() => state.openPromise, () => state.pumpPromise, () => state.source?.cancel?.(reasonCode)]) {
+        try {
+          await work();
+        } catch (cause) {
+          state.cleanupFailed = true;
+          this.cleanupErrors.push(cause);
+        }
+      }
+    }).catch((cause) => {
+      state.cleanupFailed = true;
+      this.cleanupErrors.push(cause);
+    }).finally(() => {
+      this.ownedRequests.delete(state);
+      completion.resolve();
+    });
+    return state.cleanupPromise;
   }
   dispatchStart(frame) {
     const operation = this.operations.get(applicationPortOperationKey(frame.portId, frame.operationId));
@@ -594,7 +634,10 @@ var ApplicationPortHostInstance = class {
       ...frame.frameKind === "stream-resume" ? { resumeCursor: frame.resumeCursor } : {}
     };
     this.requests.set(frame.requestId, state);
-    state.openPromise = this.runStreamOpen(state, frame, operation);
+    this.ownedRequests.add(state);
+    const completion = Promise.withResolvers();
+    state.openPromise = completion.promise;
+    void this.runStreamOpen(state, frame, operation).then(completion.resolve, completion.reject);
   }
   post(frame) {
     if (!this.isClosed) this.options.endpoint.send(frame);
@@ -604,8 +647,10 @@ var ApplicationPortHostInstance = class {
   }
   async pump(state) {
     if (state.pumpPromise !== void 0 || state.source === void 0 || state.isTerminal || state.isCancelled) return;
-    const pumping = this.pumpOnce(state);
+    const completion = Promise.withResolvers();
+    const pumping = completion.promise;
     state.pumpPromise = pumping;
+    void this.pumpOnce(state).then(completion.resolve, completion.reject);
     await pumping;
     if (state.pumpPromise === pumping) state.pumpPromise = void 0;
   }
@@ -677,8 +722,8 @@ var ApplicationPortHostInstance = class {
   async runStreamOpen(state, frame, operation) {
     try {
       const source = await this.startStreamSource(state, frame, operation);
-      this.verifyStreamSource(source, frame, state.grant);
       state.source = source;
+      this.verifyStreamSource(source, frame, state.grant);
       state.lastSequence = source.nextSequence - 1;
       state.resumeCursor = source.resumeCursor;
       if (state.isCancelled || this.isClosed) return;
@@ -697,6 +742,7 @@ var ApplicationPortHostInstance = class {
         state.isTerminal = true;
         this.post(applicationPortErrorFrame(this.options.grant, frame, this.mapError(frame, error)));
         this.requests.delete(frame.requestId);
+        void this.cleanupStream(state, ApplicationPortProxyErrorCode.hostFailure);
       }
     }
   }
@@ -728,6 +774,7 @@ var ApplicationPortHostInstance = class {
         this.post(this.cancelAcknowledgement(frame));
       }
       this.requests.delete(frame.requestId);
+      this.ownedRequests.delete(state);
     }
   }
   async sendNext(state) {
@@ -745,6 +792,7 @@ var ApplicationPortHostInstance = class {
         ...read.resumeCursor === void 0 ? {} : { resumeCursor: read.resumeCursor }
       }));
       this.requests.delete(state.frame.requestId);
+      this.ownedRequests.delete(state);
       return false;
     }
     if (source.resumable && read.value.resumeCursor === void 0) {
@@ -797,7 +845,10 @@ var ApplicationPortHostInstance = class {
       kind: "unary"
     };
     this.requests.set(frame.requestId, state);
-    state.completion = this.runUnary(state, frame, operation);
+    this.ownedRequests.add(state);
+    const completion = Promise.withResolvers();
+    state.completion = completion.promise;
+    void this.runUnary(state, frame, operation).then(completion.resolve, completion.reject);
   }
   terminateStreamWithError(state, cause, code) {
     const source = state.source;
@@ -813,6 +864,9 @@ var ApplicationPortHostInstance = class {
       error
     }));
     this.requests.delete(state.frame.requestId);
+    state.isCancelled = true;
+    state.controller.abort(ApplicationPortProxyErrorCode.hostFailure);
+    void this.cleanupStream(state, ApplicationPortProxyErrorCode.hostFailure);
   }
   verifyStreamSource(source, frame, grant) {
     const resumeMismatch = frame.frameKind === "stream-resume" && (source.streamId !== frame.streamId || source.nextSequence !== frame.lastAcceptedSequence + 1);
@@ -923,6 +977,233 @@ function serializeApplicationPortWireMessage(message, maximumFrameBytes) {
   return source;
 }
 
+// src/engineApplicationPortHost.ts
+import {
+  DappEngineSystemReferenceZod,
+  PortAttachmentGrantZod as PortAttachmentGrantZod4,
+  validateDappEngineSystemReference
+} from "@xyo-network/dapp-kit";
+
+// src/engineOperationRecovery.ts
+import {
+  DappOperationRecoveryBindingZod,
+  DappOperationRecoveryProfileZod,
+  validateDappOperationRecoveryAdmission
+} from "@xyo-network/dapp-kit";
+
+// src/enginePortAdmissionError.ts
+var DappEnginePortAdmissionError = class extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.name = "DappEnginePortAdmissionError";
+    this.code = code;
+  }
+};
+
+// src/engineOperationRecovery.ts
+var key = (portId, operationId) => JSON.stringify([portId, operationId]);
+function bindEngineOperationRecovery(options, operations2, reference, target2) {
+  if (options === void 0) return void 0;
+  const parsed = DappOperationRecoveryProfileZod.safeParse(options.profile);
+  if (!parsed.success || typeof options.readSnapshot !== "function") throw new DappEnginePortAdmissionError("recovery.profile-invalid");
+  const profile = parsed.data;
+  if (profile.operations.length !== operations2.length) throw new DappEnginePortAdmissionError("recovery.profile-mismatch");
+  const requirements = /* @__PURE__ */ new Map();
+  for (const requirement of profile.operations) {
+    if (requirement.recovery.kind !== "read-only") Object.freeze(requirement.recovery.requiredGuarantees);
+    Object.freeze(requirement.recovery);
+    requirements.set(key(requirement.portId, requirement.operationId), Object.freeze(requirement));
+  }
+  for (const binding2 of operations2) {
+    const requirement = requirements.get(key(binding2.operation.portId, binding2.operation.operationId));
+    if (requirement === void 0 || requirement.recovery.kind === "read-only" !== (binding2.access === "read")) {
+      throw new DappEnginePortAdmissionError("recovery.profile-mismatch");
+    }
+  }
+  const parsedBinding = DappOperationRecoveryBindingZod.safeParse({
+    reference,
+    dappId: target2.status.dappId,
+    hostSessionId: target2.status.hostSessionId,
+    planId: target2.status.planId,
+    network: target2.declaration.network,
+    authorityScopeId: options.authorityScopeId
+  });
+  if (!parsedBinding.success) throw new DappEnginePortAdmissionError("recovery.binding-invalid");
+  Object.freeze(parsedBinding.data.reference);
+  Object.freeze(parsedBinding.data.network);
+  const binding = Object.freeze(parsedBinding.data);
+  const readSnapshot = options.readSnapshot.bind(options);
+  return (portId, operationId) => {
+    const requirement = requirements.get(key(portId, operationId));
+    if (requirement.recovery.kind === "read-only") return;
+    let snapshot;
+    try {
+      snapshot = readSnapshot(requirement, binding);
+    } catch {
+      throw new DappEnginePortAdmissionError("recovery.unavailable");
+    }
+    let admission;
+    try {
+      admission = validateDappOperationRecoveryAdmission(requirement, binding, snapshot);
+    } catch {
+      throw new DappEnginePortAdmissionError("recovery.snapshot-invalid");
+    }
+    if (!admission.success) throw new DappEnginePortAdmissionError(admission.issue.code);
+  };
+}
+
+// src/engineApplicationPortHost.ts
+function deferredEndpoint(source) {
+  let listener;
+  let attached = false;
+  let closed = false;
+  const endpoint = {
+    addMessageListener: (value) => {
+      listener = value;
+    },
+    removeMessageListener: (value) => {
+      closed = true;
+      if (attached) source.removeMessageListener(value);
+      listener = void 0;
+    },
+    send: (message) => source.send(message)
+  };
+  return {
+    endpoint,
+    activate: () => {
+      if (closed || listener === void 0) throw new DappEnginePortAdmissionError("engine.system-unavailable");
+      attached = true;
+      source.addMessageListener(listener);
+      if (!closed) source.start?.();
+    }
+  };
+}
+function target(readStatus, reference, grant) {
+  const result = validateDappEngineSystemReference(readStatus(), reference);
+  if (!result.success) throw new DappEnginePortAdmissionError(result.issue.code);
+  const status = result.value.status;
+  if (grant.dappId !== status.dappId || grant.hostSessionId !== status.hostSessionId || grant.planId !== status.planId || grant.systemInstanceId !== status.systemInstanceId) {
+    throw new DappEnginePortAdmissionError("engine.attachment-mismatch");
+  }
+  return result.value;
+}
+function operations(bindings, grant, readTarget, admitRecovery) {
+  const keys = /* @__PURE__ */ new Set();
+  return bindings.map(({ access, operation }) => {
+    const {
+      portId,
+      operationId,
+      streaming
+    } = operation;
+    const key2 = applicationPortOperationKey(portId, operationId);
+    const allowed = grant.operations.find((value) => value.portId === portId && value.operationId === operationId);
+    if (access !== "read" && access !== "write" || keys.has(key2) || allowed?.streaming !== streaming) {
+      throw new DappEnginePortAdmissionError("engine.operation-binding-invalid");
+    }
+    keys.add(key2);
+    const authorize = () => {
+      const capability = readTarget().status.writeCapabilities.find((value) => value.portId === portId && value.operationId === operationId);
+      if (access === "read" && capability !== void 0) throw new DappEnginePortAdmissionError("engine.operation-access-invalid");
+      if (access === "write" && capability?.writable !== true) throw new DappEnginePortAdmissionError("engine.operation-not-writable");
+    };
+    const admit = () => {
+      authorize();
+      if (access !== "write" || admitRecovery === void 0) {
+        return;
+      }
+      admitRecovery(portId, operationId);
+      authorize();
+    };
+    if (operation.streaming) {
+      const open = operation.open.bind(operation);
+      const resume = operation.resume?.bind(operation);
+      return Object.freeze({
+        portId,
+        operationId,
+        streaming: true,
+        open: (context) => {
+          admit();
+          return open(context);
+        },
+        ...resume === void 0 ? {} : {
+          resume: (context) => {
+            admit();
+            return resume(context);
+          }
+        }
+      });
+    }
+    const handle = operation.handle.bind(operation);
+    return Object.freeze({
+      portId,
+      operationId,
+      streaming: false,
+      handle: (context) => {
+        admit();
+        return handle(context);
+      }
+    });
+  });
+}
+async function createDappEngineApplicationPortHost(options) {
+  const reference = DappEngineSystemReferenceZod.parse(options.reference);
+  const grant = PortAttachmentGrantZod4.parse(options.grant);
+  const readStatus = options.engine.status.bind(options.engine);
+  const readTarget = () => target(readStatus, reference, grant);
+  const selected = readTarget();
+  const admitRecovery = bindEngineOperationRecovery(options.recovery, options.operations, reference, selected);
+  const boundOperations = operations(options.operations, grant, readTarget, admitRecovery);
+  const deferred = deferredEndpoint(options.endpoint);
+  const mapDomainError = options.mapError.bind(options);
+  const disconnect = options.disconnect.bind(options);
+  const binding = options.engine.bindSystemWork(reference, () => {
+    const host = createApplicationPortHost({
+      authenticatedPrincipalId: options.authenticatedPrincipalId,
+      endpoint: deferred.endpoint,
+      grant,
+      now: options.now,
+      onProtocolError: options.onProtocolError,
+      operations: boundOperations,
+      mapError: (error) => error instanceof DappEnginePortAdmissionError ? { code: error.code, retriable: false } : mapDomainError(error)
+    });
+    let disconnected;
+    return {
+      close: () => {
+        host.closeAdmission();
+        disconnected = (async () => {
+          await disconnect();
+        })();
+        void disconnected.catch(() => {
+        });
+      },
+      drain: async () => {
+        const outcomes = await Promise.allSettled([host.drain(), disconnected]);
+        const errors = outcomes.filter((outcome) => outcome.status === "rejected").map((outcome) => outcome.reason);
+        if (errors.length > 0) throw new AggregateError(errors, "Engine application-port drainage failed");
+      }
+    };
+  });
+  try {
+    deferred.activate();
+    readTarget();
+  } catch (cause) {
+    try {
+      await binding.close();
+    } catch (cleanup) {
+      throw new AggregateError([cause, cleanup], "Engine application-port setup and cleanup failed", { cause: cleanup });
+    }
+    throw cause;
+  }
+  return Object.freeze({
+    close: () => binding.close(),
+    closeAdmission: () => {
+      void binding.close();
+    },
+    drain: () => binding.close()
+  });
+}
+
 // src/webSocketApplicationPortClient.ts
 import { PortFrameZod as PortFrameZod3 } from "@xyo-network/dapp-kit";
 var WebSocketApplicationPortClientErrorCode = {
@@ -1165,6 +1446,7 @@ export {
   ApplicationPortWireError,
   ApplicationPortWireErrorCode,
   ApplicationPortWireMessageZod,
+  DappEnginePortAdmissionError,
   WebSocketApplicationPortClientError,
   WebSocketApplicationPortClientErrorCode,
   applicationPortErrorFrame,
@@ -1174,6 +1456,7 @@ export {
   connectWebSocketApplicationPort,
   createApplicationPortClient,
   createApplicationPortHost,
+  createDappEngineApplicationPortHost,
   isApplicationPortFrame,
   parseApplicationPortFrame,
   parseApplicationPortWireText,