fix(reconnect): listener bug fixes + transport factory policy hook

[VWang1111]

Summary

• Add ClientOptions.Builder.reconnect(boolean) (default true). When false, the per-resource WebSocket clients 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() also calls builder.reconnect(false). Custom transports like SageMakerTransportFactory already manage their own connection lifecycle; wrapping them in another retry layer creates double-retry storms under burst load.
• Patch applied to all four per-resource WebSocket clients: listen/v1, listen/v2, agent/v1, speak/v1. Same structural change in each: connect() branches on clientOptions.reconnect(); disconnect(), sendMedia(), sendMessage(), assertSocketIsOpen() use directWebSocket when the listener is null.
• The four 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.

Why

Validated against a 400-concurrent-stream burst test on a 10× ml.g6.2xlarge endpoint (Deepgram on SageMaker, replicating a customer-reported failure):

Metric	Before	After (this PR + transport-side timeouts)	Δ
ThrottlingException line-count	68,909	240	−99.7 %
ModelStreamError line-count	30,442	1,128	−96.3 %
Streams hitting AWS SDK Attempt Count: 4	29,030	96	−99.7 %
4-second connection timeout after 4000	13	0	eliminated
Total error log lines	1,322,666	33,972	−97.4 %
Wall time	313.57 s	312.61 s	unchanged
Transcript count	41,337	40,467	unchanged

Same work done, ~97 % less error noise. Pairs with deepgram/deepgram-java-sdk-transport-sagemaker#14 (Layer 1 transport-side timeouts), but each provides independent value.

Backwards compatibility

Existing callers that do NOT use transportFactory(...) see zero behavior change. The new reconnect() field defaults to true, the ReconnectingWebSocketListener-wrapped code path is unchanged for the OkHttp WebSocket transport (Deepgram cloud, self-hosted Deepgram via raw WS), and the lower-level ClientOptions.Builder.webSocketFactory(...) seam is also unaffected (only the explicit DeepgramClientBuilder.transportFactory(...) API triggers the auto-disable).

Customer shape	transportFactory != null?	reconnect()	Wraps in ReconnectingWebSocketListener?	Behavior change
Deepgram Cloud (wss://api.deepgram.com)	no	true	yes (unchanged)	none
Self-hosted Deepgram (raw WS)	no	true	yes (unchanged)	none
Custom WebSocketFactory via ClientOptions (lower-level seam)	no	true	yes (unchanged)	none
transportFactory(SageMakerTransportFactory)	yes	false (auto-set)	no (direct path)	yes — desired
transportFactory(<future custom transport>)	yes	false (auto-set)	no (direct path)	yes; opt back in with .reconnect(true)

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(...):

DeepgramClient.builder()
    .transportFactory(sagemakerFactory)
    .reconnect(true)              // explicit override; not recommended for SageMaker
    .build();

This is a runtime-quality change, not an API break — no compile errors for any existing customer. Recommend mentioning in CHANGELOG and migration notes for the next minor release.

Test plan

• ./gradlew build — passes (spotless + compile + tests).
• ./gradlew test — all existing tests pass.
• End-to-end validation with patched JAR linked into a customer load-test harness against a real SageMaker endpoint (numbers above).
• CI passes.
• Push template change upstream into the Fern generator and unfreeze the four per-resource WebSocket client files in .fernignore.

🤖 Generated with Claude Code

[lukeocodes]

thanks for chasing this down, the diagnosis is right. but this shouldn't land in core. the whole point of the transport seam in #29 was so SageMaker stays invisible to the SDK. transportFactory() was meant to be the entire surface area, and looking at the plugin side over on deepgram/deepgram-java-sdk-transport-sagemaker#14 I think we can keep it that way.

what's happening here is storm handling that belongs in SageMakerTransport is bleeding upward into the generated WS clients via a boolean flag and four near-identical 75-line listener implementations. the freeze list goes from 1 file to 5, and every future regen has to reconcile four duplicated anonymous listeners.

the 4-second connectionFuture.get(4000, MILLISECONDS) ceiling and the maxRetries = Integer.MAX_VALUE default in ReconnectingWebSocketListener are both real, but they're our bugs in that file. fix them there:

• maxRetries(0) should mean "connect once, don't retry", not "refuse to connect"
• promote the hardcoded 4000 to a configurable connectionTimeoutMs on ReconnectOptions

then the plugin sets its own policy via webSocketReconnectOptions(...) and core stays untouched. no boolean on ClientOptions, no edits to generated WS clients, no new .fernignore entries past freezing the listener itself.

the storm itself shouldn't even reach ReconnectingWebSocketListener in normal operation. AWS ThrottlingException / pool exhaustion / connect timeouts should be classified and absorbed inside SageMakerTransport.ensureConnected() before they ever fire transport.onError(...). that's plugin-side work, I've left the detail on #14.

asks:

• revert the four resources/.../websocket/*WebSocketClient.java edits
• revert the four new .fernignore entries
• drop ClientOptions.reconnect(boolean) and the if (transportFactory != null) builder.reconnect(false) heuristic
• fix ReconnectingWebSocketListener instead, freeze just that file
• let the plugin declare its own ReconnectOptions. a default ReconnectOptions reconnectOptions() on DeepgramTransportFactory would do it cleanly, that file is permanently frozen anyway

with the plugin-side change in #14, customer outcome is the same, one freeze entry instead of four, and transportFactory() stays the only thing core knows about SageMaker.

[VWang1111]

Updated PR based on comments