api for automatic timeskipping

Author: feiyang3cat

openapi/openapiv2.json

@@ -10157,6 +10157,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
           type: string
           format: enum
         version:
@@ -10315,6 +10316,8 @@ components:
           $ref: '#/components/schemas/WorkflowExecutionPausedEventAttributes'
         workflowExecutionUnpausedEventAttributes:
           $ref: '#/components/schemas/WorkflowExecutionUnpausedEventAttributes'
+        workflowExecutionTimeSkippedEventAttributes:
+          $ref: '#/components/schemas/WorkflowExecutionTimeSkippedEventAttributes'
       description: |-
         History events are the method by which Temporal SDKs advance (or recreate) workflow state.
          See the `EventType` enum for more info about what each event is for.
@@ -11067,6 +11070,8 @@ components:
              Calls are retried internally by the server.
              (-- api-linter: core::0140::prepositions=disabled
                  aip.dev/not-precedent: "to" is used to indicate interval. --)
+             (-- api-linter: core::0142::time-field-names=disabled
+                 aip.dev/not-precedent: "timeout" is an acceptable suffix for duration fields in this API. --)
         nexusHeader:
           type: object
           additionalProperties:
@@ -12258,6 +12263,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
           type: string
           description: The event type of the history event generated by the request.
           format: enum
@@ -13571,6 +13577,10 @@ components:
           allOf:
             - $ref: '#/components/schemas/Priority'
           description: Priority metadata
+        timeSkippingConfig:
+          allOf:
+            - $ref: '#/components/schemas/TimeSkippingConfig'
+          description: Time skipping configuration. If not set, automatic time-skipping is disabled.
     SignalWithStartWorkflowExecutionResponse:
       type: object
       properties:
@@ -14033,6 +14043,10 @@ components:
           allOf:
             - $ref: '#/components/schemas/WorkerDeploymentOptions'
           description: Deployment Options of the worker who will process the eager task. Passed when `request_eager_execution=true`.
+        timeSkippingConfig:
+          allOf:
+            - $ref: '#/components/schemas/TimeSkippingConfig'
+          description: Automatic time-skipping configuration. If not set, automatic time-skipping is disabled.
     StartWorkflowExecutionResponse:
       type: object
       properties:
@@ -14436,6 +14450,13 @@ components:
     TerminatedFailureInfo:
       type: object
       properties: {}
+    TimeSkippingConfig:
+      type: object
+      properties:
+        enabled:
+          type: boolean
+          description: "If set, enables automatic time-skipping for this workflow execution.\n It can also be disabled by setting this field to false.\n Special attention for transitively related workflows:\n - By default, Child workflows and Continue-As-New workflows will \n inherit the enabled config but only at the time they are started.\n - But if the enabled config is flipped after a child/continue-as-new workflow is started, \n the propagation won't happen. It not recommended flip the parent's enabled config\n when there are in-flight child/continue-as-new workflows."
+      description: "Configuration for automatic time skipping on a workflow execution.\n Once enabled, time automatically advances when there is no in-flight \n activities, child workflows, or Nexus operations."
     TimeoutFailureInfo:
       type: object
       properties:
@@ -15859,6 +15880,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
           type: string
           format: enum
       description: EventReference is a direct reference to a history event through the event ID.
@@ -15929,6 +15951,7 @@ components:
             - EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
             - EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
             - EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
+            - EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED
           type: string
           format: enum
       description: RequestIdReference is a indirect reference to a history event through the request ID.
@@ -16278,6 +16301,10 @@ components:
           allOf:
             - $ref: '#/components/schemas/Priority'
           description: If set, overrides the workflow's priority sent by the SDK.
+        timeSkippingConfig:
+          allOf:
+            - $ref: '#/components/schemas/TimeSkippingConfig'
+          description: "Time-skipping configuration for this workflow execution.\n If not set, the time-skipping conf will not get updated upon request, \n i.e. the existing time-skipping conf will be preserved."
     WorkflowExecutionOptionsUpdatedEventAttributes:
       type: object
       properties:
@@ -16309,6 +16336,10 @@ components:
           description: |-
             Priority override upserted in this event. Represents the full priority; not just partial fields.
              Ignored if nil.
+        timeSkippingConfig:
+          allOf:
+            - $ref: '#/components/schemas/TimeSkippingConfig'
+          description: "Time skipping configuration upserted in this event. \n It means the time-skipping config is changed, and the full latest config is upserted."
     WorkflowExecutionPauseInfo:
       type: object
       properties:
@@ -16614,6 +16645,18 @@ components:
         identity:
           type: string
           description: id of the client who requested termination
+    WorkflowExecutionTimeSkippedEventAttributes:
+      type: object
+      properties:
+        toTime:
+          type: string
+          description: |-
+            (-- api-linter: core::0140::prepositions=disabled
+                 aip.dev/not-precedent: "to" is used to indicate target time point. --)
+          format: date-time
+      description: |-
+        Attributes for an event marking that a duration was skipped for a workflow execution,
+         either via manual time-skipping api call or automatic time-skipping.
     WorkflowExecutionTimedOutEventAttributes:
       type: object
       properties:

openapi/openapiv3.yaml

@@ -173,4 +173,6 @@ enum EventType {
     EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED = 58;
     // An event that indicates that the previously paused workflow execution has been unpaused.
     EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED = 59;
+    // An event that indicates that some duration was skipped for this workflow execution.
+    EVENT_TYPE_WORKFLOW_EXECUTION_TIME_SKIPPED = 60;
 }

temporal/api/enums/v1/event_type.proto

@@ -873,6 +873,9 @@ message WorkflowExecutionOptionsUpdatedEventAttributes {
     // Priority override upserted in this event. Represents the full priority; not just partial fields.
     // Ignored if nil.
     temporal.api.common.v1.Priority priority = 6;
+    // Time skipping configuration upserted in this event. 
+    // It means the time-skipping config is changed, and the full latest config is upserted.
+    temporal.api.workflow.v1.TimeSkippingConfig time_skipping_config = 7;
 }
 
 // Not used anywhere. Use case is replaced by WorkflowExecutionOptionsUpdatedEventAttributes
@@ -965,6 +968,14 @@ message WorkflowExecutionUnpausedEventAttributes {
     string request_id = 3;
 }
 
+// Attributes for an event marking that a duration was skipped for a workflow execution,
+// either via manual time-skipping api call or automatic time-skipping.
+message WorkflowExecutionTimeSkippedEventAttributes {
+    // (-- api-linter: core::0140::prepositions=disabled
+    //     aip.dev/not-precedent: "to" is used to indicate target time point. --)
+    google.protobuf.Timestamp to_time = 1;
+}
+
 // Event marking that an operation was scheduled by a workflow via the ScheduleNexusOperation command.
 message NexusOperationScheduledEventAttributes {
     // Endpoint name, must exist in the endpoint registry.
@@ -982,6 +993,8 @@ message NexusOperationScheduledEventAttributes {
     // Calls are retried internally by the server.
     // (-- api-linter: core::0140::prepositions=disabled
     //     aip.dev/not-precedent: "to" is used to indicate interval. --)
+    // (-- api-linter: core::0142::time-field-names=disabled
+    //     aip.dev/not-precedent: "timeout" is an acceptable suffix for duration fields in this API. --)
     google.protobuf.Duration schedule_to_close_timeout = 5;
     // Header to attach to the Nexus request. Note these headers are not the same as Temporal headers on internal
     // activities and child workflows, these are transmitted to Nexus operations that may be external and are not
@@ -1199,6 +1212,7 @@ message HistoryEvent {
         NexusOperationCancelRequestFailedEventAttributes nexus_operation_cancel_request_failed_event_attributes = 62;
         WorkflowExecutionPausedEventAttributes workflow_execution_paused_event_attributes = 63;
         WorkflowExecutionUnpausedEventAttributes workflow_execution_unpaused_event_attributes = 64;
+        WorkflowExecutionTimeSkippedEventAttributes workflow_execution_time_skipped_event_attributes = 65;
     }
 }
 

temporal/api/history/v1/message.proto

@@ -566,6 +566,28 @@ message WorkflowExecutionOptions {
 
     // If set, overrides the workflow's priority sent by the SDK.
     temporal.api.common.v1.Priority priority = 2;
+
+    // Time-skipping configuration for this workflow execution.
+    // If not set, the time-skipping conf will not get updated upon request, 
+    // i.e. the existing time-skipping conf will be preserved.
+    TimeSkippingConfig time_skipping_config = 3;
+}
+
+// Configuration for automatic time skipping on a workflow execution.
+// Once enabled, time automatically advances when there is no in-flight 
+// activities, child workflows, or Nexus operations.
+message TimeSkippingConfig {
+
+    // If set, enables automatic time-skipping for this workflow execution.
+    // It can also be disabled by setting this field to false.
+    // Special attention for transitively related workflows:
+    // - By default, Child workflows and Continue-As-New workflows will 
+    // inherit the enabled config but only at the time they are started.
+    // - But if the enabled config is flipped after a child/continue-as-new workflow is started, 
+    // the propagation won't happen. It not recommended flip the parent's enabled config
+    // when there are in-flight child/continue-as-new workflows.
+    bool enabled = 1;
+
 }
 
 // Used to override the versioning behavior (and pinned deployment version, if applicable) of a

temporal/api/workflow/v1/message.proto

@@ -197,6 +197,8 @@ message StartWorkflowExecutionRequest {
     temporal.api.common.v1.Priority priority = 27;
     // Deployment Options of the worker who will process the eager task. Passed when `request_eager_execution=true`.
     temporal.api.deployment.v1.WorkerDeploymentOptions eager_worker_deployment_options = 28;
+    // Automatic time-skipping configuration. If not set, automatic time-skipping is disabled.
+    temporal.api.workflow.v1.TimeSkippingConfig time_skipping_config = 29;
 }
 
 message StartWorkflowExecutionResponse {
@@ -836,6 +838,8 @@ message SignalWithStartWorkflowExecutionRequest {
     temporal.api.workflow.v1.VersioningOverride versioning_override = 25;
     // Priority metadata
     temporal.api.common.v1.Priority priority = 26;
+    // Time skipping configuration. If not set, automatic time-skipping is disabled.
+    temporal.api.workflow.v1.TimeSkippingConfig time_skipping_config = 27;
 }
 
 message SignalWithStartWorkflowExecutionResponse {