Wire request_id through CallbackInfo for linking

openapi/openapiv2.json

@@ -11107,21 +11107,6 @@
       },
       "description": "A link to a standalone Nexus operation."
     },
-    "LinkNexusOperationCallback": {
-      "type": "object",
-      "properties": {
-        "operationId": {
-          "type": "string"
-        },
-        "runId": {
-          "type": "string"
-        },
-        "requestId": {
-          "type": "string"
-        }
-      },
-      "description": "A link to a worker callback attached to a Nexus operation within the same namespace. e.g. the completion handler attached\nto a standalone Nexus operation, not the source Nexus operation itself. A standalone Nexus operation can have multiple\ncallbacks attached to them, and will be differentiated by the server-generated request_id used when the callback was invoked."
-    },
     "LinkWorkflow": {
       "type": "object",
       "properties": {
@@ -11549,7 +11534,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "$ref": "#/definitions/v1Callback"
+            "$ref": "#/definitions/commonV1Callback"
           },
           "description": "Completion callbacks attached to the running workflow update."
         }
@@ -12583,7 +12568,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "$ref": "#/definitions/v1Callback"
+            "$ref": "#/definitions/commonV1Callback"
           },
           "description": "Callbacks to be called by the server when this activity reaches a terminal state.\nCallback addresses must be whitelisted in the server's dynamic configuration."
         },
@@ -12745,7 +12730,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "$ref": "#/definitions/v1Callback"
+            "$ref": "#/definitions/commonV1Callback"
           },
           "description": "Completion callbacks to be invoked once the Nexus operation reaches a terminal state."
         },
@@ -12836,7 +12821,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "$ref": "#/definitions/v1Callback"
+            "$ref": "#/definitions/commonV1Callback"
           },
           "description": "Callbacks to be called by the server when this workflow reaches a terminal state.\nIf the workflow continues-as-new, these callbacks will be carried over to the new execution.\nCallback addresses must be whitelisted in the server's dynamic configuration."
         },
@@ -13380,7 +13365,7 @@
               "type": "array",
               "items": {
                 "type": "object",
-                "$ref": "#/definitions/v1Callback"
+                "$ref": "#/definitions/commonV1Callback"
               },
               "description": "Callbacks to be called by the server when this update reaches a terminal state."
             },
@@ -13480,7 +13465,7 @@
       "type": "object",
       "properties": {
         "callback": {
-          "$ref": "#/definitions/v1Callback",
+          "$ref": "#/definitions/commonV1Callback",
           "description": "Information on how this callback should be invoked (e.g. its URL and type)."
         },
         "registrationTime": {
@@ -13515,6 +13500,10 @@
           "type": "string",
           "description": "If the state is BLOCKED, blocked reason provides additional information."
         },
+        "requestId": {
+          "type": "string",
+          "description": "Server-generated request ID used as an idempotency token when invoking callbacks.\nIt has no relation to caller-side request_id sent in operations like StartNexusOperationExecutionRequest."
+        },
         "success": {
           "type": "object",
           "properties": {},
@@ -13589,7 +13578,7 @@
       "type": "object",
       "properties": {
         "callback": {
-          "$ref": "#/definitions/v1Callback",
+          "$ref": "#/definitions/commonV1Callback",
           "description": "Information on how this callback should be invoked (e.g. its URL and type)."
         },
         "trigger": {
@@ -13659,6 +13648,29 @@
       },
       "description": "When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and\nthere is already an existing running workflow, OnConflictOptions defines actions to be taken on\nthe existing running workflow. In this case, it will create a WorkflowExecutionOptionsUpdatedEvent\nhistory event in the running workflow with the changes requested in this object."
     },
+    "commonV1Callback": {
+      "type": "object",
+      "properties": {
+        "nexus": {
+          "$ref": "#/definitions/CallbackNexus"
+        },
+        "internal": {
+          "$ref": "#/definitions/CallbackInternal"
+        },
+        "worker": {
+          "$ref": "#/definitions/v1CallbackWorker"
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Link"
+          },
+          "description": "Links associated with the callback. It can be used to link to underlying resources of the\ncallback."
+        }
+      },
+      "description": "Callback to attach to various events in the system, e.g. workflow run completion."
+    },
     "protobufAny": {
       "type": "object",
       "properties": {
@@ -14737,29 +14749,6 @@
       },
       "description": "CalendarSpec describes an event specification relative to the calendar,\nsimilar to a traditional cron specification, but with labeled fields. Each\nfield can be one of:\n  *: matches always\n  x: matches when the field equals x\n  x/y : matches when the field equals x+n*y where n is an integer\n  x-z: matches when the field is between x and z inclusive\n  w,x,y,...: matches when the field is one of the listed values\nEach x, y, z, ... is either a decimal integer, or a month or day of week name\nor abbreviation (in the appropriate fields).\nA timestamp matches if all fields match.\nNote that fields have different default values, for convenience.\nNote that the special case that some cron implementations have for treating\nday_of_month and day_of_week as \"or\" instead of \"and\" when both are set is\nnot implemented.\nday_of_week can accept 0 or 7 as Sunday\nCalendarSpec gets compiled into StructuredCalendarSpec, which is what will be\nreturned if you describe the schedule."
     },
-    "v1Callback": {
-      "type": "object",
-      "properties": {
-        "nexus": {
-          "$ref": "#/definitions/CallbackNexus"
-        },
-        "internal": {
-          "$ref": "#/definitions/CallbackInternal"
-        },
-        "worker": {
-          "$ref": "#/definitions/v1CallbackWorker"
-        },
-        "links": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "$ref": "#/definitions/v1Link"
-          },
-          "description": "Links associated with the callback. It can be used to link to underlying resources of the\ncallback."
-        }
-      },
-      "description": "Callback to attach to various events in the system, e.g. workflow run completion."
-    },
     "v1CallbackState": {
       "type": "string",
       "enum": [
@@ -16123,17 +16112,18 @@
           "type": "string"
         }
       },
-      "description": "Identifies a specific execution within a namespace. This is used for standalone activities\nexecutions in batch jobs currently."
+      "description": "Identifies a specific execution within a namespace."
     },
     "v1ExecutionType": {
       "type": "string",
       "enum": [
         "EXECUTION_TYPE_UNSPECIFIED",
         "EXECUTION_TYPE_WORKFLOW",
-        "EXECUTION_TYPE_ACTIVITY"
+        "EXECUTION_TYPE_ACTIVITY",
+        "EXECUTION_TYPE_NEXUS_OPERATION"
       ],
       "default": "EXECUTION_TYPE_UNSPECIFIED",
-      "description": " - EXECUTION_TYPE_WORKFLOW: A workflow execution archetype.\n - EXECUTION_TYPE_ACTIVITY: An activity execution archetype. This is reserved for standalone activities."
+      "description": " - EXECUTION_TYPE_WORKFLOW: A workflow execution archetype.\n - EXECUTION_TYPE_ACTIVITY: An activity execution archetype. This is reserved for standalone activities.\n - EXECUTION_TYPE_NEXUS_OPERATION: A Nexus operation execution archetype. This is reserved for standalone Nexus operations."
     },
     "v1ExternalWorkflowExecutionCancelRequestedEventAttributes": {
       "type": "object",
@@ -16866,12 +16856,27 @@
         "workflow": {
           "$ref": "#/definitions/LinkWorkflow"
         },
-        "nexusOperationCallback": {
-          "$ref": "#/definitions/LinkNexusOperationCallback"
+        "callback": {
+          "$ref": "#/definitions/v1LinkCallback"
         }
       },
       "description": "Link can be associated with history events. It might contain information about an external entity\nrelated to the history event. For example, workflow A makes a Nexus call that starts workflow B:\nin this case, a history event in workflow A could contain a Link to the workflow started event in\nworkflow B, and vice-versa."
     },
+    "v1LinkCallback": {
+      "type": "object",
+      "properties": {
+        "namespace": {
+          "type": "string"
+        },
+        "execution": {
+          "$ref": "#/definitions/v1Execution"
+        },
+        "requestId": {
+          "type": "string"
+        }
+      },
+      "description": "A link to a worker callback attached to an execution. An execution (e.g. standalone Nexus operation) can have\nmultiple callbacks attached, and will be differentiated by the request_id used when the callback is invoked."
+    },
     "v1ListActivityExecutionsResponse": {
       "type": "object",
       "properties": {
@@ -18872,7 +18877,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "$ref": "#/definitions/v1Callback"
+            "$ref": "#/definitions/commonV1Callback"
           },
           "description": "Callbacks to be called by the server when this update reaches a terminal state."
         },
@@ -21777,7 +21782,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "$ref": "#/definitions/v1Callback"
+            "$ref": "#/definitions/commonV1Callback"
           },
           "description": "Completion callbacks attached to the running workflow execution."
         },
@@ -21993,7 +21998,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "$ref": "#/definitions/v1Callback"
+            "$ref": "#/definitions/commonV1Callback"
           },
           "description": "Completion callbacks attached when this workflow was started."
         },

openapi/openapiv3.yaml

@@ -10905,6 +10905,11 @@ components:
         blockedReason:
           type: string
           description: If the state is BLOCKED, blocked reason provides additional information.
+        requestId:
+          type: string
+          description: |-
+            Server-generated request ID used as an idempotency token when invoking callbacks.
+             It has no relation to caller-side request_id sent in operations like StartNexusOperationExecutionRequest.
         failure:
           allOf:
             - $ref: '#/components/schemas/Failure'
@@ -12431,15 +12436,14 @@ components:
             - EXECUTION_TYPE_UNSPECIFIED
             - EXECUTION_TYPE_WORKFLOW
             - EXECUTION_TYPE_ACTIVITY
+            - EXECUTION_TYPE_NEXUS_OPERATION
           type: string
           format: enum
         businessId:
           type: string
         runId:
           type: string
-      description: |-
-        Identifies a specific execution within a namespace. This is used for standalone activities
-         executions in batch jobs currently.
+      description: Identifies a specific execution within a namespace.
     ExternalWorkflowExecutionCancelRequestedEventAttributes:
       type: object
       properties:
@@ -13146,8 +13150,8 @@ components:
           $ref: '#/components/schemas/Link_NexusOperation'
         workflow:
           $ref: '#/components/schemas/Link_Workflow'
-        nexusOperationCallback:
-          $ref: '#/components/schemas/Link_NexusOperationCallback'
+        callback:
+          $ref: '#/components/schemas/Link_Callback'
       description: |-
         Link can be associated with history events. It might contain information about an external entity
          related to the history event. For example, workflow A makes a Nexus call that starts workflow B:
@@ -13172,29 +13176,28 @@ components:
         A link to a built-in batch job.
          Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).
          This link can be put on workflow history events generated by actions taken by a batch job.
-    Link_NexusOperation:
+    Link_Callback:
       type: object
       properties:
         namespace:
           type: string
-        operationId:
-          type: string
-        runId:
+        execution:
+          $ref: '#/components/schemas/Execution'
+        requestId:
           type: string
-      description: A link to a standalone Nexus operation.
-    Link_NexusOperationCallback:
+      description: |-
+        A link to a worker callback attached to an execution. An execution (e.g. standalone Nexus operation) can have
+         multiple callbacks attached, and will be differentiated by the request_id used when the callback is invoked.
+    Link_NexusOperation:
       type: object
       properties:
+        namespace:
+          type: string
         operationId:
           type: string
         runId:
           type: string
-        requestId:
-          type: string
-      description: |-
-        A link to a worker callback attached to a Nexus operation within the same namespace. e.g. the completion handler attached
-         to a standalone Nexus operation, not the source Nexus operation itself. A standalone Nexus operation can have multiple
-         callbacks attached to them, and will be differentiated by the server-generated request_id used when the callback was invoked.
+      description: A link to a standalone Nexus operation.
     Link_Workflow:
       type: object
       properties:

temporal/api/callback/v1/message.proto

@@ -36,12 +36,16 @@ message CallbackInfo {
     // If the state is BLOCKED, blocked reason provides additional information.
     string blocked_reason = 8;
 
+    // Server-generated request ID used as an idempotency token when invoking callbacks.
+    // It has no relation to caller-side request_id sent in operations like StartNexusOperationExecutionRequest.
+    string request_id = 9;
+
     // Result of the callback's execution, only set when the callback reaches a terminal state.
     oneof result {
         // The callback completed successfully. (Which may include delivering a "failed" result successfully.)
-        google.protobuf.Empty success = 9;
+        google.protobuf.Empty success = 10;
         // The failure if the callback was not able to complete successfully. e.g. timed out, received an
         // unretriable error, etc.
-        temporal.api.failure.v1.Failure failure = 10;
+        temporal.api.failure.v1.Failure failure = 11;
     }
 }

temporal/api/common/v1/message.proto

@@ -68,8 +68,7 @@ message WorkflowExecution {
     string run_id = 2;
 }
 
-// Identifies a specific execution within a namespace. This is used for standalone activities
-// executions in batch jobs currently.
+// Identifies a specific execution within a namespace.
 message Execution {
     temporal.api.enums.v1.ExecutionType type = 1;
     string business_id = 2;
@@ -304,13 +303,19 @@ message Link {
         string reason = 4;
     }
 
-    // A link to a worker callback attached to a Nexus operation within the same namespace. e.g. the completion handler attached
-    // to a standalone Nexus operation, not the source Nexus operation itself. A standalone Nexus operation can have multiple
-    // callbacks attached to them, and will be differentiated by the server-generated request_id used when the callback was invoked.
-    message NexusOperationCallback {
-        string operation_id = 1;
-        string run_id = 2;
+    // A link to a worker callback attached to an execution. An execution (e.g. standalone Nexus operation) can have
+    // multiple callbacks attached, and will be differentiated by the request_id used when the callback is invoked.
+    message Callback {
+        string namespace = 1;
+        Execution execution = 2;
         string request_id  = 3;
+
+        // NOTE: An Execution alone is not precise enough for all cases. e.g. a callback attached to a
+        // workflow update would be tied to a workflow execution as well as an update "component" (with
+        // an associated "component_id").
+        //
+        // Worker callbacks can only be associated with standalone Nexus operations, so those additional
+        // fields aren't currently necessary.
     }
 
     oneof variant {
@@ -319,7 +324,7 @@ message Link {
         Activity activity = 3;
         NexusOperation nexus_operation = 4;
         Workflow workflow = 5;
-        NexusOperationCallback nexus_operation_callback = 6;
+        Callback callback = 6;
     }
 }
 

temporal/api/enums/v1/common.proto

@@ -113,4 +113,6 @@ enum ExecutionType {
     EXECUTION_TYPE_WORKFLOW = 1;
     // An activity execution archetype. This is reserved for standalone activities.
     EXECUTION_TYPE_ACTIVITY = 2;
-}
+    // A Nexus operation execution archetype. This is reserved for standalone Nexus operations.
+    EXECUTION_TYPE_NEXUS_OPERATION = 3;
+}