@kyneta/websocket-transport 1.1.0

package/dist/server.d.ts

@@ -0,0 +1,161 @@
+import { PeerId, Channel, ChannelMsg, Transport, GeneratedChannel } from '@kyneta/exchange';
+import { S as Socket, c as WebsocketConnectionOptions, d as WebsocketConnectionResult } from './types-DG_89zA4.js';
+export { D as DisconnectReason, N as NodeWebsocketLike, a as SocketReadyState, e as WebsocketConnectionHandle, f as wrapNodeWebsocket, w as wrapStandardWebsocket } from './types-DG_89zA4.js';
+
+/**
+ * Default fragment threshold in bytes.
+ * Messages larger than this are fragmented for cloud infrastructure compatibility.
+ * AWS API Gateway has a 128KB limit, so 100KB provides a safe margin.
+ */
+declare const DEFAULT_FRAGMENT_THRESHOLD: number;
+/**
+ * Configuration for creating a WebsocketConnection.
+ */
+interface WebsocketConnectionConfig {
+    /**
+     * Fragment threshold in bytes. Messages larger than this are fragmented.
+     * Set to 0 to disable fragmentation (not recommended for cloud deployments).
+     * Default: 100KB (safe for AWS API Gateway's 128KB limit)
+     */
+    fragmentThreshold?: number;
+}
+/**
+ * Represents a single Websocket connection to a peer (server-side).
+ *
+ * Manages encoding, framing, fragmentation, and reassembly for one
+ * connected client. Created by `WebsocketServerTransport.handleConnection()`.
+ *
+ * The connection uses the CBOR codec for binary transport — this is
+ * the natural choice for Websocket's binary frame support.
+ */
+declare class WebsocketConnection {
+    #private;
+    readonly peerId: PeerId;
+    readonly channelId: number;
+    constructor(peerId: PeerId, channelId: number, socket: Socket, config?: WebsocketConnectionConfig);
+    /**
+     * Set the channel reference.
+     * Called by the adapter when the channel is created.
+     * @internal
+     */
+    _setChannel(channel: Channel): void;
+    /**
+     * Start processing messages on this connection.
+     *
+     * Sets up the message handler on the socket. Must be called after
+     * the connection is fully set up (channel assigned, stored in adapter).
+     */
+    start(): void;
+    /**
+     * Send a ChannelMsg through the Websocket.
+     *
+     * Encodes via CBOR codec → frame → fragment if needed → socket.send().
+     */
+    send(msg: ChannelMsg): void;
+    /**
+     * Send a "ready" signal to the client.
+     *
+     * This is a transport-level text message that tells the client the
+     * server is ready to receive protocol messages. The client creates
+     * its channel and sends establish-request after receiving this.
+     */
+    sendReady(): void;
+    /**
+     * Close the connection and clean up resources.
+     */
+    close(code?: number, reason?: string): void;
+}
+
+/**
+ * Options for the Websocket server adapter.
+ */
+interface WebsocketServerTransportOptions {
+    /**
+     * Fragment threshold in bytes. Messages larger than this are fragmented.
+     * Set to 0 to disable fragmentation (not recommended for cloud deployments).
+     * Default: 100KB (safe for AWS API Gateway's 128KB limit)
+     */
+    fragmentThreshold?: number;
+}
+/**
+ * Websocket server network adapter.
+ *
+ * Framework-agnostic — works with any Websocket library through the
+ * `Socket` interface. Use `handleConnection()` to integrate with your
+ * framework's Websocket upgrade handler.
+ *
+ * Each client connection is tracked as a `WebsocketConnection` keyed
+ * by peer ID. The adapter creates a channel per connection and routes
+ * outbound messages through the connection's send method.
+ *
+ * The connection handshake follows a two-phase protocol:
+ * 1. Server sends text `"ready"` signal (transport-level)
+ * 2. Client sends `establish-request` (protocol-level)
+ * 3. Server responds with `establish-response` (handled by Synchronizer)
+ *
+ * The server does NOT call `establishChannel()` — it waits for the
+ * client's establish-request to avoid a race condition where the binary
+ * establish-request could arrive before the client has processed "ready".
+ */
+declare class WebsocketServerTransport extends Transport<PeerId> {
+    #private;
+    constructor(options?: WebsocketServerTransportOptions);
+    protected generate(peerId: PeerId): GeneratedChannel;
+    onStart(): Promise<void>;
+    onStop(): Promise<void>;
+    /**
+     * Handle a new Websocket connection.
+     *
+     * Call this from your framework's Websocket upgrade handler.
+     * Returns a connection handle and a `start()` function that begins
+     * message processing and sends the "ready" signal.
+     *
+     * @param options - Connection options including the Socket and optional peer ID
+     * @returns A connection handle and start function
+     *
+     * @example Bun
+     * ```typescript
+     * const { start } = serverAdapter.handleConnection({
+     *   socket: wrapBunWebsocket(ws),
+     * })
+     * start()
+     * ```
+     *
+     * @example Node.js ws
+     * ```typescript
+     * wss.on("connection", (ws) => {
+     *   const { start } = serverAdapter.handleConnection({
+     *     socket: wrapNodeWebsocket(ws),
+     *   })
+     *   start()
+     * })
+     * ```
+     */
+    handleConnection(options: WebsocketConnectionOptions): WebsocketConnectionResult;
+    /**
+     * Get an active connection by peer ID.
+     */
+    getConnection(peerId: PeerId): WebsocketConnection | undefined;
+    /**
+     * Get all active connections.
+     */
+    getAllConnections(): WebsocketConnection[];
+    /**
+     * Check if a peer is connected.
+     */
+    isConnected(peerId: PeerId): boolean;
+    /**
+     * Unregister a connection, removing its channel and cleaning up state.
+     */
+    unregisterConnection(peerId: PeerId): void;
+    /**
+     * Broadcast a message to all connected peers.
+     */
+    broadcast(msg: ChannelMsg): void;
+    /**
+     * Get the number of connected peers.
+     */
+    get connectionCount(): number;
+}
+
+export { DEFAULT_FRAGMENT_THRESHOLD, Socket, WebsocketConnection, type WebsocketConnectionConfig, WebsocketConnectionOptions, WebsocketConnectionResult, WebsocketServerTransport, type WebsocketServerTransportOptions };

package/dist/server.js

@@ -0,0 +1,315 @@
+import {
+  wrapNodeWebsocket,
+  wrapStandardWebsocket
+} from "./chunk-5FHT54WT.js";
+
+// src/server-transport.ts
+import { Transport } from "@kyneta/exchange";
+
+// src/connection.ts
+import {
+  cborCodec,
+  decodeBinaryFrame,
+  encodeComplete,
+  FragmentReassembler,
+  fragmentPayload,
+  wrapCompleteMessage
+} from "@kyneta/wire";
+var DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024;
+var WebsocketConnection = class {
+  peerId;
+  channelId;
+  #socket;
+  #channel = null;
+  #started = false;
+  // Fragmentation support
+  #fragmentThreshold;
+  #reassembler;
+  constructor(peerId, channelId, socket, config) {
+    this.peerId = peerId;
+    this.channelId = channelId;
+    this.#socket = socket;
+    this.#fragmentThreshold = config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD;
+    this.#reassembler = new FragmentReassembler({
+      timeoutMs: 1e4,
+      onTimeout: (frameId) => {
+        console.warn(
+          `[WebsocketConnection] Fragment batch timed out: ${frameId}`
+        );
+      }
+    });
+  }
+  // ==========================================================================
+  // INTERNAL API — for adapter use
+  // ==========================================================================
+  /**
+   * Set the channel reference.
+   * Called by the adapter when the channel is created.
+   * @internal
+   */
+  _setChannel(channel) {
+    this.#channel = channel;
+  }
+  // ==========================================================================
+  // PUBLIC API
+  // ==========================================================================
+  /**
+   * Start processing messages on this connection.
+   *
+   * Sets up the message handler on the socket. Must be called after
+   * the connection is fully set up (channel assigned, stored in adapter).
+   */
+  start() {
+    if (this.#started) {
+      return;
+    }
+    this.#started = true;
+    this.#socket.onMessage((data) => {
+      this.#handleMessage(data);
+    });
+  }
+  /**
+   * Send a ChannelMsg through the Websocket.
+   *
+   * Encodes via CBOR codec → frame → fragment if needed → socket.send().
+   */
+  send(msg) {
+    if (this.#socket.readyState !== "open") {
+      return;
+    }
+    const frame = encodeComplete(cborCodec, msg);
+    if (this.#fragmentThreshold > 0 && frame.length > this.#fragmentThreshold) {
+      const fragments = fragmentPayload(frame, this.#fragmentThreshold);
+      for (const fragment of fragments) {
+        this.#socket.send(fragment);
+      }
+    } else {
+      this.#socket.send(wrapCompleteMessage(frame));
+    }
+  }
+  /**
+   * Send a "ready" signal to the client.
+   *
+   * This is a transport-level text message that tells the client the
+   * server is ready to receive protocol messages. The client creates
+   * its channel and sends establish-request after receiving this.
+   */
+  sendReady() {
+    if (this.#socket.readyState !== "open") {
+      return;
+    }
+    this.#socket.send("ready");
+  }
+  /**
+   * Close the connection and clean up resources.
+   */
+  close(code, reason) {
+    this.#reassembler.dispose();
+    this.#socket.close(code, reason);
+  }
+  // ==========================================================================
+  // INTERNAL — message handling
+  // ==========================================================================
+  /**
+   * Handle an incoming message from the Websocket.
+   */
+  #handleMessage(data) {
+    if (typeof data === "string") {
+      this.#handleKeepalive(data);
+      return;
+    }
+    const result = this.#reassembler.receiveRaw(data);
+    if (result.status === "complete") {
+      try {
+        const frame = decodeBinaryFrame(result.data);
+        const messages = cborCodec.decode(frame.content.payload);
+        for (const msg of messages) {
+          this.#handleChannelMessage(msg);
+        }
+      } catch (error) {
+        console.error("Failed to decode wire message:", error);
+      }
+    } else if (result.status === "error") {
+      console.error("Fragment reassembly error:", result.error);
+    }
+  }
+  /**
+   * Handle a decoded channel message.
+   *
+   * Delivers messages synchronously. The Synchronizer's receive queue
+   * handles recursion prevention by queuing messages and processing
+   * them iteratively.
+   */
+  #handleChannelMessage(msg) {
+    if (!this.#channel) {
+      console.error("Cannot handle message: channel not set");
+      return;
+    }
+    this.#channel.onReceive(msg);
+  }
+  /**
+   * Handle keepalive ping/pong messages.
+   */
+  #handleKeepalive(text) {
+    if (text === "ping") {
+      this.#socket.send("pong");
+    }
+  }
+};
+
+// src/server-transport.ts
+function generatePeerId() {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "ws-";
+  for (let i = 0; i < 12; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+var WebsocketServerTransport = class extends Transport {
+  #connections = /* @__PURE__ */ new Map();
+  #fragmentThreshold;
+  constructor(options) {
+    super({ transportType: "websocket-server" });
+    this.#fragmentThreshold = options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD;
+  }
+  // ==========================================================================
+  // Adapter abstract method implementations
+  // ==========================================================================
+  generate(peerId) {
+    return {
+      transportType: this.transportType,
+      send: (msg) => {
+        const connection = this.#connections.get(peerId);
+        if (connection) {
+          connection.send(msg);
+        }
+      },
+      stop: () => {
+        this.unregisterConnection(peerId);
+      }
+    };
+  }
+  async onStart() {
+  }
+  async onStop() {
+    for (const connection of this.#connections.values()) {
+      connection.close(1001, "Server shutting down");
+    }
+    this.#connections.clear();
+  }
+  // ==========================================================================
+  // Connection management
+  // ==========================================================================
+  /**
+   * Handle a new Websocket connection.
+   *
+   * Call this from your framework's Websocket upgrade handler.
+   * Returns a connection handle and a `start()` function that begins
+   * message processing and sends the "ready" signal.
+   *
+   * @param options - Connection options including the Socket and optional peer ID
+   * @returns A connection handle and start function
+   *
+   * @example Bun
+   * ```typescript
+   * const { start } = serverAdapter.handleConnection({
+   *   socket: wrapBunWebsocket(ws),
+   * })
+   * start()
+   * ```
+   *
+   * @example Node.js ws
+   * ```typescript
+   * wss.on("connection", (ws) => {
+   *   const { start } = serverAdapter.handleConnection({
+   *     socket: wrapNodeWebsocket(ws),
+   *   })
+   *   start()
+   * })
+   * ```
+   */
+  handleConnection(options) {
+    const { socket, peerId: providedPeerId } = options;
+    const peerId = providedPeerId ?? generatePeerId();
+    const existingConnection = this.#connections.get(peerId);
+    if (existingConnection) {
+      existingConnection.close(1e3, "Replaced by new connection");
+      this.unregisterConnection(peerId);
+    }
+    const channel = this.addChannel(peerId);
+    const connection = new WebsocketConnection(
+      peerId,
+      channel.channelId,
+      socket,
+      {
+        fragmentThreshold: this.#fragmentThreshold
+      }
+    );
+    connection._setChannel(channel);
+    this.#connections.set(peerId, connection);
+    socket.onClose((_code, _reason) => {
+      this.unregisterConnection(peerId);
+    });
+    socket.onError((_error) => {
+      this.unregisterConnection(peerId);
+    });
+    return {
+      connection,
+      start: () => {
+        connection.start();
+        connection.sendReady();
+      }
+    };
+  }
+  /**
+   * Get an active connection by peer ID.
+   */
+  getConnection(peerId) {
+    return this.#connections.get(peerId);
+  }
+  /**
+   * Get all active connections.
+   */
+  getAllConnections() {
+    return Array.from(this.#connections.values());
+  }
+  /**
+   * Check if a peer is connected.
+   */
+  isConnected(peerId) {
+    return this.#connections.has(peerId);
+  }
+  /**
+   * Unregister a connection, removing its channel and cleaning up state.
+   */
+  unregisterConnection(peerId) {
+    const connection = this.#connections.get(peerId);
+    if (connection) {
+      this.removeChannel(connection.channelId);
+      this.#connections.delete(peerId);
+    }
+  }
+  /**
+   * Broadcast a message to all connected peers.
+   */
+  broadcast(msg) {
+    for (const connection of this.#connections.values()) {
+      connection.send(msg);
+    }
+  }
+  /**
+   * Get the number of connected peers.
+   */
+  get connectionCount() {
+    return this.#connections.size;
+  }
+};
+export {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  WebsocketConnection,
+  WebsocketServerTransport,
+  wrapNodeWebsocket,
+  wrapStandardWebsocket
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server-transport.ts","../src/connection.ts"],"sourcesContent":["// server-adapter — Websocket server adapter for @kyneta/exchange.\n//\n// Manages Websocket connections from clients, encoding/decoding via the\n// kyneta wire format. Framework-agnostic — works with any Websocket\n// library through the Socket interface.\n//\n// Usage with Bun:\n//   import { WebsocketServerTransport } from \"@kyneta/websocket-network-adapter/server\"\n//   import { createBunWebsocketHandlers } from \"@kyneta/websocket-network-adapter/bun\"\n//\n//   const serverAdapter = new WebsocketServerTransport()\n//   Bun.serve({\n//     websocket: createBunWebsocketHandlers(serverAdapter),\n//     fetch(req, server) { server.upgrade(req); return new Response(\"\", { status: 101 }) },\n//   })\n//\n// Usage with Node.js `ws`:\n//   import { WebsocketServerTransport, wrapNodeWebsocket } from \"@kyneta/websocket-network-adapter/server\"\n//   import { WebSocketServer } from \"ws\"\n//\n//   const serverAdapter = new WebsocketServerTransport()\n//   const wss = new WebSocketServer({ server })\n//   wss.on(\"connection\", (ws) => {\n//     const { start } = serverAdapter.handleConnection({ socket: wrapNodeWebsocket(ws) })\n//     start()\n//   })\n//\n// Ported from @loro-extended/adapter-websocket's WsServerNetworkAdapter with\n// kyneta naming conventions and the kyneta 5-message protocol.\n\nimport type { ChannelMsg, GeneratedChannel, PeerId } from \"@kyneta/exchange\"\nimport { Transport } from \"@kyneta/exchange\"\nimport {\n  DEFAULT_FRAGMENT_THRESHOLD,\n  WebsocketConnection,\n  type WebsocketConnectionConfig,\n} from \"./connection.js\"\nimport type {\n  Socket,\n  WebsocketConnectionOptions,\n  WebsocketConnectionResult,\n} from \"./types.js\"\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the Websocket server adapter.\n */\nexport interface WebsocketServerTransportOptions {\n  /**\n   * Fragment threshold in bytes. Messages larger than this are fragmented.\n   * Set to 0 to disable fragmentation (not recommended for cloud deployments).\n   * Default: 100KB (safe for AWS API Gateway's 128KB limit)\n   */\n  fragmentThreshold?: number\n}\n\n// ---------------------------------------------------------------------------\n// Peer ID generation\n// ---------------------------------------------------------------------------\n\n/**\n * Generate a random peer ID for connections that don't provide one.\n */\nfunction generatePeerId(): PeerId {\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\"\n  let result = \"ws-\"\n  for (let i = 0; i < 12; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length))\n  }\n  return result\n}\n\n// ---------------------------------------------------------------------------\n// WebsocketServerTransport\n// ---------------------------------------------------------------------------\n\n/**\n * Websocket server network adapter.\n *\n * Framework-agnostic — works with any Websocket library through the\n * `Socket` interface. Use `handleConnection()` to integrate with your\n * framework's Websocket upgrade handler.\n *\n * Each client connection is tracked as a `WebsocketConnection` keyed\n * by peer ID. The adapter creates a channel per connection and routes\n * outbound messages through the connection's send method.\n *\n * The connection handshake follows a two-phase protocol:\n * 1. Server sends text `\"ready\"` signal (transport-level)\n * 2. Client sends `establish-request` (protocol-level)\n * 3. Server responds with `establish-response` (handled by Synchronizer)\n *\n * The server does NOT call `establishChannel()` — it waits for the\n * client's establish-request to avoid a race condition where the binary\n * establish-request could arrive before the client has processed \"ready\".\n */\nexport class WebsocketServerTransport extends Transport<PeerId> {\n  #connections = new Map<PeerId, WebsocketConnection>()\n  readonly #fragmentThreshold: number\n\n  constructor(options?: WebsocketServerTransportOptions) {\n    super({ transportType: \"websocket-server\" })\n    this.#fragmentThreshold =\n      options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n  }\n\n  // ==========================================================================\n  // Adapter abstract method implementations\n  // ==========================================================================\n\n  protected generate(peerId: PeerId): GeneratedChannel {\n    return {\n      transportType: this.transportType,\n      send: (msg: ChannelMsg) => {\n        const connection = this.#connections.get(peerId)\n        if (connection) {\n          connection.send(msg)\n        }\n      },\n      stop: () => {\n        this.unregisterConnection(peerId)\n      },\n    }\n  }\n\n  async onStart(): Promise<void> {\n    // Server adapter starts passively — connections arrive via handleConnection()\n  }\n\n  async onStop(): Promise<void> {\n    // Disconnect all active connections\n    for (const connection of this.#connections.values()) {\n      connection.close(1001, \"Server shutting down\")\n    }\n    this.#connections.clear()\n  }\n\n  // ==========================================================================\n  // Connection management\n  // ==========================================================================\n\n  /**\n   * Handle a new Websocket connection.\n   *\n   * Call this from your framework's Websocket upgrade handler.\n   * Returns a connection handle and a `start()` function that begins\n   * message processing and sends the \"ready\" signal.\n   *\n   * @param options - Connection options including the Socket and optional peer ID\n   * @returns A connection handle and start function\n   *\n   * @example Bun\n   * ```typescript\n   * const { start } = serverAdapter.handleConnection({\n   *   socket: wrapBunWebsocket(ws),\n   * })\n   * start()\n   * ```\n   *\n   * @example Node.js ws\n   * ```typescript\n   * wss.on(\"connection\", (ws) => {\n   *   const { start } = serverAdapter.handleConnection({\n   *     socket: wrapNodeWebsocket(ws),\n   *   })\n   *   start()\n   * })\n   * ```\n   */\n  handleConnection(\n    options: WebsocketConnectionOptions,\n  ): WebsocketConnectionResult {\n    const { socket, peerId: providedPeerId } = options\n\n    // Generate peer ID if not provided\n    const peerId = providedPeerId ?? generatePeerId()\n\n    // Check for existing connection with same peer ID\n    const existingConnection = this.#connections.get(peerId)\n    if (existingConnection) {\n      existingConnection.close(1000, \"Replaced by new connection\")\n      this.unregisterConnection(peerId)\n    }\n\n    // Create channel for this peer\n    const channel = this.addChannel(peerId)\n\n    // Create connection object with fragmentation config\n    const connection = new WebsocketConnection(\n      peerId,\n      channel.channelId,\n      socket,\n      {\n        fragmentThreshold: this.#fragmentThreshold,\n      },\n    )\n    connection._setChannel(channel)\n\n    // Store connection\n    this.#connections.set(peerId, connection)\n\n    // Set up close handler\n    socket.onClose((_code, _reason) => {\n      this.unregisterConnection(peerId)\n    })\n\n    socket.onError(_error => {\n      this.unregisterConnection(peerId)\n    })\n\n    return {\n      connection,\n      start: () => {\n        connection.start()\n\n        // Send ready signal to client so it knows the server is ready\n        // This is a transport-level signal, separate from protocol-level establishment\n        connection.sendReady()\n\n        // NOTE: We do NOT call establishChannel() here.\n        // The client will send establish-request after receiving \"ready\".\n        // Our channel gets established when the Synchronizer receives\n        // and processes that establish-request.\n        //\n        // This prevents a race condition where our binary establish-request\n        // could arrive before the client has processed \"ready\" and created\n        // its channel.\n      },\n    }\n  }\n\n  /**\n   * Get an active connection by peer ID.\n   */\n  getConnection(peerId: PeerId): WebsocketConnection | undefined {\n    return this.#connections.get(peerId)\n  }\n\n  /**\n   * Get all active connections.\n   */\n  getAllConnections(): WebsocketConnection[] {\n    return Array.from(this.#connections.values())\n  }\n\n  /**\n   * Check if a peer is connected.\n   */\n  isConnected(peerId: PeerId): boolean {\n    return this.#connections.has(peerId)\n  }\n\n  /**\n   * Unregister a connection, removing its channel and cleaning up state.\n   */\n  unregisterConnection(peerId: PeerId): void {\n    const connection = this.#connections.get(peerId)\n    if (connection) {\n      this.removeChannel(connection.channelId)\n      this.#connections.delete(peerId)\n    }\n  }\n\n  /**\n   * Broadcast a message to all connected peers.\n   */\n  broadcast(msg: ChannelMsg): void {\n    for (const connection of this.#connections.values()) {\n      connection.send(msg)\n    }\n  }\n\n  /**\n   * Get the number of connected peers.\n   */\n  get connectionCount(): number {\n    return this.#connections.size\n  }\n}\n","// connection — WebsocketConnection for server-side peer connections.\n//\n// Wraps a Socket + CBOR codec + FragmentReassembler to provide\n// send/receive for ChannelMsg over a single Websocket connection.\n//\n// Used by WebsocketServerTransport to manage individual client connections.\n// The client adapter handles its own encoding/decoding inline since it\n// manages a single socket with reconnection logic.\n//\n// Ported from @loro-extended/adapter-websocket's WsConnection with\n// kyneta naming conventions and the kyneta wire format.\n\nimport type { Channel, ChannelMsg, PeerId } from \"@kyneta/exchange\"\nimport {\n  cborCodec,\n  decodeBinaryFrame,\n  encodeComplete,\n  FragmentReassembler,\n  fragmentPayload,\n  wrapCompleteMessage,\n} from \"@kyneta/wire\"\nimport type { Socket } from \"./types.js\"\n\n/**\n * Default fragment threshold in bytes.\n * Messages larger than this are fragmented for cloud infrastructure compatibility.\n * AWS API Gateway has a 128KB limit, so 100KB provides a safe margin.\n */\nexport const DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024\n\n/**\n * Configuration for creating a WebsocketConnection.\n */\nexport interface WebsocketConnectionConfig {\n  /**\n   * Fragment threshold in bytes. Messages larger than this are fragmented.\n   * Set to 0 to disable fragmentation (not recommended for cloud deployments).\n   * Default: 100KB (safe for AWS API Gateway's 128KB limit)\n   */\n  fragmentThreshold?: number\n}\n\n/**\n * Represents a single Websocket connection to a peer (server-side).\n *\n * Manages encoding, framing, fragmentation, and reassembly for one\n * connected client. Created by `WebsocketServerTransport.handleConnection()`.\n *\n * The connection uses the CBOR codec for binary transport — this is\n * the natural choice for Websocket's binary frame support.\n */\nexport class WebsocketConnection {\n  readonly peerId: PeerId\n  readonly channelId: number\n\n  #socket: Socket\n  #channel: Channel | null = null\n  #started = false\n\n  // Fragmentation support\n  readonly #fragmentThreshold: number\n  readonly #reassembler: FragmentReassembler\n\n  constructor(\n    peerId: PeerId,\n    channelId: number,\n    socket: Socket,\n    config?: WebsocketConnectionConfig,\n  ) {\n    this.peerId = peerId\n    this.channelId = channelId\n    this.#socket = socket\n    this.#fragmentThreshold =\n      config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n    this.#reassembler = new FragmentReassembler({\n      timeoutMs: 10_000,\n      onTimeout: (frameId: string) => {\n        console.warn(\n          `[WebsocketConnection] Fragment batch timed out: ${frameId}`,\n        )\n      },\n    })\n  }\n\n  // ==========================================================================\n  // INTERNAL API — for adapter use\n  // ==========================================================================\n\n  /**\n   * Set the channel reference.\n   * Called by the adapter when the channel is created.\n   * @internal\n   */\n  _setChannel(channel: Channel): void {\n    this.#channel = channel\n  }\n\n  // ==========================================================================\n  // PUBLIC API\n  // ==========================================================================\n\n  /**\n   * Start processing messages on this connection.\n   *\n   * Sets up the message handler on the socket. Must be called after\n   * the connection is fully set up (channel assigned, stored in adapter).\n   */\n  start(): void {\n    if (this.#started) {\n      return\n    }\n    this.#started = true\n\n    this.#socket.onMessage(data => {\n      this.#handleMessage(data)\n    })\n  }\n\n  /**\n   * Send a ChannelMsg through the Websocket.\n   *\n   * Encodes via CBOR codec → frame → fragment if needed → socket.send().\n   */\n  send(msg: ChannelMsg): void {\n    if (this.#socket.readyState !== \"open\") {\n      return\n    }\n\n    const frame = encodeComplete(cborCodec, msg)\n\n    // Fragment large payloads for cloud infrastructure compatibility\n    if (this.#fragmentThreshold > 0 && frame.length > this.#fragmentThreshold) {\n      const fragments = fragmentPayload(frame, this.#fragmentThreshold)\n      for (const fragment of fragments) {\n        this.#socket.send(fragment)\n      }\n    } else {\n      // Wrap with MESSAGE_COMPLETE prefix for transport layer consistency\n      this.#socket.send(wrapCompleteMessage(frame))\n    }\n  }\n\n  /**\n   * Send a \"ready\" signal to the client.\n   *\n   * This is a transport-level text message that tells the client the\n   * server is ready to receive protocol messages. The client creates\n   * its channel and sends establish-request after receiving this.\n   */\n  sendReady(): void {\n    if (this.#socket.readyState !== \"open\") {\n      return\n    }\n    this.#socket.send(\"ready\")\n  }\n\n  /**\n   * Close the connection and clean up resources.\n   */\n  close(code?: number, reason?: string): void {\n    this.#reassembler.dispose()\n    this.#socket.close(code, reason)\n  }\n\n  // ==========================================================================\n  // INTERNAL — message handling\n  // ==========================================================================\n\n  /**\n   * Handle an incoming message from the Websocket.\n   */\n  #handleMessage(data: Uint8Array | string): void {\n    // Handle keepalive ping/pong (text frames)\n    if (typeof data === \"string\") {\n      this.#handleKeepalive(data)\n      return\n    }\n\n    // Handle binary protocol messages through reassembler\n    const result = this.#reassembler.receiveRaw(data)\n\n    if (result.status === \"complete\") {\n      try {\n        const frame = decodeBinaryFrame(result.data)\n        const messages = cborCodec.decode(frame.content.payload)\n        for (const msg of messages) {\n          this.#handleChannelMessage(msg)\n        }\n      } catch (error) {\n        console.error(\"Failed to decode wire message:\", error)\n      }\n    } else if (result.status === \"error\") {\n      console.error(\"Fragment reassembly error:\", result.error)\n    }\n    // \"pending\" status means we're waiting for more fragments — nothing to do\n  }\n\n  /**\n   * Handle a decoded channel message.\n   *\n   * Delivers messages synchronously. The Synchronizer's receive queue\n   * handles recursion prevention by queuing messages and processing\n   * them iteratively.\n   */\n  #handleChannelMessage(msg: ChannelMsg): void {\n    if (!this.#channel) {\n      console.error(\"Cannot handle message: channel not set\")\n      return\n    }\n\n    // Deliver synchronously — the Synchronizer's receive queue prevents recursion\n    this.#channel.onReceive(msg)\n  }\n\n  /**\n   * Handle keepalive ping/pong messages.\n   */\n  #handleKeepalive(text: string): void {\n    if (text === \"ping\") {\n      this.#socket.send(\"pong\")\n    }\n    // Ignore \"pong\" and \"ready\" responses\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/types-DG_89zA4.d.ts

@@ -0,0 +1,149 @@
+import { StateTransition, TransitionListener as TransitionListener$1, PeerId } from '@kyneta/exchange';
+
+/**
+ * Websocket ready states — mirrors the standard WebSocket readyState
+ * values as human-readable strings.
+ */
+type SocketReadyState = "connecting" | "open" | "closing" | "closed";
+/**
+ * Framework-agnostic Websocket interface.
+ *
+ * This allows the adapter to work with any Websocket library:
+ * - Browser `WebSocket` via `wrapStandardWebsocket()`
+ * - Node.js `ws` library via `wrapNodeWebsocket()`
+ * - Bun `ServerWebSocket` via `wrapBunWebsocket()`
+ *
+ * The interface is intentionally minimal — only the operations the
+ * adapter needs are exposed.
+ */
+interface Socket {
+    /** Send binary or text data through the Websocket. */
+    send(data: Uint8Array | string): void;
+    /** Close the Websocket connection. */
+    close(code?: number, reason?: string): void;
+    /** Register a handler for incoming messages (binary or text). */
+    onMessage(handler: (data: Uint8Array | string) => void): void;
+    /** Register a handler for connection close. */
+    onClose(handler: (code: number, reason: string) => void): void;
+    /** Register a handler for errors. */
+    onError(handler: (error: Error) => void): void;
+    /** The current ready state of the Websocket. */
+    readonly readyState: SocketReadyState;
+}
+/**
+ * Options for handling a new Websocket connection on the server.
+ */
+interface WebsocketConnectionOptions {
+    /** The Websocket instance, wrapped in the Socket interface. */
+    socket: Socket;
+    /** Optional peer ID extracted from the upgrade request. */
+    peerId?: PeerId;
+    /** Optional authentication token from the upgrade request. */
+    authToken?: string;
+}
+/**
+ * Handle for an active Websocket connection.
+ */
+interface WebsocketConnectionHandle {
+    /** The peer ID for this connection. */
+    readonly peerId: PeerId;
+    /** The channel ID for this connection. */
+    readonly channelId: number;
+    /** Close the connection. */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Result of handling a Websocket connection on the server.
+ */
+interface WebsocketConnectionResult {
+    /** The connection handle for managing this peer. */
+    connection: WebsocketConnectionHandle;
+    /** Call this to start processing messages. */
+    start(): void;
+}
+/**
+ * Discriminated union describing why a Websocket connection was lost.
+ */
+type DisconnectReason = {
+    type: "intentional";
+} | {
+    type: "error";
+    error: Error;
+} | {
+    type: "closed";
+    code: number;
+    reason: string;
+} | {
+    type: "max-retries-exceeded";
+    attempts: number;
+} | {
+    type: "not-started";
+};
+/**
+ * All possible states of the Websocket client.
+ *
+ * State machine transitions:
+ * ```
+ * disconnected → connecting → connected → ready
+ *                    ↓            ↓         ↓
+ *               reconnecting ← ─ ┴ ─ ─ ─ ─ ┘
+ *                    ↓
+ *               connecting (retry)
+ *                    ↓
+ *               disconnected (max retries)
+ * ```
+ */
+type WebsocketClientState = {
+    status: "disconnected";
+    reason?: DisconnectReason;
+} | {
+    status: "connecting";
+    attempt: number;
+} | {
+    status: "connected";
+} | {
+    status: "ready";
+} | {
+    status: "reconnecting";
+    attempt: number;
+    nextAttemptMs: number;
+};
+/**
+ * A state transition event for websocket client states.
+ * Specialized from the generic `StateTransition<S>`.
+ */
+type WebsocketClientStateTransition = StateTransition<WebsocketClientState>;
+/**
+ * Listener for websocket client state transitions.
+ * Specialized from the generic `TransitionListener<S>`.
+ */
+type TransitionListener = TransitionListener$1<WebsocketClientState>;
+/**
+ * Wrap a standard `WebSocket` (browser or Node.js `ws` via `ws` package
+ * in `WebSocket`-compatible mode) into the `Socket` interface.
+ *
+ * Handles `ArrayBuffer`, `Blob`, and string messages.
+ */
+declare function wrapStandardWebsocket(ws: WebSocket): Socket;
+/**
+ * The minimal interface we need from the Node.js `ws` library's `WebSocket`.
+ *
+ * Using a structural type rather than importing `ws` — consumers provide
+ * the actual `ws` instance, we just need these methods.
+ */
+interface NodeWebsocketLike {
+    send(data: Uint8Array | string): void;
+    close(code?: number, reason?: string): void;
+    on(event: "message", handler: (data: Buffer | ArrayBuffer | string, isBinary: boolean) => void): void;
+    on(event: "close", handler: (code: number, reason: Buffer) => void): void;
+    on(event: "error", handler: (error: Error) => void): void;
+    readyState: number;
+}
+/**
+ * Wrap a Node.js `ws` library WebSocket into the `Socket` interface.
+ *
+ * Handles `Buffer` → `Uint8Array` conversion for binary messages.
+ */
+declare function wrapNodeWebsocket(ws: NodeWebsocketLike): Socket;
+
+export { type DisconnectReason as D, type NodeWebsocketLike as N, type Socket as S, type TransitionListener as T, type WebsocketClientStateTransition as W, type SocketReadyState as a, type WebsocketClientState as b, type WebsocketConnectionOptions as c, type WebsocketConnectionResult as d, type WebsocketConnectionHandle as e, wrapNodeWebsocket as f, wrapStandardWebsocket as w };