Add request ID reference in links (#563)

_**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 -->
**What changed?**
Add request ID reference to `Link`.

<!-- Tell your future self why have you made these changes -->
**Why?**
Request ID can be used to associate links to history event ID.

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

Author: rodrigozhou

openapi/openapiv2.json

@@ -6724,6 +6724,9 @@
         },
         "eventRef": {
           "$ref": "#/definitions/WorkflowEventEventReference"
+        },
+        "requestIdRef": {
+          "$ref": "#/definitions/WorkflowEventRequestIdReference"
         }
       }
     },
@@ -6973,7 +6976,20 @@
         "eventType": {
           "$ref": "#/definitions/v1EventType"
         }
-      }
+      },
+      "description": "EventReference is a direct reference to a history event through the event ID."
+    },
+    "WorkflowEventRequestIdReference": {
+      "type": "object",
+      "properties": {
+        "requestId": {
+          "type": "string"
+        },
+        "eventType": {
+          "$ref": "#/definitions/v1EventType"
+        }
+      },
+      "description": "RequestIdReference is a indirect reference to a history event through the request ID."
     },
     "WorkflowRuleActionActionActivityPause": {
       "type": "object"
@@ -12390,6 +12406,25 @@
     "v1RequestCancelWorkflowExecutionResponse": {
       "type": "object"
     },
+    "v1RequestIdInfo": {
+      "type": "object",
+      "properties": {
+        "eventType": {
+          "$ref": "#/definitions/v1EventType",
+          "description": "The event type of the history event generated by the request."
+        },
+        "eventId": {
+          "type": "string",
+          "format": "int64",
+          "description": "The event id of the history event generated by the request. It's possible the event ID is not\nknown (unflushed buffered event). In this case, the value will be zero or a negative value,\nrepresenting an invalid ID."
+        },
+        "buffered": {
+          "type": "boolean",
+          "description": "Indicate if the request is still buffered. If so, the event ID is not known and its value\nwill be an invalid event ID."
+        }
+      },
+      "description": "RequestIdInfo contains details of a request ID."
+    },
     "v1ResetActivityResponse": {
       "type": "object"
     },
@@ -13725,6 +13760,10 @@
         "eagerWorkflowTask": {
           "$ref": "#/definitions/v1PollWorkflowTaskQueueResponse",
           "description": "When `request_eager_execution` is set on the `StartWorkflowExecutionRequest`, the server - if supported - will\nreturn the first workflow task to be eagerly executed.\nThe caller is expected to have a worker available to process the task."
+        },
+        "link": {
+          "$ref": "#/definitions/apicommonv1Link",
+          "description": "Link to the workflow event."
         }
       }
     },
@@ -14846,6 +14885,13 @@
         "resetRunId": {
           "type": "string",
           "description": "Reset Run ID points to the new run when this execution is reset. If the execution is reset multiple times, it points to the latest run."
+        },
+        "requestIdInfos": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/v1RequestIdInfo"
+          },
+          "description": "Request ID information (eg: history event information associated with the request ID).\nNote: It only contains request IDs from StartWorkflowExecution requests, including indirect\ncalls (eg: if SignalWithStartWorkflowExecution starts a new workflow, then the request ID is\nused in the StartWorkflowExecution request)."
         }
       },
       "description": "Holds all the extra information about workflow execution that is not part of Visibility."

openapi/openapiv3.yaml

@@ -7986,6 +7986,8 @@ components:
           type: string
         eventRef:
           $ref: '#/components/schemas/WorkflowEvent_EventReference'
+        requestIdRef:
+          $ref: '#/components/schemas/WorkflowEvent_RequestIdReference'
     ListArchivedWorkflowExecutionsResponse:
       type: object
       properties:
@@ -9401,6 +9403,84 @@ components:
     RequestCancelWorkflowExecutionResponse:
       type: object
       properties: {}
+    RequestIdInfo:
+      type: object
+      properties:
+        eventType:
+          enum:
+            - EVENT_TYPE_UNSPECIFIED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_STARTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIMED_OUT
+            - EVENT_TYPE_WORKFLOW_TASK_SCHEDULED
+            - EVENT_TYPE_WORKFLOW_TASK_STARTED
+            - EVENT_TYPE_WORKFLOW_TASK_COMPLETED
+            - EVENT_TYPE_WORKFLOW_TASK_TIMED_OUT
+            - EVENT_TYPE_WORKFLOW_TASK_FAILED
+            - EVENT_TYPE_ACTIVITY_TASK_SCHEDULED
+            - EVENT_TYPE_ACTIVITY_TASK_STARTED
+            - EVENT_TYPE_ACTIVITY_TASK_COMPLETED
+            - EVENT_TYPE_ACTIVITY_TASK_FAILED
+            - EVENT_TYPE_ACTIVITY_TASK_TIMED_OUT
+            - EVENT_TYPE_ACTIVITY_TASK_CANCEL_REQUESTED
+            - EVENT_TYPE_ACTIVITY_TASK_CANCELED
+            - EVENT_TYPE_TIMER_STARTED
+            - EVENT_TYPE_TIMER_FIRED
+            - EVENT_TYPE_TIMER_CANCELED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_CANCEL_REQUESTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED
+            - EVENT_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED
+            - EVENT_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_CANCEL_REQUESTED
+            - EVENT_TYPE_MARKER_RECORDED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_CONTINUED_AS_NEW
+            - EVENT_TYPE_START_CHILD_WORKFLOW_EXECUTION_INITIATED
+            - EVENT_TYPE_START_CHILD_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_STARTED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_COMPLETED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_CANCELED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_TIMED_OUT
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_TERMINATED
+            - EVENT_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED
+            - EVENT_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_SIGNALED
+            - EVENT_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_ADMITTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_ACCEPTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_REJECTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_COMPLETED
+            - EVENT_TYPE_WORKFLOW_PROPERTIES_MODIFIED_EXTERNALLY
+            - EVENT_TYPE_ACTIVITY_PROPERTIES_MODIFIED_EXTERNALLY
+            - EVENT_TYPE_WORKFLOW_PROPERTIES_MODIFIED
+            - EVENT_TYPE_NEXUS_OPERATION_SCHEDULED
+            - EVENT_TYPE_NEXUS_OPERATION_STARTED
+            - EVENT_TYPE_NEXUS_OPERATION_COMPLETED
+            - EVENT_TYPE_NEXUS_OPERATION_FAILED
+            - EVENT_TYPE_NEXUS_OPERATION_CANCELED
+            - EVENT_TYPE_NEXUS_OPERATION_TIMED_OUT
+            - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
+            - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
+            - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
+          type: string
+          description: The event type of the history event generated by the request.
+          format: enum
+        eventId:
+          type: string
+          description: |-
+            The event id of the history event generated by the request. It's possible the event ID is not
+             known (unflushed buffered event). In this case, the value will be zero or a negative value,
+             representing an invalid ID.
+        buffered:
+          type: boolean
+          description: |-
+            Indicate if the request is still buffered. If so, the event ID is not known and its value
+             will be an invalid event ID.
+      description: RequestIdInfo contains details of a request ID.
     ResetActivityRequest:
       type: object
       properties:
@@ -10919,6 +10999,10 @@ components:
             When `request_eager_execution` is set on the `StartWorkflowExecutionRequest`, the server - if supported - will
              return the first workflow task to be eagerly executed.
              The caller is expected to have a worker available to process the task.
+        link:
+          allOf:
+            - $ref: '#/components/schemas/Link'
+          description: Link to the workflow event.
     Status:
       type: object
       properties:
@@ -12048,6 +12132,75 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
           type: string
           format: enum
+      description: EventReference is a direct reference to a history event through the event ID.
+    WorkflowEvent_RequestIdReference:
+      type: object
+      properties:
+        requestId:
+          type: string
+        eventType:
+          enum:
+            - EVENT_TYPE_UNSPECIFIED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_STARTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIMED_OUT
+            - EVENT_TYPE_WORKFLOW_TASK_SCHEDULED
+            - EVENT_TYPE_WORKFLOW_TASK_STARTED
+            - EVENT_TYPE_WORKFLOW_TASK_COMPLETED
+            - EVENT_TYPE_WORKFLOW_TASK_TIMED_OUT
+            - EVENT_TYPE_WORKFLOW_TASK_FAILED
+            - EVENT_TYPE_ACTIVITY_TASK_SCHEDULED
+            - EVENT_TYPE_ACTIVITY_TASK_STARTED
+            - EVENT_TYPE_ACTIVITY_TASK_COMPLETED
+            - EVENT_TYPE_ACTIVITY_TASK_FAILED
+            - EVENT_TYPE_ACTIVITY_TASK_TIMED_OUT
+            - EVENT_TYPE_ACTIVITY_TASK_CANCEL_REQUESTED
+            - EVENT_TYPE_ACTIVITY_TASK_CANCELED
+            - EVENT_TYPE_TIMER_STARTED
+            - EVENT_TYPE_TIMER_FIRED
+            - EVENT_TYPE_TIMER_CANCELED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_CANCEL_REQUESTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED
+            - EVENT_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED
+            - EVENT_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_CANCEL_REQUESTED
+            - EVENT_TYPE_MARKER_RECORDED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_CONTINUED_AS_NEW
+            - EVENT_TYPE_START_CHILD_WORKFLOW_EXECUTION_INITIATED
+            - EVENT_TYPE_START_CHILD_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_STARTED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_COMPLETED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_CANCELED
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_TIMED_OUT
+            - EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_TERMINATED
+            - EVENT_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED
+            - EVENT_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_FAILED
+            - EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_SIGNALED
+            - EVENT_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_ADMITTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_ACCEPTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_REJECTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_UPDATE_COMPLETED
+            - EVENT_TYPE_WORKFLOW_PROPERTIES_MODIFIED_EXTERNALLY
+            - EVENT_TYPE_ACTIVITY_PROPERTIES_MODIFIED_EXTERNALLY
+            - EVENT_TYPE_WORKFLOW_PROPERTIES_MODIFIED
+            - EVENT_TYPE_NEXUS_OPERATION_SCHEDULED
+            - EVENT_TYPE_NEXUS_OPERATION_STARTED
+            - EVENT_TYPE_NEXUS_OPERATION_COMPLETED
+            - EVENT_TYPE_NEXUS_OPERATION_FAILED
+            - EVENT_TYPE_NEXUS_OPERATION_CANCELED
+            - EVENT_TYPE_NEXUS_OPERATION_TIMED_OUT
+            - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
+            - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
+            - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
+          type: string
+          format: enum
+      description: RequestIdReference is a indirect reference to a history event through the request ID.
     WorkflowExecution:
       type: object
       properties:
@@ -12199,6 +12352,15 @@ components:
         resetRunId:
           type: string
           description: Reset Run ID points to the new run when this execution is reset. If the execution is reset multiple times, it points to the latest run.
+        requestIdInfos:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/RequestIdInfo'
+          description: |-
+            Request ID information (eg: history event information associated with the request ID).
+             Note: It only contains request IDs from StartWorkflowExecution requests, including indirect
+             calls (eg: if SignalWithStartWorkflowExecution starts a new workflow, then the request ID is
+             used in the StartWorkflowExecution request).
       description: Holds all the extra information about workflow execution that is not part of Visibility.
     WorkflowExecutionFailedEventAttributes:
       type: object

temporal/api/common/v1/message.proto

@@ -219,11 +219,18 @@ message Callback {
 // workflow B, and vice-versa.
 message Link {
     message WorkflowEvent {
+        // EventReference is a direct reference to a history event through the event ID.
         message EventReference {
             int64 event_id = 1;
             temporal.api.enums.v1.EventType event_type = 2;
         }
 
+        // RequestIdReference is a indirect reference to a history event through the request ID.
+        message RequestIdReference {
+            string request_id = 1;
+            temporal.api.enums.v1.EventType event_type = 2;
+        }
+
         string namespace = 1;
         string workflow_id = 2;
         string run_id = 3;
@@ -232,6 +239,7 @@ message Link {
         // Eg: the caller workflow can send the history event details that made the Nexus call.
         oneof reference {
             EventReference event_ref = 100;
+            RequestIdReference request_id_ref = 101;
         }
     }
 

temporal/api/workflow/v1/message.proto

@@ -36,6 +36,7 @@ import "google/protobuf/empty.proto";
 import "google/protobuf/timestamp.proto";
 
 import "temporal/api/enums/v1/common.proto";
+import "temporal/api/enums/v1/event_type.proto";
 import "temporal/api/enums/v1/workflow.proto";
 import "temporal/api/common/v1/message.proto";
 import "temporal/api/deployment/v1/message.proto";
@@ -139,6 +140,12 @@ message WorkflowExecutionExtendedInfo {
 
     // Reset Run ID points to the new run when this execution is reset. If the execution is reset multiple times, it points to the latest run.
     string reset_run_id = 6;
+
+    // Request ID information (eg: history event information associated with the request ID).
+    // Note: It only contains request IDs from StartWorkflowExecution requests, including indirect
+    // calls (eg: if SignalWithStartWorkflowExecution starts a new workflow, then the request ID is
+    // used in the StartWorkflowExecution request).
+    map<string, RequestIdInfo> request_id_infos = 7;
 }
 
 // Holds all the information about worker versioning for a particular workflow execution.
@@ -550,3 +557,16 @@ message OnConflictOptions {
     // Attaches the links to the WorkflowExecutionOptionsUpdatedEvent history event.
     bool attach_links = 3;
 }
+
+// RequestIdInfo contains details of a request ID.
+message RequestIdInfo {
+    // The event type of the history event generated by the request.
+    temporal.api.enums.v1.EventType event_type = 1;
+    // The event id of the history event generated by the request. It's possible the event ID is not
+    // known (unflushed buffered event). In this case, the value will be zero or a negative value,
+    // representing an invalid ID.
+    int64 event_id = 2;
+    // Indicate if the request is still buffered. If so, the event ID is not known and its value
+    // will be an invalid event ID.
+    bool buffered = 3;
+}

temporal/api/workflowservice/v1/request_response.proto

@@ -225,6 +225,8 @@ message StartWorkflowExecutionResponse {
     // return the first workflow task to be eagerly executed.
     // The caller is expected to have a worker available to process the task.
     PollWorkflowTaskQueueResponse eager_workflow_task = 2;
+    // Link to the workflow event.
+    temporal.api.common.v1.Link link = 4;
 }
 
 message GetWorkflowExecutionHistoryRequest {