Use Temporal Failures for Nexus APIs

Also add a failure representation of the Nexus SDK's OperationError.

Author: bergundy

openapi/openapiv2.json

@@ -9131,6 +9131,9 @@
         },
         "nexusHandlerFailureInfo": {
           "$ref": "#/definitions/v1NexusHandlerFailureInfo"
+        },
+        "nexusSdkOperationFailureInfo": {
+          "$ref": "#/definitions/v1NexusSDKOperationFailureInfo"
         }
       }
     },
@@ -9181,6 +9184,9 @@
           "format": "date-time",
           "description": "The timestamp when the request was scheduled in the frontend."
         },
+        "capabilities": {
+          "$ref": "#/definitions/v1RequestCapabilities"
+        },
         "startOperation": {
           "$ref": "#/definitions/v1StartOperationRequest"
         },
@@ -12579,7 +12585,8 @@
           "type": "string",
           "description": "Operation token - may be empty if the operation completed synchronously."
         }
-      }
+      },
+      "description": "Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers."
     },
     "v1NexusOperationScheduledEventAttributes": {
       "type": "object",
@@ -12669,6 +12676,15 @@
       },
       "description": "Nexus operation timed out."
     },
+    "v1NexusSDKOperationFailureInfo": {
+      "type": "object",
+      "properties": {
+        "state": {
+          "type": "string"
+        }
+      },
+      "description": "Representation of the Nexus SDK OperationError object."
+    },
     "v1OnConflictOptions": {
       "type": "object",
       "properties": {
@@ -13635,6 +13651,15 @@
     "v1RequestCancelWorkflowExecutionResponse": {
       "type": "object"
     },
+    "v1RequestCapabilities": {
+      "type": "object",
+      "properties": {
+        "temporalFailureResponses": {
+          "type": "boolean",
+          "description": "If set, handlers may use temporal.api.failure.v1.Failure instances to return failures to the server.\nThis also allows handler and operation errors to have their own messages and stack traces."
+        }
+      }
+    },
     "v1RequestIdInfo": {
       "type": "object",
       "properties": {
@@ -14849,6 +14874,10 @@
         "operationError": {
           "$ref": "#/definitions/v1UnsuccessfulOperationError",
           "description": "The operation completed unsuccessfully (failed or canceled)."
+        },
+        "failure": {
+          "$ref": "#/definitions/apifailurev1Failure",
+          "description": "The operation completed unsuccessfully (failed or canceled).\nFailure object must contain a NexusSDKOperationFailureInfo object."
         }
       },
       "description": "Response variant for StartOperationRequest."

openapi/openapiv3.yaml

@@ -8261,6 +8261,8 @@ components:
           $ref: '#/components/schemas/NexusOperationFailureInfo'
         nexusHandlerFailureInfo:
           $ref: '#/components/schemas/NexusHandlerFailureInfo'
+        nexusSdkOperationFailureInfo:
+          $ref: '#/components/schemas/NexusSDKOperationFailureInfo'
     FetchWorkerConfigRequest:
       type: object
       properties:
@@ -9383,6 +9385,7 @@ components:
         operationToken:
           type: string
           description: Operation token - may be empty if the operation completed synchronously.
+      description: Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers.
     NexusOperationScheduledEventAttributes:
       type: object
       properties:
@@ -9474,6 +9477,12 @@ components:
           type: string
           description: The request ID allocated at schedule time.
       description: Nexus operation timed out.
+    NexusSDKOperationFailureInfo:
+      type: object
+      properties:
+        state:
+          type: string
+      description: Representation of the Nexus SDK OperationError object.
     OnConflictOptions:
       type: object
       properties:

temporal/api/failure/v1/message.proto

@@ -66,6 +66,7 @@ message ChildWorkflowExecutionFailureInfo {
     temporal.api.enums.v1.RetryState retry_state = 6;
 }
 
+// Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers.
 message NexusOperationFailureInfo {
     // The NexusOperationScheduled event ID.
     int64 scheduled_event_id = 1;
@@ -91,6 +92,11 @@ message NexusHandlerFailureInfo {
     temporal.api.enums.v1.NexusHandlerErrorRetryBehavior retry_behavior = 2;
 }
 
+// Representation of the Nexus SDK OperationError object.
+message NexusSDKOperationFailureInfo {
+    string state = 1;
+}
+
 message Failure {
     string message = 1;
     // The source this Failure originated in, e.g. TypeScriptSDK / JavaSDK
@@ -125,6 +131,7 @@ message Failure {
         ChildWorkflowExecutionFailureInfo child_workflow_execution_failure_info = 12;
         NexusOperationFailureInfo nexus_operation_execution_failure_info = 13;
         NexusHandlerFailureInfo nexus_handler_failure_info = 14;
+        NexusSDKOperationFailureInfo nexus_sdk_operation_failure_info = 15;
     }
 }
 

temporal/api/nexus/v1/message.proto

@@ -12,6 +12,7 @@ option csharp_namespace = "Temporalio.Api.Nexus.V1";
 import "google/protobuf/timestamp.proto";
 import "temporal/api/common/v1/message.proto";
 import "temporal/api/enums/v1/nexus.proto";
+import "temporal/api/failure/v1/message.proto";
 
 // A general purpose failure message.
 // See: https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure
@@ -77,6 +78,12 @@ message CancelOperationRequest {
 
 // A Nexus request.
 message Request {
+    message Capabilities {
+        // If set, handlers may use temporal.api.failure.v1.Failure instances to return failures to the server.
+        // This also allows handler and operation errors to have their own messages and stack traces.
+        bool temporal_failure_responses = 1;
+    }
+
     // Headers extracted from the original request in the Temporal frontend.
     // When using Nexus over HTTP, this includes the request's HTTP headers ignoring multiple values.
     map<string, string> header = 1;
@@ -86,6 +93,8 @@ message Request {
     //     aip.dev/not-precedent: Not following linter rules. --)
     google.protobuf.Timestamp scheduled_time = 2;
 
+    Capabilities capabilities = 100;
+
     oneof variant {
         StartOperationRequest start_operation = 3;
         CancelOperationRequest cancel_operation = 4;
@@ -114,6 +123,9 @@ message StartOperationResponse {
         Async async_success = 2;
         // The operation completed unsuccessfully (failed or canceled).
         UnsuccessfulOperationError operation_error = 3;
+        // The operation completed unsuccessfully (failed or canceled).
+        // Failure object must contain a NexusSDKOperationFailureInfo object.
+        temporal.api.failure.v1.Failure failure = 4;
     }
 }
 

temporal/api/workflowservice/v1/request_response.proto

@@ -1834,8 +1834,10 @@ message RespondNexusTaskFailedRequest {
     string identity = 2;
     // A unique identifier for this task.
     bytes task_token = 3;
-    // The error the handler failed with.
+    // The error the handler failed with (DEPRECATED, use the failure field instead).
     temporal.api.nexus.v1.HandlerError error = 4;
+    // The error the handler failed with. Must contain a NexusHandlerFailureInfo object.
+    temporal.api.failure.v1.Failure failure = 5;
 }
 
 message RespondNexusTaskFailedResponse {
@@ -2550,4 +2552,4 @@ message DescribeWorkerRequest {
 
 message DescribeWorkerResponse {
     temporal.api.worker.v1.WorkerInfo worker_info = 1;
-}
+}