[DO NOT MERGE] 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

Not implemented yet, which is why this PR is still in draft.

temporal/api/workflowservice/v1/request_response.proto

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

temporal/api/nexus/v1/message.proto

+
+    // 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

temporal/api/nexus/v1/message.proto

+    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).

temporal/api/workflowservice/v1/request_response.proto

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

temporal/api/workflowservice/v1/request_response.proto

+    // 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.

temporal/api/workflowservice/v1/service.proto

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

temporal/api/nexus/v1/message.proto

+    // 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

temporal/api/workflowservice/v1/request_response.proto

 // 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 <noreply@anthropic.com>

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

temporal/api/nexus/v1/message.proto

+    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

temporal/api/nexus/v1/message.proto


-    // 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.

stephanos · 2026-02-25T19:54:46Z

temporal/api/enums/v1/nexus.proto


 // Status of a standalone Nexus operation.
-// The status is updated once, when the operation is originally scheduled, and again when the operation reaches a
-// terminal status.


Moved this to NexusOperationListInfo where it seems to be applicable; and only there?

It's applicable here too.

Oh, I see so UNSPECIFIED -> RUNNING -> [terminal state].

bergundy

@stephanos added a few more comments but this is almost good to merge AFAIC.

bergundy · 2026-02-27T01:15:03Z

temporal/api/common/v1/message.proto

    }

+    // A link to a standalone Nexus operation execution.
+    message NexusOperationExecution {


Looks like the naming is inconsistent with BatchJob and WorkflowEvent. Neither of those use the term Execution. I'm on the fence whether this is acceptable or not.

bergundy · 2026-02-27T01:16:39Z

temporal/api/enums/v1/nexus.proto

+    NEXUS_OPERATION_EXECUTION_STATUS_CANCELED = 4;
+    // The operation was terminated. Termination happens immediately without notifying the handler.
+    NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED = 5;
+    // The operation has timed out by reaching the specified schedule-to-close timeout.


This could be any timeout now that we've added start-to-close and schedule-to-close.

bergundy · 2026-02-27T01:18:27Z

temporal/api/enums/v1/nexus.proto

+    // Requesting to cancel an operation does not automatically transition the operation to canceled status, depending
+    // on the current operation status and the cancelation type used.
+    NEXUS_OPERATION_EXECUTION_STATUS_CANCELED = 4;
+    // The operation was terminated. Termination happens immediately without notifying the handler.


Note to future us: This comment may not be true if we add a Nexus equivalent of a "parent close policy".

bergundy · 2026-02-27T01:19:56Z

temporal/api/nexus/v1/message.proto

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


Copy pasta probably. Thanks for catching this.

bergundy · 2026-02-27T01:20:53Z

temporal/api/nexus/v1/message.proto

+    // 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;


Might as well add start_to_close_timeout and schedule_to_start_timeout already. Those are already supported by the server for workflow ops.

bergundy · 2026-02-27T01:21:38Z

temporal/api/nexus/v1/message.proto


-    // 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.


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 <noreply@anthropic.com>

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

0b8ceb6

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

stephanos added 3 commits February 25, 2026 12:01

gen

6b6a666

add Execution

c706e34

consistent comment

1077802

bergundy commented Feb 27, 2026

View reviewed changes

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!

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!

bergundy left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

bergundy commented Dec 9, 2025 •

edited by stephanos

Loading

stephanos Feb 25, 2026 •

edited

Loading

cretz Dec 9, 2025 •

edited

Loading

stephanos Feb 25, 2026 •

edited

Loading