@defensestation/ysync-go 0.1.0-dev.3.3d87b03

package/src/client/websocket-yjs-provider.ts

@@ -0,0 +1,335 @@
+import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate } from "y-protocols/awareness";
+import * as Y from "yjs";
+import { makeClientId } from "./id.js";
+import type { YjsProviderIdentity, YjsProviderIdentityListener, YjsProviderStatus, YjsProviderStatusListener } from "./provider-status.js";
+
+const REMOTE_ORIGIN = "websocket-remote";
+const DEFAULT_RECONNECT_INITIAL_DELAY_MS = 500;
+const DEFAULT_RECONNECT_MAX_DELAY_MS = 5000;
+const DEFAULT_AWARENESS_THROTTLE_MS = 150;
+
+type WebSocketMessage = {
+  type: string;
+  docId?: string;
+  clientId?: string;
+  senderClientId?: string;
+  sequence?: number;
+  stateVector?: string;
+  update?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  userId?: string;
+  userName?: string;
+  userColor?: string;
+};
+
+export interface WebSocketYjsProviderOptions {
+  ydoc: Y.Doc;
+  docId: string;
+  url?: string;
+  baseUrl?: string;
+  clientId?: string;
+  user: {
+    name: string;
+    color?: string;
+  };
+  reconnectInitialDelayMs?: number;
+  reconnectMaxDelayMs?: number;
+  awarenessThrottleMs?: number;
+}
+
+export class WebSocketYjsProvider {
+  readonly awareness: Awareness;
+  readonly clientId: string;
+
+  private readonly options: Required<
+    Pick<
+      WebSocketYjsProviderOptions,
+      "reconnectInitialDelayMs" | "reconnectMaxDelayMs" | "awarenessThrottleMs"
+    >
+  > &
+    WebSocketYjsProviderOptions;
+  private socket?: WebSocket;
+  private pending: WebSocketMessage[] = [];
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private awarenessSendTimer?: ReturnType<typeof setTimeout>;
+  private awarenessDirty = false;
+  private reconnectDelayMs: number;
+  private destroyed = false;
+  private currentStatus: YjsProviderStatus = "connecting";
+  private readonly statusListeners = new Set<YjsProviderStatusListener>();
+  private currentIdentity?: YjsProviderIdentity;
+  private readonly identityListeners = new Set<YjsProviderIdentityListener>();
+
+  private readonly yjsUpdateHandler = (update: Uint8Array, origin: unknown) => {
+    if (origin === REMOTE_ORIGIN) {
+      return;
+    }
+    this.send({
+      type: "yjs_update",
+      docId: this.options.docId,
+      clientId: this.clientId,
+      update: bytesToBase64(update),
+    });
+  };
+
+  // Only push changes to the LOCAL awareness state. Remote states arrive from
+  // the server already fanned out; re-broadcasting them would multiply every
+  // cursor move by the number of connected clients.
+  private readonly awarenessUpdateHandler = ({ added, updated, removed }: {
+    added: number[];
+    updated: number[];
+    removed: number[];
+  }) => {
+    const local = this.awareness.clientID;
+    if (!added.includes(local) && !updated.includes(local) && !removed.includes(local)) {
+      return;
+    }
+    this.scheduleAwarenessSend();
+  };
+
+  constructor(options: WebSocketYjsProviderOptions) {
+    this.options = {
+      ...options,
+      reconnectInitialDelayMs:
+        options.reconnectInitialDelayMs ?? DEFAULT_RECONNECT_INITIAL_DELAY_MS,
+      reconnectMaxDelayMs:
+        options.reconnectMaxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS,
+      awarenessThrottleMs:
+        options.awarenessThrottleMs ?? DEFAULT_AWARENESS_THROTTLE_MS,
+    };
+    this.clientId = options.clientId ?? makeClientId();
+    this.reconnectDelayMs = this.options.reconnectInitialDelayMs;
+    this.awareness = new Awareness(options.ydoc);
+    this.awareness.setLocalStateField("user", {
+      name: options.user.name,
+      color: options.user.color,
+    });
+    this.options.ydoc.on("update", this.yjsUpdateHandler);
+    // No extra heartbeat timer: y-protocols renews the local awareness state
+    // (bumping its clock) roughly every 15s while idle, which fires this
+    // handler. A fixed-interval resend of the same clock would be ignored by
+    // receivers anyway.
+    this.awareness.on("update", this.awarenessUpdateHandler);
+    this.connect();
+  }
+
+  get status(): YjsProviderStatus {
+    return this.currentStatus;
+  }
+
+  // Server-assigned presence identity; undefined until the join is
+  // acknowledged.
+  get identity(): YjsProviderIdentity | undefined {
+    return this.currentIdentity;
+  }
+
+  // Returns an unsubscribe function.
+  onIdentity(listener: YjsProviderIdentityListener): () => void {
+    this.identityListeners.add(listener);
+    return () => this.identityListeners.delete(listener);
+  }
+
+  private applyIdentity(name?: string, color?: string) {
+    if (!name && !color) return;
+    const identity: YjsProviderIdentity = {
+      name: name || this.options.user.name,
+      color: color ?? this.options.user.color,
+    };
+    this.currentIdentity = identity;
+    this.awareness.setLocalStateField("user", { name: identity.name, color: identity.color });
+    for (const listener of this.identityListeners) listener(identity);
+  }
+
+  // Returns an unsubscribe function.
+  onStatus(listener: YjsProviderStatusListener): () => void {
+    this.statusListeners.add(listener);
+    return () => this.statusListeners.delete(listener);
+  }
+
+  private setStatus(status: YjsProviderStatus) {
+    if (this.currentStatus === status) return;
+    this.currentStatus = status;
+    for (const listener of this.statusListeners) listener(status);
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.options.ydoc.off("update", this.yjsUpdateHandler);
+    this.awareness.off("update", this.awarenessUpdateHandler);
+    // Announce departure while the socket is still usable so peers drop the
+    // cursor immediately instead of after the 30s awareness timeout.
+    this.awareness.setLocalState(null);
+    if (this.socket?.readyState === WebSocket.OPEN) {
+      this.sendNow({
+        type: "awareness_update",
+        docId: this.options.docId,
+        clientId: this.clientId,
+        update: bytesToBase64(encodeAwarenessUpdate(this.awareness, [this.awareness.clientID])),
+      });
+      this.sendNow({ type: "leave", docId: this.options.docId, clientId: this.clientId });
+    }
+    this.destroyed = true;
+    this.setStatus("disconnected");
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+    }
+    if (this.awarenessSendTimer) {
+      clearTimeout(this.awarenessSendTimer);
+    }
+    this.socket?.close();
+  }
+
+  private connect() {
+    if (this.destroyed) {
+      return;
+    }
+    this.setStatus("connecting");
+    const socket = new WebSocket(this.options.url ?? websocketURL(this.options.baseUrl));
+    this.socket = socket;
+    socket.addEventListener("open", () => {
+      this.setStatus("connected");
+      this.reconnectDelayMs = this.options.reconnectInitialDelayMs;
+      this.sendNow({
+        type: "join",
+        docId: this.options.docId,
+        clientId: this.clientId,
+        stateVector: bytesToBase64(Y.encodeStateVector(this.options.ydoc)),
+        userName: this.options.user.name,
+        userColor: this.options.user.color,
+      });
+      this.sendLocalAwarenessNow();
+      for (const message of this.pending.splice(0)) {
+        this.sendNow(message);
+      }
+    });
+    socket.addEventListener("message", (event) => {
+      if (typeof event.data !== "string") {
+        return;
+      }
+      this.applyMessage(JSON.parse(event.data) as WebSocketMessage);
+    });
+    socket.addEventListener("close", () => {
+      if (this.socket === socket) {
+        this.socket = undefined;
+      }
+      this.setStatus("disconnected");
+      this.scheduleReconnect();
+    });
+    socket.addEventListener("error", () => {
+      socket.close();
+    });
+  }
+
+  private scheduleReconnect() {
+    if (this.destroyed || this.reconnectTimer) {
+      return;
+    }
+    const delay = this.reconnectDelayMs;
+    this.reconnectDelayMs = Math.min(
+      this.reconnectDelayMs * 2,
+      this.options.reconnectMaxDelayMs,
+    );
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.connect();
+    }, delay);
+  }
+
+  private send(message: WebSocketMessage) {
+    if (this.socket?.readyState === WebSocket.OPEN) {
+      this.sendNow(message);
+      return;
+    }
+    this.pending.push(message);
+  }
+
+  private sendNow(message: WebSocketMessage) {
+    this.socket?.send(JSON.stringify(message));
+  }
+
+  // Leading + trailing throttle: the first change sends immediately, changes
+  // arriving inside the window (e.g. cursor movement while typing or
+  // selecting) collapse into one trailing send.
+  private scheduleAwarenessSend() {
+    if (this.destroyed) {
+      return;
+    }
+    if (this.awarenessSendTimer) {
+      this.awarenessDirty = true;
+      return;
+    }
+    this.sendLocalAwarenessNow();
+    this.awarenessSendTimer = setTimeout(() => {
+      this.awarenessSendTimer = undefined;
+      if (this.awarenessDirty) {
+        this.awarenessDirty = false;
+        this.scheduleAwarenessSend();
+      }
+    }, this.options.awarenessThrottleMs);
+  }
+
+  private sendLocalAwarenessNow() {
+    if (this.destroyed) {
+      return;
+    }
+    this.send({
+      type: "awareness_update",
+      docId: this.options.docId,
+      clientId: this.clientId,
+      update: bytesToBase64(encodeAwarenessUpdate(this.awareness, [this.awareness.clientID])),
+    });
+  }
+
+  private applyMessage(message: WebSocketMessage) {
+    switch (message.type) {
+      case "joined":
+        this.applyIdentity(message.userName, message.userColor);
+        break;
+      case "sync_update":
+      case "yjs_update":
+        if (message.update) {
+          Y.applyUpdate(this.options.ydoc, base64ToBytes(message.update), REMOTE_ORIGIN);
+        }
+        break;
+      case "awareness_update":
+        if (message.update) {
+          applyAwarenessUpdate(this.awareness, base64ToBytes(message.update), REMOTE_ORIGIN);
+        }
+        break;
+      case "error":
+        console.error("Yjs WebSocket server error", message.errorCode, message.errorMessage);
+        break;
+    }
+  }
+}
+
+function websocketURL(baseUrl?: string): string {
+  const fallback =
+    typeof window !== "undefined" && window.location?.origin
+      ? window.location.origin
+      : "http://localhost:8080";
+  const url = new URL(baseUrl ?? fallback);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = "/ysync/ws";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(binary);
+}
+
+function base64ToBytes(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}