Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 223 additions & 28 deletions openapi/openapiv2.json

Large diffs are not rendered by default.

335 changes: 309 additions & 26 deletions openapi/openapiv3.yaml

Large diffs are not rendered by default.

99 changes: 93 additions & 6 deletions temporal/api/activity/v1/message.proto
Original file line number Diff line number Diff line change
Expand Up @@ -36,33 +36,95 @@ message ActivityExecutionOutcome {
temporal.api.enums.v1.RetryState retry_state = 3;
}

// An activity attempt has two phases: before handoff and waiting for external completion.
// Handoff occurs when the server durably accepts `RespondActivityTaskHandoff`.
//
// This message sets the timeouts before handoff and while waiting for external completion.
// Its heartbeat timeout and retry policy apply only before handoff. After handoff, use the
// heartbeat timeout and retry policy in `ActivityOptions`.
// `ActivityOptions.start_to_close_timeout` spans both phases. If it expires, retries use
// `ActivityOptions.retry_policy`.
//
// Presence, including an empty message, enables two-phase timeouts and retries. Absence preserves
// existing timeout, retry, and attempt-counting behavior even when handoff is reported.
// A positive `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout`
// is required unless both phase timeouts are positive. An unset or zero start-to-close timeout
// remains disabled.
//
// Phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and
// `ActivityOptions.schedule_to_close_timeout` values. Heartbeat timeouts are also capped by their
// phase timeout. The server stores and returns the capped values. Increasing a bound does not
// restore a capped value unless that value is also updated.
message HandoffOptions {
// Maximum time from the current worker pickup until the server durably accepts handoff. Unset
// or zero disables this timeout. On timeout, the server retries according to
// `HandoffOptions.retry_policy`.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" identifies the endpoints of the timeout. --)
google.protobuf.Duration start_to_handoff_timeout = 1;

// Maximum time from the server durably accepting handoff until the current activity attempt
// closes. Unset or zero disables this timeout. On timeout, the server retries according to
// `ActivityOptions.retry_policy`.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" identifies the endpoints of the timeout. --)
google.protobuf.Duration handoff_to_close_timeout = 2;

// Maximum time between recorded heartbeats before accepted handoff, initially measured from
// worker pickup. Unset or zero disables it; `ActivityOptions.heartbeat_timeout` is not inherited
// and applies only after handoff.
google.protobuf.Duration heartbeat_timeout = 3;

// Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff.
// Retries increment `PollActivityTaskQueueResponse.handoff_attempt` without incrementing
// `PollActivityTaskQueueResponse.attempt`. Exhausting this policy does not fall back to
// `ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry
// policy, independently of `ActivityOptions.retry_policy`.
// To change `RetryPolicy.non_retryable_error_types`, replace
// `handoff_options.retry_policy` as a whole in the update mask.
temporal.api.common.v1.RetryPolicy retry_policy = 4;
}

message ActivityOptions {
temporal.api.taskqueue.v1.TaskQueue task_queue = 1;

// Indicates how long the caller is willing to wait for an activity completion. Limits how long
// retries will be attempted. Either this or `start_to_close_timeout` must be specified.
// retries will be attempted. Either this or `start_to_close_timeout` must be specified,
// unless `ActivityOptions.handoff_options` provides both phase timeouts.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration schedule_to_close_timeout = 2;
// Limits time an activity task can stay in a task queue before a worker picks it up. This
// timeout is always non retryable, as all a retry would achieve is to put it back into the same
// queue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not
// specified.
// specified. With `handoff_options` set, defaults to a positive
// `schedule_to_close_timeout`, otherwise remains disabled.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration schedule_to_start_timeout = 3;
// Maximum time an activity is allowed to execute after being picked up by a worker. This
// timeout is always retryable. Either this or `schedule_to_close_timeout` must be
// specified.
// timeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,
// unless `ActivityOptions.handoff_options` provides both phase timeouts.
// When `ActivityOptions.handoff_options` is present, the start-to-close timeout runs from
// the first worker pickup of the activity attempt across both phases, handoff retries, backoff, and
// queue waits.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration start_to_close_timeout = 4;
// Maximum permitted time between successful worker heartbeats.
// When `ActivityOptions.handoff_options` is present, the activity heartbeat timeout
// applies after handoff, starting at accepted handoff.
// Before handoff, use `HandoffOptions.heartbeat_timeout`.
google.protobuf.Duration heartbeat_timeout = 5;
// The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.
// When `ActivityOptions.handoff_options` is present, this policy handles post-handoff failures
// and timeouts, plus start-to-close timeouts in either phase. Other pre-handoff failures use
// `HandoffOptions.retry_policy`.
temporal.api.common.v1.RetryPolicy retry_policy = 6;

// Priority metadata. If this message is not present, or any fields are not
Expand All @@ -73,6 +135,9 @@ message ActivityOptions {
// When updated, the time is added to the original `schedule_time`, not to the current time.
// If the resulting time is in the past, the task is made available for dispatch immediately.
google.protobuf.Duration start_delay = 8;

// Two-phase timeout and retry settings.
HandoffOptions handoff_options = 9;
}

// Information about a standalone activity.
Expand Down Expand Up @@ -111,19 +176,22 @@ message ActivityExecutionInfo {
google.protobuf.Duration start_to_close_timeout = 9;

// Maximum permitted time between successful worker heartbeats.
// See `ActivityOptions.heartbeat_timeout` for behavior with handoff options.
google.protobuf.Duration heartbeat_timeout = 10;

// The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.
// See `ActivityOptions.retry_policy` for behavior with handoff options.
temporal.api.common.v1.RetryPolicy retry_policy = 11;

// Details provided in the last recorded activity heartbeat.
// DescribeActivityExecution does not set this field unless include_heartbeat_details was true in the request.
temporal.api.common.v1.Payloads heartbeat_details = 12;
// Time the last heartbeat was recorded.
google.protobuf.Timestamp last_heartbeat_time = 13;
// Time the last attempt was started.
// Time the most recent activity task started.
google.protobuf.Timestamp last_started_time = 14;
// The attempt this activity is currently on. Incremented each time a new attempt is scheduled.
// The attempt this activity is currently on. Activity retries increment this count;
// handoff retries increment `ActivityExecutionInfo.handoff_attempt` instead.
int32 attempt = 15;
// How long this activity has been running for, including all attempts and backoff between attempts.
google.protobuf.Duration execution_duration = 16;
Expand Down Expand Up @@ -218,6 +286,25 @@ message ActivityExecutionInfo {

// Authenticated principal of the worker that most recently interacted with this activity execution.
temporal.api.common.v1.ResolvedPrincipal last_worker_principal = 43;

// Handoff attempt within the current activity attempt. Starts at 1 when
// `ActivityExecutionInfo.handoff_options` are configured at creation or added by update.
// Increments on handoff retries and resets to 1 on an activity retry or applied reset.
// Zero when options are absent.
int32 handoff_attempt = 44;

// Most recent durably recorded handoff time. Retained through retry backoff, waiting for the
// next worker pickup, and terminal closure. Cleared when a reset is applied or the next delivery
// starts on a worker.
google.protobuf.Timestamp handoff_time = 45;

// True while the current delivery awaits external completion, independent of
// `ActivityExecutionInfo.run_state`. Cleared when the delivery ends or is reset;
// pending pause, cancel, or reset requests do not clear it.
bool handed_off = 46;

// Server-normalized and defaulted handoff options, if configured.
HandoffOptions handoff_options = 47;
}

// Limited activity information returned in the list response.
Expand Down
19 changes: 14 additions & 5 deletions temporal/api/command/v1/message.proto
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import "google/protobuf/duration.proto";

import "temporal/api/enums/v1/workflow.proto";
import "temporal/api/enums/v1/command_type.proto";
import "temporal/api/activity/v1/message.proto";
import "temporal/api/common/v1/message.proto";
import "temporal/api/failure/v1/message.proto";
import "temporal/api/taskqueue/v1/message.proto";
Expand All @@ -31,7 +32,8 @@ message ScheduleActivityTaskCommandAttributes {
// Indicates how long the caller is willing to wait for activity completion. The "schedule" time
// is when the activity is initially scheduled, not when the most recent retry is scheduled.
// Limits how long retries will be attempted. Either this or `start_to_close_timeout` must be
// specified. When not specified, defaults to the workflow execution timeout.
// specified, unless `handoff_options` provides both phase timeouts. Without handoff
// options, defaults to the workflow execution timeout when not specified.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
Expand All @@ -41,23 +43,28 @@ message ScheduleActivityTaskCommandAttributes {
// be set: it's useful in specific scenarios like worker-specific task queues. This timeout is
// always non retryable, as all a retry would achieve is to put it back into the same queue.
// Defaults to `schedule_to_close_timeout` or workflow execution timeout if that is not
// specified. More info:
// specified. With `handoff_options` set, defaults to a positive
// `schedule_to_close_timeout`, otherwise remains disabled. More info:
// https://docs.temporal.io/docs/content/what-is-a-schedule-to-start-timeout/
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration schedule_to_start_timeout = 8;
// Maximum time an activity is allowed to execute after being picked up by a worker. This
// timeout is always retryable. Either this or `schedule_to_close_timeout` must be specified.
// timeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,
// unless `handoff_options` provides both phase timeouts. With handoff options set,
// see `ActivityOptions.start_to_close_timeout` for timing.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration start_to_close_timeout = 9;
// Maximum permitted time between successful worker heartbeats.
// Maximum permitted time between successful worker heartbeats. With `handoff_options`
// set, applies after handoff; before handoff, use `HandoffOptions.heartbeat_timeout`.
google.protobuf.Duration heartbeat_timeout = 10;
// Activities are provided by a default retry policy which is controlled through the service's
// dynamic configuration. Retries will be attempted until `schedule_to_close_timeout` has
// elapsed. To disable retries set retry_policy.maximum_attempts to 1.
// elapsed. To disable retries under this policy, set retry_policy.maximum_attempts to 1.
// With `handoff_options` set, see `ActivityOptions.retry_policy` for applicability.
temporal.api.common.v1.RetryPolicy retry_policy = 11;
// Request to start the activity directly bypassing matching service and worker polling
// The slot for executing the activity should be reserved when setting this field to true.
Expand All @@ -68,6 +75,8 @@ message ScheduleActivityTaskCommandAttributes {
// Priority metadata. If this message is not present, or any fields are not
// present, they inherit the values from the workflow.
temporal.api.common.v1.Priority priority = 14;
// Handoff timeout and retry settings.
temporal.api.activity.v1.HandoffOptions handoff_options = 15;
}

message RequestCancelActivityTaskCommandAttributes {
Expand Down
6 changes: 6 additions & 0 deletions temporal/api/enums/v1/workflow.proto
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,8 @@ enum PendingActivityState {
PENDING_ACTIVITY_STATE_PAUSED = 4;
// PAUSE_REQUESTED means activity is currently running on the worker, but paused on the server
PENDING_ACTIVITY_STATE_PAUSE_REQUESTED = 5;
// HANDED_OFF means the server accepted handoff and is waiting for external completion.
PENDING_ACTIVITY_STATE_HANDED_OFF = 6;
}

enum PendingWorkflowTaskState {
Expand Down Expand Up @@ -122,6 +124,10 @@ enum TimeoutType {
TIMEOUT_TYPE_SCHEDULE_TO_START = 2;
TIMEOUT_TYPE_SCHEDULE_TO_CLOSE = 3;
TIMEOUT_TYPE_HEARTBEAT = 4;
// The worker-owned handoff phase exceeded its configured timeout before accepted handoff.
TIMEOUT_TYPE_START_TO_HANDOFF = 5;
// The external-completion phase exceeded its configured timeout after accepted handoff.
TIMEOUT_TYPE_HANDOFF_TO_CLOSE = 6;
}

// Versioning Behavior specifies if and how a workflow execution moves between Worker Deployment
Expand Down
20 changes: 14 additions & 6 deletions temporal/api/history/v1/message.proto
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import "temporal/api/enums/v1/event_type.proto";
import "temporal/api/enums/v1/failed_cause.proto";
import "temporal/api/enums/v1/update.proto";
import "temporal/api/enums/v1/workflow.proto";
import "temporal/api/activity/v1/message.proto";
import "temporal/api/common/v1/message.proto";
import "temporal/api/deployment/v1/message.proto";
import "temporal/api/failure/v1/message.proto";
Expand Down Expand Up @@ -432,33 +433,38 @@ message ActivityTaskScheduledEventAttributes {
temporal.api.common.v1.Header header = 5;
temporal.api.common.v1.Payloads input = 6;
// Indicates how long the caller is willing to wait for an activity completion. Limits how long
// retries will be attempted. Either this or `start_to_close_timeout` must be specified.
// retries will be attempted. Either this or `start_to_close_timeout` must be specified,
// unless `handoff_options` provides both phase timeouts.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration schedule_to_close_timeout = 7;
// Limits time an activity task can stay in a task queue before a worker picks it up. This
// timeout is always non retryable, as all a retry would achieve is to put it back into the same
// queue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not
// specified.
// specified. With `handoff_options` set, defaults to a positive
// `schedule_to_close_timeout`, otherwise remains disabled.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration schedule_to_start_timeout = 8;
// Maximum time an activity is allowed to execute after being picked up by a worker. This
// timeout is always retryable. Either this or `schedule_to_close_timeout` must be
// specified.
// specified, unless `handoff_options` provides both phase timeouts. With handoff
// options set, see `ActivityOptions.start_to_close_timeout` for timing.
//
// (-- api-linter: core::0140::prepositions=disabled
// aip.dev/not-precedent: "to" is used to indicate interval. --)
google.protobuf.Duration start_to_close_timeout = 9;
// Maximum permitted time between successful worker heartbeats.
// Maximum permitted time between successful worker heartbeats. With `handoff_options`
// set, applies after handoff; before handoff, use `HandoffOptions.heartbeat_timeout`.
google.protobuf.Duration heartbeat_timeout = 10;
// The `WORKFLOW_TASK_COMPLETED` event which this command was reported with
int64 workflow_task_completed_event_id = 11;
// Activities are assigned a default retry policy controlled by the service's dynamic
// configuration. Retries will happen up to `schedule_to_close_timeout`. To disable retries set
// retry_policy.maximum_attempts to 1.
// configuration. Retries will happen up to `schedule_to_close_timeout`. To disable retries under
// this policy, set retry_policy.maximum_attempts to 1.
// With `handoff_options` set, see `ActivityOptions.retry_policy` for applicability.
temporal.api.common.v1.RetryPolicy retry_policy = 12;
// If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,
// Assignment rules of the activity's Task Queue will be used to determine the Build ID.
Expand All @@ -467,6 +473,8 @@ message ActivityTaskScheduledEventAttributes {
// Priority metadata. If this message is not present, or any fields are not
// present, they inherit the values from the workflow.
temporal.api.common.v1.Priority priority = 14;
// Handoff timeout and retry settings.
temporal.api.activity.v1.HandoffOptions handoff_options = 15;
}

message ActivityTaskStartedEventAttributes {
Expand Down
4 changes: 4 additions & 0 deletions temporal/api/namespace/v1/message.proto
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,10 @@ message NamespaceInfo {
bool standalone_activity_batch_operations = 16;
// True if the namespace supports standalone activity operator commands.
bool standalone_activity_operator_commands = 17;
// True if workers can report standalone activity handoff through `RespondActivityTaskHandoff`.
bool standalone_activity_handoff = 18;
// True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`.
bool workflow_activity_handoff = 19;
}

// Namespace configured limits
Expand Down
11 changes: 11 additions & 0 deletions temporal/api/workflow/v1/message.proto
Original file line number Diff line number Diff line change
Expand Up @@ -381,6 +381,17 @@ message PendingActivityInfo {

// Current activity options. May be different from the one used to start the activity.
temporal.api.activity.v1.ActivityOptions activity_options = 24;

// Handoff attempt within the activity attempt. Starts at 1 when handoff options are
// configured, increments on handoff retries, and resets to 1 on an activity retry or applied
// reset. Zero when handoff options are absent.
int32 handoff_attempt = 26;

// Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset.
google.protobuf.Timestamp handoff_time = 27;

// True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it.
bool handed_off = 28;
}

message PendingChildExecutionInfo {
Expand Down
Loading
Loading