Add Temporal Nexus Operation Handler by Quinn-With-Two-Ns · Pull Request #2842 · temporalio/sdk-java

Quinn-With-Two-Ns · 2026-04-14T19:03:08Z

Add TemporalOperationHandler for generic Nexus operations

Goal

Provide a new base to make it easy to expose more Temporal actions as Nexus Operations

Summary

Adds TemporalOperationHandler, a generic OperationHandler implementation that maps Nexus operations to Temporal workflows via a composable StartFunction
Adds TemporalNexusClient for starting workflows (typed and untyped) from within Nexus operation handlers
Supports subclassing TemporalOperationHandler to customize cancel behavior by overriding cancelWorkflowRun
Extracts shared workflow start logic into NexusStartWorkflowHelper, reused by both WorkflowRunOperation and the new handler

Test plan

GenericHandlerTypedStartWorkflowTest — typed workflow with return value
GenericHandlerTypedProcTest — typed void workflow
GenericHandlerUntypedStartWorkflowTest — untyped workflow start
GenericHandlerSyncResultTest — synchronous result path
GenericHandlerCancelTest — cancel with default and custom behavior

Note

Medium Risk
New experimental handler API on the Nexus workflow start/cancel path; behavior is covered by integration tests but affects how operations complete and cancel downstream workflows.

Overview
Adds an experimental composable Nexus path: TemporalOperationHandler.create(...) wires a start lambda to TemporalNexusClient (typed/untyped workflow starts) and TemporalOperationResult for sync vs async (operation token) responses. Cancel parses tokens via generalized OperationToken / loadOperationToken, dispatches workflow-run cancels (default: cancel workflow; overridable cancelWorkflowRun).

NexusStartWorkflowHelper centralizes Nexus workflow start + link attachment; WorkflowRunOperationImpl now delegates to it. TemporalNexusClientImpl allows only one async startWorkflow per handler call (extra starts error; guard resets on failure).

Tests cover typed/untyped starts, sync results, cancel, and double-start rejection.

^{Reviewed by Cursor Bugbot for commit 10a94e4. Bugbot is set up for automated code reviews on this repo. Configure here.}

VegetarianOrc

Looks great. Couple small questions mostly for my learning!

VegetarianOrc · 2026-05-22T16:54:00Z

    if (Strings.isNullOrEmpty(token.getWorkflowId())) {
-      throw new IllegalArgumentException("Invalid workflow run token: missing workflow ID (wid)");
+      throw new IllegalArgumentException("Invalid operation token: missing workflow ID (wid)");


Should this check be moved into loadWorkflowRunOperationToken?

VegetarianOrc · 2026-05-22T17:56:22Z

+  /**
+   * Returns the synchronous result value, or null if this is an async result.
+   *
+   * @return the sync result value, or null
+   */
+  @Nullable
+  public R getSyncResult() {
+    return syncResult;
+  }
+
+  /**
+   * Returns the async operation token, or null if this is a sync result.
+   *
+   * @return the operation token, or null
+   */
+  @Nullable
+  public String getAsyncOperationToken() {
+    return asyncOperationToken;
+  }


Just a style question to familiarize myself with Java a bit more: Should these throw if invoked on the wrong type of result? i.e. should getAsyncOperationToken throw if isSync == true?

Agreed, it would be more idiomatic to check and throw. We can then remove @Nullable annotations from the methods too.

VegetarianOrc · 2026-05-22T17:58:57Z


-  public WorkflowRunOperationToken(String namespace, String workflowId) {
-    this.type = OperationTokenType.WORKFLOW_RUN;
+  public OperationToken(OperationTokenType type, String namespace, String workflowId) {


With more types of tokens upcoming, should we favor something like static constructors for this like OperationToken.NewWorkflowRunToken() that takes the required fields for the workflow run type?

I guess this is a bit like what OperationTokenUtil provides so feel free to dismiss this!

maciejdudko

Looks good, only a few small changes needed.

maciejdudko · 2026-06-04T21:00:27Z

+  /**
+   * Returns the synchronous result value, or null if this is an async result.
+   *
+   * @return the sync result value, or null
+   */
+  @Nullable
+  public R getSyncResult() {
+    return syncResult;
+  }
+
+  /**
+   * Returns the async operation token, or null if this is a sync result.
+   *
+   * @return the operation token, or null
+   */
+  @Nullable
+  public String getAsyncOperationToken() {
+    return asyncOperationToken;
+  }


Agreed, it would be more idiomatic to check and throw. We can then remove @Nullable annotations from the methods too.

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 10a94e4. Configure here.}

Quinn-With-Two-Ns marked this pull request as ready for review April 14, 2026 22:33

Quinn-With-Two-Ns requested a review from a team as a code owner April 14, 2026 22:33

Quinn-With-Two-Ns commented Apr 14, 2026

View reviewed changes

Comment thread temporal-sdk/src/test/java/io/temporal/workflow/nexus/GenericHandlerTypedProcTest.java Outdated

cursor Bot reviewed Apr 14, 2026

View reviewed changes

Comment thread temporal-sdk/src/test/java/io/temporal/internal/nexus/WorkflowRunTokenTest.java

Comment thread temporal-sdk/src/test/java/io/temporal/workflow/nexus/AsyncWorkflowOperationTest.java Outdated

cursor Bot reviewed Apr 14, 2026

View reviewed changes

Comment thread temporal-sdk/src/test/java/io/temporal/workflow/nexus/AsyncWorkflowOperationTest.java Outdated

cursor Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/internal/nexus/OperationTokenUtil.java

Quinn-With-Two-Ns force-pushed the temporal-nexus-operation-handler branch from a33ff01 to 7e61dab Compare May 8, 2026 14:14

cursor Bot reviewed May 8, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalOperationHandler.java

Quinn-With-Two-Ns requested a review from bergundy May 11, 2026 15:09

VegetarianOrc reviewed May 12, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java Outdated

Quinn-With-Two-Ns added 8 commits May 15, 2026 16:04

Add Temporal Nexus Operation Handler

6a88535

Update

380e112

Update some docs

deb19d4

Update calling convention

ba2fbb6

Code review

1e424f3

Address feedback

77502a8

Add check for duplicate handler start

e03fa5d

Add check for duplicate handler start

f2c65fc

Quinn-With-Two-Ns force-pushed the temporal-nexus-operation-handler branch from 7e61dab to f2c65fc Compare May 15, 2026 23:04

cursor Bot reviewed May 15, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java Outdated

bergundy removed their request for review May 20, 2026 19:14

Fix race

d448f63

VegetarianOrc approved these changes May 22, 2026

View reviewed changes

Switch to CancelWorkflowRunInput

de643d7

cursor Bot reviewed May 29, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java

Switch to CancelWorkflowRunInput

d6dc34a

Quinn-With-Two-Ns requested a review from maciejdudko May 29, 2026 20:37

maciejdudko requested changes Jun 4, 2026

View reviewed changes

Respond to PR comments

10a94e4

Quinn-With-Two-Ns requested a review from maciejdudko June 4, 2026 22:42

cursor Bot reviewed Jun 4, 2026

View reviewed changes

Comment thread temporal-sdk/src/main/java/io/temporal/nexus/TemporalNexusClientImpl.java

maciejdudko approved these changes Jun 5, 2026

View reviewed changes

Conversation

Quinn-With-Two-Ns commented Apr 14, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add TemporalOperationHandler for generic Nexus operations

Goal

Summary

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VegetarianOrc left a comment

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc May 22, 2026

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc May 22, 2026

Choose a reason for hiding this comment

Uh oh!

maciejdudko Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Quinn-With-Two-Ns Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maciejdudko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maciejdudko Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Quinn-With-Two-Ns commented Apr 14, 2026 •

edited by cursor Bot

Loading