@multiplatform.one/frappe 6.1.0 → 6.4.0

package/src/realtime.spec.ts

@@ -1,5 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { RealtimeModule } from "./realtime";
+import { io } from "socket.io-client";
+import { AuthType } from "./core/types";
+import { RealtimeModule, RealtimePlatform } from "./realtime";
 
 // Mock socket.io-client
 const mockSocket = {
@@ -9,7 +11,11 @@ const mockSocket = {
   emit: vi.fn(),
   connect: vi.fn(),
   disconnect: vi.fn(),
+  removeAllListeners: vi.fn(),
   id: "mock-socket-id",
+  // Manager handle: RealtimeModule mutates manager.opts on credential
+  // refresh and registers a reconnect_attempt safety net.
+  io: { opts: {} as Record<string, unknown>, on: vi.fn() },
 };
 
 vi.mock("socket.io-client", () => ({
@@ -67,6 +73,7 @@ describe("RealtimeModule", () => {
         baseURL: "http://localhost:3000",
       });
       expect(rnInstance).toBeDefined();
+      expect((rnInstance as any).config.platform).toBe(RealtimePlatform.ReactNative);
 
       // Restore
       if (originalUA) {
@@ -76,6 +83,105 @@ describe("RealtimeModule", () => {
         });
       }
     });
+
+    it("detects React Native via navigator.product (RN sets no userAgent)", () => {
+      // Real RN runtimes define navigator.product === "ReactNative" and NO
+      // userAgent — the old UA-only sniff misdetected RN as Web, skipping
+      // the extraHeaders auth path (cookie-auth sockets connected as guest).
+      const originalNavigator = (global as any).navigator;
+      Object.defineProperty(global, "navigator", {
+        value: { product: "ReactNative" },
+        writable: true,
+      });
+      const rnInstance = new RealtimeModule({ baseURL: "http://localhost:3000" });
+      expect((rnInstance as any).config.platform).toBe(RealtimePlatform.ReactNative);
+      Object.defineProperty(global, "navigator", {
+        value: originalNavigator,
+        writable: true,
+      });
+    });
+
+    it("keeps detecting Web in a browser-like environment", () => {
+      const webInstance = new RealtimeModule({ baseURL: "http://localhost:3000" });
+      expect((webInstance as any).config.platform).toBe(RealtimePlatform.Web);
+    });
+
+    it("classifies GJS (imports.gi global) as Node — before the Web branch", () => {
+      // GJS has window/document layout stubs in the GNOME bundles, so the
+      // Web classification would otherwise win — but GJS has no XHR for a
+      // polling-first handshake and its libsoup WebSocket polyfill accepts
+      // custom headers, so it must take the non-Web (extraHeaders) path.
+      (globalThis as any).imports = { gi: {} };
+      try {
+        const gjsInstance = new RealtimeModule({ baseURL: "http://localhost:3000" });
+        expect((gjsInstance as any).config.platform).toBe(RealtimePlatform.Node);
+      } finally {
+        delete (globalThis as any).imports;
+      }
+    });
+  });
+
+  describe("GJS handshake", () => {
+    function ioOptions(): Record<string, any> {
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      return calls[calls.length - 1]?.[1] ?? {};
+    }
+
+    it("connects websocket-first with token auth in extraHeaders", async () => {
+      (globalThis as any).imports = { gi: {} };
+      try {
+        const rt = new RealtimeModule({
+          baseURL: "http://localhost:3000",
+          auth: { useToken: true, token: "key:secret", type: AuthType.Token },
+        });
+        await (rt as any).connect();
+
+        const options = ioOptions();
+        expect(options.transports).toEqual(["websocket", "polling"]);
+        expect(options.extraHeaders.Authorization).toBe("token key:secret");
+        expect(options.extraHeaders.Origin).toBe("http://localhost:3000");
+        expect(options.transportOptions.websocket.extraHeaders.Authorization).toBe(
+          "token key:secret",
+        );
+        rt.disconnect();
+      } finally {
+        delete (globalThis as any).imports;
+      }
+    });
+  });
+
+  describe("React Native handshake", () => {
+    function ioOptions(): Record<string, any> {
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      return calls[calls.length - 1]?.[1] ?? {};
+    }
+
+    it("routes the sid session cookie into extraHeaders on RN (cookie auth)", async () => {
+      const originalNavigator = (global as any).navigator;
+      Object.defineProperty(global, "navigator", {
+        value: { product: "ReactNative" },
+        writable: true,
+      });
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { sessionId: async () => "sid-abc" },
+      });
+      await (rt as any).connect();
+
+      const options = ioOptions();
+      // Native is websocket-first and must carry sid + Origin itself —
+      // there is no shared browser cookie jar on the socket handshake.
+      expect(options.transports).toEqual(["websocket", "polling"]);
+      expect(options.extraHeaders.Cookie).toBe("sid=sid-abc");
+      expect(options.extraHeaders.Origin).toBe("http://localhost:3000");
+      expect(options.transportOptions.websocket.extraHeaders.Cookie).toBe("sid=sid-abc");
+
+      rt.disconnect();
+      Object.defineProperty(global, "navigator", {
+        value: originalNavigator,
+        writable: true,
+      });
+    });
   });
 
   describe("connect", () => {
@@ -106,6 +212,7 @@ describe("RealtimeModule", () => {
   describe("on", () => {
     it("should register event handler and create socket listener dynamically", async () => {
       const handler = vi.fn();
+      await (realtime as any).connect();
       await realtime.on("custom_event", handler);
 
       // Should create socket listener for new event
@@ -165,6 +272,7 @@ describe("RealtimeModule", () => {
       const handler1 = vi.fn();
       const handler2 = vi.fn();
 
+      await (realtime as any).connect();
       await realtime.on("test_event", handler1);
       await realtime.on("test_event", handler2);
 
@@ -182,11 +290,26 @@ describe("RealtimeModule", () => {
       expect(handler2).toHaveBeenCalledWith(payload);
     });
 
-    it("should connect automatically when adding first handler", async () => {
+    it("does NOT connect when adding a handler — socket lifecycle is room-driven", async () => {
+      // The sync engine registers its handlers at construction; if that
+      // booted a socket, merely constructing a client for an unreachable
+      // host would start an unclosable infinite reconnect loop (the
+      // fixture/mock-story leak). Handlers wait for the first room join.
       const handler = vi.fn();
       await realtime.on("test_event", handler);
 
-      expect(mockSocket.on).toHaveBeenCalledWith("connect", expect.any(Function));
+      expect(io).not.toHaveBeenCalled();
+      expect((realtime as any).socket).toBeUndefined();
+    });
+
+    it("attaches handlers registered before the first room join once it connects", async () => {
+      const handler = vi.fn();
+      await realtime.on("pre_join_event", handler);
+      expect(io).not.toHaveBeenCalled();
+
+      await realtime.subscribeList("Task");
+
+      expect(mockSocket.on).toHaveBeenCalledWith("pre_join_event", expect.any(Function));
     });
   });
 
@@ -195,6 +318,7 @@ describe("RealtimeModule", () => {
       const handler1 = vi.fn();
       const handler2 = vi.fn();
 
+      await (realtime as any).connect();
       await realtime.on("test_event", handler1);
       await realtime.on("test_event", handler2);
 
@@ -217,6 +341,7 @@ describe("RealtimeModule", () => {
     it("should remove socket listener when last handler is removed", async () => {
       const handler = vi.fn();
 
+      await (realtime as any).connect();
       await realtime.on("test_event", handler);
       realtime.off("test_event", handler);
 
@@ -228,6 +353,7 @@ describe("RealtimeModule", () => {
       const handler1 = vi.fn();
       const handler2 = vi.fn();
 
+      await (realtime as any).connect();
       await realtime.on("test_event", handler1);
       await realtime.on("test_event", handler2);
 
@@ -249,10 +375,8 @@ describe("RealtimeModule", () => {
       (realtime as any).socketHealthy = true;
 
       await realtime.subscribeDoc("Task", "TASK-001");
-      expect(mockSocket.emit).toHaveBeenCalledWith("doc_subscribe", {
-        doctype: "Task",
-        name: "TASK-001",
-      });
+      // Positional args — frappe's socketio handler signature is (doctype, docname)
+      expect(mockSocket.emit).toHaveBeenCalledWith("doc_subscribe", "Task", "TASK-001");
     });
 
     it("should emit doc_unsubscribe event", async () => {
@@ -261,10 +385,7 @@ describe("RealtimeModule", () => {
       (realtime as any).socket = mockSocket;
 
       realtime.unsubscribeDoc("Task", "TASK-001");
-      expect(mockSocket.emit).toHaveBeenCalledWith("doc_unsubscribe", {
-        doctype: "Task",
-        name: "TASK-001",
-      });
+      expect(mockSocket.emit).toHaveBeenCalledWith("doc_unsubscribe", "Task", "TASK-001");
     });
 
     it("should connect before subscribing if not connected", async () => {
@@ -274,26 +395,22 @@ describe("RealtimeModule", () => {
   });
 
   describe("subscribeList / unsubscribeList", () => {
-    it("should emit list_subscribe event", async () => {
+    it("should emit doctype_subscribe event", async () => {
       mockSocket.connected = true;
       (realtime as any).socketHealthy = true;
 
       await realtime.subscribeList("Task", { status: "Open" });
-      expect(mockSocket.emit).toHaveBeenCalledWith("list_subscribe", {
-        doctype: "Task",
-        filters: { status: "Open" },
-      });
+      // frappe has one realtime room per doctype; filters stay client-side
+      expect(mockSocket.emit).toHaveBeenCalledWith("doctype_subscribe", "Task");
     });
 
-    it("should emit list_unsubscribe event", async () => {
+    it("should emit doctype_unsubscribe event", async () => {
       mockSocket.connected = true;
       (realtime as any).socketHealthy = true;
       (realtime as any).socket = mockSocket;
 
       realtime.unsubscribeList("Task");
-      expect(mockSocket.emit).toHaveBeenCalledWith("list_unsubscribe", {
-        doctype: "Task",
-      });
+      expect(mockSocket.emit).toHaveBeenCalledWith("doctype_unsubscribe", "Task");
     });
   });
 
@@ -347,6 +464,7 @@ describe("RealtimeModule", () => {
       const handler1 = vi.fn();
       const handler2 = vi.fn();
 
+      await (realtime as any).connect();
       await realtime.on("event1", handler1);
       await realtime.on("event2", handler2);
 
@@ -449,5 +567,331 @@ describe("RealtimeModule", () => {
       expect(event1Calls.length).toBe(0);
       expect(event2Calls.length).toBe(0);
     });
+
+    it("should re-emit doc and list subscriptions on reconnect", async () => {
+      await realtime.subscribeDoc("Task", "TASK-001");
+      await realtime.subscribeList("Task", { status: "Open" });
+
+      // Drain the initial subscribe emits from the first connect
+      await new Promise((r) => setTimeout(r, 10));
+      mockSocket.emit.mockClear();
+
+      // Simulate transport recovery: soft path keeps rooms, reconnect re-emits them
+      (realtime as any).socket = undefined;
+      (realtime as any).socketHealthy = false;
+      (realtime as any).isConnecting = false;
+      await (realtime as any).connect();
+      const connectHandler = mockSocket.on.mock.calls.find(
+        (call: any[]) => call[0] === "connect",
+      )?.[1];
+      connectHandler?.();
+
+      expect(mockSocket.emit).toHaveBeenCalledWith("doc_subscribe", "Task", "TASK-001");
+      expect(mockSocket.emit).toHaveBeenCalledWith("doctype_subscribe", "Task");
+    });
+  });
+
+  describe("updateAuth", () => {
+    it("should reconnect and preserve handlers after auth refresh", async () => {
+      const handler = vi.fn();
+      // A live room keeps the socket warranted across the rotation.
+      await realtime.subscribeList("Task");
+      await realtime.on("doc_changed", handler);
+      await new Promise((r) => setTimeout(r, 10));
+
+      mockSocket.disconnect.mockClear();
+      mockSocket.on.mockClear();
+
+      await realtime.updateAuth({
+        useToken: true,
+        token: "new-token",
+        type: "token" as any,
+      });
+
+      // Soft disconnect tears down the socket but keeps handlers
+      expect(mockSocket.disconnect).toHaveBeenCalled();
+      // New connect should re-attach the preserved handler
+      const reattached = mockSocket.on.mock.calls.some((call: any[]) => call[0] === "doc_changed");
+      expect(reattached).toBe(true);
+    });
+
+    it("does not boot a socket on auth rotation while idle (no rooms)", async () => {
+      const handler = vi.fn();
+      await realtime.on("doc_changed", handler);
+      expect((realtime as any).socket).toBeUndefined();
+
+      await realtime.updateAuth({ useToken: true, token: "rotated" });
+
+      // Still idle: the next room join will connect with the fresh auth.
+      expect((realtime as any).socket).toBeUndefined();
+      expect(io).not.toHaveBeenCalled();
+    });
+
+    it("should reconnect when only room subscriptions exist (no handlers)", async () => {
+      mockSocket.connected = true;
+      (realtime as any).socketHealthy = true;
+      (realtime as any).socket = mockSocket;
+      await realtime.subscribeDoc("Task", "TASK-009");
+
+      mockSocket.disconnect.mockClear();
+      await realtime.updateAuth({ useToken: true, token: "rotated" });
+
+      expect(mockSocket.disconnect).toHaveBeenCalled();
+      // Rooms preserved → soft reconnect opened a new socket
+      expect((realtime as any).socket).toBeDefined();
+      expect((realtime as any).docRooms.size).toBe(1);
+    });
+  });
+
+  describe("subscribe before healthy", () => {
+    it("should emit doc_subscribe after the connect event (no race no-op)", async () => {
+      const subscribePromise = realtime.subscribeDoc("Task", "TASK-RACE");
+      // Connect handler is scheduled via setTimeout(0) in the mock
+      await subscribePromise;
+
+      expect(mockSocket.emit).toHaveBeenCalledWith("doc_subscribe", "Task", "TASK-RACE");
+    });
+  });
+
+  describe("idle teardown", () => {
+    it("tears the socket down when the last room is unsubscribed", async () => {
+      await realtime.subscribeDoc("Task", "TASK-001");
+      await new Promise((r) => setTimeout(r, 10));
+      expect((realtime as any).socket).toBeDefined();
+
+      mockSocket.disconnect.mockClear();
+      realtime.unsubscribeDoc("Task", "TASK-001");
+
+      expect(mockSocket.disconnect).toHaveBeenCalled();
+      expect((realtime as any).socket).toBeUndefined();
+    });
+
+    it("keeps the socket while any room remains", async () => {
+      await realtime.subscribeDoc("Task", "TASK-001");
+      await realtime.subscribeList("Task");
+      await new Promise((r) => setTimeout(r, 10));
+
+      mockSocket.disconnect.mockClear();
+      realtime.unsubscribeDoc("Task", "TASK-001");
+
+      // The doctype room still holds the socket open.
+      expect(mockSocket.disconnect).not.toHaveBeenCalled();
+      expect((realtime as any).socket).toBeDefined();
+    });
+
+    it("notifies lifecycle handlers on idle teardown", async () => {
+      const onDisconnect = vi.fn();
+      await realtime.on("disconnect", onDisconnect);
+      await realtime.subscribeList("Task");
+      await new Promise((r) => setTimeout(r, 10));
+
+      realtime.unsubscribeList("Task");
+
+      expect(onDisconnect).toHaveBeenCalledWith({ reason: "idle-teardown" });
+    });
+
+    it("reconnects with preserved handlers on the next subscription after teardown", async () => {
+      const handler = vi.fn();
+      await realtime.on("doc_update", handler);
+      await realtime.subscribeList("Task");
+      await new Promise((r) => setTimeout(r, 10));
+      realtime.unsubscribeList("Task");
+      expect((realtime as any).socket).toBeUndefined();
+
+      mockSocket.on.mockClear();
+      await realtime.subscribeList("ToDo");
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect((realtime as any).socket).toBeDefined();
+      expect(mockSocket.on).toHaveBeenCalledWith("doc_update", expect.any(Function));
+    });
+  });
+
+  describe("connect_error", () => {
+    it("should forward connect_error to registered handlers", async () => {
+      const onError = vi.fn();
+      await (realtime as any).connect();
+      await realtime.on("connect_error", onError);
+
+      const errorHandler = mockSocket.on.mock.calls.find(
+        (call: any[]) => call[0] === "connect_error",
+      )?.[1];
+      const err = new Error("auth failed");
+      errorHandler?.(err);
+
+      expect(onError).toHaveBeenCalledWith(err);
+    });
+  });
+
+  describe("token auth handshake", () => {
+    function ioOptions(): Record<string, any> {
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      return calls[calls.length - 1]?.[1] ?? {};
+    }
+
+    it("attaches Authorization (never Origin) and handshakes over polling on web", async () => {
+      mockSocket.io.opts = {};
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { useToken: true, token: async () => "tok-1" },
+      });
+      await (rt as any).connect();
+
+      const options = ioOptions();
+      // Browsers can only attach headers to the polling (XHR) handshake —
+      // websocket upgrade rides the established session afterwards.
+      expect(options.transports).toEqual(["polling", "websocket"]);
+      expect(options.extraHeaders.Authorization).toBe("Bearer tok-1");
+      // Origin is a forbidden browser header: the browser always sends the
+      // page origin itself, and attempting to set it spams "Attempt to set a
+      // forbidden header was denied: Origin" on every polling request.
+      expect(options.extraHeaders.Origin).toBeUndefined();
+      // Headers are mirrored per-transport for node websocket handshakes
+      expect(options.transportOptions.polling.extraHeaders.Authorization).toBe("Bearer tok-1");
+      expect(options.transportOptions.websocket.extraHeaders.Authorization).toBe("Bearer tok-1");
+      rt.disconnect();
+    });
+
+    it("sets no forbidden header on web in any transport option (Origin, Cookie)", async () => {
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { useToken: true, token: "key:secret", type: "token" as any, sessionId: "sid-x" },
+      });
+      await (rt as any).connect();
+
+      const options = ioOptions();
+      expect(options.extraHeaders.Origin).toBeUndefined();
+      expect(options.extraHeaders.Cookie).toBeUndefined();
+      expect(options.transportOptions.polling.extraHeaders.Origin).toBeUndefined();
+      expect(options.transportOptions.polling.extraHeaders.Cookie).toBeUndefined();
+      expect(options.transportOptions.websocket.extraHeaders.Origin).toBeUndefined();
+      rt.disconnect();
+    });
+
+    it("derives the socket host from baseURL (LAN page → LAN socket)", async () => {
+      // The dev wrapper rewrites a loopback baseURL to the page hostname
+      // (features/backoffice/shared/env.ts); the socket must follow that
+      // hostname with the socketPort swapped in — not stay on localhost.
+      const rt = new RealtimeModule({
+        baseURL: "http://10.236.0.10:8000",
+        socketPort: 9000,
+      });
+      await (rt as any).connect();
+
+      const calls = (io as unknown as ReturnType<typeof vi.fn>).mock.calls;
+      expect(calls[calls.length - 1]?.[0]).toBe("http://10.236.0.10:9000/10.236.0.10");
+      rt.disconnect();
+    });
+
+    it("uses the token scheme when auth type is token", async () => {
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { useToken: true, token: "key:secret", type: "token" as any },
+      });
+      await (rt as any).connect();
+
+      expect(ioOptions().extraHeaders.Authorization).toBe("token key:secret");
+      rt.disconnect();
+    });
+
+    it("handshakes polling-first on web even without token auth", async () => {
+      // Cookie-session auth and reverse-proxy-injected Authorization only
+      // ride HTTP requests, and ws-upgrade-hostile dev proxies (vite
+      // middleware mode) hang raw upgrades — browsers always start on
+      // polling and let Socket.IO upgrade the established session.
+      const rt = new RealtimeModule({ baseURL: "http://localhost:3000" });
+      await (rt as any).connect();
+
+      expect(ioOptions().transports).toEqual(["polling", "websocket"]);
+      rt.disconnect();
+    });
+
+    it("keeps websocket-first transports off-web (node)", async () => {
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        platform: RealtimePlatform.Node,
+      });
+      await (rt as any).connect();
+
+      expect(ioOptions().transports).toEqual(["websocket", "polling"]);
+      rt.disconnect();
+    });
+
+    it("omits Authorization when the token getter resolves empty (signed out)", async () => {
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { useToken: true, token: async () => "" },
+      });
+      await (rt as any).connect();
+
+      expect(ioOptions().extraHeaders?.Authorization).toBeUndefined();
+      rt.disconnect();
+    });
+
+    it("re-resolves the token into manager opts on disconnect (refresh mid-session)", async () => {
+      let calls = 0;
+      const token = async () => (++calls === 1 ? "tok-1" : "tok-2");
+      mockSocket.io.opts = {};
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { useToken: true, token },
+      });
+      await (rt as any).connect();
+      expect(ioOptions().extraHeaders.Authorization).toBe("Bearer tok-1");
+
+      // Simulate a transport drop: the disconnect handler must refresh the
+      // credentials in the live manager opts before socket.io retries.
+      const disconnectHandler = mockSocket.on.mock.calls.find(
+        (call: any[]) => call[0] === "disconnect",
+      )?.[1];
+      disconnectHandler?.("transport close");
+      await (rt as any).refreshSocketAuth();
+
+      const opts = mockSocket.io.opts as any;
+      expect(opts.extraHeaders.Authorization).toBe("Bearer tok-2");
+      expect(opts.transportOptions.polling.extraHeaders.Authorization).toBe("Bearer tok-2");
+      rt.disconnect();
+    });
+
+    it("registers a reconnect_attempt refresh hook on the manager", async () => {
+      mockSocket.io.opts = {};
+      mockSocket.io.on.mockClear();
+      let calls = 0;
+      const token = async () => `tok-${++calls}`;
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { useToken: true, token },
+      });
+      await (rt as any).connect();
+
+      const reconnectHook = mockSocket.io.on.mock.calls.find(
+        (call: any[]) => call[0] === "reconnect_attempt",
+      )?.[1];
+      expect(reconnectHook).toBeDefined();
+
+      reconnectHook?.();
+      await (rt as any).refreshSocketAuth();
+
+      const opts = mockSocket.io.opts as any;
+      expect(opts.extraHeaders.Authorization).toBe("Bearer tok-2");
+      rt.disconnect();
+    });
+
+    it("preserves rooms across explicit token rotation (updateAuth)", async () => {
+      const rt = new RealtimeModule({
+        baseURL: "http://localhost:3000",
+        auth: { useToken: true, token: "old-token" },
+      });
+      await rt.subscribeDoc("Task", "TASK-100");
+      await rt.subscribeList("Task");
+      await new Promise((r) => setTimeout(r, 10));
+
+      await rt.updateAuth({ useToken: true, token: "new-token" });
+
+      expect((rt as any).docRooms.size).toBe(1);
+      expect((rt as any).listRooms.size).toBe(1);
+      expect(ioOptions().extraHeaders.Authorization).toBe("Bearer new-token");
+      rt.disconnect();
+    });
   });
 });