Add Nexus worker service for server-to-worker commands by rkannan82 · Pull Request #708 · temporalio/api

rkannan82 · 2026-02-03T21:30:05Z

Summary

Defines a Nexus service for server-to-worker communication, starting with activity cancellation support.

Design Decision

We chose a generic command API (WorkerCommandsRequest with oneof command types) instead of a cancel-specific API. This allows a future optimization to batch multiple commands (cancel, pause, etc) in a single request and deliver to a worker in one RPC.

Files

temporal/api/nexusservices/workerservice/v1/request_response.proto - Message definitions
temporal/api/nexusservices/workerservice/v1/service.yaml - Nexus service definition

What other services defined in this repo? gRPC ones? To confirm, are we saying Nexus services have to somehow be consistent with gRPC services? Surely it's understood they are already not consistent because they are completely different protocols/contracts.

Nexus services should be consistent with Nexus services and if there are gaps in expected consistency as Nexus use grows, we remedy it, but it's not correct to pretend completely unrelated proto/gRPC's rules/approaches have any bearing on Nexus.

temporal/api/worker/v1/worker_service.nexusrpc.yaml

cretz · 2026-02-12T20:37:26Z

temporal/api/worker/v1/worker_service.nexusrpc.yaml

+          activities need to be cancelled (e.g., workflow cancellation or
+          explicit activity cancellation).
+        input:
+          $goRef: "go.temporal.io/api/worker/v1.CancelActivitiesRequest"


I think we should consider using JSON schema here and no protos (but if we must use protos, we should reference all languages)

Updated to have ref for all languages.

temporal/api/worker/v1/worker_service.nexusrpc.yaml

Change from CancelActivitiesRequest to WorkerCommandsRequest with repeated WorkerCommand using oneof type. This allows adding new command types without changing the Nexus operation. - Rename operation: cancel-activities -> execute-commands - Request: WorkerCommandsRequest with WorkerCommand.CancelActivity - Response: WorkerCommandsResponse with WorkerCommandResult.CancelActivityResult Made-with: Cursor

Made-with: Cursor

…e/v1 New package: temporal.api.nexusservices.workerservice.v1 Made-with: Cursor

Made-with: Cursor

- Rename operation: execute-commands -> executeCommands - Add refs for all languages: Go, Java, Python, TypeScript, .NET, Ruby Made-with: Cursor

Sushisource · 2026-02-27T23:06:41Z

temporal/api/nexusservices/workerservice/v1/request_response.proto

+
+// Response payload for the "executeCommands" Nexus operation.
+message WorkerCommandsResponse {
+    repeated WorkerCommandResult results = 1;


We should document the expectation (at least, what I assume is the expectation... hence the need for a docstrings) that this results list must be 1:1 with the request list, of the same size and order.

bergundy · 2026-02-27T23:00:00Z

temporal/api/nexusservices/workerservice/v1/service.yaml

+      Internal Nexus service for server-to-worker communication.
+      Used by the Temporal server to send commands to workers.
+    operations:
+      executeCommands:


Suggested change

executeCommands:

ExecuteCommands:

bergundy · 2026-02-27T23:03:19Z

temporal/api/nexusservices/workerservice/v1/request_response.proto

+message WorkerCommandsRequest {
+    repeated WorkerCommand commands = 1;
+
+    message WorkerCommand {


I would pull this out to a top level message and put it in temporal.api.worker.v1 to make it easier to use and available in other contexts, traditionally we have only put requests and responses in request_response.proto files.

bergundy · 2026-02-27T23:03:50Z

temporal/api/nexusservices/workerservice/v1/request_response.proto

+        }
+    }
+
+    message CancelActivity {


Same, make this a top level temporal.api.worker.v1.CancelActivityCommand.

bergundy · 2026-02-27T23:04:00Z

temporal/api/nexusservices/workerservice/v1/request_response.proto

+message WorkerCommandsResponse {
+    repeated WorkerCommandResult results = 1;
+
+    message WorkerCommandResult {


bergundy · 2026-02-27T23:09:53Z

temporal/api/nexusservices/workerservice/v1/request_response.proto

+
+    message WorkerCommandResult {
+        oneof type {
+            CancelActivity cancel_activity = 1;


temporal.api.worker.v1.CancelActivityResult

bergundy · 2026-02-27T23:10:42Z

temporal/api/nexusservices/workerservice/v1/request_response.proto

+// --)
+
+// Request payload for the "executeCommands" Nexus operation.
+message WorkerCommandsRequest {


If the API is called ExecuteCommands, the request and response should be named accordingly.

Suggested change

message WorkerCommandsRequest {

message ExecuteCommandsRequest {

rkannan82 requested review from a team as code owners February 3, 2026 21:30

rkannan82 requested review from ShahabT, Sushisource and yuandrew February 3, 2026 21:33

rkannan82 force-pushed the kannan/activity-cancel branch 3 times, most recently from 4b2e0d1 to 54edb8e Compare February 3, 2026 21:42

cretz reviewed Feb 3, 2026

View reviewed changes

rkannan82 force-pushed the kannan/activity-cancel branch 2 times, most recently from afb40a2 to b920471 Compare February 4, 2026 05:43

rkannan82 changed the title ~~Add API to send control tasks from server to worker~~ Add Nexus request and response payloads to cancel activities Feb 4, 2026

rkannan82 requested a review from cretz February 4, 2026 05:50

rkannan82 force-pushed the kannan/activity-cancel branch from b920471 to 84c0bac Compare February 4, 2026 05:51

rkannan82 marked this pull request as draft February 4, 2026 05:55

rkannan82 removed the request for review from ShahabT February 5, 2026 18:05

cretz reviewed Feb 9, 2026

View reviewed changes

temporal/api/worker/v1/worker_nexus_service_commands.proto Outdated Show resolved Hide resolved

temporal/api/worker/v1/worker_nexus_service_commands.proto Outdated Show resolved Hide resolved

temporal/api/nexusservices/workerservice/v1/request_response.proto Show resolved Hide resolved

rkannan82 mentioned this pull request Feb 11, 2026

Add attributes needed by server to propagate nexus tasks to worker #711

Open

rkannan82 force-pushed the kannan/activity-cancel branch from 84c0bac to 28ea1dd Compare February 11, 2026 21:20

rkannan82 changed the base branch from master to kannan/add-worker-instance-key-to-wft-complete February 11, 2026 21:23

rkannan82 requested review from bergundy and cretz February 12, 2026 18:56

rkannan82 marked this pull request as ready for review February 12, 2026 19:39

rkannan82 force-pushed the kannan/activity-cancel branch from 7d3bfb7 to e0d0049 Compare February 12, 2026 19:43

rkannan82 force-pushed the kannan/add-worker-instance-key-to-wft-complete branch from 61952c9 to 98350a9 Compare February 12, 2026 19:46

rkannan82 added 5 commits February 12, 2026 11:47

Add worker control task protos for activity cancellation

22ab5e7

Add WorkerControlTasks, WorkerControlTask, and CancelActivityTask to worker/v1/message.proto for pushing control messages to workers via Nexus control queue.

Rename proto and Nexus service name

1643b18

Add Nexus service definition for worker commands

c5a0a89

Adds a nexusrpc.yaml file defining the temporal.api.worker.v1.WorkerService for server-to-worker communication via Nexus. Uses $goRef to reference proto-generated types.

Simplify proto comments, reference YAML for service definition

6f53c22

Move task queue format to YAML, keep proto minimal

6c21af4

rkannan82 force-pushed the kannan/activity-cancel branch from e0d0049 to 6c21af4 Compare February 12, 2026 19:47

bergundy approved these changes Feb 12, 2026

View reviewed changes

cretz reviewed Feb 12, 2026

View reviewed changes

yuandrew reviewed Feb 17, 2026

View reviewed changes

temporal/api/worker/v1/worker_service.nexusrpc.yaml Show resolved Hide resolved

rkannan82 force-pushed the kannan/activity-cancel branch 2 times, most recently from 37ffb33 to 6c21af4 Compare February 27, 2026 22:19

rkannan82 added 7 commits February 27, 2026 14:21

Use symmetric CancelActivity naming in request and response

5074e8a

Made-with: Cursor

Move worker service protos to temporal/api/nexusservices/workerservic…

f06f149

…e/v1 New package: temporal.api.nexusservices.workerservice.v1 Made-with: Cursor

Simplify execute-commands operation description

09ee5c4

Made-with: Cursor

Rename proto file to request_response.proto

ab6c53b

Made-with: Cursor

Rename YAML file to service.yaml

106652b

Made-with: Cursor

Use camelCase operation name and add multi-language refs

9f19af6

- Rename operation: execute-commands -> executeCommands - Add refs for all languages: Go, Java, Python, TypeScript, .NET, Ruby Made-with: Cursor

rkannan82 changed the title ~~Add Nexus request and response payloads to cancel activities~~ Add Nexus worker service for server-to-worker commands Feb 27, 2026

rkannan82 requested a review from bergundy February 27, 2026 22:56

Add documentation

32523fb

Sushisource reviewed Feb 27, 2026

View reviewed changes

rkannan82 requested review from Sushisource and yuandrew February 27, 2026 23:06

bergundy reviewed Feb 27, 2026

View reviewed changes

               }
+              // Container for batching multiple control tasks delivered to a worker in one Nexus operation.
+              message WorkerControlTasks {

+              nexusrpc: 1.0.0
+              services:
+                temporal.api.worker.v1.WorkerService:

	message WorkerCommandsRequest {
	message ExecuteCommandsRequest {

Conversation

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

Uh oh!

Summary

Design Decision

Files

Related

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rkannan82 Feb 6, 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!

cretz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bergundy left a comment

Choose a reason for hiding this comment

Uh oh!

cretz 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!

cretz Feb 19, 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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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

Uh oh!

5 participants

rkannan82 commented Feb 3, 2026 •

edited

Loading

rkannan82 Feb 6, 2026 •

edited

Loading

cretz Feb 19, 2026 •

edited

Loading