@multiplatform.one/frappe 6.0.0

package/src/realtime.ts

@@ -0,0 +1,279 @@
+import type { ManagerOptions, Socket, SocketOptions } from "socket.io-client";
+import { io } from "socket.io-client";
+import type { AuthConfig } from "./core/types";
+import { isBrowser } from "./util";
+
+export type Handler = (payload: unknown) => void;
+
+export enum RealtimePlatform {
+  Node = "node",
+  Web = "web",
+  ReactNative = "react-native",
+}
+
+export interface RealtimeConfig {
+  auth?: AuthConfig;
+  baseURL: string;
+  /**
+   * Override the port used for the Socket.IO connection.
+   *
+   * In development the Frappe SocketIO server often runs on a separate port
+   * (e.g. `FRAPPE_SOCKETIO_PORT=9000`) while the main Frappe HTTP server is
+   * on port 8000.  Set this to the SocketIO port so the client connects to
+   * the right place without needing a reverse proxy.
+   *
+   * When omitted the port from `baseURL` is used as-is, which is the correct
+   * behaviour behind a production reverse proxy (e.g. nginx) that maps
+   * `/socket.io` to the SocketIO backend.
+   */
+  socketPort?: number;
+  platform?: RealtimePlatform;
+  socketOptions?: Partial<ManagerOptions & SocketOptions>;
+}
+
+export class RealtimeModule {
+  private socket: Socket | undefined;
+  private handlerMap = new Map<string, Set<Handler>>();
+  /** Tracks events with socket listeners attached to prevent duplicates. */
+  private attachedSocketEvents = new Set<string>();
+  /** Stored socket event handler references for proper cleanup. */
+  private socketEventHandlers = new Map<string, (payload: unknown) => void>();
+  private socketHealthy = false;
+  private isConnecting = false;
+  private config: RealtimeConfig;
+
+  constructor(config: RealtimeConfig) {
+    this.config = {
+      ...config,
+      platform: config.platform || this.detectPlatform(),
+    };
+  }
+
+  private detectPlatform() {
+    if (!isBrowser()) return RealtimePlatform.Node;
+    if (typeof navigator !== "undefined" && navigator.userAgent?.includes("ReactNative")) {
+      return RealtimePlatform.ReactNative;
+    }
+    return RealtimePlatform.Web;
+  }
+
+  private getSocketURL(): string {
+    const base = this.config.baseURL.replace(/\/$/, "");
+    if (!this.config.socketPort) return base;
+    try {
+      const url = new URL(base);
+      url.port = String(this.config.socketPort);
+      return url.toString().replace(/\/$/, "");
+    } catch {
+      // Fallback: replace port via regex when URL constructor isn't available
+      return base.replace(/(:\d+)/, `:${this.config.socketPort}`);
+    }
+  }
+
+  private async getAuthOptions(): Promise<Partial<ManagerOptions & SocketOptions>> {
+    const authOptions: Partial<ManagerOptions & SocketOptions> = {};
+    if (this.config.platform !== RealtimePlatform.Web && this.config.auth?.sessionId) {
+      const sessionId =
+        typeof this.config.auth.sessionId === "function"
+          ? await this.config.auth.sessionId()
+          : this.config.auth.sessionId;
+      const Cookie = `sid=${sessionId}`;
+      authOptions.extraHeaders = {
+        Cookie,
+      };
+      authOptions.transportOptions = {
+        websocket: {
+          extraHeaders: {
+            Cookie,
+          },
+        },
+        polling: {
+          extraHeaders: {
+            Cookie,
+          },
+        },
+      };
+    }
+    if (this.config.auth?.useToken && this.config.auth.token) {
+      const token =
+        typeof this.config.auth.token === "function"
+          ? await this.config.auth.token()
+          : this.config.auth.token;
+      const authType = this.config.auth.type || "Bearer";
+      if (!authOptions.extraHeaders) authOptions.extraHeaders = {};
+      authOptions.extraHeaders.Authorization =
+        authType === "Bearer" ? `Bearer ${token}` : `token ${token}`;
+    }
+    return authOptions;
+  }
+
+  private async connect() {
+    if (this.socket || this.isConnecting) return;
+    this.isConnecting = true;
+    try {
+      const authOptions = await this.getAuthOptions();
+      const socketURL = this.getSocketURL();
+      this.socket = io(socketURL, {
+        autoConnect: false,
+        path: "/socket.io",
+        randomizationFactor: 0.5,
+        reconnection: true,
+        reconnectionAttempts: Number.POSITIVE_INFINITY,
+        reconnectionDelay: 1000,
+        reconnectionDelayMax: 5000,
+        timeout: 20000,
+        transports: ["websocket", "polling"],
+        withCredentials: true,
+        ...authOptions,
+        ...this.config.socketOptions,
+      });
+      this.initHandlers();
+      this.socket.connect();
+    } catch (err) {
+      this.isConnecting = false;
+      throw err;
+    }
+  }
+
+  private initHandlers(): void {
+    if (!this.socket) return;
+    // New socket instance: reset attached event tracking so listeners are re-registered fresh
+    this.attachedSocketEvents.clear();
+    this.socketEventHandlers.clear();
+    this.socket.on("connect", () => {
+      this.isConnecting = false;
+      this.socketHealthy = true;
+      this.emitToHandlers("connected", { sid: this.socket?.id });
+    });
+    this.socket.on("disconnect", (reason) => {
+      this.socketHealthy = false;
+      this.emitToHandlers("disconnect", { reason });
+    });
+    this.socket.on("connect_error", (_error) => {
+      this.isConnecting = false;
+    });
+    // Attach listeners for existing handler events, avoiding duplicates
+    for (const event of this.handlerMap.keys()) {
+      this.attachSocketListener(event);
+    }
+  }
+
+  /**
+   * Attaches a socket listener for an event, storing the reference to prevent duplicates.
+   */
+  private attachSocketListener(event: string): void {
+    if (!this.socket || this.attachedSocketEvents.has(event)) return;
+
+    const handler = (payload: unknown) => {
+      this.emitToHandlers(event, payload);
+    };
+    this.socketEventHandlers.set(event, handler);
+    this.attachedSocketEvents.add(event);
+    this.socket.on(event, handler);
+  }
+
+  /**
+   * Removes a socket listener for an event.
+   */
+  private detachSocketListener(event: string): void {
+    if (!this.socket || !this.attachedSocketEvents.has(event)) return;
+
+    const handler = this.socketEventHandlers.get(event);
+    if (handler) {
+      this.socket.off(event, handler);
+      this.socketEventHandlers.delete(event);
+    }
+    this.attachedSocketEvents.delete(event);
+  }
+
+  private emitToHandlers(event: string, payload: unknown) {
+    const handlerSet = this.handlerMap.get(event);
+    if (!handlerSet) return;
+    for (const handler of handlerSet) {
+      handler(payload);
+    }
+  }
+
+  async on(event: string, handler: Handler): Promise<void> {
+    let handlerSet = this.handlerMap.get(event);
+    if (!handlerSet) {
+      handlerSet = new Set();
+      this.handlerMap.set(event, handlerSet);
+    }
+    handlerSet.add(handler);
+    if (!this.socket && !this.isConnecting) {
+      await this.connect();
+    }
+    // Attach socket listener for this event (safe to call multiple times)
+    this.attachSocketListener(event);
+  }
+
+  off(event: string, handler: Handler): void {
+    const handlerSet = this.handlerMap.get(event);
+    if (!handlerSet) return;
+    handlerSet.delete(handler);
+    if (handlerSet.size === 0) {
+      this.handlerMap.delete(event);
+      this.detachSocketListener(event);
+    }
+  }
+
+  async subscribeDoc(doctype: string, name: string): Promise<void> {
+    if (!this.socket) await this.connect();
+    if (this.socket && this.socketHealthy) {
+      this.socket.emit("doc_subscribe", { doctype, name });
+    }
+  }
+
+  unsubscribeDoc(doctype: string, name: string): void {
+    if (this.socket && this.socketHealthy) {
+      this.socket.emit("doc_unsubscribe", { doctype, name });
+    }
+  }
+
+  async subscribeList(doctype: string, filters?: Record<string, unknown>): Promise<void> {
+    if (!this.socket) await this.connect();
+    if (this.socket && this.socketHealthy) {
+      this.socket.emit("list_subscribe", { doctype, filters });
+    }
+  }
+  unsubscribeList(doctype: string): void {
+    if (this.socket && this.socketHealthy) {
+      this.socket.emit("list_unsubscribe", { doctype });
+    }
+  }
+
+  isHealthy() {
+    return this.socketHealthy && this.socket?.connected === true;
+  }
+
+  disconnect(): void {
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = undefined;
+    }
+    this.handlerMap.clear();
+    this.attachedSocketEvents.clear();
+    this.socketEventHandlers.clear();
+    this.socketHealthy = false;
+    this.isConnecting = false;
+  }
+
+  async updateAuth(auth: AuthConfig) {
+    this.config.auth = auth;
+    this.disconnect();
+    if (this.handlerMap.size > 0) {
+      await this.connect();
+    }
+  }
+
+  emit(event: string, data: unknown) {
+    if (this.socket && this.socketHealthy) {
+      this.socket.emit(event, data);
+    }
+  }
+
+  getSocket() {
+    return this.socket;
+  }
+}