@defensestation/ysync-go 0.1.0-dev.7.0bd462a → 0.1.0-dev.9.f016116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defensestation/ysync-go",
-  "version": "0.1.0-dev.7.0bd462a",
+  "version": "0.1.0-dev.9.f016116",
   "description": "Browser Yjs providers (Connect RPC and WebSocket) for the ysync-go collaboration backend",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "scripts": {
     "generate": "cd .. && PATH=\"./npm/node_modules/.bin:$PATH\" buf generate --template npm/buf.gen.yaml",

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

@@ -1,358 +0,0 @@
-import { Code, ConnectError, createClient, type Interceptor } from "@connectrpc/connect";
-import { createConnectTransport } from "@connectrpc/connect-web";
-import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate } from "y-protocols/awareness";
-import * as Y from "yjs";
-import { type ServerFrame, YjsSyncService } from "../gen/ysync/v1/sync_pb.js";
-import { makeClientId } from "./id.js";
-import type { YjsProviderIdentity, YjsProviderIdentityListener, YjsProviderStatus, YjsProviderStatusListener } from "./provider-status.js";
-
-const REMOTE_ORIGIN = "connectrpc-remote";
-const DEFAULT_RECONNECT_INITIAL_DELAY_MS = 500;
-const DEFAULT_RECONNECT_MAX_DELAY_MS = 5000;
-const DEFAULT_AWARENESS_THROTTLE_MS = 150;
-const DEFAULT_UPDATE_FLUSH_DELAY_MS = 100;
-
-function defaultBaseUrl(): string {
-  return typeof window !== "undefined" && window.location?.origin ? window.location.origin : "http://localhost:8080";
-}
-
-function createDefaultClient(baseUrl: string, user?: { name: string; color?: string }) {
-  const interceptors: Interceptor[] = [];
-  if (user) {
-    // Actor identity for audit history; the server reads these headers on
-    // every RPC. Real deployments should derive identity from auth instead.
-    const asciiOnly = (value: string) => /^[\x20-\x7E]*$/.test(value);
-    interceptors.push((next) => (req) => {
-      if (asciiOnly(user.name)) req.header.set("x-user-name", user.name);
-      if (user.color && asciiOnly(user.color)) req.header.set("x-user-color", user.color);
-      return next(req);
-    });
-  }
-  return createClient(YjsSyncService, createConnectTransport({ baseUrl, useBinaryFormat: true, interceptors }));
-}
-
-export type YjsSyncRpcClient = ReturnType<typeof createDefaultClient>;
-
-export interface ConnectYjsProviderOptions {
-  ydoc: Y.Doc;
-  docId: string;
-  baseUrl?: string;
-  rpcClient?: YjsSyncRpcClient;
-  clientId?: string;
-  user: { name: string; color?: string };
-  reconnectInitialDelayMs?: number;
-  reconnectMaxDelayMs?: number;
-  awarenessThrottleMs?: number;
-  // Micro-batch window for document updates: the first local update in a
-  // window is pushed immediately, updates arriving within the window are
-  // merged into one request. 0 pushes every update individually.
-  updateFlushDelayMs?: number;
-}
-
-// Browser-compatible Connect RPC provider. Browsers cannot open bidirectional
-// Connect streams (fetch has no streaming request bodies), so this provider
-// uses the unary/server-stream workflow from the proto contract:
-// JoinDocument -> StreamDocumentFrames + PushYjsUpdate/PushAwarenessUpdate,
-// then LeaveDocument on teardown. The bidirectional Sync RPC remains available
-// for clients on transports that support it (e.g. connect-go over HTTP/2).
-export class ConnectYjsProvider {
-  readonly awareness: Awareness;
-  readonly clientId: string;
-
-  private readonly client: YjsSyncRpcClient;
-  private readonly options: Required<Pick<ConnectYjsProviderOptions, "reconnectInitialDelayMs" | "reconnectMaxDelayMs" | "awarenessThrottleMs" | "updateFlushDelayMs">> & ConnectYjsProviderOptions;
-  private abortController?: AbortController;
-  private reconnectTimer?: ReturnType<typeof setTimeout>;
-  private awarenessSendTimer?: ReturnType<typeof setTimeout>;
-  private awarenessDirty = false;
-  private updateFlushTimer?: ReturnType<typeof setTimeout>;
-  private updatesDirty = false;
-  private destroyed = false;
-  private joined = false;
-  private reconnectDelayMs: number;
-  private pendingUpdates: Uint8Array[] = [];
-  // The current batch is frozen with its idempotency key so a retry after a
-  // failed push resends the exact same payload; updates queued in the
-  // meantime merge into the NEXT batch.
-  private inFlightBatch?: { key: string; update: Uint8Array };
-  private pushInFlight = false;
-  private updateCounter = 0;
-  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.pendingUpdates.push(update);
-    this.scheduleUpdateFlush();
-  };
-
-  // 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: ConnectYjsProviderOptions) {
-    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,
-      updateFlushDelayMs: options.updateFlushDelayMs ?? DEFAULT_UPDATE_FLUSH_DELAY_MS,
-    };
-    this.clientId = options.clientId ?? makeClientId();
-    this.client = options.rpcClient ?? createDefaultClient(options.baseUrl ?? defaultBaseUrl(), options.user);
-    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 completes.
-  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 so peers drop the cursor immediately instead of
-    // after the 30s awareness timeout.
-    this.awareness.setLocalState(null);
-    if (this.joined) {
-      void this.client
-        .pushAwarenessUpdate({
-          docId: this.options.docId,
-          clientId: this.clientId,
-          awarenessUpdate: encodeAwarenessUpdate(this.awareness, [this.awareness.clientID]),
-        })
-        .catch(() => undefined);
-    }
-    this.destroyed = true;
-    this.setStatus("disconnected");
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
-    if (this.awarenessSendTimer) clearTimeout(this.awarenessSendTimer);
-    if (this.updateFlushTimer) clearTimeout(this.updateFlushTimer);
-    void this.client
-      .leaveDocument({ docId: this.options.docId, clientId: this.clientId })
-      .catch(() => undefined);
-    this.abortController?.abort();
-  }
-
-  private connect() {
-    if (this.destroyed) return;
-    this.abortController?.abort();
-    this.abortController = new AbortController();
-    this.setStatus("connecting");
-    void this.runSession(this.abortController.signal);
-  }
-
-  private async runSession(signal: AbortSignal) {
-    try {
-      const join = await this.client.joinDocument(
-        {
-          docId: this.options.docId,
-          clientId: this.clientId,
-          stateVector: Y.encodeStateVector(this.options.ydoc),
-        },
-        { signal },
-      );
-      for (const update of join.syncUpdates) {
-        if (update.length > 0) Y.applyUpdate(this.options.ydoc, update, REMOTE_ORIGIN);
-      }
-      this.joined = true;
-      this.applyIdentity(join.assignedDisplayName, join.assignedColor);
-      this.setStatus("connected");
-      this.reconnectDelayMs = this.options.reconnectInitialDelayMs;
-      this.sendLocalAwarenessNow();
-      void this.flushUpdates();
-
-      const frames = this.client.streamDocumentFrames(
-        {
-          docId: this.options.docId,
-          clientId: this.clientId,
-          afterSequence: join.sequence,
-        },
-        { signal },
-      );
-      for await (const response of frames) {
-        if (response.frame) this.applyFrame(response.frame);
-      }
-      this.joined = false;
-      if (!this.destroyed && !signal.aborted) {
-        this.setStatus("disconnected");
-        this.scheduleReconnect();
-      }
-    } catch (error) {
-      this.joined = false;
-      if (!this.destroyed && !isAbortError(error)) {
-        this.setStatus("disconnected");
-        console.error("Yjs sync stream failed", error);
-        this.scheduleReconnect();
-      }
-    }
-  }
-
-  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);
-  }
-
-  // Leading + trailing micro-batch, same shape as the awareness throttle.
-  private scheduleUpdateFlush() {
-    if (this.destroyed) return;
-    if (this.options.updateFlushDelayMs <= 0) {
-      void this.flushUpdates();
-      return;
-    }
-    if (this.updateFlushTimer) {
-      this.updatesDirty = true;
-      return;
-    }
-    void this.flushUpdates();
-    this.updateFlushTimer = setTimeout(() => {
-      this.updateFlushTimer = undefined;
-      if (this.updatesDirty) {
-        this.updatesDirty = false;
-        this.scheduleUpdateFlush();
-      }
-    }, this.options.updateFlushDelayMs);
-  }
-
-  private async flushUpdates() {
-    if (this.pushInFlight || !this.joined) return;
-    this.pushInFlight = true;
-    try {
-      while ((this.inFlightBatch || this.pendingUpdates.length > 0) && this.joined && !this.destroyed) {
-        if (!this.inFlightBatch) {
-          // Merge everything queued so far into one push. Under network
-          // latency this naturally batches keystrokes: while one push is in
-          // flight, new updates accumulate and go out as a single request.
-          const batch = this.pendingUpdates.splice(0);
-          this.inFlightBatch = {
-            key: `${this.clientId}-${this.updateCounter++}`,
-            update: batch.length === 1 ? batch[0] : Y.mergeUpdates(batch),
-          };
-        }
-        try {
-          await this.client.pushYjsUpdate({
-            docId: this.options.docId,
-            clientId: this.clientId,
-            yjsUpdate: this.inFlightBatch.update,
-            idempotencyKey: this.inFlightBatch.key,
-          });
-        } catch (error) {
-          if (!this.destroyed && !isAbortError(error)) {
-            console.error("Yjs update push failed", error);
-            this.scheduleReconnect();
-          }
-          return;
-        }
-        this.inFlightBatch = undefined;
-      }
-    } finally {
-      this.pushInFlight = false;
-    }
-  }
-
-  // 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 || !this.joined) return;
-    void this.client
-      .pushAwarenessUpdate({
-        docId: this.options.docId,
-        clientId: this.clientId,
-        awarenessUpdate: encodeAwarenessUpdate(this.awareness, [this.awareness.clientID]),
-      })
-      .catch(() => undefined);
-  }
-
-  private applyFrame(frame: ServerFrame) {
-    switch (frame.payload.case) {
-      case "syncUpdate":
-      case "yjsUpdate":
-        Y.applyUpdate(this.options.ydoc, frame.payload.value, REMOTE_ORIGIN);
-        this.reconnectDelayMs = this.options.reconnectInitialDelayMs;
-        break;
-      case "awarenessUpdate":
-        applyAwarenessUpdate(this.awareness, frame.payload.value, REMOTE_ORIGIN);
-        break;
-      case "error":
-        console.error("Yjs sync server error", frame.payload.value);
-        break;
-    }
-  }
-}
-
-function isAbortError(error: unknown): boolean {
-  if (error instanceof DOMException && error.name === "AbortError") return true;
-  return error instanceof ConnectError && error.code === Code.Canceled;
-}

package/src/client/id.ts

@@ -1,22 +0,0 @@
-export function makeClientId() {
-  const cryptoApi = globalThis.crypto;
-  if (typeof cryptoApi?.randomUUID === "function") {
-    return cryptoApi.randomUUID();
-  }
-
-  if (typeof cryptoApi?.getRandomValues === "function") {
-    const bytes = cryptoApi.getRandomValues(new Uint8Array(16));
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0"));
-    return [
-      hex.slice(0, 4).join(""),
-      hex.slice(4, 6).join(""),
-      hex.slice(6, 8).join(""),
-      hex.slice(8, 10).join(""),
-      hex.slice(10, 16).join(""),
-    ].join("-");
-  }
-
-  return `client-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-}

package/src/client/provider-status.ts

@@ -1,9 +0,0 @@
-export type YjsProviderStatus = "connecting" | "connected" | "disconnected";
-
-export type YjsProviderStatusListener = (status: YjsProviderStatus) => void;
-
-// Presence identity assigned by the server at join time: sanitized display
-// name plus a palette color that is distinct among the room's participants.
-export type YjsProviderIdentity = { name: string; color?: string };
-
-export type YjsProviderIdentityListener = (identity: YjsProviderIdentity) => void;