@xyo-network/dapp-kit-port 0.1.2

package/dist/browser/index.mjs

@@ -0,0 +1,1180 @@
+// src/applicationPortClient.ts
+import {
+  canonicalizeIJson,
+  PortAttachmentGrantZod,
+  validatePortFrame
+} from "@xyo-network/dapp-kit";
+
+// src/applicationPortModel.ts
+import { PortFrameZod } from "@xyo-network/dapp-kit";
+var ApplicationPortProxyErrorCode = {
+  cancelled: "port.cancelled",
+  detached: "port.detached",
+  directionInvalid: "port.direction-invalid",
+  duplicateRequest: "port.duplicate-request",
+  hostFailure: "port.host-failure",
+  operationKindMismatch: "port.operation-kind-mismatch",
+  operationUnavailable: "port.operation-unavailable",
+  requestUnknown: "port.request-unknown",
+  streamStateInvalid: "port.stream-state-invalid"
+};
+var ApplicationPortProxyError = class extends Error {
+  code;
+  issues;
+  constructor(code, message, issues) {
+    super(message);
+    this.name = "ApplicationPortProxyError";
+    this.code = code;
+    this.issues = issues;
+  }
+};
+var ApplicationPortRemoteError = class extends Error {
+  code;
+  details;
+  retriable;
+  constructor(error) {
+    super(`Remote application-port operation failed: ${error.code}`);
+    this.name = "ApplicationPortRemoteError";
+    this.code = error.code;
+    this.details = error.details;
+    this.retriable = error.retriable;
+  }
+};
+var ApplicationPortCancelledError = class extends Error {
+  code = ApplicationPortProxyErrorCode.cancelled;
+  reasonCode;
+  constructor(reasonCode) {
+    super(`Application-port request was cancelled: ${reasonCode}`);
+    this.name = "ApplicationPortCancelledError";
+    this.reasonCode = reasonCode;
+  }
+};
+function applicationPortOperationKey(portId, operationId) {
+  return `${portId}\0${operationId}`;
+}
+function applicationPortOperationGrant(grant, portId, operationId) {
+  return grant.operations.find((operation) => operation.portId === portId && operation.operationId === operationId);
+}
+function applicationPortFrameBase(grant, frame) {
+  return {
+    schema: "network.xyo.dapp.port.frame",
+    schemaVersion: 1,
+    dappId: grant.dappId,
+    protocolVersion: grant.protocolVersion,
+    planId: grant.planId,
+    systemInstanceId: grant.systemInstanceId,
+    hostSessionId: grant.hostSessionId,
+    attachmentId: grant.attachmentId,
+    requestId: frame.requestId,
+    deadlineUnixMs: frame.deadlineUnixMs,
+    portId: frame.portId,
+    operationId: frame.operationId
+  };
+}
+function parseApplicationPortFrame(value) {
+  return PortFrameZod.parse(value);
+}
+function applicationPortErrorFrame(grant, frame, error) {
+  return parseApplicationPortFrame({
+    ...applicationPortFrameBase(grant, frame),
+    frameKind: "error",
+    error
+  });
+}
+
+// src/applicationPortClient.ts
+var ApplicationPortStreamInstance = class {
+  requestId;
+  streamId;
+  client;
+  state;
+  constructor(client, state, streamId) {
+    this.client = client;
+    this.requestId = state.frame.requestId;
+    this.state = state;
+    this.streamId = streamId;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  cancel(reasonCode = "client-cancelled") {
+    this.client.cancel(this.state, reasonCode);
+  }
+  credit(value) {
+    this.client.credit(this.state, value);
+  }
+  async next() {
+    const value = this.state.queue.shift();
+    if (value !== void 0) return { done: false, value };
+    if (this.state.terminalError !== void 0) throw this.state.terminalError;
+    if (this.state.isTerminal) return { done: true, value: void 0 };
+    const waiter = { promise: Promise.withResolvers() };
+    this.state.waiters.push(waiter);
+    return await waiter.promise.promise;
+  }
+};
+var ApplicationPortClientInstance = class {
+  isClosed = false;
+  listener;
+  options;
+  requests = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.options = { ...options, grant: PortAttachmentGrantZod.parse(options.grant) };
+    this.listener = (message) => this.receive(message);
+    options.endpoint.addMessageListener(this.listener);
+    options.endpoint.start?.();
+  }
+  cancel(state, reasonCode) {
+    if (state.isTerminal || state.reasonCode !== void 0 || this.isClosed) return;
+    state.reasonCode = reasonCode;
+    this.post(parseApplicationPortFrame({
+      ...applicationPortFrameBase(this.options.grant, state.frame),
+      frameKind: "cancel",
+      reasonCode
+    }));
+  }
+  close() {
+    if (this.isClosed) return;
+    this.isClosed = true;
+    this.options.endpoint.removeMessageListener(this.listener);
+    const error = new ApplicationPortProxyError(
+      ApplicationPortProxyErrorCode.detached,
+      "Application-port client detached before the request completed"
+    );
+    for (const state of this.requests.values()) this.fail(state, error);
+    this.requests.clear();
+  }
+  credit(state, value) {
+    if (!state.isOpen || state.isTerminal || state.streamId === void 0) {
+      throw new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Credit requires an open stream"
+      );
+    }
+    const grant = state.grant;
+    this.verifyCredit(value, state.availableCredit, grant);
+    state.availableCredit += value;
+    this.post(parseApplicationPortFrame({
+      ...applicationPortFrameBase(this.options.grant, state.frame),
+      frameKind: "stream-credit",
+      streamId: state.streamId,
+      credit: value
+    }));
+  }
+  request(options) {
+    if (options.signal?.aborted === true) return Promise.reject(new ApplicationPortCancelledError("client-abort"));
+    const grant = this.requireGrant(options.portId, options.operationId, false);
+    const frame = this.requestFrame(options);
+    const promise = Promise.withResolvers();
+    const state = {
+      frame,
+      grant,
+      isTerminal: false,
+      kind: "unary",
+      promise
+    };
+    this.requests.set(frame.requestId, state);
+    this.setAbortBinding(state, options.signal);
+    this.post(frame);
+    return promise.promise;
+  }
+  resumeStream(options) {
+    if (options.signal?.aborted === true) return Promise.reject(new ApplicationPortCancelledError("client-abort"));
+    const grant = this.requireGrant(options.portId, options.operationId, true);
+    if (!grant.resumable) {
+      throw new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.operationKindMismatch,
+        "Application-port stream does not permit resume"
+      );
+    }
+    this.verifyCredit(options.credit, 0, grant);
+    const frame = parseApplicationPortFrame({
+      ...this.newFrameBase(options),
+      frameKind: "stream-resume",
+      streamId: options.streamId,
+      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.resumeCursor = options.resumeCursor;
+    state.streamId = options.streamId;
+    this.requests.set(frame.requestId, state);
+    this.setAbortBinding(state, options.signal);
+    this.post(frame);
+    return state.opened.promise;
+  }
+  stream(options) {
+    if (options.signal?.aborted === true) return Promise.reject(new ApplicationPortCancelledError("client-abort"));
+    const grant = this.requireGrant(options.portId, options.operationId, true);
+    this.verifyCredit(options.initialCredit, 0, grant);
+    const frame = this.requestFrame(options);
+    const state = this.streamState(frame, grant, options.initialCredit);
+    this.requests.set(frame.requestId, state);
+    this.setAbortBinding(state, options.signal);
+    this.post(frame);
+    return state.opened.promise;
+  }
+  completeStream(state) {
+    state.isTerminal = true;
+    state.removeAbortListener?.();
+    for (const waiter of state.waiters.splice(0)) {
+      if (state.terminalError === void 0) waiter.promise.resolve({ done: true, value: void 0 });
+      else waiter.promise.reject(state.terminalError);
+    }
+    this.requests.delete(state.frame.requestId);
+  }
+  fail(state, error) {
+    state.isTerminal = true;
+    state.removeAbortListener?.();
+    if (state.kind === "unary") state.promise.reject(error);
+    else {
+      state.terminalError = error;
+      state.opened.reject(error);
+      this.completeStream(state);
+    }
+  }
+  handleStreamFrame(state, frame) {
+    if (frame.frameKind === "error") {
+      this.fail(state, new ApplicationPortRemoteError(frame.error));
+      return;
+    }
+    if (frame.frameKind === "cancel-ack") {
+      this.fail(state, new ApplicationPortCancelledError(state.reasonCode ?? "remote-cancelled"));
+      return;
+    }
+    if (frame.frameKind === "stream-open") {
+      this.openStream(state, frame);
+      return;
+    }
+    if (!state.isOpen || !("streamId" in frame) || frame.streamId !== state.streamId) {
+      this.fail(state, new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Stream frame arrived before a matching open"
+      ));
+      return;
+    }
+    if (frame.frameKind === "stream-item") this.receiveStreamItem(state, frame);
+    else if (frame.frameKind === "stream-error" || frame.frameKind === "stream-close") {
+      this.terminateStream(state, frame);
+    } else {
+      this.report(ApplicationPortProxyErrorCode.directionInvalid, "Client received a client-to-host stream frame", frame);
+    }
+  }
+  newFrameBase(options) {
+    if (this.isClosed) {
+      throw new ApplicationPortProxyError(ApplicationPortProxyErrorCode.detached, "Application-port client is closed");
+    }
+    return applicationPortFrameBase(this.options.grant, {
+      ...options,
+      requestId: this.options.nextRequestId()
+    });
+  }
+  openStream(state, frame) {
+    const grant = state.grant;
+    const resumeMismatch = state.lastAcceptedSequence > 0 && 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,
+        "Stream open conflicts with the pending request"
+      ));
+      return;
+    }
+    state.isOpen = true;
+    state.streamId = frame.streamId;
+    state.lastAcceptedSequence = frame.nextSequence - 1;
+    state.resumeCursor = frame.resumeCursor;
+    state.opened.resolve(new ApplicationPortStreamInstance(this, state, frame.streamId));
+    if (state.frame.frameKind === "request") this.credit(state, state.initialCredit);
+  }
+  post(frame) {
+    if (this.isClosed) {
+      throw new ApplicationPortProxyError(ApplicationPortProxyErrorCode.detached, "Application-port client is closed");
+    }
+    this.options.endpoint.send(frame);
+  }
+  receive(value) {
+    if (this.isClosed) return;
+    const result = validatePortFrame(value, {
+      authenticatedPrincipalId: this.options.authenticatedPrincipalId,
+      grant: this.options.grant,
+      now: this.options.now()
+    });
+    if (!result.success) {
+      this.options.onProtocolError({
+        cause: new ApplicationPortProxyError(
+          ApplicationPortProxyErrorCode.directionInvalid,
+          "Application-port frame failed attachment validation",
+          result.issues
+        ),
+        value
+      });
+      return;
+    }
+    this.receiveValid(result.value);
+  }
+  receiveStreamItem(state, frame) {
+    if (state.availableCredit <= 0) {
+      this.fail(state, new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Stream item exceeded receiver credit"
+      ));
+      return;
+    }
+    state.availableCredit -= 1;
+    const canonical = canonicalizeIJson({
+      body: frame.body,
+      consistency: frame.consistency,
+      resumeCursor: frame.resumeCursor ?? null
+    });
+    const prior = state.seen.get(frame.sequence);
+    if (prior !== void 0) {
+      if (prior !== canonical) {
+        this.fail(state, new ApplicationPortProxyError(
+          ApplicationPortProxyErrorCode.streamStateInvalid,
+          "Redelivered stream sequence changed content"
+        ));
+      }
+      return;
+    }
+    if (frame.sequence !== state.lastAcceptedSequence + 1) {
+      this.fail(state, new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Stream item sequence is not contiguous"
+      ));
+      return;
+    }
+    state.seen.set(frame.sequence, canonical);
+    state.lastAcceptedSequence = frame.sequence;
+    state.resumeCursor = frame.resumeCursor;
+    const value = this.streamValue(frame);
+    const waiter = state.waiters.shift();
+    if (waiter === void 0) state.queue.push(value);
+    else waiter.promise.resolve({ done: false, value });
+  }
+  receiveUnary(state, frame) {
+    if (frame.frameKind === "response") {
+      state.isTerminal = true;
+      state.removeAbortListener?.();
+      state.promise.resolve({ body: frame.body, consistency: frame.consistency });
+      this.requests.delete(frame.requestId);
+      return;
+    }
+    if (frame.frameKind === "error") this.fail(state, new ApplicationPortRemoteError(frame.error));
+    else if (frame.frameKind === "cancel-ack") {
+      this.fail(state, new ApplicationPortCancelledError(state.reasonCode ?? "remote-cancelled"));
+    } else this.report(ApplicationPortProxyErrorCode.directionInvalid, "Client received a client-to-host frame", frame);
+  }
+  receiveValid(frame) {
+    const state = this.requests.get(frame.requestId);
+    if (state === void 0) {
+      this.report(ApplicationPortProxyErrorCode.requestUnknown, "Response targets an unknown request", frame);
+      return;
+    }
+    if (frame.portId !== state.frame.portId || frame.operationId !== state.frame.operationId) {
+      this.fail(state, new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Response operation does not match its request"
+      ));
+      return;
+    }
+    if (state.kind === "stream") {
+      this.handleStreamFrame(state, frame);
+      return;
+    }
+    this.receiveUnary(state, frame);
+  }
+  report(code, message, value) {
+    this.options.onProtocolError({ cause: new ApplicationPortProxyError(code, message), value });
+  }
+  requestFrame(options) {
+    return parseApplicationPortFrame({
+      ...this.newFrameBase(options),
+      frameKind: "request",
+      body: options.body
+    });
+  }
+  requireGrant(portId, operationId, streaming) {
+    const grant = applicationPortOperationGrant(this.options.grant, portId, operationId);
+    if (grant?.streaming !== streaming) {
+      throw new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.operationKindMismatch,
+        `Attachment does not grant ${streaming ? "stream" : "unary"} operation ${portId}.${operationId}`
+      );
+    }
+    return grant;
+  }
+  setAbortBinding(state, signal) {
+    if (signal === void 0) return;
+    const listener = () => this.cancel(state, "client-abort");
+    signal.addEventListener("abort", listener, { once: true });
+    Object.assign(state, { removeAbortListener: () => signal.removeEventListener("abort", listener) });
+  }
+  streamState(frame, grant, initialCredit) {
+    return {
+      availableCredit: 0,
+      frame,
+      grant,
+      initialCredit,
+      isOpen: false,
+      isTerminal: false,
+      kind: "stream",
+      lastAcceptedSequence: 0,
+      opened: Promise.withResolvers(),
+      queue: [],
+      seen: /* @__PURE__ */ new Map(),
+      waiters: []
+    };
+  }
+  streamValue(frame) {
+    return {
+      body: frame.body,
+      consistency: frame.consistency,
+      ...frame.resumeCursor === void 0 ? {} : { resumeCursor: frame.resumeCursor },
+      sequence: frame.sequence
+    };
+  }
+  terminateStream(state, frame) {
+    if (frame.lastSequence !== Math.max(0, state.lastAcceptedSequence)) {
+      this.fail(state, new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Stream terminal sequence does not match accepted items"
+      ));
+      return;
+    }
+    state.resumeCursor = frame.resumeCursor;
+    if (frame.frameKind === "stream-error") state.terminalError = new ApplicationPortRemoteError(frame.error);
+    this.completeStream(state);
+  }
+  verifyCredit(value, availableCredit, grant) {
+    if (!Number.isSafeInteger(value) || value <= 0 || availableCredit + value > grant.maximumCredit) {
+      throw new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Outstanding credit exceeds the stream grant"
+      );
+    }
+  }
+};
+function createApplicationPortClient(options) {
+  return new ApplicationPortClientInstance(options);
+}
+
+// src/applicationPortHost.ts
+import {
+  PortAttachmentGrantZod as PortAttachmentGrantZod2,
+  validatePortFrame as validatePortFrame2
+} from "@xyo-network/dapp-kit";
+function registeredOperations(options) {
+  const operations = /* @__PURE__ */ new Map();
+  for (const operation of options.operations) {
+    const key = applicationPortOperationKey(operation.portId, operation.operationId);
+    const grant = applicationPortOperationGrant(options.grant, operation.portId, operation.operationId);
+    if (operations.has(key)) {
+      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}`
+      );
+    }
+    operations.set(key, operation);
+  }
+  return operations;
+}
+var ApplicationPortHostInstance = class {
+  isClosed = false;
+  listener;
+  operations;
+  options;
+  requests = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.options = { ...options, grant: PortAttachmentGrantZod2.parse(options.grant) };
+    this.operations = registeredOperations(this.options);
+    this.listener = (message) => void this.receive(message);
+    options.endpoint.addMessageListener(this.listener);
+    options.endpoint.start?.();
+  }
+  async close() {
+    if (this.isClosed) return;
+    this.isClosed = true;
+    this.options.endpoint.removeMessageListener(this.listener);
+    const completions = [];
+    for (const state of this.requests.values()) {
+      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();
+  }
+  cancelAcknowledgement(frame) {
+    return parseApplicationPortFrame({
+      ...applicationPortFrameBase(this.options.grant, frame),
+      frameKind: "cancel-ack",
+      willEmitNoNewWork: true
+    });
+  }
+  async cancelRequest(frame) {
+    const state = this.requests.get(frame.requestId);
+    if (state === void 0) {
+      this.report(ApplicationPortProxyErrorCode.requestUnknown, "Cancellation targets an unknown request", frame);
+      return;
+    }
+    if (state.isTerminal || state.isCancelled) return;
+    state.isCancelled = true;
+    state.controller.abort(frame.reasonCode);
+    if (state.kind === "unary") {
+      await state.completion;
+      return;
+    }
+    await state.openPromise;
+    if (state.pumpPromise !== void 0) await state.pumpPromise;
+    await state.source?.cancel?.(frame.reasonCode);
+    if (!this.isClosed && !state.isTerminal) {
+      state.isTerminal = true;
+      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));
+    }
+  }
+  dispatchStart(frame) {
+    const operation = this.operations.get(applicationPortOperationKey(frame.portId, frame.operationId));
+    const grant = applicationPortOperationGrant(this.options.grant, frame.portId, frame.operationId);
+    if (operation === void 0 || grant === void 0) {
+      this.postError(frame, ApplicationPortProxyErrorCode.operationUnavailable);
+      return;
+    }
+    if (operation.streaming !== grant.streaming) {
+      this.postError(frame, ApplicationPortProxyErrorCode.operationKindMismatch);
+      return;
+    }
+    if (operation.streaming && grant.streaming) {
+      this.openStream(frame, operation, grant);
+      return;
+    }
+    if (frame.frameKind === "request" && !operation.streaming) {
+      this.startUnary(frame, operation);
+      return;
+    }
+    this.postError(frame, ApplicationPortProxyErrorCode.operationKindMismatch);
+  }
+  mapError(frame, cause) {
+    const fallback = { code: ApplicationPortProxyErrorCode.hostFailure, retriable: false };
+    try {
+      const mapped = this.options.mapError(cause);
+      applicationPortErrorFrame(this.options.grant, frame, mapped);
+      return mapped;
+    } catch {
+      return fallback;
+    }
+  }
+  openStream(frame, operation, grant) {
+    const state = {
+      availableCredit: frame.frameKind === "stream-resume" ? frame.credit : 0,
+      controller: new AbortController(),
+      frame,
+      grant,
+      isCancelled: false,
+      isTerminal: false,
+      kind: "stream",
+      lastSequence: frame.frameKind === "stream-resume" ? frame.lastAcceptedSequence : -1,
+      ...frame.frameKind === "stream-resume" ? { resumeCursor: frame.resumeCursor } : {}
+    };
+    this.requests.set(frame.requestId, state);
+    state.openPromise = this.runStreamOpen(state, frame, operation);
+  }
+  post(frame) {
+    if (!this.isClosed) this.options.endpoint.send(frame);
+  }
+  postError(frame, code) {
+    this.post(applicationPortErrorFrame(this.options.grant, frame, { code, retriable: false }));
+  }
+  async pump(state) {
+    if (state.pumpPromise !== void 0 || state.source === void 0 || state.isTerminal || state.isCancelled) return;
+    const pumping = this.pumpOnce(state);
+    state.pumpPromise = pumping;
+    await pumping;
+    if (state.pumpPromise === pumping) state.pumpPromise = void 0;
+  }
+  async pumpOnce(state) {
+    try {
+      while (state.availableCredit > 0 && !state.isTerminal && !state.isCancelled && !this.isClosed) {
+        if (!await this.sendNext(state)) return;
+      }
+    } catch (error) {
+      if (!state.isCancelled && !this.isClosed) this.terminateStreamWithError(state, error);
+    }
+  }
+  async receive(value) {
+    if (this.isClosed) return;
+    const result = validatePortFrame2(value, {
+      authenticatedPrincipalId: this.options.authenticatedPrincipalId,
+      grant: this.options.grant,
+      now: this.options.now()
+    });
+    if (!result.success) {
+      this.reportInvalid(result.issues, value);
+      return;
+    }
+    const frame = result.value;
+    if (frame.frameKind === "cancel") {
+      await this.cancelRequest(frame);
+      return;
+    }
+    if (frame.frameKind === "stream-credit") {
+      await this.receiveCredit(frame);
+      return;
+    }
+    if (frame.frameKind !== "request" && frame.frameKind !== "stream-resume") {
+      this.report(ApplicationPortProxyErrorCode.directionInvalid, "Host received a server-to-client frame", frame);
+      return;
+    }
+    if (this.requests.has(frame.requestId)) {
+      this.report(ApplicationPortProxyErrorCode.duplicateRequest, "Request ID is already active", frame);
+      return;
+    }
+    this.dispatchStart(frame);
+  }
+  async receiveCredit(frame) {
+    const state = this.requests.get(frame.requestId);
+    if (state?.kind !== "stream" || state.source?.streamId !== frame.streamId || state.isTerminal) {
+      this.report(ApplicationPortProxyErrorCode.streamStateInvalid, "Stream credit targets an inactive stream", frame);
+      return;
+    }
+    if (state.availableCredit + frame.credit > state.grant.maximumCredit) {
+      this.terminateStreamWithError(state, void 0, "port.credit-exceeded");
+      return;
+    }
+    state.availableCredit += frame.credit;
+    await this.pump(state);
+  }
+  report(code, message, value) {
+    this.options.onProtocolError({ cause: new ApplicationPortProxyError(code, message), value });
+  }
+  reportInvalid(issues, value) {
+    this.options.onProtocolError({
+      cause: new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.directionInvalid,
+        "Application-port frame failed attachment validation",
+        issues
+      ),
+      value
+    });
+  }
+  async runStreamOpen(state, frame, operation) {
+    try {
+      const source = await this.startStreamSource(state, frame, operation);
+      this.verifyStreamSource(source, frame, state.grant);
+      state.source = source;
+      state.lastSequence = source.nextSequence - 1;
+      state.resumeCursor = source.resumeCursor;
+      if (state.isCancelled || this.isClosed) return;
+      this.post(parseApplicationPortFrame({
+        ...applicationPortFrameBase(this.options.grant, frame),
+        frameKind: "stream-open",
+        streamId: source.streamId,
+        delivery: "at-least-once",
+        resumable: source.resumable,
+        nextSequence: source.nextSequence,
+        ...source.resumeCursor === void 0 ? {} : { resumeCursor: source.resumeCursor }
+      }));
+      await this.pump(state);
+    } catch (error) {
+      if (!state.isCancelled && !this.isClosed) {
+        state.isTerminal = true;
+        this.post(applicationPortErrorFrame(this.options.grant, frame, this.mapError(frame, error)));
+        this.requests.delete(frame.requestId);
+      }
+    }
+  }
+  async runUnary(state, frame, operation) {
+    try {
+      const result = await operation.handle({
+        body: frame.body,
+        grant: this.options.grant,
+        requestId: frame.requestId,
+        signal: state.controller.signal
+      });
+      if (!state.isCancelled && !this.isClosed) {
+        state.isTerminal = true;
+        this.post(parseApplicationPortFrame({
+          ...applicationPortFrameBase(this.options.grant, frame),
+          frameKind: "response",
+          consistency: result.consistency,
+          body: result.body
+        }));
+      }
+    } catch (error) {
+      if (!state.isCancelled && !this.isClosed) {
+        state.isTerminal = true;
+        this.post(applicationPortErrorFrame(this.options.grant, frame, this.mapError(frame, error)));
+      }
+    } finally {
+      if (state.isCancelled && !state.isTerminal && !this.isClosed) {
+        state.isTerminal = true;
+        this.post(this.cancelAcknowledgement(frame));
+      }
+      this.requests.delete(frame.requestId);
+    }
+  }
+  async sendNext(state) {
+    const source = state.source;
+    if (source === void 0) return false;
+    const read = await source.next(state.controller.signal);
+    if (state.isCancelled || this.isClosed) return false;
+    if (read.done) {
+      state.isTerminal = true;
+      this.post(parseApplicationPortFrame({
+        ...applicationPortFrameBase(this.options.grant, state.frame),
+        frameKind: "stream-close",
+        streamId: source.streamId,
+        lastSequence: Math.max(0, state.lastSequence),
+        ...read.resumeCursor === void 0 ? {} : { resumeCursor: read.resumeCursor }
+      }));
+      this.requests.delete(state.frame.requestId);
+      return false;
+    }
+    if (source.resumable && read.value.resumeCursor === void 0) {
+      throw new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Resumable stream item did not provide a durable cursor"
+      );
+    }
+    state.availableCredit -= 1;
+    state.lastSequence += 1;
+    state.resumeCursor = read.value.resumeCursor;
+    this.post(parseApplicationPortFrame({
+      ...applicationPortFrameBase(this.options.grant, state.frame),
+      frameKind: "stream-item",
+      streamId: source.streamId,
+      sequence: state.lastSequence,
+      ...read.value.resumeCursor === void 0 ? {} : { resumeCursor: read.value.resumeCursor },
+      consistency: read.value.consistency,
+      body: read.value.body
+    }));
+    return true;
+  }
+  async startStreamSource(state, frame, operation) {
+    const context = {
+      body: frame.frameKind === "request" ? frame.body : null,
+      grant: this.options.grant,
+      requestId: frame.requestId,
+      signal: state.controller.signal
+    };
+    if (frame.frameKind === "request") return await operation.open(context);
+    if (operation.resume === void 0) {
+      throw new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.operationUnavailable,
+        "Stream operation does not implement resume"
+      );
+    }
+    return await operation.resume({
+      ...context,
+      lastAcceptedSequence: frame.lastAcceptedSequence,
+      resumeCursor: frame.resumeCursor,
+      streamId: frame.streamId
+    });
+  }
+  startUnary(frame, operation) {
+    const state = {
+      controller: new AbortController(),
+      frame,
+      isCancelled: false,
+      isTerminal: false,
+      kind: "unary"
+    };
+    this.requests.set(frame.requestId, state);
+    state.completion = this.runUnary(state, frame, operation);
+  }
+  terminateStreamWithError(state, cause, code) {
+    const source = state.source;
+    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({
+      ...applicationPortFrameBase(this.options.grant, state.frame),
+      frameKind: "stream-error",
+      streamId: source.streamId,
+      lastSequence: Math.max(0, state.lastSequence),
+      ...state.resumeCursor === void 0 ? {} : { resumeCursor: state.resumeCursor },
+      error
+    }));
+    this.requests.delete(state.frame.requestId);
+  }
+  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) {
+      throw new ApplicationPortProxyError(
+        ApplicationPortProxyErrorCode.streamStateInvalid,
+        "Stream source conflicts with its grant or resume request"
+      );
+    }
+  }
+};
+function createApplicationPortHost(options) {
+  return new ApplicationPortHostInstance(options);
+}
+
+// src/applicationPortWire.ts
+import {
+  canonicalizeIJson as canonicalizeIJson2,
+  IdentifierZod,
+  parseStrictJsonText,
+  PortAttachmentGrantZod as PortAttachmentGrantZod3,
+  PortFrameZod as PortFrameZod2
+} from "@xyo-network/dapp-kit";
+import { z } from "zod";
+var ApplicationPortTransportSchema = "network.xyo.dapp.port.transport";
+var ApplicationPortTransportHelloZod = z.strictObject({
+  schema: z.literal(ApplicationPortTransportSchema),
+  schemaVersion: z.literal(1),
+  messageKind: z.literal("hello"),
+  maximumFrameBytes: z.number().int().positive().max(16 * 1024 * 1024),
+  grant: PortAttachmentGrantZod3
+});
+var ApplicationPortTransportErrorZod = z.strictObject({
+  schema: z.literal(ApplicationPortTransportSchema),
+  schemaVersion: z.literal(1),
+  messageKind: z.literal("error"),
+  code: IdentifierZod,
+  retriable: z.boolean()
+});
+var ApplicationPortWireMessageZod = z.union([
+  PortFrameZod2,
+  ApplicationPortTransportHelloZod,
+  ApplicationPortTransportErrorZod
+]);
+var ApplicationPortWireErrorCode = {
+  frameTooLarge: "port.wire-frame-too-large",
+  invalidMessage: "port.wire-invalid-message"
+};
+var ApplicationPortWireError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "ApplicationPortWireError";
+    this.code = code;
+  }
+};
+function byteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+function verifyMaximumFrameBytes(value) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > 16 * 1024 * 1024) {
+    throw new RangeError("maximum application-port frame bytes must be between 1 and 16777216");
+  }
+  return value;
+}
+function isApplicationPortFrame(message) {
+  return message.schema === "network.xyo.dapp.port.frame";
+}
+function parseApplicationPortWireText(source, maximumFrameBytes) {
+  const maximum = verifyMaximumFrameBytes(maximumFrameBytes);
+  if (byteLength(source) > maximum) {
+    throw new ApplicationPortWireError(
+      ApplicationPortWireErrorCode.frameTooLarge,
+      `application-port frame exceeds ${maximum} bytes`
+    );
+  }
+  try {
+    return ApplicationPortWireMessageZod.parse(parseStrictJsonText(source, { maximumDepth: 64 }));
+  } catch (cause) {
+    if (cause instanceof ApplicationPortWireError) throw cause;
+    throw new ApplicationPortWireError(
+      ApplicationPortWireErrorCode.invalidMessage,
+      "application-port wire message is invalid",
+      { cause }
+    );
+  }
+}
+function serializeApplicationPortWireMessage(message, maximumFrameBytes) {
+  const maximum = verifyMaximumFrameBytes(maximumFrameBytes);
+  let source;
+  try {
+    source = canonicalizeIJson2(ApplicationPortWireMessageZod.parse(message));
+  } catch (cause) {
+    throw new ApplicationPortWireError(
+      ApplicationPortWireErrorCode.invalidMessage,
+      "application-port wire message is invalid",
+      { cause }
+    );
+  }
+  if (byteLength(source) > maximum) {
+    throw new ApplicationPortWireError(
+      ApplicationPortWireErrorCode.frameTooLarge,
+      `application-port frame exceeds ${maximum} bytes`
+    );
+  }
+  return source;
+}
+
+// src/webSocketApplicationPortClient.ts
+import { PortFrameZod as PortFrameZod3 } from "@xyo-network/dapp-kit";
+var WebSocketApplicationPortClientErrorCode = {
+  aborted: "port.websocket-aborted",
+  closed: "port.websocket-closed",
+  handshakeInvalid: "port.websocket-handshake-invalid",
+  serverRejected: "port.websocket-server-rejected",
+  socketError: "port.websocket-socket-error",
+  timeout: "port.websocket-timeout",
+  urlInvalid: "port.websocket-url-invalid"
+};
+var WebSocketApplicationPortClientError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "WebSocketApplicationPortClientError";
+    this.code = code;
+  }
+};
+function report(options, error) {
+  try {
+    options.onTransportError?.(error);
+  } catch {
+  }
+}
+function webSocketUrl(value) {
+  let url;
+  try {
+    url = new URL(value.toString());
+  } catch (cause) {
+    throw new WebSocketApplicationPortClientError(
+      WebSocketApplicationPortClientErrorCode.urlInvalid,
+      "application-port WebSocket URL is invalid",
+      { cause }
+    );
+  }
+  if (url.protocol !== "ws:" && url.protocol !== "wss:" || url.username !== "" || url.password !== "" || url.hash !== "" || url.search !== "") {
+    throw new WebSocketApplicationPortClientError(
+      WebSocketApplicationPortClientErrorCode.urlInvalid,
+      "application-port URL must be credential-free WebSocket without query or fragment data"
+    );
+  }
+  return url.href;
+}
+function positiveInteger(value, name, maximum) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) {
+    throw new RangeError(`${name} must be between 1 and ${maximum}`);
+  }
+  return value;
+}
+function closeWebSocket(socket, code, reason) {
+  if (socket.readyState === WebSocket.OPEN) socket.close(code, reason);
+  else if (socket.readyState === WebSocket.CONNECTING) socket.close();
+}
+function assertExpectedGrant(grant, expected, now) {
+  if (grant.dappId !== expected.dappId || grant.planId !== expected.planId || grant.protocolVersion !== expected.protocolVersion || grant.expiresAt <= now) {
+    throw new WebSocketApplicationPortClientError(
+      WebSocketApplicationPortClientErrorCode.handshakeInvalid,
+      "application-port attachment does not match the expected dApp, plan, protocol, or lifetime"
+    );
+  }
+}
+var BrowserWebSocketApplicationPortEndpoint = class {
+  listeners = /* @__PURE__ */ new Set();
+  maximumFrameBytes;
+  onFailure;
+  socket;
+  constructor(socket, maximumFrameBytes, onFailure) {
+    this.maximumFrameBytes = maximumFrameBytes;
+    this.onFailure = onFailure;
+    this.socket = socket;
+    this.socket.addEventListener("message", this.receive);
+  }
+  addMessageListener(listener) {
+    this.listeners.add(listener);
+  }
+  dispose() {
+    this.listeners.clear();
+    this.socket.removeEventListener("message", this.receive);
+  }
+  removeMessageListener(listener) {
+    this.listeners.delete(listener);
+  }
+  send(message) {
+    if (this.socket.readyState !== WebSocket.OPEN) {
+      throw new WebSocketApplicationPortClientError(
+        WebSocketApplicationPortClientErrorCode.closed,
+        "application-port WebSocket is not open"
+      );
+    }
+    const frame = PortFrameZod3.parse(message);
+    this.socket.send(serializeApplicationPortWireMessage(frame, this.maximumFrameBytes));
+  }
+  receive = (event) => {
+    try {
+      if (typeof event.data !== "string") {
+        throw new WebSocketApplicationPortClientError(
+          WebSocketApplicationPortClientErrorCode.handshakeInvalid,
+          "binary application-port frames are forbidden"
+        );
+      }
+      const message = parseApplicationPortWireText(event.data, this.maximumFrameBytes);
+      if (!isApplicationPortFrame(message)) {
+        throw new WebSocketApplicationPortClientError(
+          WebSocketApplicationPortClientErrorCode.handshakeInvalid,
+          "server sent a transport control message after attachment"
+        );
+      }
+      for (const listener of this.listeners) listener(message);
+    } catch (error) {
+      this.onFailure(error);
+    }
+  };
+};
+async function connectWebSocketApplicationPort(options) {
+  if (options.signal?.aborted === true) {
+    throw new WebSocketApplicationPortClientError(
+      WebSocketApplicationPortClientErrorCode.aborted,
+      "application-port connection was aborted before launch"
+    );
+  }
+  const maximumFrameBytes = positiveInteger(
+    options.maximumFrameBytes ?? 256 * 1024,
+    "maximum frame bytes",
+    16 * 1024 * 1024
+  );
+  const handshakeTimeoutMs = positiveInteger(options.handshakeTimeoutMs ?? 1e4, "handshake timeout", 6e4);
+  const createWebSocket = options.webSocketFactory ?? ((url) => new WebSocket(url));
+  const socket = createWebSocket(webSocketUrl(options.url));
+  const closed = Promise.withResolvers();
+  socket.addEventListener("close", (event) => closed.resolve({
+    code: event.code,
+    reason: event.reason,
+    wasClean: event.wasClean
+  }), { once: true });
+  let timer;
+  let abortListener;
+  try {
+    const hello = await new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.removeEventListener("message", onMessage);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+        if (abortListener !== void 0) options.signal?.removeEventListener("abort", abortListener);
+      };
+      const fail = (error) => {
+        cleanup();
+        closeWebSocket(socket, 4e3, "attachment failed");
+        reject(error instanceof Error ? error : new Error("application-port attachment failed", { cause: error }));
+      };
+      const onClose = () => fail(new WebSocketApplicationPortClientError(
+        WebSocketApplicationPortClientErrorCode.closed,
+        "application-port WebSocket closed before attachment"
+      ));
+      const onError = () => fail(new WebSocketApplicationPortClientError(
+        WebSocketApplicationPortClientErrorCode.socketError,
+        "application-port WebSocket failed before attachment"
+      ));
+      const onMessage = (event) => {
+        try {
+          if (typeof event.data !== "string") throw new TypeError("binary handshake");
+          const message = parseApplicationPortWireText(event.data, maximumFrameBytes);
+          const rejected = ApplicationPortTransportErrorZod.safeParse(message);
+          if (rejected.success) {
+            fail(new WebSocketApplicationPortClientError(
+              WebSocketApplicationPortClientErrorCode.serverRejected,
+              `application-port server rejected attachment: ${rejected.data.code}`
+            ));
+            return;
+          }
+          const parsed = ApplicationPortTransportHelloZod.parse(message);
+          assertExpectedGrant(parsed.grant, options.expected, options.now());
+          cleanup();
+          resolve(parsed);
+        } catch (cause) {
+          fail(cause instanceof WebSocketApplicationPortClientError ? cause : new WebSocketApplicationPortClientError(
+            WebSocketApplicationPortClientErrorCode.handshakeInvalid,
+            "application-port attachment handshake is invalid",
+            { cause }
+          ));
+        }
+      };
+      abortListener = () => fail(new WebSocketApplicationPortClientError(
+        WebSocketApplicationPortClientErrorCode.aborted,
+        "application-port connection was aborted"
+      ));
+      options.signal?.addEventListener("abort", abortListener, { once: true });
+      socket.addEventListener("message", onMessage);
+      socket.addEventListener("error", onError, { once: true });
+      socket.addEventListener("close", onClose, { once: true });
+      timer = setTimeout(() => fail(new WebSocketApplicationPortClientError(
+        WebSocketApplicationPortClientErrorCode.timeout,
+        "application-port attachment handshake timed out"
+      )), handshakeTimeoutMs);
+    });
+    const negotiatedMaximum = Math.min(maximumFrameBytes, hello.maximumFrameBytes);
+    const endpoint = new BrowserWebSocketApplicationPortEndpoint(socket, negotiatedMaximum, (error) => {
+      report(options, error);
+      closeWebSocket(socket, 4001, "invalid application-port frame");
+    });
+    const client = createApplicationPortClient({
+      authenticatedPrincipalId: hello.grant.principalId,
+      endpoint,
+      grant: hello.grant,
+      nextRequestId: options.nextRequestId,
+      now: options.now,
+      onProtocolError: options.onProtocolError
+    });
+    socket.addEventListener("close", () => {
+      endpoint.dispose();
+      client.close();
+    }, { once: true });
+    let isClosed = false;
+    return {
+      client,
+      grant: hello.grant,
+      whenClosed: closed.promise,
+      close: () => {
+        if (isClosed) return;
+        isClosed = true;
+        client.close();
+        endpoint.dispose();
+        closeWebSocket(socket, 1e3, "client detached");
+      }
+    };
+  } catch (error) {
+    report(options, error);
+    throw error;
+  }
+}
+export {
+  ApplicationPortCancelledError,
+  ApplicationPortProxyError,
+  ApplicationPortProxyErrorCode,
+  ApplicationPortRemoteError,
+  ApplicationPortTransportErrorZod,
+  ApplicationPortTransportHelloZod,
+  ApplicationPortTransportSchema,
+  ApplicationPortWireError,
+  ApplicationPortWireErrorCode,
+  ApplicationPortWireMessageZod,
+  WebSocketApplicationPortClientError,
+  WebSocketApplicationPortClientErrorCode,
+  applicationPortErrorFrame,
+  applicationPortFrameBase,
+  applicationPortOperationGrant,
+  applicationPortOperationKey,
+  connectWebSocketApplicationPort,
+  createApplicationPortClient,
+  createApplicationPortHost,
+  isApplicationPortFrame,
+  parseApplicationPortFrame,
+  parseApplicationPortWireText,
+  serializeApplicationPortWireMessage
+};
+//# sourceMappingURL=index.mjs.map