Use Temporal failures in Nexus APIs (#682)

**What changed?**
Use Temporal failures for sending Nexus response errors.

**Why?**
Consistency with other Temporal APIs and compatibility with encryption proxies.

**Breaking changes**
Not explicitly, but server and SDK will need to be able to handle both
error formats based on `capabilities` field.

**Server PR**
temporalio/temporal#8799

---------

Co-authored-by: Roey Berman <roey.berman@gmail.com>

Author: pdoerner

Makefile

@@ -81,7 +81,8 @@ grpc-install:
 	@go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
 	@go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
 	@go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest
-	@go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
+	# v2.27.8 errors with --openapiv2_out: can't resolve OpenAPI name from ".temporal.api.protocol.v1.Message"
+	@go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@v2.27.7
 	@go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest
 	@go install github.com/mikefarah/yq/v4@latest
 

openapi/openapiv2.json

@@ -13658,7 +13658,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",

openapi/openapiv3.yaml

@@ -10705,6 +10705,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:

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;

temporal/api/nexus/v1/message.proto

@@ -12,14 +12,17 @@ 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
 message Failure {
     string message = 1;
+    string stack_trace = 4;
     map<string, string> metadata = 2;
     // UTF-8 encoded JSON serializable details.
     bytes details = 3;
+    Failure cause = 5;
 }
 
 message HandlerError {
@@ -77,6 +80,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 +95,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;
@@ -117,7 +128,11 @@ message StartOperationResponse {
         Sync sync_success = 1;
         Async async_success = 2;
         // The operation completed unsuccessfully (failed or canceled).
-        UnsuccessfulOperationError operation_error = 3;
+        // Deprecated. Use the failure variant instead.
+        UnsuccessfulOperationError operation_error = 3 [deprecated = true];
+        // The operation completed unsuccessfully (failed or canceled).
+        // Failure object must contain an ApplicationFailureInfo or CanceledFailureInfo object.
+        temporal.api.failure.v1.Failure failure = 4;
     }
 }
 

temporal/api/workflowservice/v1/request_response.proto

@@ -1885,8 +1885,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 {