@kyneta/websocket-transport 1.1.0

package/src/client.ts

@@ -0,0 +1,39 @@
+// client — barrel export for @kyneta/websocket-network-adapter/client.
+//
+// This is the client-side entry point. It exports everything needed
+// to create a Websocket client adapter for browser or service connections.
+
+// ---------------------------------------------------------------------------
+// Client adapter + factory functions
+// ---------------------------------------------------------------------------
+
+export {
+  createServiceWebsocketClient,
+  createWebsocketClient,
+  DEFAULT_FRAGMENT_THRESHOLD,
+  type DisconnectReason,
+  type ServiceWebsocketClientOptions,
+  type WebsocketClientLifecycleEvents,
+  type WebsocketClientOptions,
+  type WebsocketClientState,
+  type WebsocketClientStateTransition,
+  WebsocketClientTransport,
+} from "./client-transport.js"
+
+// ---------------------------------------------------------------------------
+// State machine
+// ---------------------------------------------------------------------------
+
+export { WebsocketClientStateMachine } from "./client-state-machine.js"
+
+// ---------------------------------------------------------------------------
+// Shared types
+// ---------------------------------------------------------------------------
+
+export type {
+  Socket,
+  SocketReadyState,
+  TransitionListener,
+} from "./types.js"
+
+export { wrapStandardWebsocket } from "./types.js"

package/src/connection.ts

@@ -0,0 +1,224 @@
+// connection — WebsocketConnection for server-side peer connections.
+//
+// Wraps a Socket + CBOR codec + FragmentReassembler to provide
+// send/receive for ChannelMsg over a single Websocket connection.
+//
+// Used by WebsocketServerTransport to manage individual client connections.
+// The client adapter handles its own encoding/decoding inline since it
+// manages a single socket with reconnection logic.
+//
+// Ported from @loro-extended/adapter-websocket's WsConnection with
+// kyneta naming conventions and the kyneta wire format.
+
+import type { Channel, ChannelMsg, PeerId } from "@kyneta/exchange"
+import {
+  cborCodec,
+  decodeBinaryFrame,
+  encodeComplete,
+  FragmentReassembler,
+  fragmentPayload,
+  wrapCompleteMessage,
+} from "@kyneta/wire"
+import type { Socket } from "./types.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.
+ */
+export const DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024
+
+/**
+ * Configuration for creating a WebsocketConnection.
+ */
+export 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.
+ */
+export class WebsocketConnection {
+  readonly peerId: PeerId
+  readonly channelId: number
+
+  #socket: Socket
+  #channel: Channel | null = null
+  #started = false
+
+  // Fragmentation support
+  readonly #fragmentThreshold: number
+  readonly #reassembler: FragmentReassembler
+
+  constructor(
+    peerId: PeerId,
+    channelId: number,
+    socket: Socket,
+    config?: WebsocketConnectionConfig,
+  ) {
+    this.peerId = peerId
+    this.channelId = channelId
+    this.#socket = socket
+    this.#fragmentThreshold =
+      config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD
+    this.#reassembler = new FragmentReassembler({
+      timeoutMs: 10_000,
+      onTimeout: (frameId: string) => {
+        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: Channel): void {
+    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(): void {
+    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: ChannelMsg): void {
+    if (this.#socket.readyState !== "open") {
+      return
+    }
+
+    const frame = encodeComplete(cborCodec, msg)
+
+    // Fragment large payloads for cloud infrastructure compatibility
+    if (this.#fragmentThreshold > 0 && frame.length > this.#fragmentThreshold) {
+      const fragments = fragmentPayload(frame, this.#fragmentThreshold)
+      for (const fragment of fragments) {
+        this.#socket.send(fragment)
+      }
+    } else {
+      // Wrap with MESSAGE_COMPLETE prefix for transport layer consistency
+      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(): void {
+    if (this.#socket.readyState !== "open") {
+      return
+    }
+    this.#socket.send("ready")
+  }
+
+  /**
+   * Close the connection and clean up resources.
+   */
+  close(code?: number, reason?: string): void {
+    this.#reassembler.dispose()
+    this.#socket.close(code, reason)
+  }
+
+  // ==========================================================================
+  // INTERNAL — message handling
+  // ==========================================================================
+
+  /**
+   * Handle an incoming message from the Websocket.
+   */
+  #handleMessage(data: Uint8Array | string): void {
+    // Handle keepalive ping/pong (text frames)
+    if (typeof data === "string") {
+      this.#handleKeepalive(data)
+      return
+    }
+
+    // Handle binary protocol messages through reassembler
+    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)
+    }
+    // "pending" status means we're waiting for more fragments — nothing to do
+  }
+
+  /**
+   * 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: ChannelMsg): void {
+    if (!this.#channel) {
+      console.error("Cannot handle message: channel not set")
+      return
+    }
+
+    // Deliver synchronously — the Synchronizer's receive queue prevents recursion
+    this.#channel.onReceive(msg)
+  }
+
+  /**
+   * Handle keepalive ping/pong messages.
+   */
+  #handleKeepalive(text: string): void {
+    if (text === "ping") {
+      this.#socket.send("pong")
+    }
+    // Ignore "pong" and "ready" responses
+  }
+}

package/src/server-transport.ts

@@ -0,0 +1,282 @@
+// server-adapter — Websocket server adapter for @kyneta/exchange.
+//
+// Manages Websocket connections from clients, encoding/decoding via the
+// kyneta wire format. Framework-agnostic — works with any Websocket
+// library through the Socket interface.
+//
+// Usage with Bun:
+//   import { WebsocketServerTransport } from "@kyneta/websocket-network-adapter/server"
+//   import { createBunWebsocketHandlers } from "@kyneta/websocket-network-adapter/bun"
+//
+//   const serverAdapter = new WebsocketServerTransport()
+//   Bun.serve({
+//     websocket: createBunWebsocketHandlers(serverAdapter),
+//     fetch(req, server) { server.upgrade(req); return new Response("", { status: 101 }) },
+//   })
+//
+// Usage with Node.js `ws`:
+//   import { WebsocketServerTransport, wrapNodeWebsocket } from "@kyneta/websocket-network-adapter/server"
+//   import { WebSocketServer } from "ws"
+//
+//   const serverAdapter = new WebsocketServerTransport()
+//   const wss = new WebSocketServer({ server })
+//   wss.on("connection", (ws) => {
+//     const { start } = serverAdapter.handleConnection({ socket: wrapNodeWebsocket(ws) })
+//     start()
+//   })
+//
+// Ported from @loro-extended/adapter-websocket's WsServerNetworkAdapter with
+// kyneta naming conventions and the kyneta 5-message protocol.
+
+import type { ChannelMsg, GeneratedChannel, PeerId } from "@kyneta/exchange"
+import { Transport } from "@kyneta/exchange"
+import {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  WebsocketConnection,
+  type WebsocketConnectionConfig,
+} from "./connection.js"
+import type {
+  Socket,
+  WebsocketConnectionOptions,
+  WebsocketConnectionResult,
+} from "./types.js"
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the Websocket server adapter.
+ */
+export 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
+}
+
+// ---------------------------------------------------------------------------
+// Peer ID generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a random peer ID for connections that don't provide one.
+ */
+function generatePeerId(): PeerId {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+  let result = "ws-"
+  for (let i = 0; i < 12; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length))
+  }
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// WebsocketServerTransport
+// ---------------------------------------------------------------------------
+
+/**
+ * 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".
+ */
+export class WebsocketServerTransport extends Transport<PeerId> {
+  #connections = new Map<PeerId, WebsocketConnection>()
+  readonly #fragmentThreshold: number
+
+  constructor(options?: WebsocketServerTransportOptions) {
+    super({ transportType: "websocket-server" })
+    this.#fragmentThreshold =
+      options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD
+  }
+
+  // ==========================================================================
+  // Adapter abstract method implementations
+  // ==========================================================================
+
+  protected generate(peerId: PeerId): GeneratedChannel {
+    return {
+      transportType: this.transportType,
+      send: (msg: ChannelMsg) => {
+        const connection = this.#connections.get(peerId)
+        if (connection) {
+          connection.send(msg)
+        }
+      },
+      stop: () => {
+        this.unregisterConnection(peerId)
+      },
+    }
+  }
+
+  async onStart(): Promise<void> {
+    // Server adapter starts passively — connections arrive via handleConnection()
+  }
+
+  async onStop(): Promise<void> {
+    // Disconnect all active connections
+    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: WebsocketConnectionOptions,
+  ): WebsocketConnectionResult {
+    const { socket, peerId: providedPeerId } = options
+
+    // Generate peer ID if not provided
+    const peerId = providedPeerId ?? generatePeerId()
+
+    // Check for existing connection with same peer ID
+    const existingConnection = this.#connections.get(peerId)
+    if (existingConnection) {
+      existingConnection.close(1000, "Replaced by new connection")
+      this.unregisterConnection(peerId)
+    }
+
+    // Create channel for this peer
+    const channel = this.addChannel(peerId)
+
+    // Create connection object with fragmentation config
+    const connection = new WebsocketConnection(
+      peerId,
+      channel.channelId,
+      socket,
+      {
+        fragmentThreshold: this.#fragmentThreshold,
+      },
+    )
+    connection._setChannel(channel)
+
+    // Store connection
+    this.#connections.set(peerId, connection)
+
+    // Set up close handler
+    socket.onClose((_code, _reason) => {
+      this.unregisterConnection(peerId)
+    })
+
+    socket.onError(_error => {
+      this.unregisterConnection(peerId)
+    })
+
+    return {
+      connection,
+      start: () => {
+        connection.start()
+
+        // Send ready signal to client so it knows the server is ready
+        // This is a transport-level signal, separate from protocol-level establishment
+        connection.sendReady()
+
+        // NOTE: We do NOT call establishChannel() here.
+        // The client will send establish-request after receiving "ready".
+        // Our channel gets established when the Synchronizer receives
+        // and processes that establish-request.
+        //
+        // This prevents a race condition where our binary establish-request
+        // could arrive before the client has processed "ready" and created
+        // its channel.
+      },
+    }
+  }
+
+  /**
+   * Get an active connection by peer ID.
+   */
+  getConnection(peerId: PeerId): WebsocketConnection | undefined {
+    return this.#connections.get(peerId)
+  }
+
+  /**
+   * Get all active connections.
+   */
+  getAllConnections(): WebsocketConnection[] {
+    return Array.from(this.#connections.values())
+  }
+
+  /**
+   * Check if a peer is connected.
+   */
+  isConnected(peerId: PeerId): boolean {
+    return this.#connections.has(peerId)
+  }
+
+  /**
+   * Unregister a connection, removing its channel and cleaning up state.
+   */
+  unregisterConnection(peerId: PeerId): void {
+    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: ChannelMsg): void {
+    for (const connection of this.#connections.values()) {
+      connection.send(msg)
+    }
+  }
+
+  /**
+   * Get the number of connected peers.
+   */
+  get connectionCount(): number {
+    return this.#connections.size
+  }
+}

package/src/server.ts

@@ -0,0 +1,39 @@
+// server — barrel export for @kyneta/websocket-network-adapter/server.
+//
+// This is the server-side entry point. It exports everything needed
+// to create a Websocket server adapter with any framework.
+
+// ---------------------------------------------------------------------------
+// Server adapter
+// ---------------------------------------------------------------------------
+
+export {
+  WebsocketServerTransport,
+  type WebsocketServerTransportOptions,
+} from "./server-transport.js"
+
+// ---------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------
+
+export {
+  DEFAULT_FRAGMENT_THRESHOLD,
+  WebsocketConnection,
+  type WebsocketConnectionConfig,
+} from "./connection.js"
+
+// ---------------------------------------------------------------------------
+// Shared types + wrappers
+// ---------------------------------------------------------------------------
+
+export type {
+  DisconnectReason,
+  NodeWebsocketLike,
+  Socket,
+  SocketReadyState,
+  WebsocketConnectionHandle,
+  WebsocketConnectionOptions,
+  WebsocketConnectionResult,
+} from "./types.js"
+
+export { wrapNodeWebsocket, wrapStandardWebsocket } from "./types.js"