Add Temporal Nexus Operation Handler

[Quinn-With-Two-Ns]

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
Adds new public Nexus handler/client APIs and changes operation-token parsing/cancel dispatch behavior, which could affect async operation lifecycle and cancellation semantics. Risk is moderate since changes are mostly additive but touch workflow start/link attachment and token validation used across Nexus operations.

Overview
Adds a new generic TemporalOperationHandler API that lets Nexus operation implementations return either sync results or start an async workflow via a new TemporalNexusClient (typed overloads + untyped) and TemporalOperationResult.

Refactors workflow-start/link attachment into NexusStartWorkflowHelper and updates WorkflowRunOperationImpl to use it.

Renames and generalizes workflow-run tokens to OperationToken, extends OperationTokenUtil with loadOperationToken (type-agnostic) while keeping a workflow-run asserting loader, and adds/updates tests covering typed/untyped starts, sync results, double-start guard, and cancel dispatch.

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

[cursor]

Unreachable else branch is dead code

Low Severity

The else branch in TemporalOperationHandler.start() is unreachable dead code. TemporalOperationResult.isSync() returns the isSync field, and isAsync() returns !isSync — they are always complementary. No instance of TemporalOperationResult can ever be neither sync nor async, so the HandlerException at the bottom can never be thrown.

Additional Locations (1)

• temporal-sdk/src/main/java/io/temporal/nexus/TemporalOperationResult.java#L53-L61

 

^{Reviewed by Cursor Bugbot for commit 7e61dab. Configure here.}

[VegetarianOrc]

Forgive my lack of Java concurrency know how, but could this flag cause a race if you call startWorkflow concurrently? Both attempt to start, race past the check and successfully start a workflow.

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

[cursor]

Non-thread-safe check-then-act on asyncOperationStarted flag

Medium Severity

The asyncOperationStarted boolean field uses a check-then-act pattern without synchronization. If startWorkflow is called concurrently from multiple threads sharing this client instance, both calls can race past the if (asyncOperationStarted) check before either sets the flag to true, resulting in two workflows being started when the invariant requires at most one. Making the field volatile alone wouldn't fix the TOCTOU issue; an AtomicBoolean with compareAndSet or synchronized block is needed to make the guard atomic.

 

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