Skip to content

feat(regen): add AutoCloseable client lifecycle and Flux runtime numerals - #114

Merged
GregHolmes merged 10 commits into
mainfrom
gh/sdk-gen-2026-09-23
Sep 24, 2026
Merged

GregHolmes merged 10 commits into
mainfrom
gh/sdk-gen-2026-09-23

Conversation

@GregHolmes

@GregHolmes GregHolmes commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Regenerates the Java SDK with Fern 4.21.0 and preserves existing compatibility/runtime patches that Fern does not yet emit.

  • Adds AutoCloseable clients with ownership-aware OkHttp cleanup: SDK-created clients release dispatcher and connection-pool resources; caller-supplied OkHttpClient instances remain caller-owned. Close each WebSocket client before closing its root client.
  • Adds Flux Listen v2 runtime ListenV2Configure.numerals support for turns transcribed after the update.
  • Restores all 23 existing compatibility/runtime patches, then removes the temporary .bak files.
  • Retains the released 0.10.1 metadata; Release Please owns the next version bump.
  • Supersedes the lifecycle implementation in fix(client): release owned HTTP resources #108: Fern now generates the behavior, while wrapper-level regression tests and README guidance remain here.

Validation

  • ./gradlew spotlessApply
  • ./gradlew spotlessCheck test compileExamples
  • ./gradlew test --tests com.deepgram.ReadmeSnippetsCompileTest --rerun-tasks
  • Lifecycle ownership tests for sync and async wrapper clients
  • Versionless update-listen provider regression coverage
  • Typed runtime numerals Configure wire coverage

@GregHolmes GregHolmes changed the title chore: SDK regeneration 2026-09-23 feat(regen): add client lifecycle management and Flux numerals configuration Sep 23, 2026

@dg-coreylweathers dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. The new Flux snippet (README.md:311-321) creates fluxWs and 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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)".
  6. 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.
  7. 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.
  8. 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.
  9. 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.

@GregHolmes GregHolmes changed the title feat(regen): add client lifecycle management and Flux numerals configuration feat: add AutoCloseable lifecycle (close WS first, supplied OkHttp caller-owned) and Flux runtime numerals Sep 23, 2026
@GregHolmes

Copy link
Copy Markdown
Collaborator Author

Addressed the review feedback in beb6c98:

  • close() is now safe before connect() in all five WebSocket clients, with a regression test for each.
  • Both new README snippets are self-contained, await connection, and close WebSockets before their root client.
  • Restored the generated-file patch markers, added the Agent WebSocket freeze entry, tightened Configure frame coverage for true/false/omitted numerals, corrected the lifecycle Javadoc, and updated two streaming examples plus the historical migration note.
  • Updated the PR title so the generated changelog captures AutoCloseable lifecycle ownership, close ordering, and Flux runtime numerals.

Validation: ./gradlew compileExamples test passes.

One cross-repo item from the independent DevRel review: the published Numerals guide still says Flux rejects runtime Configure.numerals, while the AsyncAPI schema and this SDK now model it. Separately, ListenV2ConfigureSuccessEvent does not model the acknowledged numerals value, so generated SDKs expose it only through additional properties. We need to raise a deepgram-docs issue to align the guide and add ConfigureSuccess.numerals, then regenerate the SDKs.

@GregHolmes

Copy link
Copy Markdown
Collaborator Author

Correction to my prior note: the required cross-repository work already exists in deepgram/deepgram-docs#1226. It updates the Numerals guide and adds numerals to ListenV2ConfigureSuccessEvent, so we do not need a new issue.

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 dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 push

After 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 .fernignore and AGENTS.md.
  • Does close() respect ownership? Yes. An OkHttp client the SDK created has its dispatcher shut down, a caller-supplied one is left untouched, and ClientBuilderTest asserts both cases.
  • Does ListenV2Configure.numerals reach 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 AutoCloseable and close().
  • 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.

@GregHolmes GregHolmes changed the title feat: add AutoCloseable lifecycle (close WS first, supplied OkHttp caller-owned) and Flux runtime numerals feat: AutoCloseable clients with caller-owned OkHttp, and Flux runtime numerals Sep 24, 2026
@GregHolmes GregHolmes changed the title feat: AutoCloseable clients with caller-owned OkHttp, and Flux runtime numerals chore: SDK regeneration 2026-09-23 Sep 24, 2026
@GregHolmes GregHolmes changed the title chore: SDK regeneration 2026-09-23 feat(regen): add AutoCloseable client lifecycle and Flux runtime numerals Sep 24, 2026

@dg-coreylweathers dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 .fernignore and AGENTS.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 numerals reach 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 numerals to ListenV2ConfigureSuccessEvent, and this regen predates it. Until then, Java callers read that value through getAdditionalProperties(). Nothing fails, because unknown fields are ignored.
  • For the Fern request list: closing the root client while a WebSocket is open gives a bare RejectedExecutionException on the next reconnect.

@GregHolmes
GregHolmes merged commit ff9fdd4 into main Sep 24, 2026
8 of 10 checks passed
GregHolmes added a commit that referenced this pull request Sep 28, 2026
🤖 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants