Repository navigation
feat(regen): add AutoCloseable client lifecycle and Flux runtime numerals - #114
Conversation
dg-coreylweathers
left a comment
There was a problem hiding this comment.
Regen looks structurally sound — all 23 manual patches survived 4.21.0 verbatim, no public surface was removed, and the version state is consistent at 0.10.1. I verified the Flux claim against live production rather than by inspection: six sessions, the mid-session Configure frame is accepted, the connection survives, and turns after it come back in the new form ("twenty three messages and forty two dollars" → "23 messages and 42 dollars"), with a no-Configure control run ruling out transcription noise. The UNPARSABLE_CLIENT_MESSAGE failure this frame produced on an earlier attempt did not reproduce.
One blocking item before merge.
The new "Resource Lifecycle" README snippet throws when run. It opens a WebSocket client in try-with-resources without calling connect(), and close() → disconnect() dereferences reconnectingListener, which only connect() assigns (V2WebSocketClient.java:60, :175, :232). Compiled and run against this branch:
Exception in thread "main" java.lang.NullPointerException: Cannot invoke
"com.deepgram.core.ReconnectingWebSocketListener.disconnect()" because "this.reconnectingListener" is null
at com.deepgram.resources.listen.v2.websocket.V2WebSocketClient.disconnect(V2WebSocketClient.java:232)
at com.deepgram.resources.listen.v2.websocket.V2WebSocketClient.close(V2WebSocketClient.java:390)
ReadmeSnippetsCompileTest compiles snippets but never executes them, so this stays green in CI. The null-guard gap in disconnect() is pre-existing generated code in all five WS clients — what's new is that this section walks developers into it. Minimal fix is to call connect() inside the try block:
try (DeepgramClient client = DeepgramClient.builder().build()) {
try (V2WebSocketClient ws = client.listen().v2().v2WebSocket()) {
ws.connect(V2ConnectOptions.builder()
.model(ListenV2Model.FLUX_GENERAL_EN)
.build())
.get(10, TimeUnit.SECONDS);
// Send audio and handle events.
}
}Worth deciding separately whether disconnect() should also be null-guarded in all five clients so close()-without-connect() is safe generally — that's a 24th carried patch versus a generator fix, your call.
Should-fix items:
- The new Flux snippet (README.md:311-321) creates
fluxWsand never closes it, contradicting the lifecycle section this same PR adds at README.md:74. Matters because ReconnectingWebSocketListener holds a non-daemon executor, so an unclosed connected client keeps the JVM alive. - All 21
// Manual patch - see .fernignore.markers were deleted repo-wide (21 files on main → 0 here); that's the entire -2 delta on the fields-less types, the unions and the WS clients. Not formatter-driven — they were present on main at the green 0.10.1 commit. It's the in-file signal AGENTS.md step 6 exists to back up after ListenV2ForceEndTurn once slipped through. - The generated changelog line ("add client lifecycle management and Flux numerals configuration") names no method, no ownership rule and no ordering requirement. Since release PR bodies here are already hand-curated (0.10.1 names onFunctionCallCancelled and deferUntilEot verbatim), worth curating this one to mention AutoCloseable/close(), that a caller-supplied OkHttpClient stays caller-owned, and the close-WebSockets-first ordering.
- ListenV2ControlFrameWireTest.java:119-128 uses contains() where the sibling test 12 lines above asserts the exact frame, with a comment explaining why ("the server rejects unknown fields on control messages"). Suggest isEqualTo("{"type":"Configure","numerals":true}"), plus the numerals(false) and omitted cases.
- docs/Migrating-v0.6-to-v0.7.md:92 still ends "Connection-time only." Keeping the historical guide accurate to 0.7.0 is right, but a forward pointer costs nothing: "(as of 0.7.0; later versions can also change it mid-stream — see the README)".
- The new AGENTS.md:51 bullet names no file although it sits under "Current temporarily frozen files", and has no exit condition — it's really a reconciliation caveat about ClientOptions.java on the line above. Fold it there, or move it under "After regeneration". The parallel .fernignore:17 comment is attached to its file and is the right pattern.
- examples/ has 43 client constructions and zero closes, so every shipped example now models what README.md:73 warns against. compileExamples won't flag it. Converting one or two would be enough.
- Neither new snippet is copy-pasteable: the lifecycle one uses DeepgramClient without importing it, the Flux one uses an undeclared
client. The compile test injects both, so CI can't catch it. - ClientOptions.java:135-136 says requests after close() fail with RejectedExecutionException. Sync calls use OkHttp's execute(), which never touches the dispatcher executor, so they succeed — and DeepgramClient is the sync client. Async delivers InterruptedIOException("executor rejected") instead.
Separately, and not blocking this PR: the server's ConfigureSuccess carries numerals, profanity_filter and redact_usage, none of which ListenV2ConfigureSuccess models, so they only reach callers via getAdditionalProperties() (and language_hints is modeled but not returned). That's a spec fix in api/specs/** that regenerates every SDK.
Verified: gate green in Docker (spotlessCheck test compileExamples), all 23 patches intact, fields-less hashCode sweep clean, no .bak files left, FLUX_RENEE_EN restored at all five touchpoints, escape hatch still reaching the upgrade URL, ownership flag correct on every construction path including Builder.from, no source or behavior break for a 0.10.1 consumer, and feat(regen): correctly yielding 0.10.2 given bump-patch-for-minor-pre-major.
|
Addressed the review feedback in beb6c98:
Validation: One cross-repo item from the independent DevRel review: the published Numerals guide still says Flux rejects runtime |
|
Correction to my prior note: the required cross-repository work already exists in deepgram/deepgram-docs#1226. It updates the Numerals guide and adds The direct Java review items are addressed in beb6c98. Could you re-review the Java content while #1226 finishes review? We should hold merge on this PR until #1226 merges and its documentation deploys; the follow-up SDK regeneration for the typed ConfigureSuccess getter can remain additive release work. |
dg-coreylweathers
left a comment
There was a problem hiding this comment.
@GregHolmes, two small fixes will turn CI green. The regen itself checks out, details below.
1. Spotless Check fails on ClientBuilderTest.java
The formatter wants one line wrapped at src/test/java/com/deepgram/ClientBuilderTest.java:186. Run:
./gradlew spotlessApply
git commit -am "style: apply spotless formatting"
git pushAfter the fix, that line reads:
try (DeepgramClient client =
DeepgramClient.builder().apiKey("test-key").build()) {2. Title Check fails: the title is 106 characters, the limit is 100
gh pr edit 114 --title "feat: AutoCloseable clients with caller-owned OkHttp, and Flux runtime numerals"Verify: ./gradlew spotlessCheck test compileExamples passes locally (I ran it in eclipse-temurin:17-jdk: test compileExamples passes and only spotlessCheck fails today). Both checks go green on the next push.
What I checked
- Did all 23 manual patches survive the regen? Yes. The new agent WebSocket
disconnect()null guard is also recorded in.fernignoreandAGENTS.md. - Does
close()respect ownership? Yes. An OkHttp client the SDK created has its dispatcher shut down, a caller-supplied one is left untouched, andClientBuilderTestasserts both cases. - Does
ListenV2Configure.numeralsreach the wire? Yes. The wire test asserts the literal JSON, including leaving the field out when it is unset. - Any public API removed? No. The change only adds
AutoCloseableandclose(). - README, migration doc, examples? Every referenced symbol exists, and the 0.7 migration guidance is preserved.
Follow-up, not blocking this PR: every WebSocket client shares the root client's OkHttp dispatcher. A caller who closes the root client while a socket is still open gets a bare RejectedExecutionException on the next reconnect. README documents the close order, but nothing enforces it. Fern generates this code, so it's worth adding to the upstream request list.
dg-coreylweathers
left a comment
There was a problem hiding this comment.
@GregHolmes, approved on bdf4551.
What this PR does: Regenerates the Java SDK with Fern 4.21.0. Root clients are now AutoCloseable: closing one releases the OkHttp threads and connections when the SDK created them, and leaves a caller-supplied OkHttpClient alone. Flux Listen v2 gains a mid-stream ListenV2Configure.numerals setting. All 23 existing manual patches are carried forward.
What I checked
- Are the CI items from my last review fixed? Yes. The formatting fix and the retitle both pass, and compile plus unit tests pass on Java 11, 17 and 21.
- Did the manual patches survive? Yes, all 23, plus the new agent WebSocket
disconnect()null guard, which is recorded in.fernignoreandAGENTS.md. - Does
close()respect ownership? Yes. The tests assert that an SDK-created client is shut down and a caller-supplied one is not. - Does
numeralsreach the wire? Yes. The wire tests assert the literal JSON for true, for false, and for the field left out. - Is the merge hold still needed? No. deepgram-docs#1226 merged at 13:01 UTC today.
For the next regen, non-blocking:
- #1226 added
numeralstoListenV2ConfigureSuccessEvent, and this regen predates it. Until then, Java callers read that value throughgetAdditionalProperties(). Nothing fails, because unknown fields are ignored. - For the Fern request list: closing the root client while a WebSocket is open gives a bare
RejectedExecutionExceptionon the next reconnect.
🤖 I have created a release *beep* *boop* --- ## [0.10.2](v0.10.1...v0.10.2) (2026-09-24) ### Features * **Client lifecycle:** `DeepgramClient` and `AsyncDeepgramClient` now implement `AutoCloseable` for try-with-resources. Closing a root client releases SDK-owned OkHttp dispatcher and connection-pool resources, while caller-provided `OkHttpClient` instances remain caller-owned; close associated WebSocket clients before the root client. ([#114](#114)) ([ff9fdd4](ff9fdd4)) * **Listen v2 (Flux):** configure numerals during an active session with `wsClient.sendConfigure(ListenV2Configure.builder().numerals(true).build())`; the setting applies to turns transcribed after the update. ([#114](#114)) ([ff9fdd4](ff9fdd4)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Greg Holmes <greg.holmes@deepgram.com>
Summary
Regenerates the Java SDK with Fern 4.21.0 and preserves existing compatibility/runtime patches that Fern does not yet emit.
AutoCloseableclients with ownership-aware OkHttp cleanup: SDK-created clients release dispatcher and connection-pool resources; caller-suppliedOkHttpClientinstances remain caller-owned. Close each WebSocket client before closing its root client.ListenV2Configure.numeralssupport for turns transcribed after the update..bakfiles.0.10.1metadata; Release Please owns the next version bump.Validation
./gradlew spotlessApply./gradlew spotlessCheck test compileExamples./gradlew test --tests com.deepgram.ReadmeSnippetsCompileTest --rerun-tasks