Skip to content

api changes for time-skipping propagation #770

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
feiyang3cat wants to merge 3 commits into
base: master
Choose a base branch
from
+53 −50
Open

api changes for time-skipping propagation #770

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7583ee8
rm the flexibility of disable propagation for simplicity
feiyang3cat Apr 17, 2026
332d275
delete max target time, add comments to ts propagation
feiyang3cat Apr 23, 2026
8c1f458
comments refined
feiyang3cat Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 9 additions & 10 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17961,6 +17961,10 @@
"priority": {
"$ref": "#/definitions/v1Priority",
"title": "Priority metadata"
},
"timeSkippingConfig": {
"$ref": "#/definitions/v1TimeSkippingConfig",
"description": "The propagated time-skipping configuration for the child workflow."
}
}
},
Expand Down Expand Up @@ -18349,11 +18353,7 @@
"properties": {
"enabled": {
"type": "boolean",
"description": "Enables or disables time skipping for this workflow execution.\nBy default, this field is propagated to transitively related workflows (child workflows/start-as-new/reset) \nat the time they are started.\nChanges made after a transitively related workflow has started are not propagated."
},
"disablePropagation": {
"type": "boolean",
"description": "If set, the enabled field is not propagated to transitively related workflows."
"description": "Enables or disables time skipping for this workflow execution."
},
"maxSkippedDuration": {
"type": "string",
Expand All @@ -18363,13 +18363,12 @@
"type": "string",
"description": "Maximum elapsed time since time skipping was enabled.\nThis includes both skipped time and real time elapsing."
},
"maxTargetTime": {
"initialSkippedDuration": {
"type": "string",
"format": "date-time",
"description": "Absolute virtual timestamp at which time skipping is disabled.\nTime skipping will not advance beyond this point."
"description": "If this execution was started by a previous execution that had already skipped some time,\nit inherits the accumulated skipped duration from that execution through this field.\nThis field is set internally by the server and cannot be configured by the user."
}
},
"description": "Configuration for time skipping during a workflow execution.\nWhen enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over.\nWhen time advances, it skips to the earlier of the next user timer or the configured bound, if either exists."
"description": "Configuration for time skipping during a workflow execution.\nWhen enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over.\nWhen time advances, it skips to the earlier of the next user timer or the configured bound, if either exists.\n\nPropagation behavior of time skipping:\nThe enabled flag, bound fields, and accumulated skipped duration are propagated to related executions as follows:\n(1) Child workflows and continue-as-new: both the configuration and the accumulated skipped duration are\n inherited from the current execution. The configured bound is shared between the inherited skipped\n duration and any additional duration skipped by the new run.\n(2) Retry and cron: the configuration and accumulated skipped duration are inherited as recorded when the\n current workflow started; the accumulated skipped duration of the current run is not propagated.\n(3) Reset: the new run retains the time-skipping configuration of the current execution. Because reset replays\n all events up to the reset point and re-applies any UpdateWorkflowExecutionOptions changes made after that\n point, the resulting run ends up with the same final time-skipping configuration as the previous run."
},
"v1TimeoutFailureInfo": {
"type": "object",
Expand Down Expand Up @@ -19653,7 +19652,7 @@
},
"timeSkippingConfig": {
"$ref": "#/definitions/v1TimeSkippingConfig",
"description": "Time-skipping configuration for this workflow execution.\nIf not set, the time-skipping conf will not get updated upon request, \ni.e. the existing time-skipping conf will be preserved."
"description": "Time-skipping configuration for this workflow execution.\nIf not set, the time-skipping configuration is not updated by this request;\nthe existing configuration is preserved."
}
}
},
Expand Down
31 changes: 15 additions & 16 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15553,6 +15553,10 @@ components:
allOf:
- $ref: '#/components/schemas/Priority'
description: Priority metadata
timeSkippingConfig:
allOf:
- $ref: '#/components/schemas/TimeSkippingConfig'
description: The propagated time-skipping configuration for the child workflow.
StartNexusOperationExecutionRequest:
type: object
properties:
Expand Down Expand Up @@ -16239,10 +16243,7 @@ components:
properties:
enabled:
type: boolean
description: "Enables or disables time skipping for this workflow execution.\n By default, this field is propagated to transitively related workflows (child workflows/start-as-new/reset) \n at the time they are started.\n Changes made after a transitively related workflow has started are not propagated."
disablePropagation:
type: boolean
description: If set, the enabled field is not propagated to transitively related workflows.
description: Enables or disables time skipping for this workflow execution.
maxSkippedDuration:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
Expand All @@ -16253,19 +16254,14 @@ components:
description: |-
Maximum elapsed time since time skipping was enabled.
This includes both skipped time and real time elapsing.
maxTargetTime:
initialSkippedDuration:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: |-
Absolute virtual timestamp at which time skipping is disabled.
Time skipping will not advance beyond this point.
format: date-time
description: |-
Configuration for time skipping during a workflow execution.
When enabled, virtual time advances automatically whenever there is no in-flight work.
In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,
and possibly other features added in the future.
User timers are not classified as in-flight work and will be skipped over.
When time advances, it skips to the earlier of the next user timer or the configured bound, if either exists.
If this execution was started by a previous execution that had already skipped some time,
it inherits the accumulated skipped duration from that execution through this field.
This field is set internally by the server and cannot be configured by the user.
description: "Configuration for time skipping during a workflow execution.\n When enabled, virtual time advances automatically whenever there is no in-flight work.\n In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\n and possibly other features added in the future.\n User timers are not classified as in-flight work and will be skipped over.\n When time advances, it skips to the earlier of the next user timer or the configured bound, if either exists.\n \n Propagation behavior of time skipping:\n The enabled flag, bound fields, and accumulated skipped duration are propagated to related executions as follows:\n (1) Child workflows and continue-as-new: both the configuration and the accumulated skipped duration are\n inherited from the current execution. The configured bound is shared between the inherited skipped\n duration and any additional duration skipped by the new run.\n (2) Retry and cron: the configuration and accumulated skipped duration are inherited as recorded when the\n current workflow started; the accumulated skipped duration of the current run is not propagated.\n (3) Reset: the new run retains the time-skipping configuration of the current execution. Because reset replays\n all events up to the reset point and re-applies any UpdateWorkflowExecutionOptions changes made after that\n point, the resulting run ends up with the same final time-skipping configuration as the previous run."
TimeoutFailureInfo:
type: object
properties:
Expand Down Expand Up @@ -18215,7 +18211,10 @@ components:
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."
description: |-
Time-skipping configuration for this workflow execution.
If not set, the time-skipping configuration is not updated by this request;
the existing configuration is preserved.
WorkflowExecutionOptionsUpdatedEventAttributes:
type: object
properties:
Expand Down
3 changes: 3 additions & 0 deletions temporal/api/history/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -770,6 +770,9 @@ message StartChildWorkflowExecutionInitiatedEventAttributes {
bool inherit_build_id = 19 [deprecated = true];
// Priority metadata
temporal.api.common.v1.Priority priority = 20;

// The propagated time-skipping configuration for the child workflow.
temporal.api.workflow.v1.TimeSkippingConfig time_skipping_config = 21;
}

message StartChildWorkflowExecutionFailedEventAttributes {
Expand Down
50 changes: 26 additions & 24 deletions temporal/api/workflow/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -580,8 +580,8 @@ message WorkflowExecutionOptions {
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.
// If not set, the time-skipping configuration is not updated by this request;
// the existing configuration is preserved.
TimeSkippingConfig time_skipping_config = 3;
}

Expand All @@ -591,43 +591,45 @@ message WorkflowExecutionOptions {
// and possibly other features added in the future.
// User timers are not classified as in-flight work and will be skipped over.
// When time advances, it skips to the earlier of the next user timer or the configured bound, if either exists.
//
Copy link
Copy Markdown
Contributor Author

@feiyang3cat feiyang3cat Apr 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @yycptt added here but yet still this cannot replace the power of an educational document with examples in our web

// Propagation behavior of time skipping:
// The enabled flag, bound fields, and accumulated skipped duration are propagated to related executions as follows:
// (1) Child workflows and continue-as-new: both the configuration and the accumulated skipped duration are
// inherited from the current execution. The configured bound is shared between the inherited skipped
// duration and any additional duration skipped by the new run.
// (2) Retry and cron: the configuration and accumulated skipped duration are inherited as recorded when the
// current workflow started; the accumulated skipped duration of the current run is not propagated.
// (3) Reset: the new run retains the time-skipping configuration of the current execution. Because reset replays
// all events up to the reset point and re-applies any UpdateWorkflowExecutionOptions changes made after that
// point, the resulting run ends up with the same final time-skipping configuration as the previous run.
message TimeSkippingConfig {
Copy link
Copy Markdown
Contributor Author

@feiyang3cat feiyang3cat Apr 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these reserved ones can be removed
but buf-breaking step in Makefile:115-117 stops this kind of changes

reserved 2, 6;
reserved "disable_propagation", "max_target_time";

// Enables or disables time skipping for this workflow execution.
// By default, this field is propagated to transitively related workflows (child workflows/start-as-new/reset)
// at the time they are started.
// Changes made after a transitively related workflow has started are not propagated.
bool enabled = 1;

// If set, the enabled field is not propagated to transitively related workflows.
bool disable_propagation = 2;

// Optional bound that limits how long time skipping remains active.
// Once the bound is reached, time skipping is automatically disabled.
// It can later be re-enabled via UpdateWorkflowExecutionOptions.
//
// This is particularly useful in testing scenarios where workflows
// are expected to receive signals, updates, or other events while
// timers are in progress.
// Optional bound that limits the gap between the virtual time of this execution and wall-clock time.
// Once the bound is reached, time skipping is automatically disabled,
// but can be re-enabled by setting `enabled` to true via UpdateWorkflowExecutionOptions.
// This bound cannot be set to a value smaller than the execution's currently skipped duration.
//
// This bound is not propagated to transitively related workflows.
// When bound is also needed for transitively related workflows,
// it is recommended to set disable_propagation to true
// and configure TimeSkippingConfig explicitly for transitively related workflows.
// This is useful in testing scenarios where a workflow is expected to receive
// signals, updates, or other external events while timers are in progress.
oneof bound {

// Maximum total virtual time that can be skipped.
google.protobuf.Duration max_skipped_duration = 4;

// Maximum elapsed time since time skipping was enabled.
// This includes both skipped time and real time elapsing.
// (-- api-linter: core::0142::time-field-names=disabled --)
google.protobuf.Duration max_elapsed_duration = 5;

// Absolute virtual timestamp at which time skipping is disabled.
// Time skipping will not advance beyond this point.
google.protobuf.Timestamp max_target_time = 6;
}

// If this execution was started by a previous execution that had already skipped some time,
// it inherits the accumulated skipped duration from that execution through this field.
// This field is set internally by the server and cannot be configured by the user.
google.protobuf.Duration initial_skipped_duration = 3;
}

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