feat: opt out of ReconnectingWebSocketListener wrapper, auto-disable for custom transports

Adds `ClientOptions.Builder.reconnect(boolean)` (default `true`). When
`false`, the per-resource WebSocket clients (`listen/v1`, `listen/v2`,
`agent/v1`, `speak/v1`) connect once via a plain `okhttp3.WebSocketListener`
and propagate failures directly, bypassing `ReconnectingWebSocketListener`
and its hardcoded `connectionFuture.get(4000, MILLISECONDS)` ceiling.

Auto-disable for custom transports: when
`DeepgramClientBuilder.transportFactory(...)` (or its async counterpart)
is set, `setAdditional()` now also calls `builder.reconnect(false)`.
Custom transports like `SageMakerTransportFactory` already manage their
own connection lifecycle and retry semantics; wrapping them in another
retry layer creates double-retry storms under burst load.

The four per-resource WebSocket client files are added to the
"temporarily frozen" section of `.fernignore` so the patch survives the
next Fern regen. Unfreeze once the change has been pushed upstream into
the Fern generator template.

Backwards compatibility:

- Existing callers that do NOT use `transportFactory(...)` see zero
  behavior change. `reconnect()` defaults to `true`, the
  `ReconnectingWebSocketListener` wrapper is unchanged for the OkHttp
  WebSocket path (Deepgram cloud, self-hosted Deepgram via raw WS),
  and the lower-level `ClientOptions.Builder.webSocketFactory(...)`
  seam is also unaffected.
- Existing SageMaker callers (the only known users of
  `transportFactory(...)`) get the auto-disable. Empirically this
  eliminates the retry-storm pattern observed at 400 concurrent
  streams on a 10x ml.g6.2xlarge endpoint:

      ThrottlingException line-count    68,909  ->     240  (-99.7%)
      ModelStreamError line-count       30,442  ->   1,128  (-96.3%)
      Streams hitting Attempt Count: 4  29,030  ->      96  (-99.7%)
      4-second `connection timeout`         13  ->       0
      Total error log lines           1,322,666 -> 33,972   (-97.4%)

  Same wall time (313 vs 312 s), same transcript count, dramatically
  cleaner error log.

Edge case worth calling out:

- A SageMaker caller who has been tuning retry behavior via
  `wsClient.reconnectOptions(customOpts)` will find those options
  silently ignored after this change (`reconnect=false` skips the
  listener entirely). Their tuning was almost certainly a workaround
  for the very storm we are now eliminating, so the right migration
  is to delete the `reconnectOptions(...)` call. Customers who
  genuinely want both a custom transport and SDK-side reconnect can
  re-enable explicitly with `.reconnect(true)` after
  `.transportFactory(...)`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: VWang1111

.fernignore

@@ -19,6 +19,17 @@ src/main/java/com/deepgram/core/ClientOptions.java
 # Transport abstraction (pluggable transport for SageMaker, etc.)
 src/main/java/com/deepgram/core/transport/
 
+# Temporarily frozen — Layer 4 patch: ClientOptions.reconnect(false) opt-out path
+# in the per-resource WebSocket clients. When `clientOptions.reconnect()` is false
+# (auto-set by `DeepgramClientBuilder.transportFactory(...)`), connect() bypasses
+# `ReconnectingWebSocketListener` and uses a plain okhttp3.WebSocketListener.
+# Pull these out of the freeze once the change has been pushed upstream into the
+# Fern generator template.
+src/main/java/com/deepgram/resources/listen/v1/websocket/V1WebSocketClient.java
+src/main/java/com/deepgram/resources/listen/v2/websocket/V2WebSocketClient.java
+src/main/java/com/deepgram/resources/agent/v1/websocket/V1WebSocketClient.java
+src/main/java/com/deepgram/resources/speak/v1/websocket/V1WebSocketClient.java
+
 # Build and project configuration
 build.gradle
 settings.gradle

src/main/java/com/deepgram/AsyncDeepgramClientBuilder.java

@@ -118,6 +118,11 @@ protected void setAdditional(ClientOptions.Builder builder) {
         builder.addHeader("x-deepgram-session-id", sid);
         if (transportFactory != null) {
             builder.webSocketFactory(new TransportWebSocketFactory(transportFactory));
+            // Custom transports manage their own connection lifecycle and retry semantics.
+            // Wrapping them in ReconnectingWebSocketListener creates double-retry layering
+            // that compounds failures under burst load. Auto-disable here; users can
+            // re-enable explicitly via ClientOptions if they have a reason to.
+            builder.reconnect(false);
         }
     }
 

src/main/java/com/deepgram/DeepgramClientBuilder.java

@@ -117,6 +117,11 @@ protected void setAdditional(ClientOptions.Builder builder) {
         builder.addHeader("x-deepgram-session-id", sid);
         if (transportFactory != null) {
             builder.webSocketFactory(new TransportWebSocketFactory(transportFactory));
+            // Custom transports manage their own connection lifecycle and retry semantics.
+            // Wrapping them in ReconnectingWebSocketListener creates double-retry layering
+            // that compounds failures under burst load. Auto-disable here; users can
+            // re-enable explicitly via ClientOptions if they have a reason to.
+            builder.reconnect(false);
         }
     }
 

src/main/java/com/deepgram/core/ClientOptions.java

@@ -27,6 +27,8 @@ public final class ClientOptions {
 
     private final Optional<LogConfig> logging;
 
+    private final boolean reconnect;
+
     private ClientOptions(
             Environment environment,
             Map<String, String> headers,
@@ -35,7 +37,8 @@ private ClientOptions(
             int timeout,
             int maxRetries,
             Optional<WebSocketFactory> webSocketFactory,
-            Optional<LogConfig> logging) {
+            Optional<LogConfig> logging,
+            boolean reconnect) {
         this.environment = environment;
         this.headers = new HashMap<>();
         this.headers.putAll(headers);
@@ -53,6 +56,7 @@ private ClientOptions(
         this.maxRetries = maxRetries;
         this.webSocketFactory = webSocketFactory;
         this.logging = logging;
+        this.reconnect = reconnect;
     }
 
     public Environment environment() {
@@ -106,6 +110,18 @@ public Optional<LogConfig> logging() {
         return this.logging;
     }
 
+    /**
+     * Whether the per-resource WebSocket clients should wrap the underlying WebSocket in a
+     * {@link ReconnectingWebSocketListener} that retries on failure. Defaults to {@code true}.
+     * When {@code false}, the WebSocket clients connect once and propagate failures directly
+     * without retry. Use {@code false} when the underlying transport (e.g. SageMaker bidi
+     * streaming) already manages its own connection lifecycle and retry semantics, in which
+     * case wrapping in another retry layer causes double-retry storms under burst load.
+     */
+    public boolean reconnect() {
+        return this.reconnect;
+    }
+
     public static Builder builder() {
         return new Builder();
     }
@@ -127,6 +143,8 @@ public static class Builder {
 
         private Optional<WebSocketFactory> webSocketFactory = Optional.empty();
 
+        private boolean reconnect = true;
+
         public Builder environment(Environment environment) {
             this.environment = environment;
             return this;
@@ -187,6 +205,17 @@ public Builder logging(LogConfig logging) {
             return this;
         }
 
+        /**
+         * Enable or disable the auto-reconnecting WebSocket wrapper. Defaults to {@code true}.
+         * Set to {@code false} when using a custom transport (e.g. SageMaker) that already
+         * manages its own connection lifecycle — wrapping such transports in the reconnect
+         * listener causes double-retry storms under burst load.
+         */
+        public Builder reconnect(boolean reconnect) {
+            this.reconnect = reconnect;
+            return this;
+        }
+
         public ClientOptions build() {
             OkHttpClient.Builder httpClientBuilder =
                     this.httpClient != null ? this.httpClient.newBuilder() : new OkHttpClient.Builder();
@@ -220,7 +249,8 @@ public ClientOptions build() {
                     this.timeout.get(),
                     this.maxRetries,
                     this.webSocketFactory,
-                    this.logging);
+                    this.logging,
+                    this.reconnect);
         }
 
         /**
@@ -235,6 +265,7 @@ public static Builder from(ClientOptions clientOptions) {
             builder.headerSuppliers.putAll(clientOptions.headerSuppliers);
             builder.maxRetries = clientOptions.maxRetries();
             builder.logging = clientOptions.logging();
+            builder.reconnect = clientOptions.reconnect();
             return builder;
         }
     }

src/main/java/com/deepgram/resources/agent/v1/websocket/V1WebSocketClient.java

@@ -42,6 +42,7 @@
 import okhttp3.Request;
 import okhttp3.Response;
 import okhttp3.WebSocket;
+import okhttp3.WebSocketListener;
 import okio.ByteString;
 
 /**
@@ -73,6 +74,12 @@ public class V1WebSocketClient implements AutoCloseable {
 
     private ReconnectingWebSocketListener reconnectingListener;
 
+    // Direct (non-reconnecting) WebSocket — used when clientOptions.reconnect() is false
+    // (e.g. when a custom transportFactory is configured). In that mode, the underlying
+    // transport owns its own connection lifecycle, so we connect once and propagate
+    // failures directly without wrapping in ReconnectingWebSocketListener.
+    private volatile WebSocket directWebSocket;
+
     private volatile Consumer<AgentV1ReceiveFunctionCallResponse> onFunctionCallResponseHandler;
 
     private volatile Consumer<AgentV1PromptUpdated> promptUpdatedHandler;
@@ -144,6 +151,58 @@ public CompletableFuture<Void> connect() {
         clientOptions.headers(null).forEach(requestBuilder::addHeader);
         final Request request = requestBuilder.build();
         this.readyState = WebSocketReadyState.CONNECTING;
+
+        if (!clientOptions.reconnect()) {
+            // Direct mode — no ReconnectingWebSocketListener wrapper. Used when a custom
+            // transportFactory manages its own retry/lifecycle (e.g. SageMaker bidi streaming).
+            WebSocketListener directListener = new WebSocketListener() {
+                @Override
+                public void onOpen(WebSocket webSocket, Response response) {
+                    directWebSocket = webSocket;
+                    readyState = WebSocketReadyState.OPEN;
+                    if (onConnectedHandler != null) {
+                        onConnectedHandler.run();
+                    }
+                    connectionFuture.complete(null);
+                }
+
+                @Override
+                public void onMessage(WebSocket webSocket, String text) {
+                    handleIncomingMessage(text);
+                }
+
+                @Override
+                public void onMessage(WebSocket webSocket, ByteString bytes) {
+                    if (agentV1AudioHandler != null) {
+                        agentV1AudioHandler.accept(bytes);
+                    }
+                }
+
+                @Override
+                public void onFailure(WebSocket webSocket, Throwable t, Response response) {
+                    readyState = WebSocketReadyState.CLOSED;
+                    if (onErrorHandler != null) {
+                        onErrorHandler.accept(new RuntimeException(t));
+                    }
+                    connectionFuture.completeExceptionally(t);
+                }
+
+                @Override
+                public void onClosed(WebSocket webSocket, int code, String reason) {
+                    readyState = WebSocketReadyState.CLOSED;
+                    if (onDisconnectedHandler != null) {
+                        onDisconnectedHandler.accept(new DisconnectReason(code, reason));
+                    }
+                }
+            };
+            if (clientOptions.webSocketFactory().isPresent()) {
+                this.directWebSocket = clientOptions.webSocketFactory().get().create(request, directListener);
+            } else {
+                this.directWebSocket = okHttpClient.newWebSocket(request, directListener);
+            }
+            return connectionFuture;
+        }
+
         ReconnectingWebSocketListener.ReconnectOptions reconnectOpts = this.reconnectOptions != null
                 ? this.reconnectOptions
                 : ReconnectingWebSocketListener.ReconnectOptions.builder().build();
@@ -201,7 +260,12 @@ protected void onWebSocketClosed(WebSocket webSocket, int code, String reason) {
      * Disconnects the WebSocket connection and releases resources.
      */
     public void disconnect() {
-        reconnectingListener.disconnect();
+        if (reconnectingListener != null) {
+            reconnectingListener.disconnect();
+        } else if (directWebSocket != null) {
+            directWebSocket.close(1000, "Client disconnecting");
+            directWebSocket = null;
+        }
         if (timeoutExecutor != null) {
             timeoutExecutor.shutdownNow();
             timeoutExecutor = null;
@@ -300,8 +364,12 @@ public CompletableFuture<Void> sendMedia(ByteString message) {
         CompletableFuture<Void> future = new CompletableFuture<>();
         try {
             assertSocketIsOpen();
-            // Use reconnecting listener's sendBinary method which handles queuing
-            reconnectingListener.sendBinary(message);
+            if (reconnectingListener != null) {
+                // Use reconnecting listener's sendBinary method which handles queuing
+                reconnectingListener.sendBinary(message);
+            } else {
+                directWebSocket.send(message);
+            }
             future.complete(null);
         } catch (Exception e) {
             future.completeExceptionally(new RuntimeException("Failed to send binary data", e));
@@ -501,7 +569,10 @@ public void close() {
      * @throws IllegalStateException if the socket is not connected or not open
      */
     private void assertSocketIsOpen() {
-        if (reconnectingListener.getWebSocket() == null) {
+        WebSocket activeSocket = (reconnectingListener != null)
+                ? reconnectingListener.getWebSocket()
+                : directWebSocket;
+        if (activeSocket == null) {
             throw new IllegalStateException("WebSocket is not connected. Call connect() first.");
         }
         if (readyState != WebSocketReadyState.OPEN) {
@@ -514,8 +585,12 @@ private CompletableFuture<Void> sendMessage(Object body) {
         try {
             assertSocketIsOpen();
             String json = objectMapper.writeValueAsString(body);
-            // Use reconnecting listener's send method which handles queuing
-            reconnectingListener.send(json);
+            if (reconnectingListener != null) {
+                // Use reconnecting listener's send method which handles queuing
+                reconnectingListener.send(json);
+            } else {
+                directWebSocket.send(json);
+            }
             future.complete(null);
         } catch (IllegalStateException e) {
             future.completeExceptionally(e);