Skip to content

Add Nexus worker service for server-to-worker commands #708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rkannan82 wants to merge 14 commits into
base: kannan/add-worker-instance-key-to-wft-complete
Choose a base branch
from
Open

Add Nexus worker service for server-to-worker commands #708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
22ab5e7
Add worker control task protos for activity cancellation
rkannan82 Jan 14, 2026
e9d56b9
Refactor worker control protos: separate file and use task tokens
rkannan82 Feb 4, 2026
1643b18
Rename proto and Nexus service name
rkannan82 Feb 12, 2026
c5a0a89
Add Nexus service definition for worker commands
rkannan82 Feb 12, 2026
6f53c22
Simplify proto comments, reference YAML for service definition
rkannan82 Feb 12, 2026
6c21af4
Move task queue format to YAML, keep proto minimal
rkannan82 Feb 12, 2026
8506d65
Use WorkerCommandsRequest with oneof for extensibility
rkannan82 Feb 27, 2026
5074e8a
Use symmetric CancelActivity naming in request and response
rkannan82 Feb 27, 2026
f06f149
Move worker service protos to temporal/api/nexusservices/workerservic…
rkannan82 Feb 27, 2026
09ee5c4
Simplify execute-commands operation description
rkannan82 Feb 27, 2026
ab6c53b
Rename proto file to request_response.proto
rkannan82 Feb 27, 2026
106652b
Rename YAML file to service.yaml
rkannan82 Feb 27, 2026
9f19af6
Use camelCase operation name and add multi-language refs
rkannan82 Feb 27, 2026
32523fb
Add documentation
rkannan82 Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions temporal/api/nexusservices/workerservice/v1/request_response.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
syntax = "proto3";

package temporal.api.nexusservices.workerservice.v1;

option go_package = "go.temporal.io/api/nexusservices/workerservice/v1;workerservice";
option java_package = "io.temporal.api.nexusservices.workerservice.v1";
option java_multiple_files = true;
option java_outer_classname = "RequestResponseProto";
option ruby_package = "Temporalio::Api::Nexusservices::Workerservice::V1";
option csharp_namespace = "Temporalio.Api.Nexusservices.Workerservice.V1";

// (--
// Internal Nexus service for server-to-worker communication.
// See service.yaml for the service definition.
// --)

// Request payload for the "executeCommands" Nexus operation.
message WorkerCommandsRequest {
Copy link
Member

@bergundy bergundy Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Suggested change
message WorkerCommandsRequest {
message ExecuteCommandsRequest {

repeated WorkerCommand commands = 1;

message WorkerCommand {
Copy link
Member

@bergundy bergundy Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@yuandrew yuandrew Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But since this is a new nexus service, shouldn't this be decoupled from the existing gRPC temporal.api.worker.v1 protos and exist in the separate temporal/api/nexusservices? Maybe temporal.api.nexusservices.worker.v1?

Do we know what other contexts we might want to use this message, or is that hypothetical?

oneof type {
CancelActivity cancel_activity = 1;
}
}

// Cancel an activity if it is still running. Otherwise, do nothing.
message CancelActivity {
Copy link
Member

@bergundy bergundy Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

bytes task_token = 1;
}
}

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

@Sushisource Sushisource Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


message WorkerCommandResult {
Copy link
Member

@bergundy bergundy Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here.

oneof type {
CancelActivity cancel_activity = 1;
Copy link
Member

@bergundy bergundy Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

temporal.api.worker.v1.CancelActivityResult

}
}

// Treat both successful cancellation and no-op (activity is no longer running) as success.
message CancelActivity {
}
}
32 changes: 32 additions & 0 deletions temporal/api/nexusservices/workerservice/v1/service.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# yaml-language-server: $schema=https://raw.githubusercontent.com/nexus-rpc/nexus-rpc-gen/main/schemas/nexus-rpc-gen.json
#
# Nexus service definition for server-to-worker communication.
# See request_response.proto for message definitions.
#
# Task queue format: /temporal-sys/worker-commands/{namespace}/{worker_grouping_key}

nexusrpc: 1.0.0

services:
temporal.api.nexusservices.workerservice.v1.WorkerService:
description: >
Internal Nexus service for server-to-worker communication.
Used by the Temporal server to send commands to workers.
operations:
executeCommands:
Copy link
Member

@bergundy bergundy Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
executeCommands:
ExecuteCommands:

description: Executes worker commands sent by the server.
input:
$goRef: "go.temporal.io/api/nexusservices/workerservice/v1.WorkerCommandsRequest"
$javaRef: "io.temporal.api.nexusservices.workerservice.v1.WorkerCommandsRequest"
$pythonRef: "temporalio.api.nexusservices.workerservice.v1.WorkerCommandsRequest"
$typescriptRef: "@temporalio/api/nexusservices/workerservice/v1.WorkerCommandsRequest"
$dotnetRef: "Temporalio.Api.Nexusservices.Workerservice.V1.WorkerCommandsRequest"
$rubyRef: "Temporalio::Api::Nexusservices::Workerservice::V1::WorkerCommandsRequest"
output:
$goRef: "go.temporal.io/api/nexusservices/workerservice/v1.WorkerCommandsResponse"
$javaRef: "io.temporal.api.nexusservices.workerservice.v1.WorkerCommandsResponse"
$pythonRef: "temporalio.api.nexusservices.workerservice.v1.WorkerCommandsResponse"
$typescriptRef: "@temporalio/api/nexusservices/workerservice/v1.WorkerCommandsResponse"
$dotnetRef: "Temporalio.Api.Nexusservices.Workerservice.V1.WorkerCommandsResponse"
$rubyRef: "Temporalio::Api::Nexusservices::Workerservice::V1::WorkerCommandsResponse"

Loading