From 5ea060efbaba3aecf9c36ea75a3cd32df2088e5d Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Sun, 19 Jul 2026 14:01:32 -0700 Subject: [PATCH 1/6] add max_skip_count and change comments of TimeSkippingConfig --- openapi/openapiv2.json | 9 ++++-- openapi/openapiv3.yaml | 43 +++++++++++++++++----------- temporal/api/common/v1/message.proto | 41 +++++++++++++++----------- 3 files changed, 57 insertions(+), 36 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3eeda5de9..7d77698b7 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -19890,14 +19890,19 @@ }, "fastForward": { "type": "string", - "description": "Optionally fast-forward the current workflow execution by this duration ahead of current workflow execution time.\nAfter the fast-forward completes, time skipping is disabled, and this\naction is recorded in the WorkflowExecutionTimeSkippingTransitionedEvent. It can be re-enabled by\nsetting `enabled` to true or setting `fast_forward` again via UpdateWorkflowExecutionOptions.\nThe current workflow execution is a chain of runs (retries, cron, continue-as-new);\nchild workflows are separate executions, so this fast_forward won't affect them.\n\nFor a given workflow execution, only one active fast-forward is allowed at a time.\nIf a new fast-forward is set via UpdateWorkflowExecutionOptions before the previous\none completes, the new one will override the previous one.\nIf the fast-forward duration exceeds the remaining execution timeout, time will only\nbe fast-forwarded up to the end of the execution." + "description": "Optionally fast-forward the current execution by this duration ahead of current workflow time.\nAfter the fast-forward completes, time skipping is disabled. And it can be re-enabled by calling\nan update API with the time-skipping opt-in.\n\nFor a given execution, only one active fast-forward is allowed at a time.\nIf a new fast-forward is set via an update call before the previous\none completes, the new one will override the previous one.\nIf the fast-forward duration exceeds the remaining execution timeout, time will not\npass beyond the end of the execution, and fast_forward won't have a chance to complete." }, "disablePropagation": { "type": "boolean", "description": "By default, executions started by another execution (e.g. a child workflow of a parent workflow or\na schedule with the timeskipping policy enabled), inherit the \"enabled\" flag and skip time when possible.\nThis flag disables that inheritance." + }, + "maxSkipCount": { + "type": "integer", + "format": "int32", + "description": "The maximum skip count allowed after time skipping is enabled. It is used to protect the current execution\nfrom unlimited retries when backoff is skipped. Every time the execution skips some time,\nthe skip count is incremented by one, and when it reaches max_skip_count, time skipping will be disabled.\n\nIf the field is not set, a large default value (e.g. 100) will be set by the server.\nThe default value can be changed through dynamic config, and can be overridden by this field if set." } }, - "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." + "description": "The configuration for time skipping of an execution.\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nOptions like fast_forward, disable_propagation, and max_skip_count are provided for granular\ncontrol of the execution's time skipping behavior. See each field's comment for a detailed explanation.\n\nAn example of workflows with time skipping:\nFor workflows, an execution is a chain of runs including retries, cron, and continue-as-new.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc.\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.\nEvery time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled.\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." }, "v1TimeSkippingStatePropagation": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 71e444e29..eb08b85ed 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -17655,34 +17655,43 @@ components: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: |- - Optionally fast-forward the current workflow execution by this duration ahead of current workflow execution time. - After the fast-forward completes, time skipping is disabled, and this - action is recorded in the WorkflowExecutionTimeSkippingTransitionedEvent. It can be re-enabled by - setting `enabled` to true or setting `fast_forward` again via UpdateWorkflowExecutionOptions. - The current workflow execution is a chain of runs (retries, cron, continue-as-new); - child workflows are separate executions, so this fast_forward won't affect them. + Optionally fast-forward the current execution by this duration ahead of current workflow time. + After the fast-forward completes, time skipping is disabled. And it can be re-enabled by calling + an update API with the time-skipping opt-in. - For a given workflow execution, only one active fast-forward is allowed at a time. - If a new fast-forward is set via UpdateWorkflowExecutionOptions before the previous + For a given execution, only one active fast-forward is allowed at a time. + If a new fast-forward is set via an update call before the previous one completes, the new one will override the previous one. - If the fast-forward duration exceeds the remaining execution timeout, time will only - be fast-forwarded up to the end of the execution. + If the fast-forward duration exceeds the remaining execution timeout, time will not + pass beyond the end of the execution, and fast_forward won't have a chance to complete. disablePropagation: type: boolean description: |- By default, executions started by another execution (e.g. a child workflow of a parent workflow or a schedule with the timeskipping policy enabled), inherit the "enabled" flag and skip time when possible. This flag disables that inheritance. + maxSkipCount: + type: integer + description: |- + The maximum skip count allowed after time skipping is enabled. It is used to protect the current execution + from unlimited retries when backoff is skipped. Every time the execution skips some time, + the skip count is incremented by one, and when it reaches max_skip_count, time skipping will be disabled. + + If the field is not set, a large default value (e.g. 100) will be set by the server. + The default value can be changed through dynamic config, and can be overridden by this field if set. + format: int32 description: |- - The configuration for time skipping of a workflow execution (a chain of runs including retries, cron, continue-as-new). + The configuration for time skipping of an execution. When time skipping is 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; the virtual clock may also skip to the - time point of the registered fast forward when there is no in-flight work. - When time is skipped, a WorkflowExecutionTimeSkippingTransitionedEvent will be - added to the workflow history to capture the state changes. + Options like fast_forward, disable_propagation, and max_skip_count are provided for granular + control of the execution's time skipping behavior. See each field's comment for a detailed explanation. + An example of workflows with time skipping: + For workflows, an execution is a chain of runs including retries, cron, and continue-as-new. + In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc. + User timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the + time point of the registered fast-forward when there is no in-flight work. + Every time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled. For child workflows, by default, if the parent execution is skipping time, the child execution will also skip time, 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 diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 1af5b4acc..07d904025 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -403,15 +403,17 @@ message OnConflictOptions { bool attach_links = 3; } -// The configuration for time skipping of a workflow execution (a chain of runs including retries, cron, continue-as-new). +// The configuration for time skipping of an execution. // When time skipping is 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; the virtual clock may also skip to the -// time point of the registered fast forward when there is no in-flight work. -// When time is skipped, a WorkflowExecutionTimeSkippingTransitionedEvent will be -// added to the workflow history to capture the state changes. +// Options like fast_forward, disable_propagation, and max_skip_count are provided for granular +// control of the execution's time skipping behavior. See each field's comment for a detailed explanation. // +// An example of workflows with time skipping: +// For workflows, an execution is a chain of runs including retries, cron, and continue-as-new. +// In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc. +// User timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the +// time point of the registered fast-forward when there is no in-flight work. +// Every time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled. // For child workflows, by default, if the parent execution is skipping time, the child execution will also skip time, // 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 @@ -420,24 +422,29 @@ message TimeSkippingConfig { // Enables or disables time skipping for this workflow execution. bool enabled = 1; - // Optionally fast-forward the current workflow execution by this duration ahead of current workflow execution time. - // After the fast-forward completes, time skipping is disabled, and this - // action is recorded in the WorkflowExecutionTimeSkippingTransitionedEvent. It can be re-enabled by - // setting `enabled` to true or setting `fast_forward` again via UpdateWorkflowExecutionOptions. - // The current workflow execution is a chain of runs (retries, cron, continue-as-new); - // child workflows are separate executions, so this fast_forward won't affect them. + // Optionally fast-forward the current execution by this duration ahead of current workflow time. + // After the fast-forward completes, time skipping is disabled. And it can be re-enabled by calling + // an update API with the time-skipping opt-in. // - // For a given workflow execution, only one active fast-forward is allowed at a time. - // If a new fast-forward is set via UpdateWorkflowExecutionOptions before the previous + // For a given execution, only one active fast-forward is allowed at a time. + // If a new fast-forward is set via an update call before the previous // one completes, the new one will override the previous one. - // If the fast-forward duration exceeds the remaining execution timeout, time will only - // be fast-forwarded up to the end of the execution. + // If the fast-forward duration exceeds the remaining execution timeout, time will not + // pass beyond the end of the execution, and fast_forward won't have a chance to complete. google.protobuf.Duration fast_forward = 2; // By default, executions started by another execution (e.g. a child workflow of a parent workflow or // a schedule with the timeskipping policy enabled), inherit the "enabled" flag and skip time when possible. // This flag disables that inheritance. bool disable_propagation = 3; + + // The maximum skip count allowed after time skipping is enabled. It is used to protect the current execution + // from unlimited retries when backoff is skipped. Every time the execution skips some time, + // the skip count is incremented by one, and when it reaches max_skip_count, time skipping will be disabled. + // + // If the field is not set, a large default value (e.g. 100) will be set by the server. + // The default value can be changed through dynamic config, and can be overridden by this field if set. + int32 max_skip_count = 4; } // The time-skipping state that needs to be propagated from a parent workflow to a child workflow, From 0eca82ac43457a2b493b31384f4ff66c90b0538b Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Sun, 19 Jul 2026 14:47:06 -0700 Subject: [PATCH 2/6] add TimeSkippingInfo to WorkflowExecutionExtendedInfo, add poll api --- openapi/openapiv2.json | 147 ++++++++++++++++++ openapi/openapiv3.yaml | 135 ++++++++++++++++ temporal/api/common/v1/message.proto | 24 +++ temporal/api/workflow/v1/message.proto | 4 + .../workflowservice/v1/request_response.proto | 25 +++ temporal/api/workflowservice/v1/service.proto | 17 ++ 6 files changed, 352 insertions(+) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 7d77698b7..fea8d2375 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -4427,6 +4427,49 @@ ] } }, + "/api/v1/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/time-skipping/poll": { + "get": { + "summary": "PollWorkflowExecutionTimeSkipping long-polls until the time-skipping state of a workflow\nexecution changes (its time-skipping config is updated or an active fast-forward completes),\nthen returns the reason and the current fast-forward info. It lets callers observe fast-forward\nprogress without busy-polling.", + "operationId": "PollWorkflowExecutionTimeSkipping2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PollWorkflowExecutionTimeSkippingResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "workflowExecution.workflowId", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "workflowExecution.runId", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/update-options": { "post": { "summary": "UpdateWorkflowExecutionOptions partially updates the WorkflowExecutionOptions of an existing workflow execution.", @@ -9961,6 +10004,49 @@ ] } }, + "/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/time-skipping/poll": { + "get": { + "summary": "PollWorkflowExecutionTimeSkipping long-polls until the time-skipping state of a workflow\nexecution changes (its time-skipping config is updated or an active fast-forward completes),\nthen returns the reason and the current fast-forward info. It lets callers observe fast-forward\nprogress without busy-polling.", + "operationId": "PollWorkflowExecutionTimeSkipping", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PollWorkflowExecutionTimeSkippingResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "workflowExecution.workflowId", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "workflowExecution.runId", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/update-options": { "post": { "summary": "UpdateWorkflowExecutionOptions partially updates the WorkflowExecutionOptions of an existing workflow execution.", @@ -11059,6 +11145,16 @@ } } }, + "PollWorkflowExecutionTimeSkippingResponseReturnReason": { + "type": "string", + "enum": [ + "RETURN_REASON_UNSPECIFIED", + "RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED", + "RETURN_REASON_FAST_FORWARD_COMPLETED" + ], + "default": "RETURN_REASON_UNSPECIFIED", + "description": "Why the poll returned.\n\n - RETURN_REASON_UNSPECIFIED: The poll returned because its server-side timeout elapsed without any change. The caller\nmay poll again.\n - RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED: The execution's time-skipping config was updated.\n - RETURN_REASON_FAST_FORWARD_COMPLETED: The active fast-forward reached its target time and completed." + }, "PostResetOperationSignalWorkflow": { "type": "object", "properties": { @@ -17967,6 +18063,18 @@ } } }, + "v1PollWorkflowExecutionTimeSkippingResponse": { + "type": "object", + "properties": { + "reason": { + "$ref": "#/definitions/PollWorkflowExecutionTimeSkippingResponseReturnReason" + }, + "fastForwardInfo": { + "$ref": "#/definitions/v1TimeSkippingFastForwardInfo", + "description": "The current fast-forward on the execution, if any." + } + } + }, "v1PollWorkflowTaskQueueResponse": { "type": "object", "properties": { @@ -19904,6 +20012,41 @@ }, "description": "The configuration for time skipping of an execution.\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nOptions like fast_forward, disable_propagation, and max_skip_count are provided for granular\ncontrol of the execution's time skipping behavior. See each field's comment for a detailed explanation.\n\nAn example of workflows with time skipping:\nFor workflows, an execution is a chain of runs including retries, cron, and continue-as-new.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc.\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.\nEvery time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled.\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." }, + "v1TimeSkippingFastForwardInfo": { + "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." + }, + "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." + }, + "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,\nmax skip allowed checking, or user configuration, it will be false." + } + }, + "description": "Describes the current time-skipping state of a workflow execution." + }, "v1TimeSkippingStatePropagation": { "type": "object", "properties": { @@ -21087,6 +21230,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.\nIf 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 eb08b85ed..be7e6920d 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -4572,6 +4572,48 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/time-skipping/poll: + get: + tags: + - WorkflowService + description: |- + PollWorkflowExecutionTimeSkipping long-polls until the time-skipping state of a workflow + execution changes (its time-skipping config is updated or an active fast-forward completes), + then returns the reason and the current fast-forward info. It lets callers observe fast-forward + progress without busy-polling. + operationId: PollWorkflowExecutionTimeSkipping + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: workflow_execution.workflow_id + in: path + required: true + schema: + type: string + - name: workflowExecution.workflowId + in: query + schema: + type: string + - name: workflowExecution.runId + in: query + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollWorkflowExecutionTimeSkippingResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/update-options: post: tags: @@ -9568,6 +9610,48 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/time-skipping/poll: + get: + tags: + - WorkflowService + description: |- + PollWorkflowExecutionTimeSkipping long-polls until the time-skipping state of a workflow + execution changes (its time-skipping config is updated or an active fast-forward completes), + then returns the reason and the current fast-forward info. It lets callers observe fast-forward + progress without busy-polling. + operationId: PollWorkflowExecutionTimeSkipping + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: workflow_execution.workflow_id + in: path + required: true + schema: + type: string + - name: workflowExecution.workflowId + in: query + schema: + type: string + - name: workflowExecution.runId + in: query + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollWorkflowExecutionTimeSkippingResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/update-options: post: tags: @@ -14391,6 +14475,20 @@ components: allOf: - $ref: '#/components/schemas/Failure' description: The failure if the operation completed unsuccessfully. + PollWorkflowExecutionTimeSkippingResponse: + type: object + properties: + reason: + enum: + - RETURN_REASON_UNSPECIFIED + - RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED + - RETURN_REASON_FAST_FORWARD_COMPLETED + type: string + format: enum + fastForwardInfo: + allOf: + - $ref: '#/components/schemas/TimeSkippingFastForwardInfo' + description: The current fast-forward on the execution, if any. PollWorkflowTaskQueueResponse: type: object properties: @@ -17696,6 +17794,37 @@ 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. + 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. + 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 + 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, + max skip allowed checking, or user configuration, it will be false. + description: Describes the current time-skipping state of a workflow execution. TimeSkippingStatePropagation: type: object properties: @@ -19639,6 +19768,12 @@ 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 07d904025..dd9c66457 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -459,3 +459,27 @@ 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. +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; + + // 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, + // max skip allowed checking, or user configuration, it will be false. + bool is_running = 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; +} diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index c09370f7c..1ed33fa4c 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -134,6 +134,10 @@ 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. diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 66f478c5c..bf58201af 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3634,3 +3634,28 @@ message DeleteNexusOperationExecutionRequest { message DeleteNexusOperationExecutionResponse { } + + +// A long-poll request that blocks until the time-skipping state of an execution changes, so callers +// can observe fast-forward progress and time-skipping config updates without busy-polling. +message PollWorkflowExecutionTimeSkippingRequest { + string namespace = 1; + temporal.api.common.v1.WorkflowExecution workflow_execution = 2; +} + +message PollWorkflowExecutionTimeSkippingResponse { + // Why the poll returned. + enum ReturnReason { + // The poll returned because its server-side timeout elapsed without any change. The caller + // may poll again. + RETURN_REASON_UNSPECIFIED = 0; + // The execution's time-skipping config was updated. + RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED = 1; + // The active fast-forward reached its target time and completed. + RETURN_REASON_FAST_FORWARD_COMPLETED = 2; + } + ReturnReason reason = 1; + + // The current fast-forward on the execution, if any. + temporal.api.common.v1.TimeSkippingFastForwardInfo fast_forward_info = 2; +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index bec02b9e5..97a26e3d7 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -2039,4 +2039,21 @@ service WorkflowService { // (-- api-linter: core::0127::http-annotation=disabled // aip.dev/not-precedent: Nexus operation deletion not exposed to HTTP, users should use cancel or terminate. --) rpc DeleteNexusOperationExecution (DeleteNexusOperationExecutionRequest) returns (DeleteNexusOperationExecutionResponse) {} + + // PollWorkflowExecutionTimeSkipping long-polls until the time-skipping state of a workflow + // execution changes (its time-skipping config is updated or an active fast-forward completes), + // then returns the reason and the current fast-forward info. It lets callers observe fast-forward + // progress without busy-polling. + rpc PollWorkflowExecutionTimeSkipping (PollWorkflowExecutionTimeSkippingRequest) returns (PollWorkflowExecutionTimeSkippingResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/time-skipping/poll" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/time-skipping/poll" + } + }; + option (temporal.api.protometa.v1.request_header) = { + header: "temporal-resource-id" + value: "workflow:{workflow_execution.workflow_id}" + }; + } } From fe7c9938cf11acc2d2f0c4dbcea6f1076234a885 Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Sun, 19 Jul 2026 16:46:36 -0700 Subject: [PATCH 3/6] add initial_skip_count to TimeSkippingStatePropagation and refine comments --- openapi/openapiv2.json | 13 +++++++++---- openapi/openapiv3.yaml | 24 ++++++++++++++---------- temporal/api/common/v1/message.proto | 22 +++++++++++++--------- 3 files changed, 36 insertions(+), 23 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index fea8d2375..8729ed986 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -20007,7 +20007,7 @@ "maxSkipCount": { "type": "integer", "format": "int32", - "description": "The maximum skip count allowed after time skipping is enabled. It is used to protect the current execution\nfrom unlimited retries when backoff is skipped. Every time the execution skips some time,\nthe skip count is incremented by one, and when it reaches max_skip_count, time skipping will be disabled.\n\nIf the field is not set, a large default value (e.g. 100) will be set by the server.\nThe default value can be changed through dynamic config, and can be overridden by this field if set." + "description": "The maximum skip count allowed after time skipping is enabled for an execution.\nIt protects the current execution from unlimited retries when backoff is skipped.\nEvery time the execution skips some time, the skip count is incremented by one,\nand when it reaches max_skip_count, time skipping is disabled.\nFor an execution with a chain of runs, the count is accumulated across all runs.\n\nIf the field is not set, a large default value (e.g. 100) will be set by the server.\nThe default value can be changed through dynamic config, and can be overridden by this field if set." } }, "description": "The configuration for time skipping of an execution.\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nOptions like fast_forward, disable_propagation, and max_skip_count are provided for granular\ncontrol of the execution's time skipping behavior. See each field's comment for a detailed explanation.\n\nAn example of workflows with time skipping:\nFor workflows, an execution is a chain of runs including retries, cron, and continue-as-new.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc.\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.\nEvery time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled.\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." @@ -20052,15 +20052,20 @@ "properties": { "initialSkippedDuration": { "type": "string", - "description": "The time skipped by the previous execution that started this workflow.\nIt can happen in child workflows and a chain of runs (CaN, cron, retry)." + "description": "The time skipped by the previous run. It is propagated both to executions started by the\ncurrent execution and through a chain of runs (CaN, cron, retry)." }, "fastForwardTargetTime": { "type": "string", "format": "date-time", - "description": "If there is a fast-forward action set for the previous run in a chain of runs,\nthe target time should be propagated to the next run as well." + "description": "The fast-forward target time. It only propagates across a chain of runs within the same execution." + }, + "initialSkipCount": { + "type": "integer", + "format": "int32", + "description": "The initial skip count. It only propagates across a chain of runs within the same execution." } }, - "description": "The time-skipping state that needs to be propagated from a parent workflow to a child workflow,\nor through a chain of runs." + "description": "The time-skipping state that needs to be propagated from one execution to another, or through a chain of runs\nwithin the same execution." }, "v1TimeoutFailureInfo": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index be7e6920d..e93235ea8 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -17771,9 +17771,11 @@ components: maxSkipCount: type: integer description: |- - The maximum skip count allowed after time skipping is enabled. It is used to protect the current execution - from unlimited retries when backoff is skipped. Every time the execution skips some time, - the skip count is incremented by one, and when it reaches max_skip_count, time skipping will be disabled. + The maximum skip count allowed after time skipping is enabled for an execution. + It protects the current execution from unlimited retries when backoff is skipped. + Every time the execution skips some time, the skip count is incremented by one, + and when it reaches max_skip_count, time skipping is disabled. + For an execution with a chain of runs, the count is accumulated across all runs. If the field is not set, a large default value (e.g. 100) will be set by the server. The default value can be changed through dynamic config, and can be overridden by this field if set. @@ -17832,17 +17834,19 @@ components: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: |- - The time skipped by the previous execution that started this workflow. - It can happen in child workflows and a chain of runs (CaN, cron, retry). + The time skipped by the previous run. It is propagated both to executions started by the + current execution and through a chain of runs (CaN, cron, retry). fastForwardTargetTime: type: string - description: |- - If there is a fast-forward action set for the previous run in a chain of runs, - the target time should be propagated to the next run as well. + description: The fast-forward target time. It only propagates across a chain of runs within the same execution. format: date-time + initialSkipCount: + type: integer + description: The initial skip count. It only propagates across a chain of runs within the same execution. + format: int32 description: |- - The time-skipping state that needs to be propagated from a parent workflow to a child workflow, - or through a chain of runs. + The time-skipping state that needs to be propagated from one execution to another, or through a chain of runs + within the same execution. TimeoutFailureInfo: type: object properties: diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index dd9c66457..091546956 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -438,26 +438,30 @@ message TimeSkippingConfig { // This flag disables that inheritance. bool disable_propagation = 3; - // The maximum skip count allowed after time skipping is enabled. It is used to protect the current execution - // from unlimited retries when backoff is skipped. Every time the execution skips some time, - // the skip count is incremented by one, and when it reaches max_skip_count, time skipping will be disabled. + // The maximum skip count allowed after time skipping is enabled for an execution. + // It protects the current execution from unlimited retries when backoff is skipped. + // Every time the execution skips some time, the skip count is incremented by one, + // and when it reaches max_skip_count, time skipping is disabled. + // For an execution with a chain of runs, the count is accumulated across all runs. // // If the field is not set, a large default value (e.g. 100) will be set by the server. // The default value can be changed through dynamic config, and can be overridden by this field if set. int32 max_skip_count = 4; } -// The time-skipping state that needs to be propagated from a parent workflow to a child workflow, -// or through a chain of runs. +// The time-skipping state that needs to be propagated from one execution to another, or through a chain of runs +// within the same execution. message TimeSkippingStatePropagation { - // The time skipped by the previous execution that started this workflow. - // It can happen in child workflows and a chain of runs (CaN, cron, retry). + // The time skipped by the previous run. It is propagated both to executions started by the + // current execution and through a chain of runs (CaN, cron, retry). google.protobuf.Duration initial_skipped_duration = 1; - // If there is a fast-forward action set for the previous run in a chain of runs, - // the target time should be propagated to the next run as well. + // The fast-forward target time. It only propagates across a chain of runs within the same execution. google.protobuf.Timestamp fast_forward_target_time = 2; + + // The initial skip count. It only propagates across a chain of runs within the same execution. + int32 initial_skip_count = 3; } From 62c79a00c79a8af12150c2943fa8071f600d23fc Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Sun, 19 Jul 2026 18:19:28 -0700 Subject: [PATCH 4/6] rename PollWorkflowExecutionTimeSkippingResponse fields --- openapi/openapiv2.json | 20 ++++++++------- openapi/openapiv3.yaml | 14 +++++++---- .../workflowservice/v1/request_response.proto | 25 +++++++++++-------- 3 files changed, 34 insertions(+), 25 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 8729ed986..83e49c69a 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11145,15 +11145,16 @@ } } }, - "PollWorkflowExecutionTimeSkippingResponseReturnReason": { + "PollWorkflowExecutionTimeSkippingResponseResult": { "type": "string", "enum": [ - "RETURN_REASON_UNSPECIFIED", - "RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED", - "RETURN_REASON_FAST_FORWARD_COMPLETED" + "RESULT_UNSPECIFIED", + "RESULT_TIMESKIPPING_CONFIG_UPDATED", + "RESULT_FAST_FORWARD_COMPLETED", + "RESULT_NO_PENDING_FAST_FORWARD" ], - "default": "RETURN_REASON_UNSPECIFIED", - "description": "Why the poll returned.\n\n - RETURN_REASON_UNSPECIFIED: The poll returned because its server-side timeout elapsed without any change. The caller\nmay poll again.\n - RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED: The execution's time-skipping config was updated.\n - RETURN_REASON_FAST_FORWARD_COMPLETED: The active fast-forward reached its target time and completed." + "default": "RESULT_UNSPECIFIED", + "description": " - RESULT_UNSPECIFIED: The poll timed out server-side before any time-skipping state change occurred to fast forward.\nThe caller may poll again.\n - RESULT_TIMESKIPPING_CONFIG_UPDATED: The execution's time-skipping config changed while the poll was waiting.\n - RESULT_FAST_FORWARD_COMPLETED: The fast-forward that was active when the poll started reached its target time and completed.\n - RESULT_NO_PENDING_FAST_FORWARD: No fast-forward was in progress when the poll started, so there was nothing to wait for." }, "PostResetOperationSignalWorkflow": { "type": "object", @@ -18066,12 +18067,13 @@ "v1PollWorkflowExecutionTimeSkippingResponse": { "type": "object", "properties": { - "reason": { - "$ref": "#/definitions/PollWorkflowExecutionTimeSkippingResponseReturnReason" + "result": { + "$ref": "#/definitions/PollWorkflowExecutionTimeSkippingResponseResult", + "description": "The result of this poll." }, "fastForwardInfo": { "$ref": "#/definitions/v1TimeSkippingFastForwardInfo", - "description": "The current fast-forward on the execution, if any." + "description": "The execution's most recent fast-forward, whether it is still pending or already completed.\nUnset only if the execution has never had a fast-forward." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index e93235ea8..fa3794bdb 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -14478,17 +14478,21 @@ components: PollWorkflowExecutionTimeSkippingResponse: type: object properties: - reason: + result: enum: - - RETURN_REASON_UNSPECIFIED - - RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED - - RETURN_REASON_FAST_FORWARD_COMPLETED + - RESULT_UNSPECIFIED + - RESULT_TIMESKIPPING_CONFIG_UPDATED + - RESULT_FAST_FORWARD_COMPLETED + - RESULT_NO_PENDING_FAST_FORWARD type: string + description: The result of this poll. format: enum fastForwardInfo: allOf: - $ref: '#/components/schemas/TimeSkippingFastForwardInfo' - description: The current fast-forward on the execution, if any. + description: |- + The execution's most recent fast-forward, whether it is still pending or already completed. + Unset only if the execution has never had a fast-forward. PollWorkflowTaskQueueResponse: type: object properties: diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index bf58201af..3c2d48b01 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3644,18 +3644,21 @@ message PollWorkflowExecutionTimeSkippingRequest { } message PollWorkflowExecutionTimeSkippingResponse { - // Why the poll returned. - enum ReturnReason { - // The poll returned because its server-side timeout elapsed without any change. The caller - // may poll again. - RETURN_REASON_UNSPECIFIED = 0; - // The execution's time-skipping config was updated. - RETURN_REASON_TIMESKIPPING_CONFIG_UPDATED = 1; - // The active fast-forward reached its target time and completed. - RETURN_REASON_FAST_FORWARD_COMPLETED = 2; + enum Result { + // The poll timed out server-side before any time-skipping state change occurred to fast forward. + // The caller may poll again. + RESULT_UNSPECIFIED = 0; + // The execution's time-skipping config changed while the poll was waiting. + RESULT_TIMESKIPPING_CONFIG_UPDATED = 1; + // The fast-forward that was active when the poll started reached its target time and completed. + RESULT_FAST_FORWARD_COMPLETED = 2; + // No fast-forward was in progress when the poll started, so there was nothing to wait for. + RESULT_NO_PENDING_FAST_FORWARD = 3; } - ReturnReason reason = 1; + // The result of this poll. + Result result = 1; - // The current fast-forward on the execution, if any. + // The execution's most recent fast-forward, whether it is still pending or already completed. + // Unset only if the execution has never had a fast-forward. temporal.api.common.v1.TimeSkippingFastForwardInfo fast_forward_info = 2; } From a22f9fc26f1475ddde2a27c45e6c5b47155f2f9d Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Sun, 19 Jul 2026 18:37:20 -0700 Subject: [PATCH 5/6] rename max_skip_per_session, add RESULT_WORKFLOW_ENDED --- openapi/openapiv2.json | 6 ++--- openapi/openapiv3.yaml | 23 +++++++++++-------- temporal/api/common/v1/message.proto | 23 +++++++++++-------- .../workflowservice/v1/request_response.proto | 3 +++ 4 files changed, 32 insertions(+), 23 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 83e49c69a..3afe05733 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -20006,13 +20006,13 @@ "type": "boolean", "description": "By default, executions started by another execution (e.g. a child workflow of a parent workflow or\na schedule with the timeskipping policy enabled), inherit the \"enabled\" flag and skip time when possible.\nThis flag disables that inheritance." }, - "maxSkipCount": { + "maxSkipPerSession": { "type": "integer", "format": "int32", - "description": "The maximum skip count allowed after time skipping is enabled for an execution.\nIt protects the current execution from unlimited retries when backoff is skipped.\nEvery time the execution skips some time, the skip count is incremented by one,\nand when it reaches max_skip_count, time skipping is disabled.\nFor an execution with a chain of runs, the count is accumulated across all runs.\n\nIf the field is not set, a large default value (e.g. 100) will be set by the server.\nThe default value can be changed through dynamic config, and can be overridden by this field if set." + "description": "The maximum number of skips allowed within a single time-skipping session, where a session\nruns from when time skipping is enabled until it is disabled. It protects the execution from\nunlimited retries when backoff is skipped.\nEvery time the execution skips time, the skip count is incremented by one, and when it reaches\nmax_skip_per_session, time skipping is disabled.\nFor an execution with a chain of runs (retry, cron, continue-as-new), the count is accumulated\nacross all runs within the same session. The count resets to 0 at the start of each new session,\ni.e. each time this config is updated to re-enable time skipping.\n\nIf this field is not set, the server applies a large default value (e.g. 100). The default can\nbe changed through dynamic config, and is overridden by this field when set." } }, - "description": "The configuration for time skipping of an execution.\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nOptions like fast_forward, disable_propagation, and max_skip_count are provided for granular\ncontrol of the execution's time skipping behavior. See each field's comment for a detailed explanation.\n\nAn example of workflows with time skipping:\nFor workflows, an execution is a chain of runs including retries, cron, and continue-as-new.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc.\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.\nEvery time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled.\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." + "description": "The configuration for time skipping of an execution.\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nOptions like fast_forward, disable_propagation, and max_skip_per_session are provided for granular\ncontrol of the execution's time skipping behavior. See each field's comment for a detailed explanation.\n\nAn example of workflows with time skipping:\nFor workflows, an execution is a chain of runs including retries, cron, and continue-as-new.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc.\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.\nEvery time time is skipped, the skip count is incremented by one; max_skip_per_session bounds the number of skips allowed within a single time-skipping session.\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." }, "v1TimeSkippingFastForwardInfo": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index fa3794bdb..b41fda380 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -17772,22 +17772,25 @@ components: By default, executions started by another execution (e.g. a child workflow of a parent workflow or a schedule with the timeskipping policy enabled), inherit the "enabled" flag and skip time when possible. This flag disables that inheritance. - maxSkipCount: + maxSkipPerSession: type: integer description: |- - The maximum skip count allowed after time skipping is enabled for an execution. - It protects the current execution from unlimited retries when backoff is skipped. - Every time the execution skips some time, the skip count is incremented by one, - and when it reaches max_skip_count, time skipping is disabled. - For an execution with a chain of runs, the count is accumulated across all runs. + The maximum number of skips allowed within a single time-skipping session, where a session + runs from when time skipping is enabled until it is disabled. It protects the execution from + unlimited retries when backoff is skipped. + Every time the execution skips time, the skip count is incremented by one, and when it reaches + max_skip_per_session, time skipping is disabled. + For an execution with a chain of runs (retry, cron, continue-as-new), the count is accumulated + across all runs within the same session. The count resets to 0 at the start of each new session, + i.e. each time this config is updated to re-enable time skipping. - If the field is not set, a large default value (e.g. 100) will be set by the server. - The default value can be changed through dynamic config, and can be overridden by this field if set. + If this field is not set, the server applies a large default value (e.g. 100). The default can + be changed through dynamic config, and is overridden by this field when set. format: int32 description: |- The configuration for time skipping of an execution. When time skipping is enabled, virtual time advances automatically whenever there is no in-flight work. - Options like fast_forward, disable_propagation, and max_skip_count are provided for granular + Options like fast_forward, disable_propagation, and max_skip_per_session are provided for granular control of the execution's time skipping behavior. See each field's comment for a detailed explanation. An example of workflows with time skipping: @@ -17795,7 +17798,7 @@ components: In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc. User timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the time point of the registered fast-forward when there is no in-flight work. - Every time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled. + Every time time is skipped, the skip count is incremented by one; max_skip_per_session bounds the number of skips allowed within a single time-skipping session. For child workflows, by default, if the parent execution is skipping time, the child execution will also skip time, 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 diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 091546956..04dba0f46 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -405,7 +405,7 @@ message OnConflictOptions { // The configuration for time skipping of an execution. // When time skipping is enabled, virtual time advances automatically whenever there is no in-flight work. -// Options like fast_forward, disable_propagation, and max_skip_count are provided for granular +// Options like fast_forward, disable_propagation, and max_skip_per_session are provided for granular // control of the execution's time skipping behavior. See each field's comment for a detailed explanation. // // An example of workflows with time skipping: @@ -413,7 +413,7 @@ message OnConflictOptions { // In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc. // User timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the // time point of the registered fast-forward when there is no in-flight work. -// Every time time is skipped, the skip count is incremented by one, and a maximum skip count is allowed each time time skipping is enabled. +// Every time time is skipped, the skip count is incremented by one; max_skip_per_session bounds the number of skips allowed within a single time-skipping session. // For child workflows, by default, if the parent execution is skipping time, the child execution will also skip time, // 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 @@ -438,15 +438,18 @@ message TimeSkippingConfig { // This flag disables that inheritance. bool disable_propagation = 3; - // The maximum skip count allowed after time skipping is enabled for an execution. - // It protects the current execution from unlimited retries when backoff is skipped. - // Every time the execution skips some time, the skip count is incremented by one, - // and when it reaches max_skip_count, time skipping is disabled. - // For an execution with a chain of runs, the count is accumulated across all runs. + // The maximum number of skips allowed within a single time-skipping session, where a session + // runs from when time skipping is enabled until it is disabled. It protects the execution from + // unlimited retries when backoff is skipped. + // Every time the execution skips time, the skip count is incremented by one, and when it reaches + // max_skip_per_session, time skipping is disabled. + // For an execution with a chain of runs (retry, cron, continue-as-new), the count is accumulated + // across all runs within the same session. The count resets to 0 at the start of each new session, + // i.e. each time this config is updated to re-enable time skipping. // - // If the field is not set, a large default value (e.g. 100) will be set by the server. - // The default value can be changed through dynamic config, and can be overridden by this field if set. - int32 max_skip_count = 4; + // If this field is not set, the server applies a large default value (e.g. 100). The default can + // be changed through dynamic config, and is overridden by this field when set. + int32 max_skip_per_session = 4; } // The time-skipping state that needs to be propagated from one execution to another, or through a chain of runs diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 3c2d48b01..c91ef1ed5 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3654,6 +3654,9 @@ message PollWorkflowExecutionTimeSkippingResponse { RESULT_FAST_FORWARD_COMPLETED = 2; // No fast-forward was in progress when the poll started, so there was nothing to wait for. RESULT_NO_PENDING_FAST_FORWARD = 3; + // The workflow has ended, where "workflow" refers to the whole chain of runs (so a + // continue-as-new does not count as ended) and "ended" means it reached a terminal status. + RESULT_WORKFLOW_ENDED = 4; } // The result of this poll. Result result = 1; From 4d4a582223a656d36d4a287b1f581dc1d22dca70 Mon Sep 17 00:00:00 2001 From: Feiyang Xie Date: Mon, 20 Jul 2026 16:46:39 -0700 Subject: [PATCH 6/6] add fast_forward_id, and other runtime fields to TimeSkippingInfo --- openapi/openapiv2.json | 36 ++++++++++++++++-- openapi/openapiv3.yaml | 37 ++++++++++++++++--- temporal/api/common/v1/message.proto | 10 +++++ .../workflowservice/v1/request_response.proto | 32 ++++++++++------ 4 files changed, 94 insertions(+), 21 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3afe05733..abac56205 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -4463,6 +4463,13 @@ "in": "query", "required": false, "type": "string" + }, + { + "name": "fastForwardId", + "description": "Required. Identifies the fast-forward whose completion the caller wants to wait for.\nMust match the `fast_forward_id` set in the execution's TimeSkippingConfig.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -10040,6 +10047,13 @@ "in": "query", "required": false, "type": "string" + }, + { + "name": "fastForwardId", + "description": "Required. Identifies the fast-forward whose completion the caller wants to wait for.\nMust match the `fast_forward_id` set in the execution's TimeSkippingConfig.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -11149,12 +11163,14 @@ "type": "string", "enum": [ "RESULT_UNSPECIFIED", - "RESULT_TIMESKIPPING_CONFIG_UPDATED", + "RESULT_POLL_TIMEOUT", "RESULT_FAST_FORWARD_COMPLETED", - "RESULT_NO_PENDING_FAST_FORWARD" + "RESULT_FAST_FORWARD_NOT_FOUND", + "RESULT_FAST_FORWARD_OVERRIDDEN", + "RESULT_WORKFLOW_END_BEFORE_FAST_FORWARD_COMPLETION" ], "default": "RESULT_UNSPECIFIED", - "description": " - RESULT_UNSPECIFIED: The poll timed out server-side before any time-skipping state change occurred to fast forward.\nThe caller may poll again.\n - RESULT_TIMESKIPPING_CONFIG_UPDATED: The execution's time-skipping config changed while the poll was waiting.\n - RESULT_FAST_FORWARD_COMPLETED: The fast-forward that was active when the poll started reached its target time and completed.\n - RESULT_NO_PENDING_FAST_FORWARD: No fast-forward was in progress when the poll started, so there was nothing to wait for." + "description": " - RESULT_UNSPECIFIED: Never returned; guards against an unset result.\n - RESULT_POLL_TIMEOUT: The poll timed out server-side before the fast-forward completed. The caller may poll again.\n - RESULT_FAST_FORWARD_COMPLETED: The fast-forward identified by the request's `fast_forward_id` reached its target time and completed.\n - RESULT_FAST_FORWARD_NOT_FOUND: The request's `fast_forward_id` does not match the execution's current `fast_forward_id`.\nThe API returns immediately with this result, and `fast_forward_info` carries the execution's\ncurrent fast-forward info.\n - RESULT_FAST_FORWARD_OVERRIDDEN: The request's `fast_forward_id` matched the execution's current `fast_forward_id`, but while\nwaiting for it to complete the fast-forward was overridden by another call that changed the\nTimeSkippingConfig.\n - RESULT_WORKFLOW_END_BEFORE_FAST_FORWARD_COMPLETION: The request's `fast_forward_id` matched the execution's current `fast_forward_id`,\nbut the workflow execution (the whole chain of runs) has completed before fast forward has a chance to complete." }, "PostResetOperationSignalWorkflow": { "type": "object", @@ -18073,7 +18089,7 @@ }, "fastForwardInfo": { "$ref": "#/definitions/v1TimeSkippingFastForwardInfo", - "description": "The execution's most recent fast-forward, whether it is still pending or already completed.\nUnset only if the execution has never had a fast-forward." + "description": "The execution's most recent fast forward. Unset if time skipping was enabled without a fast-forward." } } }, @@ -20002,6 +20018,10 @@ "type": "string", "description": "Optionally fast-forward the current execution by this duration ahead of current workflow time.\nAfter the fast-forward completes, time skipping is disabled. And it can be re-enabled by calling\nan update API with the time-skipping opt-in.\n\nFor a given execution, only one active fast-forward is allowed at a time.\nIf a new fast-forward is set via an update call before the previous\none completes, the new one will override the previous one.\nIf the fast-forward duration exceeds the remaining execution timeout, time will not\npass beyond the end of the execution, and fast_forward won't have a chance to complete." }, + "fastForwardId": { + "type": "string", + "description": "A client-supplied ID that must be set together with `fast_forward`. It is used to poll for\nfast-forward completion via PollWorkflowExecutionTimeSkipping.\nThe server performs no idempotency check on this ID; the client is responsible for managing it." + }, "disablePropagation": { "type": "boolean", "description": "By default, executions started by another execution (e.g. a child workflow of a parent workflow or\na schedule with the timeskipping policy enabled), inherit the \"enabled\" flag and skip time when possible.\nThis flag disables that inheritance." @@ -20030,6 +20050,10 @@ "hasCompleted": { "type": "boolean", "description": "True once `target_time` has been reached." + }, + "fastForwardId": { + "type": "string", + "description": "The client-supplied ID set alongside `fast_forward` when this fast-forward was created." } }, "description": "TimeSkippingFastForwardInfo describes the current time-skipping fast-forward on an execution." @@ -20045,6 +20069,10 @@ "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,\nmax skip allowed checking, or user configuration, it will be false." + }, + "fastForwardInfo": { + "$ref": "#/definitions/v1TimeSkippingFastForwardInfo", + "description": "The execution's current fast-forward, if any. Unset if time skipping is enabled without a fast-forward." } }, "description": "Describes the current time-skipping state of a workflow execution." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index b41fda380..d7bcdd640 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -4601,6 +4601,13 @@ paths: in: query schema: type: string + - name: fastForwardId + in: query + description: |- + Required. Identifies the fast-forward whose completion the caller wants to wait for. + Must match the `fast_forward_id` set in the execution's TimeSkippingConfig. + schema: + type: string responses: "200": description: OK @@ -9639,6 +9646,13 @@ paths: in: query schema: type: string + - name: fastForwardId + in: query + description: |- + Required. Identifies the fast-forward whose completion the caller wants to wait for. + Must match the `fast_forward_id` set in the execution's TimeSkippingConfig. + schema: + type: string responses: "200": description: OK @@ -14481,18 +14495,18 @@ components: result: enum: - RESULT_UNSPECIFIED - - RESULT_TIMESKIPPING_CONFIG_UPDATED + - RESULT_POLL_TIMEOUT - RESULT_FAST_FORWARD_COMPLETED - - RESULT_NO_PENDING_FAST_FORWARD + - RESULT_FAST_FORWARD_NOT_FOUND + - RESULT_FAST_FORWARD_OVERRIDDEN + - RESULT_WORKFLOW_END_BEFORE_FAST_FORWARD_COMPLETION type: string description: The result of this poll. format: enum fastForwardInfo: allOf: - $ref: '#/components/schemas/TimeSkippingFastForwardInfo' - description: |- - The execution's most recent fast-forward, whether it is still pending or already completed. - Unset only if the execution has never had a fast-forward. + description: The execution's most recent fast forward. Unset if time skipping was enabled without a fast-forward. PollWorkflowTaskQueueResponse: type: object properties: @@ -17766,6 +17780,12 @@ components: one completes, the new one will override the previous one. If the fast-forward duration exceeds the remaining execution timeout, time will not pass beyond the end of the execution, and fast_forward won't have a chance to complete. + fastForwardId: + type: string + description: |- + A client-supplied ID that must be set together with `fast_forward`. It is used to poll for + fast-forward completion via PollWorkflowExecutionTimeSkipping. + The server performs no idempotency check on this ID; the client is responsible for managing it. disablePropagation: type: boolean description: |- @@ -17817,6 +17837,9 @@ components: hasCompleted: type: boolean description: True once `target_time` has been reached. + fastForwardId: + type: string + description: The client-supplied ID set alongside `fast_forward` when this fast-forward was created. description: TimeSkippingFastForwardInfo describes the current time-skipping fast-forward on an execution. TimeSkippingInfo: type: object @@ -17833,6 +17856,10 @@ components: 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, max skip allowed checking, or user configuration, it will be false. + fastForwardInfo: + allOf: + - $ref: '#/components/schemas/TimeSkippingFastForwardInfo' + description: The execution's current fast-forward, if any. Unset if time skipping is enabled without a fast-forward. description: Describes the current time-skipping state of a workflow execution. TimeSkippingStatePropagation: type: object diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 04dba0f46..6f446f02f 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -433,6 +433,11 @@ message TimeSkippingConfig { // pass beyond the end of the execution, and fast_forward won't have a chance to complete. google.protobuf.Duration fast_forward = 2; + // A client-supplied ID that must be set together with `fast_forward`. It is used to poll for + // fast-forward completion via PollWorkflowExecutionTimeSkipping. + // The server performs no idempotency check on this ID; the client is responsible for managing it. + string fast_forward_id = 5; + // By default, executions started by another execution (e.g. a child workflow of a parent workflow or // a schedule with the timeskipping policy enabled), inherit the "enabled" flag and skip time when possible. // This flag disables that inheritance. @@ -478,6 +483,9 @@ message TimeSkippingInfo { // this field will be set to true. If time has stopped skipping either by fast-forward completion, // max skip allowed checking, or user configuration, it will be false. bool is_running = 2; + + // The execution's current fast-forward, if any. Unset if time skipping is enabled without a fast-forward. + TimeSkippingFastForwardInfo fast_forward_info = 3; } @@ -489,4 +497,6 @@ message TimeSkippingFastForwardInfo { google.protobuf.Timestamp target_time = 2; // True once `target_time` has been reached. bool has_completed = 3; + // The client-supplied ID set alongside `fast_forward` when this fast-forward was created. + string fast_forward_id = 4; } diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c91ef1ed5..91a01d582 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3641,27 +3641,35 @@ message DeleteNexusOperationExecutionResponse { message PollWorkflowExecutionTimeSkippingRequest { string namespace = 1; temporal.api.common.v1.WorkflowExecution workflow_execution = 2; + // Required. Identifies the fast-forward whose completion the caller wants to wait for. + // Must match the `fast_forward_id` set in the execution's TimeSkippingConfig. + string fast_forward_id = 3; } message PollWorkflowExecutionTimeSkippingResponse { enum Result { - // The poll timed out server-side before any time-skipping state change occurred to fast forward. - // The caller may poll again. + // Never returned; guards against an unset result. RESULT_UNSPECIFIED = 0; - // The execution's time-skipping config changed while the poll was waiting. - RESULT_TIMESKIPPING_CONFIG_UPDATED = 1; - // The fast-forward that was active when the poll started reached its target time and completed. + // The poll timed out server-side before the fast-forward completed. The caller may poll again. + RESULT_POLL_TIMEOUT = 1; + // The fast-forward identified by the request's `fast_forward_id` reached its target time and completed. RESULT_FAST_FORWARD_COMPLETED = 2; - // No fast-forward was in progress when the poll started, so there was nothing to wait for. - RESULT_NO_PENDING_FAST_FORWARD = 3; - // The workflow has ended, where "workflow" refers to the whole chain of runs (so a - // continue-as-new does not count as ended) and "ended" means it reached a terminal status. - RESULT_WORKFLOW_ENDED = 4; + // The request's `fast_forward_id` does not match the execution's current `fast_forward_id`. + // The API returns immediately with this result, and `fast_forward_info` carries the execution's + // current fast-forward info. + RESULT_FAST_FORWARD_NOT_FOUND = 3; + // The request's `fast_forward_id` matched the execution's current `fast_forward_id`, but while + // waiting for it to complete the fast-forward was overridden by another call that changed the + // TimeSkippingConfig. + RESULT_FAST_FORWARD_OVERRIDDEN = 4; + // The request's `fast_forward_id` matched the execution's current `fast_forward_id`, + // but the workflow execution (the whole chain of runs) has completed before fast forward has a chance to complete. + RESULT_WORKFLOW_END_BEFORE_FAST_FORWARD_COMPLETION = 5; } + // The result of this poll. Result result = 1; - // The execution's most recent fast-forward, whether it is still pending or already completed. - // Unset only if the execution has never had a fast-forward. + // The execution's most recent fast forward. Unset if time skipping was enabled without a fast-forward. temporal.api.common.v1.TimeSkippingFastForwardInfo fast_forward_info = 2; }