Skip to content

automatic time-skipping #740

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 1 commit into
base: master
Choose a base branch
from
+127 −2
Open

automatic time-skipping #740

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
44 changes: 42 additions & 2 deletions openapi/openapiv2.json
View file
Open in desktop

Large diffs are not rendered by default.

43 changes: 43 additions & 0 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 2 additions & 0 deletions temporal/api/enums/v1/event_type.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
14 changes: 14 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 @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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;
}
}

Expand Down
22 changes: 22 additions & 0 deletions temporal/api/workflow/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Author

@feiyang3cat feiyang3cat Mar 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

@Sushisource Hey! I've cleaned this pr and ready for review.

And this config may need special attention since it is changed significantly from previous version Chad proposed.
(1)deleted most of the fine-grained control (like max timer-firing count, max duration to skip) from the previous version. The reason is it is ambiguous when complicated configuration is propagated to child-workflows.
(2) I have also changed the nested config to one single layer because this configuration is only used for automatic time-skipping, manual time-skipping will have a separate request and response payload
(3) we allow disabling time-skipping for in-flight workflows since it is not hard for the server to have this feature, and it will be a nice-to-have feature same as the SDK TestServer.

I think we can consider wrapping up this pr early, and put manual time-skipping in a separate pr maybe.
Pls feel free to disagree, happy to refine.

// 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
Expand Down
4 changes: 4 additions & 0 deletions temporal/api/workflowservice/v1/request_response.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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 {
Expand Down
Loading