Skip to content

Generic Temporal Nexus Operation Handler#690

Open
Quinn-With-Two-Ns wants to merge 4 commits into
temporalio:mainfrom
Quinn-With-Two-Ns:nexus-generic-handler
Open

Generic Temporal Nexus Operation Handler#690
Quinn-With-Two-Ns wants to merge 4 commits into
temporalio:mainfrom
Quinn-With-Two-Ns:nexus-generic-handler

Conversation

@Quinn-With-Two-Ns
Copy link
Copy Markdown
Contributor

@Quinn-With-Two-Ns Quinn-With-Two-Ns commented May 13, 2026

What was changed

Added a generic Nexus operation handler that consolidates the common pattern of "either return a synchronous
result or start a workflow as an async operation."

Why?

The existing WorkflowRun / SyncOperation split forces users to pick the operation shape up front, which is awkward when:

  • The start handler decides at runtime whether to respond sync or async.
  • The handler needs access to the Temporal client.
  • The user wants a custom cancel implementation (e.g. terminate instead of cancel).
  • Difficult to extend as we add new operations

The new TemporalOperation unifies these cases behind one API and makes the common path much shorter.

Checklist

  1. Closes

  2. How was this tested:

  1. Any docs updates needed?

Note

Medium Risk
Adds new Nexus operation handler and client APIs that affect workflow-start plumbing, token handling, and cancellation behavior; bugs could impact operation cancellation or link/callback propagation.

Overview
Introduces a new generic Temporal-backed Nexus operation handler (TemporalNexusOperationHandler) that lets a start function return either a synchronous value or an async operation token via TemporalOperationResult, and supports overridable cancel behavior for workflow-run tokens.

Adds a Nexus-aware client (ITemporalNexusClient/TemporalNexusClient) plus NexusWorkflowStartHelper to centralize workflow-start plumbing (task queue defaulting, conflict attach options, inbound/outbound links, completion callbacks, and token header injection).

Refactors NexusWorkflowRunHandle token handling to expose ParseToken (validates base64url/JSON/version while leaving token-type enforcement to callers) and updates WorkflowRunOperationContext to use the shared start helper. Expands tests to cover token encoding/parsing, TemporalOperationResult, and end-to-end worker behavior for the new handler (start-by-expression/name, sync results, links, conflict policy, and cancellation/overrides).

Reviewed by Cursor Bugbot for commit 40094ad. Bugbot is set up for automated code reviews on this repo. Configure here.

@Quinn-With-Two-Ns Quinn-With-Two-Ns changed the title Nexus generic handler Generic Temporal Nexus Operation Handler May 13, 2026
@Quinn-With-Two-Ns Quinn-With-Two-Ns marked this pull request as ready for review May 13, 2026 23:46
@Quinn-With-Two-Ns Quinn-With-Two-Ns requested a review from a team as a code owner May 13, 2026 23:46
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.

1 participant