fix(reconnect): maxRetries(0) and configurable connectionTimeoutMs; auto-wire transport factory policy

Reworks the Layer-4 patch (#45) per @lukeocodes' review. Replaces the previous
ClientOptions.reconnect(boolean) flag and the four duplicated WebSocketClient
listeners with the underlying bug fixes in ReconnectingWebSocketListener plus
a clean policy-declaration hook on DeepgramTransportFactory.

Reverts (no edits to generated WS clients, no .fernignore freeze inflation):
  - ClientOptions.reconnect(boolean) field/getter/builder method.
  - if (transportFactory != null) builder.reconnect(false) auto-disable
    heuristic in both DeepgramClientBuilder and AsyncDeepgramClientBuilder.
  - The four resources/.../websocket/*WebSocketClient.java listener
    duplications and their .fernignore freeze entries.

Bug fixes in ReconnectingWebSocketListener (now temporarily frozen):
  - maxRetries(0) used to refuse to connect because the gate compared
    retryCount.get() >= maxRetries on the initial attempt (retryCount starts
    at 0). The initial attempt is not a retry; the gate is now > maxRetries
    so the count caps retries only. maxRetries(0) means "1 attempt, no
    retries" as the API name implies.
  - The 4000 ms connectionFuture.get(...) timeout is now configurable via a
    new connectionTimeoutMs field on ReconnectOptions (default 4000,
    validated > 0). The hardcoded literal is gone.
  - Adds applyOptionsOverride(ReconnectOptions) so a transport-factory wrapper
    can rewire policy on the listener after construction. Used by
    TransportWebSocketFactory to honour the new factory hook below without
    requiring edits to the per-resource WebSocketClient classes.

Plugin policy declaration:
  - DeepgramTransportFactory (already permanently frozen) gains a default
    ReconnectOptions reconnectOptions() method returning null. Plugins
    managing their own connection lifecycle (e.g. SageMaker) override this
    to return ReconnectOptions.builder().maxRetries(0).build() so the
    SDK's wrapper-level reconnect doesn't compound their internal retries
    into a Throttling-on-Throttling storm under burst load.
  - TransportWebSocketFactory.create() applies factory.reconnectOptions()
    to the wrapping ReconnectingWebSocketListener via the new override hook.
    Auto-wiring with no edits to generated code.

Tests:
  - New ReconnectingWebSocketListenerTest covers the maxRetries(0)
    regression, connectionTimeoutMs default + customisation + validation,
    and applyOptionsOverride no-op + retry-gate behaviour.

Net diff vs the prior PR head: 4 files changed (+94/−10) instead of 8 files
(+364/−24). Freeze list grows by 1 (the listener), shrinks by 4 (the WS
clients).

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

Author: VWang1111

.fernignore

@@ -19,16 +19,10 @@ 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
+# Bug fixes for maxRetries(0) semantics ("connect once, don't retry") and a
+# configurable connectionTimeoutMs on ReconnectOptions (was hardcoded 4000ms).
+# Pull this back out once the fixes are upstreamed into the Fern generator.
+src/main/java/com/deepgram/core/ReconnectingWebSocketListener.java
 
 # Build and project configuration
 build.gradle

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

@@ -118,11 +118,6 @@ 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,11 +117,6 @@ 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,8 +27,6 @@ public final class ClientOptions {
 
     private final Optional<LogConfig> logging;
 
-    private final boolean reconnect;
-
     private ClientOptions(
             Environment environment,
             Map<String, String> headers,
@@ -37,8 +35,7 @@ private ClientOptions(
             int timeout,
             int maxRetries,
             Optional<WebSocketFactory> webSocketFactory,
-            Optional<LogConfig> logging,
-            boolean reconnect) {
+            Optional<LogConfig> logging) {
         this.environment = environment;
         this.headers = new HashMap<>();
         this.headers.putAll(headers);
@@ -56,7 +53,6 @@ private ClientOptions(
         this.maxRetries = maxRetries;
         this.webSocketFactory = webSocketFactory;
         this.logging = logging;
-        this.reconnect = reconnect;
     }
 
     public Environment environment() {
@@ -110,18 +106,6 @@ 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();
     }
@@ -143,8 +127,6 @@ public static class Builder {
 
         private Optional<WebSocketFactory> webSocketFactory = Optional.empty();
 
-        private boolean reconnect = true;
-
         public Builder environment(Environment environment) {
             this.environment = environment;
             return this;
@@ -205,17 +187,6 @@ 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();
@@ -249,8 +220,7 @@ public ClientOptions build() {
                     this.timeout.get(),
                     this.maxRetries,
                     this.webSocketFactory,
-                    this.logging,
-                    this.reconnect);
+                    this.logging);
         }
 
         /**
@@ -265,7 +235,6 @@ 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/core/ReconnectingWebSocketListener.java

@@ -25,16 +25,21 @@
  * Provides production-ready resilience for WebSocket connections.
  */
 public abstract class ReconnectingWebSocketListener extends WebSocketListener {
-    private final long minReconnectionDelayMs;
+    // Option-derived fields are volatile (not final) so {@link #applyOptionsOverride} can rewire them
+    // after construction — used by {@code TransportWebSocketFactory} to honour
+    // {@code DeepgramTransportFactory.reconnectOptions()} without editing the generated WS clients.
+    private volatile long minReconnectionDelayMs;
 
-    private final long maxReconnectionDelayMs;
+    private volatile long maxReconnectionDelayMs;
 
-    private final double reconnectionDelayGrowFactor;
+    private volatile double reconnectionDelayGrowFactor;
 
-    private final int maxRetries;
+    private volatile int maxRetries;
 
     private final int maxEnqueuedMessages;
 
+    private volatile long connectionTimeoutMs;
+
     private final AtomicInteger retryCount = new AtomicInteger(0);
 
     private final AtomicBoolean connectLock = new AtomicBoolean(false);
@@ -66,16 +71,44 @@ public ReconnectingWebSocketListener(
         this.reconnectionDelayGrowFactor = options.reconnectionDelayGrowFactor;
         this.maxRetries = options.maxRetries;
         this.maxEnqueuedMessages = options.maxEnqueuedMessages;
+        this.connectionTimeoutMs = options.connectionTimeoutMs;
         this.connectionSupplier = connectionSupplier;
     }
 
+    /**
+     * Replaces the option-derived parameters on this listener at runtime. Used by
+     * {@code TransportWebSocketFactory} to apply {@code DeepgramTransportFactory.reconnectOptions()}
+     * without requiring edits to the generated per-resource WebSocket clients. {@code maxEnqueuedMessages}
+     * is intentionally not overridden — the message queue is sized at construction.
+     *
+     * <p>Thread-safety: option-derived fields are volatile; reads observe the latest write. The
+     * initial connect() call may have already started before the override lands, so for the very
+     * first attempt the original options apply; the override takes effect from the next attempt
+     * onwards. For the SageMaker storm-suppression case ({@code maxRetries(0)}) this is fine
+     * because the initial attempt's gate ({@code retryCount > maxRetries} with {@code retryCount=0})
+     * always passes regardless.
+     *
+     * @param options replacement options; {@code null} is a no-op.
+     */
+    public void applyOptionsOverride(ReconnectOptions options) {
+        if (options == null) {
+            return;
+        }
+        this.minReconnectionDelayMs = options.minReconnectionDelayMs;
+        this.maxReconnectionDelayMs = options.maxReconnectionDelayMs;
+        this.reconnectionDelayGrowFactor = options.reconnectionDelayGrowFactor;
+        this.maxRetries = options.maxRetries;
+        this.connectionTimeoutMs = options.connectionTimeoutMs;
+    }
+
     /**
      * Initiates a WebSocket connection with automatic reconnection enabled.
      *
      * Connection behavior:
-     * - Times out after 4000 milliseconds
+     * - Times out after {@code ReconnectOptions.connectionTimeoutMs} (default 4000ms)
      * - Thread-safe via atomic lock (returns immediately if connection in progress)
-     * - Retry count not incremented for initial connection attempt
+     * - {@code maxRetries} counts retries only — the initial attempt always proceeds.
+     *   {@code maxRetries(0)} means "connect once, don't retry" (not "refuse to connect").
      *
      * Error handling:
      * - TimeoutException: Includes retry attempt context
@@ -86,18 +119,21 @@ public void connect() {
         if (!connectLock.compareAndSet(false, true)) {
             return;
         }
-        if (retryCount.get() >= maxRetries) {
+        // retryCount is incremented inside scheduleReconnect() before re-entering connect(),
+        // so on the initial call retryCount == 0 and we always proceed. The cap applies to
+        // retries only — maxRetries(0) blocks retries but allows the initial attempt.
+        if (retryCount.get() > maxRetries) {
             connectLock.set(false);
             return;
         }
         try {
             CompletableFuture<? extends WebSocket> connectionFuture = CompletableFuture.supplyAsync(connectionSupplier);
             try {
-                webSocket = connectionFuture.get(4000, MILLISECONDS);
+                webSocket = connectionFuture.get(connectionTimeoutMs, MILLISECONDS);
             } catch (TimeoutException e) {
                 connectionFuture.cancel(true);
                 TimeoutException timeoutError =
-                        new TimeoutException("WebSocket connection timeout after " + 4000 + " milliseconds"
+                        new TimeoutException("WebSocket connection timeout after " + connectionTimeoutMs + " milliseconds"
                                 + (retryCount.get() > 0
                                         ? " (retry attempt #" + retryCount.get()
                                         : " (initial connection attempt)"));
@@ -399,12 +435,15 @@ public static final class ReconnectOptions {
 
         public final int maxEnqueuedMessages;
 
+        public final long connectionTimeoutMs;
+
         private ReconnectOptions(Builder builder) {
             this.minReconnectionDelayMs = builder.minReconnectionDelayMs;
             this.maxReconnectionDelayMs = builder.maxReconnectionDelayMs;
             this.reconnectionDelayGrowFactor = builder.reconnectionDelayGrowFactor;
             this.maxRetries = builder.maxRetries;
             this.maxEnqueuedMessages = builder.maxEnqueuedMessages;
+            this.connectionTimeoutMs = builder.connectionTimeoutMs;
         }
 
         public static Builder builder() {
@@ -422,12 +461,15 @@ public static final class Builder {
 
             private int maxEnqueuedMessages;
 
+            private long connectionTimeoutMs;
+
             public Builder() {
                 this.minReconnectionDelayMs = 1000;
                 this.maxReconnectionDelayMs = 10000;
                 this.reconnectionDelayGrowFactor = 1.3;
                 this.maxRetries = 2147483647;
                 this.maxEnqueuedMessages = 1000;
+                this.connectionTimeoutMs = 4000;
             }
 
             public Builder minReconnectionDelayMs(long minReconnectionDelayMs) {
@@ -455,6 +497,16 @@ public Builder maxEnqueuedMessages(int maxEnqueuedMessages) {
                 return this;
             }
 
+            /**
+             * Sets the per-attempt connection timeout in milliseconds. Defaults to {@code 4000}.
+             * Each call to {@link ReconnectingWebSocketListener#connect()} will wait at most
+             * this long for the underlying WebSocket factory to produce a connected socket.
+             */
+            public Builder connectionTimeoutMs(long connectionTimeoutMs) {
+                this.connectionTimeoutMs = connectionTimeoutMs;
+                return this;
+            }
+
             /**
              * Builds the ReconnectOptions with validation.
              *
@@ -463,6 +515,7 @@ public Builder maxEnqueuedMessages(int maxEnqueuedMessages) {
              * - minReconnectionDelayMs <= maxReconnectionDelayMs
              * - reconnectionDelayGrowFactor >= 1.0
              * - maxRetries and maxEnqueuedMessages are non-negative
+             * - connectionTimeoutMs is positive
              *
              * @return The validated ReconnectOptions instance
              * @throws IllegalArgumentException if configuration is invalid
@@ -487,6 +540,9 @@ public ReconnectOptions build() {
                 if (maxEnqueuedMessages < 0) {
                     throw new IllegalArgumentException("maxEnqueuedMessages must be non-negative");
                 }
+                if (connectionTimeoutMs <= 0) {
+                    throw new IllegalArgumentException("connectionTimeoutMs must be positive");
+                }
                 return new ReconnectOptions(this);
             }
         }

src/main/java/com/deepgram/core/transport/DeepgramTransportFactory.java

@@ -1,5 +1,6 @@
 package com.deepgram.core.transport;
 
+import com.deepgram.core.ReconnectingWebSocketListener;
 import java.util.Map;
 
 /**
@@ -19,7 +20,6 @@
  * <p>When a transport factory is set, all WebSocket clients (Listen, Speak, Agent) will use it
  * instead of the default OkHttp WebSocket connection.
  */
-@FunctionalInterface
 public interface DeepgramTransportFactory {
 
     /**
@@ -31,4 +31,19 @@ public interface DeepgramTransportFactory {
      * @return a connected or connecting transport instance
      */
     DeepgramTransport create(String url, Map<String, String> headers);
+
+    /**
+     * Reconnect policy the SDK should apply when wrapping connections produced by this factory.
+     * Returning {@code null} (the default) leaves the SDK's {@link ReconnectingWebSocketListener}
+     * defaults in place.
+     *
+     * <p>Plugins that own their own connection lifecycle and retry/backoff (e.g. SageMaker bidi
+     * streaming) should return {@code ReconnectOptions.builder().maxRetries(0).build()} so the
+     * SDK's wrapper-level reconnect doesn't compound their internal retries into a storm.
+     *
+     * @return reconnect options to apply, or {@code null} for SDK defaults
+     */
+    default ReconnectingWebSocketListener.ReconnectOptions reconnectOptions() {
+        return null;
+    }
 }

src/main/java/com/deepgram/core/transport/TransportWebSocketFactory.java

@@ -1,5 +1,6 @@
 package com.deepgram.core.transport;
 
+import com.deepgram.core.ReconnectingWebSocketListener;
 import com.deepgram.core.WebSocketFactory;
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -31,6 +32,13 @@ public TransportWebSocketFactory(DeepgramTransportFactory transportFactory) {
 
     @Override
     public WebSocket create(Request request, WebSocketListener listener) {
+        // Apply the plugin-declared reconnect policy to the SDK's wrapping listener. Plugins that
+        // own their own retry/backoff (SageMaker) return maxRetries(0) here so the wrapper-level
+        // reconnect doesn't compound their internal retries into a storm.
+        if (listener instanceof ReconnectingWebSocketListener) {
+            ((ReconnectingWebSocketListener) listener).applyOptionsOverride(transportFactory.reconnectOptions());
+        }
+
         String url = request.url().toString();
         // Restore wss:// scheme — OkHttp's HttpUrl normalizes to https://
         if (url.startsWith("https://")) {