cojson 0.19.20 → 0.19.22

package/src/CojsonMessageChannel/CojsonMessageChannel.ts

@@ -0,0 +1,332 @@
+import type { Peer } from "../sync.js";
+import { ConnectedPeerChannel } from "../streamUtils.js";
+import { MessagePortOutgoingChannel } from "./MessagePortOutgoingChannel.js";
+import type {
+  AcceptFromPortOptions,
+  WaitForConnectionOptions,
+  ExposeOptions,
+  MessageChannelLike,
+  MessagePortLike,
+  PostMessageTarget,
+  ReadyMessage,
+} from "./types.js";
+import {
+  isControlMessage,
+  isPortTransferMessage,
+  isReadyAckMessage,
+  isReadyMessage,
+} from "./types.js";
+import { logger } from "../logger.js";
+
+/**
+ * CojsonMessageChannel provides a low-level API for creating cojson peers
+ * that communicate via the MessageChannel API (or compatible implementations
+ * like Electron's MessageChannelMain).
+ *
+ * Inspired by Comlink, it handles:
+ * - Port management (creating MessageChannels and transferring ports)
+ * - Handshake protocol (ensuring both sides are ready)
+ * - Peer creation (returning a standard cojson Peer)
+ */
+export class CojsonMessageChannel {
+  /**
+   * Expose a cojson connection to a target with a postMessage API.
+   * Creates a MessageChannel, transfers port2 to the target, and waits for handshake.
+   *
+   * @param target - Any object with a postMessage method (Worker, Window, MessagePort, etc.)
+   * @param opts - Configuration options
+   * @returns A promise that resolves to a Peer once the handshake completes
+   */
+  static expose(
+    target: PostMessageTarget,
+    opts: ExposeOptions = {},
+  ): Promise<Peer> {
+    const id = opts.id ?? `channel_${Math.random()}`;
+    const role = opts.role ?? "client";
+
+    // Create or use provided MessageChannel
+    const channel: MessageChannelLike =
+      opts.messageChannel ?? new MessageChannel();
+    const { port1, port2 } = channel;
+
+    return new Promise<Peer>((resolve, reject) => {
+      let resolved = false;
+
+      const cleanup = () => {
+        port1.removeEventListener("message", handleMessage);
+        port1.removeEventListener("messageerror", handleError);
+      };
+
+      const handleError = (evt: unknown) => {
+        if (resolved) return;
+        cleanup();
+        port1.close();
+        reject(
+          new Error("MessageChannel error during handshake", {
+            cause: evt,
+          }),
+        );
+      };
+
+      const handleMessage = (event: unknown) => {
+        const data = (event as MessageEvent).data;
+
+        // Wait for ready acknowledgment from guest
+        if (isReadyAckMessage(data)) {
+          if (resolved) return;
+          resolved = true;
+          cleanup();
+
+          // Create the peer
+          const peer = createPeerFromPort(port1, {
+            id,
+            role,
+            onClose: opts.onClose,
+          });
+
+          resolve(peer);
+        }
+      };
+
+      // Start listening on port1
+      port1.addEventListener("message", handleMessage);
+      port1.addEventListener("messageerror", handleError);
+
+      // Start the port if needed (browser MessagePort requires this)
+      if (port1.start) {
+        port1.start();
+      }
+
+      // Transfer port2 to target
+      // Detect if target is a Window (has postMessage with targetOrigin signature)
+      // We use duck typing: if targetOrigin is provided, assume it's a Window
+      const targetOrigin = opts.targetOrigin ?? "*";
+      const portTransferMessage = { type: "jazz:port", id };
+
+      try {
+        // Try Window-style postMessage first if targetOrigin is specified
+        if (opts.targetOrigin !== undefined) {
+          // Window/iframe: postMessage(data, targetOrigin, [transfer])
+          target.postMessage(portTransferMessage, targetOrigin, [port2]);
+        } else {
+          // Worker/MessagePort style: postMessage(data, [transfer])
+          target.postMessage(portTransferMessage, [port2]);
+        }
+      } catch {
+        // Fallback: try the other signature
+        try {
+          target.postMessage(portTransferMessage, [port2]);
+        } catch (e) {
+          cleanup();
+          port1.close();
+          reject(new Error(`Failed to transfer port to target: ${e}`));
+          return;
+        }
+      }
+
+      // Send ready message with our ID
+      const readyMessage: ReadyMessage = { type: "jazz:ready", id };
+      port1.postMessage(readyMessage);
+    });
+  }
+
+  /**
+   * Wait for an incoming Jazz connection.
+   * Listens for a port transfer message on the global scope and completes the handshake.
+   *
+   * @param opts - Configuration options
+   * @returns A promise that resolves to a Peer once the handshake completes
+   */
+  static waitForConnection(opts: WaitForConnectionOptions = {}): Promise<Peer> {
+    return new Promise<Peer>((resolve) => {
+      let resolved = false;
+
+      const scope = globalThis as unknown as EventTarget;
+
+      const cleanup = () => {
+        scope.removeEventListener("message", handlePortTransfer);
+      };
+
+      const handlePortTransfer = async (event: unknown) => {
+        const messageEvent = event as MessageEvent;
+        const data = messageEvent.data;
+
+        // Check if this is a valid port transfer message
+        if (!isPortTransferMessage(data)) {
+          return;
+        }
+
+        // If id filter is provided, check it against the port transfer message
+        if (opts.id !== undefined && data.id !== opts.id) {
+          return; // Ignore, keep waiting for matching id
+        }
+
+        // Validate origin if in Window context and allowedOrigins is specified
+        if (opts.allowedOrigins && opts.allowedOrigins.length > 0) {
+          const origin = messageEvent.origin;
+          const isAllowed = opts.allowedOrigins.some(
+            (allowed) => allowed === "*" || allowed === origin,
+          );
+          if (!isAllowed) {
+            logger.warn(`Ignoring message from non-allowed origin: ${origin}`);
+            return; // Ignore messages from non-allowed origins
+          }
+        }
+
+        // Get the transferred port
+        const port = messageEvent.ports?.[0] as MessagePortLike | undefined;
+        if (!port) {
+          return; // No port transferred, ignore
+        }
+
+        if (resolved) return;
+        resolved = true;
+        cleanup();
+
+        // Complete the handshake using acceptFromPort
+        // Pass the id from the port transfer message to acceptFromPort
+        const peer = await CojsonMessageChannel.acceptFromPort(port, {
+          ...opts,
+          id: data.id, // Use the id from the port transfer message
+        });
+        resolve(peer);
+      };
+
+      // Start listening for port transfer
+      scope.addEventListener("message", handlePortTransfer);
+    });
+  }
+
+  /**
+   * Accept an incoming Jazz connection from a specific port.
+   * Lower-level API useful for testing or when you already have the port.
+   * This method has no timeout - it will wait indefinitely for the handshake.
+   *
+   * @param port - The MessagePort to accept the connection on
+   * @param opts - Configuration options
+   * @returns A promise that resolves to a Peer once the handshake completes
+   */
+  static acceptFromPort(
+    port: MessagePortLike,
+    opts: AcceptFromPortOptions = {},
+  ): Promise<Peer> {
+    const role = opts.role ?? "client";
+
+    return new Promise<Peer>((resolve) => {
+      let resolved = false;
+      let peerId: string | undefined;
+
+      const cleanup = () => {
+        port.removeEventListener("message", handleMessage);
+        port.removeEventListener("messageerror", handleError);
+      };
+
+      const handleError = () => {
+        if (resolved) return;
+        // On error, just close and let the caller handle it
+        cleanup();
+        port.close();
+      };
+
+      const handleMessage = (event: unknown) => {
+        const data = (event as MessageEvent).data;
+
+        // Wait for ready message from host
+        if (isReadyMessage(data)) {
+          // If id filter is provided, validate it
+          if (opts.id !== undefined && data.id !== opts.id) {
+            return; // Ignore, keep waiting for matching id
+          }
+
+          peerId = data.id;
+
+          // Send acknowledgment
+          port.postMessage({ type: "jazz:ready" });
+
+          if (resolved) return;
+          resolved = true;
+          cleanup();
+
+          // Create the peer
+          const peer = createPeerFromPort(port, {
+            id: peerId,
+            role,
+            onClose: opts.onClose,
+          });
+
+          resolve(peer);
+        }
+      };
+
+      // Start listening
+      port.addEventListener("message", handleMessage);
+      port.addEventListener("messageerror", handleError);
+
+      // Start the port if needed (browser MessagePort requires this)
+      if (port.start) {
+        port.start();
+      }
+    });
+  }
+}
+
+/**
+ * Create a Peer from a MessagePort after handshake is complete.
+ */
+function createPeerFromPort(
+  port: MessagePortLike,
+  opts: {
+    id: string;
+    role: "client" | "server";
+    onClose?: () => void;
+  },
+): Peer {
+  const incoming = new ConnectedPeerChannel();
+  const outgoing = new MessagePortOutgoingChannel(port);
+
+  // Forward messages from port to incoming channel
+  const handleMessage = (event: unknown) => {
+    const data = (event as MessageEvent).data;
+
+    // Skip control messages (they're for handshake only)
+    if (isControlMessage(data)) {
+      return;
+    }
+
+    incoming.push(data);
+  };
+
+  const handleError = () => {
+    incoming.push("Disconnected");
+    incoming.close();
+  };
+
+  port.addEventListener("message", handleMessage);
+  port.addEventListener("messageerror", handleError);
+  port.addEventListener("close", () => {
+    incoming.push("Disconnected");
+    incoming.close();
+  });
+
+  // Handle outgoing channel close
+  outgoing.onClose(() => {
+    port.removeEventListener("message", handleMessage);
+    port.removeEventListener("messageerror", handleError);
+    port.close();
+    incoming.push("Disconnected");
+    incoming.close();
+    opts.onClose?.();
+  });
+
+  // Handle incoming channel close (propagate to outgoing)
+  incoming.onClose(() => {
+    outgoing.close();
+  });
+
+  return {
+    id: opts.id,
+    incoming,
+    outgoing,
+    role: opts.role,
+  };
+}

package/src/CojsonMessageChannel/MessagePortOutgoingChannel.ts

@@ -0,0 +1,52 @@
+import type {
+  DisconnectedError,
+  OutgoingPeerChannel,
+  SyncMessage,
+} from "../sync.js";
+import type { MessagePortLike } from "./types.js";
+
+/**
+ * An implementation of OutgoingPeerChannel that sends messages via a MessagePortLike.
+ *
+ * Messages are sent directly using the port's postMessage method,
+ * which uses structured cloning (no JSON serialization needed).
+ */
+export class MessagePortOutgoingChannel implements OutgoingPeerChannel {
+  private port: MessagePortLike;
+  private closed = false;
+  private closeListeners = new Set<() => void>();
+
+  constructor(port: MessagePortLike) {
+    this.port = port;
+  }
+
+  push(msg: SyncMessage | DisconnectedError): void {
+    if (this.closed) {
+      return;
+    }
+
+    if (msg === "Disconnected") {
+      this.close();
+      return;
+    }
+
+    this.port.postMessage(msg);
+  }
+
+  close(): void {
+    if (this.closed) {
+      return;
+    }
+
+    this.closed = true;
+    this.port.close();
+
+    for (const listener of this.closeListeners) {
+      listener();
+    }
+  }
+
+  onClose(callback: () => void): void {
+    this.closeListeners.add(callback);
+  }
+}

package/src/CojsonMessageChannel/index.ts

@@ -0,0 +1,9 @@
+export { CojsonMessageChannel } from "./CojsonMessageChannel.js";
+export type {
+  AcceptFromPortOptions,
+  WaitForConnectionOptions,
+  ExposeOptions,
+  MessageChannelLike,
+  PostMessageTarget,
+  MessagePortLike,
+} from "./types.js";

package/src/CojsonMessageChannel/types.ts

@@ -0,0 +1,200 @@
+/**
+ * Type definitions for JazzMessageChannel
+ *
+ * These types support cross-context communication via MessageChannel API
+ * and compatible implementations (e.g., Electron's MessageChannelMain).
+ */
+
+/**
+ * Duck-typed interface for any object that can receive messages via postMessage.
+ *
+ * Covers:
+ * - Worker
+ * - Window (including iframes via contentWindow)
+ * - MessagePort
+ * - ServiceWorker
+ * - Client (Service Worker clients)
+ * - Electron's WebContents (renderer windows)
+ */
+export interface PostMessageTarget {
+  postMessage(message: unknown, transfer?: MessagePortLike[]): void;
+  postMessage(
+    message: unknown,
+    targetOrigin: string,
+    transfer?: MessagePortLike[],
+  ): void;
+}
+
+/**
+ * MessagePort-like interface that covers browser MessagePort and Electron MessagePortMain.
+ *
+ * Note: Electron's MessagePortMain does not have a start() method,
+ * so it's optional here.
+ */
+export interface MessagePortLike {
+  postMessage(message: unknown): void;
+  addEventListener(
+    type: "message" | "messageerror",
+    listener: (event: unknown) => void,
+  ): void;
+  removeEventListener(
+    type: "message" | "messageerror",
+    listener: (event: unknown) => void,
+  ): void;
+  addEventListener(event: "close", listener: () => void): void;
+  removeEventListener(type: "close", listener: () => void): void;
+  /** Optional - not present on Electron's MessagePortMain */
+  start?(): void;
+  close(): void;
+}
+
+/**
+ * MessageChannel-like interface that covers browser MessageChannel
+ * and Electron MessageChannelMain.
+ */
+export interface MessageChannelLike {
+  port1: MessagePortLike;
+  port2: MessagePortLike;
+}
+
+/**
+ * Options for JazzMessageChannel.expose()
+ */
+export interface ExposeOptions {
+  /**
+   * Unique identifier for the peer connection, sent to the guest during handshake.
+   * Both sides will use this same ID for the Peer object.
+   * If not provided, a unique ID will be generated using `channel_${Math.random()}`.
+   */
+  id?: string;
+
+  /** Role of the peer in the sync topology */
+  role?: "client" | "server";
+
+  /** Target origin for Window targets (default: "*") */
+  targetOrigin?: string;
+
+  /**
+   * A pre-created MessageChannel to use instead of creating a new one.
+   * Use this for environments where the global MessageChannel is not available,
+   * e.g., Electron main process with MessageChannelMain.
+   * If not provided, a new MessageChannel will be created.
+   */
+  messageChannel?: MessageChannelLike;
+
+  /** Callback when the connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * Options for CojsonMessageChannel.waitForConnection()
+ */
+export interface WaitForConnectionOptions {
+  /**
+   * Expected peer ID to accept.
+   * If provided, only handshakes with matching id will be accepted; others are ignored.
+   * If not provided, any connection will be accepted.
+   */
+  id?: string;
+
+  /** Role of the peer in the sync topology */
+  role?: "client" | "server";
+
+  /** Allowed origins for Window contexts (default: ["*"]) */
+  allowedOrigins?: string[];
+
+  /** Callback when the connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * Options for CojsonMessageChannel.acceptFromPort()
+ * Note: No timeout option - acceptFromPort waits indefinitely.
+ */
+export interface AcceptFromPortOptions {
+  /**
+   * Expected peer ID to accept.
+   * If provided, only handshakes with matching id will be accepted; others are ignored.
+   * If not provided, any connection will be accepted.
+   */
+  id?: string;
+
+  /** Role of the peer in the sync topology */
+  role?: "client" | "server";
+
+  /** Callback when the connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * Port transfer message sent via target.postMessage.
+ * The actual port is transferred via Transferable.
+ */
+export interface PortTransferMessage {
+  type: "jazz:port";
+  /** The peer ID for this connection */
+  id: string;
+}
+
+/**
+ * Ready signal sent from host to guest via MessagePort.
+ * Contains the peer ID that both sides will use.
+ */
+export interface ReadyMessage {
+  type: "jazz:ready";
+  /** The peer ID to use on both sides */
+  id: string;
+}
+
+/**
+ * Acknowledgment sent from guest to host via MessagePort.
+ * No id needed - guest uses the id from the host's ReadyMessage.
+ */
+export interface ReadyAckMessage {
+  type: "jazz:ready";
+}
+
+/**
+ * Union of all control messages used in the handshake protocol.
+ */
+export type ControlMessage =
+  | PortTransferMessage
+  | ReadyMessage
+  | ReadyAckMessage;
+
+/**
+ * Type guard to check if a message is a Jazz control message.
+ * Control messages are identified by having a "type" property starting with "jazz:".
+ */
+export function isControlMessage(msg: unknown): msg is ControlMessage {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    "type" in msg &&
+    typeof msg.type === "string" &&
+    msg.type.startsWith("jazz:")
+  );
+}
+
+/**
+ * Type guard to check if a message is a PortTransferMessage.
+ */
+export function isPortTransferMessage(
+  msg: unknown,
+): msg is PortTransferMessage {
+  return isControlMessage(msg) && msg.type === "jazz:port";
+}
+
+/**
+ * Type guard to check if a message is a ReadyMessage (with id).
+ */
+export function isReadyMessage(msg: unknown): msg is ReadyMessage {
+  return isControlMessage(msg) && msg.type === "jazz:ready" && "id" in msg;
+}
+
+/**
+ * Type guard to check if a message is a ReadyAckMessage (without id).
+ */
+export function isReadyAckMessage(msg: unknown): msg is ReadyAckMessage {
+  return isControlMessage(msg) && msg.type === "jazz:ready" && !("id" in msg);
+}

package/src/GarbageCollector.ts

@@ -2,13 +2,13 @@ import { CoValueCore } from "./coValueCore/coValueCore.js";
 import { GARBAGE_COLLECTOR_CONFIG } from "./config.js";
 import { RawCoID } from "./ids.js";
 
+/**
+ * TTL-based garbage collector for removing unused CoValues from memory.
+ */
 export class GarbageCollector {
   private readonly interval: ReturnType<typeof setInterval>;
 
-  constructor(
-    private readonly coValues: Map<RawCoID, CoValueCore>,
-    private readonly garbageCollectGroups: boolean,
-  ) {
+  constructor(private readonly coValues: Map<RawCoID, CoValueCore>) {
     this.interval = setInterval(() => {
       this.collect();
     }, GARBAGE_COLLECTOR_CONFIG.INTERVAL);
@@ -36,7 +36,7 @@ export class GarbageCollector {
       const timeSinceLastAccessed = currentTime - verified.lastAccessed;
 
       if (timeSinceLastAccessed > GARBAGE_COLLECTOR_CONFIG.MAX_AGE) {
-        coValue.unmount(this.garbageCollectGroups);
+        coValue.unmount();
       }
     }
   }

package/src/SyncStateManager.ts

@@ -4,14 +4,14 @@ import {
   areCurrentSessionsInSyncWith,
 } from "./knownState.js";
 import { PeerState } from "./PeerState.js";
-import { PeerID, SyncManager } from "./sync.js";
+import { Peer, PeerID, SyncManager } from "./sync.js";
 
 export type SyncState = {
   uploaded: boolean;
 };
 
 export type GlobalSyncStateListenerCallback = (
-  peerId: PeerID,
+  peer: Peer,
   knownState: CoValueKnownState,
   sync: SyncState,
 ) => void;
@@ -93,10 +93,10 @@ export class SyncStateManager {
     };
   }
 
-  triggerUpdate(peerId: PeerID, id: RawCoID, knownState: CoValueKnownState) {
+  triggerUpdate(peer: Peer, id: RawCoID, knownState: CoValueKnownState) {
     const globalListeners = this.listeners;
     const coValueListeners = this.listenersByCoValues.get(id);
-    const peerMap = this.listenersByPeersAndCoValues.get(peerId);
+    const peerMap = this.listenersByPeersAndCoValues.get(peer.id);
     const coValueAndPeerListeners = peerMap?.get(id);
 
     if (
@@ -113,12 +113,12 @@ export class SyncStateManager {
     };
 
     for (const listener of this.listeners) {
-      listener(peerId, knownState, syncState);
+      listener(peer, knownState, syncState);
     }
 
     if (coValueListeners) {
       for (const listener of coValueListeners) {
-        listener(peerId, knownState, syncState);
+        listener(peer, knownState, syncState);
       }
     }