@kyneta/websocket-transport 1.3.0 → 1.4.0

package/dist/server.js

@@ -1,304 +1,306 @@
-import {
-  wrapNodeWebsocket,
-  wrapStandardWebsocket
-} from "./chunk-PSG3LLT5.js";
-
-// src/server-transport.ts
+import { a as wrapNodeWebsocket, i as READY_STATE, n as WebsocketClientTransport, o as wrapStandardWebsocket } from "./client-transport-DIZ-LJxs.js";
 import { Transport } from "@kyneta/transport";
-
-// src/connection.ts
-import {
-  decodeBinaryMessages,
-  encodeBinaryAndSend,
-  FragmentReassembler
-} from "@kyneta/wire";
-var DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024;
+import { FragmentReassembler, decodeBinaryMessages, encodeBinaryAndSend } from "@kyneta/wire";
+//#region src/connection.ts
+/**
+* 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.
+*/
+const DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024;
+/**
+* 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.
+*/
 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;
-    }
-    encodeBinaryAndSend(
-      msg,
-      this.#fragmentThreshold,
-      (data) => this.#socket.send(data)
-    );
-  }
-  /**
-   * 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;
-    }
-    try {
-      const messages = decodeBinaryMessages(data, this.#reassembler);
-      if (messages) {
-        for (const msg of messages) {
-          this.#handleChannelMessage(msg);
-        }
-      }
-    } catch (error) {
-      console.error("Failed to decode wire message:", 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");
-    }
-  }
+	peerId;
+	channelId;
+	#socket;
+	#channel = null;
+	#started = false;
+	#fragmentThreshold;
+	#reassembler;
+	constructor(peerId, channelId, socket, config) {
+		this.peerId = peerId;
+		this.channelId = channelId;
+		this.#socket = socket;
+		this.#fragmentThreshold = config?.fragmentThreshold ?? 102400;
+		this.#reassembler = new FragmentReassembler({
+			timeoutMs: 1e4,
+			onTimeout: (frameId) => {
+				console.warn(`[WebsocketConnection] Fragment batch timed out: ${frameId}`);
+			}
+		});
+	}
+	/**
+	* Set the channel reference.
+	* Called by the adapter when the channel is created.
+	* @internal
+	*/
+	_setChannel(channel) {
+		this.#channel = channel;
+	}
+	/**
+	* 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;
+		encodeBinaryAndSend(msg, this.#fragmentThreshold, (data) => this.#socket.send(data));
+	}
+	/**
+	* 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 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);
+	}
+	/**
+	* Handle an incoming message from the Websocket.
+	*/
+	#handleMessage(data) {
+		if (typeof data === "string") {
+			this.#handleKeepalive(data);
+			return;
+		}
+		try {
+			const messages = decodeBinaryMessages(data, this.#reassembler);
+			if (messages) for (const msg of messages) this.#handleChannelMessage(msg);
+		} catch (error) {
+			console.error("Failed to decode wire message:", 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
+//#endregion
+//#region src/server-transport.ts
+/**
+* Generate a random peer ID for connections that don't provide one.
+*/
 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;
+	const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+	let result = "ws-";
+	for (let i = 0; i < 12; i++) result += chars.charAt(Math.floor(Math.random() * 62));
+	return result;
 }
+/**
+* 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` (protocol-level)
+* 3. Server upgrades channel and sends present (handled by Synchronizer)
+*
+* The server does NOT call `establishChannel()` — it waits for the
+* client's establish to avoid a race condition where the binary
+* establish could arrive before the client has processed "ready".
+*/
 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
+	#connections = /* @__PURE__ */ new Map();
+	#fragmentThreshold;
+	constructor(options) {
+		super({ transportType: "websocket-server" });
+		this.#fragmentThreshold = options?.fragmentThreshold ?? 102400;
+	}
+	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();
+	}
+	/**
+	* 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;
+	}
 };
+//#endregion
+//#region src/service-client.ts
+/**
+* Create a Websocket client transport for service-to-service connections.
+*
+* This factory is for backend environments (Bun, Node.js) where you need
+* to pass authentication headers during the Websocket upgrade.
+*
+* Note: Headers are a Bun/Node-specific extension. The browser WebSocket API
+* does not support custom headers. For browser clients, use
+* `createWebsocketClient()` and authenticate via URL query parameters.
+*
+* @example
+* ```typescript
+* import { createServiceWebsocketClient } from "@kyneta/websocket-transport/server"
+*
+* const exchange = new Exchange({
+*   transports: [createServiceWebsocketClient({
+*     url: "ws://primary-server:3000/ws",
+*     WebSocket,
+*     headers: { Authorization: "Bearer token" },
+*     reconnect: { enabled: true },
+*   })],
+* })
+* ```
+*/
+function createServiceWebsocketClient(options) {
+	return () => new WebsocketClientTransport(options);
+}
+//#endregion
+export { DEFAULT_FRAGMENT_THRESHOLD, READY_STATE, WebsocketConnection, WebsocketServerTransport, createServiceWebsocketClient, wrapNodeWebsocket, wrapStandardWebsocket };
+
 //# sourceMappingURL=server.js.map