From a8d9291c285eca5fd16f741914cdef9a237637bf Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Sat, 28 Mar 2026 14:20:50 -0700 Subject: [PATCH 1/4] Add Stand Alone Callbacks --- openapi/openapiv2.json | 913 +++++++++++++++++- openapi/openapiv3.yaml | 840 +++++++++++++++- temporal/api/callback/v1/message.proto | 113 +++ temporal/api/common/v1/message.proto | 8 + temporal/api/enums/v1/common.proto | 4 + temporal/api/errordetails/v1/message.proto | 6 + temporal/api/nexus/v1/message.proto | 2 + .../workflowservice/v1/request_response.proto | 135 +++ temporal/api/workflowservice/v1/service.proto | 81 ++ 9 files changed, 2048 insertions(+), 54 deletions(-) create mode 100644 temporal/api/callback/v1/message.proto diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index d2ffdad75..f90e73a3a 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1237,6 +1237,295 @@ ] } }, + "/api/v1/namespaces/{namespace}/callback-count": { + "get": { + "summary": "CountCallbackExecutions is a visibility API to count callback executions in a specific namespace.", + "operationId": "CountCallbackExecutions2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CountCallbackExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/callbacks": { + "get": { + "summary": "ListCallbackExecutions is a visibility API to list callback executions in a specific namespace.", + "operationId": "ListCallbackExecutions2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListCallbackExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "description": "Max number of executions to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token returned in ListCallbackExecutionsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/callbacks/{callbackId}": { + "get": { + "summary": "DescribeCallbackExecution returns information about a callback execution.\nIt can be used to:\n- Get current callback info without waiting\n- Long-poll for next state change and return new callback info\nResponse can optionally include the outcome (if the callback has completed).", + "operationId": "DescribeCallbackExecution2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeCallbackExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "callbackId", + "description": "Identifier for the callback", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "runId", + "description": "Run ID of the callback execution to describe. If empty, the latest run will be described.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the callback has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeCallbackExecutionResponse. If present, long-poll until callback\nstate changes from the state encoded in this token. If absent, return current state immediately.\nNote that callback state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "StartCallbackExecution starts a new standalone callback execution.", + "description": "Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same\ncallback ID in this namespace.", + "operationId": "StartCallbackExecution2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StartCallbackExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "callbackId", + "description": "Identifier for this callback. Required. Must be unique among callbacks in the same namespace.\nIf a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartCallbackExecutionBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/callbacks/{callbackId}/outcome": { + "get": { + "summary": "PollCallbackExecution long-polls for a callback execution to complete and returns the outcome.", + "operationId": "PollCallbackExecution2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PollCallbackExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "callbackId", + "description": "Identifier for the callback", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "runId", + "description": "Run ID of the callback execution to poll. If empty, the latest run will be polled.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/callbacks/{callbackId}/terminate": { + "post": { + "summary": "TerminateCallbackExecution terminates an existing callback execution immediately.", + "description": "Termination happens immediately. A terminated callback will have its state set to\nCALLBACK_STATE_TERMINATED.", + "operationId": "TerminateCallbackExecution2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1TerminateCallbackExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "callbackId", + "description": "Identifier for the callback", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceTerminateCallbackExecutionBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { "post": { "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `SetWorkerDeploymentCurrentVersion`.", @@ -5919,7 +6208,298 @@ "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartBatchOperationResponse" + "$ref": "#/definitions/v1StartBatchOperationResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Job ID defines the unique ID for the batch job", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/batch-operations/{jobId}/stop": { + "post": { + "summary": "StopBatchOperation stops a batch operation", + "operationId": "StopBatchOperation", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StopBatchOperationResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Batch job id", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/callback-count": { + "get": { + "summary": "CountCallbackExecutions is a visibility API to count callback executions in a specific namespace.", + "operationId": "CountCallbackExecutions", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CountCallbackExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/callbacks": { + "get": { + "summary": "ListCallbackExecutions is a visibility API to list callback executions in a specific namespace.", + "operationId": "ListCallbackExecutions", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListCallbackExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "description": "Max number of executions to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token returned in ListCallbackExecutionsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/callbacks/{callbackId}": { + "get": { + "summary": "DescribeCallbackExecution returns information about a callback execution.\nIt can be used to:\n- Get current callback info without waiting\n- Long-poll for next state change and return new callback info\nResponse can optionally include the outcome (if the callback has completed).", + "operationId": "DescribeCallbackExecution", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeCallbackExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "callbackId", + "description": "Identifier for the callback", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "runId", + "description": "Run ID of the callback execution to describe. If empty, the latest run will be described.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the callback has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeCallbackExecutionResponse. If present, long-poll until callback\nstate changes from the state encoded in this token. If absent, return current state immediately.\nNote that callback state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "StartCallbackExecution starts a new standalone callback execution.", + "description": "Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same\ncallback ID in this namespace.", + "operationId": "StartCallbackExecution", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StartCallbackExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "callbackId", + "description": "Identifier for this callback. Required. Must be unique among callbacks in the same namespace.\nIf a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartCallbackExecutionBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/callbacks/{callbackId}/outcome": { + "get": { + "summary": "PollCallbackExecution long-polls for a callback execution to complete and returns the outcome.", + "operationId": "PollCallbackExecution", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PollCallbackExecutionResponse" } }, "default": { @@ -5932,25 +6512,23 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Job ID defines the unique ID for the batch job", + "name": "callbackId", + "description": "Identifier for the callback", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" - } + "name": "runId", + "description": "Run ID of the callback execution to poll. If empty, the latest run will be polled.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -5958,15 +6536,16 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}/stop": { + "/namespaces/{namespace}/callbacks/{callbackId}/terminate": { "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation", + "summary": "TerminateCallbackExecution terminates an existing callback execution immediately.", + "description": "Termination happens immediately. A terminated callback will have its state set to\nCALLBACK_STATE_TERMINATED.", + "operationId": "TerminateCallbackExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1TerminateCallbackExecutionResponse" } }, "default": { @@ -5979,14 +6558,13 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "callbackId", + "description": "Identifier for the callback", "in": "path", "required": true, "type": "string" @@ -5996,7 +6574,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" + "$ref": "#/definitions/WorkflowServiceTerminateCallbackExecutionBody" } } ], @@ -9077,6 +9655,10 @@ "type": "string" }, "description": "Header to attach to callback request." + }, + "token": { + "type": "string", + "description": "Standard token to use for completion." } } }, @@ -9165,6 +9747,15 @@ }, "description": "A link to a built-in batch job.\nBatch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).\nThis link can be put on workflow history events generated by actions taken by a batch job." }, + "LinkCallbackExecution": { + "type": "object", + "properties": { + "callbackId": { + "type": "string" + } + }, + "title": "A link to a durable callback execution" + }, "LinkWorkflowEvent": { "type": "object", "properties": { @@ -10490,6 +11081,39 @@ } } }, + "WorkflowServiceStartCallbackExecutionBody": { + "type": "object", + "properties": { + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "requestId": { + "type": "string", + "description": "A unique identifier for this start request. Typically UUIDv4." + }, + "runId": { + "type": "string", + "description": "Callback execution run ID, targets the latest run if run_id is empty." + }, + "callback": { + "$ref": "#/definitions/v1Callback", + "description": "Information on how this callback should be invoked (e.g. its URL and type)." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Schedule-to-close timeout for this callback." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes for indexing." + }, + "completion": { + "$ref": "#/definitions/v1CallbackExecutionCompletion", + "description": "The Nexus completion data to deliver to the callback URL.\nRequired. Contains either a successful result payload or a failure." + } + } + }, "WorkflowServiceStartWorkflowExecutionBody": { "type": "object", "properties": { @@ -10639,6 +11263,27 @@ } } }, + "WorkflowServiceTerminateCallbackExecutionBody": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "Run ID of the callback execution to terminate. If empty, the latest run will be terminated." + }, + "identity": { + "type": "string", + "description": "The identity of the worker/client." + }, + "requestId": { + "type": "string", + "description": "Used to de-dupe termination requests." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the termination." + } + } + }, "WorkflowServiceTerminateWorkflowExecutionBody": { "type": "object", "properties": { @@ -12089,6 +12734,140 @@ }, "description": "Callback to attach to various events in the system, e.g. workflow run completion." }, + "v1CallbackExecutionCompletion": { + "type": "object", + "properties": { + "success": { + "$ref": "#/definitions/v1Payload", + "description": "Deliver a successful Nexus operation completion with this result payload.\nIf set, the callback delivers a successful completion to the target URL." + }, + "failure": { + "$ref": "#/definitions/v1Failure", + "description": "Deliver a failed Nexus operation completion with this failure.\nIf set, the callback delivers a failed completion to the target URL." + } + }, + "description": "The Nexus completion data that a standalone callback execution will deliver to its target URL.\nExactly one of success or failure should be set." + }, + "v1CallbackExecutionInfo": { + "type": "object", + "properties": { + "callbackId": { + "type": "string", + "description": "Unique identifier of this callback within its namespace." + }, + "runId": { + "type": "string", + "description": "Run ID of the callback execution." + }, + "callback": { + "$ref": "#/definitions/v1Callback", + "description": "Information on how this callback should be invoked (e.g. its URL and type)." + }, + "state": { + "$ref": "#/definitions/v1CallbackState", + "description": "Current state of the callback." + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver the callback.\nThis number represents a minimum bound since the attempt is incremented after the callback request completes." + }, + "createTime": { + "type": "string", + "format": "date-time", + "description": "The time when the callback was created/scheduled." + }, + "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." + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, provides additional information." + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "Time when the callback transitioned to a terminal state." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes for indexing." + }, + "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 standalone callback execution." + }, + "v1CallbackExecutionListInfo": { + "type": "object", + "properties": { + "callbackId": { + "type": "string", + "description": "Unique identifier of this callback within its namespace." + }, + "runId": { + "type": "string", + "description": "Run ID of the callback execution." + }, + "state": { + "$ref": "#/definitions/v1CallbackState", + "description": "Current state of the callback." + }, + "createTime": { + "type": "string", + "format": "date-time", + "description": "The time when the callback was created/scheduled." + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "Time when the callback transitioned to a terminal state." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes from the start request." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Incremented each time the callback's state is mutated." + } + }, + "description": "Limited callback information returned in the list response." + }, + "v1CallbackExecutionOutcome": { + "type": "object", + "properties": { + "success": { + "type": "object", + "properties": {}, + "description": "The callback completed successfully." + }, + "failure": { + "$ref": "#/definitions/v1Failure", + "description": "The failure if the callback completed unsuccessfully." + } + }, + "description": "The outcome of a completed callback execution: either success or a failure." + }, "v1CallbackInfo": { "type": "object", "properties": { @@ -12143,10 +12922,12 @@ "CALLBACK_STATE_BACKING_OFF", "CALLBACK_STATE_FAILED", "CALLBACK_STATE_SUCCEEDED", - "CALLBACK_STATE_BLOCKED" + "CALLBACK_STATE_BLOCKED", + "CALLBACK_STATE_CANCELED", + "CALLBACK_STATE_TERMINATED" ], "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 (eg: by circuit breaker).\n - CALLBACK_STATE_CANCELED: Callback was canceled via RequestCancelCallbackExecution.\n - CALLBACK_STATE_TERMINATED: Callback was terminated via TerminateCallbackExecution." }, "v1CancelExternalWorkflowExecutionFailedCause": { "type": "string", @@ -12554,6 +13335,40 @@ } } }, + "v1CountCallbackExecutionsResponse": { + "type": "object", + "properties": { + "count": { + "type": "string", + "format": "int64", + "description": "If `query` is not grouping by any field, the count is an approximate number\nof callbacks that match the query.\nIf `query` is grouping by a field, the count is simply the sum of the counts\nof the groups returned in the response. This number can be smaller than the\ntotal number of callbacks matching the query." + }, + "groups": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1CountCallbackExecutionsResponseAggregationGroup" + }, + "description": "Contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." + } + } + }, + "v1CountCallbackExecutionsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CountSchedulesResponse": { "type": "object", "properties": { @@ -12884,6 +13699,24 @@ } } }, + "v1DescribeCallbackExecutionResponse": { + "type": "object", + "properties": { + "info": { + "$ref": "#/definitions/v1CallbackExecutionInfo", + "description": "Information about the callback execution." + }, + "outcome": { + "$ref": "#/definitions/v1CallbackExecutionOutcome", + "description": "Only set if the callback is completed and include_outcome was true in the request." + }, + "longPollToken": { + "type": "string", + "format": "byte", + "description": "Token for follow-on long-poll requests. Absent only if the callback is complete." + } + } + }, "v1DescribeDeploymentResponse": { "type": "object", "properties": { @@ -13914,6 +14747,9 @@ }, "batchJob": { "$ref": "#/definitions/LinkBatchJob" + }, + "callbackExecution": { + "$ref": "#/definitions/LinkCallbackExecution" } }, "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." @@ -13968,6 +14804,23 @@ } } }, + "v1ListCallbackExecutionsResponse": { + "type": "object", + "properties": { + "executions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1CallbackExecutionListInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte", + "description": "Token to use to fetch the next page. If empty, there is no next page." + } + } + }, "v1ListDeploymentsResponse": { "type": "object", "properties": { @@ -15120,6 +15973,14 @@ } } }, + "v1PollCallbackExecutionResponse": { + "type": "object", + "properties": { + "outcome": { + "$ref": "#/definitions/v1CallbackExecutionOutcome" + } + } + }, "v1PollWorkflowTaskQueueResponse": { "type": "object", "properties": { @@ -16410,6 +17271,15 @@ "v1StartBatchOperationResponse": { "type": "object" }, + "v1StartCallbackExecutionResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the callback that was started." + } + } + }, "v1StartChildWorkflowExecutionFailedCause": { "type": "string", "enum": [ @@ -16883,6 +17753,9 @@ "v1TerminateActivityExecutionResponse": { "type": "object" }, + "v1TerminateCallbackExecutionResponse": { + "type": "object" + }, "v1TerminateWorkflowExecutionResponse": { "type": "object" }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 418ea1ba7..334c6976a 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1111,6 +1111,254 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/callback-count: + get: + tags: + - WorkflowService + description: CountCallbackExecutions is a visibility API to count callback executions in a specific namespace. + operationId: CountCallbackExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountCallbackExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/callbacks: + get: + tags: + - WorkflowService + description: ListCallbackExecutions is a visibility API to list callback executions in a specific namespace. + operationId: ListCallbackExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of executions to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListCallbackExecutionsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListCallbackExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/callbacks/{callbackId}: + get: + tags: + - WorkflowService + description: |- + DescribeCallbackExecution returns information about a callback execution. + It can be used to: + - Get current callback info without waiting + - Long-poll for next state change and return new callback info + Response can optionally include the outcome (if the callback has completed). + operationId: DescribeCallbackExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: callbackId + in: path + description: Identifier for the callback + required: true + schema: + type: string + - name: runId + in: query + description: Run ID of the callback execution to describe. If empty, the latest run will be described. + schema: + type: string + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the callback has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeCallbackExecutionResponse. If present, long-poll until callback + state changes from the state encoded in this token. If absent, return current state immediately. + Note that callback state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeCallbackExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartCallbackExecution starts a new standalone callback execution. + + Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same + callback ID in this namespace. + operationId: StartCallbackExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: callbackId + in: path + description: |- + Identifier for this callback. Required. Must be unique among callbacks in the same namespace. + If a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartCallbackExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartCallbackExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/callbacks/{callbackId}/outcome: + get: + tags: + - WorkflowService + description: PollCallbackExecution long-polls for a callback execution to complete and returns the outcome. + operationId: PollCallbackExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: callbackId + in: path + description: Identifier for the callback + required: true + schema: + type: string + - name: runId + in: query + description: Run ID of the callback execution to poll. If empty, the latest run will be polled. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollCallbackExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/callbacks/{callbackId}/terminate: + post: + tags: + - WorkflowService + description: |- + TerminateCallbackExecution terminates an existing callback execution immediately. + + Termination happens immediately. A terminated callback will have its state set to + CALLBACK_STATE_TERMINATED. + operationId: TerminateCallbackExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: callbackId + in: path + description: Identifier for the callback + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateCallbackExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateCallbackExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/current-deployment/{deployment.series_name}: post: tags: @@ -5242,11 +5490,247 @@ paths: in: query description: List page size schema: - type: integer - format: int32 - - name: nextPageToken + type: integer + format: int32 + - name: nextPageToken + in: query + description: Next page token + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListBatchOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/batch-operations/{jobId}: + get: + tags: + - WorkflowService + description: DescribeBatchOperation returns the information about a batch operation + operationId: DescribeBatchOperation + parameters: + - name: namespace + in: path + description: Namespace that contains the batch operation + required: true + schema: + type: string + - name: jobId + in: path + description: Batch job id + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeBatchOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: StartBatchOperation starts a new batch operation + operationId: StartBatchOperation + parameters: + - name: namespace + in: path + description: Namespace that contains the batch operation + required: true + schema: + type: string + - name: jobId + in: path + description: Job ID defines the unique ID for the batch job + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartBatchOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartBatchOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/batch-operations/{jobId}/stop: + post: + tags: + - WorkflowService + description: StopBatchOperation stops a batch operation + operationId: StopBatchOperation + parameters: + - name: namespace + in: path + description: Namespace that contains the batch operation + required: true + schema: + type: string + - name: jobId + in: path + description: Batch job id + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StopBatchOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StopBatchOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/callback-count: + get: + tags: + - WorkflowService + description: CountCallbackExecutions is a visibility API to count callback executions in a specific namespace. + operationId: CountCallbackExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountCallbackExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/callbacks: + get: + tags: + - WorkflowService + description: ListCallbackExecutions is a visibility API to list callback executions in a specific namespace. + operationId: ListCallbackExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of executions to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListCallbackExecutionsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListCallbackExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/callbacks/{callbackId}: + get: + tags: + - WorkflowService + description: |- + DescribeCallbackExecution returns information about a callback execution. + It can be used to: + - Get current callback info without waiting + - Long-poll for next state change and return new callback info + Response can optionally include the outcome (if the callback has completed). + operationId: DescribeCallbackExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: callbackId + in: path + description: Identifier for the callback + required: true + schema: + type: string + - name: runId + in: query + description: Run ID of the callback execution to describe. If empty, the latest run will be described. + schema: + type: string + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the callback has completed. + schema: + type: boolean + - name: longPollToken in: query - description: Next page token + description: |- + Token from a previous DescribeCallbackExecutionResponse. If present, long-poll until callback + state changes from the state encoded in this token. If absent, return current state immediately. + Note that callback state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. schema: type: string format: bytes @@ -5256,98 +5740,110 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListBatchOperationsResponse' + $ref: '#/components/schemas/DescribeCallbackExecutionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/batch-operations/{jobId}: - get: + post: tags: - WorkflowService - description: DescribeBatchOperation returns the information about a batch operation - operationId: DescribeBatchOperation + description: |- + StartCallbackExecution starts a new standalone callback execution. + + Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same + callback ID in this namespace. + operationId: StartCallbackExecution parameters: - name: namespace in: path - description: Namespace that contains the batch operation required: true schema: type: string - - name: jobId + - name: callbackId in: path - description: Batch job id + description: |- + Identifier for this callback. Required. Must be unique among callbacks in the same namespace. + If a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted. required: true schema: type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartCallbackExecutionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DescribeBatchOperationResponse' + $ref: '#/components/schemas/StartCallbackExecutionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - post: + /namespaces/{namespace}/callbacks/{callbackId}/outcome: + get: tags: - WorkflowService - description: StartBatchOperation starts a new batch operation - operationId: StartBatchOperation + description: PollCallbackExecution long-polls for a callback execution to complete and returns the outcome. + operationId: PollCallbackExecution parameters: - name: namespace in: path - description: Namespace that contains the batch operation required: true schema: type: string - - name: jobId + - name: callbackId in: path - description: Job ID defines the unique ID for the batch job + description: Identifier for the callback required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/StartBatchOperationRequest' - required: true + - name: runId + in: query + description: Run ID of the callback execution to poll. If empty, the latest run will be polled. + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/StartBatchOperationResponse' + $ref: '#/components/schemas/PollCallbackExecutionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/batch-operations/{jobId}/stop: + /namespaces/{namespace}/callbacks/{callbackId}/terminate: post: tags: - WorkflowService - description: StopBatchOperation stops a batch operation - operationId: StopBatchOperation + description: |- + TerminateCallbackExecution terminates an existing callback execution immediately. + + Termination happens immediately. A terminated callback will have its state set to + CALLBACK_STATE_TERMINATED. + operationId: TerminateCallbackExecution parameters: - name: namespace in: path - description: Namespace that contains the batch operation required: true schema: type: string - - name: jobId + - name: callbackId in: path - description: Batch job id + description: Identifier for the callback required: true schema: type: string @@ -5355,7 +5851,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/StopBatchOperationRequest' + $ref: '#/components/schemas/TerminateCallbackExecutionRequest' required: true responses: "200": @@ -5363,7 +5859,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/StopBatchOperationResponse' + $ref: '#/components/schemas/TerminateCallbackExecutionResponse' default: description: Default error response content: @@ -9059,6 +9555,142 @@ 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. + CallbackExecutionCompletion: + type: object + properties: + success: + allOf: + - $ref: '#/components/schemas/Payload' + description: |- + Deliver a successful Nexus operation completion with this result payload. + If set, the callback delivers a successful completion to the target URL. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: |- + Deliver a failed Nexus operation completion with this failure. + If set, the callback delivers a failed completion to the target URL. + description: |- + The Nexus completion data that a standalone callback execution will deliver to its target URL. + Exactly one of success or failure should be set. + CallbackExecutionInfo: + type: object + properties: + callbackId: + type: string + description: Unique identifier of this callback within its namespace. + runId: + type: string + description: Run ID of the callback execution. + callback: + allOf: + - $ref: '#/components/schemas/Callback' + description: Information on how this callback should be invoked (e.g. its URL and type). + state: + enum: + - CALLBACK_STATE_UNSPECIFIED + - CALLBACK_STATE_STANDBY + - CALLBACK_STATE_SCHEDULED + - CALLBACK_STATE_BACKING_OFF + - CALLBACK_STATE_FAILED + - CALLBACK_STATE_SUCCEEDED + - CALLBACK_STATE_BLOCKED + - CALLBACK_STATE_CANCELED + - CALLBACK_STATE_TERMINATED + type: string + description: Current state of the callback. + format: enum + attempt: + type: integer + description: |- + The number of attempts made to deliver the callback. + This number represents a minimum bound since the attempt is incremented after the callback request completes. + format: int32 + createTime: + type: string + description: The time when the callback was created/scheduled. + 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. + format: date-time + blockedReason: + type: string + description: If the state is BLOCKED, provides additional information. + closeTime: + type: string + description: Time when the callback transitioned to a terminal state. + format: date-time + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes for indexing. + 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 standalone callback execution. + CallbackExecutionListInfo: + type: object + properties: + callbackId: + type: string + description: Unique identifier of this callback within its namespace. + runId: + type: string + description: Run ID of the callback execution. + state: + enum: + - CALLBACK_STATE_UNSPECIFIED + - CALLBACK_STATE_STANDBY + - CALLBACK_STATE_SCHEDULED + - CALLBACK_STATE_BACKING_OFF + - CALLBACK_STATE_FAILED + - CALLBACK_STATE_SUCCEEDED + - CALLBACK_STATE_BLOCKED + - CALLBACK_STATE_CANCELED + - CALLBACK_STATE_TERMINATED + type: string + description: Current state of the callback. + format: enum + createTime: + type: string + description: The time when the callback was created/scheduled. + format: date-time + closeTime: + type: string + description: Time when the callback transitioned to a terminal state. + format: date-time + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes from the start request. + stateTransitionCount: + type: string + description: Incremented each time the callback's state is mutated. + description: Limited callback information returned in the list response. + CallbackExecutionOutcome: + type: object + properties: + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the callback completed unsuccessfully. + description: 'The outcome of a completed callback execution: either success or a failure.' CallbackInfo: type: object properties: @@ -9083,6 +9715,8 @@ components: - CALLBACK_STATE_FAILED - CALLBACK_STATE_SUCCEEDED - CALLBACK_STATE_BLOCKED + - CALLBACK_STATE_CANCELED + - CALLBACK_STATE_TERMINATED type: string format: enum attempt: @@ -9139,6 +9773,9 @@ components: additionalProperties: type: string description: Header to attach to callback request. + token: + type: string + description: Standard token to use for completion. CanceledFailureInfo: type: object properties: @@ -9513,6 +10150,33 @@ components: $ref: '#/components/schemas/Payload' count: type: string + CountCallbackExecutionsResponse: + type: object + properties: + count: + type: string + description: |- + If `query` is not grouping by any field, the count is an approximate number + of callbacks that match the query. + If `query` is grouping by a field, the count is simply the sum of the counts + of the groups returned in the response. This number can be smaller than the + total number of callbacks matching the query. + groups: + type: array + items: + $ref: '#/components/schemas/CountCallbackExecutionsResponse_AggregationGroup' + description: |- + Contains the groups if the request is grouping by a field. + The list might not be complete, and the counts of each group is approximate. + CountCallbackExecutionsResponse_AggregationGroup: + type: object + properties: + groupValues: + type: array + items: + $ref: '#/components/schemas/Payload' + count: + type: string CountSchedulesResponse: type: object properties: @@ -9929,6 +10593,21 @@ components: reason: type: string description: Reason indicates the reason to stop a operation + DescribeCallbackExecutionResponse: + type: object + properties: + info: + allOf: + - $ref: '#/components/schemas/CallbackExecutionInfo' + description: Information about the callback execution. + outcome: + allOf: + - $ref: '#/components/schemas/CallbackExecutionOutcome' + description: Only set if the callback is completed and include_outcome was true in the request. + longPollToken: + type: string + description: Token for follow-on long-poll requests. Absent only if the callback is complete. + format: bytes DescribeDeploymentResponse: type: object properties: @@ -10877,6 +11556,8 @@ components: $ref: '#/components/schemas/Link_WorkflowEvent' batchJob: $ref: '#/components/schemas/Link_BatchJob' + callbackExecution: + $ref: '#/components/schemas/Link_CallbackExecution' 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: @@ -10891,6 +11572,12 @@ 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_CallbackExecution: + type: object + properties: + callbackId: + type: string + description: A link to a durable callback execution Link_WorkflowEvent: type: object properties: @@ -10936,6 +11623,17 @@ components: nextPageToken: type: string format: bytes + ListCallbackExecutionsResponse: + type: object + properties: + executions: + type: array + items: + $ref: '#/components/schemas/CallbackExecutionListInfo' + nextPageToken: + type: string + description: Token to use to fetch the next page. If empty, there is no next page. + format: bytes ListDeploymentsResponse: type: object properties: @@ -12062,6 +12760,11 @@ components: description: The run ID of the activity, useful when run_id was not specified in the request. outcome: $ref: '#/components/schemas/ActivityExecutionOutcome' + PollCallbackExecutionResponse: + type: object + properties: + outcome: + $ref: '#/components/schemas/CallbackExecutionOutcome' PollWorkflowTaskQueueResponse: type: object properties: @@ -14306,6 +15009,52 @@ components: StartBatchOperationResponse: type: object properties: {} + StartCallbackExecutionRequest: + type: object + properties: + namespace: + type: string + identity: + type: string + description: The identity of the client who initiated this request. + requestId: + type: string + description: A unique identifier for this start request. Typically UUIDv4. + callbackId: + type: string + description: |- + Identifier for this callback. Required. Must be unique among callbacks in the same namespace. + If a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted. + runId: + type: string + description: Callback execution run ID, targets the latest run if run_id is empty. + callback: + allOf: + - $ref: '#/components/schemas/Callback' + description: Information on how this callback should be invoked (e.g. its URL and type). + 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. --) + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes for indexing. + completion: + allOf: + - $ref: '#/components/schemas/CallbackExecutionCompletion' + description: |- + The Nexus completion data to deliver to the callback URL. + Required. Contains either a successful result payload or a failure. + StartCallbackExecutionResponse: + type: object + properties: + runId: + type: string + description: The run ID of the callback that was started. StartChildWorkflowExecutionFailedEventAttributes: type: object properties: @@ -14925,6 +15674,29 @@ components: TerminateActivityExecutionResponse: type: object properties: {} + TerminateCallbackExecutionRequest: + type: object + properties: + namespace: + type: string + callbackId: + type: string + description: Identifier for the callback + runId: + type: string + description: Run ID of the callback execution to terminate. If empty, the latest run will be terminated. + identity: + type: string + description: The identity of the worker/client. + requestId: + type: string + description: Used to de-dupe termination requests. + reason: + type: string + description: Reason for requesting the termination. + TerminateCallbackExecutionResponse: + type: object + properties: {} TerminateWorkflowExecutionRequest: type: object properties: diff --git a/temporal/api/callback/v1/message.proto b/temporal/api/callback/v1/message.proto new file mode 100644 index 000000000..f720ccbde --- /dev/null +++ b/temporal/api/callback/v1/message.proto @@ -0,0 +1,113 @@ +syntax = "proto3"; + +package temporal.api.callback.v1; + +option go_package = "go.temporal.io/api/callback/v1;callback"; +option java_package = "io.temporal.api.callback.v1"; +option java_multiple_files = true; +option java_outer_classname = "MessageProto"; +option ruby_package = "Temporalio::Api::Callback::V1"; +option csharp_namespace = "Temporalio.Api.Callback.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 completed callback execution: either success or a failure. +message CallbackExecutionOutcome { + oneof value { + // The callback completed successfully. + google.protobuf.Empty success = 1; + // The failure if the callback completed unsuccessfully. + temporal.api.failure.v1.Failure failure = 2; + } +} + +// The Nexus completion data that a standalone callback execution will deliver to its target URL. +// Exactly one of success or failure should be set. +message CallbackExecutionCompletion { + oneof result { + // Deliver a successful Nexus operation completion with this result payload. + // If set, the callback delivers a successful completion to the target URL. + temporal.api.common.v1.Payload success = 1; + // Deliver a failed Nexus operation completion with this failure. + // If set, the callback delivers a failed completion to the target URL. + temporal.api.failure.v1.Failure failure = 2; + } +} + +// Information about a standalone callback execution. +message CallbackExecutionInfo { + // Unique identifier of this callback within its namespace. + string callback_id = 1; + + // Run ID of the callback execution. + string run_id = 2; + + // Information on how this callback should be invoked (e.g. its URL and type). + temporal.api.common.v1.Callback callback = 3; + + // Current state of the callback. + temporal.api.enums.v1.CallbackState state = 4; + + // The number of attempts made to deliver the callback. + // This number represents a minimum bound since the attempt is incremented after the callback request completes. + int32 attempt = 5; + + // The time when the callback was created/scheduled. + google.protobuf.Timestamp create_time = 6; + + // The time when the last attempt completed. + google.protobuf.Timestamp last_attempt_complete_time = 7; + + // The last attempt's failure, if any. + temporal.api.failure.v1.Failure last_attempt_failure = 8; + + // The time when the next attempt is scheduled. + google.protobuf.Timestamp next_attempt_schedule_time = 9; + + // If the state is BLOCKED, provides additional information. + string blocked_reason = 10; + + // Time when the callback transitioned to a terminal state. + google.protobuf.Timestamp close_time = 11; + + // Search attributes for indexing. + temporal.api.common.v1.SearchAttributes search_attributes = 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; +} + +// Limited callback information returned in the list response. +message CallbackExecutionListInfo { + // Unique identifier of this callback within its namespace. + string callback_id = 1; + + // Run ID of the callback execution. + string run_id = 2; + + // Current state of the callback. + temporal.api.enums.v1.CallbackState state = 3; + + // The time when the callback was created/scheduled. + google.protobuf.Timestamp create_time = 4; + + // Time when the callback transitioned to a terminal state. + google.protobuf.Timestamp close_time = 5; + + // Search attributes from the start request. + temporal.api.common.v1.SearchAttributes search_attributes = 6; + + // Incremented each time the callback's state is mutated. + int64 state_transition_count = 7; +} diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 88c3a834e..ea26ba8f3 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -181,6 +181,8 @@ message Callback { string url = 1; // Header to attach to callback request. map header = 2; + // Standard token to use for completion. + string token = 3; } // Callbacks to be delivered internally within the system. @@ -240,9 +242,15 @@ message Link { string job_id = 1; } + // A link to a durable callback execution + message CallbackExecution { + string callback_id = 1; + } + oneof variant { WorkflowEvent workflow_event = 1; BatchJob batch_job = 2; + CallbackExecution callback_execution = 3; } } diff --git a/temporal/api/enums/v1/common.proto b/temporal/api/enums/v1/common.proto index 192c1d75b..7f5d76382 100644 --- a/temporal/api/enums/v1/common.proto +++ b/temporal/api/enums/v1/common.proto @@ -49,6 +49,10 @@ enum CallbackState { CALLBACK_STATE_SUCCEEDED = 5; // Callback is blocked (eg: by circuit breaker). CALLBACK_STATE_BLOCKED = 6; + // Callback was canceled via RequestCancelCallbackExecution. + CALLBACK_STATE_CANCELED = 7; + // Callback was terminated via TerminateCallbackExecution. + CALLBACK_STATE_TERMINATED = 8; } // State of a pending Nexus operation. diff --git a/temporal/api/errordetails/v1/message.proto b/temporal/api/errordetails/v1/message.proto index c01e90e2c..a0f42a7e2 100644 --- a/temporal/api/errordetails/v1/message.proto +++ b/temporal/api/errordetails/v1/message.proto @@ -129,3 +129,9 @@ message ActivityExecutionAlreadyStartedFailure { string start_request_id = 1; string run_id = 2; } + +// An error indicating that a callback execution failed to start because a callback with the given +// callback ID already exists in this namespace. +message CallbackExecutionAlreadyStartedFailure { + string start_request_id = 1; +} diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index 552b75c26..4a688c23e 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -61,6 +61,8 @@ message StartOperationRequest { map callback_header = 6; // Links contain caller information and can be attached to the operations started by the handler. repeated Link links = 7; + // Callback token + string callback_token = 8; } // A request to cancel an operation. diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 540de0a5b..c611b6c8a 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -21,6 +21,7 @@ import "temporal/api/enums/v1/deployment.proto"; import "temporal/api/enums/v1/update.proto"; import "temporal/api/enums/v1/activity.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"; @@ -3055,3 +3056,137 @@ message DeleteActivityExecutionRequest { message DeleteActivityExecutionResponse { } + +message StartCallbackExecutionRequest { + string namespace = 1; + // The identity of the client who initiated this request. + string identity = 2; + // A unique identifier for this start request. Typically UUIDv4. + string request_id = 3; + // Identifier for this callback. Required. Must be unique among callbacks in the same namespace. + // If a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted. + string callback_id = 4; + // Callback execution run ID, targets the latest run if run_id is empty. + string run_id = 5; + // Information on how this callback should be invoked (e.g. its URL and type). + temporal.api.common.v1.Callback callback = 6; + // 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 = 7; + // Search attributes for indexing. + temporal.api.common.v1.SearchAttributes search_attributes = 8; + // The Nexus completion data to deliver to the callback URL. + // Required. Contains either a successful result payload or a failure. + temporal.api.callback.v1.CallbackExecutionCompletion completion = 9; +} + +message StartCallbackExecutionResponse { + // The run ID of the callback that was started. + string run_id = 1; +} + +message DescribeCallbackExecutionRequest { + string namespace = 1; + // Identifier for the callback + string callback_id = 2; + // Run ID of the callback execution to describe. If empty, the latest run will be described. + string run_id = 3; + // Include the outcome (result/failure) in the response if the callback has completed. + bool include_outcome = 4; + // Token from a previous DescribeCallbackExecutionResponse. If present, long-poll until callback + // state changes from the state encoded in this token. If absent, return current state immediately. + // Note that callback state may change multiple times between requests, therefore it is not + // guaranteed that a client making a sequence of long-poll requests will see a complete + // sequence of state changes. + bytes long_poll_token = 5; +} + +message DescribeCallbackExecutionResponse { + // Information about the callback execution. + temporal.api.callback.v1.CallbackExecutionInfo info = 1; + // Only set if the callback is completed and include_outcome was true in the request. + temporal.api.callback.v1.CallbackExecutionOutcome outcome = 2; + // Token for follow-on long-poll requests. Absent only if the callback is complete. + bytes long_poll_token = 3; +} + +message PollCallbackExecutionRequest { + string namespace = 1; + // Identifier for the callback + string callback_id = 2; + // Run ID of the callback execution to poll. If empty, the latest run will be polled. + string run_id = 3; +} + +message PollCallbackExecutionResponse { + temporal.api.callback.v1.CallbackExecutionOutcome outcome = 1; +} + +message ListCallbackExecutionsRequest { + string namespace = 1; + // Max number of executions to return per page. + int32 page_size = 2; + // Token returned in ListCallbackExecutionsResponse. + bytes next_page_token = 3; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + string query = 4; +} + +message ListCallbackExecutionsResponse { + repeated temporal.api.callback.v1.CallbackExecutionListInfo executions = 1; + // Token to use to fetch the next page. If empty, there is no next page. + bytes next_page_token = 2; +} + +message CountCallbackExecutionsRequest { + string namespace = 1; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + string query = 2; +} + +message CountCallbackExecutionsResponse { + // If `query` is not grouping by any field, the count is an approximate number + // of callbacks that match the query. + // If `query` is grouping by a field, the count is simply the sum of the counts + // of the groups returned in the response. This number can be smaller than the + // total number of callbacks matching the query. + int64 count = 1; + + // Contains the groups if the request is grouping by a field. + // The list might not be complete, and the counts of each group is approximate. + repeated AggregationGroup groups = 2; + + message AggregationGroup { + repeated temporal.api.common.v1.Payload group_values = 1; + int64 count = 2; + } +} + +message TerminateCallbackExecutionRequest { + string namespace = 1; + // Identifier for the callback + string callback_id = 2; + // Run ID of the callback execution to terminate. If empty, the latest run will be terminated. + string run_id = 3; + // The identity of the worker/client. + string identity = 4; + // Used to de-dupe termination requests. + string request_id = 5; + // Reason for requesting the termination. + string reason = 6; +} + +message TerminateCallbackExecutionResponse { +} + +message DeleteCallbackExecutionRequest { + string namespace = 1; + // Identifier for the callback + string callback_id = 2; + // Run ID of the callback execution to delete. If empty, the latest run will be deleted. + string run_id = 3; +} + +message DeleteCallbackExecutionResponse { +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 914bbaf83..89c815617 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1740,4 +1740,85 @@ service WorkflowService { // (-- api-linter: core::0127::http-annotation=disabled // aip.dev/not-precedent: Activity deletion not exposed to HTTP, users should use cancel or terminate. --) rpc DeleteActivityExecution (DeleteActivityExecutionRequest) returns (DeleteActivityExecutionResponse) {} + + // StartCallbackExecution starts a new standalone callback execution. + // + // Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same + // callback ID in this namespace. + rpc StartCallbackExecution (StartCallbackExecutionRequest) returns (StartCallbackExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/callbacks/{callback_id}" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/callbacks/{callback_id}" + body: "*" + } + }; + } + + // DescribeCallbackExecution returns information about a callback execution. + // It can be used to: + // - Get current callback info without waiting + // - Long-poll for next state change and return new callback info + // Response can optionally include the outcome (if the callback has completed). + rpc DescribeCallbackExecution (DescribeCallbackExecutionRequest) returns (DescribeCallbackExecutionResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/callbacks/{callback_id}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/callbacks/{callback_id}" + } + }; + } + + // PollCallbackExecution long-polls for a callback execution to complete and returns the outcome. + rpc PollCallbackExecution (PollCallbackExecutionRequest) returns (PollCallbackExecutionResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/callbacks/{callback_id}/outcome" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/callbacks/{callback_id}/outcome" + } + }; + } + + // ListCallbackExecutions is a visibility API to list callback executions in a specific namespace. + rpc ListCallbackExecutions (ListCallbackExecutionsRequest) returns (ListCallbackExecutionsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/callbacks" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/callbacks" + } + }; + } + + // CountCallbackExecutions is a visibility API to count callback executions in a specific namespace. + rpc CountCallbackExecutions (CountCallbackExecutionsRequest) returns (CountCallbackExecutionsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/callback-count" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/callback-count" + } + }; + } + + // TerminateCallbackExecution terminates an existing callback execution immediately. + // + // Termination happens immediately. A terminated callback will have its state set to + // CALLBACK_STATE_TERMINATED. + rpc TerminateCallbackExecution (TerminateCallbackExecutionRequest) returns (TerminateCallbackExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/callbacks/{callback_id}/terminate" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/callbacks/{callback_id}/terminate" + body: "*" + } + }; + } + + // DeleteCallbackExecution asynchronously deletes a callback execution. If the callback is + // running, it will be terminated before deletion. + // + // (-- api-linter: core::0127::http-annotation=disabled + // aip.dev/not-precedent: Callback deletion not exposed to HTTP, users should use cancel or terminate. --) + rpc DeleteCallbackExecution (DeleteCallbackExecutionRequest) returns (DeleteCallbackExecutionResponse) {} } From 7738dd01c3fa03faf150943ee4a4000c9aeebed5 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Fri, 3 Apr 2026 11:15:14 -0700 Subject: [PATCH 2/4] Respond to PR comments --- openapi/openapiv2.json | 61 +++++++++++-------- openapi/openapiv3.yaml | 61 ++++++++----------- temporal/api/callback/v1/message.proto | 9 +-- temporal/api/common/v1/message.proto | 6 -- temporal/api/enums/v1/common.proto | 18 +++++- temporal/api/errordetails/v1/message.proto | 1 + .../workflowservice/v1/request_response.proto | 23 ++++--- temporal/api/workflowservice/v1/service.proto | 2 +- 8 files changed, 96 insertions(+), 85 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index f90e73a3a..dba7e1f2c 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1368,6 +1368,13 @@ "required": false, "type": "string" }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, { "name": "includeOutcome", "description": "Include the outcome (result/failure) in the response if the callback has completed.", @@ -1390,7 +1397,7 @@ }, "post": { "summary": "StartCallbackExecution starts a new standalone callback execution.", - "description": "Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same\ncallback ID in this namespace.", + "description": "Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same\ncallback ID in this namespace, either in running or terminal states.", "operationId": "StartCallbackExecution2", "responses": { "200": { @@ -6425,6 +6432,13 @@ "required": false, "type": "string" }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, { "name": "includeOutcome", "description": "Include the outcome (result/failure) in the response if the callback has completed.", @@ -6447,7 +6461,7 @@ }, "post": { "summary": "StartCallbackExecution starts a new standalone callback execution.", - "description": "Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same\ncallback ID in this namespace.", + "description": "Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same\ncallback ID in this namespace, either in running or terminal states.", "operationId": "StartCallbackExecution", "responses": { "200": { @@ -9747,15 +9761,6 @@ }, "description": "A link to a built-in batch job.\nBatch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).\nThis link can be put on workflow history events generated by actions taken by a batch job." }, - "LinkCallbackExecution": { - "type": "object", - "properties": { - "callbackId": { - "type": "string" - } - }, - "title": "A link to a durable callback execution" - }, "LinkWorkflowEvent": { "type": "object", "properties": { @@ -11092,10 +11097,6 @@ "type": "string", "description": "A unique identifier for this start request. Typically UUIDv4." }, - "runId": { - "type": "string", - "description": "Callback execution run ID, targets the latest run if run_id is empty." - }, "callback": { "$ref": "#/definitions/v1Callback", "description": "Information on how this callback should be invoked (e.g. its URL and type)." @@ -11110,7 +11111,7 @@ }, "completion": { "$ref": "#/definitions/v1CallbackExecutionCompletion", - "description": "The Nexus completion data to deliver to the callback URL.\nRequired. Contains either a successful result payload or a failure." + "description": "The Nexus completion data to deliver to the callback URL.\nContains either a successful result payload or a failure." } } }, @@ -12743,7 +12744,7 @@ }, "failure": { "$ref": "#/definitions/v1Failure", - "description": "Deliver a failed Nexus operation completion with this failure.\nIf set, the callback delivers a failed completion to the target URL." + "description": "Deliver a failed Nexus operation completion with this failure.\nIf set, the callback delivers a failed completion to the target URL.\nIf CanceledFailureInfo is set, the target operation is resolved is canceled instead of failed." } }, "description": "The Nexus completion data that a standalone callback execution will deliver to its target URL.\nExactly one of success or failure should be set." @@ -12764,8 +12765,8 @@ "description": "Information on how this callback should be invoked (e.g. its URL and type)." }, "state": { - "$ref": "#/definitions/v1CallbackState", - "description": "Current state of the callback." + "$ref": "#/definitions/v1CallbackExecutionState", + "description": "Current state of the callback execution." }, "attempt": { "type": "integer", @@ -12828,8 +12829,8 @@ "description": "Run ID of the callback execution." }, "state": { - "$ref": "#/definitions/v1CallbackState", - "description": "Current state of the callback." + "$ref": "#/definitions/v1CallbackExecutionState", + "description": "Current state of the callback execution." }, "createTime": { "type": "string", @@ -12868,6 +12869,18 @@ }, "description": "The outcome of a completed callback execution: either success or a failure." }, + "v1CallbackExecutionState": { + "type": "string", + "enum": [ + "CALLBACK_EXECUTION_STATE_UNSPECIFIED", + "CALLBACK_EXECUTION_STATE_RUNNING", + "CALLBACK_EXECUTION_STATE_SUCCEEDED", + "CALLBACK_EXECUTION_STATE_FAILED", + "CALLBACK_EXECUTION_STATE_TERMINATED" + ], + "default": "CALLBACK_EXECUTION_STATE_UNSPECIFIED", + "description": "Terminal status of a standalone callback execution.\n\n - CALLBACK_EXECUTION_STATE_UNSPECIFIED: Default value, unspecified status.\n - CALLBACK_EXECUTION_STATE_RUNNING: Callback execution is running.\n - CALLBACK_EXECUTION_STATE_SUCCEEDED: Callback has succeeded.\n - CALLBACK_EXECUTION_STATE_FAILED: Callback has failed.\n - CALLBACK_EXECUTION_STATE_TERMINATED: Callback was terminated via TerminateCallbackExecution." + }, "v1CallbackInfo": { "type": "object", "properties": { @@ -12923,11 +12936,10 @@ "CALLBACK_STATE_FAILED", "CALLBACK_STATE_SUCCEEDED", "CALLBACK_STATE_BLOCKED", - "CALLBACK_STATE_CANCELED", "CALLBACK_STATE_TERMINATED" ], "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).\n - CALLBACK_STATE_CANCELED: Callback was canceled via RequestCancelCallbackExecution.\n - CALLBACK_STATE_TERMINATED: Callback was terminated via TerminateCallbackExecution." + "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).\n - CALLBACK_STATE_TERMINATED: Callback was terminated via TerminateCallbackExecution. Only possible for standalone callbacks." }, "v1CancelExternalWorkflowExecutionFailedCause": { "type": "string", @@ -14747,9 +14759,6 @@ }, "batchJob": { "$ref": "#/definitions/LinkBatchJob" - }, - "callbackExecution": { - "$ref": "#/definitions/LinkCallbackExecution" } }, "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." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 334c6976a..3322fe070 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1211,6 +1211,11 @@ paths: description: Run ID of the callback execution to describe. If empty, the latest run will be described. schema: type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean - name: includeOutcome in: query description: Include the outcome (result/failure) in the response if the callback has completed. @@ -1247,7 +1252,7 @@ paths: StartCallbackExecution starts a new standalone callback execution. Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same - callback ID in this namespace. + callback ID in this namespace, either in running or terminal states. operationId: StartCallbackExecution parameters: - name: namespace @@ -5718,6 +5723,11 @@ paths: description: Run ID of the callback execution to describe. If empty, the latest run will be described. schema: type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean - name: includeOutcome in: query description: Include the outcome (result/failure) in the response if the callback has completed. @@ -5754,7 +5764,7 @@ paths: StartCallbackExecution starts a new standalone callback execution. Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same - callback ID in this namespace. + callback ID in this namespace, either in running or terminal states. operationId: StartCallbackExecution parameters: - name: namespace @@ -9570,6 +9580,7 @@ components: description: |- Deliver a failed Nexus operation completion with this failure. If set, the callback delivers a failed completion to the target URL. + If CanceledFailureInfo is set, the target operation is resolved is canceled instead of failed. description: |- The Nexus completion data that a standalone callback execution will deliver to its target URL. Exactly one of success or failure should be set. @@ -9588,17 +9599,13 @@ components: description: Information on how this callback should be invoked (e.g. its URL and type). state: enum: - - CALLBACK_STATE_UNSPECIFIED - - CALLBACK_STATE_STANDBY - - CALLBACK_STATE_SCHEDULED - - CALLBACK_STATE_BACKING_OFF - - CALLBACK_STATE_FAILED - - CALLBACK_STATE_SUCCEEDED - - CALLBACK_STATE_BLOCKED - - CALLBACK_STATE_CANCELED - - CALLBACK_STATE_TERMINATED + - CALLBACK_EXECUTION_STATE_UNSPECIFIED + - CALLBACK_EXECUTION_STATE_RUNNING + - CALLBACK_EXECUTION_STATE_SUCCEEDED + - CALLBACK_EXECUTION_STATE_FAILED + - CALLBACK_EXECUTION_STATE_TERMINATED type: string - description: Current state of the callback. + description: Current state of the callback execution. format: enum attempt: type: integer @@ -9655,17 +9662,13 @@ components: description: Run ID of the callback execution. state: enum: - - CALLBACK_STATE_UNSPECIFIED - - CALLBACK_STATE_STANDBY - - CALLBACK_STATE_SCHEDULED - - CALLBACK_STATE_BACKING_OFF - - CALLBACK_STATE_FAILED - - CALLBACK_STATE_SUCCEEDED - - CALLBACK_STATE_BLOCKED - - CALLBACK_STATE_CANCELED - - CALLBACK_STATE_TERMINATED + - CALLBACK_EXECUTION_STATE_UNSPECIFIED + - CALLBACK_EXECUTION_STATE_RUNNING + - CALLBACK_EXECUTION_STATE_SUCCEEDED + - CALLBACK_EXECUTION_STATE_FAILED + - CALLBACK_EXECUTION_STATE_TERMINATED type: string - description: Current state of the callback. + description: Current state of the callback execution. format: enum createTime: type: string @@ -9715,7 +9718,6 @@ components: - CALLBACK_STATE_FAILED - CALLBACK_STATE_SUCCEEDED - CALLBACK_STATE_BLOCKED - - CALLBACK_STATE_CANCELED - CALLBACK_STATE_TERMINATED type: string format: enum @@ -11556,8 +11558,6 @@ components: $ref: '#/components/schemas/Link_WorkflowEvent' batchJob: $ref: '#/components/schemas/Link_BatchJob' - callbackExecution: - $ref: '#/components/schemas/Link_CallbackExecution' 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: @@ -11572,12 +11572,6 @@ 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_CallbackExecution: - type: object - properties: - callbackId: - type: string - description: A link to a durable callback execution Link_WorkflowEvent: type: object properties: @@ -15025,9 +15019,6 @@ components: description: |- Identifier for this callback. Required. Must be unique among callbacks in the same namespace. If a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted. - runId: - type: string - description: Callback execution run ID, targets the latest run if run_id is empty. callback: allOf: - $ref: '#/components/schemas/Callback' @@ -15048,7 +15039,7 @@ components: - $ref: '#/components/schemas/CallbackExecutionCompletion' description: |- The Nexus completion data to deliver to the callback URL. - Required. Contains either a successful result payload or a failure. + Contains either a successful result payload or a failure. StartCallbackExecutionResponse: type: object properties: diff --git a/temporal/api/callback/v1/message.proto b/temporal/api/callback/v1/message.proto index f720ccbde..020dd3abd 100644 --- a/temporal/api/callback/v1/message.proto +++ b/temporal/api/callback/v1/message.proto @@ -36,6 +36,7 @@ message CallbackExecutionCompletion { temporal.api.common.v1.Payload success = 1; // Deliver a failed Nexus operation completion with this failure. // If set, the callback delivers a failed completion to the target URL. + // If CanceledFailureInfo is set, the target operation is resolved is canceled instead of failed. temporal.api.failure.v1.Failure failure = 2; } } @@ -51,8 +52,8 @@ message CallbackExecutionInfo { // Information on how this callback should be invoked (e.g. its URL and type). temporal.api.common.v1.Callback callback = 3; - // Current state of the callback. - temporal.api.enums.v1.CallbackState state = 4; + // Current state of the callback execution. + temporal.api.enums.v1.CallbackExecutionState state = 4; // The number of attempts made to deliver the callback. // This number represents a minimum bound since the attempt is incremented after the callback request completes. @@ -96,8 +97,8 @@ message CallbackExecutionListInfo { // Run ID of the callback execution. string run_id = 2; - // Current state of the callback. - temporal.api.enums.v1.CallbackState state = 3; + // Current state of the callback execution. + temporal.api.enums.v1.CallbackExecutionState state = 3; // The time when the callback was created/scheduled. google.protobuf.Timestamp create_time = 4; diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index ea26ba8f3..cb6d73e60 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -242,15 +242,9 @@ message Link { string job_id = 1; } - // A link to a durable callback execution - message CallbackExecution { - string callback_id = 1; - } - oneof variant { WorkflowEvent workflow_event = 1; BatchJob batch_job = 2; - CallbackExecution callback_execution = 3; } } diff --git a/temporal/api/enums/v1/common.proto b/temporal/api/enums/v1/common.proto index 7f5d76382..ab2a7d366 100644 --- a/temporal/api/enums/v1/common.proto +++ b/temporal/api/enums/v1/common.proto @@ -49,10 +49,22 @@ enum CallbackState { CALLBACK_STATE_SUCCEEDED = 5; // Callback is blocked (eg: by circuit breaker). CALLBACK_STATE_BLOCKED = 6; - // Callback was canceled via RequestCancelCallbackExecution. - CALLBACK_STATE_CANCELED = 7; + // Callback was terminated via TerminateCallbackExecution. Only possible for standalone callbacks. + CALLBACK_STATE_TERMINATED = 7; +} + +// Terminal status of a standalone callback execution. +enum CallbackExecutionState { + // Default value, unspecified status. + CALLBACK_EXECUTION_STATE_UNSPECIFIED = 0; + // Callback execution is running. + CALLBACK_EXECUTION_STATE_RUNNING = 1; + // Callback has succeeded. + CALLBACK_EXECUTION_STATE_SUCCEEDED = 2; + // Callback has failed. + CALLBACK_EXECUTION_STATE_FAILED = 3; // Callback was terminated via TerminateCallbackExecution. - CALLBACK_STATE_TERMINATED = 8; + CALLBACK_EXECUTION_STATE_TERMINATED = 4; } // State of a pending Nexus operation. diff --git a/temporal/api/errordetails/v1/message.proto b/temporal/api/errordetails/v1/message.proto index a0f42a7e2..28acc809c 100644 --- a/temporal/api/errordetails/v1/message.proto +++ b/temporal/api/errordetails/v1/message.proto @@ -134,4 +134,5 @@ message ActivityExecutionAlreadyStartedFailure { // callback ID already exists in this namespace. message CallbackExecutionAlreadyStartedFailure { string start_request_id = 1; + string run_id = 2; } diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c611b6c8a..7ec4201aa 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3066,19 +3066,20 @@ message StartCallbackExecutionRequest { // Identifier for this callback. Required. Must be unique among callbacks in the same namespace. // If a callback with this ID already exists, the request will fail with CallbackExecutionAlreadyStarted. string callback_id = 4; - // Callback execution run ID, targets the latest run if run_id is empty. - string run_id = 5; // Information on how this callback should be invoked (e.g. its URL and type). - temporal.api.common.v1.Callback callback = 6; + temporal.api.common.v1.Callback callback = 5; // 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 = 7; + google.protobuf.Duration schedule_to_close_timeout = 6; // Search attributes for indexing. - temporal.api.common.v1.SearchAttributes search_attributes = 8; - // The Nexus completion data to deliver to the callback URL. - // Required. Contains either a successful result payload or a failure. - temporal.api.callback.v1.CallbackExecutionCompletion completion = 9; + temporal.api.common.v1.SearchAttributes search_attributes = 7; + // The input data to deliver to the callback URL. + oneof input { + // The Nexus completion data to deliver to the callback URL. + // Contains either a successful result payload or a failure. + temporal.api.callback.v1.CallbackExecutionCompletion completion = 8; + } } message StartCallbackExecutionResponse { @@ -3092,14 +3093,16 @@ message DescribeCallbackExecutionRequest { string callback_id = 2; // Run ID of the callback execution to describe. If empty, the latest run will be described. string run_id = 3; + // Include the input field in the response. + bool include_input = 4; // Include the outcome (result/failure) in the response if the callback has completed. - bool include_outcome = 4; + bool include_outcome = 5; // Token from a previous DescribeCallbackExecutionResponse. If present, long-poll until callback // state changes from the state encoded in this token. If absent, return current state immediately. // Note that callback state may change multiple times between requests, therefore it is not // guaranteed that a client making a sequence of long-poll requests will see a complete // sequence of state changes. - bytes long_poll_token = 5; + bytes long_poll_token = 6; } message DescribeCallbackExecutionResponse { diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 89c815617..4627fd8d3 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1744,7 +1744,7 @@ service WorkflowService { // StartCallbackExecution starts a new standalone callback execution. // // Returns a `CallbackExecutionAlreadyStarted` error if a callback already exists with the same - // callback ID in this namespace. + // callback ID in this namespace, either in running or terminal states. rpc StartCallbackExecution (StartCallbackExecutionRequest) returns (StartCallbackExecutionResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/callbacks/{callback_id}" From 86146a818f7c0d9e90bee699210b1579a74713a9 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Fri, 3 Apr 2026 16:08:30 -0700 Subject: [PATCH 3/4] Respond to PR comments --- temporal/api/callback/v1/message.proto | 32 +++++++++++-------- temporal/api/enums/v1/common.proto | 18 +++++++---- .../workflowservice/v1/request_response.proto | 6 ++-- 3 files changed, 33 insertions(+), 23 deletions(-) diff --git a/temporal/api/callback/v1/message.proto b/temporal/api/callback/v1/message.proto index 020dd3abd..8e2bad345 100644 --- a/temporal/api/callback/v1/message.proto +++ b/temporal/api/callback/v1/message.proto @@ -52,41 +52,44 @@ message CallbackExecutionInfo { // Information on how this callback should be invoked (e.g. its URL and type). temporal.api.common.v1.Callback callback = 3; - // Current state of the callback execution. - temporal.api.enums.v1.CallbackExecutionState state = 4; + // A general status for this callback, indicates whether it is currently running or in one of the terminal statuses. + temporal.api.enums.v1.CallbackExecutionStatus status = 4; + + // The detailed state of this callback, provides more granular information than the general status. + temporal.api.enums.v1.CallbackState state = 5; // The number of attempts made to deliver the callback. // This number represents a minimum bound since the attempt is incremented after the callback request completes. - int32 attempt = 5; + int32 attempt = 6; // The time when the callback was created/scheduled. - google.protobuf.Timestamp create_time = 6; + google.protobuf.Timestamp create_time = 7; // The time when the last attempt completed. - google.protobuf.Timestamp last_attempt_complete_time = 7; + google.protobuf.Timestamp last_attempt_complete_time = 8; // The last attempt's failure, if any. - temporal.api.failure.v1.Failure last_attempt_failure = 8; + temporal.api.failure.v1.Failure last_attempt_failure = 9; // The time when the next attempt is scheduled. - google.protobuf.Timestamp next_attempt_schedule_time = 9; + google.protobuf.Timestamp next_attempt_schedule_time = 10; // If the state is BLOCKED, provides additional information. - string blocked_reason = 10; + string blocked_reason = 11; // Time when the callback transitioned to a terminal state. - google.protobuf.Timestamp close_time = 11; + google.protobuf.Timestamp close_time = 12; // Search attributes for indexing. - temporal.api.common.v1.SearchAttributes search_attributes = 12; + temporal.api.common.v1.SearchAttributes search_attributes = 13; // 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; + google.protobuf.Duration schedule_to_close_timeout = 14; // Incremented each time the callback's state is mutated in persistence. - int64 state_transition_count = 14; + int64 state_transition_count = 15; } // Limited callback information returned in the list response. @@ -97,8 +100,9 @@ message CallbackExecutionListInfo { // Run ID of the callback execution. string run_id = 2; - // Current state of the callback execution. - temporal.api.enums.v1.CallbackExecutionState state = 3; + // Only running and terminal statuses appear here. More detailed information in CallbackExecutionInfo but not + // available in the list response. + temporal.api.enums.v1.CallbackExecutionStatus status = 3; // The time when the callback was created/scheduled. google.protobuf.Timestamp create_time = 4; diff --git a/temporal/api/enums/v1/common.proto b/temporal/api/enums/v1/common.proto index ab2a7d366..c6d1e1779 100644 --- a/temporal/api/enums/v1/common.proto +++ b/temporal/api/enums/v1/common.proto @@ -53,18 +53,22 @@ enum CallbackState { CALLBACK_STATE_TERMINATED = 7; } -// Terminal status of a standalone callback execution. -enum CallbackExecutionState { +// Status of a callback execution. +// The status is updated once, when the callback is originally scheduled, and again when the callback reaches a terminal +// status. +// (-- api-linter: core::0216::synonyms=disabled +// aip.dev/not-precedent: To be consistent with other enums like ActivityExecutionStatus. --) +enum CallbackExecutionStatus { // Default value, unspecified status. - CALLBACK_EXECUTION_STATE_UNSPECIFIED = 0; + CALLBACK_EXECUTION_STATUS_UNSPECIFIED = 0; // Callback execution is running. - CALLBACK_EXECUTION_STATE_RUNNING = 1; + CALLBACK_EXECUTION_STATUS_RUNNING = 1; // Callback has succeeded. - CALLBACK_EXECUTION_STATE_SUCCEEDED = 2; + CALLBACK_EXECUTION_STATUS_SUCCEEDED = 2; // Callback has failed. - CALLBACK_EXECUTION_STATE_FAILED = 3; + CALLBACK_EXECUTION_STATUS_FAILED = 3; // Callback was terminated via TerminateCallbackExecution. - CALLBACK_EXECUTION_STATE_TERMINATED = 4; + CALLBACK_EXECUTION_STATUS_TERMINATED = 4; } // State of a pending Nexus operation. diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 7ec4201aa..35a9564cc 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3122,8 +3122,10 @@ message PollCallbackExecutionRequest { string run_id = 3; } -message PollCallbackExecutionResponse { - temporal.api.callback.v1.CallbackExecutionOutcome outcome = 1; +message PollCallbackExecutionResponse { + // The run ID of the callback, useful when run_id was not specified in the request. + string run_id = 1; + temporal.api.callback.v1.CallbackExecutionOutcome outcome = 2; } message ListCallbackExecutionsRequest { From d4d1e139f1c231dbdf4a1a4a275b19dd8bb84458 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Fri, 3 Apr 2026 19:43:57 -0700 Subject: [PATCH 4/4] rebase and regen --- openapi/openapiv2.json | 34 +++++++++++++++++++------------- openapi/openapiv3.yaml | 44 +++++++++++++++++++++++++++++------------- 2 files changed, 52 insertions(+), 26 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index dba7e1f2c..a7c7df3ce 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -12764,9 +12764,13 @@ "$ref": "#/definitions/v1Callback", "description": "Information on how this callback should be invoked (e.g. its URL and type)." }, + "status": { + "$ref": "#/definitions/v1CallbackExecutionStatus", + "description": "A general status for this callback, indicates whether it is currently running or in one of the terminal statuses." + }, "state": { - "$ref": "#/definitions/v1CallbackExecutionState", - "description": "Current state of the callback execution." + "$ref": "#/definitions/v1CallbackState", + "description": "The detailed state of this callback, provides more granular information than the general status." }, "attempt": { "type": "integer", @@ -12828,9 +12832,9 @@ "type": "string", "description": "Run ID of the callback execution." }, - "state": { - "$ref": "#/definitions/v1CallbackExecutionState", - "description": "Current state of the callback execution." + "status": { + "$ref": "#/definitions/v1CallbackExecutionStatus", + "description": "Only running and terminal statuses appear here. More detailed information in CallbackExecutionInfo but not\navailable in the list response." }, "createTime": { "type": "string", @@ -12869,17 +12873,17 @@ }, "description": "The outcome of a completed callback execution: either success or a failure." }, - "v1CallbackExecutionState": { + "v1CallbackExecutionStatus": { "type": "string", "enum": [ - "CALLBACK_EXECUTION_STATE_UNSPECIFIED", - "CALLBACK_EXECUTION_STATE_RUNNING", - "CALLBACK_EXECUTION_STATE_SUCCEEDED", - "CALLBACK_EXECUTION_STATE_FAILED", - "CALLBACK_EXECUTION_STATE_TERMINATED" + "CALLBACK_EXECUTION_STATUS_UNSPECIFIED", + "CALLBACK_EXECUTION_STATUS_RUNNING", + "CALLBACK_EXECUTION_STATUS_SUCCEEDED", + "CALLBACK_EXECUTION_STATUS_FAILED", + "CALLBACK_EXECUTION_STATUS_TERMINATED" ], - "default": "CALLBACK_EXECUTION_STATE_UNSPECIFIED", - "description": "Terminal status of a standalone callback execution.\n\n - CALLBACK_EXECUTION_STATE_UNSPECIFIED: Default value, unspecified status.\n - CALLBACK_EXECUTION_STATE_RUNNING: Callback execution is running.\n - CALLBACK_EXECUTION_STATE_SUCCEEDED: Callback has succeeded.\n - CALLBACK_EXECUTION_STATE_FAILED: Callback has failed.\n - CALLBACK_EXECUTION_STATE_TERMINATED: Callback was terminated via TerminateCallbackExecution." + "default": "CALLBACK_EXECUTION_STATUS_UNSPECIFIED", + "description": "Status of a callback execution.\nThe status is updated once, when the callback is originally scheduled, and again when the callback reaches a terminal\nstatus.\n\n - CALLBACK_EXECUTION_STATUS_UNSPECIFIED: Default value, unspecified status.\n - CALLBACK_EXECUTION_STATUS_RUNNING: Callback execution is running.\n - CALLBACK_EXECUTION_STATUS_SUCCEEDED: Callback has succeeded.\n - CALLBACK_EXECUTION_STATUS_FAILED: Callback has failed.\n - CALLBACK_EXECUTION_STATUS_TERMINATED: Callback was terminated via TerminateCallbackExecution." }, "v1CallbackInfo": { "type": "object", @@ -15985,6 +15989,10 @@ "v1PollCallbackExecutionResponse": { "type": "object", "properties": { + "runId": { + "type": "string", + "description": "The run ID of the callback, useful when run_id was not specified in the request." + }, "outcome": { "$ref": "#/definitions/v1CallbackExecutionOutcome" } diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 3322fe070..9a7bd3ff1 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -9597,15 +9597,28 @@ components: allOf: - $ref: '#/components/schemas/Callback' description: Information on how this callback should be invoked (e.g. its URL and type). + status: + enum: + - CALLBACK_EXECUTION_STATUS_UNSPECIFIED + - CALLBACK_EXECUTION_STATUS_RUNNING + - CALLBACK_EXECUTION_STATUS_SUCCEEDED + - CALLBACK_EXECUTION_STATUS_FAILED + - CALLBACK_EXECUTION_STATUS_TERMINATED + type: string + description: A general status for this callback, indicates whether it is currently running or in one of the terminal statuses. + format: enum state: enum: - - CALLBACK_EXECUTION_STATE_UNSPECIFIED - - CALLBACK_EXECUTION_STATE_RUNNING - - CALLBACK_EXECUTION_STATE_SUCCEEDED - - CALLBACK_EXECUTION_STATE_FAILED - - CALLBACK_EXECUTION_STATE_TERMINATED + - CALLBACK_STATE_UNSPECIFIED + - CALLBACK_STATE_STANDBY + - CALLBACK_STATE_SCHEDULED + - CALLBACK_STATE_BACKING_OFF + - CALLBACK_STATE_FAILED + - CALLBACK_STATE_SUCCEEDED + - CALLBACK_STATE_BLOCKED + - CALLBACK_STATE_TERMINATED type: string - description: Current state of the callback execution. + description: The detailed state of this callback, provides more granular information than the general status. format: enum attempt: type: integer @@ -9660,15 +9673,17 @@ components: runId: type: string description: Run ID of the callback execution. - state: + status: enum: - - CALLBACK_EXECUTION_STATE_UNSPECIFIED - - CALLBACK_EXECUTION_STATE_RUNNING - - CALLBACK_EXECUTION_STATE_SUCCEEDED - - CALLBACK_EXECUTION_STATE_FAILED - - CALLBACK_EXECUTION_STATE_TERMINATED + - CALLBACK_EXECUTION_STATUS_UNSPECIFIED + - CALLBACK_EXECUTION_STATUS_RUNNING + - CALLBACK_EXECUTION_STATUS_SUCCEEDED + - CALLBACK_EXECUTION_STATUS_FAILED + - CALLBACK_EXECUTION_STATUS_TERMINATED type: string - description: Current state of the callback execution. + description: |- + Only running and terminal statuses appear here. More detailed information in CallbackExecutionInfo but not + available in the list response. format: enum createTime: type: string @@ -12757,6 +12772,9 @@ components: PollCallbackExecutionResponse: type: object properties: + runId: + type: string + description: The run ID of the callback, useful when run_id was not specified in the request. outcome: $ref: '#/components/schemas/CallbackExecutionOutcome' PollWorkflowTaskQueueResponse: