From f683380392d80882029b32971dc37a5159bbb257 Mon Sep 17 00:00:00 2001
From: smoghe-bw <smoghe-bw>
Date: Wed, 9 Sep 2026 14:23:01 -0400
Subject: [PATCH 1/2] fix(signaling): only retry on close code 1001, tear down
 on everything else

rpc-websockets' unlimited auto-reconnect only special-cases close code
1000 - every other code, including ones this SDK doesn't recognize yet,
was silently retried forever. Flip the default: 1001 (Going Away) is
the only code the gateway sends to mean "come back on this session";
everything else - 1000 (endpoint gone), 4409 (superseded by a newer
connection from this same device, pv-gateway PR pv-gateway#123), 1011
(internal error, where the right recovery is minting a new endpoint,
not retrying this connection), and any future/unknown code - now
disables auto-reconnect and tears the connection down.

The gateway-initiated codes (4409, 1011) race the "close" event: the
underlying client schedules its reconnect timer synchronously inside
the raw WebSocket's own close listener, before it defers emitting the
"close" event this file listens on. setAutoReconnect(false) alone is
too late for those; the already-queued reconnect_timer_id has to be
cleared directly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/v1/signaling.test.ts | 35 +++++++++++++++++++++++++++++++++--
 src/v1/signaling.ts      | 27 ++++++++++++++++++++++++++-
 2 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/src/v1/signaling.test.ts b/src/v1/signaling.test.ts
index a993a41..f9a317f 100644
--- a/src/v1/signaling.test.ts
+++ b/src/v1/signaling.test.ts
@@ -184,7 +184,7 @@ describe("Signaling websocket event handlers", () => {
     expect(ws.setAutoReconnect).not.toHaveBeenCalled();
   });
 
-  test("should clear ping interval and set isReady false on close", async () => {
+  test("should clear ping interval on close", async () => {
     // Trigger open first to set up pingInterval
     const openCallback = getWsCallback("open");
     await openCallback();
@@ -192,7 +192,7 @@ describe("Signaling websocket event handlers", () => {
     const closeCallback = getWsCallback("close");
     expect(closeCallback).toBeDefined();
 
-    closeCallback(4000);
+    closeCallback(1001);
 
     expect((signaling as any).isReady).toBe(false);
   });
@@ -207,6 +207,37 @@ describe("Signaling websocket event handlers", () => {
     expect((signaling as any).ws).toBeNull();
     expect((signaling as any).isReady).toBe(false);
   });
+
+  // 1001 is the only close code the gateway sends to say "come back on this
+  // same session" (drain eviction, lost media server, etc). Everything else
+  // must tear the connection down rather than let rpc-websockets' unlimited
+  // auto-reconnect keep hammering a connection that isn't coming back.
+  test("should not disconnect on the retryable close code 1001", async () => {
+    const closeCallback = getWsCallback("close");
+    expect(closeCallback).toBeDefined();
+
+    closeCallback(1001);
+
+    expect((signaling as any).ws).not.toBeNull();
+    const ws = (signaling as any).ws;
+    expect(ws.setAutoReconnect).not.toHaveBeenCalled();
+  });
+
+  test.each([
+    [4409, "superseded by a newer connection from the same device"],
+    [1011, "gateway internal error"],
+    [4000, "an unrecognized close code"],
+  ])("should disable auto-reconnect and disconnect on close code %d (%s)", async (code) => {
+    const ws = (signaling as any).ws;
+    const closeCallback = getWsCallback("close");
+    expect(closeCallback).toBeDefined();
+
+    closeCallback(code);
+
+    expect(ws.setAutoReconnect).toHaveBeenCalledWith(false);
+    expect((signaling as any).ws).toBeNull();
+    expect((signaling as any).isReady).toBe(false);
+  });
 });
 
 describe("Signaling disconnect", () => {
diff --git a/src/v1/signaling.ts b/src/v1/signaling.ts
index cd369bf..a069517 100644
--- a/src/v1/signaling.ts
+++ b/src/v1/signaling.ts
@@ -32,6 +32,21 @@ const FATAL_HANDSHAKE_ERRORS: Record<string, { status: number; logMessage: strin
   },
 };
 
+/**
+ * The only close code that should trigger a reconnect on this same client
+ * instance: 1001 (Going Away) is the gateway explicitly telling this session
+ * to come back (drain eviction, lost media server, etc.).
+ *
+ * Every other code tears the connection down for good, including codes we
+ * don't otherwise recognize: 1000 means the endpoint is gone; 4409 means a
+ * newer connection from this same device already took over, so reconnecting
+ * here would just fight the one that won; 1011 (internal error) means retrying
+ * this same connection isn't the right recovery — the app should mint a new
+ * endpoint and start over, not have this client silently keep hammering the
+ * same one.
+ */
+const RETRY_CLOSE_CODES = new Set([1001]);
+
 class Signaling extends EventEmitter {
   private defaultWebsocketUrl: string = "wss://gateway.pv.prod.global.aws.bandwidth.com/prod/gateway-service/api/v1/endpoints";
   private ws: JsonRpcClient | null = null;
@@ -143,7 +158,17 @@ class Signaling extends EventEmitter {
         if (this.pingInterval) {
           clearInterval(this.pingInterval);
         }
-        if (code == 1000) {
+        if (!RETRY_CLOSE_CODES.has(code)) {
+          // rpc-websockets decides whether to schedule a reconnect synchronously,
+          // inside the underlying socket's own "close" listener — before it even
+          // fires the "close" event we're handling here (that emit is deferred via
+          // setTimeout). For code 1000 the library's own check already skips
+          // scheduling one, but for any other non-retryable code the reconnect
+          // timer is already queued by the time we get here, so setAutoReconnect(false)
+          // alone is too late. Clearing the client's own timer handle is the only
+          // way to stop it from firing.
+          clearTimeout((ws as any).reconnect_timer_id);
+          ws.setAutoReconnect(false);
           // We were asked to go away and not come back. We should disconnect without calling leave.
           this._disconnect(false);
         }

From d51948b3adab7e8795b713666f400dd0588c5a1c Mon Sep 17 00:00:00 2001
From: smoghe-bw <smoghe-bw>
Date: Wed, 9 Sep 2026 14:25:38 -0400
Subject: [PATCH 2/2] fix(signaling): trim comments to public SDK-facing
 language
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop pv-gateway internal implementation detail (drain eviction, media
server loss, etc.) from comments — this is a public SDK, comments
should describe SDK behavior, not the internals of one server that
happens to implement the protocol.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/v1/signaling.test.ts | 10 +---------
 src/v1/signaling.ts      | 26 ++++++--------------------
 2 files changed, 7 insertions(+), 29 deletions(-)

diff --git a/src/v1/signaling.test.ts b/src/v1/signaling.test.ts
index f9a317f..29de410 100644
--- a/src/v1/signaling.test.ts
+++ b/src/v1/signaling.test.ts
@@ -208,10 +208,6 @@ describe("Signaling websocket event handlers", () => {
     expect((signaling as any).isReady).toBe(false);
   });
 
-  // 1001 is the only close code the gateway sends to say "come back on this
-  // same session" (drain eviction, lost media server, etc). Everything else
-  // must tear the connection down rather than let rpc-websockets' unlimited
-  // auto-reconnect keep hammering a connection that isn't coming back.
   test("should not disconnect on the retryable close code 1001", async () => {
     const closeCallback = getWsCallback("close");
     expect(closeCallback).toBeDefined();
@@ -223,11 +219,7 @@ describe("Signaling websocket event handlers", () => {
     expect(ws.setAutoReconnect).not.toHaveBeenCalled();
   });
 
-  test.each([
-    [4409, "superseded by a newer connection from the same device"],
-    [1011, "gateway internal error"],
-    [4000, "an unrecognized close code"],
-  ])("should disable auto-reconnect and disconnect on close code %d (%s)", async (code) => {
+  test.each([4409, 1011, 4000])("should disable auto-reconnect and disconnect on close code %d", async (code) => {
     const ws = (signaling as any).ws;
     const closeCallback = getWsCallback("close");
     expect(closeCallback).toBeDefined();
diff --git a/src/v1/signaling.ts b/src/v1/signaling.ts
index a069517..bb5d386 100644
--- a/src/v1/signaling.ts
+++ b/src/v1/signaling.ts
@@ -33,17 +33,9 @@ const FATAL_HANDSHAKE_ERRORS: Record<string, { status: number; logMessage: strin
 };
 
 /**
- * The only close code that should trigger a reconnect on this same client
- * instance: 1001 (Going Away) is the gateway explicitly telling this session
- * to come back (drain eviction, lost media server, etc.).
- *
- * Every other code tears the connection down for good, including codes we
- * don't otherwise recognize: 1000 means the endpoint is gone; 4409 means a
- * newer connection from this same device already took over, so reconnecting
- * here would just fight the one that won; 1011 (internal error) means retrying
- * this same connection isn't the right recovery — the app should mint a new
- * endpoint and start over, not have this client silently keep hammering the
- * same one.
+ * Close codes that should trigger a reconnect on this same client instance.
+ * Every other code, including ones this SDK doesn't recognize, tears the
+ * connection down instead of retrying it.
  */
 const RETRY_CLOSE_CODES = new Set([1001]);
 
@@ -159,17 +151,11 @@ class Signaling extends EventEmitter {
           clearInterval(this.pingInterval);
         }
         if (!RETRY_CLOSE_CODES.has(code)) {
-          // rpc-websockets decides whether to schedule a reconnect synchronously,
-          // inside the underlying socket's own "close" listener — before it even
-          // fires the "close" event we're handling here (that emit is deferred via
-          // setTimeout). For code 1000 the library's own check already skips
-          // scheduling one, but for any other non-retryable code the reconnect
-          // timer is already queued by the time we get here, so setAutoReconnect(false)
-          // alone is too late. Clearing the client's own timer handle is the only
-          // way to stop it from firing.
+          // rpc-websockets schedules its own reconnect synchronously, before it
+          // fires the "close" event we're handling here, so setAutoReconnect(false)
+          // alone is too late — the pending timer has to be cleared directly.
           clearTimeout((ws as any).reconnect_timer_id);
           ws.setAutoReconnect(false);
-          // We were asked to go away and not come back. We should disconnect without calling leave.
           this._disconnect(false);
         }
         this.isReady = false;