@kyneta/webrtc-transport 1.3.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webrtc-transport.ts"],"sourcesContent":["// webrtc-transport — BYODC WebRTC data channel transport for @kyneta/exchange.\n//\n// \"Bring Your Own Data Channel\" design: the application manages WebRTC\n// connections (signaling, ICE, media streams). This transport attaches\n// to already-established data channels for kyneta document sync.\n//\n// Uses the shared binary pipeline from @kyneta/wire (same as WebSocket):\n//   encodeBinaryAndSend — outbound: encode → fragment → sendFn\n//   decodeBinaryMessages — inbound: reassemble → decode → ChannelMsg[]\n//\n// The transport accepts any object satisfying `DataChannelLike` — a\n// 5-member interface that native RTCDataChannel satisfies structurally\n// and that libraries like simple-peer can conform to via a trivial bridge.\n\nimport type {\n  ChannelId,\n  ChannelMsg,\n  GeneratedChannel,\n  TransportFactory,\n} from \"@kyneta/transport\"\nimport { Transport } from \"@kyneta/transport\"\nimport {\n  decodeBinaryMessages,\n  encodeBinaryAndSend,\n  FragmentReassembler,\n} from \"@kyneta/wire\"\nimport type { DataChannelLike } from \"./data-channel-like.js\"\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/**\n * Default fragment threshold in bytes.\n *\n * SCTP (the underlying transport for WebRTC data channels) has a message\n * size limit of approximately 256KB. 200KB provides a safe margin.\n *\n * This differs from the WebSocket transport's 100KB default, which\n * targets AWS API Gateway's 128KB limit. WebRTC has no such gateway.\n */\nexport const DEFAULT_FRAGMENT_THRESHOLD = 200 * 1024\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/**\n * Configuration options for the WebRTC transport.\n */\nexport interface WebrtcTransportOptions {\n  /**\n   * Fragment threshold in bytes. Messages larger than this are fragmented\n   * for SCTP compatibility. Set to 0 to disable fragmentation (not recommended).\n   *\n   * @default 204800 (200KB)\n   */\n  fragmentThreshold?: number\n}\n\n// ---------------------------------------------------------------------------\n// Internal types\n// ---------------------------------------------------------------------------\n\n/**\n * Context for each attached data channel — stored per remotePeerId.\n */\ntype DataChannelContext = {\n  remotePeerId: string\n  channel: DataChannelLike\n}\n\n/**\n * Internal tracking for an attached data channel.\n */\ntype AttachedChannel = {\n  remotePeerId: string\n  channel: DataChannelLike\n  channelId: ChannelId | null\n  reassembler: FragmentReassembler\n  cleanup: () => void\n}\n\n// ---------------------------------------------------------------------------\n// WebrtcTransport\n// ---------------------------------------------------------------------------\n\n/**\n * WebRTC data channel transport for @kyneta/exchange.\n *\n * Follows a \"Bring Your Own Data Channel\" (BYODC) design — the application\n * manages WebRTC connections and attaches data channels to this transport\n * for kyneta document synchronization.\n *\n * Uses binary CBOR encoding with transport-level fragmentation via\n * `@kyneta/wire` — the same pipeline as the WebSocket transport.\n *\n * ## Usage\n *\n * ```typescript\n * import { Exchange } from \"@kyneta/exchange\"\n * import { createWebrtcTransport } from \"@kyneta/webrtc-transport\"\n *\n * const webrtcTransport = createWebrtcTransport()\n *\n * const exchange = new Exchange({\n *   identity: { peerId: \"alice\", name: \"Alice\" },\n *   transports: [webrtcTransport],\n * })\n *\n * // When a WebRTC connection is established:\n * const cleanup = transport.attachDataChannel(remotePeerId, dataChannel)\n *\n * // When done:\n * cleanup() // or transport.detachDataChannel(remotePeerId)\n * ```\n *\n * ## Ownership\n *\n * The transport does NOT own the data channel. `detachDataChannel()`\n * removes the sync channel and event listeners but does not close the\n * data channel or the peer connection. The application manages the\n * WebRTC connection lifecycle independently.\n */\nexport class WebrtcTransport extends Transport<DataChannelContext> {\n  /**\n   * Map of remotePeerId → attached channel tracking.\n   */\n  readonly #attachedChannels = new Map<string, AttachedChannel>()\n\n  /**\n   * Fragment threshold in bytes.\n   */\n  readonly #fragmentThreshold: number\n\n  constructor(options?: WebrtcTransportOptions) {\n    super({ transportType: \"webrtc-datachannel\" })\n    this.#fragmentThreshold =\n      options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n  }\n\n  // ==========================================================================\n  // Transport abstract method implementations\n  // ==========================================================================\n\n  /**\n   * Generate a channel for a data channel context.\n   *\n   * Called internally by the `Transport` base class when `addChannel()` is\n   * invoked. Users never call this directly — use `attachDataChannel()`.\n   */\n  protected generate(context: DataChannelContext): GeneratedChannel {\n    const { channel } = context\n\n    return {\n      transportType: this.transportType,\n      send: (msg: ChannelMsg) => {\n        if (channel.readyState !== \"open\") {\n          return\n        }\n        encodeBinaryAndSend(msg, this.#fragmentThreshold, data =>\n          channel.send(data),\n        )\n      },\n      stop: () => {\n        // Cleanup is handled by detachDataChannel().\n        // This callback fires when the internal channel is removed.\n      },\n    }\n  }\n\n  /**\n   * Called when the transport starts.\n   *\n   * No-op for WebRTC — channels are added dynamically via\n   * `attachDataChannel()`, not at start time.\n   */\n  async onStart(): Promise<void> {}\n\n  /**\n   * Called when the transport stops.\n   *\n   * Detaches all attached data channels and cleans up resources.\n   */\n  async onStop(): Promise<void> {\n    for (const remotePeerId of [...this.#attachedChannels.keys()]) {\n      this.detachDataChannel(remotePeerId)\n    }\n  }\n\n  // ==========================================================================\n  // Public API — data channel management\n  // ==========================================================================\n\n  /**\n   * Attach a data channel for a remote peer.\n   *\n   * Creates an internal sync channel when the data channel is open\n   * (or waits for the `\"open\"` event if still connecting). The sync\n   * channel triggers the establishment handshake with the remote peer.\n   *\n   * If a data channel is already attached for this peer, the old one\n   * is detached first.\n   *\n   * @param remotePeerId - The stable peer ID of the remote peer\n   * @param channel - Any object satisfying `DataChannelLike`\n   * @returns A cleanup function that calls `detachDataChannel(remotePeerId)`\n   */\n  attachDataChannel(\n    remotePeerId: string,\n    channel: DataChannelLike,\n  ): () => void {\n    // Detach existing channel for this peer if any\n    if (this.#attachedChannels.has(remotePeerId)) {\n      this.detachDataChannel(remotePeerId)\n    }\n\n    // Best-effort: request arraybuffer mode for incoming data.\n    // The message handler doesn't depend on this — it accepts both\n    // ArrayBuffer and Uint8Array regardless.\n    channel.binaryType = \"arraybuffer\"\n\n    // Create reassembler for this data channel\n    const reassembler = new FragmentReassembler({ timeoutMs: 10_000 })\n\n    // Event handlers — stored as named functions for removeEventListener\n    const onOpen = () => {\n      this.#createSyncChannel(remotePeerId)\n    }\n\n    const onClose = () => {\n      this.#removeSyncChannel(remotePeerId)\n    }\n\n    const onError = () => {\n      this.#removeSyncChannel(remotePeerId)\n    }\n\n    const onMessage = (event: any) => {\n      this.#handleMessage(remotePeerId, event)\n    }\n\n    // Cleanup function to remove all event listeners\n    const cleanup = () => {\n      channel.removeEventListener(\"open\", onOpen)\n      channel.removeEventListener(\"close\", onClose)\n      channel.removeEventListener(\"error\", onError)\n      channel.removeEventListener(\"message\", onMessage)\n    }\n\n    // Register event listeners\n    channel.addEventListener(\"open\", onOpen)\n    channel.addEventListener(\"close\", onClose)\n    channel.addEventListener(\"error\", onError)\n    channel.addEventListener(\"message\", onMessage)\n\n    // Track the attached channel\n    const attached: AttachedChannel = {\n      remotePeerId,\n      channel,\n      channelId: null,\n      reassembler,\n      cleanup,\n    }\n    this.#attachedChannels.set(remotePeerId, attached)\n\n    // If the channel is already open, create the sync channel immediately\n    if (channel.readyState === \"open\") {\n      this.#createSyncChannel(remotePeerId)\n    }\n\n    return () => this.detachDataChannel(remotePeerId)\n  }\n\n  /**\n   * Detach a data channel for a remote peer.\n   *\n   * Removes the sync channel, cleans up event listeners, and disposes\n   * the reassembler. Does NOT close the data channel — the application\n   * manages the WebRTC connection lifecycle.\n   *\n   * @param remotePeerId - The peer ID to detach\n   */\n  detachDataChannel(remotePeerId: string): void {\n    const attached = this.#attachedChannels.get(remotePeerId)\n    if (!attached) return\n\n    // Remove the sync channel if it exists\n    this.#removeSyncChannel(remotePeerId)\n\n    // Dispose the reassembler to clean up timers\n    attached.reassembler.dispose()\n\n    // Remove event listeners from the data channel\n    attached.cleanup()\n\n    // Remove from tracking\n    this.#attachedChannels.delete(remotePeerId)\n  }\n\n  /**\n   * Check if a data channel is attached for a peer.\n   */\n  hasDataChannel(remotePeerId: string): boolean {\n    return this.#attachedChannels.has(remotePeerId)\n  }\n\n  /**\n   * Get all peer IDs with attached data channels.\n   */\n  getAttachedPeerIds(): string[] {\n    return [...this.#attachedChannels.keys()]\n  }\n\n  // ==========================================================================\n  // Internal — sync channel lifecycle\n  // ==========================================================================\n\n  /**\n   * Create an internal sync channel for an attached data channel.\n   *\n   * Called when the data channel's `\"open\"` event fires (or immediately\n   * if already open on attach). The sync channel is registered with the\n   * Transport base class, which triggers the establishment handshake.\n   */\n  #createSyncChannel(remotePeerId: string): void {\n    const attached = this.#attachedChannels.get(remotePeerId)\n    if (!attached) return\n\n    // Don't create if already exists\n    if (attached.channelId !== null) return\n\n    // addChannel() creates and registers the sync channel\n    const syncChannel = this.addChannel({\n      remotePeerId,\n      channel: attached.channel,\n    })\n    attached.channelId = syncChannel.channelId\n\n    // Start the establishment handshake\n    this.establishChannel(syncChannel.channelId)\n  }\n\n  /**\n   * Remove the internal sync channel for a peer.\n   */\n  #removeSyncChannel(remotePeerId: string): void {\n    const attached = this.#attachedChannels.get(remotePeerId)\n    if (!attached || attached.channelId === null) return\n\n    this.removeChannel(attached.channelId)\n    attached.channelId = null\n  }\n\n  // ==========================================================================\n  // Internal — message handling\n  // ==========================================================================\n\n  /**\n   * Handle an incoming message from a data channel.\n   *\n   * Extracts binary data from the event, feeding both `ArrayBuffer`\n   * (native RTCDataChannel with binaryType \"arraybuffer\") and\n   * `Uint8Array` (simple-peer and other wrappers) into the shared\n   * decode pipeline.\n   */\n  #handleMessage(remotePeerId: string, event: any): void {\n    const attached = this.#attachedChannels.get(remotePeerId)\n    if (!attached || attached.channelId === null) return\n\n    const syncChannel = this.channels.get(attached.channelId)\n    if (!syncChannel) return\n\n    // Extract bytes — robust to both ArrayBuffer and Uint8Array\n    const raw = event.data\n    const bytes =\n      raw instanceof ArrayBuffer\n        ? new Uint8Array(raw)\n        : raw instanceof Uint8Array\n          ? raw\n          : null\n\n    if (!bytes) {\n      // Unexpected data type (e.g. string) — ignore silently\n      return\n    }\n\n    try {\n      const messages = decodeBinaryMessages(bytes, attached.reassembler)\n      if (messages) {\n        for (const msg of messages) {\n          syncChannel.onReceive(msg)\n        }\n      }\n    } catch (error) {\n      console.error(\n        `[webrtc-transport] Failed to decode message from peer ${remotePeerId}:`,\n        error,\n      )\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory function\n// ---------------------------------------------------------------------------\n\n/**\n * Create a WebRTC transport factory for use with `Exchange`.\n *\n * Returns a `TransportFactory` — pass directly to\n * `Exchange({ transports: [...] })`. The returned transport instance\n * exposes `attachDataChannel()` / `detachDataChannel()` for BYODC\n * data channel management.\n *\n * To access the transport instance after creation, use\n * `exchange.getTransport(\"webrtc-datachannel\")`.\n *\n * @example\n * ```typescript\n * import { Exchange } from \"@kyneta/exchange\"\n * import { createWebrtcTransport } from \"@kyneta/webrtc-transport\"\n *\n * const exchange = new Exchange({\n *   identity: { peerId: \"alice\", name: \"Alice\" },\n *   transports: [createWebrtcTransport()],\n * })\n * ```\n */\nexport function createWebrtcTransport(\n  options?: WebrtcTransportOptions,\n): TransportFactory {\n  return () => new WebrtcTransport(options)\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kyneta/webrtc-transport",
+  "version": "1.3.0",
+  "description": "WebRTC data channel transport for @kyneta/exchange — BYODC (Bring Your Own Data Channel) with DataChannelLike interface",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/exchange/transports/webrtc"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./src/*": "./src/*"
+  },
+  "peerDependencies": {
+    "@kyneta/transport": "^1.3.0",
+    "@kyneta/wire": "^1.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17",
+    "@kyneta/exchange": "^1.3.0",
+    "@kyneta/wire": "^1.3.0",
+    "@kyneta/transport": "^1.3.0",
+    "@kyneta/schema": "^1.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}

package/src/__tests__/mock-data-channel.ts

@@ -0,0 +1,94 @@
+// mock-data-channel — test helper implementing DataChannelLike.
+//
+// Provides a minimal, spy-friendly implementation for testing the
+// WebRTC transport without a real RTCDataChannel or browser environment.
+
+import { vi } from "vitest"
+import type { DataChannelLike } from "../data-channel-like.js"
+
+/**
+ * A mock DataChannelLike for testing.
+ *
+ * Features:
+ * - Configurable initial `readyState`
+ * - `send` is a vitest spy
+ * - `emit(type, event?)` simulates incoming events
+ * - Tracks all addEventListener/removeEventListener calls
+ */
+export class MockDataChannel implements DataChannelLike {
+  readyState: string
+  binaryType = "blob"
+  send = vi.fn<(data: Uint8Array) => void>()
+
+  readonly #listeners = new Map<string, Set<(event: any) => void>>()
+
+  constructor(initialReadyState: string = "connecting") {
+    this.readyState = initialReadyState
+  }
+
+  addEventListener(type: string, listener: (event: any) => void): void {
+    let set = this.#listeners.get(type)
+    if (!set) {
+      set = new Set()
+      this.#listeners.set(type, set)
+    }
+    set.add(listener)
+  }
+
+  removeEventListener(type: string, listener: (event: any) => void): void {
+    const set = this.#listeners.get(type)
+    if (set) {
+      set.delete(listener)
+      if (set.size === 0) this.#listeners.delete(type)
+    }
+  }
+
+  /**
+   * Simulate an event firing on the data channel.
+   *
+   * For "message" events, pass `{ data: ... }` as the event.
+   * For "open"/"close"/"error", no event payload is needed.
+   */
+  emit(type: string, event?: any): void {
+    const set = this.#listeners.get(type)
+    if (!set) return
+    for (const listener of set) {
+      listener(event ?? {})
+    }
+  }
+
+  /**
+   * Simulate the data channel opening.
+   * Sets readyState to "open" and fires the "open" event.
+   */
+  open(): void {
+    this.readyState = "open"
+    this.emit("open")
+  }
+
+  /**
+   * Simulate the data channel closing.
+   * Sets readyState to "closed" and fires the "close" event.
+   */
+  close(): void {
+    this.readyState = "closed"
+    this.emit("close")
+  }
+
+  /**
+   * Get the number of listeners registered for a given event type.
+   */
+  listenerCount(type: string): number {
+    return this.#listeners.get(type)?.size ?? 0
+  }
+
+  /**
+   * Check if any listeners are registered at all.
+   */
+  hasListeners(): boolean {
+    for (const set of this.#listeners.values()) {
+      if (set.size > 0) return true
+    }
+    return false
+  }
+}

package/src/__tests__/simple-peer-bridge.test.ts

@@ -0,0 +1,197 @@
+// simple-peer-bridge.test — demonstrates that a simple-peer-style EventEmitter
+// can be trivially bridged to DataChannelLike and used with WebrtcTransport.
+//
+// The ~20-line fromSimplePeer() bridge function maps simple-peer's
+// EventEmitter API (on/off, "connect"/"data"/"close"/"error") to the
+// DataChannelLike contract (addEventListener/removeEventListener,
+// "open"/"message"/"close"/"error").
+
+import { describe, expect, it, vi } from "vitest"
+import type { DataChannelLike } from "../data-channel-like.js"
+import { WebrtcTransport } from "../webrtc-transport.js"
+
+// ---------------------------------------------------------------------------
+// MockSimplePeer — mimics simple-peer's EventEmitter-style API
+// ---------------------------------------------------------------------------
+
+class MockSimplePeer {
+  connected = false
+  private listeners = new Map<string, Set<(...args: any[]) => void>>()
+
+  on(event: string, fn: (...args: any[]) => void) {
+    let set = this.listeners.get(event)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(fn)
+    return this
+  }
+
+  off(event: string, fn: (...args: any[]) => void) {
+    this.listeners.get(event)?.delete(fn)
+  }
+
+  send(_data: any) {
+    /* no-op for mock */
+  }
+
+  /** Test helper to simulate events */
+  _emit(event: string, ...args: any[]) {
+    for (const fn of this.listeners.get(event) ?? []) fn(...args)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// fromSimplePeer — the ~20-line bridge function under test
+// ---------------------------------------------------------------------------
+
+function fromSimplePeer(peer: MockSimplePeer): DataChannelLike {
+  // Map: DataChannelLike event → simple-peer event
+  const eventMap: Record<string, string> = {
+    open: "connect",
+    close: "close",
+    error: "error",
+    message: "data",
+  }
+
+  // Track wrapped listeners for cleanup
+  const wrapperMap = new Map<Function, Function>()
+
+  return {
+    get readyState() {
+      return peer.connected ? "open" : "connecting"
+    },
+    binaryType: "arraybuffer",
+    send(data: Uint8Array) {
+      peer.send(data)
+    },
+    addEventListener(type: string, listener: (event: any) => void) {
+      const peerEvent = eventMap[type]
+      if (!peerEvent) return
+      const wrapped =
+        type === "message"
+          ? (data: any) => listener({ data })
+          : () => listener({})
+      wrapperMap.set(listener, wrapped)
+      peer.on(peerEvent, wrapped)
+    },
+    removeEventListener(type: string, listener: (event: any) => void) {
+      const peerEvent = eventMap[type]
+      if (!peerEvent) return
+      const wrapped = wrapperMap.get(listener)
+      if (wrapped) {
+        peer.off(peerEvent, wrapped as any)
+        wrapperMap.delete(listener)
+      }
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function initializeTransport(transport: WebrtcTransport) {
+  transport._initialize({
+    identity: { peerId: "local", name: "Local", type: "user" as const },
+    onChannelReceive: vi.fn(),
+    onChannelAdded: vi.fn(),
+    onChannelRemoved: vi.fn(),
+    onChannelEstablish: vi.fn(),
+  })
+  await transport._start()
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("fromSimplePeer bridge", () => {
+  it("satisfies DataChannelLike", () => {
+    const peer = new MockSimplePeer()
+    const dc: DataChannelLike = fromSimplePeer(peer)
+
+    expect(dc.readyState).toBe("connecting")
+    expect(dc.binaryType).toBe("arraybuffer")
+    expect(typeof dc.send).toBe("function")
+    expect(typeof dc.addEventListener).toBe("function")
+    expect(typeof dc.removeEventListener).toBe("function")
+  })
+
+  it("readyState reflects peer.connected", () => {
+    const peer = new MockSimplePeer()
+    const dc = fromSimplePeer(peer)
+
+    expect(dc.readyState).toBe("connecting")
+
+    peer.connected = true
+    expect(dc.readyState).toBe("open")
+
+    peer.connected = false
+    expect(dc.readyState).toBe("connecting")
+  })
+
+  it("open event fires when peer emits connect", () => {
+    const peer = new MockSimplePeer()
+    const dc = fromSimplePeer(peer)
+    const spy = vi.fn()
+
+    dc.addEventListener("open", spy)
+    peer._emit("connect")
+
+    expect(spy).toHaveBeenCalledOnce()
+    expect(spy).toHaveBeenCalledWith({})
+  })
+
+  it("message event wraps data in event object", () => {
+    const peer = new MockSimplePeer()
+    const dc = fromSimplePeer(peer)
+    const spy = vi.fn()
+    const payload = new Uint8Array([1, 2, 3, 4])
+
+    dc.addEventListener("message", spy)
+    peer._emit("data", payload)
+
+    expect(spy).toHaveBeenCalledOnce()
+    expect(spy).toHaveBeenCalledWith({ data: payload })
+  })
+
+  it("removeEventListener cleans up", () => {
+    const peer = new MockSimplePeer()
+    const dc = fromSimplePeer(peer)
+    const spy = vi.fn()
+
+    dc.addEventListener("open", spy)
+    dc.removeEventListener("open", spy)
+    peer._emit("connect")
+
+    expect(spy).not.toHaveBeenCalled()
+  })
+
+  it("works with WebrtcTransport", async () => {
+    const transport = new WebrtcTransport()
+    await initializeTransport(transport)
+
+    const peer = new MockSimplePeer()
+    const dc = fromSimplePeer(peer)
+
+    transport.attachDataChannel("remote-peer", dc)
+
+    // Channel attached but not yet open — no sync channel yet
+    expect(transport.hasDataChannel("remote-peer")).toBe(true)
+    expect(transport.channels.size).toBe(0)
+
+    // Simulate simple-peer connection
+    peer.connected = true
+    peer._emit("connect")
+
+    // Transport should now have a sync channel
+    expect(transport.channels.size).toBe(1)
+
+    // Clean up
+    transport.detachDataChannel("remote-peer")
+    expect(transport.hasDataChannel("remote-peer")).toBe(false)
+    expect(transport.channels.size).toBe(0)
+  })
+})