From fe6c7661e76edecb4d81dade93d0660e78c0f132 Mon Sep 17 00:00:00 2001 From: Fred Tzeng Date: Mon, 19 Oct 2026 18:28:17 -0700 Subject: [PATCH 1/7] Add activity async handoff API definitions --- openapi/openapiv2.json | 211 ++++++++++++-- openapi/openapiv3.yaml | 271 +++++++++++++++++- temporal/api/activity/v1/message.proto | 88 +++++- temporal/api/enums/v1/workflow.proto | 6 + temporal/api/namespace/v1/message.proto | 4 + .../workflowservice/v1/request_response.proto | 46 ++- temporal/api/workflowservice/v1/service.proto | 23 ++ 7 files changed, 607 insertions(+), 42 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 9a389f44e..453d64c6c 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1139,6 +1139,47 @@ ] } }, + "/api/v1/namespaces/{namespace}/activity-handoff": { + "post": { + "summary": "RespondActivityTaskHandoff durably records that the current activity delivery is awaiting\nexternal completion. Call after the external system durably accepts the submitted work.", + "description": "A successful response leaves the task token valid for heartbeats and completion. Repeating\nthis call with the same valid token succeeds without changing the handoff time or deadlines.\nFails with `NotFound` if the token is no longer valid. Does not support reporting by ID.\nA timeout or retry does not stop work already running in the external system; applications\nmust make external submissions idempotent.", + "operationId": "RespondActivityTaskHandoff2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1RespondActivityTaskHandoffResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace containing the activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskHandoffBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/activity-heartbeat": { "post": { "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", @@ -6794,6 +6835,47 @@ ] } }, + "/namespaces/{namespace}/activity-handoff": { + "post": { + "summary": "RespondActivityTaskHandoff durably records that the current activity delivery is awaiting\nexternal completion. Call after the external system durably accepts the submitted work.", + "description": "A successful response leaves the task token valid for heartbeats and completion. Repeating\nthis call with the same valid token succeeds without changing the handoff time or deadlines.\nFails with `NotFound` if the token is no longer valid. Does not support reporting by ID.\nA timeout or retry does not stop work already running in the external system; applications\nmust make external submissions idempotent.", + "operationId": "RespondActivityTaskHandoff", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1RespondActivityTaskHandoffResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace containing the activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskHandoffBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/namespaces/{namespace}/activity-heartbeat": { "post": { "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", @@ -12309,6 +12391,29 @@ } } }, + "WorkflowServiceRespondActivityTaskHandoffBody": { + "type": "object", + "properties": { + "taskToken": { + "type": "string", + "format": "byte", + "description": "The task token as received in `PollActivityTaskQueueResponse`." + }, + "identity": { + "type": "string", + "description": "The identity of the worker reporting handoff." + }, + "resourceId": { + "type": "string", + "description": "Resource ID for routing." + }, + "deploymentOptions": { + "$ref": "#/definitions/v1WorkerDeploymentOptions", + "description": "Worker deployment options configured on the worker. Must be set if the worker has\n`WorkerDeploymentOptions` configured, regardless of whether versioning is enabled." + } + }, + "description": "Reports handoff of the current activity task for external completion." + }, "WorkflowServiceSetCurrentDeploymentBody": { "type": "object", "properties": { @@ -12584,7 +12689,7 @@ }, "scheduleToCloseTimeout": { "type": "string", - "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified.\n" + "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts.\n" }, "scheduleToStartTimeout": { "type": "string", @@ -12592,11 +12697,11 @@ }, "startToCloseTimeout": { "type": "string", - "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be\nspecified.\n" + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,\nunless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. See\n`ActivityOptions.start_to_close_timeout`.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Maximum permitted time between successful worker heartbeats." + "description": "Maximum permitted time between successful worker heartbeats.\nSee `ActivityOptions.heartbeat_timeout` for behavior when\n`StartActivityExecutionRequest.async_handoff_options` is present." }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", @@ -12661,6 +12766,10 @@ "requestEagerExecution": { "type": "boolean", "description": "Request that the first activity task be returned directly in the start response instead of\nbeing dispatched through a task queue. If set to true, the caller is expected to have a\nworker available and capable of processing the task. The returned task will be marked as\nstarted. The server may ignore this request." + }, + "asyncHandoffOptions": { + "$ref": "#/definitions/v1AsyncHandoffOptions", + "description": "Two-phase timeout and retry settings." } } }, @@ -13851,12 +13960,12 @@ "lastStartedTime": { "type": "string", "format": "date-time", - "description": "Time the last attempt was started." + "description": "Time the most recent activity task started." }, "attempt": { "type": "integer", "format": "int32", - "description": "The attempt this activity is currently on. Incremented each time a new attempt is scheduled." + "description": "The attempt this activity is currently on. Activity retries increment this count;\nhandoff retries increment `ActivityExecutionInfo.handoff_attempt` instead." }, "executionDuration": { "type": "string", @@ -13979,6 +14088,24 @@ "lastWorkerPrincipal": { "$ref": "#/definitions/v1ResolvedPrincipal", "description": "Authenticated principal of the worker that most recently interacted with this activity execution." + }, + "handoffAttempt": { + "type": "integer", + "format": "int32", + "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`ActivityExecutionInfo.async_handoff_options` are added. Increments on handoff retries and\nresets to 1 on an activity retry or applied reset. Zero when options are absent." + }, + "asyncHandoffTime": { + "type": "string", + "format": "date-time", + "description": "Most recent durably recorded handoff time. Retained through retry backoff, waiting for the\nnext worker pickup, and terminal closure. Cleared when a reset is applied or the next delivery\nstarts on a worker." + }, + "awaitingCompletion": { + "type": "boolean", + "description": "True while the current delivery awaits external completion, independent of\n`ActivityExecutionInfo.run_state`. Cleared when the delivery ends or is reset;\npending pause, cancel, or reset requests do not clear it." + }, + "asyncHandoffOptions": { + "$ref": "#/definitions/v1AsyncHandoffOptions", + "description": "Server-normalized and defaulted handoff options, if configured." } }, "description": "Information about a standalone activity." @@ -14129,7 +14256,7 @@ }, "scheduleToCloseTimeout": { "type": "string", - "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified.\n" + "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `ActivityOptions.async_handoff_options` provides both phase timeouts.\n" }, "scheduleToStartTimeout": { "type": "string", @@ -14137,15 +14264,15 @@ }, "startToCloseTimeout": { "type": "string", - "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be\nspecified.\n" + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,\nunless `ActivityOptions.async_handoff_options` provides both phase timeouts.\nWhen `ActivityOptions.async_handoff_options` is present, the start-to-close timeout runs from\nthe first worker pickup of the activity attempt across both phases, handoff retries, backoff, and\nqueue waits.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Maximum permitted time between successful worker heartbeats." + "description": "Maximum permitted time between successful worker heartbeats.\nWhen `ActivityOptions.async_handoff_options` is present, the activity heartbeat timeout\napplies after handoff, starting at accepted handoff.\nBefore handoff, use `AsyncHandoffOptions.heartbeat_timeout`." }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`." + "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.\nWhen `ActivityOptions.async_handoff_options` is present, this policy handles post-handoff failures\nand timeouts, plus start-to-close timeouts in either phase. Other pre-handoff failures use\n`AsyncHandoffOptions.retry_policy`." }, "priority": { "$ref": "#/definitions/v1Priority", @@ -14154,6 +14281,10 @@ "startDelay": { "type": "string", "description": "Time to wait before making the first activity task available for dispatch. This delay is not applied to retry attempts.\nWhen updated, the time is added to the original `schedule_time`, not to the current time.\nIf the resulting time is in the past, the task is made available for dispatch immediately." + }, + "asyncHandoffOptions": { + "$ref": "#/definitions/v1AsyncHandoffOptions", + "description": "Two-phase timeout and retry settings." } } }, @@ -14462,6 +14593,28 @@ ], "default": "ARCHIVAL_STATE_UNSPECIFIED" }, + "v1AsyncHandoffOptions": { + "type": "object", + "properties": { + "startToHandoffTimeout": { + "type": "string", + "description": "Maximum time from the current worker pickup until the server durably accepts handoff. Unset\nor zero disables this timeout. On timeout, the server retries according to\n`AsyncHandoffOptions.retry_policy`.\n" + }, + "handoffToCloseTimeout": { + "type": "string", + "description": "Maximum time from the server durably accepting handoff until the current activity attempt\ncloses. Unset or zero disables this timeout. On timeout, the server retries according to\n`ActivityOptions.retry_policy`.\n" + }, + "heartbeatTimeout": { + "type": "string", + "description": "Maximum time between recorded heartbeats before accepted handoff, initially measured from\nworker pickup. Unset or zero disables it; `ActivityOptions.heartbeat_timeout` is not inherited\nand applies only after handoff." + }, + "retryPolicy": { + "$ref": "#/definitions/v1RetryPolicy", + "description": "Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff.\nRetries increment `ActivityExecutionInfo.handoff_attempt` without incrementing\n`ActivityExecutionInfo.attempt`. Exhausting this policy does not fall back to\n`ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry\npolicy, independently of `ActivityOptions.retry_policy`.\nTo change `RetryPolicy.non_retryable_error_types`, replace\n`async_handoff_options.retry_policy` as a whole in the update mask." + } + }, + "description": "Timeout and retry options for activity handoff and external completion. The completion phase\nbegins when the server durably accepts `RespondActivityTaskHandoff`.\n\nPresence, including an empty message, enables two-phase timeouts and retries. Absence preserves\nexisting timeout, retry, and attempt-counting behavior even when handoff is reported.\nEither `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout`\nmust be positive; otherwise, both phase timeouts below must be positive so neither phase can\nwait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout`\nis enforced only when explicitly positive. Only the current phase timeout is active.\n\nPositive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and\n`ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by\ntheir phase timeout and those positive bounds. The server stores and returns normalized values.\nIncreasing a bound does not restore a capped value unless that value is also updated." + }, "v1BackfillRequest": { "type": "object", "properties": { @@ -17505,6 +17658,14 @@ "standaloneActivityOperatorCommands": { "type": "boolean", "description": "True if the namespace supports standalone activity operator commands." + }, + "standaloneActivityAsyncHandoff": { + "type": "boolean", + "description": "True if workers can report standalone activity handoff through `RespondActivityTaskHandoff`." + }, + "workflowActivityAsyncHandoff": { + "type": "boolean", + "description": "True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`." } }, "description": "Namespace capability details. Should contain what features are enabled in a namespace." @@ -18361,10 +18522,11 @@ "PENDING_ACTIVITY_STATE_STARTED", "PENDING_ACTIVITY_STATE_CANCEL_REQUESTED", "PENDING_ACTIVITY_STATE_PAUSED", - "PENDING_ACTIVITY_STATE_PAUSE_REQUESTED" + "PENDING_ACTIVITY_STATE_PAUSE_REQUESTED", + "PENDING_ACTIVITY_STATE_AWAITING_COMPLETION" ], "default": "PENDING_ACTIVITY_STATE_UNSPECIFIED", - "title": "- PENDING_ACTIVITY_STATE_PAUSED: PAUSED means activity is paused on the server, and is not running in the worker\n - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED: PAUSE_REQUESTED means activity is currently running on the worker, but paused on the server" + "description": " - PENDING_ACTIVITY_STATE_PAUSED: PAUSED means activity is paused on the server, and is not running in the worker\n - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED: PAUSE_REQUESTED means activity is currently running on the worker, but paused on the server\n - PENDING_ACTIVITY_STATE_AWAITING_COMPLETION: The server has recorded async handoff and is waiting for external completion." }, "v1PendingChildExecutionInfo": { "type": "object", @@ -18592,12 +18754,12 @@ "startedTime": { "type": "string", "format": "date-time", - "title": "When was this task started (this attempt)" + "description": "Time this activity task started." }, "attempt": { "type": "integer", "format": "int32", - "title": "Starting at 1, the number of attempts to perform this activity" + "description": "Starting at 1, the number of attempts to perform this activity\nHandoff retries increment `PollActivityTaskQueueResponse.handoff_attempt` instead." }, "scheduleToCloseTimeout": { "type": "string", @@ -18605,11 +18767,11 @@ }, "startToCloseTimeout": { "type": "string", - "title": "Current attempt start -> final result reported timeout" + "description": "Configured start-to-close timeout for the activity attempt.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Window within which the activity must report a heartbeat, or be timed out." + "description": "Window within which the activity must report a heartbeat, or be timed out.\nWhen `PollActivityTaskQueueResponse.async_handoff_options` is present, workers use\n`AsyncHandoffOptions.heartbeat_timeout` before handoff." }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", @@ -18642,6 +18804,15 @@ "propagatedNexusSerializationContext": { "$ref": "#/definitions/v1PropagatedSerializationContext", "description": "Serialization context propagated from the Nexus caller that started this activity." + }, + "handoffAttempt": { + "type": "integer", + "format": "int32", + "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`PollActivityTaskQueueResponse.async_handoff_options` are added. Increments on handoff retries\nand resets to 1 on an activity retry or applied reset. Zero when options are absent." + }, + "asyncHandoffOptions": { + "$ref": "#/definitions/v1AsyncHandoffOptions", + "description": "Handoff options for this activity task." } } }, @@ -19457,6 +19628,9 @@ } } }, + "v1RespondActivityTaskHandoffResponse": { + "type": "object" + }, "v1RetryPolicy": { "type": "object", "properties": { @@ -20776,9 +20950,12 @@ "TIMEOUT_TYPE_START_TO_CLOSE", "TIMEOUT_TYPE_SCHEDULE_TO_START", "TIMEOUT_TYPE_SCHEDULE_TO_CLOSE", - "TIMEOUT_TYPE_HEARTBEAT" + "TIMEOUT_TYPE_HEARTBEAT", + "TIMEOUT_TYPE_START_TO_HANDOFF", + "TIMEOUT_TYPE_HANDOFF_TO_CLOSE" ], - "default": "TIMEOUT_TYPE_UNSPECIFIED" + "default": "TIMEOUT_TYPE_UNSPECIFIED", + "description": " - TIMEOUT_TYPE_START_TO_HANDOFF: The worker-owned handoff phase exceeded its configured timeout before accepted handoff.\n - TIMEOUT_TYPE_HANDOFF_TO_CLOSE: The external-completion phase exceeded its configured timeout after accepted handoff." }, "v1TimerCanceledEventAttributes": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 6c8a7fbe5..73ac9f9f9 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1053,6 +1053,46 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activity-handoff: + post: + tags: + - WorkflowService + description: |- + RespondActivityTaskHandoff durably records that the current activity delivery is awaiting + external completion. Call after the external system durably accepts the submitted work. + + A successful response leaves the task token valid for heartbeats and completion. Repeating + this call with the same valid token succeeds without changing the handoff time or deadlines. + Fails with `NotFound` if the token is no longer valid. Does not support reporting by ID. + A timeout or retry does not stop work already running in the external system; applications + must make external submissions idempotent. + operationId: RespondActivityTaskHandoff + parameters: + - name: namespace + in: path + description: The namespace containing the activity. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskHandoffRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskHandoffResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/activity-heartbeat: post: tags: @@ -6138,6 +6178,46 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activity-handoff: + post: + tags: + - WorkflowService + description: |- + RespondActivityTaskHandoff durably records that the current activity delivery is awaiting + external completion. Call after the external system durably accepts the submitted work. + + A successful response leaves the task token valid for heartbeats and completion. Repeating + this call with the same valid token succeeds without changing the handoff time or deadlines. + Fails with `NotFound` if the token is no longer valid. Does not support reporting by ID. + A timeout or retry does not stop work already running in the external system; applications + must make external submissions idempotent. + operationId: RespondActivityTaskHandoff + parameters: + - name: namespace + in: path + description: The namespace containing the activity. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskHandoffRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskHandoffResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/activity-heartbeat: post: tags: @@ -9763,6 +9843,7 @@ components: - PENDING_ACTIVITY_STATE_CANCEL_REQUESTED - PENDING_ACTIVITY_STATE_PAUSED - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED + - PENDING_ACTIVITY_STATE_AWAITING_COMPLETION type: string description: More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING. format: enum @@ -9816,11 +9897,13 @@ components: format: date-time lastStartedTime: type: string - description: Time the last attempt was started. + description: Time the most recent activity task started. format: date-time attempt: type: integer - description: The attempt this activity is currently on. Incremented each time a new attempt is scheduled. + description: |- + The attempt this activity is currently on. Activity retries increment this count; + handoff retries increment `ActivityExecutionInfo.handoff_attempt` instead. format: int32 executionDuration: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ @@ -9952,6 +10035,30 @@ components: allOf: - $ref: '#/components/schemas/ResolvedPrincipal' description: Authenticated principal of the worker that most recently interacted with this activity execution. + handoffAttempt: + type: integer + description: |- + Handoff attempt within the current activity attempt. Starts at 1 when + `ActivityExecutionInfo.async_handoff_options` are added. Increments on handoff retries and + resets to 1 on an activity retry or applied reset. Zero when options are absent. + format: int32 + asyncHandoffTime: + type: string + description: |- + 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. + format: date-time + awaitingCompletion: + type: boolean + description: |- + 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. + asyncHandoffOptions: + allOf: + - $ref: '#/components/schemas/AsyncHandoffOptions' + description: Server-normalized and defaulted handoff options, if configured. description: Information about a standalone activity. ActivityExecutionListInfo: type: object @@ -10080,7 +10187,8 @@ components: type: string description: |- 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.async_handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -10100,19 +10208,30 @@ components: type: string description: |- 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.async_handoff_options` provides both phase timeouts. + When `ActivityOptions.async_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. --) heartbeatTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string - description: Maximum permitted time between successful worker heartbeats. + description: |- + Maximum permitted time between successful worker heartbeats. + When `ActivityOptions.async_handoff_options` is present, the activity heartbeat timeout + applies after handoff, starting at accepted handoff. + Before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' - description: The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + description: |- + The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + When `ActivityOptions.async_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 + `AsyncHandoffOptions.retry_policy`. priority: allOf: - $ref: '#/components/schemas/Priority' @@ -10126,6 +10245,10 @@ components: Time to wait before making the first activity task available for dispatch. This delay is not applied to retry attempts. 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. + asyncHandoffOptions: + allOf: + - $ref: '#/components/schemas/AsyncHandoffOptions' + description: Two-phase timeout and retry settings. ActivityPropertiesModifiedExternallyEventAttributes: type: object properties: @@ -10421,6 +10544,62 @@ components: - APPLICATION_ERROR_CATEGORY_BENIGN type: string format: enum + AsyncHandoffOptions: + type: object + properties: + startToHandoffTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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 + `AsyncHandoffOptions.retry_policy`. + + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" identifies the endpoints of the timeout. --) + handoffToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. --) + heartbeatTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. + retryPolicy: + allOf: + - $ref: '#/components/schemas/RetryPolicy' + description: |- + Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff. + Retries increment `ActivityExecutionInfo.handoff_attempt` without incrementing + `ActivityExecutionInfo.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 + `async_handoff_options.retry_policy` as a whole in the update mask. + description: |- + Timeout and retry options for activity handoff and external completion. The completion phase + begins when the server durably accepts `RespondActivityTaskHandoff`. + + 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. + Either `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` + must be positive; otherwise, both phase timeouts below must be positive so neither phase can + wait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout` + is enforced only when explicitly positive. Only the current phase timeout is active. + + Positive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and + `ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by + their phase timeout and those positive bounds. The server stores and returns normalized values. + Increasing a bound does not restore a capped value unless that value is also updated. BackfillRequest: type: object properties: @@ -13705,6 +13884,12 @@ components: standaloneActivityOperatorCommands: type: boolean description: True if the namespace supports standalone activity operator commands. + standaloneActivityAsyncHandoff: + type: boolean + description: True if workers can report standalone activity handoff through `RespondActivityTaskHandoff`. + workflowActivityAsyncHandoff: + type: boolean + description: True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`. description: Namespace capability details. Should contain what features are enabled in a namespace. NamespaceInfo_Limits: type: object @@ -14515,6 +14700,7 @@ components: - PENDING_ACTIVITY_STATE_CANCEL_REQUESTED - PENDING_ACTIVITY_STATE_PAUSED - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED + - PENDING_ACTIVITY_STATE_AWAITING_COMPLETION type: string format: enum heartbeatDetails: @@ -14833,11 +15019,13 @@ components: format: date-time startedTime: type: string - description: When was this task started (this attempt) + description: Time this activity task started. format: date-time attempt: type: integer - description: Starting at 1, the number of attempts to perform this activity + description: |- + Starting at 1, the number of attempts to perform this activity + Handoff retries increment `PollActivityTaskQueueResponse.handoff_attempt` instead. format: int32 scheduleToCloseTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ @@ -14851,14 +15039,17 @@ components: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: |- - Current attempt start -> final result reported timeout + Configured start-to-close timeout for the activity attempt. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) heartbeatTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string - description: Window within which the activity must report a heartbeat, or be timed out. + description: |- + Window within which the activity must report a heartbeat, or be timed out. + When `PollActivityTaskQueueResponse.async_handoff_options` is present, workers use + `AsyncHandoffOptions.heartbeat_timeout` before handoff. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' @@ -14903,6 +15094,17 @@ components: allOf: - $ref: '#/components/schemas/PropagatedSerializationContext' description: Serialization context propagated from the Nexus caller that started this activity. + handoffAttempt: + type: integer + description: |- + Handoff attempt within the current activity attempt. Starts at 1 when + `PollActivityTaskQueueResponse.async_handoff_options` are added. Increments on handoff retries + and resets to 1 on an activity retry or applied reset. Zero when options are absent. + format: int32 + asyncHandoffOptions: + allOf: + - $ref: '#/components/schemas/AsyncHandoffOptions' + description: Handoff options for this activity task. PollNexusOperationExecutionResponse: type: object properties: @@ -16322,6 +16524,32 @@ components: description: |- Server validation failures could include last_heartbeat_details payload is too large, request failure is too large + RespondActivityTaskHandoffRequest: + type: object + properties: + taskToken: + type: string + description: The task token as received in `PollActivityTaskQueueResponse`. + format: bytes + identity: + type: string + description: The identity of the worker reporting handoff. + namespace: + type: string + description: The namespace containing the activity. + resourceId: + type: string + description: Resource ID for routing. + deploymentOptions: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentOptions' + description: |- + Worker deployment options configured on the worker. Must be set if the worker has + `WorkerDeploymentOptions` configured, regardless of whether versioning is enabled. + description: Reports handoff of the current activity task for external completion. + RespondActivityTaskHandoffResponse: + type: object + properties: {} RetryPolicy: type: object properties: @@ -17312,7 +17540,8 @@ components: type: string description: |- 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 `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -17331,15 +17560,19 @@ components: type: string description: |- 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 `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. See + `ActivityOptions.start_to_close_timeout`. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) heartbeatTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string - description: Maximum permitted time between successful worker heartbeats. + description: |- + Maximum permitted time between successful worker heartbeats. + See `ActivityOptions.heartbeat_timeout` for behavior when + `StartActivityExecutionRequest.async_handoff_options` is present. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' @@ -17418,6 +17651,10 @@ components: being dispatched through a task queue. If set to true, the caller is expected to have a worker available and capable of processing the task. The returned task will be marked as started. The server may ignore this request. + asyncHandoffOptions: + allOf: + - $ref: '#/components/schemas/AsyncHandoffOptions' + description: Two-phase timeout and retry settings. StartActivityExecutionResponse: type: object properties: @@ -18536,6 +18773,8 @@ components: - TIMEOUT_TYPE_SCHEDULE_TO_START - TIMEOUT_TYPE_SCHEDULE_TO_CLOSE - TIMEOUT_TYPE_HEARTBEAT + - TIMEOUT_TYPE_START_TO_HANDOFF + - TIMEOUT_TYPE_HANDOFF_TO_CLOSE type: string format: enum lastHeartbeatDetails: @@ -21743,6 +21982,8 @@ components: - TIMEOUT_TYPE_SCHEDULE_TO_START - TIMEOUT_TYPE_SCHEDULE_TO_CLOSE - TIMEOUT_TYPE_HEARTBEAT + - TIMEOUT_TYPE_START_TO_HANDOFF + - TIMEOUT_TYPE_HANDOFF_TO_CLOSE type: string format: enum WorkflowType: diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index 077ceba99..41f0dfff1 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -36,11 +36,58 @@ message ActivityExecutionOutcome { temporal.api.enums.v1.RetryState retry_state = 3; } +// Timeout and retry options for activity handoff and external completion. The completion phase +// begins when the server durably accepts `RespondActivityTaskHandoff`. +// +// 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. +// Either `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` +// must be positive; otherwise, both phase timeouts below must be positive so neither phase can +// wait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout` +// is enforced only when explicitly positive. Only the current phase timeout is active. +// +// Positive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and +// `ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by +// their phase timeout and those positive bounds. The server stores and returns normalized values. +// Increasing a bound does not restore a capped value unless that value is also updated. +message AsyncHandoffOptions { + // 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 + // `AsyncHandoffOptions.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 `ActivityExecutionInfo.handoff_attempt` without incrementing + // `ActivityExecutionInfo.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 + // `async_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.async_handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -54,15 +101,24 @@ message ActivityOptions { // 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.async_handoff_options` provides both phase timeouts. + // When `ActivityOptions.async_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.async_handoff_options` is present, the activity heartbeat timeout + // applies after handoff, starting at accepted handoff. + // Before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. google.protobuf.Duration heartbeat_timeout = 5; // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + // When `ActivityOptions.async_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 + // `AsyncHandoffOptions.retry_policy`. temporal.api.common.v1.RetryPolicy retry_policy = 6; // Priority metadata. If this message is not present, or any fields are not @@ -73,6 +129,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. + AsyncHandoffOptions async_handoff_options = 9; } // Information about a standalone activity. @@ -121,9 +180,10 @@ message ActivityExecutionInfo { 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; @@ -218,6 +278,24 @@ 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.async_handoff_options` are added. 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 async_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 awaiting_completion = 46; + + // Server-normalized and defaulted handoff options, if configured. + AsyncHandoffOptions async_handoff_options = 47; } // Limited activity information returned in the list response. diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index a9ac3fc33..390dd7931 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -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; + // The server has recorded async handoff and is waiting for external completion. + PENDING_ACTIVITY_STATE_AWAITING_COMPLETION = 6; } enum PendingWorkflowTaskState { @@ -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 diff --git a/temporal/api/namespace/v1/message.proto b/temporal/api/namespace/v1/message.proto index a80566458..a276b70c7 100644 --- a/temporal/api/namespace/v1/message.proto +++ b/temporal/api/namespace/v1/message.proto @@ -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_async_handoff = 18; + // True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`. + bool workflow_activity_async_handoff = 19; } // Namespace configured limits diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 859bbcdc9..33bd685db 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -611,21 +611,24 @@ message PollActivityTaskQueueResponse { google.protobuf.Timestamp scheduled_time = 10; // When was this task attempt scheduled google.protobuf.Timestamp current_attempt_scheduled_time = 11; - // When was this task started (this attempt) + // Time this activity task started. google.protobuf.Timestamp started_time = 12; // Starting at 1, the number of attempts to perform this activity + // Handoff retries increment `PollActivityTaskQueueResponse.handoff_attempt` instead. int32 attempt = 13; // First scheduled -> final result reported timeout // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration schedule_to_close_timeout = 14; - // Current attempt start -> final result reported timeout + // Configured start-to-close timeout for the activity attempt. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration start_to_close_timeout = 15; // Window within which the activity must report a heartbeat, or be timed out. + // When `PollActivityTaskQueueResponse.async_handoff_options` is present, workers use + // `AsyncHandoffOptions.heartbeat_timeout` before handoff. google.protobuf.Duration heartbeat_timeout = 16; // This is the retry policy the service uses which may be different from the one provided // (or not) during activity scheduling. The service can override the provided one if some @@ -654,6 +657,14 @@ message PollActivityTaskQueueResponse { temporal.api.taskqueue.v1.PollerGroupsInfo poller_groups_info = 22; // Serialization context propagated from the Nexus caller that started this activity. temporal.api.nexus.v1.PropagatedSerializationContext propagated_nexus_serialization_context = 23; + + // Handoff attempt within the current activity attempt. Starts at 1 when + // `PollActivityTaskQueueResponse.async_handoff_options` are added. Increments on handoff retries + // and resets to 1 on an activity retry or applied reset. Zero when options are absent. + int32 handoff_attempt = 24; + + // Handoff options for this activity task. + temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 25; } message RecordActivityTaskHeartbeatRequest { @@ -712,6 +723,24 @@ message RecordActivityTaskHeartbeatByIdResponse { bool activity_reset = 3; } +// Reports handoff of the current activity task for external completion. +message RespondActivityTaskHandoffRequest { + // The task token as received in `PollActivityTaskQueueResponse`. + bytes task_token = 1; + // The identity of the worker reporting handoff. + string identity = 2; + // The namespace containing the activity. + string namespace = 3; + // Resource ID for routing. + string resource_id = 4; + // Worker deployment options configured on the worker. Must be set if the worker has + // `WorkerDeploymentOptions` configured, regardless of whether versioning is enabled. + temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 5; +} + +message RespondActivityTaskHandoffResponse { +} + message RespondActivityTaskCompletedRequest { // The task token as received in `PollActivityTaskQueueResponse` bytes task_token = 1; @@ -3278,7 +3307,8 @@ message StartActivityExecutionRequest { // Task queue to schedule this activity on. temporal.api.taskqueue.v1.TaskQueue task_queue = 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 `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -3291,13 +3321,16 @@ message StartActivityExecutionRequest { // 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 `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. See + // `ActivityOptions.start_to_close_timeout`. // // (-- 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. + // See `ActivityOptions.heartbeat_timeout` for behavior when + // `StartActivityExecutionRequest.async_handoff_options` is present. google.protobuf.Duration heartbeat_timeout = 10; // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. temporal.api.common.v1.RetryPolicy retry_policy = 11; @@ -3337,6 +3370,9 @@ message StartActivityExecutionRequest { // worker available and capable of processing the task. The returned task will be marked as // started. The server may ignore this request. bool request_eager_execution = 24; + + // Two-phase timeout and retry settings. + temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 25; } message StartActivityExecutionResponse { diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 4de2dac14..e06f603d9 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -289,6 +289,29 @@ service WorkflowService { }; } + // RespondActivityTaskHandoff durably records that the current activity delivery is awaiting + // external completion. Call after the external system durably accepts the submitted work. + // + // A successful response leaves the task token valid for heartbeats and completion. Repeating + // this call with the same valid token succeeds without changing the handoff time or deadlines. + // Fails with `NotFound` if the token is no longer valid. Does not support reporting by ID. + // A timeout or retry does not stop work already running in the external system; applications + // must make external submissions idempotent. + rpc RespondActivityTaskHandoff (RespondActivityTaskHandoffRequest) returns (RespondActivityTaskHandoffResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/activity-handoff" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/activity-handoff" + body: "*" + } + }; + option (temporal.api.protometa.v1.request_header) = { + header: "temporal-resource-id" + value: "{resource_id}" + }; + } + // RespondActivityTaskCompleted is called by workers when they successfully complete an activity // task. // From f05f0791f4e70a881e8b608ccb22a1e150e6241f Mon Sep 17 00:00:00 2001 From: Fred Tzeng Date: Mon, 19 Oct 2026 21:04:55 -0700 Subject: [PATCH 2/7] Polish docs --- openapi/openapiv2.json | 14 +++++----- openapi/openapiv3.yaml | 27 +++++++++++++------ temporal/api/activity/v1/message.proto | 7 +++-- .../workflowservice/v1/request_response.proto | 10 ++++--- 4 files changed, 38 insertions(+), 20 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 453d64c6c..a226b7b66 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -12405,7 +12405,7 @@ }, "resourceId": { "type": "string", - "description": "Resource ID for routing." + "description": "Resource ID for routing. Contains \"workflow:{workflow_id}\" for workflow activities or\n\"activity:{activity_id}\" for standalone activities." }, "deploymentOptions": { "$ref": "#/definitions/v1WorkerDeploymentOptions", @@ -12705,7 +12705,7 @@ }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`." + "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.\nSee `ActivityOptions.retry_policy` for behavior with handoff options." }, "input": { "$ref": "#/definitions/v1Payloads", @@ -13942,11 +13942,11 @@ }, "heartbeatTimeout": { "type": "string", - "description": "Maximum permitted time between successful worker heartbeats." + "description": "Maximum permitted time between successful worker heartbeats.\nSee `ActivityOptions.heartbeat_timeout` for behavior with handoff options." }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`." + "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.\nSee `ActivityOptions.retry_policy` for behavior with handoff options." }, "heartbeatDetails": { "$ref": "#/definitions/v1Payloads", @@ -14092,7 +14092,7 @@ "handoffAttempt": { "type": "integer", "format": "int32", - "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`ActivityExecutionInfo.async_handoff_options` are added. Increments on handoff retries and\nresets to 1 on an activity retry or applied reset. Zero when options are absent." + "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`ActivityExecutionInfo.async_handoff_options` are configured at creation or added by update.\nIncrements on handoff retries and resets to 1 on an activity retry or applied reset.\nZero when options are absent." }, "asyncHandoffTime": { "type": "string", @@ -18775,7 +18775,7 @@ }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "This is the retry policy the service uses which may be different from the one provided\n(or not) during activity scheduling. The service can override the provided one if some\nvalues are not specified or exceed configured system limits." + "description": "This is the retry policy the service uses which may be different from the one provided\n(or not) during activity scheduling. The service can override the provided one if some\nvalues are not specified or exceed configured system limits.\nSee `ActivityOptions.retry_policy` for behavior with handoff options." }, "pollerScalingDecision": { "$ref": "#/definitions/v1PollerScalingDecision", @@ -18808,7 +18808,7 @@ "handoffAttempt": { "type": "integer", "format": "int32", - "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`PollActivityTaskQueueResponse.async_handoff_options` are added. Increments on handoff retries\nand resets to 1 on an activity retry or applied reset. Zero when options are absent." + "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`PollActivityTaskQueueResponse.async_handoff_options` are configured at creation or added by update.\nIncrements on handoff retries and resets to 1 on an activity retry or applied reset.\nZero when options are absent." }, "asyncHandoffOptions": { "$ref": "#/definitions/v1AsyncHandoffOptions", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 73ac9f9f9..3ad46d07c 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -9880,11 +9880,15 @@ components: heartbeatTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string - description: Maximum permitted time between successful worker heartbeats. + description: |- + Maximum permitted time between successful worker heartbeats. + See `ActivityOptions.heartbeat_timeout` for behavior with handoff options. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' - description: The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + description: |- + The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + See `ActivityOptions.retry_policy` for behavior with handoff options. heartbeatDetails: allOf: - $ref: '#/components/schemas/Payloads' @@ -10039,8 +10043,9 @@ components: type: integer description: |- Handoff attempt within the current activity attempt. Starts at 1 when - `ActivityExecutionInfo.async_handoff_options` are added. Increments on handoff retries and - resets to 1 on an activity retry or applied reset. Zero when options are absent. + `ActivityExecutionInfo.async_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. format: int32 asyncHandoffTime: type: string @@ -15057,6 +15062,7 @@ components: This is the retry policy the service uses which may be different from the one provided (or not) during activity scheduling. The service can override the provided one if some values are not specified or exceed configured system limits. + See `ActivityOptions.retry_policy` for behavior with handoff options. pollerScalingDecision: allOf: - $ref: '#/components/schemas/PollerScalingDecision' @@ -15098,8 +15104,9 @@ components: type: integer description: |- Handoff attempt within the current activity attempt. Starts at 1 when - `PollActivityTaskQueueResponse.async_handoff_options` are added. Increments on handoff retries - and resets to 1 on an activity retry or applied reset. Zero when options are absent. + `PollActivityTaskQueueResponse.async_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. format: int32 asyncHandoffOptions: allOf: @@ -16539,7 +16546,9 @@ components: description: The namespace containing the activity. resourceId: type: string - description: Resource ID for routing. + description: |- + Resource ID for routing. Contains "workflow:{workflow_id}" for workflow activities or + "activity:{activity_id}" for standalone activities. deploymentOptions: allOf: - $ref: '#/components/schemas/WorkerDeploymentOptions' @@ -17576,7 +17585,9 @@ components: retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' - description: The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + description: |- + The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + See `ActivityOptions.retry_policy` for behavior with handoff options. input: allOf: - $ref: '#/components/schemas/Payloads' diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index 41f0dfff1..66776c333 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -170,9 +170,11 @@ 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. @@ -280,8 +282,9 @@ message ActivityExecutionInfo { temporal.api.common.v1.ResolvedPrincipal last_worker_principal = 43; // Handoff attempt within the current activity attempt. Starts at 1 when - // `ActivityExecutionInfo.async_handoff_options` are added. Increments on handoff retries and - // resets to 1 on an activity retry or applied reset. Zero when options are absent. + // `ActivityExecutionInfo.async_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 diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 33bd685db..c8a9b5090 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -633,6 +633,7 @@ message PollActivityTaskQueueResponse { // This is the retry policy the service uses which may be different from the one provided // (or not) during activity scheduling. The service can override the provided one if some // values are not specified or exceed configured system limits. + // See `ActivityOptions.retry_policy` for behavior with handoff options. temporal.api.common.v1.RetryPolicy retry_policy = 17; // Server-advised information the SDK may use to adjust its poller count. temporal.api.taskqueue.v1.PollerScalingDecision poller_scaling_decision = 18; @@ -659,8 +660,9 @@ message PollActivityTaskQueueResponse { temporal.api.nexus.v1.PropagatedSerializationContext propagated_nexus_serialization_context = 23; // Handoff attempt within the current activity attempt. Starts at 1 when - // `PollActivityTaskQueueResponse.async_handoff_options` are added. Increments on handoff retries - // and resets to 1 on an activity retry or applied reset. Zero when options are absent. + // `PollActivityTaskQueueResponse.async_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 = 24; // Handoff options for this activity task. @@ -731,7 +733,8 @@ message RespondActivityTaskHandoffRequest { string identity = 2; // The namespace containing the activity. string namespace = 3; - // Resource ID for routing. + // Resource ID for routing. Contains "workflow:{workflow_id}" for workflow activities or + // "activity:{activity_id}" for standalone activities. string resource_id = 4; // Worker deployment options configured on the worker. Must be set if the worker has // `WorkerDeploymentOptions` configured, regardless of whether versioning is enabled. @@ -3333,6 +3336,7 @@ message StartActivityExecutionRequest { // `StartActivityExecutionRequest.async_handoff_options` is present. 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; // Serialized arguments to the activity. These are passed as arguments to the activity function. From 2d8551589e5dbdb38d5b3126a00f9b8be113d1d5 Mon Sep 17 00:00:00 2001 From: Fred Tzeng Date: Thu, 5 Nov 2026 13:18:36 -0800 Subject: [PATCH 3/7] Add WFA support --- openapi/openapiv2.json | 34 ++++++++++++++++---- openapi/openapiv3.yaml | 43 +++++++++++++++++++++----- temporal/api/activity/v1/message.proto | 3 +- temporal/api/command/v1/message.proto | 19 +++++++++--- temporal/api/history/v1/message.proto | 20 ++++++++---- temporal/api/workflow/v1/message.proto | 14 +++++++++ 6 files changed, 108 insertions(+), 25 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index a226b7b66..bed725024 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -14260,7 +14260,7 @@ }, "scheduleToStartTimeout": { "type": "string", - "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified.\n" + "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified. With `async_handoff_options` set, defaults to a positive\n`schedule_to_close_timeout`, otherwise remains disabled.\n" }, "startToCloseTimeout": { "type": "string", @@ -14442,19 +14442,19 @@ }, "scheduleToCloseTimeout": { "type": "string", - "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified.\n" + "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `async_handoff_options` provides both phase timeouts.\n" }, "scheduleToStartTimeout": { "type": "string", - "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified.\n" + "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified. With `async_handoff_options` set, defaults to a positive\n`schedule_to_close_timeout`, otherwise remains disabled.\n" }, "startToCloseTimeout": { "type": "string", - "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be\nspecified.\n" + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be\nspecified, unless `async_handoff_options` provides both phase timeouts. With handoff\noptions set, see `ActivityOptions.start_to_close_timeout` for timing.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Maximum permitted time between successful worker heartbeats." + "description": "Maximum permitted time between successful worker heartbeats. With `async_handoff_options`\nset, applies after handoff; before handoff, use `AsyncHandoffOptions.heartbeat_timeout`." }, "workflowTaskCompletedEventId": { "type": "string", @@ -14463,7 +14463,7 @@ }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "Activities are assigned a default retry policy controlled by the service's dynamic\nconfiguration. Retries will happen up to `schedule_to_close_timeout`. To disable retries set\nretry_policy.maximum_attempts to 1." + "description": "Activities are assigned a default retry policy controlled by the service's dynamic\nconfiguration. Retries will happen up to `schedule_to_close_timeout`. To disable retries under\nthis policy, set retry_policy.maximum_attempts to 1.\nWith `async_handoff_options` set, see `ActivityOptions.retry_policy` for applicability." }, "useWorkflowBuildId": { "type": "boolean", @@ -14472,6 +14472,10 @@ "priority": { "$ref": "#/definitions/v1Priority", "description": "Priority metadata. If this message is not present, or any fields are not\npresent, they inherit the values from the workflow." + }, + "asyncHandoffOptions": { + "$ref": "#/definitions/v1AsyncHandoffOptions", + "description": "Handoff timeout and retry settings." } } }, @@ -18511,6 +18515,24 @@ "activityOptions": { "$ref": "#/definitions/v1ActivityOptions", "description": "Current activity options. May be different from the one used to start the activity." + }, + "handoffAttempt": { + "type": "integer", + "format": "int32", + "description": "Handoff attempt within the activity attempt. Starts at 1 when handoff options are\nconfigured, increments on handoff retries, and resets to 1 on an activity retry or applied\nreset. Zero when handoff options are absent." + }, + "asyncHandoffTime": { + "type": "string", + "format": "date-time", + "description": "Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset." + }, + "awaitingCompletion": { + "type": "boolean", + "description": "True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it." + }, + "asyncHandoffOptions": { + "$ref": "#/definitions/v1AsyncHandoffOptions", + "description": "Server-normalized and defaulted handoff options." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 3ad46d07c..242312950 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10204,7 +10204,8 @@ components: 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 `async_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. --) @@ -10386,7 +10387,8 @@ components: type: string description: |- 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 `async_handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -10397,7 +10399,8 @@ components: 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 `async_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. --) @@ -10407,14 +10410,17 @@ components: description: |- 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 `async_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. --) heartbeatTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string - description: Maximum permitted time between successful worker heartbeats. + description: |- + Maximum permitted time between successful worker heartbeats. With `async_handoff_options` + set, applies after handoff; before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. workflowTaskCompletedEventId: type: string description: The `WORKFLOW_TASK_COMPLETED` event which this command was reported with @@ -10423,8 +10429,9 @@ components: - $ref: '#/components/schemas/RetryPolicy' description: |- 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 `async_handoff_options` set, see `ActivityOptions.retry_policy` for applicability. useWorkflowBuildId: type: boolean description: |- @@ -10437,6 +10444,10 @@ components: description: |- Priority metadata. If this message is not present, or any fields are not present, they inherit the values from the workflow. + asyncHandoffOptions: + allOf: + - $ref: '#/components/schemas/AsyncHandoffOptions' + description: Handoff timeout and retry settings. ActivityTaskStartedEventAttributes: type: object properties: @@ -14796,6 +14807,24 @@ components: allOf: - $ref: '#/components/schemas/ActivityOptions' description: Current activity options. May be different from the one used to start the activity. + handoffAttempt: + type: integer + description: |- + 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. + format: int32 + asyncHandoffTime: + type: string + description: Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset. + format: date-time + awaitingCompletion: + type: boolean + description: True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. + asyncHandoffOptions: + allOf: + - $ref: '#/components/schemas/AsyncHandoffOptions' + description: Server-normalized and defaulted handoff options. PendingActivityInfo_PauseInfo: type: object properties: diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index 66776c333..ee711cad1 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -95,7 +95,8 @@ message ActivityOptions { // 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 `async_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. --) diff --git a/temporal/api/command/v1/message.proto b/temporal/api/command/v1/message.proto index ee839115b..7759bc5aa 100644 --- a/temporal/api/command/v1/message.proto +++ b/temporal/api/command/v1/message.proto @@ -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"; @@ -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 `async_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. --) @@ -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 `async_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 `async_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 `async_handoff_options` + // set, applies after handoff; before handoff, use `AsyncHandoffOptions.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 `async_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. @@ -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.AsyncHandoffOptions async_handoff_options = 15; } message RequestCancelActivityTaskCommandAttributes { diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index aeeb334f2..d81098cf2 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -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"; @@ -432,7 +433,8 @@ 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 `async_handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -440,25 +442,29 @@ message ActivityTaskScheduledEventAttributes { // 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 `async_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 `async_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 `async_handoff_options` + // set, applies after handoff; before handoff, use `AsyncHandoffOptions.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 `async_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. @@ -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.AsyncHandoffOptions async_handoff_options = 15; } message ActivityTaskStartedEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 86224a4b1..bf1fef49d 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -381,6 +381,20 @@ 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 async_handoff_time = 27; + + // True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. + bool awaiting_completion = 28; + + // Server-normalized and defaulted handoff options. + temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 29; } message PendingChildExecutionInfo { From 8a9f3d07c0580012b8242f7a4e3d4cef972c8531 Mon Sep 17 00:00:00 2001 From: Fred Tzeng Date: Fri, 6 Nov 2026 10:43:17 -0800 Subject: [PATCH 4/7] Remove redundant field --- openapi/openapiv2.json | 6 +----- openapi/openapiv3.yaml | 8 ++------ temporal/api/activity/v1/message.proto | 4 ++-- temporal/api/workflow/v1/message.proto | 3 --- 4 files changed, 5 insertions(+), 16 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index bed725024..fab3c7068 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -14614,7 +14614,7 @@ }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff.\nRetries increment `ActivityExecutionInfo.handoff_attempt` without incrementing\n`ActivityExecutionInfo.attempt`. Exhausting this policy does not fall back to\n`ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry\npolicy, independently of `ActivityOptions.retry_policy`.\nTo change `RetryPolicy.non_retryable_error_types`, replace\n`async_handoff_options.retry_policy` as a whole in the update mask." + "description": "Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff.\nRetries increment `PollActivityTaskQueueResponse.handoff_attempt` without incrementing\n`PollActivityTaskQueueResponse.attempt`. Exhausting this policy does not fall back to\n`ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry\npolicy, independently of `ActivityOptions.retry_policy`.\nTo change `RetryPolicy.non_retryable_error_types`, replace\n`async_handoff_options.retry_policy` as a whole in the update mask." } }, "description": "Timeout and retry options for activity handoff and external completion. The completion phase\nbegins when the server durably accepts `RespondActivityTaskHandoff`.\n\nPresence, including an empty message, enables two-phase timeouts and retries. Absence preserves\nexisting timeout, retry, and attempt-counting behavior even when handoff is reported.\nEither `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout`\nmust be positive; otherwise, both phase timeouts below must be positive so neither phase can\nwait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout`\nis enforced only when explicitly positive. Only the current phase timeout is active.\n\nPositive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and\n`ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by\ntheir phase timeout and those positive bounds. The server stores and returns normalized values.\nIncreasing a bound does not restore a capped value unless that value is also updated." @@ -18529,10 +18529,6 @@ "awaitingCompletion": { "type": "boolean", "description": "True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it." - }, - "asyncHandoffOptions": { - "$ref": "#/definitions/v1AsyncHandoffOptions", - "description": "Server-normalized and defaulted handoff options." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 242312950..aa7d13936 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10595,8 +10595,8 @@ components: - $ref: '#/components/schemas/RetryPolicy' description: |- Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff. - Retries increment `ActivityExecutionInfo.handoff_attempt` without incrementing - `ActivityExecutionInfo.attempt`. Exhausting this policy does not fall back to + 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 @@ -14821,10 +14821,6 @@ components: awaitingCompletion: type: boolean description: True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. - asyncHandoffOptions: - allOf: - - $ref: '#/components/schemas/AsyncHandoffOptions' - description: Server-normalized and defaulted handoff options. PendingActivityInfo_PauseInfo: type: object properties: diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index ee711cad1..a0c24c8e2 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -73,8 +73,8 @@ message AsyncHandoffOptions { google.protobuf.Duration heartbeat_timeout = 3; // Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff. - // Retries increment `ActivityExecutionInfo.handoff_attempt` without incrementing - // `ActivityExecutionInfo.attempt`. Exhausting this policy does not fall back to + // 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 diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index bf1fef49d..c9fb9a9aa 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -392,9 +392,6 @@ message PendingActivityInfo { // True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. bool awaiting_completion = 28; - - // Server-normalized and defaulted handoff options. - temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 29; } message PendingChildExecutionInfo { From 1922899c3039d63e421cdea43ecb8ab5d5a85076 Mon Sep 17 00:00:00 2001 From: Fred Tzeng Date: Fri, 13 Nov 2026 12:06:52 -0800 Subject: [PATCH 5/7] Address pr comment --- openapi/openapiv2.json | 102 +++++----- openapi/openapiv3.yaml | 179 +++++++++--------- temporal/api/activity/v1/message.proto | 28 +-- temporal/api/command/v1/message.proto | 14 +- temporal/api/history/v1/message.proto | 14 +- .../workflowservice/v1/request_response.proto | 17 +- 6 files changed, 178 insertions(+), 176 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index fab3c7068..1e3f38aa3 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -12689,7 +12689,7 @@ }, "scheduleToCloseTimeout": { "type": "string", - "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts.\n" + "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `StartActivityExecutionRequest.handoff_options` provides both phase timeouts.\n" }, "scheduleToStartTimeout": { "type": "string", @@ -12697,11 +12697,11 @@ }, "startToCloseTimeout": { "type": "string", - "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,\nunless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. See\n`ActivityOptions.start_to_close_timeout`.\n" + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,\nunless `StartActivityExecutionRequest.handoff_options` provides both phase timeouts. See\n`ActivityOptions.start_to_close_timeout`.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Maximum permitted time between successful worker heartbeats.\nSee `ActivityOptions.heartbeat_timeout` for behavior when\n`StartActivityExecutionRequest.async_handoff_options` is present." + "description": "Maximum permitted time between successful worker heartbeats.\nSee `ActivityOptions.heartbeat_timeout` for behavior when\n`StartActivityExecutionRequest.handoff_options` is present." }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", @@ -12767,8 +12767,8 @@ "type": "boolean", "description": "Request that the first activity task be returned directly in the start response instead of\nbeing dispatched through a task queue. If set to true, the caller is expected to have a\nworker available and capable of processing the task. The returned task will be marked as\nstarted. The server may ignore this request." }, - "asyncHandoffOptions": { - "$ref": "#/definitions/v1AsyncHandoffOptions", + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", "description": "Two-phase timeout and retry settings." } } @@ -14092,7 +14092,7 @@ "handoffAttempt": { "type": "integer", "format": "int32", - "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`ActivityExecutionInfo.async_handoff_options` are configured at creation or added by update.\nIncrements on handoff retries and resets to 1 on an activity retry or applied reset.\nZero when options are absent." + "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`ActivityExecutionInfo.handoff_options` are configured at creation or added by update.\nIncrements on handoff retries and resets to 1 on an activity retry or applied reset.\nZero when options are absent." }, "asyncHandoffTime": { "type": "string", @@ -14103,8 +14103,8 @@ "type": "boolean", "description": "True while the current delivery awaits external completion, independent of\n`ActivityExecutionInfo.run_state`. Cleared when the delivery ends or is reset;\npending pause, cancel, or reset requests do not clear it." }, - "asyncHandoffOptions": { - "$ref": "#/definitions/v1AsyncHandoffOptions", + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", "description": "Server-normalized and defaulted handoff options, if configured." } }, @@ -14256,23 +14256,23 @@ }, "scheduleToCloseTimeout": { "type": "string", - "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `ActivityOptions.async_handoff_options` provides both phase timeouts.\n" + "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `ActivityOptions.handoff_options` provides both phase timeouts.\n" }, "scheduleToStartTimeout": { "type": "string", - "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified. With `async_handoff_options` set, defaults to a positive\n`schedule_to_close_timeout`, otherwise remains disabled.\n" + "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified. With `handoff_options` set, defaults to a positive\n`schedule_to_close_timeout`, otherwise remains disabled.\n" }, "startToCloseTimeout": { "type": "string", - "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,\nunless `ActivityOptions.async_handoff_options` provides both phase timeouts.\nWhen `ActivityOptions.async_handoff_options` is present, the start-to-close timeout runs from\nthe first worker pickup of the activity attempt across both phases, handoff retries, backoff, and\nqueue waits.\n" + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be specified,\nunless `ActivityOptions.handoff_options` provides both phase timeouts.\nWhen `ActivityOptions.handoff_options` is present, the start-to-close timeout runs from\nthe first worker pickup of the activity attempt across both phases, handoff retries, backoff, and\nqueue waits.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Maximum permitted time between successful worker heartbeats.\nWhen `ActivityOptions.async_handoff_options` is present, the activity heartbeat timeout\napplies after handoff, starting at accepted handoff.\nBefore handoff, use `AsyncHandoffOptions.heartbeat_timeout`." + "description": "Maximum permitted time between successful worker heartbeats.\nWhen `ActivityOptions.handoff_options` is present, the activity heartbeat timeout\napplies after handoff, starting at accepted handoff.\nBefore handoff, use `HandoffOptions.heartbeat_timeout`." }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.\nWhen `ActivityOptions.async_handoff_options` is present, this policy handles post-handoff failures\nand timeouts, plus start-to-close timeouts in either phase. Other pre-handoff failures use\n`AsyncHandoffOptions.retry_policy`." + "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`.\nWhen `ActivityOptions.handoff_options` is present, this policy handles post-handoff failures\nand timeouts, plus start-to-close timeouts in either phase. Other pre-handoff failures use\n`HandoffOptions.retry_policy`." }, "priority": { "$ref": "#/definitions/v1Priority", @@ -14282,8 +14282,8 @@ "type": "string", "description": "Time to wait before making the first activity task available for dispatch. This delay is not applied to retry attempts.\nWhen updated, the time is added to the original `schedule_time`, not to the current time.\nIf the resulting time is in the past, the task is made available for dispatch immediately." }, - "asyncHandoffOptions": { - "$ref": "#/definitions/v1AsyncHandoffOptions", + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", "description": "Two-phase timeout and retry settings." } } @@ -14442,19 +14442,19 @@ }, "scheduleToCloseTimeout": { "type": "string", - "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `async_handoff_options` provides both phase timeouts.\n" + "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified,\nunless `handoff_options` provides both phase timeouts.\n" }, "scheduleToStartTimeout": { "type": "string", - "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified. With `async_handoff_options` set, defaults to a positive\n`schedule_to_close_timeout`, otherwise remains disabled.\n" + "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` or workflow execution timeout if not\nspecified. With `handoff_options` set, defaults to a positive\n`schedule_to_close_timeout`, otherwise remains disabled.\n" }, "startToCloseTimeout": { "type": "string", - "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be\nspecified, unless `async_handoff_options` provides both phase timeouts. With handoff\noptions set, see `ActivityOptions.start_to_close_timeout` for timing.\n" + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be\nspecified, unless `handoff_options` provides both phase timeouts. With handoff\noptions set, see `ActivityOptions.start_to_close_timeout` for timing.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Maximum permitted time between successful worker heartbeats. With `async_handoff_options`\nset, applies after handoff; before handoff, use `AsyncHandoffOptions.heartbeat_timeout`." + "description": "Maximum permitted time between successful worker heartbeats. With `handoff_options`\nset, applies after handoff; before handoff, use `HandoffOptions.heartbeat_timeout`." }, "workflowTaskCompletedEventId": { "type": "string", @@ -14463,7 +14463,7 @@ }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", - "description": "Activities are assigned a default retry policy controlled by the service's dynamic\nconfiguration. Retries will happen up to `schedule_to_close_timeout`. To disable retries under\nthis policy, set retry_policy.maximum_attempts to 1.\nWith `async_handoff_options` set, see `ActivityOptions.retry_policy` for applicability." + "description": "Activities are assigned a default retry policy controlled by the service's dynamic\nconfiguration. Retries will happen up to `schedule_to_close_timeout`. To disable retries under\nthis policy, set retry_policy.maximum_attempts to 1.\nWith `handoff_options` set, see `ActivityOptions.retry_policy` for applicability." }, "useWorkflowBuildId": { "type": "boolean", @@ -14473,8 +14473,8 @@ "$ref": "#/definitions/v1Priority", "description": "Priority metadata. If this message is not present, or any fields are not\npresent, they inherit the values from the workflow." }, - "asyncHandoffOptions": { - "$ref": "#/definitions/v1AsyncHandoffOptions", + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", "description": "Handoff timeout and retry settings." } } @@ -14597,28 +14597,6 @@ ], "default": "ARCHIVAL_STATE_UNSPECIFIED" }, - "v1AsyncHandoffOptions": { - "type": "object", - "properties": { - "startToHandoffTimeout": { - "type": "string", - "description": "Maximum time from the current worker pickup until the server durably accepts handoff. Unset\nor zero disables this timeout. On timeout, the server retries according to\n`AsyncHandoffOptions.retry_policy`.\n" - }, - "handoffToCloseTimeout": { - "type": "string", - "description": "Maximum time from the server durably accepting handoff until the current activity attempt\ncloses. Unset or zero disables this timeout. On timeout, the server retries according to\n`ActivityOptions.retry_policy`.\n" - }, - "heartbeatTimeout": { - "type": "string", - "description": "Maximum time between recorded heartbeats before accepted handoff, initially measured from\nworker pickup. Unset or zero disables it; `ActivityOptions.heartbeat_timeout` is not inherited\nand applies only after handoff." - }, - "retryPolicy": { - "$ref": "#/definitions/v1RetryPolicy", - "description": "Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff.\nRetries increment `PollActivityTaskQueueResponse.handoff_attempt` without incrementing\n`PollActivityTaskQueueResponse.attempt`. Exhausting this policy does not fall back to\n`ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry\npolicy, independently of `ActivityOptions.retry_policy`.\nTo change `RetryPolicy.non_retryable_error_types`, replace\n`async_handoff_options.retry_policy` as a whole in the update mask." - } - }, - "description": "Timeout and retry options for activity handoff and external completion. The completion phase\nbegins when the server durably accepts `RespondActivityTaskHandoff`.\n\nPresence, including an empty message, enables two-phase timeouts and retries. Absence preserves\nexisting timeout, retry, and attempt-counting behavior even when handoff is reported.\nEither `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout`\nmust be positive; otherwise, both phase timeouts below must be positive so neither phase can\nwait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout`\nis enforced only when explicitly positive. Only the current phase timeout is active.\n\nPositive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and\n`ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by\ntheir phase timeout and those positive bounds. The server stores and returns normalized values.\nIncreasing a bound does not restore a capped value unless that value is also updated." - }, "v1BackfillRequest": { "type": "object", "properties": { @@ -16797,6 +16775,28 @@ } } }, + "v1HandoffOptions": { + "type": "object", + "properties": { + "startToHandoffTimeout": { + "type": "string", + "description": "Maximum time from the current worker pickup until the server durably accepts handoff. Unset\nor zero disables this timeout. On timeout, the server retries according to\n`HandoffOptions.retry_policy`.\n" + }, + "handoffToCloseTimeout": { + "type": "string", + "description": "Maximum time from the server durably accepting handoff until the current activity attempt\ncloses. Unset or zero disables this timeout. On timeout, the server retries according to\n`ActivityOptions.retry_policy`.\n" + }, + "heartbeatTimeout": { + "type": "string", + "description": "Maximum time between recorded heartbeats before accepted handoff, initially measured from\nworker pickup. Unset or zero disables it; `ActivityOptions.heartbeat_timeout` is not inherited\nand applies only after handoff." + }, + "retryPolicy": { + "$ref": "#/definitions/v1RetryPolicy", + "description": "Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff.\nRetries increment `PollActivityTaskQueueResponse.handoff_attempt` without incrementing\n`PollActivityTaskQueueResponse.attempt`. Exhausting this policy does not fall back to\n`ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry\npolicy, independently of `ActivityOptions.retry_policy`.\nTo change `RetryPolicy.non_retryable_error_types`, replace\n`handoff_options.retry_policy` as a whole in the update mask." + } + }, + "description": "Timeout and retry options for activity handoff and external completion. The completion phase\nbegins when the server durably accepts `RespondActivityTaskHandoff`.\n\nPresence, including an empty message, enables two-phase timeouts and retries. Absence preserves\nexisting timeout, retry, and attempt-counting behavior even when handoff is reported.\nEither `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout`\nmust be positive; otherwise, both phase timeouts below must be positive so neither phase can\nwait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout`\nis enforced only when explicitly positive. Only the current phase timeout is active.\n\nPositive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and\n`ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by\ntheir phase timeout and those positive bounds. The server stores and returns normalized values.\nIncreasing a bound does not restore a capped value unless that value is also updated." + }, "v1Header": { "type": "object", "properties": { @@ -18541,10 +18541,10 @@ "PENDING_ACTIVITY_STATE_CANCEL_REQUESTED", "PENDING_ACTIVITY_STATE_PAUSED", "PENDING_ACTIVITY_STATE_PAUSE_REQUESTED", - "PENDING_ACTIVITY_STATE_AWAITING_COMPLETION" + "PENDING_ACTIVITY_STATE_HANDED_OFF" ], "default": "PENDING_ACTIVITY_STATE_UNSPECIFIED", - "description": " - PENDING_ACTIVITY_STATE_PAUSED: PAUSED means activity is paused on the server, and is not running in the worker\n - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED: PAUSE_REQUESTED means activity is currently running on the worker, but paused on the server\n - PENDING_ACTIVITY_STATE_AWAITING_COMPLETION: The server has recorded async handoff and is waiting for external completion." + "description": " - PENDING_ACTIVITY_STATE_PAUSED: PAUSED means activity is paused on the server, and is not running in the worker\n - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED: PAUSE_REQUESTED means activity is currently running on the worker, but paused on the server\n - PENDING_ACTIVITY_STATE_HANDED_OFF: HANDED_OFF means the server accepted handoff and is waiting for external completion." }, "v1PendingChildExecutionInfo": { "type": "object", @@ -18785,11 +18785,11 @@ }, "startToCloseTimeout": { "type": "string", - "description": "Configured start-to-close timeout for the activity attempt.\n" + "description": "Configured start-to-close timeout for the activity attempt.\nWith `handoff_options` set, an unset or zero value disables this timeout.\n" }, "heartbeatTimeout": { "type": "string", - "description": "Window within which the activity must report a heartbeat, or be timed out.\nWhen `PollActivityTaskQueueResponse.async_handoff_options` is present, workers use\n`AsyncHandoffOptions.heartbeat_timeout` before handoff." + "description": "Window within which the activity must report a heartbeat, or be timed out.\nWhen `PollActivityTaskQueueResponse.handoff_options` is present, workers use\n`HandoffOptions.heartbeat_timeout` before handoff." }, "retryPolicy": { "$ref": "#/definitions/v1RetryPolicy", @@ -18826,10 +18826,10 @@ "handoffAttempt": { "type": "integer", "format": "int32", - "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`PollActivityTaskQueueResponse.async_handoff_options` are configured at creation or added by update.\nIncrements on handoff retries and resets to 1 on an activity retry or applied reset.\nZero when options are absent." + "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`PollActivityTaskQueueResponse.handoff_options` are configured at creation or added by update.\nIncrements on handoff retries and resets to 1 on an activity retry or applied reset.\nZero when options are absent." }, - "asyncHandoffOptions": { - "$ref": "#/definitions/v1AsyncHandoffOptions", + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", "description": "Handoff options for this activity task." } } diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index aa7d13936..3fdac60a9 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -9843,7 +9843,7 @@ components: - PENDING_ACTIVITY_STATE_CANCEL_REQUESTED - PENDING_ACTIVITY_STATE_PAUSED - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED - - PENDING_ACTIVITY_STATE_AWAITING_COMPLETION + - PENDING_ACTIVITY_STATE_HANDED_OFF type: string description: More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING. format: enum @@ -10043,7 +10043,7 @@ components: type: integer description: |- Handoff attempt within the current activity attempt. Starts at 1 when - `ActivityExecutionInfo.async_handoff_options` are configured at creation or added by update. + `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. format: int32 @@ -10060,9 +10060,9 @@ components: 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. - asyncHandoffOptions: + handoffOptions: allOf: - - $ref: '#/components/schemas/AsyncHandoffOptions' + - $ref: '#/components/schemas/HandoffOptions' description: Server-normalized and defaulted handoff options, if configured. description: Information about a standalone activity. ActivityExecutionListInfo: @@ -10193,7 +10193,7 @@ components: description: |- 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, - unless `ActivityOptions.async_handoff_options` provides both phase timeouts. + unless `ActivityOptions.handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -10204,7 +10204,7 @@ components: 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. With `async_handoff_options` set, defaults to a positive + specified. With `handoff_options` set, defaults to a positive `schedule_to_close_timeout`, otherwise remains disabled. (-- api-linter: core::0140::prepositions=disabled @@ -10215,8 +10215,8 @@ components: description: |- 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, - unless `ActivityOptions.async_handoff_options` provides both phase timeouts. - When `ActivityOptions.async_handoff_options` is present, the start-to-close timeout runs from + 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. @@ -10227,17 +10227,17 @@ components: type: string description: |- Maximum permitted time between successful worker heartbeats. - When `ActivityOptions.async_handoff_options` is present, the activity heartbeat timeout + When `ActivityOptions.handoff_options` is present, the activity heartbeat timeout applies after handoff, starting at accepted handoff. - Before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. + Before handoff, use `HandoffOptions.heartbeat_timeout`. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' description: |- The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. - When `ActivityOptions.async_handoff_options` is present, this policy handles post-handoff failures + 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 - `AsyncHandoffOptions.retry_policy`. + `HandoffOptions.retry_policy`. priority: allOf: - $ref: '#/components/schemas/Priority' @@ -10251,9 +10251,9 @@ components: Time to wait before making the first activity task available for dispatch. This delay is not applied to retry attempts. 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. - asyncHandoffOptions: + handoffOptions: allOf: - - $ref: '#/components/schemas/AsyncHandoffOptions' + - $ref: '#/components/schemas/HandoffOptions' description: Two-phase timeout and retry settings. ActivityPropertiesModifiedExternallyEventAttributes: type: object @@ -10388,7 +10388,7 @@ components: description: |- 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, - unless `async_handoff_options` provides both phase timeouts. + unless `handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -10399,7 +10399,7 @@ components: 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. With `async_handoff_options` set, defaults to a positive + specified. With `handoff_options` set, defaults to a positive `schedule_to_close_timeout`, otherwise remains disabled. (-- api-linter: core::0140::prepositions=disabled @@ -10410,7 +10410,7 @@ components: description: |- 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, unless `async_handoff_options` provides both phase timeouts. With handoff + 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 @@ -10419,8 +10419,8 @@ components: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: |- - Maximum permitted time between successful worker heartbeats. With `async_handoff_options` - set, applies after handoff; before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. + Maximum permitted time between successful worker heartbeats. With `handoff_options` + set, applies after handoff; before handoff, use `HandoffOptions.heartbeat_timeout`. workflowTaskCompletedEventId: type: string description: The `WORKFLOW_TASK_COMPLETED` event which this command was reported with @@ -10431,7 +10431,7 @@ components: 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 under this policy, set retry_policy.maximum_attempts to 1. - With `async_handoff_options` set, see `ActivityOptions.retry_policy` for applicability. + With `handoff_options` set, see `ActivityOptions.retry_policy` for applicability. useWorkflowBuildId: type: boolean description: |- @@ -10444,9 +10444,9 @@ components: description: |- Priority metadata. If this message is not present, or any fields are not present, they inherit the values from the workflow. - asyncHandoffOptions: + handoffOptions: allOf: - - $ref: '#/components/schemas/AsyncHandoffOptions' + - $ref: '#/components/schemas/HandoffOptions' description: Handoff timeout and retry settings. ActivityTaskStartedEventAttributes: type: object @@ -10560,62 +10560,6 @@ components: - APPLICATION_ERROR_CATEGORY_BENIGN type: string format: enum - AsyncHandoffOptions: - type: object - properties: - startToHandoffTimeout: - pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ - type: string - description: |- - 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 - `AsyncHandoffOptions.retry_policy`. - - (-- api-linter: core::0140::prepositions=disabled - aip.dev/not-precedent: "to" identifies the endpoints of the timeout. --) - handoffToCloseTimeout: - pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ - type: string - description: |- - 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. --) - heartbeatTimeout: - pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ - type: string - description: |- - 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. - retryPolicy: - allOf: - - $ref: '#/components/schemas/RetryPolicy' - description: |- - 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 - `async_handoff_options.retry_policy` as a whole in the update mask. - description: |- - Timeout and retry options for activity handoff and external completion. The completion phase - begins when the server durably accepts `RespondActivityTaskHandoff`. - - 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. - Either `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` - must be positive; otherwise, both phase timeouts below must be positive so neither phase can - wait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout` - is enforced only when explicitly positive. Only the current phase timeout is active. - - Positive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and - `ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by - their phase timeout and those positive bounds. The server stores and returns normalized values. - Increasing a bound does not restore a capped value unless that value is also updated. BackfillRequest: type: object properties: @@ -13083,6 +13027,62 @@ components: description: The type of the serialized message. additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. + HandoffOptions: + type: object + properties: + startToHandoffTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. --) + handoffToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. --) + heartbeatTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + 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. + retryPolicy: + allOf: + - $ref: '#/components/schemas/RetryPolicy' + description: |- + 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. + description: |- + Timeout and retry options for activity handoff and external completion. The completion phase + begins when the server durably accepts `RespondActivityTaskHandoff`. + + 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. + Either `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` + must be positive; otherwise, both phase timeouts below must be positive so neither phase can + wait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout` + is enforced only when explicitly positive. Only the current phase timeout is active. + + Positive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and + `ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by + their phase timeout and those positive bounds. The server stores and returns normalized values. + Increasing a bound does not restore a capped value unless that value is also updated. Header: type: object properties: @@ -14716,7 +14716,7 @@ components: - PENDING_ACTIVITY_STATE_CANCEL_REQUESTED - PENDING_ACTIVITY_STATE_PAUSED - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED - - PENDING_ACTIVITY_STATE_AWAITING_COMPLETION + - PENDING_ACTIVITY_STATE_HANDED_OFF type: string format: enum heartbeatDetails: @@ -15070,6 +15070,7 @@ components: type: string description: |- Configured start-to-close timeout for the activity attempt. + With `handoff_options` set, an unset or zero value disables this timeout. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -15078,8 +15079,8 @@ components: type: string description: |- Window within which the activity must report a heartbeat, or be timed out. - When `PollActivityTaskQueueResponse.async_handoff_options` is present, workers use - `AsyncHandoffOptions.heartbeat_timeout` before handoff. + When `PollActivityTaskQueueResponse.handoff_options` is present, workers use + `HandoffOptions.heartbeat_timeout` before handoff. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' @@ -15129,13 +15130,13 @@ components: type: integer description: |- Handoff attempt within the current activity attempt. Starts at 1 when - `PollActivityTaskQueueResponse.async_handoff_options` are configured at creation or added by update. + `PollActivityTaskQueueResponse.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. format: int32 - asyncHandoffOptions: + handoffOptions: allOf: - - $ref: '#/components/schemas/AsyncHandoffOptions' + - $ref: '#/components/schemas/HandoffOptions' description: Handoff options for this activity task. PollNexusOperationExecutionResponse: type: object @@ -17575,7 +17576,7 @@ components: description: |- 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, - unless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. + unless `StartActivityExecutionRequest.handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -17595,7 +17596,7 @@ components: description: |- 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, - unless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. See + unless `StartActivityExecutionRequest.handoff_options` provides both phase timeouts. See `ActivityOptions.start_to_close_timeout`. (-- api-linter: core::0140::prepositions=disabled @@ -17606,7 +17607,7 @@ components: description: |- Maximum permitted time between successful worker heartbeats. See `ActivityOptions.heartbeat_timeout` for behavior when - `StartActivityExecutionRequest.async_handoff_options` is present. + `StartActivityExecutionRequest.handoff_options` is present. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' @@ -17687,9 +17688,9 @@ components: being dispatched through a task queue. If set to true, the caller is expected to have a worker available and capable of processing the task. The returned task will be marked as started. The server may ignore this request. - asyncHandoffOptions: + handoffOptions: allOf: - - $ref: '#/components/schemas/AsyncHandoffOptions' + - $ref: '#/components/schemas/HandoffOptions' description: Two-phase timeout and retry settings. StartActivityExecutionResponse: type: object diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index a0c24c8e2..a90363bb1 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -50,10 +50,10 @@ message ActivityExecutionOutcome { // `ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by // their phase timeout and those positive bounds. The server stores and returns normalized values. // Increasing a bound does not restore a capped value unless that value is also updated. -message AsyncHandoffOptions { +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 - // `AsyncHandoffOptions.retry_policy`. + // `HandoffOptions.retry_policy`. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" identifies the endpoints of the timeout. --) @@ -78,7 +78,7 @@ message AsyncHandoffOptions { // `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 - // `async_handoff_options.retry_policy` as a whole in the update mask. + // `handoff_options.retry_policy` as a whole in the update mask. temporal.api.common.v1.RetryPolicy retry_policy = 4; } @@ -87,7 +87,7 @@ message ActivityOptions { // 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, - // unless `ActivityOptions.async_handoff_options` provides both phase timeouts. + // unless `ActivityOptions.handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -95,7 +95,7 @@ message ActivityOptions { // 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. With `async_handoff_options` set, defaults to a positive + // specified. With `handoff_options` set, defaults to a positive // `schedule_to_close_timeout`, otherwise remains disabled. // // (-- api-linter: core::0140::prepositions=disabled @@ -103,8 +103,8 @@ message ActivityOptions { 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, - // unless `ActivityOptions.async_handoff_options` provides both phase timeouts. - // When `ActivityOptions.async_handoff_options` is present, the start-to-close timeout runs from + // 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. // @@ -112,14 +112,14 @@ message ActivityOptions { // 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.async_handoff_options` is present, the activity heartbeat timeout + // When `ActivityOptions.handoff_options` is present, the activity heartbeat timeout // applies after handoff, starting at accepted handoff. - // Before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. + // 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.async_handoff_options` is present, this policy handles post-handoff failures + // 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 - // `AsyncHandoffOptions.retry_policy`. + // `HandoffOptions.retry_policy`. temporal.api.common.v1.RetryPolicy retry_policy = 6; // Priority metadata. If this message is not present, or any fields are not @@ -132,7 +132,7 @@ message ActivityOptions { google.protobuf.Duration start_delay = 8; // Two-phase timeout and retry settings. - AsyncHandoffOptions async_handoff_options = 9; + HandoffOptions handoff_options = 9; } // Information about a standalone activity. @@ -283,7 +283,7 @@ message ActivityExecutionInfo { temporal.api.common.v1.ResolvedPrincipal last_worker_principal = 43; // Handoff attempt within the current activity attempt. Starts at 1 when - // `ActivityExecutionInfo.async_handoff_options` are configured at creation or added by update. + // `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; @@ -299,7 +299,7 @@ message ActivityExecutionInfo { bool awaiting_completion = 46; // Server-normalized and defaulted handoff options, if configured. - AsyncHandoffOptions async_handoff_options = 47; + HandoffOptions handoff_options = 47; } // Limited activity information returned in the list response. diff --git a/temporal/api/command/v1/message.proto b/temporal/api/command/v1/message.proto index 7759bc5aa..3aef5d479 100644 --- a/temporal/api/command/v1/message.proto +++ b/temporal/api/command/v1/message.proto @@ -32,7 +32,7 @@ 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, unless `async_handoff_options` provides both phase timeouts. Without handoff + // 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 @@ -43,7 +43,7 @@ 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. With `async_handoff_options` set, defaults to a positive + // 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/ // @@ -52,19 +52,19 @@ message ScheduleActivityTaskCommandAttributes { 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, - // unless `async_handoff_options` provides both phase timeouts. With handoff options set, + // 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. With `async_handoff_options` - // set, applies after handoff; before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. + // 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 under this policy, set retry_policy.maximum_attempts to 1. - // With `async_handoff_options` set, see `ActivityOptions.retry_policy` for applicability. + // 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. @@ -76,7 +76,7 @@ message ScheduleActivityTaskCommandAttributes { // present, they inherit the values from the workflow. temporal.api.common.v1.Priority priority = 14; // Handoff timeout and retry settings. - temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 15; + temporal.api.activity.v1.HandoffOptions handoff_options = 15; } message RequestCancelActivityTaskCommandAttributes { diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index d81098cf2..adc19311d 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -434,7 +434,7 @@ message ActivityTaskScheduledEventAttributes { 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, - // unless `async_handoff_options` provides both phase timeouts. + // unless `handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -442,7 +442,7 @@ message ActivityTaskScheduledEventAttributes { // 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. With `async_handoff_options` set, defaults to a positive + // specified. With `handoff_options` set, defaults to a positive // `schedule_to_close_timeout`, otherwise remains disabled. // // (-- api-linter: core::0140::prepositions=disabled @@ -450,21 +450,21 @@ message ActivityTaskScheduledEventAttributes { 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, unless `async_handoff_options` provides both phase timeouts. With handoff + // 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. With `async_handoff_options` - // set, applies after handoff; before handoff, use `AsyncHandoffOptions.heartbeat_timeout`. + // 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 under // this policy, set retry_policy.maximum_attempts to 1. - // With `async_handoff_options` set, see `ActivityOptions.retry_policy` for applicability. + // 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. @@ -474,7 +474,7 @@ message ActivityTaskScheduledEventAttributes { // present, they inherit the values from the workflow. temporal.api.common.v1.Priority priority = 14; // Handoff timeout and retry settings. - temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 15; + temporal.api.activity.v1.HandoffOptions handoff_options = 15; } message ActivityTaskStartedEventAttributes { diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c8a9b5090..9ede77f78 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -622,13 +622,14 @@ message PollActivityTaskQueueResponse { // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration schedule_to_close_timeout = 14; // Configured start-to-close timeout for the activity attempt. + // With `handoff_options` set, an unset or zero value disables this timeout. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration start_to_close_timeout = 15; // Window within which the activity must report a heartbeat, or be timed out. - // When `PollActivityTaskQueueResponse.async_handoff_options` is present, workers use - // `AsyncHandoffOptions.heartbeat_timeout` before handoff. + // When `PollActivityTaskQueueResponse.handoff_options` is present, workers use + // `HandoffOptions.heartbeat_timeout` before handoff. google.protobuf.Duration heartbeat_timeout = 16; // This is the retry policy the service uses which may be different from the one provided // (or not) during activity scheduling. The service can override the provided one if some @@ -660,13 +661,13 @@ message PollActivityTaskQueueResponse { temporal.api.nexus.v1.PropagatedSerializationContext propagated_nexus_serialization_context = 23; // Handoff attempt within the current activity attempt. Starts at 1 when - // `PollActivityTaskQueueResponse.async_handoff_options` are configured at creation or added by update. + // `PollActivityTaskQueueResponse.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 = 24; // Handoff options for this activity task. - temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 25; + temporal.api.activity.v1.HandoffOptions handoff_options = 25; } message RecordActivityTaskHeartbeatRequest { @@ -3311,7 +3312,7 @@ message StartActivityExecutionRequest { temporal.api.taskqueue.v1.TaskQueue task_queue = 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, - // unless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. + // unless `StartActivityExecutionRequest.handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -3325,7 +3326,7 @@ message StartActivityExecutionRequest { 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, - // unless `StartActivityExecutionRequest.async_handoff_options` provides both phase timeouts. See + // unless `StartActivityExecutionRequest.handoff_options` provides both phase timeouts. See // `ActivityOptions.start_to_close_timeout`. // // (-- api-linter: core::0140::prepositions=disabled @@ -3333,7 +3334,7 @@ message StartActivityExecutionRequest { google.protobuf.Duration start_to_close_timeout = 9; // Maximum permitted time between successful worker heartbeats. // See `ActivityOptions.heartbeat_timeout` for behavior when - // `StartActivityExecutionRequest.async_handoff_options` is present. + // `StartActivityExecutionRequest.handoff_options` is present. 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. @@ -3376,7 +3377,7 @@ message StartActivityExecutionRequest { bool request_eager_execution = 24; // Two-phase timeout and retry settings. - temporal.api.activity.v1.AsyncHandoffOptions async_handoff_options = 25; + temporal.api.activity.v1.HandoffOptions handoff_options = 25; } message StartActivityExecutionResponse { From 2f549bb3f4b95d2e8c3088776278f0e9d563af54 Mon Sep 17 00:00:00 2001 From: Fred Tzeng Date: Fri, 13 Nov 2026 12:12:04 -0800 Subject: [PATCH 6/7] Rename PENDING_ACTIVITY_STATE_HANDED_OFF --- temporal/api/enums/v1/workflow.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 390dd7931..af53dc9a1 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -91,8 +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; - // The server has recorded async handoff and is waiting for external completion. - PENDING_ACTIVITY_STATE_AWAITING_COMPLETION = 6; + // HANDED_OFF means the server accepted handoff and is waiting for external completion. + PENDING_ACTIVITY_STATE_HANDED_OFF = 6; } enum PendingWorkflowTaskState { From 31b6726b3b7c545d831bafabec0c4841a1373cbb Mon Sep 17 00:00:00 2001 From: Fred Tzeng Date: Wed, 18 Nov 2026 16:29:22 -0800 Subject: [PATCH 7/7] Address comments --- openapi/openapiv2.json | 18 ++++---- openapi/openapiv3.yaml | 41 +++++++++++-------- temporal/api/activity/v1/message.proto | 29 +++++++------ temporal/api/namespace/v1/message.proto | 4 +- temporal/api/workflow/v1/message.proto | 4 +- .../workflowservice/v1/request_response.proto | 4 +- 6 files changed, 55 insertions(+), 45 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 1e3f38aa3..59fbeb26d 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -14094,12 +14094,12 @@ "format": "int32", "description": "Handoff attempt within the current activity attempt. Starts at 1 when\n`ActivityExecutionInfo.handoff_options` are configured at creation or added by update.\nIncrements on handoff retries and resets to 1 on an activity retry or applied reset.\nZero when options are absent." }, - "asyncHandoffTime": { + "handoffTime": { "type": "string", "format": "date-time", "description": "Most recent durably recorded handoff time. Retained through retry backoff, waiting for the\nnext worker pickup, and terminal closure. Cleared when a reset is applied or the next delivery\nstarts on a worker." }, - "awaitingCompletion": { + "handedOff": { "type": "boolean", "description": "True while the current delivery awaits external completion, independent of\n`ActivityExecutionInfo.run_state`. Cleared when the delivery ends or is reset;\npending pause, cancel, or reset requests do not clear it." }, @@ -16795,7 +16795,7 @@ "description": "Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff.\nRetries increment `PollActivityTaskQueueResponse.handoff_attempt` without incrementing\n`PollActivityTaskQueueResponse.attempt`. Exhausting this policy does not fall back to\n`ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry\npolicy, independently of `ActivityOptions.retry_policy`.\nTo change `RetryPolicy.non_retryable_error_types`, replace\n`handoff_options.retry_policy` as a whole in the update mask." } }, - "description": "Timeout and retry options for activity handoff and external completion. The completion phase\nbegins when the server durably accepts `RespondActivityTaskHandoff`.\n\nPresence, including an empty message, enables two-phase timeouts and retries. Absence preserves\nexisting timeout, retry, and attempt-counting behavior even when handoff is reported.\nEither `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout`\nmust be positive; otherwise, both phase timeouts below must be positive so neither phase can\nwait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout`\nis enforced only when explicitly positive. Only the current phase timeout is active.\n\nPositive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and\n`ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by\ntheir phase timeout and those positive bounds. The server stores and returns normalized values.\nIncreasing a bound does not restore a capped value unless that value is also updated." + "description": "An activity attempt has two phases: before handoff and waiting for external completion.\nHandoff occurs when the server durably accepts `RespondActivityTaskHandoff`.\n\nThis message sets the timeouts before handoff and while waiting for external completion.\nIts heartbeat timeout and retry policy apply only before handoff. After handoff, use the\nheartbeat timeout and retry policy in `ActivityOptions`.\n`ActivityOptions.start_to_close_timeout` spans both phases. If it expires, retries use\n`ActivityOptions.retry_policy`.\n\nPresence, including an empty message, enables two-phase timeouts and retries. Absence preserves\nexisting timeout, retry, and attempt-counting behavior even when handoff is reported.\nA positive `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout`\nis required unless both phase timeouts are positive. An unset or zero start-to-close timeout\nremains disabled.\n\nPhase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and\n`ActivityOptions.schedule_to_close_timeout` values. Heartbeat timeouts are also capped by their\nphase timeout. The server stores and returns the capped values. Increasing a bound does not\nrestore a capped value unless that value is also updated." }, "v1Header": { "type": "object", @@ -17663,11 +17663,11 @@ "type": "boolean", "description": "True if the namespace supports standalone activity operator commands." }, - "standaloneActivityAsyncHandoff": { + "standaloneActivityHandoff": { "type": "boolean", "description": "True if workers can report standalone activity handoff through `RespondActivityTaskHandoff`." }, - "workflowActivityAsyncHandoff": { + "workflowActivityHandoff": { "type": "boolean", "description": "True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`." } @@ -18521,12 +18521,12 @@ "format": "int32", "description": "Handoff attempt within the activity attempt. Starts at 1 when handoff options are\nconfigured, increments on handoff retries, and resets to 1 on an activity retry or applied\nreset. Zero when handoff options are absent." }, - "asyncHandoffTime": { + "handoffTime": { "type": "string", "format": "date-time", "description": "Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset." }, - "awaitingCompletion": { + "handedOff": { "type": "boolean", "description": "True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it." } @@ -18767,12 +18767,12 @@ "currentAttemptScheduledTime": { "type": "string", "format": "date-time", - "title": "When was this task attempt scheduled" + "description": "Time this activity attempt was first scheduled. Preserved across handoff retries." }, "startedTime": { "type": "string", "format": "date-time", - "description": "Time this activity task started." + "description": "Time this activity attempt first started. Preserved across handoff retries." }, "attempt": { "type": "integer", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 3fdac60a9..8023730ce 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10047,14 +10047,14 @@ components: Increments on handoff retries and resets to 1 on an activity retry or applied reset. Zero when options are absent. format: int32 - asyncHandoffTime: + handoffTime: type: string description: |- 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. format: date-time - awaitingCompletion: + handedOff: type: boolean description: |- True while the current delivery awaits external completion, independent of @@ -13069,20 +13069,25 @@ components: To change `RetryPolicy.non_retryable_error_types`, replace `handoff_options.retry_policy` as a whole in the update mask. description: |- - Timeout and retry options for activity handoff and external completion. The completion phase - begins when the server durably accepts `RespondActivityTaskHandoff`. + 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. - Either `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` - must be positive; otherwise, both phase timeouts below must be positive so neither phase can - wait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout` - is enforced only when explicitly positive. Only the current phase timeout is active. + 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. - Positive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and - `ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by - their phase timeout and those positive bounds. The server stores and returns normalized values. - Increasing a bound does not restore a capped value unless that value is also updated. + 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. Header: type: object properties: @@ -13900,10 +13905,10 @@ components: standaloneActivityOperatorCommands: type: boolean description: True if the namespace supports standalone activity operator commands. - standaloneActivityAsyncHandoff: + standaloneActivityHandoff: type: boolean description: True if workers can report standalone activity handoff through `RespondActivityTaskHandoff`. - workflowActivityAsyncHandoff: + workflowActivityHandoff: type: boolean description: True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`. description: Namespace capability details. Should contain what features are enabled in a namespace. @@ -14814,11 +14819,11 @@ components: configured, increments on handoff retries, and resets to 1 on an activity retry or applied reset. Zero when handoff options are absent. format: int32 - asyncHandoffTime: + handoffTime: type: string description: Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset. format: date-time - awaitingCompletion: + handedOff: type: boolean description: True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. PendingActivityInfo_PauseInfo: @@ -15045,11 +15050,11 @@ components: format: date-time currentAttemptScheduledTime: type: string - description: When was this task attempt scheduled + description: Time this activity attempt was first scheduled. Preserved across handoff retries. format: date-time startedTime: type: string - description: Time this activity task started. + description: Time this activity attempt first started. Preserved across handoff retries. format: date-time attempt: type: integer diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index a90363bb1..97872ba6d 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -36,20 +36,25 @@ message ActivityExecutionOutcome { temporal.api.enums.v1.RetryState retry_state = 3; } -// Timeout and retry options for activity handoff and external completion. The completion phase -// begins when the server durably accepts `RespondActivityTaskHandoff`. +// 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. -// Either `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` -// must be positive; otherwise, both phase timeouts below must be positive so neither phase can -// wait indefinitely. The earliest applicable deadline wins. `ActivityOptions.start_to_close_timeout` -// is enforced only when explicitly positive. Only the current phase timeout is active. +// 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. // -// Positive phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and -// `ActivityOptions.schedule_to_close_timeout` bounds. Positive heartbeat timeouts are capped by -// their phase timeout and those positive bounds. The server stores and returns normalized values. -// Increasing a bound does not restore a capped value unless that value is also updated. +// 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 @@ -291,12 +296,12 @@ message ActivityExecutionInfo { // 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 async_handoff_time = 45; + 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 awaiting_completion = 46; + bool handed_off = 46; // Server-normalized and defaulted handoff options, if configured. HandoffOptions handoff_options = 47; diff --git a/temporal/api/namespace/v1/message.proto b/temporal/api/namespace/v1/message.proto index a276b70c7..e7fd1388c 100644 --- a/temporal/api/namespace/v1/message.proto +++ b/temporal/api/namespace/v1/message.proto @@ -67,9 +67,9 @@ message NamespaceInfo { // 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_async_handoff = 18; + bool standalone_activity_handoff = 18; // True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`. - bool workflow_activity_async_handoff = 19; + bool workflow_activity_handoff = 19; } // Namespace configured limits diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index c9fb9a9aa..4b8f49f37 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -388,10 +388,10 @@ message PendingActivityInfo { int32 handoff_attempt = 26; // Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset. - google.protobuf.Timestamp async_handoff_time = 27; + google.protobuf.Timestamp handoff_time = 27; // True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. - bool awaiting_completion = 28; + bool handed_off = 28; } message PendingChildExecutionInfo { diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 9ede77f78..66f56ecc7 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -609,9 +609,9 @@ message PollActivityTaskQueueResponse { temporal.api.common.v1.Payloads heartbeat_details = 9; // When was this task first scheduled google.protobuf.Timestamp scheduled_time = 10; - // When was this task attempt scheduled + // Time this activity attempt was first scheduled. Preserved across handoff retries. google.protobuf.Timestamp current_attempt_scheduled_time = 11; - // Time this activity task started. + // Time this activity attempt first started. Preserved across handoff retries. google.protobuf.Timestamp started_time = 12; // Starting at 1, the number of attempts to perform this activity // Handoff retries increment `PollActivityTaskQueueResponse.handoff_attempt` instead.