@xyo-network/dapp-kit-port 3.0.1 → 3.1.0

package/dist/browser/index.mjs

@@ -2,11 +2,14 @@
 import {
   canonicalizeIJson,
   PortAttachmentGrantZod,
+  PortFrameSchemaVersionZod,
+  portStreamResumeNextSequence,
+  portStreamTerminalMatches,
   validatePortFrame
 } from "@xyo-network/dapp-kit";
 
 // src/applicationPortModel.ts
-import { PortFrameSchema, PortFrameZod } from "@xyo-network/dapp-kit";
+import { PortFrameAnyVersionZod, PortFrameSchema } from "@xyo-network/dapp-kit";
 var ApplicationPortProxyErrorCode = {
   cancelled: "port.cancelled",
   detached: "port.detached",
@@ -58,7 +61,7 @@ function applicationPortOperationGrant(grant, portId, operationId) {
 function applicationPortFrameBase(grant, frame) {
   return {
     schema: PortFrameSchema,
-    schemaVersion: 1,
+    schemaVersion: frame.schemaVersion ?? 1,
     dappId: grant.dappId,
     protocolVersion: grant.protocolVersion,
     planId: grant.planId,
@@ -72,7 +75,7 @@ function applicationPortFrameBase(grant, frame) {
   };
 }
 function parseApplicationPortFrame(value) {
-  return PortFrameZod.parse(value);
+  return PortFrameAnyVersionZod.parse(value);
 }
 function applicationPortErrorFrame(grant, frame, error) {
   return parseApplicationPortFrame({
@@ -87,13 +90,21 @@ var ApplicationPortStreamInstance = class {
   requestId;
   streamId;
   client;
+  openingProgress;
   state;
   constructor(client, state, streamId) {
     this.client = client;
+    this.openingProgress = Object.freeze({
+      nextSequence: state.lastAcceptedSequence + 1,
+      ...state.resumeCursor === void 0 ? {} : { resumeCursor: state.resumeCursor }
+    });
     this.requestId = state.frame.requestId;
     this.state = state;
     this.streamId = streamId;
   }
+  get initialProgress() {
+    return this.openingProgress;
+  }
   [Symbol.asyncIterator]() {
     return this;
   }
@@ -119,7 +130,11 @@ var ApplicationPortClientInstance = class {
   options;
   requests = /* @__PURE__ */ new Map();
   constructor(options) {
-    this.options = { ...options, grant: PortAttachmentGrantZod.parse(options.grant) };
+    this.options = {
+      ...options,
+      frameSchemaVersion: PortFrameSchemaVersionZod.parse(options.frameSchemaVersion ?? 1),
+      grant: PortAttachmentGrantZod.parse(options.grant)
+    };
     this.listener = (message) => this.receive(message);
     options.endpoint.addMessageListener(this.listener);
     options.endpoint.start?.();
@@ -188,17 +203,21 @@ var ApplicationPortClientInstance = class {
       );
     }
     this.verifyCredit(options.credit, 0, grant);
+    const version = this.options.frameSchemaVersion ?? 1;
+    if (version === 1 && (options.lastAcceptedSequence === void 0 || options.nextSequence !== void 0) || version === 2 && (options.nextSequence === void 0 || options.lastAcceptedSequence !== void 0)) {
+      throw new ApplicationPortProxyError(ApplicationPortProxyErrorCode.streamStateInvalid, "Resume progress does not match the selected frame schema version");
+    }
     const frame = parseApplicationPortFrame({
       ...this.newFrameBase(options),
       frameKind: "stream-resume",
       streamId: options.streamId,
-      lastAcceptedSequence: options.lastAcceptedSequence,
+      ...version === 2 ? { nextSequence: options.nextSequence } : { lastAcceptedSequence: options.lastAcceptedSequence },
       resumeCursor: options.resumeCursor,
       credit: options.credit
     });
     const state = this.streamState(frame, grant, options.credit);
     state.availableCredit = options.credit;
-    state.lastAcceptedSequence = options.lastAcceptedSequence;
+    state.lastAcceptedSequence = portStreamResumeNextSequence(frame) - 1;
     state.resumeCursor = options.resumeCursor;
     state.streamId = options.streamId;
     this.requests.set(frame.requestId, state);
@@ -269,12 +288,13 @@ var ApplicationPortClientInstance = class {
     }
     return applicationPortFrameBase(this.options.grant, {
       ...options,
+      schemaVersion: this.options.frameSchemaVersion,
       requestId: this.options.nextRequestId()
     });
   }
   openStream(state, frame) {
     const grant = state.grant;
-    const resumeMismatch = state.lastAcceptedSequence > 0 && frame.nextSequence !== state.lastAcceptedSequence + 1;
+    const resumeMismatch = state.frame.frameKind === "stream-resume" && frame.nextSequence !== state.lastAcceptedSequence + 1;
     if (state.isOpen || frame.resumable !== grant.resumable || state.streamId !== void 0 && state.streamId !== frame.streamId || resumeMismatch) {
       this.fail(state, new ApplicationPortProxyError(
         ApplicationPortProxyErrorCode.streamStateInvalid,
@@ -299,6 +319,7 @@ var ApplicationPortClientInstance = class {
     if (this.isClosed) return;
     const result = validatePortFrame(value, {
       authenticatedPrincipalId: this.options.authenticatedPrincipalId,
+      frameSchemaVersion: this.options.frameSchemaVersion,
       grant: this.options.grant,
       now: this.options.now()
     });
@@ -437,7 +458,7 @@ var ApplicationPortClientInstance = class {
     };
   }
   terminateStream(state, frame) {
-    if (frame.lastSequence !== Math.max(0, state.lastAcceptedSequence)) {
+    if (!portStreamTerminalMatches(frame, state.lastAcceptedSequence + 1)) {
       this.fail(state, new ApplicationPortProxyError(
         ApplicationPortProxyErrorCode.streamStateInvalid,
         "Stream terminal sequence does not match accepted items"
@@ -464,29 +485,31 @@ function createApplicationPortClient(options) {
 // src/applicationPortHost.ts
 import {
   PortAttachmentGrantZod as PortAttachmentGrantZod2,
+  PortFrameSchemaVersionZod as PortFrameSchemaVersionZod2,
+  PortStreamProgressUnsupportedCode,
+  portStreamResumeNextSequence as portStreamResumeNextSequence2,
+  portStreamTerminalProgress,
   validatePortFrame as validatePortFrame2
 } from "@xyo-network/dapp-kit";
-function registeredOperations(options) {
+
+// src/applicationPortOperations.ts
+function registeredApplicationPortOperations(attachment, values) {
   const operations2 = /* @__PURE__ */ new Map();
-  for (const operation of options.operations) {
+  for (const operation of values) {
     const key2 = applicationPortOperationKey(operation.portId, operation.operationId);
-    const grant = applicationPortOperationGrant(options.grant, operation.portId, operation.operationId);
+    const grant = applicationPortOperationGrant(attachment, operation.portId, operation.operationId);
     if (operations2.has(key2)) {
-      throw new ApplicationPortProxyError(
-        ApplicationPortProxyErrorCode.duplicateRequest,
-        `Application-port operation is registered more than once: ${operation.portId}.${operation.operationId}`
-      );
+      throw new ApplicationPortProxyError(ApplicationPortProxyErrorCode.duplicateRequest, `Application-port operation is registered more than once: ${operation.portId}.${operation.operationId}`);
     }
     if (grant?.streaming !== operation.streaming) {
-      throw new ApplicationPortProxyError(
-        ApplicationPortProxyErrorCode.operationKindMismatch,
-        `Registered operation conflicts with attachment grant: ${operation.portId}.${operation.operationId}`
-      );
+      throw new ApplicationPortProxyError(ApplicationPortProxyErrorCode.operationKindMismatch, `Registered operation conflicts with attachment grant: ${operation.portId}.${operation.operationId}`);
     }
     operations2.set(key2, operation);
   }
   return operations2;
 }
+
+// src/applicationPortHost.ts
 var ApplicationPortHostInstance = class {
   cleanupErrors = [];
   closePromise;
@@ -497,8 +520,12 @@ var ApplicationPortHostInstance = class {
   ownedRequests = /* @__PURE__ */ new Set();
   requests = /* @__PURE__ */ new Map();
   constructor(options) {
-    this.options = { ...options, grant: PortAttachmentGrantZod2.parse(options.grant) };
-    this.operations = registeredOperations(this.options);
+    this.options = {
+      ...options,
+      frameSchemaVersion: PortFrameSchemaVersionZod2.parse(options.frameSchemaVersion ?? 1),
+      grant: PortAttachmentGrantZod2.parse(options.grant)
+    };
+    this.operations = registeredApplicationPortOperations(this.options.grant, this.options.operations);
     this.listener = (message) => void this.receive(message);
     options.endpoint.addMessageListener(this.listener);
     options.endpoint.start?.();
@@ -630,7 +657,7 @@ var ApplicationPortHostInstance = class {
       isCancelled: false,
       isTerminal: false,
       kind: "stream",
-      lastSequence: frame.frameKind === "stream-resume" ? frame.lastAcceptedSequence : -1,
+      lastSequence: frame.frameKind === "stream-resume" ? portStreamResumeNextSequence2(frame) - 1 : -1,
       ...frame.frameKind === "stream-resume" ? { resumeCursor: frame.resumeCursor } : {}
     };
     this.requests.set(frame.requestId, state);
@@ -667,6 +694,7 @@ var ApplicationPortHostInstance = class {
     if (this.isClosed) return;
     const result = validatePortFrame2(value, {
       authenticatedPrincipalId: this.options.authenticatedPrincipalId,
+      frameSchemaVersion: this.options.frameSchemaVersion,
       grant: this.options.grant,
       now: this.options.now()
     });
@@ -783,18 +811,25 @@ var ApplicationPortHostInstance = class {
     const read = await source.next(state.controller.signal);
     if (state.isCancelled || this.isClosed) return false;
     if (read.done) {
+      if (state.frame.schemaVersion === 1 && state.lastSequence < 0) {
+        this.terminateStreamWithError(state, void 0, PortStreamProgressUnsupportedCode);
+        return false;
+      }
       state.isTerminal = true;
       this.post(parseApplicationPortFrame({
         ...applicationPortFrameBase(this.options.grant, state.frame),
         frameKind: "stream-close",
         streamId: source.streamId,
-        lastSequence: Math.max(0, state.lastSequence),
+        ...portStreamTerminalProgress(state.frame.schemaVersion, state.lastSequence + 1),
         ...read.resumeCursor === void 0 ? {} : { resumeCursor: read.resumeCursor }
       }));
       this.requests.delete(state.frame.requestId);
       this.ownedRequests.delete(state);
       return false;
     }
+    if (!Number.isSafeInteger(state.lastSequence + 2)) {
+      throw new ApplicationPortProxyError(ApplicationPortProxyErrorCode.streamStateInvalid, "Stream successor exceeds safe integer progress");
+    }
     if (source.resumable && read.value.resumeCursor === void 0) {
       throw new ApplicationPortProxyError(
         ApplicationPortProxyErrorCode.streamStateInvalid,
@@ -831,7 +866,8 @@ var ApplicationPortHostInstance = class {
     }
     return await operation.resume({
       ...context,
-      lastAcceptedSequence: frame.lastAcceptedSequence,
+      nextSequence: portStreamResumeNextSequence2(frame),
+      ...portStreamResumeNextSequence2(frame) > 0 ? { lastAcceptedSequence: portStreamResumeNextSequence2(frame) - 1 } : {},
       resumeCursor: frame.resumeCursor,
       streamId: frame.streamId
     });
@@ -855,11 +891,12 @@ var ApplicationPortHostInstance = class {
     if (source === void 0 || state.isTerminal || this.isClosed) return;
     state.isTerminal = true;
     const error = code === void 0 ? this.mapError(state.frame, cause) : { code, retriable: false };
-    this.post(parseApplicationPortFrame({
+    if (state.frame.schemaVersion === 1 && state.lastSequence < 0) this.postError(state.frame, PortStreamProgressUnsupportedCode);
+    else this.post(parseApplicationPortFrame({
       ...applicationPortFrameBase(this.options.grant, state.frame),
       frameKind: "stream-error",
       streamId: source.streamId,
-      lastSequence: Math.max(0, state.lastSequence),
+      ...portStreamTerminalProgress(state.frame.schemaVersion, state.lastSequence + 1),
       ...state.resumeCursor === void 0 ? {} : { resumeCursor: state.resumeCursor },
       error
     }));
@@ -869,8 +906,8 @@ var ApplicationPortHostInstance = class {
     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);
-    if (source.resumable !== grant.resumable || source.resumable && source.resumeCursor === void 0 || resumeMismatch) {
+    const resumeMismatch = frame.frameKind === "stream-resume" && (source.streamId !== frame.streamId || source.nextSequence !== portStreamResumeNextSequence2(frame));
+    if (!Number.isSafeInteger(source.nextSequence) || source.nextSequence < 0 || source.resumable !== grant.resumable || source.resumable && source.resumeCursor === void 0 || resumeMismatch) {
       throw new ApplicationPortProxyError(
         ApplicationPortProxyErrorCode.streamStateInvalid,
         "Stream source conflicts with its grant or resume request"
@@ -888,7 +925,7 @@ import {
   IdentifierZod,
   parseStrictJsonText,
   PortAttachmentGrantZod as PortAttachmentGrantZod3,
-  PortFrameZod as PortFrameZod2
+  PortFrameAnyVersionZod as PortFrameAnyVersionZod2
 } from "@xyo-network/dapp-kit";
 import { asSchema } from "@xyo-network/sdk";
 import { z } from "zod";
@@ -900,6 +937,15 @@ var ApplicationPortTransportHelloZod = z.strictObject({
   maximumFrameBytes: z.number().int().positive().max(16 * 1024 * 1024),
   grant: PortAttachmentGrantZod3
 });
+var ApplicationPortTransportHelloV2Zod = z.strictObject({
+  ...ApplicationPortTransportHelloZod.shape,
+  schemaVersion: z.literal(2),
+  frameSchemaVersion: z.literal(2)
+});
+var ApplicationPortTransportHelloAnyVersionZod = z.discriminatedUnion("schemaVersion", [
+  ApplicationPortTransportHelloZod,
+  ApplicationPortTransportHelloV2Zod
+]);
 var ApplicationPortTransportErrorZod = z.strictObject({
   schema: z.literal(ApplicationPortTransportSchema),
   schemaVersion: z.literal(1),
@@ -908,8 +954,8 @@ var ApplicationPortTransportErrorZod = z.strictObject({
   retriable: z.boolean()
 });
 var ApplicationPortWireMessageZod = z.union([
-  PortFrameZod2,
-  ApplicationPortTransportHelloZod,
+  PortFrameAnyVersionZod2,
+  ApplicationPortTransportHelloAnyVersionZod,
   ApplicationPortTransportErrorZod
 ]);
 var ApplicationPortWireErrorCode = {
@@ -981,6 +1027,7 @@ function serializeApplicationPortWireMessage(message, maximumFrameBytes) {
 import {
   DappEngineSystemReferenceZod,
   PortAttachmentGrantZod as PortAttachmentGrantZod4,
+  PortFrameSchemaVersionZod as PortFrameSchemaVersionZod3,
   validateDappEngineSystemReference
 } from "@xyo-network/dapp-kit";
 
@@ -1147,6 +1194,7 @@ function operations(bindings, grant, readTarget, admitRecovery) {
   });
 }
 async function createDappEngineApplicationPortHost(options) {
+  const frameSchemaVersion = PortFrameSchemaVersionZod3.parse(options.frameSchemaVersion ?? 1);
   const reference = DappEngineSystemReferenceZod.parse(options.reference);
   const grant = PortAttachmentGrantZod4.parse(options.grant);
   const readStatus = options.engine.status.bind(options.engine);
@@ -1161,6 +1209,7 @@ async function createDappEngineApplicationPortHost(options) {
     const host = createApplicationPortHost({
       authenticatedPrincipalId: options.authenticatedPrincipalId,
       endpoint: deferred.endpoint,
+      frameSchemaVersion,
       grant,
       now: options.now,
       onProtocolError: options.onProtocolError,
@@ -1205,7 +1254,7 @@ async function createDappEngineApplicationPortHost(options) {
 }
 
 // src/webSocketApplicationPortClient.ts
-import { PortFrameZod as PortFrameZod3 } from "@xyo-network/dapp-kit";
+import { PortFrameAnyVersionZod as PortFrameAnyVersionZod3, PortFrameSchemaVersionZod as PortFrameSchemaVersionZod4 } from "@xyo-network/dapp-kit";
 var WebSocketApplicationPortClientErrorCode = {
   aborted: "port.websocket-aborted",
   closed: "port.websocket-closed",
@@ -1294,7 +1343,7 @@ var BrowserWebSocketApplicationPortEndpoint = class {
         "application-port WebSocket is not open"
       );
     }
-    const frame = PortFrameZod3.parse(message);
+    const frame = PortFrameAnyVersionZod3.parse(message);
     this.socket.send(serializeApplicationPortWireMessage(frame, this.maximumFrameBytes));
   }
   receive = (event) => {
@@ -1325,6 +1374,8 @@ async function connectWebSocketApplicationPort(options) {
       "application-port connection was aborted before launch"
     );
   }
+  const acceptedVersions = new Set((options.acceptedFrameSchemaVersions ?? [1, 2]).map((version) => PortFrameSchemaVersionZod4.parse(version)));
+  if (acceptedVersions.size === 0) throw new TypeError("at least one application-port frame schema version must be accepted");
   const maximumFrameBytes = positiveInteger(
     options.maximumFrameBytes ?? 256 * 1024,
     "maximum frame bytes",
@@ -1375,7 +1426,8 @@ async function connectWebSocketApplicationPort(options) {
             ));
             return;
           }
-          const parsed = ApplicationPortTransportHelloZod.parse(message);
+          const parsed = ApplicationPortTransportHelloAnyVersionZod.parse(message);
+          if (!acceptedVersions.has(parsed.schemaVersion)) throw new TypeError("server selected an unsupported application-port frame schema version");
           assertExpectedGrant(parsed.grant, options.expected, options.now());
           cleanup();
           resolve(parsed);
@@ -1409,6 +1461,7 @@ async function connectWebSocketApplicationPort(options) {
       authenticatedPrincipalId: hello.grant.principalId,
       endpoint,
       grant: hello.grant,
+      frameSchemaVersion: hello.schemaVersion,
       nextRequestId: options.nextRequestId,
       now: options.now,
       onProtocolError: options.onProtocolError
@@ -1421,6 +1474,7 @@ async function connectWebSocketApplicationPort(options) {
     return {
       client,
       grant: hello.grant,
+      frameSchemaVersion: hello.schemaVersion,
       whenClosed: closed.promise,
       close: () => {
         if (isClosed) return;
@@ -1441,6 +1495,8 @@ export {
   ApplicationPortProxyErrorCode,
   ApplicationPortRemoteError,
   ApplicationPortTransportErrorZod,
+  ApplicationPortTransportHelloAnyVersionZod,
+  ApplicationPortTransportHelloV2Zod,
   ApplicationPortTransportHelloZod,
   ApplicationPortTransportSchema,
   ApplicationPortWireError,