diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 97ff181c9..b596d4312 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -10757,6 +10757,20 @@ } } }, + "CallbackNexusOperationCompletion": { + "type": "object", + "properties": { + "operationId": { + "type": "string" + }, + "runId": { + "type": "string" + }, + "requestId": { + "type": "string" + } + } + }, "ComputeStatusProviderValidationStatus": { "type": "object", "properties": { @@ -10834,20 +10848,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": { @@ -11290,7 +11290,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Callback" + "$ref": "#/definitions/commonV1Callback" }, "description": "Completion callbacks attached to the running workflow update." } @@ -12316,7 +12316,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Callback" + "$ref": "#/definitions/commonV1Callback" }, "description": "Callbacks to be called by the server when this activity reaches a terminal state.\nCallback addresses must be whitelisted in the server's dynamic configuration." }, @@ -12469,6 +12469,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/commonV1Callback" + }, + "description": "Completion callbacks to be invoked once the Nexus operation reaches a terminal state." } } }, @@ -12549,7 +12557,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Callback" + "$ref": "#/definitions/commonV1Callback" }, "description": "Callbacks to be called by the server when this workflow reaches a terminal state.\nIf the workflow continues-as-new, these callbacks will be carried over to the new execution.\nCallback addresses must be whitelisted in the server's dynamic configuration." }, @@ -13093,7 +13101,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Callback" + "$ref": "#/definitions/commonV1Callback" }, "description": "Callbacks to be called by the server when this update reaches a terminal state." }, @@ -13193,7 +13201,7 @@ "type": "object", "properties": { "callback": { - "$ref": "#/definitions/v1Callback", + "$ref": "#/definitions/commonV1Callback", "description": "Information on how this callback should be invoked (e.g. its URL and type)." }, "registrationTime": { @@ -13253,7 +13261,7 @@ "type": "object", "properties": { "callback": { - "$ref": "#/definitions/v1Callback", + "$ref": "#/definitions/commonV1Callback", "description": "Information on how this callback should be invoked (e.g. its URL and type)." }, "trigger": { @@ -13323,6 +13331,29 @@ }, "description": "When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and\nthere is already an existing running workflow, OnConflictOptions defines actions to be taken on\nthe existing running workflow. In this case, it will create a WorkflowExecutionOptionsUpdatedEvent\nhistory event in the running workflow with the changes requested in this object." }, + "commonV1Callback": { + "type": "object", + "properties": { + "nexus": { + "$ref": "#/definitions/CallbackNexus" + }, + "internal": { + "$ref": "#/definitions/CallbackInternal" + }, + "worker": { + "$ref": "#/definitions/v1CallbackWorker" + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Link" + }, + "description": "Links associated with the callback. It can be used to link to underlying resources of the\ncallback." + } + }, + "description": "Callback to attach to various events in the system, e.g. workflow run completion." + }, "protobufAny": { "type": "object", "properties": { @@ -14397,25 +14428,34 @@ }, "description": "CalendarSpec describes an event specification relative to the calendar,\nsimilar to a traditional cron specification, but with labeled fields. Each\nfield can be one of:\n *: matches always\n x: matches when the field equals x\n x/y : matches when the field equals x+n*y where n is an integer\n x-z: matches when the field is between x and z inclusive\n w,x,y,...: matches when the field is one of the listed values\nEach x, y, z, ... is either a decimal integer, or a month or day of week name\nor abbreviation (in the appropriate fields).\nA timestamp matches if all fields match.\nNote that fields have different default values, for convenience.\nNote that the special case that some cron implementations have for treating\nday_of_month and day_of_week as \"or\" instead of \"and\" when both are set is\nnot implemented.\nday_of_week can accept 0 or 7 as Sunday\nCalendarSpec gets compiled into StructuredCalendarSpec, which is what will be\nreturned if you describe the schedule." }, - "v1Callback": { + "v1CallbackExecutionInfo": { "type": "object", "properties": { - "nexus": { - "$ref": "#/definitions/CallbackNexus" + "callbackId": { + "type": "string", + "description": "Identifier of the callback's execution. Unique within the containing namespace." }, - "internal": { - "$ref": "#/definitions/CallbackInternal" + "info": { + "$ref": "#/definitions/apiCallbackV1CallbackInfo" }, - "links": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/v1Link" - }, - "description": "Links associated with the callback. It can be used to link to underlying resources of the\ncallback." + "outcome": { + "$ref": "#/definitions/v1CallbackExecutionOutcome" } - }, - "description": "Callback to attach to various events in the system, e.g. workflow run completion." + } + }, + "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." + } + } }, "v1CallbackState": { "type": "string", @@ -14429,7 +14469,31 @@ "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": { + "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. \"HTTPAdaptor\"." + }, + "operation": { + "type": "string", + "description": "Target operation, e.g. \"DeliverAsWebhook\"." + }, + "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", @@ -15354,6 +15418,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." } } }, @@ -15591,7 +15663,7 @@ "type": "object", "properties": { "worker": { - "$ref": "#/definitions/EndpointTargetWorker" + "$ref": "#/definitions/v1EndpointTargetWorker" }, "external": { "$ref": "#/definitions/EndpointTargetExternal" @@ -15599,6 +15671,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": { @@ -16427,10 +16513,25 @@ }, "workflow": { "$ref": "#/definitions/LinkWorkflow" + }, + "callback": { + "$ref": "#/definitions/v1LinkCallback" } }, "description": "Link can be associated with history events. It might contain information about an external entity\nrelated to the history event. For example, workflow A makes a Nexus call that starts workflow B:\nin this case, a history event in workflow A could contain a Link to the workflow started event in\nworkflow B, and vice-versa." }, + "v1LinkCallback": { + "type": "object", + "properties": { + "callbackId": { + "type": "string" + }, + "nexusOperationCompletion": { + "$ref": "#/definitions/CallbackNexusOperationCompletion" + } + }, + "description": "A link to a callback or completion handler for an operation. e.g. not a link to a standalone Nexus operation,\nbut the callback that was executed once that operation finished." + }, "v1ListActivityExecutionsResponse": { "type": "object", "properties": { @@ -18410,7 +18511,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Callback" + "$ref": "#/definitions/commonV1Callback" }, "description": "Callbacks to be called by the server when this update reaches a terminal state." }, @@ -21250,7 +21351,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Callback" + "$ref": "#/definitions/commonV1Callback" }, "description": "Completion callbacks attached to the running workflow execution." }, @@ -21466,7 +21567,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Callback" + "$ref": "#/definitions/commonV1Callback" }, "description": "Completion callbacks attached when this workflow was started." }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index f2081bd9b..ad214c8d8 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10748,6 +10748,8 @@ components: $ref: '#/components/schemas/Callback_Nexus' internal: $ref: '#/components/schemas/Callback_Internal' + worker: + $ref: '#/components/schemas/Callback_Worker' links: type: array items: @@ -10756,6 +10758,25 @@ 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. + info: + $ref: '#/components/schemas/CallbackInfo' + outcome: + $ref: '#/components/schemas/CallbackExecutionOutcome' + 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. CallbackInfo: type: object properties: @@ -10824,6 +10845,51 @@ components: additionalProperties: type: string description: Header to attach to callback request. + Callback_NexusOperationCompletion: + type: object + properties: + operationId: + type: string + runId: + type: string + requestId: + type: string + 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. "HTTPAdaptor". + operation: + type: string + description: Target operation, e.g. "DeliverAsWebhook". + 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: @@ -11808,6 +11874,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: @@ -12841,6 +12914,8 @@ components: $ref: '#/components/schemas/Link_NexusOperation' workflow: $ref: '#/components/schemas/Link_Workflow' + callback: + $ref: '#/components/schemas/Link_Callback' description: |- Link can be associated with history events. It might contain information about an external entity related to the history event. For example, workflow A makes a Nexus call that starts workflow B: @@ -12865,6 +12940,16 @@ components: A link to a built-in batch job. Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc). This link can be put on workflow history events generated by actions taken by a batch job. + Link_Callback: + type: object + properties: + callbackId: + type: string + nexusOperationCompletion: + $ref: '#/components/schemas/Callback_NexusOperationCompletion' + description: |- + 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. Link_NexusOperation: type: object properties: @@ -17060,6 +17145,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/callback/v1/message.proto b/temporal/api/callback/v1/message.proto index f881a4eef..47cc020c8 100644 --- a/temporal/api/callback/v1/message.proto +++ b/temporal/api/callback/v1/message.proto @@ -9,6 +9,7 @@ option java_outer_classname = "MessageProto"; option ruby_package = "Temporalio::Api::Callback::V1"; option csharp_namespace = "Temporalio.Api.Callback.V1"; +import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto"; import "temporal/api/common/v1/message.proto"; @@ -34,4 +35,23 @@ message CallbackInfo { google.protobuf.Timestamp next_attempt_schedule_time = 7; // If the state is BLOCKED, blocked reason provides additional information. string blocked_reason = 8; -} \ No newline at end of file +} + +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; + } +} + +message CallbackExecutionInfo { + // Identifier of the callback's execution. Unique within the containing namespace. + string callback_id = 1; + + CallbackInfo info = 2; + CallbackExecutionOutcome outcome = 3; +} + diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 1af5b4acc..6bf391d26 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 task_queue_name = 1; + + // Target Nexus service, e.g. "HTTPAdapter". + string service = 2; + // Target operation, e.g. "DeliverAsWebhook". + 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 @@ -273,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; } } 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/notificationservice/v1/request_response.proto b/temporal/api/notificationservice/v1/request_response.proto new file mode 100644 index 000000000..edf861c77 --- /dev/null +++ b/temporal/api/notificationservice/v1/request_response.proto @@ -0,0 +1,40 @@ +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. +// +// Information about the source operation will be available in the form of a commonpb.Link, +// which will be available separately from this OnCompleteRequest. e.g. a link to the source +// standalone Nexus operation would be found in the nexuspb.StartOperationRequest parameter +// sent to the worker callback. (In addition to this OnCompleteRequest.) +message OnCompleteRequest { + + // 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; + } + } + Outcome outcome = 1; + + // User-supplied data which was added to the source invocation. (As applicable.) + temporal.api.common.v1.Payload source_context = 2; +} + +// 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..683d57bbf 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -22,6 +22,7 @@ import "temporal/api/enums/v1/update.proto"; import "temporal/api/enums/v1/activity.proto"; import "temporal/api/enums/v1/nexus.proto"; import "temporal/api/activity/v1/message.proto"; +import "temporal/api/callback/v1/message.proto"; import "temporal/api/common/v1/message.proto"; import "temporal/api/history/v1/message.proto"; import "temporal/api/workflow/v1/message.proto"; @@ -3393,6 +3394,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 { @@ -3441,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 temporal.api.callback.v1.CallbackExecutionInfo completion_callbacks = 7; } message PollNexusOperationExecutionRequest {