Merge remote-tracking branch 'origin/master' into standalone-nexus-op

# Conflicts:
#	openapi/openapiv2.json
#	openapi/openapiv3.yaml
#	temporal/api/common/v1/message.proto

Author: stephanos

openapi/openapiv2.json

@@ -8878,6 +8878,11 @@ components:
         canceledReason:
           type: string
           description: Set if activity cancelation was requested.
+        links:
+          type: array
+          items:
+            $ref: '#/components/schemas/Link'
+          description: Links to related entities, such as the entity that started this activity.
       description: Information about a standalone activity.
     ActivityExecutionListInfo:
       type: object
@@ -9708,10 +9713,6 @@ components:
           allOf:
             - $ref: '#/components/schemas/Callback'
           description: Information on how this callback should be invoked (e.g. its URL and type).
-        trigger:
-          allOf:
-            - $ref: '#/components/schemas/CallbackInfo_Trigger'
-          description: Trigger for this callback.
         registrationTime:
           type: string
           description: The time when the callback was registered.
@@ -9726,6 +9727,7 @@ components:
             - CALLBACK_STATE_SUCCEEDED
             - CALLBACK_STATE_BLOCKED
           type: string
+          description: The current state of the callback.
           format: enum
         attempt:
           type: integer
@@ -9748,16 +9750,7 @@ components:
         blockedReason:
           type: string
           description: If the state is BLOCKED, blocked reason provides additional information.
-      description: CallbackInfo contains the state of an attached workflow callback.
-    CallbackInfo_Trigger:
-      type: object
-      properties:
-        workflowClosed:
-          $ref: '#/components/schemas/CallbackInfo_WorkflowClosed'
-    CallbackInfo_WorkflowClosed:
-      type: object
-      properties: {}
-      description: Trigger for when the workflow is closed.
+      description: Common callback information. Specific CallbackInfo messages should embed this and may include additional fields.
     Callback_Internal:
       type: object
       properties:
@@ -10581,6 +10574,11 @@ components:
           type: string
           description: Token for follow-on long-poll requests. Absent only if the activity is complete.
           format: bytes
+        callbacks:
+          type: array
+          items:
+            $ref: '#/components/schemas/CallbackInfo'
+          description: Callbacks attached to this activity execution and their current state.
     DescribeBatchOperationResponse:
       type: object
       properties:
@@ -11427,7 +11425,7 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/Link'
-          description: Links associated with the event.
+          description: Links to related entities, such as the entity that started this event's workflow.
         principal:
           allOf:
             - $ref: '#/components/schemas/Principal'
@@ -11565,9 +11563,28 @@ components:
         sourceDeploymentRevisionNumber:
           type: string
           description: The revision number of the source deployment version of the parent/previous workflow.
+        continueAsNewInitialVersioningBehavior:
+          enum:
+            - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_UNSPECIFIED
+            - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_AUTO_UPGRADE
+            - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_USE_RAMPING_VERSION
+          type: string
+          description: |-
+            Experimental.
+             If this workflow is the result of a continue-as-new, this field is set to the initial_versioning_behavior
+             specified in that command.
+             Only used for the initial task of this run and the initial task of any retries of this run.
+             Not passed to children or to future continue-as-new.
+
+             Note: In the first release of Upgrade-on-CaN, when the only ContinueAsNewVersioningBehavior was AutoUpgrade,
+             a non-empty InheritedAutoUpgradeInfo meant that the workflow should start as AutoUpgrade. So for compatibility
+             with history events generated during that time, know that an UNSPECIFIED value here is equivalent to AutoUpgrade
+             value if the InheritedAutoUpgradeInfo is non-empty.
+          format: enum
       description: |-
         Used as part of WorkflowExecutionStartedEventAttributes to pass down the AutoUpgrade behavior and source deployment version
          to a workflow execution whose parent/previous workflow has an AutoUpgrade behavior.
+         Also used for Upgrade-on-CaN behaviors AutoUpgrade and UseRampingVersion.
     Input:
       type: object
       properties:
@@ -11612,13 +11629,25 @@ components:
           $ref: '#/components/schemas/Link_WorkflowEvent'
         batchJob:
           $ref: '#/components/schemas/Link_BatchJob'
+        activity:
+          $ref: '#/components/schemas/Link_Activity'
         nexusOperation:
           $ref: '#/components/schemas/Link_NexusOperation'
       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:
          in this case, a history event in workflow A could contain a Link to the workflow started event in
          workflow B, and vice-versa.
+    Link_Activity:
+      type: object
+      properties:
+        namespace:
+          type: string
+        activityId:
+          type: string
+        runId:
+          type: string
+      description: A link to an activity.
     Link_BatchJob:
       type: object
       properties:
@@ -15280,6 +15309,20 @@ components:
           allOf:
             - $ref: '#/components/schemas/Priority'
           description: Priority metadata.
+        completionCallbacks:
+          type: array
+          items:
+            $ref: '#/components/schemas/Callback'
+          description: |-
+            Callbacks to be called by the server when this activity reaches a terminal state.
+             Callback addresses must be whitelisted in the server's dynamic configuration.
+        links:
+          type: array
+          items:
+            $ref: '#/components/schemas/Link'
+          description: |-
+            Links to be associated with the activity. Callbacks may also have associated links;
+             links already included with a callback should not be duplicated here.
     StartActivityExecutionResponse:
       type: object
       properties:
@@ -15289,6 +15332,10 @@ components:
         started:
           type: boolean
           description: If true, a new activity was started.
+        link:
+          allOf:
+            - $ref: '#/components/schemas/Link'
+          description: Link to the started activity.
     StartBatchOperationRequest:
       type: object
       properties:
@@ -17875,6 +17922,7 @@ components:
           enum:
             - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_UNSPECIFIED
             - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_AUTO_UPGRADE
+            - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_USE_RAMPING_VERSION
           type: string
           description: |-
             Experimental. Optionally decide the versioning behavior that the first task of the new run should use.
@@ -18649,6 +18697,24 @@ components:
              Note: Pinned tasks and sticky tasks send a value of 0 for this field since these tasks do not
              face the problem of inconsistent dispatching that arises from eventual consistency between
              task queues and their partitions.
+        continueAsNewInitialVersioningBehavior:
+          enum:
+            - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_UNSPECIFIED
+            - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_AUTO_UPGRADE
+            - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_USE_RAMPING_VERSION
+          type: string
+          description: |-
+            Experimental.
+             If this workflow is the result of a continue-as-new, this field is set to the initial_versioning_behavior
+             specified in that command.
+             Only used for the initial task of this run and the initial task of any retries of this run.
+             Not passed to children or to future continue-as-new.
+
+             Note: In the first release of Upgrade-on-CaN, when the only ContinueAsNewVersioningBehavior was AutoUpgrade,
+             a non-empty InheritedAutoUpgradeInfo meant that the workflow should start as AutoUpgrade. So for compatibility
+             with ContinueAsNew history commands generated during that time, know that an UNSPECIFIED value here is equivalent
+             to ContinueAsNewVersioningBehaviorAutoUpgrade if the behavior of the workflow is AutoUpgrade.
+          format: enum
       description: |-
         Holds all the information about worker versioning for a particular workflow execution.
          Experimental. Versioning info is experimental and might change in the future.

openapi/openapiv3.yaml

@@ -15,6 +15,7 @@ import "google/protobuf/timestamp.proto";
 import "temporal/api/common/v1/message.proto";
 import "temporal/api/deployment/v1/message.proto";
 import "temporal/api/enums/v1/activity.proto";
+import "temporal/api/callback/v1/message.proto";
 import "temporal/api/enums/v1/workflow.proto";
 import "temporal/api/failure/v1/message.proto";
 import "temporal/api/taskqueue/v1/message.proto";
@@ -161,6 +162,9 @@ message ActivityExecutionInfo {
 
     // Set if activity cancelation was requested.
     string canceled_reason = 32;
+
+    // Links to related entities, such as the entity that started this activity.
+    repeated temporal.api.common.v1.Link links = 33;
 }
 
 // Limited activity information returned in the list response.
@@ -195,3 +199,20 @@ message ActivityExecutionListInfo {
     // This field is only populated if the activity is closed.
     google.protobuf.Duration execution_duration = 11;
 }
+
+// CallbackInfo contains the state of an attached activity callback.
+message CallbackInfo {
+    // Trigger for when the activity is closed.
+    message ActivityClosed {}
+
+    message Trigger {
+        oneof variant {
+            ActivityClosed activity_closed = 1;
+        }
+    }
+
+    // Trigger for this callback.
+    Trigger trigger = 1;
+    // Common callback info.
+    temporal.api.callback.v1.CallbackInfo info = 2;
+}

temporal/api/activity/v1/message.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package temporal.api.callback.v1;
+
+option go_package = "go.temporal.io/api/callback/v1;callback";
+option java_package = "io.temporal.api.callback.v1";
+option java_multiple_files = true;
+option java_outer_classname = "MessageProto";
+option ruby_package = "Temporalio::Api::Callback::V1";
+option csharp_namespace = "Temporalio.Api.Callback.V1";
+
+import "google/protobuf/timestamp.proto";
+
+import "temporal/api/common/v1/message.proto";
+import "temporal/api/enums/v1/common.proto";
+import "temporal/api/failure/v1/message.proto";
+
+// Common callback information. Specific CallbackInfo messages should embed this and may include additional fields.
+message CallbackInfo {
+    // Information on how this callback should be invoked (e.g. its URL and type).
+    temporal.api.common.v1.Callback callback = 1;
+    // The time when the callback was registered.
+    google.protobuf.Timestamp registration_time = 2;
+    // The current state of the callback.
+    temporal.api.enums.v1.CallbackState state = 3;
+    // The number of attempts made to deliver the callback.
+    // This number represents a minimum bound since the attempt is incremented after the callback request completes.
+    int32 attempt = 4;
+    // The time when the last attempt completed.
+    google.protobuf.Timestamp last_attempt_complete_time = 5;
+    // The last attempt's failure, if any.
+    temporal.api.failure.v1.Failure last_attempt_failure = 6;
+    // The time when the next attempt is scheduled.
+    google.protobuf.Timestamp next_attempt_schedule_time = 7;
+    // If the state is BLOCKED, blocked reason provides additional information.
+    string blocked_reason = 8;
+}

temporal/api/callback/v1/message.proto

@@ -240,6 +240,13 @@ message Link {
         string job_id = 1;
     }
 
+    // A link to an activity.
+    message Activity {
+        string namespace = 1;
+        string activity_id = 2;
+        string run_id = 3;
+    }
+
     // A link to a standalone Nexus operation.
     message NexusOperation {
         string namespace = 1;
@@ -250,7 +257,8 @@ message Link {
     oneof variant {
         WorkflowEvent workflow_event = 1;
         BatchJob batch_job = 2;
-        NexusOperation nexus_operation = 3;
+        Activity activity = 3;
+        NexusOperation nexus_operation = 4;
     }
 }
 

temporal/api/common/v1/message.proto

@@ -11,6 +11,7 @@ option csharp_namespace = "Temporalio.Api.Deployment.V1";
 
 import "google/protobuf/timestamp.proto";
 
+import "temporal/api/enums/v1/workflow.proto";
 import "temporal/api/enums/v1/deployment.proto";
 import "temporal/api/enums/v1/task_queue.proto";
 import "temporal/api/common/v1/message.proto";
@@ -316,9 +317,21 @@ message RoutingConfig {
 
 // Used as part of WorkflowExecutionStartedEventAttributes to pass down the AutoUpgrade behavior and source deployment version
 // to a workflow execution whose parent/previous workflow has an AutoUpgrade behavior.
+// Also used for Upgrade-on-CaN behaviors AutoUpgrade and UseRampingVersion.
 message InheritedAutoUpgradeInfo {
     // The source deployment version of the parent/previous workflow.
     temporal.api.deployment.v1.WorkerDeploymentVersion source_deployment_version = 1;
     // The revision number of the source deployment version of the parent/previous workflow.
     int64 source_deployment_revision_number = 2;
+    // Experimental.
+    // If this workflow is the result of a continue-as-new, this field is set to the initial_versioning_behavior
+    // specified in that command.
+    // Only used for the initial task of this run and the initial task of any retries of this run.
+    // Not passed to children or to future continue-as-new.
+    //
+    // Note: In the first release of Upgrade-on-CaN, when the only ContinueAsNewVersioningBehavior was AutoUpgrade,
+    // a non-empty InheritedAutoUpgradeInfo meant that the workflow should start as AutoUpgrade. So for compatibility
+    // with history events generated during that time, know that an UNSPECIFIED value here is equivalent to AutoUpgrade
+    // value if the InheritedAutoUpgradeInfo is non-empty.
+    temporal.api.enums.v1.ContinueAsNewVersioningBehavior continue_as_new_initial_versioning_behavior = 3;
 }

temporal/api/deployment/v1/message.proto

@@ -178,16 +178,31 @@ enum VersioningBehavior {
 enum ContinueAsNewVersioningBehavior {
     CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_UNSPECIFIED = 0;
 
+    // Experimental.
     // Start the new run with AutoUpgrade behavior. Use the Target Version of the workflow's task queue at
     // start-time, as AutoUpgrade workflows do. After the first workflow task completes, use whatever
     // Versioning Behavior the workflow is annotated with in the workflow code.
     //
-    // Note that if the previous workflow had a Pinned override, that override will be inherited by the
+    // Note that if the workflow being continued has a Pinned override, that override will be inherited by the
     // new workflow run regardless of the ContinueAsNewVersioningBehavior specified in the continue-as-new
-    // command. If a Pinned override is inherited by the new run, and the new run starts with AutoUpgrade
-    // behavior, the base version of the new run will be the Target Version as described above, but the
-    // effective version will be whatever is specified by the Versioning Override until the override is removed.
+    // command. Versioning Override always takes precedence until it's removed manually via UpdateWorkflowExecutionOptions.
     CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_AUTO_UPGRADE = 1;
+
+    // Experimental.
+    // Use the Ramping Version of the workflow's task queue at start time, regardless of the workflow's
+    // Target Version (according to f(workflow_id, ramp_percentage)). After the first workflow task completes,
+    // the workflow will use whatever Versioning Behavior it is annotated with. If there is no Ramping
+    // Version by the time that the first workflow task is dispatched, it will be sent to the Current Version.
+    //
+    // It is highly discouraged to use this if the workflow is annotated with AutoUpgrade behavior, because
+    // this setting ONLY applies to the first task of the workflow. If, after the first task, the workflow
+    // is AutoUpgrade, it will behave like a normal AutoUpgrade workflow and go to the Target Version, which
+    // may be the Current Version instead of the Ramping Version.
+    //
+    // Note that if the workflow being continued has a Pinned override, that override will be inherited by the
+    // new workflow run regardless of the ContinueAsNewVersioningBehavior specified in the continue-as-new
+    // command. Versioning Override always takes precedence until it's removed manually via UpdateWorkflowExecutionOptions.
+    CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_USE_RAMPING_VERSION = 2;
 }
 
 // SuggestContinueAsNewReason specifies why SuggestContinueAsNew is true.

temporal/api/enums/v1/workflow.proto

@@ -1152,7 +1152,7 @@ message HistoryEvent {
     //  * timer_started_event_attributes - summary represents an identifier for the timer for use by
     //    user interfaces.
     temporal.api.sdk.v1.UserMetadata user_metadata = 301;
-    // Links associated with the event.
+    // Links to related entities, such as the entity that started this event's workflow.
     repeated temporal.api.common.v1.Link links = 302;
     // Server-computed authenticated caller identity associated with this event.
     temporal.api.common.v1.Principal principal = 303;

temporal/api/history/v1/message.proto

@@ -231,6 +231,17 @@ message WorkflowExecutionVersioningInfo {
     // face the problem of inconsistent dispatching that arises from eventual consistency between
     // task queues and their partitions.
     int64 revision_number = 8;
+    // Experimental.
+    // If this workflow is the result of a continue-as-new, this field is set to the initial_versioning_behavior
+    // specified in that command.
+    // Only used for the initial task of this run and the initial task of any retries of this run.
+    // Not passed to children or to future continue-as-new.
+    //
+    // Note: In the first release of Upgrade-on-CaN, when the only ContinueAsNewVersioningBehavior was AutoUpgrade,
+    // a non-empty InheritedAutoUpgradeInfo meant that the workflow should start as AutoUpgrade. So for compatibility
+    // with ContinueAsNew history commands generated during that time, know that an UNSPECIFIED value here is equivalent
+    // to ContinueAsNewVersioningBehaviorAutoUpgrade if the behavior of the workflow is AutoUpgrade.
+    temporal.api.enums.v1.ContinueAsNewVersioningBehavior continue_as_new_initial_versioning_behavior = 9;
 }
 
 // Holds information about ongoing transition of a workflow execution from one deployment to another.