Add request header annotation and resource-id fields (#728)

_**READ BEFORE MERGING:** All PRs require approval by both Server AND
SDK teams before merging! This is why the number of required approvals
is "2" and not "1"--two reviewers from the same team is NOT sufficient.
If your PR is not approved by someone in BOTH teams, it may be summarily
reverted._

<!-- Describe what has changed in this PR -->
Adding a proto annotation to be used for automatically propagating
message fields into headers. Will be accompanied by SDK changes to
generate code for doing so based on the annotations. See
temporalio/api-go#236 and
temporalio/sdk-go#2226 for example.

Also adds additional `resource-id` fields to a number of messages for
use in routing.

<!-- Tell your future self why have you made these changes -->
MCN support

<!-- Are there any breaking changes on binary or code level? -->
**Breaking changes**


<!-- If this breaks the Server, please provide the Server PR to merge
right after this PR was merged. -->
**Server PR**

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: 2 people

openapi/openapiv2.json

@@ -9902,6 +9902,10 @@
         "selector": {
           "$ref": "#/definitions/v1WorkerSelector",
           "description": "Defines which workers should receive this command.\nonly single worker is supported at this time."
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the worker grouping key."
         }
       }
     },
@@ -10015,6 +10019,10 @@
         "identity": {
           "type": "string",
           "title": "The identity of the worker/client"
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the workflow ID or activity ID for standalone activities."
         }
       }
     },
@@ -10032,6 +10040,10 @@
         "identity": {
           "type": "string",
           "title": "The identity of the worker/client"
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains \"workflow:workflow_id\" or \"activity:activity_id\" for standalone activities."
         }
       }
     },
@@ -10048,6 +10060,10 @@
             "type": "object",
             "$ref": "#/definitions/v1WorkerHeartbeat"
           }
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the worker grouping key."
         }
       }
     },
@@ -10238,6 +10254,10 @@
           "type": "string",
           "title": "The identity of the worker/client"
         },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the workflow ID or activity ID for standalone activities."
+        },
         "workerVersion": {
           "$ref": "#/definitions/v1WorkerVersionStamp",
           "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment_options` instead."
@@ -10270,6 +10290,10 @@
         "deploymentOptions": {
           "$ref": "#/definitions/v1WorkerDeploymentOptions",
           "description": "Worker deployment options that user has set in the worker."
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains \"workflow:workflow_id\" or \"activity:activity_id\" for standalone activities."
         }
       }
     },
@@ -10289,6 +10313,10 @@
           "type": "string",
           "title": "The identity of the worker/client"
         },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the workflow ID or activity ID for standalone activities."
+        },
         "workerVersion": {
           "$ref": "#/definitions/v1WorkerVersionStamp",
           "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment_options` instead."
@@ -10317,6 +10345,10 @@
         "identity": {
           "type": "string",
           "title": "The identity of the worker/client"
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains \"workflow:workflow_id\" or \"activity:activity_id\" for standalone activities."
         }
       }
     },
@@ -10336,6 +10368,10 @@
           "type": "string",
           "title": "The identity of the worker/client"
         },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the workflow ID or activity ID for standalone activities."
+        },
         "lastHeartbeatDetails": {
           "$ref": "#/definitions/v1Payloads",
           "title": "Additional details to be stored as last activity heartbeat"
@@ -10372,6 +10408,10 @@
         "lastHeartbeatDetails": {
           "$ref": "#/definitions/v1Payloads",
           "title": "Additional details to be stored as last activity heartbeat"
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains \"workflow:workflow_id\" or \"activity:activity_id\" for standalone activities."
         }
       }
     },
@@ -11233,6 +11273,10 @@
         "selector": {
           "$ref": "#/definitions/v1WorkerSelector",
           "description": "Defines which workers should receive this command."
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the worker grouping key."
         }
       }
     },

openapi/openapiv3.yaml

@@ -10548,6 +10548,9 @@ components:
           description: |-
             Defines which workers should receive this command.
              only single worker is supported at this time.
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains the worker grouping key.
     FetchWorkerConfigResponse:
       type: object
       properties:
@@ -12857,6 +12860,9 @@ components:
         identity:
           type: string
           description: The identity of the worker/client
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
     RecordActivityTaskHeartbeatByIdResponse:
       type: object
       properties:
@@ -12889,6 +12895,9 @@ components:
           description: The identity of the worker/client
         namespace:
           type: string
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
     RecordActivityTaskHeartbeatResponse:
       type: object
       properties:
@@ -12918,6 +12927,9 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/WorkerHeartbeat'
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains the worker grouping key.
     RecordWorkerHeartbeatResponse:
       type: object
       properties: {}
@@ -13429,6 +13441,9 @@ components:
           allOf:
             - $ref: '#/components/schemas/WorkerDeploymentOptions'
           description: Worker deployment options that user has set in the worker.
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
     RespondActivityTaskCanceledByIdResponse:
       type: object
       properties: {}
@@ -13448,6 +13463,9 @@ components:
           description: The identity of the worker/client
         namespace:
           type: string
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
         workerVersion:
           allOf:
             - $ref: '#/components/schemas/WorkerVersionStamp'
@@ -13494,6 +13512,9 @@ components:
         identity:
           type: string
           description: The identity of the worker/client
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
     RespondActivityTaskCompletedByIdResponse:
       type: object
       properties: {}
@@ -13513,6 +13534,9 @@ components:
           description: The identity of the worker/client
         namespace:
           type: string
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
         workerVersion:
           allOf:
             - $ref: '#/components/schemas/WorkerVersionStamp'
@@ -13563,6 +13587,9 @@ components:
           allOf:
             - $ref: '#/components/schemas/Payloads'
           description: Additional details to be stored as last activity heartbeat
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
     RespondActivityTaskFailedByIdResponse:
       type: object
       properties:
@@ -13589,6 +13616,9 @@ components:
           description: The identity of the worker/client
         namespace:
           type: string
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
         lastHeartbeatDetails:
           allOf:
             - $ref: '#/components/schemas/Payloads'
@@ -15912,6 +15942,9 @@ components:
           allOf:
             - $ref: '#/components/schemas/WorkerSelector'
           description: Defines which workers should receive this command.
+        resourceId:
+          type: string
+          description: Resource ID for routing. Contains the worker grouping key.
     UpdateWorkerConfigResponse:
       type: object
       properties:

temporal/api/protometa/v1/annotations.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package temporal.api.protometa.v1;
+
+option go_package = "go.temporal.io/api/protometa/v1;protometa";
+option java_package = "io.temporal.api.protometa.v1";
+option java_multiple_files = true;
+option java_outer_classname = "AnnotationsProto";
+option ruby_package = "Temporalio::Api::Protometa::V1";
+option csharp_namespace = "Temporalio.Api.Protometa.V1";
+
+import "google/protobuf/descriptor.proto";
+
+// RequestHeaderAnnotation allows specifying that field values from a request
+// should be propagated as outbound headers.
+//
+// The value field supports template interpolation where field paths enclosed
+// in braces will be replaced with the actual field values from the request.
+// For example:
+//   value: "{workflow_execution.workflow_id}"
+//   value: "workflow-{workflow_execution.workflow_id}"
+//   value: "{namespace}/{workflow_execution.workflow_id}"
+message RequestHeaderAnnotation {
+  // The name of the header to set (e.g., "temporal-resource-id")
+  string header = 1;
+
+  // A template string that may contain field paths in braces.
+  // Field paths use dot notation to traverse nested messages.
+  // Example: "{workflow_execution.workflow_id}"
+  string value = 2;
+}
+
+// Extension to add request-header annotations to RPC methods.
+// Multiple headers can be set by repeating this option.
+extend google.protobuf.MethodOptions {
+  repeated RequestHeaderAnnotation request_header = 7234001;
+}

temporal/api/workflowservice/v1/request_response.proto

@@ -358,6 +358,8 @@ message RespondWorkflowTaskCompletedRequest {
     // Responses to the `queries` field in the task being responded to
     map<string, temporal.api.query.v1.WorkflowQueryResult> query_results = 8;
     string namespace = 9;
+    // Resource ID for routing. Contains the workflow ID from the original task.
+    string resource_id = 18;
     // Version info of the worker who processed this task. This message's `build_id` field should
     // always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
     // field to true. See message docstrings for more.
@@ -419,6 +421,8 @@ message RespondWorkflowTaskFailedRequest {
     // Worker process' unique binary id
     string binary_checksum = 5 [deprecated = true];
     string namespace = 6;
+    // Resource ID for routing. Contains the workflow ID from the original task.
+    string resource_id = 11;
     // Protocol messages piggybacking on a WFT as a transport
     repeated temporal.api.protocol.v1.Message messages = 7;
     // Version info of the worker who processed this task. This message's `build_id` field should
@@ -523,6 +527,8 @@ message RecordActivityTaskHeartbeatRequest {
     // The identity of the worker/client
     string identity = 3;
     string namespace = 4;
+    // Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
+    string resource_id = 5;
 }
 
 message RecordActivityTaskHeartbeatResponse {
@@ -552,6 +558,8 @@ message RecordActivityTaskHeartbeatByIdRequest {
     temporal.api.common.v1.Payloads details = 5;
     // The identity of the worker/client
     string identity = 6;
+    // Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
+    string resource_id = 7;
 }
 
 message RecordActivityTaskHeartbeatByIdResponse {
@@ -575,6 +583,8 @@ message RespondActivityTaskCompletedRequest {
     // The identity of the worker/client
     string identity = 3;
     string namespace = 4;
+    // Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
+    string resource_id = 8;
     // Version info of the worker who processed this task. This message's `build_id` field should
     // always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
     // field to true. See message docstrings for more.
@@ -605,6 +615,8 @@ message RespondActivityTaskCompletedByIdRequest {
     temporal.api.common.v1.Payloads result = 5;
     // The identity of the worker/client
     string identity = 6;
+    // Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
+    string resource_id = 7;
 }
 
 message RespondActivityTaskCompletedByIdResponse {
@@ -618,6 +630,8 @@ message RespondActivityTaskFailedRequest {
     // The identity of the worker/client
     string identity = 3;
     string namespace = 4;
+    // Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
+    string resource_id = 9;
     // Additional details to be stored as last activity heartbeat
     temporal.api.common.v1.Payloads last_heartbeat_details = 5;
     // Version info of the worker who processed this task. This message's `build_id` field should
@@ -655,6 +669,8 @@ message RespondActivityTaskFailedByIdRequest {
     string identity = 6;
     // Additional details to be stored as last activity heartbeat
     temporal.api.common.v1.Payloads last_heartbeat_details = 7;
+    // Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
+    string resource_id = 8;
 }
 
 message RespondActivityTaskFailedByIdResponse {
@@ -671,6 +687,8 @@ message RespondActivityTaskCanceledRequest {
     // The identity of the worker/client
     string identity = 3;
     string namespace = 4;
+    // Resource ID for routing. Contains the workflow ID or activity ID for standalone activities.
+    string resource_id = 8;
     // Version info of the worker who processed this task. This message's `build_id` field should
     // always be set by SDKs. Workers opting into versioning will also set the `use_versioning`
     // field to true. See message docstrings for more.
@@ -703,6 +721,8 @@ message RespondActivityTaskCanceledByIdRequest {
     string identity = 6;
     // Worker deployment options that user has set in the worker.
     temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 7;
+    // Resource ID for routing. Contains "workflow:workflow_id" or "activity:activity_id" for standalone activities.
+    string resource_id = 8;
 }
 
 message RespondActivityTaskCanceledByIdResponse {
@@ -1916,6 +1936,9 @@ message ExecuteMultiOperationRequest {
     // Note that additional operation-specific restrictions have to be considered.
     repeated Operation operations = 2;
 
+    // Resource ID for routing. Should match operations[0].start_workflow.workflow_id
+    string resource_id = 3;
+
     message Operation {
         oneof operation {
             // Additional restrictions:
@@ -2550,6 +2573,9 @@ message RecordWorkerHeartbeatRequest {
     string identity = 2;
 
     repeated temporal.api.worker.v1.WorkerHeartbeat worker_heartbeat = 3;
+    
+    // Resource ID for routing. Contains the worker grouping key.
+    string resource_id = 4;
 }
 
 message RecordWorkerHeartbeatResponse {
@@ -2636,6 +2662,8 @@ message FetchWorkerConfigRequest {
     // Defines which workers should receive this command.
     // only single worker is supported at this time.
     temporal.api.common.v1.WorkerSelector selector = 6;
+    // Resource ID for routing. Contains the worker grouping key.
+    string resource_id = 7;
 }
 
 message FetchWorkerConfigResponse {
@@ -2662,6 +2690,8 @@ message UpdateWorkerConfigRequest {
 
     // Defines which workers should receive this command.
     temporal.api.common.v1.WorkerSelector selector = 6;
+    // Resource ID for routing. Contains the worker grouping key.
+    string resource_id = 7;
 }
 
 message UpdateWorkerConfigResponse {