Add Stand Alone Callbacks

Author: Quinn-With-Two-Ns

openapi/openapiv2.json

@@ -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;
+}

openapi/openapiv3.yaml

@@ -181,6 +181,8 @@ message Callback {
         string url = 1;
         // Header to attach to callback request.
         map<string, string> 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;
     }
 }
 

temporal/api/callback/v1/message.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.

temporal/api/common/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;
+}

temporal/api/enums/v1/common.proto

@@ -61,6 +61,8 @@ message StartOperationRequest {
     map<string, string> 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.

temporal/api/errordetails/v1/message.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";
@@ -2956,3 +2957,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 {
+}