Updated for Nexus SDK Ergonomics - Not ready to be merged yet!! - #5203
Updated for Nexus SDK Ergonomics - Not ready to be merged yet!!#5203Evanthx wants to merge 9 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📖 Docs PR preview links
|
There was a problem hiding this comment.
🟡 Changes recommended
The Java guide duplicates existing documentation, lacks a runnable generated-contract setup, and leaves related Nexus pages inconsistent.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds prerelease Nexus SDK ergonomics documentation and a Java implementation guide.
Changes:
- Documents the unified Temporal Operation Handler, code generation, and Activity-backed Operations.
- Adds a Java prerelease developer guide.
- Adds the new pages to Nexus navigation.
File summaries
| File | Description |
|---|---|
sidebars.js |
Registers and groups the new pages. |
docs/encyclopedia/nexus/temporal-operation-handler.mdx |
Explains the unified handler API. |
docs/encyclopedia/nexus/nexus-standalone-activity.mdx |
Describes Activity-backed Operations. |
docs/encyclopedia/nexus/nexus-code-generator.mdx |
Introduces generated Nexus contracts. |
docs/develop/java/nexus/developer-experience.mdx |
Provides Java usage and deployment guidance. |
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 4
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| APIs are experimental and may be subject to backwards-incompatible changes. | ||
| </ReleaseNoteHeader> | ||
|
|
||
| Temporal has unified the Workflow handler and the synchronous operation handler into a single handler, and added the ability to back an Operation with a [Standalone Activity](/nexus/standalone-activity). |
| The Nexus Code Generator, [`nexgen`](https://github.com/temporalio/nex-gen), turns one schema into client code for Go, Java, Python, and TypeScript. | ||
| Both sides of a [Nexus Service](/nexus/services) generate from the same file, so neither hand-writes the types and neither can drift from the contract. |
| You can hand-write that package, but the preferred way is to generate it with the [Nexus Code Generator](https://github.com/temporalio/nex-gen). | ||
| You write the contract once as a JSON definition file and run `nexgen` against it, and it emits the typed models, | ||
| runtime validators, and the Service definition itself. |
|
Taking a quick look at this. Will do a deeper look this week. |
|
|
||
| import { ReleaseNoteHeader } from '@site/src/components'; | ||
|
|
||
| <ReleaseNoteHeader type="prerelease" languages={["Go", "Java", "Python", "TypeScript"]}> |
There was a problem hiding this comment.
This need links on the logos just to be consistent - but this is something I can do.
| APIs are experimental and may be subject to backwards-incompatible changes. | ||
| </ReleaseNoteHeader> | ||
|
|
||
| The Nexus Code Generator, [`nexgen`](https://github.com/temporalio/nex-gen), turns one schema into client code for Go, Java, Python, and TypeScript. |
There was a problem hiding this comment.
Since Nexus Code Generator might bring traffic from people who might be unfamiliar with Nexus, I'm wondering if this needs a very basic intro sentence on what a nexus code generator is for users.
There was a problem hiding this comment.
Also starting off with why use a Nexus Code Generator could be helpful as an intro.
There was a problem hiding this comment.
Good idea, I reworked that paragraph. See if you like this better!
|
|
| APIs are experimental and may be subject to backwards-incompatible changes. | ||
| </ReleaseNoteHeader> | ||
|
|
||
| :::note Not the same as a Standalone Nexus Operation |
There was a problem hiding this comment.
We try not to stack admonitions.
There was a problem hiding this comment.
Assuming this is about the release note and the note coming one right after the other - the release note will go away as soon as this comes out of pre-release, and the note I added to address something that I found very confusing so I thought needed to be clarified. I would like to defend this one, especially since the release note will be getting removed as soon as this comes out of pre-release.
There was a problem hiding this comment.
🟡 Changes recommended
The new guides duplicate existing feature guides, omit collateral updates, and incorrectly claim .NET code-generation support.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (2)
docs/develop/java/nexus/developer-experience.mdx:4
- This creates a second full Nexus feature guide beside
docs/develop/java/nexus/feature-guide.mdx; 602 of this page's 696 lines duplicate that guide. The documented SDK structure defines Nexus as a Quickstart plus one feature guide (readme/INFORMATION-ARCHITECTURE.md:150-151). Merge the ergonomics updates into the existing feature guide instead of publishing parallel guides that can drift.
title: Nexus Developer Experience - Java SDK feature guide
docs/encyclopedia/nexus/temporal-operation-handler.mdx:19
- The parent and lifecycle pages still describe the old handler model:
docs/encyclopedia/nexus/nexus.mdx:50-55says asynchronous Operations only start Workflows and treats Updates as synchronous, whiledocs/encyclopedia/nexus/nexus-operations.mdx:16,36-39still documents Workflow-backed async and separateNew-Workflow-Run-Operation/New-Sync-Operationbuilders. Update those pages alongside this unified handler so readers do not get conflicting definitions of async backings and handler APIs.
Temporal has unified the Workflow handler and the synchronous operation handler into a single handler, and added the ability to back an Operation with a [Standalone Activity](/nexus/standalone-activity).
- Files reviewed: 9/9 changed files
- Comments generated: 5
- Review effort level: Balanced
| You can hand-write that package, but the preferred way is to generate it with the [Nexus Code Generator](https://github.com/temporalio/nex-gen). | ||
| You write the contract once as a JSON definition file and run `nexgen` against it, and it emits the typed models, | ||
| runtime validators, and the Service definition itself. | ||
|
|
||
| This is what makes a Nexus Service polyglot. Both sides generate from the same definition file: the handler implements | ||
| the Service, the caller invokes its Operations, and neither hand-writes a request or response type. A Python handler | ||
| and a Go caller share no code, but they both run off that same service contract - so they interoperate with no | ||
| coordination between the teams beyond the contract itself. | ||
|
|
||
| The generated validators check every payload against the contract, when a value is parsed off the wire and again when | ||
| it is serialized onto it, so bad data is rejected at the boundary rather than reaching your Workflow. A value validates | ||
| identically in every language, which is what lets a caller and a handler written in different languages trust the same | ||
| contract. See the [`chat.nexusrpc.yaml`](https://github.com/temporalio/nex-gen/blob/main/samples/schemas/chat.nexusrpc.yaml) | ||
| sample contract and the [Definition files](https://github.com/temporalio/nex-gen#definition-files) section of the | ||
| `nexgen` README for the file format. |
| --- | ||
| id: developer-experience | ||
| slug: /develop/dotnet/nexus/developer-experience | ||
| title: Nexus Developer Experience - .NET SDK feature guide |
| --- | ||
| id: developer-experience | ||
| slug: /develop/go/nexus/developer-experience | ||
| title: Nexus Developer Experience - Go SDK feature guide |
| --- | ||
| id: developer-experience | ||
| slug: /develop/python/nexus/developer-experience | ||
| title: Nexus Developer Experience - Python SDK feature guide |
| --- | ||
| id: developer-experience | ||
| slug: /develop/typescript/nexus/developer-experience | ||
| title: Nexus Developer Experience - TypeScript SDK feature guide |
✅ Docs build passed |
|
Let's keep the feature guide as the title for now. The content of the dev experience page should all still be there since it's folded into the page but we can keep the feature page metadata - this also avoids changing all the redirects/urls. I added a callout that there's a new developer experience. Going to make a few more edits. |
bergundy
left a comment
bergundy
left a comment
There was a problem hiding this comment.
I started reviewing the whole guide and stopped myself. I am debating whether to spend time on that or not. The nexgen docs were fully reviewed.
|
|
||
| :::note | ||
|
|
||
| This Feature Guide includes the new Nexus developer experience: pre-release APIs for the [Temporal Operation Handler](/nexus/temporal-operation-handler) and [Nexus Standalone Activity](/nexus/standalone-activity). These APIs are experimental and may change. |
There was a problem hiding this comment.
I don't think we should call this feature "Nexus standalone activity", but you can say that this guide covers invoking a standalone activity from a nexus handler.
There was a problem hiding this comment.
nit: I would say "subject to change".
| Handlers should be reliable since the [circuit breaker](/nexus/operations#circuit-breaking) trips after 5 consecutive retryable errors, blocking all Operations from the caller to that Endpoint. | ||
|
|
||
| The `Temporalio.Nexus` namespace has utilities to help create Nexus Operations: | ||
| Every Operation is written with [`TemporalOperationHandler`](/nexus/temporal-operation-handler). Mark a method |
There was a problem hiding this comment.
I feel like this statement is confusing. We don't show the TemporalOperationHandler just the shorthand TemporalOperation.
|
|
||
| The `Temporalio.Nexus` namespace has utilities to help create Nexus Operations: | ||
| Every Operation is written with [`TemporalOperationHandler`](/nexus/temporal-operation-handler). Mark a method | ||
| `[TemporalOperation]` and the method body itself becomes the start handler, receiving three things: a |
There was a problem hiding this comment.
I would try to avoid using terminology like "start handler", it's better to say "operation handler" IMHO and just ignore the details of start and cancel.
| sidebar_label: Nexus Code Generator | ||
| description: The Nexus Code Generator turns one schema into typed models, runtime validators, and Nexus Service definitions for Go, Java, Python, and TypeScript. |
There was a problem hiding this comment.
Can we call this nexgen to match the language everywhere?
Same goes for the name of the file.
| APIs are experimental and may be subject to backwards-incompatible changes. | ||
| </ReleaseNoteHeader> | ||
|
|
||
| A [Nexus Service](/nexus/services) is called across a team boundary, often by a caller written in a different language and deployed on its own schedule. |
There was a problem hiding this comment.
Not super clear to me what it's different from.
| A [Nexus Service](/nexus/services) is called across a team boundary, often by a caller written in a different language and deployed on its own schedule. | |
| A [Nexus Service](/nexus/services) is called across a team boundary, often by a caller written in a different language than the handler implementation and deployed on its own schedule. |
| ## How it works | ||
|
|
||
| You write the contract once, as a JSON definition file, and run `nexgen` against it. | ||
| The generator emits client code in Go, Java, Python, or TypeScript. |
There was a problem hiding this comment.
| The generator emits client code in Go, Java, Python, or TypeScript. | |
| The generator emits contract code in Go, Java, Python, or TypeScript as requested. |
| ## Data validation | ||
|
|
||
| The generated validators check every payload against the contract, when a value is parsed off the wire and again when it is serialized onto it. | ||
| Bad data is rejected at the boundary instead of reaching your Workflow. |
There was a problem hiding this comment.
| Bad data is rejected at the boundary instead of reaching your Workflow. | |
| Bad data is rejected at the boundary instead of reaching your Workflow or Activity. |
| The generated validators check every payload against the contract, when a value is parsed off the wire and again when it is serialized onto it. | ||
| Bad data is rejected at the boundary instead of reaching your Workflow. | ||
|
|
||
| Failures aggregate into a single error listing every violation, each naming the offending field and the bound it broke. |
There was a problem hiding this comment.
| Failures aggregate into a single error listing every violation, each naming the offending field and the bound it broke. | |
| Failures aggregate into a single error listing every violation, each naming the offending field and the constraint it broke. |
| Bad data is rejected at the boundary instead of reaching your Workflow. | ||
|
|
||
| Failures aggregate into a single error listing every violation, each naming the offending field and the bound it broke. | ||
| A handler maps that to a `BAD_REQUEST` [Nexus error](/nexus/error-handling), so a malformed request tells the caller everything that was wrong in one response. |
There was a problem hiding this comment.
| A handler maps that to a `BAD_REQUEST` [Nexus error](/nexus/error-handling), so a malformed request tells the caller everything that was wrong in one response. | |
| A handler maps that to a `BAD_REQUEST` [Nexus handler error](/nexus/error-handling), so a malformed request tells the caller everything that was wrong in one response. |
| A handler maps that to a `BAD_REQUEST` [Nexus error](/nexus/error-handling), so a malformed request tells the caller everything that was wrong in one response. | ||
|
|
||
| A value is validated identically in every language, which is what lets a caller and a handler written in different ones trust the same contract. | ||
| Keeping that promise is why the supported schema subset is deliberately strict: anything ambiguous, or anything that cannot be expressed the same way everywhere, is rejected at generation time rather than becoming code that validates differently in one language than another. |
There was a problem hiding this comment.
I'd maybe note the few documented cross language inconsistencies: https://github.com/temporalio/nexgen#known-cross-language-divergences
This adds and updates some information about Nexus SDK ergonomics.
Dev Experience page replaces the Nexus feature guide.