@multiplatform.one/frappe 6.0.0

package/src/sync/realtime.ts

@@ -0,0 +1,259 @@
+import type { DbModule } from "../db";
+import type { RealtimeModule } from "../realtime";
+import type { NormalizedCache } from "./normalizedCache";
+import type { RehydrationManager } from "./rehydration";
+import type { SubscriptionManager } from "./subscriptionManager";
+import { RealtimeEventType, RehydrationReason } from "./types";
+import type { ConnectionConfig, SyncOptions } from "./types";
+
+export class RealtimeHandler {
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  private hasConnected = false;
+  private connectionConfig: Required<ConnectionConfig>;
+
+  constructor(
+    private readonly db: DbModule,
+    private readonly realtime: RealtimeModule | undefined,
+    private readonly normalizedCache: NormalizedCache,
+    private readonly subscriptionManager: SubscriptionManager,
+    private readonly rehydrationManager: RehydrationManager | undefined,
+    private readonly options: SyncOptions = {},
+  ) {
+    this.connectionConfig = {
+      reconnectBaseDelay: options.connectionConfig?.reconnectBaseDelay ?? 1000,
+      reconnectMaxDelay: options.connectionConfig?.reconnectMaxDelay ?? 30000,
+      reconnectJitter: options.connectionConfig?.reconnectJitter ?? 0.25,
+      exponentialBackoff: options.connectionConfig?.exponentialBackoff ?? true,
+    };
+    this.setupRealtimeHandlers();
+    this.setupConnectionManagement();
+  }
+
+  /**
+   * Sets up realtime event handlers for document changes.
+   */
+  private setupRealtimeHandlers() {
+    if (!this.realtime) return;
+
+    this.realtime?.on("doc_changed", async (payload) => {
+      if (this.options.onRealtimeEvent)
+        this.options.onRealtimeEvent({
+          type: RealtimeEventType.DocChanged,
+          payload,
+        });
+      return this.onDocChanged(payload as { doctype: string; name: string });
+    });
+
+    this.realtime?.on("doc_deleted", async (payload) => {
+      if (this.options.onRealtimeEvent)
+        this.options.onRealtimeEvent({
+          type: RealtimeEventType.DocDeleted,
+          payload,
+        });
+      return this.onDocDeleted(payload as { doctype: string; name: string });
+    });
+
+    this.realtime?.on("perm_epoch_bump", () => {
+      if (this.options.onRealtimeEvent)
+        this.options.onRealtimeEvent({ type: RealtimeEventType.PermEpochBump });
+      // Delegate cache reset to the main sync module
+      if (this.options.onResetCache) {
+        this.options.onResetCache();
+      }
+    });
+
+    this.realtime?.on("connected", () => {
+      this.onConnected();
+    });
+
+    this.realtime?.on("disconnect", () => {
+      this.onDisconnected();
+    });
+  }
+
+  /**
+   * Sets up connection management with exponential backoff and jitter.
+   */
+  private setupConnectionManagement() {
+    if (!this.realtime) return;
+
+    // Attempt initial connection
+    this.attemptConnection();
+  }
+
+  /**
+   * Handles successful connection.
+   */
+  private onConnected() {
+    this.hasConnected = true;
+    this.reconnectAttempts = 0;
+
+    // Clear any pending reconnection timers
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+
+    if (this.options.onRealtimeEvent) {
+      this.options.onRealtimeEvent({ type: RealtimeEventType.Connected });
+    }
+
+    // Delegate backfill to the main sync module
+    if (this.options.onBackfillAll) {
+      this.options.onBackfillAll();
+    }
+
+    console.debug("[RealtimeHandler] Connected to realtime server");
+  }
+
+  /**
+   * Handles disconnection with automatic reconnection.
+   */
+  private onDisconnected() {
+    console.debug("[RealtimeHandler] Disconnected from realtime server");
+
+    // Only attempt reconnection if we've successfully connected before
+    if (this.hasConnected) {
+      this.scheduleReconnection();
+    }
+  }
+
+  /**
+   * Attempts to connect to the realtime server.
+   */
+  private attemptConnection() {
+    if (!this.realtime) return;
+    // RealtimeModule handles reconnection internally via its reconnection config.
+    // Handlers are already attached in the constructor via setupRealtimeHandlers().
+  }
+
+  /**
+   * Schedules a reconnection attempt with exponential backoff and jitter.
+   */
+  private scheduleReconnection() {
+    // Clear any existing timer
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+    }
+
+    const delay = this.calculateReconnectDelay();
+
+    console.debug(
+      `[RealtimeHandler] Scheduling reconnection attempt ${this.reconnectAttempts + 1} in ${delay}ms`,
+    );
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectAttempts++;
+      this.attemptConnection();
+    }, delay);
+  }
+
+  /**
+   * Calculates the reconnection delay with exponential backoff and jitter.
+   */
+  private calculateReconnectDelay(): number {
+    let delay = this.connectionConfig.reconnectBaseDelay;
+
+    // Apply exponential backoff
+    if (this.connectionConfig.exponentialBackoff) {
+      delay = Math.min(
+        this.connectionConfig.reconnectBaseDelay * 2 ** this.reconnectAttempts,
+        this.connectionConfig.reconnectMaxDelay,
+      );
+    }
+
+    // Apply jitter (±jitter%)
+    const jitterRange = delay * this.connectionConfig.reconnectJitter;
+    const jitter = (Math.random() * 2 - 1) * jitterRange;
+    delay = Math.round(delay + jitter);
+
+    // Ensure delay is within bounds
+    return Math.max(
+      this.connectionConfig.reconnectBaseDelay,
+      Math.min(delay, this.connectionConfig.reconnectMaxDelay),
+    );
+  }
+
+  /**
+   * Realtime handler: authoritative document changed.
+   * Fetches document via REST with current user context to respect permissions,
+   * updates cache, and reconciles subscription membership.
+   */
+  private async onDocChanged(payload: { doctype: string; name: string }) {
+    try {
+      // Fetch authoritative document to respect permissions and server-only fields
+      const document = await this.db.getDoc<any>(payload.doctype, payload.name);
+      this.normalizedCache.upsert(document);
+
+      // Update subscription membership for this document
+      // This returns subscriptions that need rehydration for new documents
+      const subscriptionsNeedingRehydration =
+        this.subscriptionManager.updateSubscriptionMembership(document);
+
+      // Schedule rehydration for subscriptions with new remote documents
+      for (const subscription of subscriptionsNeedingRehydration) {
+        this.rehydrationManager?.scheduleRehydration(subscription, RehydrationReason.RemoteCreate);
+      }
+    } catch (err) {
+      // If fetch fails (permission, network), skip this update
+      // The next backfill will catch any missed changes
+      console.warn(
+        `Failed to fetch document ${payload?.doctype}/${payload?.name} during realtime update:`,
+        err,
+      );
+    }
+  }
+
+  /**
+   * Realtime handler: evicts document from cache and subscriptions.
+   */
+  private async onDocDeleted(payload: { doctype: string; name: string }) {
+    try {
+      // Evict the deleted document from cache
+      this.normalizedCache.remove({
+        doctype: payload.doctype,
+        name: payload.name,
+      });
+
+      // Remove from all subscription memberships
+      // This returns subscriptions that had the document removed
+      const affectedSubscriptions = this.subscriptionManager.removeFromAllSubscriptions(
+        payload.doctype,
+        payload.name,
+      );
+
+      // Schedule rehydration for affected subscriptions to fill the gap
+      for (const subscription of affectedSubscriptions) {
+        this.rehydrationManager?.scheduleRehydration(subscription, RehydrationReason.Delete);
+      }
+    } catch (err) {
+      console.warn(`Failed to process doc_deleted for ${payload?.doctype}/${payload?.name}:`, err);
+    }
+  }
+
+  /**
+   * Checks if realtime is healthy for echo suppression decisions.
+   */
+  isRealtimeHealthy(): boolean {
+    return this.realtime?.isHealthy() ?? false;
+  }
+
+  getIsConnected(): boolean {
+    return this.hasConnected;
+  }
+
+  /**
+   * Disposes of resources and clears timers.
+   */
+  dispose() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+
+    if (this.realtime) {
+      this.realtime?.disconnect();
+    }
+  }
+}