Make Go error details more accessible (#986)

- Add Details() method to transaction errors.
- Include error details in Error() message.
- Add Unwrap() methods to specific transaction errors so the underlying
  TransactionError can be retrieved without knowing the specific error
  type, to provide easier access to TransactionID and Details().
- Change Java stack trace to use similar YAML-like format as Go error
  details.
- Update minor version to 1.10.

Signed-off-by: Mark S. Lewis <[email protected]>

Author: bestbeforetoday

.github/workflows/verify-versions.yml

@@ -7,7 +7,7 @@ permissions:
   contents: read
 
 env:
-  GATEWAY_VERSION: 1.9.1
+  GATEWAY_VERSION: 1.10.0
 
 jobs:
   go:

java/pom.xml

@@ -7,7 +7,7 @@
 
     <groupId>org.hyperledger.fabric</groupId>
     <artifactId>fabric-gateway</artifactId>
-    <version>1.9.1-SNAPSHOT</version>
+    <version>1.10.0-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <name>fabric-gateway</name>

java/src/main/java/org/hyperledger/fabric/client/GrpcStackTracePrinter.java

@@ -38,16 +38,16 @@ public void printStackTrace(final PrintWriter out) {
 
         List<ErrorDetail> details = grpcStatus.getDetails();
         if (!details.isEmpty()) {
-            message.append("Error details:\n");
+            message.append("Error details:");
             for (ErrorDetail detail : details) {
-                message.append("    address: ")
+                message.append("\n  - address: ")
                         .append(detail.getAddress())
-                        .append("; mspId: ")
+                        .append("\n    mspId: ")
                         .append(detail.getMspId())
-                        .append("; message: ")
-                        .append(detail.getMessage())
-                        .append('\n');
+                        .append("\n    message: ")
+                        .append(detail.getMessage());
             }
+            message.append('\n');
         }
 
         out.print(message);

node/package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@hyperledger/fabric-gateway",
-    "version": "1.9.1",
+    "version": "1.10.0",
     "description": "Hyperledger Fabric Gateway client API for Node",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

node/package.json

@@ -5,7 +5,9 @@ package client
 
 import (
 	"fmt"
+	"strings"
 
+	"github.com/hyperledger/fabric-protos-go-apiv2/gateway"
 	"github.com/hyperledger/fabric-protos-go-apiv2/peer"
 	"google.golang.org/grpc/status"
 )
@@ -28,32 +30,98 @@ func newTransactionError(err error, transactionID string) *TransactionError {
 	}
 
 	return &TransactionError{
-		grpcError:     &grpcError{err},
+		grpcError:     grpcError{err},
 		TransactionID: transactionID,
 	}
 }
 
+func (e *grpcError) Details() []*gateway.ErrorDetail {
+	var results []*gateway.ErrorDetail
+
+	for _, detail := range e.GRPCStatus().Details() {
+		switch detail := detail.(type) {
+		case *gateway.ErrorDetail:
+			results = append(results, detail)
+		}
+	}
+
+	return results
+}
+
 // TransactionError represents an error invoking a transaction. This is a gRPC [status] error.
 type TransactionError struct {
-	*grpcError
+	grpcError
 	TransactionID string
 }
 
+// Error message including attached details.
+func (e *TransactionError) Error() string {
+	var result strings.Builder
+	result.WriteString(e.grpcError.Error())
+
+	details := e.Details()
+	if len(details) == 0 {
+		return result.String()
+	}
+
+	result.WriteString("\nDetails:")
+	for _, detail := range details {
+		result.WriteString("\n  - Address: ")
+		result.WriteString(detail.GetAddress())
+		result.WriteString("\n    MspId: ")
+		result.WriteString(detail.GetMspId())
+		result.WriteString("\n    Message: ")
+		result.WriteString(detail.GetMessage())
+	}
+
+	return result.String()
+}
+
 // EndorseError represents a failure endorsing a transaction proposal.
 type EndorseError struct {
 	*TransactionError
 }
 
+// Error message including attached details.
+func (e *EndorseError) Error() string {
+	return fmt.Sprintf("endorse error: %s", e.TransactionError)
+}
+
+// Unwrap the next error in the error chain
+func (e *EndorseError) Unwrap() error {
+	return e.TransactionError
+}
+
 // SubmitError represents a failure submitting an endorsed transaction to the orderer.
 type SubmitError struct {
 	*TransactionError
 }
 
+// Error message including attached details.
+func (e *SubmitError) Error() string {
+	return fmt.Sprintf("submit error: %s", e.TransactionError)
+}
+
+// Unwrap the next error in the error chain
+func (e *SubmitError) Unwrap() error {
+	return e.TransactionError
+}
+
 // CommitStatusError represents a failure obtaining the commit status of a transaction.
 type CommitStatusError struct {
 	*TransactionError
 }
 
+// Error message including attached details.
+func (e *CommitStatusError) Error() string {
+	return fmt.Sprintf("commit status error: %s", e.TransactionError)
+}
+
+// Unwrap the next error in the error chain
+func (e *CommitStatusError) Unwrap() error {
+	return e.TransactionError
+}
+
 func newCommitError(transactionID string, code peer.TxValidationCode) error {
 	return &CommitError{
 		message:       fmt.Sprintf("transaction %s failed to commit with status code %d (%s)", transactionID, int32(code), peer.TxValidationCode_name[int32(code)]),

pkg/client/errors.go

@@ -0,0 +1,153 @@
+// Copyright IBM Corp. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package client
+
+import (
+	"testing"
+
+	"github.com/hyperledger/fabric-protos-go-apiv2/gateway"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+	"google.golang.org/protobuf/protoadapt"
+)
+
+func newGrpcStatus(code codes.Code, message string, details ...*gateway.ErrorDetail) (*status.Status, error) {
+	result := status.New(code, message)
+	if len(details) == 0 {
+		return result, nil
+	}
+
+	var v1Details []protoadapt.MessageV1
+	for _, detail := range details {
+		v1Details = append(v1Details, protoadapt.MessageV1Of(detail))
+	}
+
+	resultWithDetails, err := result.WithDetails(v1Details...)
+	if err != nil {
+		return nil, err
+	}
+
+	return resultWithDetails, nil
+}
+
+func TestErrors(t *testing.T) {
+	for typeName, newInstance := range map[string](func(*TransactionError) error){
+		"endorse error": func(txErr *TransactionError) error {
+			return &EndorseError{txErr}
+		},
+		"submit error": func(txErr *TransactionError) error {
+			return &SubmitError{txErr}
+		},
+		"commit status error": func(txErr *TransactionError) error {
+			return &CommitStatusError{txErr}
+		},
+	} {
+		t.Run(typeName+" with details", func(t *testing.T) {
+			details := []*gateway.ErrorDetail{
+				{
+					Address: "ADDRESS_1",
+					MspId:   "MSP_ID_1",
+					Message: "MESSAGE_1",
+				},
+				{
+					Address: "ADDRESS_2",
+					MspId:   "MSP_ID_2",
+					Message: "MESSAGE_2",
+				},
+			}
+			grpcStatus, err := newGrpcStatus(codes.Aborted, "STATUS_MESSAGE", details...)
+			require.NoError(t, err)
+
+			transactionErr := newTransactionError(grpcStatus.Err(), "TRANSACTION_ID")
+			actualErr := newInstance(transactionErr)
+
+			t.Run("Error", func(t *testing.T) {
+				require.ErrorContains(t, actualErr, grpcStatus.Err().Error())
+				require.ErrorContains(t, actualErr, typeName)
+				for _, detail := range details {
+					require.ErrorContains(t, actualErr, detail.GetAddress())
+					require.ErrorContains(t, actualErr, detail.GetMspId())
+					require.ErrorContains(t, actualErr, detail.GetMessage())
+				}
+			})
+
+			t.Run("Details", func(t *testing.T) {
+				expectedErr := new(TransactionError)
+				require.ErrorAs(t, actualErr, &expectedErr)
+
+				require.Len(t, expectedErr.Details(), len(details), "number of detail messages")
+				for i, actual := range expectedErr.Details() {
+					expected := details[i]
+					AssertProtoEqual(t, expected, actual)
+				}
+			})
+		})
+
+		t.Run(typeName+" without details", func(t *testing.T) {
+			grpcStatus, err := newGrpcStatus(codes.Aborted, "STATUS_MESSAGE")
+			require.NoError(t, err)
+
+			transactionErr := newTransactionError(grpcStatus.Err(), "TRANSACTION_ID")
+			actualErr := newInstance(transactionErr)
+
+			t.Run("Error", func(t *testing.T) {
+				require.ErrorContains(t, actualErr, grpcStatus.Err().Error())
+				require.ErrorContains(t, actualErr, typeName)
+			})
+
+			t.Run("TransactionID", func(t *testing.T) {
+				var actualTransactionErr *TransactionError
+				require.ErrorAs(t, actualErr, &actualTransactionErr)
+
+				require.Equal(t, transactionErr.TransactionID, actualTransactionErr.TransactionID)
+			})
+
+			t.Run("Details", func(t *testing.T) {
+				var actualTransactionErr *TransactionError
+				require.ErrorAs(t, actualErr, &actualTransactionErr)
+
+				require.Empty(t, actualTransactionErr.Details())
+			})
+		})
+	}
+
+	t.Run("Consistent behavior", func(t *testing.T) {
+		grpcStatus, err := newGrpcStatus(codes.Aborted, "STATUS_MESSAGE")
+		require.NoError(t, err)
+
+		transactionErr := newTransactionError(grpcStatus.Err(), "TRANSACTION_ID")
+
+		t.Run("EndorseError", func(t *testing.T) {
+			actualErr := &EndorseError{transactionErr}
+
+			var endorseErr *EndorseError
+			require.ErrorAs(t, actualErr, &endorseErr)
+
+			assert.Equal(t, transactionErr.TransactionID, endorseErr.TransactionID)
+			assert.Empty(t, endorseErr.Details())
+		})
+
+		t.Run("SubmitError", func(t *testing.T) {
+			actualErr := &SubmitError{transactionErr}
+
+			var submitErr *SubmitError
+			require.ErrorAs(t, actualErr, &submitErr)
+
+			assert.Equal(t, transactionErr.TransactionID, submitErr.TransactionID)
+			assert.Empty(t, submitErr.Details())
+		})
+
+		t.Run("CommitStatusError", func(t *testing.T) {
+			actualErr := &CommitStatusError{transactionErr}
+
+			var commitStatusErr *CommitStatusError
+			require.ErrorAs(t, actualErr, &commitStatusErr)
+
+			assert.Equal(t, transactionErr.TransactionID, commitStatusErr.TransactionID)
+			assert.Empty(t, commitStatusErr.Details())
+		})
+	})
+}