Use Temporal failures in Nexus APIs

openapi/openapiv2.json

@@ -10067,6 +10067,12 @@
         },
         "nexusHandlerFailureInfo": {
           "$ref": "#/definitions/v1NexusHandlerFailureInfo"
+        },
+        "nexusSdkOperationFailureInfo": {
+          "$ref": "#/definitions/v1NexusSDKOperationFailureInfo"
+        },
+        "nexusSdkFailureErrorInfo": {
+          "$ref": "#/definitions/v1NexusSDKFailureErrorFailureInfo"
         }
       }
     },
@@ -13464,7 +13470,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",
@@ -13562,6 +13569,31 @@
       },
       "description": "Nexus operation timed out."
     },
+    "v1NexusSDKFailureErrorFailureInfo": {
+      "type": "object",
+      "properties": {
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "data": {
+          "type": "string",
+          "format": "byte"
+        }
+      },
+      "description": "Representation of the Nexus SDK FailureError object."
+    },
+    "v1NexusSDKOperationFailureInfo": {
+      "type": "object",
+      "properties": {
+        "state": {
+          "type": "string"
+        }
+      },
+      "description": "Representation of the Nexus SDK OperationError object."
+    },
     "v1OnConflictOptions": {
       "type": "object",
       "properties": {

openapi/openapiv3.yaml

@@ -9350,6 +9350,10 @@ components:
           $ref: '#/components/schemas/NexusOperationFailureInfo'
         nexusHandlerFailureInfo:
           $ref: '#/components/schemas/NexusHandlerFailureInfo'
+        nexusSdkOperationFailureInfo:
+          $ref: '#/components/schemas/NexusSDKOperationFailureInfo'
+        nexusSdkFailureErrorInfo:
+          $ref: '#/components/schemas/NexusSDKFailureErrorFailureInfo'
     FetchWorkerConfigRequest:
       type: object
       properties:
@@ -10526,6 +10530,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:
@@ -10633,6 +10638,23 @@ components:
           type: string
           description: The request ID allocated at schedule time.
       description: Nexus operation timed out.
+    NexusSDKFailureErrorFailureInfo:
+      type: object
+      properties:
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+        data:
+          type: string
+          format: bytes
+      description: Representation of the Nexus SDK FailureError object.
+    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,17 @@ message NexusHandlerFailureInfo {
     temporal.api.enums.v1.NexusHandlerErrorRetryBehavior retry_behavior = 2;
 }
 
+// Representation of the Nexus SDK OperationError object.
+message NexusSDKOperationFailureInfo {
+    string state = 1;
+}
+
+// Representation of the Nexus SDK FailureError object.
+message NexusSDKFailureErrorFailureInfo {
+    map<string, string> metadata = 1;
+    bytes data = 2;
+}
+
 message Failure {
     string message = 1;
     // The source this Failure originated in, e.g. TypeScriptSDK / JavaSDK
@@ -125,6 +137,8 @@ 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;
+        NexusSDKFailureErrorFailureInfo nexus_sdk_failure_error_info = 16;
     }
 }
 

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;
@@ -118,6 +127,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

@@ -1837,8 +1837,10 @@ message RespondNexusTaskFailedRequest {
     string identity = 2;
     // A unique identifier for this task.
     bytes task_token = 3;
-    // The error the handler failed with.
-    temporal.api.nexus.v1.HandlerError error = 4;
+    // Deprecated. Use the failure field instead.
+    temporal.api.nexus.v1.HandlerError error = 4 [deprecated = true];
+    // The error the handler failed with. Must contain a NexusHandlerFailureInfo object.
+    temporal.api.failure.v1.Failure failure = 5;
 }
 
 message RespondNexusTaskFailedResponse {