diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 9a389f44e..59fbeb26d 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. Contains \"workflow:{workflow_id}\" for workflow activities or\n\"activity:{activity_id}\" for standalone activities." + }, + "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.handoff_options` provides both phase timeouts.\n" }, "scheduleToStartTimeout": { "type": "string", @@ -12592,15 +12697,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 `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." + "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", - "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", @@ -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." + }, + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", + "description": "Two-phase timeout and retry settings." } } }, @@ -13833,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", @@ -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.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." + }, + "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." + }, + "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." + }, + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", + "description": "Server-normalized and defaulted handoff options, if configured." } }, "description": "Information about a standalone activity." @@ -14129,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.\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.\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.\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." + "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`." + "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", @@ -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." + }, + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", + "description": "Two-phase timeout and retry settings." } } }, @@ -14311,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 `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 `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 `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 `handoff_options`\nset, applies after handoff; before handoff, use `HandoffOptions.heartbeat_timeout`." }, "workflowTaskCompletedEventId": { "type": "string", @@ -14332,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 `handoff_options` set, see `ActivityOptions.retry_policy` for applicability." }, "useWorkflowBuildId": { "type": "boolean", @@ -14341,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." + }, + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", + "description": "Handoff timeout and retry settings." } } }, @@ -16640,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": "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", "properties": { @@ -17505,6 +17662,14 @@ "standaloneActivityOperatorCommands": { "type": "boolean", "description": "True if the namespace supports standalone activity operator commands." + }, + "standaloneActivityHandoff": { + "type": "boolean", + "description": "True if workers can report standalone activity handoff through `RespondActivityTaskHandoff`." + }, + "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." @@ -18350,6 +18515,20 @@ "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." + }, + "handoffTime": { + "type": "string", + "format": "date-time", + "description": "Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset." + }, + "handedOff": { + "type": "boolean", + "description": "True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it." } } }, @@ -18361,10 +18540,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_HANDED_OFF" ], "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_HANDED_OFF: HANDED_OFF means the server accepted handoff and is waiting for external completion." }, "v1PendingChildExecutionInfo": { "type": "object", @@ -18587,17 +18767,17 @@ "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", - "title": "When was this task started (this attempt)" + "description": "Time this activity attempt first started. Preserved across handoff retries." }, "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,15 +18785,15 @@ }, "startToCloseTimeout": { "type": "string", - "title": "Current attempt start -> final result reported timeout" + "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." + "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", - "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", @@ -18642,6 +18822,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.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." + }, + "handoffOptions": { + "$ref": "#/definitions/v1HandoffOptions", + "description": "Handoff options for this activity task." } } }, @@ -19457,6 +19646,9 @@ } } }, + "v1RespondActivityTaskHandoffResponse": { + "type": "object" + }, "v1RetryPolicy": { "type": "object", "properties": { @@ -20776,9 +20968,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..8023730ce 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_HANDED_OFF type: string description: More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING. format: enum @@ -9799,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' @@ -9816,11 +9901,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 +10039,31 @@ 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.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 + 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 + handedOff: + 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. + handoffOptions: + allOf: + - $ref: '#/components/schemas/HandoffOptions' + description: Server-normalized and defaulted handoff options, if configured. description: Information about a standalone activity. ActivityExecutionListInfo: type: object @@ -10080,7 +10192,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.handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -10091,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 `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. --) @@ -10100,19 +10214,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.handoff_options` provides both phase timeouts. + When `ActivityOptions.handoff_options` is present, the start-to-close timeout runs from + the first worker pickup of the activity attempt across both phases, handoff retries, backoff, and + queue waits. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) 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.handoff_options` is present, the activity heartbeat timeout + applies after handoff, starting at accepted handoff. + 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`. + description: |- + The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + When `ActivityOptions.handoff_options` is present, this policy handles post-handoff failures + and timeouts, plus start-to-close timeouts in either phase. Other pre-handoff failures use + `HandoffOptions.retry_policy`. priority: allOf: - $ref: '#/components/schemas/Priority' @@ -10126,6 +10251,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. + handoffOptions: + allOf: + - $ref: '#/components/schemas/HandoffOptions' + description: Two-phase timeout and retry settings. ActivityPropertiesModifiedExternallyEventAttributes: type: object properties: @@ -10258,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 `handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -10269,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 `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. --) @@ -10279,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 `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 `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 @@ -10295,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 `handoff_options` set, see `ActivityOptions.retry_policy` for applicability. useWorkflowBuildId: type: boolean description: |- @@ -10309,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. + handoffOptions: + allOf: + - $ref: '#/components/schemas/HandoffOptions' + description: Handoff timeout and retry settings. ActivityTaskStartedEventAttributes: type: object properties: @@ -12888,6 +13027,67 @@ 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: |- + An activity attempt has two phases: before handoff and waiting for external completion. + Handoff occurs when the server durably accepts `RespondActivityTaskHandoff`. + + This message sets the timeouts before handoff and while waiting for external completion. + Its heartbeat timeout and retry policy apply only before handoff. After handoff, use the + heartbeat timeout and retry policy in `ActivityOptions`. + `ActivityOptions.start_to_close_timeout` spans both phases. If it expires, retries use + `ActivityOptions.retry_policy`. + + Presence, including an empty message, enables two-phase timeouts and retries. Absence preserves + existing timeout, retry, and attempt-counting behavior even when handoff is reported. + A positive `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` + is required unless both phase timeouts are positive. An unset or zero start-to-close timeout + remains disabled. + + Phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and + `ActivityOptions.schedule_to_close_timeout` values. Heartbeat timeouts are also capped by their + phase timeout. The server stores and returns the capped values. Increasing a bound does not + restore a capped value unless that value is also updated. Header: type: object properties: @@ -13705,6 +13905,12 @@ components: standaloneActivityOperatorCommands: type: boolean description: True if the namespace supports standalone activity operator commands. + standaloneActivityHandoff: + type: boolean + description: True if workers can report standalone activity handoff through `RespondActivityTaskHandoff`. + 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. NamespaceInfo_Limits: type: object @@ -14515,6 +14721,7 @@ components: - PENDING_ACTIVITY_STATE_CANCEL_REQUESTED - PENDING_ACTIVITY_STATE_PAUSED - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED + - PENDING_ACTIVITY_STATE_HANDED_OFF type: string format: enum heartbeatDetails: @@ -14605,6 +14812,20 @@ 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 + handoffTime: + type: string + description: Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset. + format: date-time + handedOff: + type: boolean + description: True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. PendingActivityInfo_PauseInfo: type: object properties: @@ -14829,15 +15050,17 @@ 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: When was this task started (this attempt) + description: Time this activity attempt first started. Preserved across handoff retries. 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 +15074,18 @@ 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. + 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. --) 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.handoff_options` is present, workers use + `HandoffOptions.heartbeat_timeout` before handoff. retryPolicy: allOf: - $ref: '#/components/schemas/RetryPolicy' @@ -14866,6 +15093,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' @@ -14903,6 +15131,18 @@ 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.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 + handoffOptions: + allOf: + - $ref: '#/components/schemas/HandoffOptions' + description: Handoff options for this activity task. PollNexusOperationExecutionResponse: type: object properties: @@ -16322,6 +16562,34 @@ 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. Contains "workflow:{workflow_id}" for workflow activities or + "activity:{activity_id}" for standalone activities. + 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 +17580,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.handoff_options` provides both phase timeouts. (-- api-linter: core::0140::prepositions=disabled aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -17331,19 +17600,25 @@ 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.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.handoff_options` is present. 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' @@ -17418,6 +17693,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. + handoffOptions: + allOf: + - $ref: '#/components/schemas/HandoffOptions' + description: Two-phase timeout and retry settings. StartActivityExecutionResponse: type: object properties: @@ -18536,6 +18815,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 +22024,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..97872ba6d 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -36,11 +36,63 @@ message ActivityExecutionOutcome { temporal.api.enums.v1.RetryState retry_state = 3; } +// An activity attempt has two phases: before handoff and waiting for external completion. +// Handoff occurs when the server durably accepts `RespondActivityTaskHandoff`. +// +// This message sets the timeouts before handoff and while waiting for external completion. +// Its heartbeat timeout and retry policy apply only before handoff. After handoff, use the +// heartbeat timeout and retry policy in `ActivityOptions`. +// `ActivityOptions.start_to_close_timeout` spans both phases. If it expires, retries use +// `ActivityOptions.retry_policy`. +// +// Presence, including an empty message, enables two-phase timeouts and retries. Absence preserves +// existing timeout, retry, and attempt-counting behavior even when handoff is reported. +// A positive `ActivityOptions.start_to_close_timeout` or `ActivityOptions.schedule_to_close_timeout` +// is required unless both phase timeouts are positive. An unset or zero start-to-close timeout +// remains disabled. +// +// Phase timeouts are capped by positive `ActivityOptions.start_to_close_timeout` and +// `ActivityOptions.schedule_to_close_timeout` values. Heartbeat timeouts are also capped by their +// phase timeout. The server stores and returns the capped values. Increasing a bound does not +// restore a capped value unless that value is also updated. +message HandoffOptions { + // Maximum time from the current worker pickup until the server durably accepts handoff. Unset + // or zero disables this timeout. On timeout, the server retries according to + // `HandoffOptions.retry_policy`. + // + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" identifies the endpoints of the timeout. --) + google.protobuf.Duration start_to_handoff_timeout = 1; + + // Maximum time from the server durably accepting handoff until the current activity attempt + // closes. Unset or zero disables this timeout. On timeout, the server retries according to + // `ActivityOptions.retry_policy`. + // + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" identifies the endpoints of the timeout. --) + google.protobuf.Duration handoff_to_close_timeout = 2; + + // Maximum time between recorded heartbeats before accepted handoff, initially measured from + // worker pickup. Unset or zero disables it; `ActivityOptions.heartbeat_timeout` is not inherited + // and applies only after handoff. + google.protobuf.Duration heartbeat_timeout = 3; + + // Retry policy for failures and heartbeat or start-to-handoff timeouts before accepted handoff. + // Retries increment `PollActivityTaskQueueResponse.handoff_attempt` without incrementing + // `PollActivityTaskQueueResponse.attempt`. Exhausting this policy does not fall back to + // `ActivityOptions.retry_policy`. If omitted, uses the namespace's default activity retry + // policy, independently of `ActivityOptions.retry_policy`. + // To change `RetryPolicy.non_retryable_error_types`, replace + // `handoff_options.retry_policy` as a whole in the update mask. + temporal.api.common.v1.RetryPolicy retry_policy = 4; +} + message ActivityOptions { temporal.api.taskqueue.v1.TaskQueue task_queue = 1; // Indicates how long the caller is willing to wait for an activity completion. Limits how long - // retries will be attempted. Either this or `start_to_close_timeout` must be specified. + // retries will be attempted. Either this or `start_to_close_timeout` must be specified, + // unless `ActivityOptions.handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -48,21 +100,31 @@ 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 `handoff_options` set, defaults to a positive + // `schedule_to_close_timeout`, otherwise remains disabled. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration schedule_to_start_timeout = 3; // Maximum time an activity is allowed to execute after being picked up by a worker. This - // timeout is always retryable. Either this or `schedule_to_close_timeout` must be - // specified. + // timeout is always retryable. Either this or `schedule_to_close_timeout` must be specified, + // unless `ActivityOptions.handoff_options` provides both phase timeouts. + // When `ActivityOptions.handoff_options` is present, the start-to-close timeout runs from + // the first worker pickup of the activity attempt across both phases, handoff retries, backoff, and + // queue waits. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration start_to_close_timeout = 4; // Maximum permitted time between successful worker heartbeats. + // When `ActivityOptions.handoff_options` is present, the activity heartbeat timeout + // applies after handoff, starting at accepted handoff. + // Before handoff, use `HandoffOptions.heartbeat_timeout`. google.protobuf.Duration heartbeat_timeout = 5; // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + // When `ActivityOptions.handoff_options` is present, this policy handles post-handoff failures + // and timeouts, plus start-to-close timeouts in either phase. Other pre-handoff failures use + // `HandoffOptions.retry_policy`. temporal.api.common.v1.RetryPolicy retry_policy = 6; // Priority metadata. If this message is not present, or any fields are not @@ -73,6 +135,9 @@ message ActivityOptions { // When updated, the time is added to the original `schedule_time`, not to the current time. // If the resulting time is in the past, the task is made available for dispatch immediately. google.protobuf.Duration start_delay = 8; + + // Two-phase timeout and retry settings. + HandoffOptions handoff_options = 9; } // Information about a standalone activity. @@ -111,9 +176,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. @@ -121,9 +188,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 +286,25 @@ message ActivityExecutionInfo { // Authenticated principal of the worker that most recently interacted with this activity execution. temporal.api.common.v1.ResolvedPrincipal last_worker_principal = 43; + + // Handoff attempt within the current activity attempt. Starts at 1 when + // `ActivityExecutionInfo.handoff_options` are configured at creation or added by update. + // Increments on handoff retries and resets to 1 on an activity retry or applied reset. + // Zero when options are absent. + int32 handoff_attempt = 44; + + // Most recent durably recorded handoff time. Retained through retry backoff, waiting for the + // next worker pickup, and terminal closure. Cleared when a reset is applied or the next delivery + // starts on a worker. + google.protobuf.Timestamp handoff_time = 45; + + // True while the current delivery awaits external completion, independent of + // `ActivityExecutionInfo.run_state`. Cleared when the delivery ends or is reset; + // pending pause, cancel, or reset requests do not clear it. + bool handed_off = 46; + + // Server-normalized and defaulted handoff options, if configured. + HandoffOptions handoff_options = 47; } // Limited activity information returned in the list response. diff --git a/temporal/api/command/v1/message.proto b/temporal/api/command/v1/message.proto index ee839115b..3aef5d479 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 `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 `handoff_options` set, defaults to a positive + // `schedule_to_close_timeout`, otherwise remains disabled. More info: // https://docs.temporal.io/docs/content/what-is-a-schedule-to-start-timeout/ // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration schedule_to_start_timeout = 8; // Maximum time an activity is allowed to execute after being picked up by a worker. This - // timeout is always retryable. Either this or `schedule_to_close_timeout` must be specified. + // timeout is always retryable. Either this or `schedule_to_close_timeout` must be specified, + // unless `handoff_options` provides both phase timeouts. With handoff options set, + // see `ActivityOptions.start_to_close_timeout` for timing. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration start_to_close_timeout = 9; - // Maximum permitted time between successful worker heartbeats. + // Maximum permitted time between successful worker heartbeats. With `handoff_options` + // set, applies after handoff; before handoff, use `HandoffOptions.heartbeat_timeout`. google.protobuf.Duration heartbeat_timeout = 10; // Activities are provided by a default retry policy which is controlled through the service's // dynamic configuration. Retries will be attempted until `schedule_to_close_timeout` has - // elapsed. To disable retries set retry_policy.maximum_attempts to 1. + // elapsed. To disable retries under this policy, set retry_policy.maximum_attempts to 1. + // With `handoff_options` set, see `ActivityOptions.retry_policy` for applicability. temporal.api.common.v1.RetryPolicy retry_policy = 11; // Request to start the activity directly bypassing matching service and worker polling // The slot for executing the activity should be reserved when setting this field to true. @@ -68,6 +75,8 @@ message ScheduleActivityTaskCommandAttributes { // Priority metadata. If this message is not present, or any fields are not // present, they inherit the values from the workflow. temporal.api.common.v1.Priority priority = 14; + // Handoff timeout and retry settings. + temporal.api.activity.v1.HandoffOptions handoff_options = 15; } message RequestCancelActivityTaskCommandAttributes { diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index a9ac3fc33..af53dc9a1 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; + // HANDED_OFF means the server accepted handoff and is waiting for external completion. + PENDING_ACTIVITY_STATE_HANDED_OFF = 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/history/v1/message.proto b/temporal/api/history/v1/message.proto index aeeb334f2..adc19311d 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 `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 `handoff_options` set, defaults to a positive + // `schedule_to_close_timeout`, otherwise remains disabled. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration schedule_to_start_timeout = 8; // Maximum time an activity is allowed to execute after being picked up by a worker. This // timeout is always retryable. Either this or `schedule_to_close_timeout` must be - // specified. + // specified, unless `handoff_options` provides both phase timeouts. With handoff + // options set, see `ActivityOptions.start_to_close_timeout` for timing. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) google.protobuf.Duration start_to_close_timeout = 9; - // Maximum permitted time between successful worker heartbeats. + // Maximum permitted time between successful worker heartbeats. With `handoff_options` + // set, applies after handoff; before handoff, use `HandoffOptions.heartbeat_timeout`. google.protobuf.Duration heartbeat_timeout = 10; // The `WORKFLOW_TASK_COMPLETED` event which this command was reported with int64 workflow_task_completed_event_id = 11; // Activities are assigned a default retry policy controlled by the service's dynamic - // configuration. Retries will happen up to `schedule_to_close_timeout`. To disable retries set - // retry_policy.maximum_attempts to 1. + // configuration. Retries will happen up to `schedule_to_close_timeout`. To disable retries under + // this policy, set retry_policy.maximum_attempts to 1. + // With `handoff_options` set, see `ActivityOptions.retry_policy` for applicability. temporal.api.common.v1.RetryPolicy retry_policy = 12; // If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise, // Assignment rules of the activity's Task Queue will be used to determine the Build ID. @@ -467,6 +473,8 @@ message ActivityTaskScheduledEventAttributes { // Priority metadata. If this message is not present, or any fields are not // present, they inherit the values from the workflow. temporal.api.common.v1.Priority priority = 14; + // Handoff timeout and retry settings. + temporal.api.activity.v1.HandoffOptions handoff_options = 15; } message ActivityTaskStartedEventAttributes { diff --git a/temporal/api/namespace/v1/message.proto b/temporal/api/namespace/v1/message.proto index a80566458..e7fd1388c 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_handoff = 18; + // True if workers can report workflow activity handoff through `RespondActivityTaskHandoff`. + 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 86224a4b1..4b8f49f37 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -381,6 +381,17 @@ message PendingActivityInfo { // Current activity options. May be different from the one used to start the activity. temporal.api.activity.v1.ActivityOptions activity_options = 24; + + // Handoff attempt within the activity attempt. Starts at 1 when handoff options are + // configured, increments on handoff retries, and resets to 1 on an activity retry or applied + // reset. Zero when handoff options are absent. + int32 handoff_attempt = 26; + + // Most recent durably accepted handoff time. Cleared at the next worker pickup or applied reset. + google.protobuf.Timestamp handoff_time = 27; + + // True while waiting for external completion. Pending pause, cancel, or reset requests do not clear it. + bool handed_off = 28; } message PendingChildExecutionInfo { diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 859bbcdc9..66f56ecc7 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -609,27 +609,32 @@ 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; - // When was this task started (this attempt) + // 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. 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. + // 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.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 // 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; @@ -654,6 +659,15 @@ 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.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.HandoffOptions handoff_options = 25; } message RecordActivityTaskHeartbeatRequest { @@ -712,6 +726,25 @@ 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. 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. + 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 +3311,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.handoff_options` provides both phase timeouts. // // (-- api-linter: core::0140::prepositions=disabled // aip.dev/not-precedent: "to" is used to indicate interval. --) @@ -3291,15 +3325,19 @@ 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.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.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. @@ -3337,6 +3375,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.HandoffOptions 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. //