chore: limit retries for guide client subscribe (#697)

Author: thomaswhyyou

.changeset/twenty-llamas-tickle.md

@@ -0,0 +1,5 @@
+---
+"@knocklabs/client": patch
+---
+
+chore: limit retries for guide client real time subscription

packages/client/src/clients/guide/client.ts

@@ -49,6 +49,9 @@ const DEFAULT_ORDER_RESOLUTION_DURATION = 50; // in milliseconds
 // trigger subscribed callbacks.
 const DEFAULT_COUNTER_INCREMENT_INTERVAL = 30 * 1000; // in milliseconds
 
+// Maximum number of retry attempts for channel subscription
+const SUBSCRIBE_RETRY_LIMIT = 3;
+
 // Return the global window object if defined, so to safely guard against SSR.
 const checkForWindow = () => {
   if (typeof window !== "undefined") {
@@ -154,6 +157,7 @@ export class KnockGuideClient {
     "guide_group.added",
     "guide_group.updated",
   ];
+  private subscribeRetryCount = 0;
 
   // Original history methods to monkey patch, or restore in cleanups.
   private pushStateFn: History["pushState"] | undefined;
@@ -306,13 +310,44 @@ export class KnockGuideClient {
     }
 
     if (["closed", "errored"].includes(newChannel.state)) {
-      newChannel.join();
+      // Reset retry count for new subscription attempt
+      this.subscribeRetryCount = 0;
+
+      newChannel
+        .join()
+        .receive("ok", () => {
+          this.knock.log("[Guide] Successfully joined channel");
+        })
+        .receive("error", (resp) => {
+          this.knock.log(
+            `[Guide] Failed to join channel: ${JSON.stringify(resp)}`,
+          );
+          this.handleChannelJoinError();
+        })
+        .receive("timeout", () => {
+          this.knock.log("[Guide] Channel join timed out");
+          this.handleChannelJoinError();
+        });
     }
 
     // Track the joined channel.
     this.socketChannel = newChannel;
   }
 
+  private handleChannelJoinError() {
+    // Prevent phx channel from retrying forever in case of either network or
+    // other errors (e.g. auth error, invalid channel etc)
+    if (this.subscribeRetryCount >= SUBSCRIBE_RETRY_LIMIT) {
+      this.knock.log(
+        `[Guide] Channel join max retry limit reached: ${this.subscribeRetryCount}`,
+      );
+      this.unsubscribe();
+      return;
+    }
+
+    this.subscribeRetryCount++;
+  }
+
   unsubscribe() {
     if (!this.socketChannel) return;
     this.knock.log("[Guide] Unsubscribing from real time updates");

packages/client/test/clients/guide/guide.test.ts

@@ -267,7 +267,11 @@ describe("KnockGuideClient", () => {
     test("subscribes to socket events when socket is available", () => {
       const mockChannel = {
         join: vi.fn().mockReturnValue({
-          receive: vi.fn().mockReturnValue({ receive: vi.fn() }),
+          receive: vi.fn().mockReturnValue({
+            receive: vi.fn().mockReturnValue({
+              receive: vi.fn()
+            })
+          }),
         }),
         on: vi.fn(),
         off: vi.fn(),
@@ -303,6 +307,121 @@ describe("KnockGuideClient", () => {
       expect(mockChannel.join).toHaveBeenCalled();
     });
 
+    test("handles successful channel join", () => {
+      let okCallback: () => void;
+      const mockChannel = {
+        join: vi.fn().mockReturnValue({
+          receive: vi.fn((event, callback) => {
+            if (event === "ok") {
+              okCallback = callback;
+            }
+            return {
+              receive: vi.fn().mockReturnValue({ receive: vi.fn() })
+            };
+          }),
+        }),
+        on: vi.fn(),
+        off: vi.fn(),
+        leave: vi.fn(),
+        state: "closed",
+      };
+
+      const mockSocket = {
+        channel: vi.fn().mockReturnValue(mockChannel),
+        isConnected: vi.fn().mockReturnValue(true),
+        connect: vi.fn(),
+      };
+
+      mockApiClient.socket = mockSocket as unknown as Socket;
+      vi.mocked(mockKnock.client).mockReturnValue(mockApiClient as ApiClient);
+
+      const client = new KnockGuideClient(
+        mockKnock,
+        channelId,
+        defaultTargetParams,
+      );
+      client.subscribe();
+
+      // Trigger the ok callback
+      okCallback!();
+
+      expect(mockKnock.log).toHaveBeenCalledWith("[Guide] Successfully joined channel");
+    });
+
+    test("unsubscribes after reaching max retry limit", () => {
+      let errorCallback: (resp: { reason: string }) => void;
+      const mockChannel = {
+        join: vi.fn().mockReturnValue({
+          receive: vi.fn((event, callback) => {
+            if (event === "error") {
+              errorCallback = callback;
+            }
+            return {
+              receive: vi.fn((event, callback) => {
+                if (event === "error") {
+                  errorCallback = callback;
+                }
+                return {
+                  receive: vi.fn((event, callback) => {
+                    if (event === "error") {
+                      errorCallback = callback;
+                    }
+                    return { receive: vi.fn() };
+                  })
+                };
+              })
+            };
+          }),
+        }),
+        on: vi.fn(),
+        off: vi.fn(),
+        leave: vi.fn(),
+        state: "closed",
+      };
+
+      const mockSocket = {
+        channel: vi.fn().mockReturnValue(mockChannel),
+        isConnected: vi.fn().mockReturnValue(true),
+        connect: vi.fn(),
+      };
+
+      mockApiClient.socket = mockSocket as unknown as Socket;
+      vi.mocked(mockKnock.client).mockReturnValue(mockApiClient as ApiClient);
+
+      const client = new KnockGuideClient(
+        mockKnock,
+        channelId,
+        defaultTargetParams,
+      );
+
+      const unsubscribeSpy = vi.spyOn(client, "unsubscribe");
+
+      client.subscribe();
+
+      // Initial fail. The retry count starts at 0 and is incremented on each
+      // error to represent the next retry.
+      errorCallback!({ reason: "auth_error" });
+
+      // First retry fail
+      expect(client["subscribeRetryCount"]).toBe(1);
+      errorCallback!({ reason: "auth_error" });
+
+      // Second retry fail
+      expect(client["subscribeRetryCount"]).toBe(2);
+      errorCallback!({ reason: "auth_error" });
+
+      // Third retry fail
+      expect(client["subscribeRetryCount"]).toBe(3);
+      errorCallback!({ reason: "auth_error" });
+
+      // Check that the max retry limit message was logged
+      expect(mockKnock.log).toHaveBeenCalledWith(
+        "[Guide] Channel join max retry limit reached: 3"
+      );
+
+      expect(unsubscribeSpy).toHaveBeenCalled();
+    });
+
     test("unsubscribes from socket events", () => {
       const mockChannel = {
         join: vi.fn(),