diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3eeda5de9..abac56205 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -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.", @@ -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.", @@ -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": { @@ -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": { @@ -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", @@ -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." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 71e444e29..d7bcdd640 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -4572,6 +4572,55 @@ 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 + - 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 + 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 +9617,55 @@ 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 + - 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 + 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 +14489,24 @@ components: allOf: - $ref: '#/components/schemas/Failure' description: The failure if the operation completed unsuccessfully. + PollWorkflowExecutionTimeSkippingResponse: + type: object + properties: + result: + 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 + type: string + description: The result of this poll. + format: enum + fastForwardInfo: + allOf: + - $ref: '#/components/schemas/TimeSkippingFastForwardInfo' + description: The execution's most recent fast forward. Unset if time skipping was enabled without a fast-forward. PollWorkflowTaskQueueResponse: type: object properties: @@ -17655,38 +17771,96 @@ 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. + 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: |- 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. + maxSkipPerSession: + type: integer + description: |- + 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 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 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_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: + 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; 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 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. + 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 + 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. + 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 properties: @@ -17694,17 +17868,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: @@ -19630,6 +19806,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 1af5b4acc..6f446f02f 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_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: +// 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; 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 @@ -420,35 +422,81 @@ 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; + // 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. bool disable_propagation = 3; + + // 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 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 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; +} + + +// 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; + + // The execution's current fast-forward, if any. Unset if time skipping is enabled without a fast-forward. + TimeSkippingFastForwardInfo fast_forward_info = 3; +} + + +// 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; + // The client-supplied ID set alongside `fast_forward` when this fast-forward was created. + string fast_forward_id = 4; } 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..91a01d582 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3634,3 +3634,42 @@ 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; + // 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 { + // Never returned; guards against an unset result. + RESULT_UNSPECIFIED = 0; + // 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; + // 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. Unset if time skipping was enabled without a fast-forward. + 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}" + }; + } }