time skipping supports max skip, polling, describe

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

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 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_session_skip_count = 4;
 }
 
-// The time-skipping state that needs to be propagated from a parent workflow to a child workflow,
-// or through a chain of runs.
+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 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;
 }

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;
-}
+}

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.

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;
+}

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}"
+        };
+    }
 }