Standalone Nexus Operations by bergundy · Pull Request #685 · temporalio/api

bergundy · 2025-12-09T00:52:33Z

What changed?

Added the full API scope for standalone nexus operations.

Server PR

pdoerner · 2025-12-09T17:39:29Z

+
+    // The number of attempts made to start/deliver the operation request.
+    // This number represents a minimum bound since the attempt is incremented after the request completes.
+    int32 attempt = 9;


This is attempt to deliver the start request. Will we support overall operation retry in the future? Will this name be confusing if we do? Maybe we should call it start_attempt so that people will not confuse it with activity attempt which has a different meaning.

I want to keep this for consistency with PendingNexusOperationInfo.

pdoerner · 2025-12-09T17:40:41Z

+    string request_id = 19;
+
+    // Operation token. Only set for asynchronous operations after a successful StartOperation call.
+    string operation_token = 20;


I thought we said we didn't want to expose this to callers? They should only have one way of referencing their operations: their caller-side operation ID.

It's still worth exposing this information as we do for workflow callers.

I have no horse in this race, but I'm curious, why is it useful to have?

It's useful for debugging and can be used in the direct Nexus APIs to reattach to the same operation (future capability).

pdoerner · 2025-12-09T17:44:31Z

+    // The run ID of the operation, useful when run_id was not specified in the request.
+    string run_id = 1;
+
+    // Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked.


I'm confused, is this the stage the original request sent? Or does it represent the current stage of the operation?

The current stage. Let me fix the docstring.

cretz · 2025-12-09T20:59:49Z

+    // Updated on terminal status.
+    int64 state_transition_count = 10;
+    // Updated once on scheduled and once on terminal status.
+    int64 state_size_bytes = 11;


Is this intentionally a field only present in list? It was mentioned for standalone activities that everything in list was expected to be in describe.

Also, for standalone activities it was mentioned there would be a tool that would make sure everything in list was also in describe result. Can we prioritize that? It's a lot of effort for me to have to continually confirm our assertion on every PR and find these issues since we chose not to reuse types.

Just want to call this out that we don't have this guarantee for schedules or batch which are much older archetypes: https://github.com/temporalio/api/blob/master/temporal/api/schedule/v1/message.proto https://github.com/temporalio/api/blob/master/temporal/api/workflowservice/v1/request_response.proto#L1715-L1751.

I don't think this guarantee needs to be high priority but we should keep track of it because I do think that it is nice to have. Ideally the SDKs would allow the types to have completely different fields, there's no need to reuse the models here.

Right, but this guarantee/promise was made as part of not reusing models knowing the SDK will need this guarantee. Was not expecting a "nice to have" guarantee when the promise/guarantee was made.

Let's take this offline.

Discussed offline, we will write a tool soon.

Quinn-With-Two-Ns · 2026-01-21T19:10:42Z

 // Response to a successful UnpauseWorkflowExecution request.
 message UnpauseWorkflowExecutionResponse { }
+
+message StartNexusOperationRequest {


Is it intentional we don't have Priority support?

Yes, priorities only apply to durable matching queues, those are not used for nexus tasks.

# Conflicts: # openapi/openapiv2.json # openapi/openapiv3.yaml # temporal/api/errordetails/v1/message.proto # temporal/api/nexus/v1/message.proto # temporal/api/workflowservice/v1/request_response.proto # temporal/api/workflowservice/v1/service.proto

Co-Authored-By: Claude Opus 4.6 <[email protected]>

stephanos · 2026-02-25T01:45:21Z

+    string blocked_reason = 7;
+
+    // A reason that may be specified in the CancelNexusOpertionRequest.
+    string reason = 8;


This was set to 24 and I changed it; I don't see why it should be 24.

(I wonder why we don't have a linter for this?)

Copy pasta probably. Thanks for catching this.

stephanos · 2026-02-25T19:53:26Z


-    // How long this operation has been running for, including all attempts and backoff between attempts.
+    // Elapsed time from schedule_time to now for running operations or to close_time for closed
+    // operations, including all attempts and backoff between attempts.


Clarifies it works for running operations (as opposed to NexusOperationListInfo); correct me if that's wrong.

This reverts commit d90a320.

… comment Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Restores the Execution suffix on all Nexus operation types except Link.NexusOperation in common/v1/message.proto. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Remove state_size_bytes field and renumber execution_duration. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

…ndalone-poll

…dalone-nexus-op

# Conflicts: # openapi/openapiv2.json # openapi/openapiv3.yaml # temporal/api/common/v1/message.proto

Quinn-With-Two-Ns · 2026-04-16T18:08:38Z

+    // This is the only timeout settable for a Nexus operation.
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    google.protobuf.Duration schedule_to_close_timeout = 8;


What the other timeouts like schedule to start and start to close

Those should be added.

Will they be in this PR or later?

I'll add it now: 1d12d58

…-nexus-op-work # Conflicts: # openapi/openapiv2.json

Sushisource · 2026-04-21T21:27:52Z

+    NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL = 1;
+    // Don't start a new operation; instead return a handle for the running operation.
+    NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING = 2;
+}


We don't support terminate like w/ workflows?

cc @bergundy

I'll add that I don't have context for why it's not there; but it seems like something we can always add later if we want to.

We don't support TERMINATE_IF_RUNNING for anything that isn't workflow.

Sushisource · 2026-04-21T21:34:44Z

+    bool include_input = 4;
+    // Include the outcome (result/failure) in the response if the operation has completed.
+    bool include_outcome = 5;
+    // Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation


Suggested change

// Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation

// Token from a previous DescribeNexusOperationExecutionResponse. If present, this RPC will long-poll until operation

Took me a minute to understand what this was trying to say w/o this clarification.

Also does this mean in order to long poll on complete you must make a minimum of two RPCs? One to get the token and one to wait on it? If so what's the use case for the long poll token here instead of just using PollNexusOperationExecutionRequest?

Polling on DescribeNexusOperationExecution is for the UI. So the UI will describe once to render the page and then long poll so any update can be reflected in the UI.

fwiw, DescribeActivityExecutionRequest follows the same approach.

Also a noteable difference is, like Quinn alludes to, the Describe returns NexusOperationExecutionInfo which Poll doesn't.

bergundy · 2026-04-16T19:04:48Z

+    // - OperationId
+    // - RunId
+    // - Endpoint
+    // - Service
+    // - Operation
+    // - RequestId
+    // - StartTime
+    // - ExecutionTime
+    // - CloseTime
+    // - ExecutionStatus
+    // - ExecutionDuration
+    // - StateTransitionCount


@stephanos can you double check this against the implementation please?

All but RequestId are supported; fixing that up now: temporalio/temporal#10032

bergundy · 2026-04-22T17:07:59Z

+    NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL = 1;
+    // Don't start a new operation; instead return a handle for the running operation.
+    NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING = 2;
+}


We don't support TERMINATE_IF_RUNNING for anything that isn't workflow.

bergundy · 2026-04-22T17:10:52Z

+    // The number of attempts made to start/deliver the operation request.
+    // This number represents a minimum bound since the attempt is incremented after the request completes.


Suggested change

// The number of attempts made to start/deliver the operation request.

// This number represents a minimum bound since the attempt is incremented after the request completes.

// The number of attempts made to deliver the start operation request.

// This number is approximate, it is incremented when a task is added to the history queue.

// In practice, there could be more attempts if a task is executed but fails to commit, or less attempts if a task was

// never executed.

@stephanos please also update this comment for PendingNexusOperationInfo in workflow/v1/message.go.

Updated in 734ce9d

Standalone Nexus Operations

6724dab

bergundy requested review from a team as code owners December 9, 2025 00:52

bergundy marked this pull request as draft December 9, 2025 00:52

bergundy mentioned this pull request Dec 9, 2025

[DO NOT MERGE] Add initial WorkflowService API definitions for durable non-workflow Nexus calls #659

Closed

pdoerner reviewed Dec 9, 2025

View reviewed changes

cretz reviewed Dec 9, 2025

View reviewed changes

Quinn-With-Two-Ns reviewed Jan 21, 2026

View reviewed changes

bergundy mentioned this pull request Feb 13, 2026

[NO NOT MERGE] Direct Nexus calls #720

Open

stephanos and others added 9 commits February 23, 2026 12:35

Regenerate OpenAPI docs after merge conflict resolution

6e7c81c

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Fix buf.lock: restore grpc-gateway dependency from master

0b8ceb6

Co-Authored-By: Claude Opus 4.6 <[email protected]>

operation_id comment

7fa3ce5

request_id comment

44adc50

wait_stage comment

af1af0e

add DeleteNexusOperationRequest

b0a71e4

regen

50e415e

fix reason field number

9b1baed

stephanos reviewed Feb 25, 2026

View reviewed changes

stephanos added 7 commits February 24, 2026 17:45

fix typo

d1c5a6c

missing word

3cbc3bc

remove word

f494689

fix enum name comment

4f7081a

group messages by feature

afe9ec5

trailing dot

1e570f8

move comment to where it matters

d99cea3

stephanos force-pushed the standalone-nexus-op branch from 092ad00 to d99cea3 Compare February 25, 2026 19:47

stephanos added 2 commits February 25, 2026 11:48

request_id details

31047d7

clarify

a1bac0c

stephanos reviewed Feb 25, 2026

View reviewed changes

Merge remote-tracking branch 'origin/master' into standalone-nexus-op

341d429

stephanos mentioned this pull request Mar 11, 2026

Standalone Nexus Operations API temporalio/temporal#9458

Merged

5 tasks

stephanos and others added 8 commits March 11, 2026 16:12

Revert "Remove Execution suffix from Nexus operation API names"

93424d7

This reverts commit d90a320.

Rename NexusOperationExecution link to NexusOperation and fix timeout…

0011d23

… comment Co-Authored-By: Claude Opus 4.6 <[email protected]>

Regenerate OpenAPI spec after revert

63ec6a1

Co-Authored-By: Claude Opus 4.6 <[email protected]>

add identity to NexusOperationInfo

6003f4a

Revert "Remove Execution suffix from Nexus operation API names"

a795eb3

Restores the Execution suffix on all Nexus operation types except Link.NexusOperation in common/v1/message.proto. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Merge origin/master into standalone-nexus-op

6ae9b43

Merge bergundy/standalone-nexus-op into master

1af999c

Drop state_size_bytes from NexusOperationInfo

b314585

Remove state_size_bytes field and renumber execution_duration. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

stephanos force-pushed the standalone-nexus-op branch from 3b976ca to b314585 Compare March 20, 2026 21:40

stephanos added 6 commits April 2, 2026 08:36

Merge remote-tracking branch 'origin/master' into stephanos/nexus-sta…

5bec9d3

…ndalone-poll

Merge remote-tracking branch 'upstream/standalone-nexus-op' into stan…

c13ec32

…dalone-nexus-op

Regenerate OpenAPI docs

57db182

Merge remote-tracking branch 'origin/master' into standalone-nexus-op

57248b1

Merge remote-tracking branch 'origin/master' into standalone-nexus-op

eb533ff

Merge remote-tracking branch 'origin/master' into standalone-nexus-op

c9fab7a

# Conflicts: # openapi/openapiv2.json # openapi/openapiv3.yaml # temporal/api/common/v1/message.proto

VegetarianOrc mentioned this pull request Apr 16, 2026

Add NexusOperationExecutionAlreadyStarted serviceerror temporalio/api-go#250

Draft

stephanos marked this pull request as ready for review April 16, 2026 18:08

Quinn-With-Two-Ns reviewed Apr 16, 2026

View reviewed changes

Quinn-With-Two-Ns approved these changes Apr 17, 2026

View reviewed changes

stephanos changed the title ~~[DO NOT MERGE] Standalone Nexus Operations~~ Standalone Nexus Operations Apr 21, 2026

stephanos added 2 commits April 21, 2026 11:58

add timeouts

1d12d58

Merge remote-tracking branch 'origin/master' into bergundy-standalone…

c08ebbb

…-nexus-op-work # Conflicts: # openapi/openapiv2.json

Sushisource reviewed Apr 21, 2026

View reviewed changes

stephanos added 2 commits April 21, 2026 19:25

Merge remote-tracking branch 'upstream/master' into standalone-nexus-op

93ccdb2

Clarify Nexus long-poll token comment

6206c0c

bergundy commented Apr 22, 2026

View reviewed changes

update attempt comment

734ce9d

Sushisource approved these changes Apr 22, 2026

View reviewed changes

	// Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation
	// Token from a previous DescribeNexusOperationExecutionResponse. If present, this RPC will long-poll until operation

		// The number of attempts made to start/deliver the operation request.
		// This number represents a minimum bound since the attempt is incremented after the request completes.

-    // The number of attempts made to start/deliver the operation request.
-    // This number represents a minimum bound since the attempt is incremented after the request completes.
+  // The number of attempts made to deliver the start operation request.
+  // This number is approximate, it is incremented when a task is added to the history queue.
+  // In practice, there could be more attempts if a task is executed but fails to commit, or less attempts if a task was
+  // never executed.

Conversation

bergundy commented Dec 9, 2025 • edited by stephanos Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephanos Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cretz Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephanos Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephanos Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

bergundy commented Dec 9, 2025 •

edited by stephanos

Loading

stephanos Feb 25, 2026 •

edited

Loading

cretz Dec 9, 2025 •

edited

Loading

stephanos Apr 21, 2026 •

edited

Loading

stephanos Apr 21, 2026 •

edited

Loading

stephanos Apr 22, 2026 •

edited

Loading