From f39d34aa41932b6f0e6c88883c0846828b0c3c3c Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Mon, 20 Jul 2026 16:31:55 -0700 Subject: [PATCH 1/3] API surface area for worker callbacks --- openapi/openapiv2.json | 65 ++++++++++++++----- openapi/openapiv3.yaml | 43 ++++++++++++ temporal/api/common/v1/message.proto | 31 +++++++++ .../v1/request_response.proto | 57 ++++++++++++++++ .../workflowservice/v1/request_response.proto | 3 + 5 files changed, 184 insertions(+), 15 deletions(-) create mode 100644 temporal/api/notificationservice/v1/request_response.proto diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3eeda5de9..ec3482868 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -10834,20 +10834,6 @@ }, "description": "Target an external server by URL.\nAt a later point, this will support providing credentials, in the meantime, an http.RoundTripper can be injected\ninto the server to modify the request." }, - "EndpointTargetWorker": { - "type": "object", - "properties": { - "namespace": { - "type": "string", - "description": "Namespace to route requests to." - }, - "taskQueue": { - "type": "string", - "description": "Nexus task queue to route requests to." - } - }, - "description": "Target a worker polling on a Nexus task queue in a specific namespace." - }, "EventGroupMarkerInboundEvent": { "type": "object", "properties": { @@ -12469,6 +12455,14 @@ "userMetadata": { "$ref": "#/definitions/v1UserMetadata", "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation." + }, + "completionCallbacks": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Callback" + }, + "description": "Completion callbacks to be invoked once the Nexus operation reaches a terminal state." } } }, @@ -14406,6 +14400,9 @@ "internal": { "$ref": "#/definitions/CallbackInternal" }, + "worker": { + "$ref": "#/definitions/v1CallbackWorker" + }, "links": { "type": "array", "items": { @@ -14431,6 +14428,30 @@ "default": "CALLBACK_STATE_UNSPECIFIED", "description": "State of a callback.\n\n - CALLBACK_STATE_UNSPECIFIED: Default value, unspecified state.\n - CALLBACK_STATE_STANDBY: Callback is standing by, waiting to be triggered.\n - CALLBACK_STATE_SCHEDULED: Callback is in the queue waiting to be executed or is currently executing.\n - CALLBACK_STATE_BACKING_OFF: Callback has failed with a retryable error and is backing off before the next attempt.\n - CALLBACK_STATE_FAILED: Callback has failed.\n - CALLBACK_STATE_SUCCEEDED: Callback has succeeded.\n - CALLBACK_STATE_BLOCKED: Callback is blocked (eg: by circuit breaker)." }, + "v1CallbackWorker": { + "type": "object", + "properties": { + "taskqueueName": { + "type": "string", + "description": "Nexus task queue the Temporal worker is listening on.\n\nNOTE: This is not a temporal.api.taskqueue.v1.TaskQueue to avoid a circular dependency." + }, + "service": { + "type": "string", + "description": "Target Nexus service, e.g. \"temporal.api.notificationservice.v1.NotificationService\"." + }, + "operation": { + "type": "string", + "description": "Target operation, e.g. \"OnComplete\"." + }, + "sourceContext": { + "$ref": "#/definitions/v1Payload", + "description": "There is a relatively small maximum size the source context can be, e.g. 32KiB.", + "title": "Arbitrary user-supplied data from the source operation's callsite. (As applicable, not all operations\nsupport attaching context data.)" + } + }, + "description": "The targeted Nexus service must be registered within the same namespace as the source operation\nthe callback is attached to. (While Nexus allows for cross-namespace operations, worker callbacks\nare purely \"caller-side\".)\n\nWorker callbacks are only supported for certain types of operations, e.g. standalone Nexus operations.\nAttempting to attach a Worker callback for an unsupported operation will result in an INVALID_ARGUMENT\nerror from the server.", + "title": "Worker callbacks are requests to invoke a specific shape of Nexus operation on a Temporal worker.\nThe specified Nexus operation must have the following:\n- Input: temporal.api.notificationservice.v1.OnCompleteRequest\n- Output: temporal.api.notificationservice.v1.OnCompleteResponse" + }, "v1CancelExternalWorkflowExecutionFailedCause": { "type": "string", "enum": [ @@ -15591,7 +15612,7 @@ "type": "object", "properties": { "worker": { - "$ref": "#/definitions/EndpointTargetWorker" + "$ref": "#/definitions/v1EndpointTargetWorker" }, "external": { "$ref": "#/definitions/EndpointTargetExternal" @@ -15599,6 +15620,20 @@ }, "description": "Target to route requests to." }, + "v1EndpointTargetWorker": { + "type": "object", + "properties": { + "namespace": { + "type": "string", + "description": "Namespace to route requests to." + }, + "taskQueue": { + "type": "string", + "description": "Nexus task queue to route requests to." + } + }, + "description": "Target a worker polling on a Nexus task queue in a specific namespace." + }, "v1EventGroupMarker": { "type": "object", "properties": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 71e444e29..31df916de 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10746,6 +10746,8 @@ components: $ref: '#/components/schemas/Callback_Nexus' internal: $ref: '#/components/schemas/Callback_Internal' + worker: + $ref: '#/components/schemas/Callback_Worker' links: type: array items: @@ -10822,6 +10824,42 @@ components: additionalProperties: type: string description: Header to attach to callback request. + Callback_Worker: + type: object + properties: + taskqueueName: + type: string + description: |- + Nexus task queue the Temporal worker is listening on. + + NOTE: This is not a temporal.api.taskqueue.v1.TaskQueue to avoid a circular dependency. + service: + type: string + description: Target Nexus service, e.g. "temporal.api.notificationservice.v1.NotificationService". + operation: + type: string + description: Target operation, e.g. "OnComplete". + sourceContext: + allOf: + - $ref: '#/components/schemas/Payload' + description: |- + Arbitrary user-supplied data from the source operation's callsite. (As applicable, not all operations + support attaching context data.) + + There is a relatively small maximum size the source context can be, e.g. 32KiB. + description: |- + Worker callbacks are requests to invoke a specific shape of Nexus operation on a Temporal worker. + The specified Nexus operation must have the following: + - Input: temporal.api.notificationservice.v1.OnCompleteRequest + - Output: temporal.api.notificationservice.v1.OnCompleteResponse + + The targeted Nexus service must be registered within the same namespace as the source operation + the callback is attached to. (While Nexus allows for cross-namespace operations, worker callbacks + are purely "caller-side".) + + Worker callbacks are only supported for certain types of operations, e.g. standalone Nexus operations. + Attempting to attach a Worker callback for an unsupported operation will result in an INVALID_ARGUMENT + error from the server. CanceledFailureInfo: type: object properties: @@ -17055,6 +17093,11 @@ components: allOf: - $ref: '#/components/schemas/UserMetadata' description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. + completionCallbacks: + type: array + items: + $ref: '#/components/schemas/Callback' + description: Completion callbacks to be invoked once the Nexus operation reaches a terminal state. StartNexusOperationExecutionResponse: type: object properties: diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 1af5b4acc..08e26dc74 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -201,10 +201,41 @@ message Callback { bytes data = 1; } + // Worker callbacks are requests to invoke a specific shape of Nexus operation on a Temporal worker. + // The specified Nexus operation must have the following: + // - Input: temporal.api.notificationservice.v1.OnCompleteRequest + // - Output: temporal.api.notificationservice.v1.OnCompleteResponse + // + // The targeted Nexus service must be registered within the same namespace as the source operation + // the callback is attached to. (While Nexus allows for cross-namespace operations, worker callbacks + // are purely "caller-side".) + // + // Worker callbacks are only supported for certain types of operations, e.g. standalone Nexus operations. + // Attempting to attach a Worker callback for an unsupported operation will result in an INVALID_ARGUMENT + // error from the server. + message Worker { + // Nexus task queue the Temporal worker is listening on. + // + // NOTE: This is not a temporal.api.taskqueue.v1.TaskQueue to avoid a circular dependency. + string taskqueue_name = 1; + + // Target Nexus service, e.g. "temporal.api.notificationservice.v1.NotificationService". + string service = 2; + // Target operation, e.g. "OnComplete". + string operation = 3; + + // Arbitrary user-supplied data from the source operation's callsite. (As applicable, not all operations + // support attaching context data.) + // + // There is a relatively small maximum size the source context can be, e.g. 32KiB. + temporal.api.common.v1.Payload source_context = 4; + } + reserved 1; // For a generic callback mechanism to be added later. oneof variant { Nexus nexus = 2; Internal internal = 3; + Worker worker = 4; } // Links associated with the callback. It can be used to link to underlying resources of the diff --git a/temporal/api/notificationservice/v1/request_response.proto b/temporal/api/notificationservice/v1/request_response.proto new file mode 100644 index 000000000..26e9d53dc --- /dev/null +++ b/temporal/api/notificationservice/v1/request_response.proto @@ -0,0 +1,57 @@ +syntax = "proto3"; + +package temporal.api.notificationservice.v1; + +option go_package = "go.temporal.io/api/notificationservice/v1;notificationservice"; +option java_package = "io.temporal.api.notificationservice.v1"; +option java_multiple_files = true; +option java_outer_classname = "RequestResponseProto"; +option ruby_package = "Temporalio::Api::NotificationService::V1"; +option csharp_namespace = "Temporalio.Api.NotificationService.V1"; + +import "temporal/api/common/v1/message.proto"; +import "temporal/api/failure/v1/message.proto"; + +// OnCompleteRequest is the request type to the NotificationService's OnComplete operation, +// allowing for defining completion handlers for arbitrary asynchronous operations. +message OnCompleteRequest { + + // The source Nexus operation that the OnComplete invocation is reporting. + message NexusOperation { + // The Nexus endpoint. + string endpoint = 1; + // The Nexus service. + string service = 2; + // The Nexus operation. + string operation = 3; + + // The token the operation produced. (If it was an asynchronous Nexus operation.) + string operation_token = 4; + } + + // The source asynchronous operation. + message SourceOperation { + oneof variant { + NexusOperation nexus_operation = 1; + } + } + + // The outcome of the source operation. + message Outcome { + oneof result { + // The operation was successful, and resulted in the given payload(s). + temporal.api.common.v1.Payloads success = 1; + // The operation failed. Includes timeout, cancellation, and application errors. + temporal.api.failure.v1.Failure failure = 2; + } + } + + SourceOperation source_operation = 1; + Outcome outcome = 2; + + // User-supplied data which was added to the source invocation. (As applicable.) + temporal.api.common.v1.Payload source_context = 3; +} + +// OnCompleteResponse is the return type of the OnComplete operation. +message OnCompleteResponse {} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 66f478c5c..7e4f3ecc3 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3393,6 +3393,9 @@ message StartNexusOperationExecutionRequest { map nexus_header = 15; // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. temporal.api.sdk.v1.UserMetadata user_metadata = 16; + + // Completion callbacks to be invoked once the Nexus operation reaches a terminal state. + repeated temporal.api.common.v1.Callback completion_callbacks = 17; } message StartNexusOperationExecutionResponse { From 1329a40073317fecf083303bcaf1e4eaa0be8983 Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Tue, 21 Jul 2026 13:25:34 -0700 Subject: [PATCH 2/3] Expose CallbackExecutionInfo from DescribeNexusOperationExecutionResponse --- openapi/openapiv2.json | 97 ++++++++++++++++++- openapi/openapiv3.yaml | 92 +++++++++++++++++- temporal/api/common/v1/message.proto | 2 +- temporal/api/enums/v1/common.proto | 2 +- temporal/api/workflowservice/v1/message.proto | 74 ++++++++++++++ .../workflowservice/v1/request_response.proto | 5 + 6 files changed, 266 insertions(+), 6 deletions(-) create mode 100644 temporal/api/workflowservice/v1/message.proto diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index ec3482868..8f23c60c6 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1,7 +1,7 @@ { "swagger": "2.0", "info": { - "title": "temporal/api/workflowservice/v1/request_response.proto", + "title": "temporal/api/workflowservice/v1/message.proto", "version": "version not set" }, "tags": [ @@ -14414,6 +14414,89 @@ }, "description": "Callback to attach to various events in the system, e.g. workflow run completion." }, + "v1CallbackExecutionInfo": { + "type": "object", + "properties": { + "callbackId": { + "type": "string", + "description": "Identifier of the callback's execution. Unique within the containing namespace." + }, + "runId": { + "type": "string", + "description": "Run ID of the callback execution." + }, + "callback": { + "$ref": "#/definitions/v1Callback", + "description": "The Callback being described." + }, + "state": { + "$ref": "#/definitions/v1CallbackState", + "description": "The detailed state of the callback." + }, + "stateReason": { + "type": "string", + "description": "Human friendly context describing the state, if applicable.\ne.g. if the state is BLOCKED, provides an explanation why." + }, + "outcome": { + "$ref": "#/definitions/v1CallbackExecutionOutcome", + "description": "The outcome of the callback's execution, as applicable." + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver/execute callback.\n\nThis number is approximate. There could be more attempts if the server crashes before recording the attempt's completion, or fewer\nif the callback was terminated or timed out after the counter has been incremented and before an attempt could be made." + }, + "createTime": { + "type": "string", + "format": "date-time", + "title": "The time when the callback was created. (But not necessarily scheduled.)" + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "Time when the callback transitioned to a terminal state." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/v1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled (only set when state is BACKING_OFF)." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Schedule-to-close timeout for this callback." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Incremented each time the callback's state is mutated in persistence." + } + }, + "description": "Information about a callback's execution." + }, + "v1CallbackExecutionOutcome": { + "type": "object", + "properties": { + "success": { + "type": "object", + "properties": {}, + "title": "The callback completed successfully. (Which may include delivering a \"failed\" result successfully.)" + }, + "failure": { + "$ref": "#/definitions/v1Failure", + "description": "The failure if the callback was not able to complete successfully. e.g. timed out, received an\nunretriable error, etc." + } + }, + "description": "The outcome of a callback's execution, either success or a failure." + }, "v1CallbackState": { "type": "string", "enum": [ @@ -14426,12 +14509,12 @@ "CALLBACK_STATE_BLOCKED" ], "default": "CALLBACK_STATE_UNSPECIFIED", - "description": "State of a callback.\n\n - CALLBACK_STATE_UNSPECIFIED: Default value, unspecified state.\n - CALLBACK_STATE_STANDBY: Callback is standing by, waiting to be triggered.\n - CALLBACK_STATE_SCHEDULED: Callback is in the queue waiting to be executed or is currently executing.\n - CALLBACK_STATE_BACKING_OFF: Callback has failed with a retryable error and is backing off before the next attempt.\n - CALLBACK_STATE_FAILED: Callback has failed.\n - CALLBACK_STATE_SUCCEEDED: Callback has succeeded.\n - CALLBACK_STATE_BLOCKED: Callback is blocked (eg: by circuit breaker)." + "description": "State of a callback.\n\n - CALLBACK_STATE_UNSPECIFIED: Default value, unspecified state.\n - CALLBACK_STATE_STANDBY: Callback is standing by, waiting to be triggered.\n - CALLBACK_STATE_SCHEDULED: Callback is in the queue waiting to be executed or is currently executing.\n - CALLBACK_STATE_BACKING_OFF: Callback has failed with a retryable error and is backing off before the next attempt.\n - CALLBACK_STATE_FAILED: Callback has failed.\n - CALLBACK_STATE_SUCCEEDED: Callback has succeeded.\n - CALLBACK_STATE_BLOCKED: Callback is blocked, e.g. by circuit breaker." }, "v1CallbackWorker": { "type": "object", "properties": { - "taskqueueName": { + "taskQueueName": { "type": "string", "description": "Nexus task queue the Temporal worker is listening on.\n\nNOTE: This is not a temporal.api.taskqueue.v1.TaskQueue to avoid a circular dependency." }, @@ -15375,6 +15458,14 @@ "type": "string", "format": "byte", "description": "Token for follow-on long-poll requests. Absent only if the operation is complete." + }, + "completionCallbacks": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1CallbackExecutionInfo" + }, + "description": "Completion callbacks to be invoked once the Nexus operation reaches a terminal state.\nThey will remain in the CALLBACK_STATE_STANDBY state until the Nexus operation is finished." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 31df916de..a031df85d 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10756,6 +10756,89 @@ components: Links associated with the callback. It can be used to link to underlying resources of the callback. description: Callback to attach to various events in the system, e.g. workflow run completion. + CallbackExecutionInfo: + type: object + properties: + callbackId: + type: string + description: Identifier of the callback's execution. Unique within the containing namespace. + runId: + type: string + description: Run ID of the callback execution. + callback: + allOf: + - $ref: '#/components/schemas/Callback' + description: The Callback being described. + state: + enum: + - CALLBACK_STATE_UNSPECIFIED + - CALLBACK_STATE_STANDBY + - CALLBACK_STATE_SCHEDULED + - CALLBACK_STATE_BACKING_OFF + - CALLBACK_STATE_FAILED + - CALLBACK_STATE_SUCCEEDED + - CALLBACK_STATE_BLOCKED + type: string + description: The detailed state of the callback. + format: enum + stateReason: + type: string + description: |- + Human friendly context describing the state, if applicable. + e.g. if the state is BLOCKED, provides an explanation why. + outcome: + allOf: + - $ref: '#/components/schemas/CallbackExecutionOutcome' + description: The outcome of the callback's execution, as applicable. + attempt: + type: integer + description: |- + The number of attempts made to deliver/execute callback. + + This number is approximate. There could be more attempts if the server crashes before recording the attempt's completion, or fewer + if the callback was terminated or timed out after the counter has been incremented and before an attempt could be made. + format: int32 + createTime: + type: string + description: The time when the callback was created. (But not necessarily scheduled.) + format: date-time + closeTime: + type: string + description: Time when the callback transitioned to a terminal state. + format: date-time + lastAttemptCompleteTime: + type: string + description: The time when the last attempt completed. + format: date-time + lastAttemptFailure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The last attempt's failure, if any. + nextAttemptScheduleTime: + type: string + description: The time when the next attempt is scheduled (only set when state is BACKING_OFF). + format: date-time + scheduleToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Schedule-to-close timeout for this callback. + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + stateTransitionCount: + type: string + description: Incremented each time the callback's state is mutated in persistence. + description: Information about a callback's execution. + CallbackExecutionOutcome: + type: object + properties: + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: |- + The failure if the callback was not able to complete successfully. e.g. timed out, received an + unretriable error, etc. + description: The outcome of a callback's execution, either success or a failure. CallbackInfo: type: object properties: @@ -10827,7 +10910,7 @@ components: Callback_Worker: type: object properties: - taskqueueName: + taskQueueName: type: string description: |- Nexus task queue the Temporal worker is listening on. @@ -11844,6 +11927,13 @@ components: type: string description: Token for follow-on long-poll requests. Absent only if the operation is complete. format: bytes + completionCallbacks: + type: array + items: + $ref: '#/components/schemas/CallbackExecutionInfo' + description: |- + Completion callbacks to be invoked once the Nexus operation reaches a terminal state. + They will remain in the CALLBACK_STATE_STANDBY state until the Nexus operation is finished. DescribeScheduleResponse: type: object properties: diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 08e26dc74..bc5e54411 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -217,7 +217,7 @@ message Callback { // Nexus task queue the Temporal worker is listening on. // // NOTE: This is not a temporal.api.taskqueue.v1.TaskQueue to avoid a circular dependency. - string taskqueue_name = 1; + string task_queue_name = 1; // Target Nexus service, e.g. "temporal.api.notificationservice.v1.NotificationService". string service = 2; diff --git a/temporal/api/enums/v1/common.proto b/temporal/api/enums/v1/common.proto index cdc387173..e2929337e 100644 --- a/temporal/api/enums/v1/common.proto +++ b/temporal/api/enums/v1/common.proto @@ -47,7 +47,7 @@ enum CallbackState { CALLBACK_STATE_FAILED = 4; // Callback has succeeded. CALLBACK_STATE_SUCCEEDED = 5; - // Callback is blocked (eg: by circuit breaker). + // Callback is blocked, e.g. by circuit breaker. CALLBACK_STATE_BLOCKED = 6; } diff --git a/temporal/api/workflowservice/v1/message.proto b/temporal/api/workflowservice/v1/message.proto new file mode 100644 index 000000000..73d12f90b --- /dev/null +++ b/temporal/api/workflowservice/v1/message.proto @@ -0,0 +1,74 @@ +syntax = "proto3"; + +package temporal.api.workflowservice.v1; + +option go_package = "go.temporal.io/api/workflowservice/v1;workflowservice"; +option java_package = "io.temporal.api.workflowservice.v1"; +option java_multiple_files = true; +option java_outer_classname = "MessageProto"; +option ruby_package = "Temporalio::Api::WorkflowService::V1"; +option csharp_namespace = "Temporalio.Api.WorkflowService.V1"; + +import "google/protobuf/duration.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; + +import "temporal/api/common/v1/message.proto"; +import "temporal/api/enums/v1/common.proto"; +import "temporal/api/failure/v1/message.proto"; + +// The outcome of a callback's execution, either success or a failure. +message CallbackExecutionOutcome { + oneof value { + // The callback completed successfully. (Which may include delivering a "failed" result successfully.) + google.protobuf.Empty success = 1; + // The failure if the callback was not able to complete successfully. e.g. timed out, received an + // unretriable error, etc. + temporal.api.failure.v1.Failure failure = 2; + } +} + +// Information about a callback's execution. +message CallbackExecutionInfo { + // Identifier of the callback's execution. Unique within the containing namespace. + string callback_id = 1; + // Run ID of the callback execution. + string run_id = 2; + + // The Callback being described. + temporal.api.common.v1.Callback callback = 3; + // The detailed state of the callback. + temporal.api.enums.v1.CallbackState state = 4; + // Human friendly context describing the state, if applicable. + // e.g. if the state is BLOCKED, provides an explanation why. + string state_reason = 5; + + // The outcome of the callback's execution, as applicable. + CallbackExecutionOutcome outcome = 6; + + // The number of attempts made to deliver/execute callback. + // + // This number is approximate. There could be more attempts if the server crashes before recording the attempt's completion, or fewer + // if the callback was terminated or timed out after the counter has been incremented and before an attempt could be made. + int32 attempt = 7; + + // The time when the callback was created. (But not necessarily scheduled.) + google.protobuf.Timestamp create_time = 8; + // Time when the callback transitioned to a terminal state. + google.protobuf.Timestamp close_time = 9; + + // The time when the last attempt completed. + google.protobuf.Timestamp last_attempt_complete_time = 10; + // The last attempt's failure, if any. + temporal.api.failure.v1.Failure last_attempt_failure = 11; + // The time when the next attempt is scheduled (only set when state is BACKING_OFF). + google.protobuf.Timestamp next_attempt_schedule_time = 12; + + // Schedule-to-close timeout for this callback. + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" is used to indicate interval. --) + google.protobuf.Duration schedule_to_close_timeout = 13; + + // Incremented each time the callback's state is mutated in persistence. + int64 state_transition_count = 14; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 7e4f3ecc3..e6864d3c9 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -45,6 +45,7 @@ import "temporal/api/sdk/v1/task_complete_metadata.proto"; import "temporal/api/sdk/v1/user_metadata.proto"; import "temporal/api/nexus/v1/message.proto"; import "temporal/api/worker/v1/message.proto"; +import "temporal/api/workflowservice/v1/message.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/field_mask.proto"; @@ -3444,6 +3445,10 @@ message DescribeNexusOperationExecutionResponse { // Token for follow-on long-poll requests. Absent only if the operation is complete. bytes long_poll_token = 6; + + // Completion callbacks to be invoked once the Nexus operation reaches a terminal state. + // They will remain in the CALLBACK_STATE_STANDBY state until the Nexus operation is finished. + repeated CallbackExecutionInfo completion_callbacks = 7; } message PollNexusOperationExecutionRequest { From 1a137206f19d45f77bf029dce97f68fa2abf630b Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Tue, 21 Jul 2026 19:31:12 -0700 Subject: [PATCH 3/3] Add new Callback variant of Link --- temporal/api/common/v1/message.proto | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index bc5e54411..6b8098286 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -304,12 +304,28 @@ message Link { string reason = 4; } + // A link to a callback or completion handler for an operation. e.g. not a link to a standalone Nexus operation, + // but the callback that was executed once that operation finished. + message Callback { + message NexusOperationCompletion { + string operation_id = 1; + string run_id = 2; + string request_id = 3; + } + + string callback_id = 1; + oneof variant { + NexusOperationCompletion nexus_operation_completion = 2; + } + } + oneof variant { WorkflowEvent workflow_event = 1; BatchJob batch_job = 2; Activity activity = 3; NexusOperation nexus_operation = 4; Workflow workflow = 5; + Callback callback = 6; } }