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: tconley1428

openapi/openapiv2.json

@@ -9183,6 +9183,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."
         }
       }
     },
@@ -9296,6 +9300,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."
         }
       }
     },
@@ -9313,6 +9321,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."
         }
       }
     },
@@ -9329,6 +9341,10 @@
             "type": "object",
             "$ref": "#/definitions/v1WorkerHeartbeat"
           }
+        },
+        "resourceId": {
+          "type": "string",
+          "description": "Resource ID for routing. Contains the worker grouping key."
         }
       }
     },
@@ -9498,6 +9514,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."
@@ -9530,6 +9550,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."
         }
       }
     },
@@ -9549,6 +9573,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."
@@ -9577,6 +9605,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."
         }
       }
     },
@@ -9596,6 +9628,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"
@@ -9632,6 +9668,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."
         }
       }
     },
@@ -10416,6 +10456,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

@@ -9851,6 +9851,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:
@@ -11919,6 +11922,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:
@@ -11951,6 +11957,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:
@@ -11980,6 +11989,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: {}
@@ -12469,6 +12481,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: {}
@@ -12488,6 +12503,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'
@@ -12534,6 +12552,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: {}
@@ -12553,6 +12574,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'
@@ -12603,6 +12627,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:
@@ -12629,6 +12656,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'
@@ -14841,6 +14871,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

@@ -357,6 +357,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.
@@ -418,6 +420,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
@@ -522,6 +526,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 {
@@ -551,6 +557,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 {
@@ -574,6 +582,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.
@@ -604,6 +614,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 {
@@ -617,6 +629,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
@@ -654,6 +668,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 {
@@ -670,6 +686,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.
@@ -702,6 +720,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 {
@@ -1915,6 +1935,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:
@@ -2549,6 +2572,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 {
@@ -2635,6 +2661,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 {
@@ -2661,6 +2689,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 {