add fine-grained control to automatic timeskipping

Author: feiyang3cat

openapi/openapiv2.json

@@ -16296,6 +16296,15 @@
         "enabled": {
           "type": "boolean",
           "description": "If set, enables automatic time-skipping for this workflow execution.\nIt can also be disabled by setting this field to false.\nSpecial attention for transitively related workflows:\n- By default, Child workflows and Continue-As-New workflows will \ninherit 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, \nthe propagation won't happen. It not recommended flip the parent's enabled config\nwhen there are in-flight child/continue-as-new workflows."
+        },
+        "until": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Absolute timestamp to auto-skip until."
+        },
+        "duration": {
+          "type": "string",
+          "description": "Duration from the workflow's current virtual time (at the time the config\nis applied) to auto-skip for. The server resolves this to an absolute\ntimestamp stored in TimeSkippingInfo."
         }
       },
       "description": "Configuration for automatic time skipping on a workflow execution.\nOnce enabled, time automatically advances when there is no in-flight \nactivities, child workflows, or Nexus operations."
@@ -17870,6 +17879,10 @@
         "toTime": {
           "type": "string",
           "format": "date-time"
+        },
+        "boundReachedAndTimeSkippingDisabled": {
+          "type": "boolean",
+          "description": "when true, it means the automatic time-skipping was enabled with a bound \nand now the bound is reached and the time-skipping is disabled automatically."
         }
       },
       "description": "Attributes for an event marking that a duration was skipped for a workflow execution,\neither via manual time-skipping api call or automatic time-skipping."

openapi/openapiv3.yaml

@@ -14456,6 +14456,20 @@ components:
         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."
+        until:
+          type: string
+          description: |-
+            Absolute timestamp to auto-skip until.
+             (-- api-linter: core::0142::time-field-names=disabled
+                 aip.dev/not-precedent: `until` is intentionally used as a short, readable name in a oneof. --)
+          format: date-time
+        duration:
+          pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
+          type: string
+          description: |-
+            Duration from the workflow's current virtual time (at the time the config
+             is applied) to auto-skip for. The server resolves this to an absolute
+             timestamp stored in TimeSkippingInfo.
       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
@@ -16654,6 +16668,9 @@ components:
             (-- api-linter: core::0140::prepositions=disabled
                  aip.dev/not-precedent: "to" is used to indicate target time point. --)
           format: date-time
+        boundReachedAndTimeSkippingDisabled:
+          type: boolean
+          description: "when true, it means the automatic time-skipping was enabled with a bound \n and now the bound is reached and the time-skipping is disabled automatically."
       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.

temporal/api/history/v1/message.proto

@@ -974,6 +974,9 @@ 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;
+    // when true, it means the automatic time-skipping was enabled with a bound 
+    // and now the bound is reached and the time-skipping is disabled automatically.
+    bool bound_reached_and_time_skipping_disabled = 2;
 }
 
 // Event marking that an operation was scheduled by a workflow via the ScheduleNexusOperation command.

temporal/api/workflow/v1/message.proto

@@ -588,6 +588,16 @@ message TimeSkippingConfig {
     // when there are in-flight child/continue-as-new workflows.
     bool enabled = 1;
 
+    // The duration bound for auto-skip.
+    // When reached, the time-skipping will be disabled automatically.
+    // But it can also be re-enabled through UpdateWorkflowExecutionOptions.
+    // This field is designed for complex testing scenarios where the workflow expects to receive signals/updates/etc during a user timer.
+    // where the workflow expects to receive signals/updates/etc during a user timer.
+    // 
+    // An example: the duration is 55 minutes, and the workflow has a timer for 1hour.
+    // And server will only skip 55 minutes, and turn off the time-skipping.
+    google.protobuf.Duration max_auto_skip_duration = 3;
+    
 }
 
 // Used to override the versioning behavior (and pinned deployment version, if applicable) of a

temporal/api/workflowservice/v1/request_response.proto

@@ -2955,4 +2955,4 @@ message DeleteActivityExecutionRequest {
 }
 
 message DeleteActivityExecutionResponse {
-}
+}