Skip to content

Commit 837c381

Browse files
committed
add fine-grained control to automatic timeskipping
1 parent 1feee4f commit 837c381

File tree

5 files changed

+122
-29
lines changed

5 files changed

+122
-29
lines changed

openapi/openapiv2.json

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16295,10 +16295,28 @@
1629516295
"properties": {
1629616296
"enabled": {
1629716297
"type": "boolean",
16298-
"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."
16298+
"description": "Enables or disables automatic time skipping for this workflow execution.\nBy default, this field is propagated to child workflows at the time they are started.\nChanges made after a child workflow has started are not propagated."
16299+
},
16300+
"disablePropagation": {
16301+
"type": "boolean",
16302+
"description": "If set, the enabled field is not propagated to child workflows."
16303+
},
16304+
"maxSkippedDuration": {
16305+
"type": "string",
16306+
"description": "Maximum total virtual time that can be skipped."
16307+
},
16308+
"maxElapsedDuration": {
16309+
"type": "string",
16310+
"format": "date-time",
16311+
"description": "Maximum elapsed time since time skipping was enabled.\nThis includes both skipped time and real time elapsing."
16312+
},
16313+
"maxTargetTime": {
16314+
"type": "string",
16315+
"format": "date-time",
16316+
"description": "Absolute virtual timestamp at which time skipping is disabled.\nTime skipping will not advance beyond this point."
1629916317
}
1630016318
},
16301-
"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."
16319+
"description": "Configuration for automatic time skipping during a workflow execution.\nWhen enabled, virtual time advances automatically whenever there are\nno in-flight activities, child workflows, or Nexus operations."
1630216320
},
1630316321
"v1TimeoutFailureInfo": {
1630416322
"type": "object",
@@ -17867,12 +17885,22 @@
1786717885
"v1WorkflowExecutionTimeSkippedEventAttributes": {
1786817886
"type": "object",
1786917887
"properties": {
17870-
"toTime": {
17888+
"targetTime": {
1787117889
"type": "string",
17872-
"format": "date-time"
17890+
"format": "date-time",
17891+
"description": "The virtual time after time skipping is applied."
17892+
},
17893+
"timeSkippingDisabledDueToBound": {
17894+
"type": "boolean",
17895+
"description": "Indicates that time skipping was automatically disabled because a configured bound was reached.\nThis may occur even if no time was skipped (e.g., the workflow was already at or beyond the target time).\nIn such cases, `target_time` will be equal to the current virtual time."
17896+
},
17897+
"wallClockTime": {
17898+
"type": "string",
17899+
"format": "date-time",
17900+
"description": "The wall-clock time when the time-skipping event happened."
1787317901
}
1787417902
},
17875-
"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."
17903+
"description": "Attributes for an event indicating that virtual time was advanced for a workflow execution,\neither via a manual time-skipping API call or automatic time skipping."
1787617904
},
1787717905
"v1WorkflowExecutionTimedOutEventAttributes": {
1787817906
"type": "object",

openapi/openapiv3.yaml

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14455,8 +14455,33 @@ components:
1445514455
properties:
1445614456
enabled:
1445714457
type: boolean
14458-
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."
14459-
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."
14458+
description: |-
14459+
Enables or disables automatic time skipping for this workflow execution.
14460+
By default, this field is propagated to child workflows at the time they are started.
14461+
Changes made after a child workflow has started are not propagated.
14462+
disablePropagation:
14463+
type: boolean
14464+
description: If set, the enabled field is not propagated to child workflows.
14465+
maxSkippedDuration:
14466+
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
14467+
type: string
14468+
description: Maximum total virtual time that can be skipped.
14469+
maxElapsedDuration:
14470+
type: string
14471+
description: |-
14472+
Maximum elapsed time since time skipping was enabled.
14473+
This includes both skipped time and real time elapsing.
14474+
format: date-time
14475+
maxTargetTime:
14476+
type: string
14477+
description: |-
14478+
Absolute virtual timestamp at which time skipping is disabled.
14479+
Time skipping will not advance beyond this point.
14480+
format: date-time
14481+
description: |-
14482+
Configuration for automatic time skipping during a workflow execution.
14483+
When enabled, virtual time advances automatically whenever there are
14484+
no in-flight activities, child workflows, or Nexus operations.
1446014485
TimeoutFailureInfo:
1446114486
type: object
1446214487
properties:
@@ -16648,15 +16673,23 @@ components:
1664816673
WorkflowExecutionTimeSkippedEventAttributes:
1664916674
type: object
1665016675
properties:
16651-
toTime:
16676+
targetTime:
1665216677
type: string
16678+
description: The virtual time after time skipping is applied.
16679+
format: date-time
16680+
timeSkippingDisabledDueToBound:
16681+
type: boolean
1665316682
description: |-
16654-
(-- api-linter: core::0140::prepositions=disabled
16655-
aip.dev/not-precedent: "to" is used to indicate target time point. --)
16683+
Indicates that time skipping was automatically disabled because a configured bound was reached.
16684+
This may occur even if no time was skipped (e.g., the workflow was already at or beyond the target time).
16685+
In such cases, `target_time` will be equal to the current virtual time.
16686+
wallClockTime:
16687+
type: string
16688+
description: The wall-clock time when the time-skipping event happened.
1665616689
format: date-time
1665716690
description: |-
16658-
Attributes for an event marking that a duration was skipped for a workflow execution,
16659-
either via manual time-skipping api call or automatic time-skipping.
16691+
Attributes for an event indicating that virtual time was advanced for a workflow execution,
16692+
either via a manual time-skipping API call or automatic time skipping.
1666016693
WorkflowExecutionTimedOutEventAttributes:
1666116694
type: object
1666216695
properties:

temporal/api/history/v1/message.proto

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -968,12 +968,21 @@ message WorkflowExecutionUnpausedEventAttributes {
968968
string request_id = 3;
969969
}
970970

971-
// Attributes for an event marking that a duration was skipped for a workflow execution,
972-
// either via manual time-skipping api call or automatic time-skipping.
971+
// Attributes for an event indicating that virtual time was advanced for a workflow execution,
972+
// either via a manual time-skipping API call or automatic time skipping.
973973
message WorkflowExecutionTimeSkippedEventAttributes {
974-
// (-- api-linter: core::0140::prepositions=disabled
975-
// aip.dev/not-precedent: "to" is used to indicate target time point. --)
976-
google.protobuf.Timestamp to_time = 1;
974+
975+
// The virtual time after time skipping is applied.
976+
google.protobuf.Timestamp target_time = 1;
977+
978+
// Indicates that time skipping was automatically disabled because a configured bound was reached.
979+
// This may occur even if no time was skipped (e.g., the workflow was already at or beyond the target time).
980+
// In such cases, `target_time` will be equal to the current virtual time.
981+
// (-- api-linter: core::0140::prepositions=disabled --)
982+
bool time_skipping_disabled_due_to_bound = 2;
983+
984+
// The wall-clock time when the time-skipping event happened.
985+
google.protobuf.Timestamp wall_clock_time = 3;
977986
}
978987

979988
// Event marking that an operation was scheduled by a workflow via the ScheduleNexusOperation command.

temporal/api/workflow/v1/message.proto

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -573,21 +573,44 @@ message WorkflowExecutionOptions {
573573
TimeSkippingConfig time_skipping_config = 3;
574574
}
575575

576-
// Configuration for automatic time skipping on a workflow execution.
577-
// Once enabled, time automatically advances when there is no in-flight
578-
// activities, child workflows, or Nexus operations.
576+
// Configuration for automatic time skipping during a workflow execution.
577+
// When enabled, virtual time advances automatically whenever there are
578+
// no in-flight activities, child workflows, or Nexus operations.
579579
message TimeSkippingConfig {
580580

581-
// If set, enables automatic time-skipping for this workflow execution.
582-
// It can also be disabled by setting this field to false.
583-
// Special attention for transitively related workflows:
584-
// - By default, Child workflows and Continue-As-New workflows will
585-
// inherit the enabled config but only at the time they are started.
586-
// - But if the enabled config is flipped after a child/continue-as-new workflow is started,
587-
// the propagation won't happen. It not recommended flip the parent's enabled config
588-
// when there are in-flight child/continue-as-new workflows.
581+
// Enables or disables automatic time skipping for this workflow execution.
582+
// By default, this field is propagated to child workflows at the time they are started.
583+
// Changes made after a child workflow has started are not propagated.
589584
bool enabled = 1;
590585

586+
// If set, the enabled field is not propagated to child workflows.
587+
bool disable_propagation = 2;
588+
589+
// Optional bound that limits how long time skipping remains active.
590+
// Once the bound is reached, time skipping is automatically disabled.
591+
// It can later be re-enabled via UpdateWorkflowExecutionOptions.
592+
//
593+
// This is particularly useful in testing scenarios where workflows
594+
// are expected to receive signals, updates, or other events while
595+
// timers are in progress.
596+
//
597+
// This bound is not propagated to child workflows.
598+
// It is recommended to set disable_propagation to true
599+
// and configure TimeSkippingConfig explicitly in child workflows.
600+
oneof bound {
601+
602+
// Maximum total virtual time that can be skipped.
603+
google.protobuf.Duration max_skipped_duration = 4;
604+
605+
// Maximum elapsed time since time skipping was enabled.
606+
// This includes both skipped time and real time elapsing.
607+
// (-- api-linter: core::0142::time-field-names=disabled --)
608+
google.protobuf.Timestamp max_elapsed_duration = 5;
609+
610+
// Absolute virtual timestamp at which time skipping is disabled.
611+
// Time skipping will not advance beyond this point.
612+
google.protobuf.Timestamp max_target_time = 6;
613+
}
591614
}
592615

593616
// Used to override the versioning behavior (and pinned deployment version, if applicable) of a

temporal/api/workflowservice/v1/request_response.proto

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2955,4 +2955,4 @@ message DeleteActivityExecutionRequest {
29552955
}
29562956

29572957
message DeleteActivityExecutionResponse {
2958-
}
2958+
}

0 commit comments

Comments
 (0)