@genation/bridge-peer 0.1.0

package/src/relay/frame-channel.js

@@ -0,0 +1,110 @@
+import { bridgeFrameSchema } from "@genation/bridge-contracts";
+import { BridgePeerError } from "../core/mod.js";
+/** Strict FIFO relay frame channel with bounded cancellable waits. */ export class RelayFrameChannel {
+  #socket;
+  #pending = [];
+  #waiters = [];
+  #unhandled;
+  #onUnexpectedClose;
+  #closing = false;
+  #closed = false;
+  /** Opens one physical socket using the selected platform factory. */ constructor(url, factory){
+    this.#socket = factory(url);
+    this.#socket.addEventListener("message", (event)=>this.#receive(event.data));
+    this.#socket.addEventListener("error", ()=>this.#fail());
+    this.#socket.addEventListener("close", ()=>this.#fail());
+  }
+  /** Installs the handler for unsolicited incoming sessions and control frames. */ setUnhandled(handler) {
+    this.#unhandled = handler;
+    const retained = this.#pending.splice(0);
+    for (const frame of retained)this.#dispatch(frame);
+  }
+  /** Installs the one-shot notification used to enter SDK reconnect. */ setUnexpectedClose(handler) {
+    this.#onUnexpectedClose = handler;
+  }
+  /** Sends one schema-valid public frame or fails with a sanitized transport error. */ send(frame) {
+    try {
+      if (this.#closed || this.#socket.readyState !== WebSocket.OPEN) {
+        throw new Error("socket_not_open");
+      }
+      this.#socket.send(JSON.stringify(bridgeFrameSchema.parse(frame)));
+    } catch  {
+      throw new BridgePeerError("CONNECTION_LOST");
+    }
+  }
+  /** Waits for one matching frame with an absolute bounded timeout and cancellation. */ waitFor(predicate, timeoutMs, signal) {
+    const index = this.#pending.findIndex(predicate);
+    if (index >= 0) return Promise.resolve(this.#pending.splice(index, 1)[0]);
+    if (this.#closed) return Promise.reject(new BridgePeerError("CONNECTION_LOST"));
+    if (signal?.aborted) return Promise.reject(new BridgePeerError("CANCELLED"));
+    return new Promise((resolve, reject)=>{
+      const waiter = {
+        predicate,
+        resolve: (frame)=>resolve(frame),
+        reject,
+        timer: setTimeout(()=>{
+          this.#remove(waiter);
+          reject(new BridgePeerError("DEADLINE_EXCEEDED"));
+        }, Math.max(1, timeoutMs)),
+        signal
+      };
+      if (signal !== undefined) {
+        waiter.abort = ()=>{
+          this.#remove(waiter);
+          reject(new BridgePeerError("CANCELLED"));
+        };
+        signal.addEventListener("abort", waiter.abort, {
+          once: true
+        });
+      }
+      this.#waiters.push(waiter);
+    });
+  }
+  /** Closes the physical socket and rejects every outstanding operation once. */ close() {
+    if (this.#closing || this.#closed) return;
+    this.#closing = true;
+    if (this.#socket.readyState < WebSocket.CLOSING) {
+      this.#socket.close(1000, "bridge_peer_close");
+    }
+    this.#fail();
+  }
+  #receive(value) {
+    try {
+      const frame = bridgeFrameSchema.parse(JSON.parse(String(value)));
+      this.#dispatch(frame);
+    } catch  {
+      this.close();
+    }
+  }
+  #dispatch(frame) {
+    const index = this.#waiters.findIndex((waiter)=>waiter.predicate(frame));
+    if (index >= 0) {
+      const waiter = this.#waiters.splice(index, 1)[0];
+      this.#cleanup(waiter);
+      waiter.resolve(frame);
+      return;
+    }
+    if (this.#unhandled?.(frame) !== true) this.#pending.push(frame);
+  }
+  #remove(waiter) {
+    const index = this.#waiters.indexOf(waiter);
+    if (index >= 0) this.#waiters.splice(index, 1);
+    this.#cleanup(waiter);
+  }
+  #cleanup(waiter) {
+    clearTimeout(waiter.timer);
+    if (waiter.signal !== undefined && waiter.abort !== undefined) {
+      waiter.signal.removeEventListener("abort", waiter.abort);
+    }
+  }
+  #fail() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#pending.length = 0;
+    for (const waiter of this.#waiters.splice(0)){
+      this.#cleanup(waiter);
+      waiter.reject(new BridgePeerError("CONNECTION_LOST"));
+    }
+    if (!this.#closing) this.#onUnexpectedClose?.();
+  }
+}

package/src/relay/identity.d.ts

@@ -0,0 +1,27 @@
+import type { BridgeE2eeInitiator, BridgeE2eeResponder } from "@genation/bridge-contracts/sdk";
+import type { BridgePeerPublicIdentity } from "../core/mod.js";
+/** Public admission fields supplied to one opaque platform proof operation. */ export type BridgeConnectionProofSigningInput = Readonly<{
+  projectId: string;
+  peerId: string;
+  connectionId: string;
+  challenge: string;
+  challengeExpiresAt: number;
+  grant: string;
+}>;
+/** Opaque initiator creation input with no local private key. */ export type BridgeRelayInitiatorInput = Readonly<{
+  prologue: Uint8Array;
+  responderPublicKey: Uint8Array;
+}>;
+/** Opaque responder creation input with no local private key. */ export type BridgeRelayResponderInput = Readonly<{
+  prologue: Uint8Array;
+  initiatorPublicKey: Uint8Array;
+}>;
+/** One platform-owned peer identity exposed only through safe operations. */ export type BridgeRelayIdentity = Readonly<{
+  publicIdentity: BridgePeerPublicIdentity;
+  signConnectionProof(input: BridgeConnectionProofSigningInput): Promise<string>;
+  createInitiator(input: BridgeRelayInitiatorInput): BridgeE2eeInitiator;
+  createResponder(input: BridgeRelayResponderInput): BridgeE2eeResponder;
+}>;
+/** Platform identity loader keyed by the exact Bridge project and peer pair. */ export type BridgeRelayIdentityProvider = Readonly<{
+  load(projectId: string, peerId: string): Promise<BridgeRelayIdentity>;
+}>;

package/src/relay/runtime.d.ts

@@ -0,0 +1,8 @@
+import { type BridgeWebSocketFactory } from "./frame-channel.js";
+import type { BridgeRelayIdentityProvider } from "./identity.js";
+/** Platform-neutral relay runtime dependencies selected before composition. */ export type BridgeRelayRuntimeOptions = Readonly<{
+  relayUrl: string;
+  identityProvider: BridgeRelayIdentityProvider;
+  webSocketFactory?: BridgeWebSocketFactory;
+  operationTimeoutMs?: number;
+}>;