From 765fe53727868fef4f5803839253b19cb466fa15 Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Wed, 15 Jul 2026 13:19:45 -0700 Subject: [PATCH 1/2] add TimeSkippingInfo --- openapi/openapiv2.json | 43 ++++++++++++++++++++++++ openapi/openapiv3.yaml | 46 ++++++++++++++++++++++++++ temporal/api/common/v1/message.proto | 31 +++++++++++++++++ temporal/api/workflow/v1/message.proto | 3 ++ 4 files changed, 123 insertions(+) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 79cca5416..ced35e9e9 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11099,6 +11099,26 @@ }, "description": "UpdateWorkflowOptions represents updating workflow execution options after a workflow reset.\nKeep the parameters in sync with temporal.api.workflowservice.v1.UpdateWorkflowExecutionOptionsRequest." }, + "TimeSkippingInfoTimeSkippingFastForwardInfo": { + "type": "object", + "properties": { + "createTime": { + "type": "string", + "format": "date-time", + "description": "The virtual time at which the fast-forward was created." + }, + "targetTime": { + "type": "string", + "format": "date-time", + "description": "The target virtual time at which the fast-forward completes." + }, + "hasCompleted": { + "type": "boolean", + "description": "True once `target_time` has been reached." + } + }, + "description": "TimeSkippingFastForwardInfo describes the current time-skipping fast-forward on an execution." + }, "UpdateTaskQueueConfigRequestRateLimitUpdate": { "type": "object", "properties": { @@ -19790,6 +19810,25 @@ }, "description": "The configuration for time skipping of a workflow execution (a chain of runs including retries, cron, continue-as-new).\nWhen time skipping is 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; the virtual clock may also skip to the\ntime point of the registered fast forward when there is no in-flight work.\nWhen time is skipped, a WorkflowExecutionTimeSkippingTransitionedEvent will be\nadded to the workflow history to capture the state changes.\n\nFor child workflows, by default, if the parent execution is skipping time, the child execution will also skip time,\nbut a parent's fast_forward won't affect its child's execution. A flag is provided to disable propagation of the\n\"enabled\" flag to child workflows; regardless of that flag, a child workflow inherits the virtual time from the\nparent execution as its start time." }, + "v1TimeSkippingInfo": { + "type": "object", + "properties": { + "currentTime": { + "type": "string", + "format": "date-time", + "description": "Current virtual time of the execution. If the execution hasn't skipped\nany time yet, it will be the same as wall clock time." + }, + "fastForward": { + "$ref": "#/definitions/TimeSkippingInfoTimeSkippingFastForwardInfo", + "description": "The current fast-forward information of the execution. Nil if\nthe execution has no fast-forward set.\n`create_time` and `target_time` can be used to verify whether\nfast-forward configuration was overridden by another request,\nand `has_completed` shows whether the fast-forward duration has completed." + }, + "isRunning": { + "type": "boolean", + "description": "If the execution is actively trying to skip time automatically when there is a chance,\nthis field will be set to true. If time has stopped skipping either by fast-forward completion\nor user configuration, it will be false." + } + }, + "description": "Describes the current time-skipping state of a workflow execution, including its virtual\ntime, any active fast-forward, and whether it is actively skipping time." + }, "v1TimeSkippingStatePropagation": { "type": "object", "properties": { @@ -20973,6 +21012,10 @@ "pauseInfo": { "$ref": "#/definitions/v1WorkflowExecutionPauseInfo", "description": "Information about the workflow execution pause operation." + }, + "timeSkippingInfo": { + "$ref": "#/definitions/v1TimeSkippingInfo", + "description": "Information about time skipping of the workflow execution. If the execution has never enabled time skipping, it will be nil." } }, "description": "Holds all the extra information about workflow execution that is not part of Visibility." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index bd08a33cf..7469f1247 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -17573,6 +17573,48 @@ components: but a parent's fast_forward won't affect its child's execution. A flag is provided to disable propagation of the "enabled" flag to child workflows; regardless of that flag, a child workflow inherits the virtual time from the parent execution as its start time. + TimeSkippingInfo: + type: object + properties: + currentTime: + type: string + description: |- + Current virtual time of the execution. If the execution hasn't skipped + any time yet, it will be the same as wall clock time. + format: date-time + fastForward: + allOf: + - $ref: '#/components/schemas/TimeSkippingInfo_TimeSkippingFastForwardInfo' + description: |- + The current fast-forward information of the execution. Nil if + the execution has no fast-forward set. + `create_time` and `target_time` can be used to verify whether + fast-forward configuration was overridden by another request, + and `has_completed` shows whether the fast-forward duration has completed. + isRunning: + type: boolean + description: |- + If the execution is actively trying to skip time automatically when there is a chance, + this field will be set to true. If time has stopped skipping either by fast-forward completion + or user configuration, it will be false. + description: |- + Describes the current time-skipping state of a workflow execution, including its virtual + time, any active fast-forward, and whether it is actively skipping time. + TimeSkippingInfo_TimeSkippingFastForwardInfo: + type: object + properties: + createTime: + type: string + description: The virtual time at which the fast-forward was created. + format: date-time + targetTime: + type: string + description: The target virtual time at which the fast-forward completes. + format: date-time + hasCompleted: + type: boolean + description: True once `target_time` has been reached. + description: TimeSkippingFastForwardInfo describes the current time-skipping fast-forward on an execution. TimeSkippingStatePropagation: type: object properties: @@ -19516,6 +19558,10 @@ components: allOf: - $ref: '#/components/schemas/WorkflowExecutionPauseInfo' description: Information about the workflow execution pause operation. + timeSkippingInfo: + allOf: + - $ref: '#/components/schemas/TimeSkippingInfo' + description: Information about time skipping of the workflow execution. If the execution has never enabled time skipping, it will be nil. description: Holds all the extra information about workflow execution that is not part of Visibility. WorkflowExecutionFailedEventAttributes: type: object diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index a60b35fff..9c55a6818 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -444,3 +444,34 @@ message TimeSkippingStatePropagation { // the target time should be propagated to the next run as well. google.protobuf.Timestamp fast_forward_target_time = 2; } + + +// Describes the current time-skipping state of a workflow execution, including its virtual +// time, any active fast-forward, and whether it is actively skipping time. +message TimeSkippingInfo { + // Current virtual time of the execution. If the execution hasn't skipped + // any time yet, it will be the same as wall clock time. + google.protobuf.Timestamp current_time = 1; + + // The current fast-forward information of the execution. Nil if + // the execution has no fast-forward set. + // `create_time` and `target_time` can be used to verify whether + // fast-forward configuration was overridden by another request, + // and `has_completed` shows whether the fast-forward duration has completed. + TimeSkippingFastForwardInfo fast_forward = 2; + + // TimeSkippingFastForwardInfo describes the current time-skipping fast-forward on an execution. + message TimeSkippingFastForwardInfo { + // The virtual time at which the fast-forward was created. + google.protobuf.Timestamp create_time = 1; + // The target virtual time at which the fast-forward completes. + google.protobuf.Timestamp target_time = 2; + // True once `target_time` has been reached. + bool has_completed = 3; + } + + // If the execution is actively trying to skip time automatically when there is a chance, + // this field will be set to true. If time has stopped skipping either by fast-forward completion + // or user configuration, it will be false. + bool is_running = 3; +} diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index c09370f7c..23d206bb9 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -134,6 +134,9 @@ message WorkflowExecutionExtendedInfo { // Information about the workflow execution pause operation. WorkflowExecutionPauseInfo pause_info = 8; + + // Information about time skipping of the workflow execution. If the execution has never enabled time skipping, it will be nil. + temporal.api.common.v1.TimeSkippingInfo time_skipping_info = 9; } // Holds all the information about worker versioning for a particular workflow execution. From 503d8c9fa1b6cedac943734157d517d289d4afde Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Wed, 15 Jul 2026 20:20:04 -0700 Subject: [PATCH 2/2] add wait time skipping completion in describe workflow execution --- openapi/openapiv2.json | 14 ++++++++++++++ openapi/openapiv3.yaml | 16 ++++++++++++++++ .../workflowservice/v1/request_response.proto | 4 ++++ 3 files changed, 34 insertions(+) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index ced35e9e9..c7612b488 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -3993,6 +3993,13 @@ "in": "query", "required": false, "type": "string" + }, + { + "name": "waitTimeskippingCompletion", + "description": "If set, and the workflow execution has a pending time-skipping fast-forward,\nthe call blocks until that fast-forward completes or a timeout occurs.\nIf there is no pending fast-forward, this field is ignored.", + "in": "query", + "required": false, + "type": "boolean" } ], "tags": [ @@ -9527,6 +9534,13 @@ "in": "query", "required": false, "type": "string" + }, + { + "name": "waitTimeskippingCompletion", + "description": "If set, and the workflow execution has a pending time-skipping fast-forward,\nthe call blocks until that fast-forward completes or a timeout occurs.\nIf there is no pending fast-forward, this field is ignored.", + "in": "query", + "required": false, + "type": "boolean" } ], "tags": [ diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 7469f1247..8ace70934 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -3584,6 +3584,14 @@ paths: in: query schema: type: string + - name: waitTimeskippingCompletion + in: query + description: |- + If set, and the workflow execution has a pending time-skipping fast-forward, + the call blocks until that fast-forward completes or a timeout occurs. + If there is no pending fast-forward, this field is ignored. + schema: + type: boolean responses: "200": description: OK @@ -8580,6 +8588,14 @@ paths: in: query schema: type: string + - name: waitTimeskippingCompletion + in: query + description: |- + If set, and the workflow execution has a pending time-skipping fast-forward, + the call blocks until that fast-forward completes or a timeout occurs. + If there is no pending fast-forward, this field is ignored. + schema: + type: boolean responses: "200": description: OK diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 3d701f317..15aea8de9 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1192,6 +1192,10 @@ message QueryWorkflowResponse { message DescribeWorkflowExecutionRequest { string namespace = 1; temporal.api.common.v1.WorkflowExecution execution = 2; + // If set, and the workflow execution has a pending time-skipping fast-forward, + // the call blocks until that fast-forward completes or a timeout occurs. + // If there is no pending fast-forward, this field is ignored. + bool wait_timeskipping_completion = 3; } message DescribeWorkflowExecutionResponse {