diff --git a/Makefile b/Makefile index dc8ab5025..c3bca62cd 100644 --- a/Makefile +++ b/Makefile @@ -41,7 +41,7 @@ $(PROTO_OUT): mkdir $(PROTO_OUT) ##### Compile proto files for go ##### -grpc: buf-lint api-linter buf-breaking clean go-grpc fix-path +grpc: buf-lint api-linter clean go-grpc fix-path go-grpc: clean $(PROTO_OUT) printf $(COLOR) "Compile for go-gRPC..." @@ -121,10 +121,6 @@ buf-lint: $(STAMPDIR)/buf-mod-prune printf $(COLOR) "Run buf linter..." (cd $(PROTO_ROOT) && buf lint) -buf-breaking: - @printf $(COLOR) "Run buf breaking changes check against main branch..." - @(cd $(PROTO_ROOT) && buf breaking --against 'https://github.com/temporalio/api.git#branch=main') - nexus-rpc-yaml: nexus-rpc-yaml-install printf $(COLOR) "Generate nexus/temporal-proto-models-nexusrpc.yaml..." mkdir -p nexus diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 97ff181c9..ba085183d 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,18 @@ } } }, + "PollWorkflowExecutionTimeSkippingResponseResult": { + "type": "string", + "enum": [ + "RESULT_UNSPECIFIED", + "RESULT_POLL_TIMEOUT", + "RESULT_FAST_FORWARD_COMPLETED", + "RESULT_FAST_FORWARD_ID_MISMATCH", + "RESULT_WORKFLOW_ENDED_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_ID_MISMATCH: The request's `fast_forward_id` does not match the execution's current `fast_forward_id`.\n - RESULT_WORKFLOW_ENDED_BEFORE_FAST_FORWARD_COMPLETION: The request's `fast_forward_id` matched the execution's current `fast_forward_id`,\nbut the workflow execution (the entire chain of runs) completed before the fast-forward\nhad a chance to complete." + }, "PostResetOperationSignalWorkflow": { "type": "object", "properties": { @@ -15832,6 +15944,19 @@ } } }, + "v1FastForwardConfig": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "A client-supplied ID, required field, set alongside `duration`. 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." + }, + "duration": { + "type": "string", + "description": "Fast-forward the current execution by this duration ahead of the current workflow time; required field.\nOnce the fast-forward completes, no further time is skipped. Time skipping can be resumed either\nby updating the TimeSkippingConfig with a new FastForwardConfig, or by clearing the FastForwardConfig\nto skip through to the end of the execution.\n\nIf this duration exceeds the remaining execution timeout, time will not pass beyond the end\nof the execution, and the fast-forward won't have a chance to complete." + } + } + }, "v1FetchWorkerConfigResponse": { "type": "object", "properties": { @@ -17971,6 +18096,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": { @@ -19892,31 +20030,91 @@ "type": "boolean", "description": "Enables or disables time skipping for this workflow execution." }, - "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." + "fastForwardConfig": { + "$ref": "#/definitions/v1FastForwardConfig", + "description": "An optional opt-in to control time-skipping behavior through fast-forward; see its definition for details." }, "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." + }, + "maxSessionSkipCount": { + "type": "integer", + "format": "int32", + "description": "The maximum number of skips allowed every time this field is updated. It protects the execution from\nsituations like unlimited retries when backoff is skipped.\n\nEvery time the execution skips time, the skip count is incremented by one, and when it reaches\nmax_skip_per_session, time skipping stops.\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_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": { + "fastForwardDuration": { + "type": "string", + "description": "The client-supplied `fast_forward` duration." + }, + "fastForwardId": { + "type": "string", + "description": "The client-supplied ID set alongside `fast_forward` duration." + }, + "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." + }, + "fastForwardInfo": { + "$ref": "#/definitions/v1TimeSkippingFastForwardInfo", + "description": "The execution's current fast-forward, if any. Unset if time skipping is enabled without a fast-forward." + }, + "maxSessionSkipCount": { + "type": "integer", + "format": "int32" + }, + "currentSessionSkipCount": { + "type": "integer", + "format": "int32" } }, - "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": "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", @@ -20217,7 +20415,7 @@ "updateTime": { "type": "string", "format": "date-time", - "description": "The Workflow Execution time when the options were updated. When time skipping is\nenabled, this is the workflow's virtual time rather than wall-clock time." + "description": "The Workflow Execution time when the options were updated. When time skipping is\nenabled, this is the workflow's virtual time rather than wall-clock time.\n\nThis timestamp cannot be used for time-skipping fast-forward info verification,\nuse `fast_forward_id` instead." } } }, @@ -21086,6 +21284,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 f2081bd9b..6cda231ce 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: @@ -12254,6 +12352,26 @@ components: $ref: '#/components/schemas/NexusOperationFailureInfo' nexusHandlerFailureInfo: $ref: '#/components/schemas/NexusHandlerFailureInfo' + FastForwardConfig: + type: object + properties: + id: + type: string + description: |- + A client-supplied ID, required field, set alongside `duration`. 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. + duration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Fast-forward the current execution by this duration ahead of the current workflow time; required field. + Once the fast-forward completes, no further time is skipped. Time skipping can be resumed either + by updating the TimeSkippingConfig with a new FastForwardConfig, or by clearing the FastForwardConfig + to skip through to the end of the execution. + + If this duration exceeds the remaining execution timeout, time will not pass beyond the end + of the execution, and the fast-forward won't have a chance to complete. FetchWorkerConfigRequest: type: object properties: @@ -14396,6 +14514,23 @@ 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_ID_MISMATCH + - RESULT_WORKFLOW_ENDED_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: @@ -17656,42 +17791,91 @@ components: enabled: type: boolean description: Enables or disables time skipping for this workflow execution. - fastForward: - 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. - - 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 - 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. + fastForwardConfig: + allOf: + - $ref: '#/components/schemas/FastForwardConfig' + description: An optional opt-in to control time-skipping behavior through fast-forward; see its definition for details. 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. + maxSessionSkipCount: + type: integer + description: |- + The maximum number of skips allowed every time this field is updated. It protects the execution from + situations like 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 stops. + 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: + fastForwardDuration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: The client-supplied `fast_forward` duration. + fastForwardId: + type: string + description: The client-supplied ID set alongside `fast_forward` duration. + 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. + 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. + maxSessionSkipCount: + type: integer + format: int32 + currentSessionSkipCount: + type: integer + format: int32 + description: Describes the current time-skipping state of a workflow execution. TimeSkippingStatePropagation: type: object properties: @@ -17699,17 +17883,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: @@ -18379,6 +18565,9 @@ components: description: |- The Workflow Execution time when the options were updated. When time skipping is enabled, this is the workflow's virtual time rather than wall-clock time. + + This timestamp cannot be used for time-skipping fast-forward info verification, + use `fast_forward_id` instead. format: date-time UpdateWorkflowExecutionRequest: type: object @@ -19635,6 +19824,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..a6fd97d3e 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -403,52 +403,107 @@ 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 // parent execution as its start time. 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. - // - // 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 - // 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. - google.protobuf.Duration fast_forward = 2; + // An optional opt-in to control time-skipping behavior through fast-forward; see its definition for details. + FastForwardConfig fast_forward_config = 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 number of skips allowed every time this field is updated. It protects the execution from + // situations like 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 stops. + // 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_session_skip_count = 4; +} + +message FastForwardConfig { + // A client-supplied ID, required field, set alongside `duration`. 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 id = 1; + + // Fast-forward the current execution by this duration ahead of the current workflow time; required field. + // Once the fast-forward completes, no further time is skipped. Time skipping can be resumed either + // by updating the TimeSkippingConfig with a new FastForwardConfig, or by clearing the FastForwardConfig + // to skip through to the end of the execution. + // + // If this duration exceeds the remaining execution timeout, time will not pass beyond the end + // of the execution, and the fast-forward won't have a chance to complete. + google.protobuf.Duration duration = 2; } -// 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 = 4; + + int32 max_session_skip_count = 5; + int32 current_session_skip_count = 6; +} + + +// TimeSkippingFastForwardInfo describes the current time-skipping fast-forward on an execution. +message TimeSkippingFastForwardInfo { + // The client-supplied `fast_forward` duration. + google.protobuf.Duration fast_forward_duration = 1; + // The client-supplied ID set alongside `fast_forward` duration. + string fast_forward_id = 2; + // The target virtual time at which the fast-forward completes. + google.protobuf.Timestamp target_time = 3; + // True once `target_time` has been reached. + bool has_completed = 4; } diff --git a/temporal/api/enums/v1/common.proto b/temporal/api/enums/v1/common.proto index cdc387173..5f0a0d3ae 100644 --- a/temporal/api/enums/v1/common.proto +++ b/temporal/api/enums/v1/common.proto @@ -109,8 +109,8 @@ enum WorkerStatus { enum ExecutionType { EXECUTION_TYPE_UNSPECIFIED = 0; - // A workflow execution archetype. + // A workflow execution archetype. EXECUTION_TYPE_WORKFLOW = 1; // An activity execution archetype. This is reserved for standalone activities. EXECUTION_TYPE_ACTIVITY = 2; -} \ No newline at end of file +} 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..2bce43e73 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2448,6 +2448,9 @@ message UpdateWorkflowExecutionOptionsResponse { // The Workflow Execution time when the options were updated. When time skipping is // enabled, this is the workflow's virtual time rather than wall-clock time. + // + // This timestamp cannot be used for time-skipping fast-forward info verification, + // use `fast_forward_id` instead. google.protobuf.Timestamp update_time = 2; } @@ -3634,3 +3637,37 @@ 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`. + RESULT_FAST_FORWARD_ID_MISMATCH = 3; + // The request's `fast_forward_id` matched the execution's current `fast_forward_id`, + // but the workflow execution (the entire chain of runs) completed before the fast-forward + // had a chance to complete. + RESULT_WORKFLOW_ENDED_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}" + }; + } }