move payloads to the separate file, add conventions

Author: ychebotarev

api-linter.yaml

@@ -12,6 +12,11 @@
   disabled_rules:
     - "core::0123::resource-annotation" # We don't require resource annotations on all messages -- https://linter.aip.dev/123/resource-annotation
 
+- included_paths:
+    - "**/worker/v1/worker_nexus_service_commands.proto"
+  disabled_rules:
+    - "core::0134::request-unknown-fields" # Same rationale as `core::0131::request-unknown-fields`, but for Update RPCs -- https://linter.aip.dev/134/request-unknown-fields
+
 - included_paths:
     - "**/workflowservice/v1/request_response.proto"
     - "**/operatorservice/v1/request_response.proto"

temporal/api/worker/v1/message.proto

@@ -11,11 +11,9 @@ option csharp_namespace = "Temporalio.Api.Worker.V1";
 
 import "google/protobuf/duration.proto";
 import "google/protobuf/timestamp.proto";
-import "google/protobuf/field_mask.proto";
 
 import "temporal/api/deployment/v1/message.proto";
 import "temporal/api/enums/v1/common.proto";
-import "temporal/api/sdk/v1/worker_config.proto";
 
 message WorkerPollerInfo {
   // Number of polling RPCs that are currently in flight.
@@ -145,21 +143,3 @@ message PluginInfo {
     // The version of the plugin, may be empty.
     string version = 2;
 }
-
-// Will be send to the worker as a payload of the FetchWorkerConfig command.
-message FetchWorkerConfigCommandPayload {
-  // Worker identifier, should be unique for the namespace.
-  string worker_instance_key = 1;
-}
-
-// Will be send to the worker as a payload of the UpdateWorkerConfig command.
-message UpdateWorkerConfigCommandPayload {
-  // Worker identifier, should be unique for the namespace.
-  repeated string worker_instance_key = 1;
-
-  // The new worker config to be applied.
-  temporal.api.sdk.v1.WorkerConfig worker_config = 2;
-
-  // Controls which fields from `worker_config` will be applied
-  google.protobuf.FieldMask update_mask = 3;
-}

temporal/api/worker/v1/worker_nexus_service_commands.proto

@@ -0,0 +1,73 @@
+syntax = "proto3";
+
+package temporal.api.worker.v1;
+
+option go_package = "go.temporal.io/api/worker/v1;worker";
+option java_package = "io.temporal.api.worker.v1";
+option java_multiple_files = true;
+option java_outer_classname = "WorkerNexusServiceCommandsProto";
+option ruby_package = "Temporalio::Api::Worker::V1";
+option csharp_namespace = "Temporalio.Api.Worker.V1";
+
+import "google/protobuf/field_mask.proto";
+import "temporal/api/sdk/v1/worker_config.proto";
+
+// (--
+/////////////////////////////////////////////////////////////////////
+// This file contains:
+// - Conventions between server and worker.
+// - Definitions for commands and payloads for server-worker communication via Nexus
+//
+// WORKER COMMANDS AND CONVENTIONS:
+//
+// Worker commands are used to manage worker configurations, operations, etc.
+// Command names should match names defined in the server API.
+// Currently supported commands:
+// - FetchWorkerConfig
+// - UpdateWorkerConfig.
+//
+// Command names are provided in StartOperationRequest.Operation field.
+//
+// PAYLOAD CONVENTIONS:
+//
+// In/out payloads namings follow the same convention as the regular API:
+// - CommandNameRequest (input payload)
+// - CommandNameResponse (output payload).
+// - Empty payload if response is not needed/not expected
+//
+// COMMUNICATION PROTOCOL:
+// - Transport: Nexus messages on dedicated channel
+// - Server identifier: "sys-worker-service"
+// - Task queue: "temporal-sys/worker-tq/{namespace_name}/{process_key}"
+// --)
+
+// Will be send to the worker as a payload of the FetchWorkerConfig command.
+message FetchWorkerConfigRequest {
+  // List of worker identifiers. For now only a single worker instance key is supported.
+  repeated string worker_instance_key = 1;
+}
+
+message FetchWorkerConfigResponse {
+  message WorkerConfigEntry {
+    // Worker instance key the config is for.
+    string worker_instance_key = 1;
+
+    temporal.api.sdk.v1.WorkerConfig worker_config = 2;
+  }
+  repeated WorkerConfigEntry worker_configs = 1;
+}
+
+// Will be send to the worker as a payload of the UpdateWorkerConfig command.
+message UpdateWorkerConfigRequest {
+  // List of worker identifiers.
+  repeated string worker_instance_key = 1;
+
+  // The new worker config to be applied.
+  temporal.api.sdk.v1.WorkerConfig worker_config = 2;
+
+  // Controls which fields from `worker_config` will be applied
+  google.protobuf.FieldMask update_mask = 3;
+}
+
+message UpdateWorkerConfigResponse {
+}