VAPI-3808 VAPI-3804 fix(signaling): stop auto-reconnecting when the gateway returns 409

[smoghe-bw]

Problem

Signaling.connect builds its client with unlimited auto-reconnect:

const ws = new JsonRpcClient(websocketUrl, {
  autoconnect: true,
  reconnect: true,
  max_reconnects: 0, // Unlimited
});

but the error handler only ever treated one status as terminal:

if (error.message === "Unexpected server response: 403") {

So a 409 — the gateway rejecting the connection because another device already holds that endpoint — was treated as retryable. The SDK reconnected several times a second against a gateway that was correctly telling it the connection could not be established.

Gateway logs for a single endpoint show 21 rejections in 90 seconds across three hosts. And it was self-sustaining: each retry that won a socket before being rejected left an inert connection behind — no open handler, so it never called setMediaPreferences, never created peers, never answered the heartbeat — which held the endpoint and caused the next round of rejections. That's the same failure mode already described in the _disconnect comment added by #13; this is the other path into it.

Change

• Collect terminal handshake failures into a single FATAL_HANDSHAKE_ERRORS table keyed by the ws error message, covering 403 and now 409.
• On a match: disable auto-reconnect, close, reject with a clear error, and disconnect without calling leave.
• Add the missing return, so a fatal error no longer falls through into the generic Websocket error: ... log below it (403 was double-logging).

Retry policy is deliberately left to the application. A 409 clears when the other device disconnects, and the app knows better than the SDK whether and when re-attempting is appropriate.

Note this only works under Node — browsers don't expose the HTTP status of a failed websocket upgrade to the error handler. Same pre-existing limitation as the 403 branch; called out in a comment.

Test plan

• npm test — 72 passed
• npx tsc --noEmit clean, prettier --check clean
• New test: a 409 error closes with 409 and calls setAutoReconnect(false), mirroring the existing 403 test
• Existing generic-error test kept (renamed to "non-fatal"), still asserting setAutoReconnect is untouched for recoverable errors

🤖 Generated with Claude Code

[bwappsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[smoghe-bw]

Investigated a production incident (gateway logs 08:06–08:08 today) showing repeated new websocket connection → websocket never called setMediaPreferences; disconnecting idle connection (30s later) mixed with endpoint already has an active connection; rejecting connection bursts, all against the same endpoint.

Root cause: Signaling.connect() overwrote this.ws with a new JsonRpcClient without ever closing a pre-existing one. Since each client is constructed with reconnect: true, max_reconnects: 0 (unlimited), if connect() is ever called a second time on the same instance (e.g. app-level retry after an error/close — there's no built-in reconnect handling, see the // TODO: handle reconnections note), the old client is orphaned but keeps auto-reconnecting forever against the same endpointToken.

The orphan's open handler calls setMediaPreferences(), which internally reads this.ws — but by then this.ws points at the new, active client, so the RPC actually goes out over the wrong socket. The orphan's own connection never sends anything, sits idle, and gets reaped by the gateway's 30s idle watchdog — exactly matching the log pattern. Its reconnect loop then immediately retries, which is also the source of the repeated endpoint already has an active connection rejections.

Fix: connect() now calls this._disconnect(false) on any existing this.ws before constructing the new client, so there's never more than one live (and reconnecting) client per Signaling instance.