Skip to content

time skipping supports max skip, polling, describe #835

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

Draft
feiyang3cat wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

time skipping supports max skip, polling, describe #835

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5ea060e
add max_skip_count and change comments of TimeSkippingConfig
feiyang3cat Jul 19, 2026
0eca82a
add TimeSkippingInfo to WorkflowExecutionExtendedInfo, add poll api
feiyang3cat Jul 19, 2026
fe7c993
add initial_skip_count to TimeSkippingStatePropagation and refine com…
feiyang3cat Jul 19, 2026
62c79a0
rename PollWorkflowExecutionTimeSkippingResponse fields
feiyang3cat Jul 20, 2026
a22f9fc
rename max_skip_per_session, add RESULT_WORKFLOW_ENDED
feiyang3cat Jul 20, 2026
4d4a582
add fast_forward_id, and other runtime fields to TimeSkippingInfo
feiyang3cat Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 192 additions & 5 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4427,6 +4427,56 @@
]
}
},
"/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"
},
{
"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": [
"WorkflowService"
]
}
},
"/api/v1/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/update-options": {
"post": {
"summary": "UpdateWorkflowExecutionOptions partially updates the WorkflowExecutionOptions of an existing workflow execution.",
Expand Down Expand Up @@ -9961,6 +10011,56 @@
]
}
},
"/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"
},
{
"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": [
"WorkflowService"
]
}
},
"/namespaces/{namespace}/workflows/{workflowExecution.workflowId}/update-options": {
"post": {
"summary": "UpdateWorkflowExecutionOptions partially updates the WorkflowExecutionOptions of an existing workflow execution.",
Expand Down Expand Up @@ -11059,6 +11159,19 @@
}
}
},
"PollWorkflowExecutionTimeSkippingResponseResult": {
"type": "string",
"enum": [
"RESULT_UNSPECIFIED",
"RESULT_POLL_TIMEOUT",
"RESULT_FAST_FORWARD_COMPLETED",
"RESULT_FAST_FORWARD_NOT_FOUND",
"RESULT_FAST_FORWARD_OVERRIDDEN",
"RESULT_WORKFLOW_END_BEFORE_FAST_FORWARD_COMPLETION"
],
"default": "RESULT_UNSPECIFIED",
"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",
"properties": {
Expand Down Expand Up @@ -17967,6 +18080,19 @@
}
}
},
"v1PollWorkflowExecutionTimeSkippingResponse": {
"type": "object",
"properties": {
"result": {
"$ref": "#/definitions/PollWorkflowExecutionTimeSkippingResponseResult",
"description": "The result of this poll."
},
"fastForwardInfo": {
"$ref": "#/definitions/v1TimeSkippingFastForwardInfo",
"description": "The execution's most recent fast forward. Unset if time skipping was enabled without a fast-forward."
}
}
},
"v1PollWorkflowTaskQueueResponse": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -19890,29 +20016,86 @@
},
"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."
},
"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."
},
"maxSkipPerSession": {
"type": "integer",
"format": "int32",
"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 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_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",
"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."
},
"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."
},
"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."
},
"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."
},
"v1TimeSkippingStatePropagation": {
"type": "object",
"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",
Expand Down Expand Up @@ -21082,6 +21265,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."
Expand Down
Loading
Loading