GODRIVER-1802 add ServerError interface (#549)

Author: iwysiu

mongo/doc.go

@@ -70,6 +70,13 @@
 // Additional examples can be found under the examples directory in the driver's repository and
 // on the MongoDB website.
 //
+// Error Handling
+//
+// Errors from the MongoDB server will implement the ServerError interface, which has functions to check for specific
+// error codes, labels, and message substrings. These can be used to check for and handle specific errors. Some methods,
+// like InsertMany and BulkWrite, can return an error representing multiple errors, and in those cases the ServerError
+// functions will return true if any of the contained errors satisfy the check.
+//
 // Potential DNS Issues
 //
 // Building with Go 1.11+ and using connection strings with the "mongodb+srv"[1] scheme is

mongo/errors.go

@@ -10,6 +10,7 @@ import (
 	"bytes"
 	"errors"
 	"fmt"
+	"strings"
 
 	"go.mongodb.org/mongo-driver/bson"
 	"go.mongodb.org/mongo-driver/x/mongo/driver"
@@ -112,6 +113,26 @@ func (e MongocryptdError) Unwrap() error {
 	return e.Wrapped
 }
 
+// ServerError is the interface implemented by errors returned from the server. Custom implementations of this
+// interface should not be used in production.
+type ServerError interface {
+	error
+	// HasErrorCode returns true if the error has the specified code.
+	HasErrorCode(int) bool
+	// HasErrorLabel returns true if the error contains the specified label.
+	HasErrorLabel(string) bool
+	// HasErrorMessage returns true if the error contains the specified message.
+	HasErrorMessage(string) bool
+	// HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message.
+	HasErrorCodeWithMessage(int, string) bool
+
+	serverError()
+}
+
+var _ ServerError = CommandError{}
+var _ ServerError = WriteException{}
+var _ ServerError = BulkWriteException{}
+
 // CommandError represents a server error during execution of a command. This can be returned by any operation.
 type CommandError struct {
 	Code    int32
@@ -134,6 +155,11 @@ func (e CommandError) Unwrap() error {
 	return e.Wrapped
 }
 
+// HasErrorCode returns true if the error has the specified code.
+func (e CommandError) HasErrorCode(code int) bool {
+	return int(e.Code) == code
+}
+
 // HasErrorLabel returns true if the error contains the specified label.
 func (e CommandError) HasErrorLabel(label string) bool {
 	if e.Labels != nil {
@@ -146,11 +172,24 @@ func (e CommandError) HasErrorLabel(label string) bool {
 	return false
 }
 
+// HasErrorMessage returns true if the error contains the specified message.
+func (e CommandError) HasErrorMessage(message string) bool {
+	return strings.Contains(e.Message, message)
+}
+
+// HasErrorCodeWithMessage returns true if the error has the specified code and Message contains the specified message.
+func (e CommandError) HasErrorCodeWithMessage(code int, message string) bool {
+	return int(e.Code) == code && strings.Contains(e.Message, message)
+}
+
 // IsMaxTimeMSExpiredError returns true if the error is a MaxTimeMSExpired error.
 func (e CommandError) IsMaxTimeMSExpiredError() bool {
 	return e.Code == 50 || e.Name == "MaxTimeMSExpired"
 }
 
+// serverError implements the ServerError interface.
+func (e CommandError) serverError() {}
+
 // WriteError is an error that occurred during execution of a write operation. This error type is only returned as part
 // of a WriteException or BulkWriteException.
 type WriteError struct {
@@ -227,6 +266,19 @@ func (mwe WriteException) Error() string {
 	return buf.String()
 }
 
+// HasErrorCode returns true if the error has the specified code.
+func (mwe WriteException) HasErrorCode(code int) bool {
+	if mwe.WriteConcernError != nil && mwe.WriteConcernError.Code == code {
+		return true
+	}
+	for _, we := range mwe.WriteErrors {
+		if we.Code == code {
+			return true
+		}
+	}
+	return false
+}
+
 // HasErrorLabel returns true if the error contains the specified label.
 func (mwe WriteException) HasErrorLabel(label string) bool {
 	if mwe.Labels != nil {
@@ -239,6 +291,36 @@ func (mwe WriteException) HasErrorLabel(label string) bool {
 	return false
 }
 
+// HasErrorMessage returns true if the error contains the specified message.
+func (mwe WriteException) HasErrorMessage(message string) bool {
+	if mwe.WriteConcernError != nil && strings.Contains(mwe.WriteConcernError.Message, message) {
+		return true
+	}
+	for _, we := range mwe.WriteErrors {
+		if strings.Contains(we.Message, message) {
+			return true
+		}
+	}
+	return false
+}
+
+// HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message.
+func (mwe WriteException) HasErrorCodeWithMessage(code int, message string) bool {
+	if mwe.WriteConcernError != nil &&
+		mwe.WriteConcernError.Code == code && strings.Contains(mwe.WriteConcernError.Message, message) {
+		return true
+	}
+	for _, we := range mwe.WriteErrors {
+		if we.Code == code && strings.Contains(we.Message, message) {
+			return true
+		}
+	}
+	return false
+}
+
+// serverError implements the ServerError interface.
+func (mwe WriteException) serverError() {}
+
 func convertDriverWriteConcernError(wce *driver.WriteConcernError) *WriteConcernError {
 	if wce == nil {
 		return nil
@@ -287,6 +369,19 @@ func (bwe BulkWriteException) Error() string {
 	return buf.String()
 }
 
+// HasErrorCode returns true if any of the errors have the specified code.
+func (bwe BulkWriteException) HasErrorCode(code int) bool {
+	if bwe.WriteConcernError != nil && bwe.WriteConcernError.Code == code {
+		return true
+	}
+	for _, we := range bwe.WriteErrors {
+		if we.Code == code {
+			return true
+		}
+	}
+	return false
+}
+
 // HasErrorLabel returns true if the error contains the specified label.
 func (bwe BulkWriteException) HasErrorLabel(label string) bool {
 	if bwe.Labels != nil {
@@ -299,6 +394,36 @@ func (bwe BulkWriteException) HasErrorLabel(label string) bool {
 	return false
 }
 
+// HasErrorMessage returns true if the error contains the specified message.
+func (bwe BulkWriteException) HasErrorMessage(message string) bool {
+	if bwe.WriteConcernError != nil && strings.Contains(bwe.WriteConcernError.Message, message) {
+		return true
+	}
+	for _, we := range bwe.WriteErrors {
+		if strings.Contains(we.Message, message) {
+			return true
+		}
+	}
+	return false
+}
+
+// HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message.
+func (bwe BulkWriteException) HasErrorCodeWithMessage(code int, message string) bool {
+	if bwe.WriteConcernError != nil &&
+		bwe.WriteConcernError.Code == code && strings.Contains(bwe.WriteConcernError.Message, message) {
+		return true
+	}
+	for _, we := range bwe.WriteErrors {
+		if we.Code == code && strings.Contains(we.Message, message) {
+			return true
+		}
+	}
+	return false
+}
+
+// serverError implements the ServerError interface.
+func (bwe BulkWriteException) serverError() {}
+
 // returnResult is used to determine if a function calling processWriteError should return
 // the result or return nil. Since the processWriteError function is used by many different
 // methods, both *One and *Many, we need a way to differentiate if the method should return

mongo/integration/errors_test.go

@@ -107,4 +107,186 @@ func TestErrors(t *testing.T) {
 			assert.True(mt, netErr.Timeout(), "expected error %v to be a network timeout", err)
 		})
 	})
+	mt.Run("ServerError", func(mt *mtest.T) {
+		matchWrapped := errors.New("wrapped err")
+		otherWrapped := errors.New("other err")
+		const matchCode = 100
+		const otherCode = 120
+		const label = "testError"
+		testCases := []struct {
+			name               string
+			err                mongo.ServerError
+			hasCode            bool
+			hasLabel           bool
+			hasMessage         bool
+			hasCodeWithMessage bool
+			isResult           bool
+		}{
+			{
+				"CommandError all true",
+				mongo.CommandError{matchCode, "foo", []string{label}, "name", matchWrapped},
+				true,
+				true,
+				true,
+				true,
+				true,
+			},
+			{
+				"CommandError all false",
+				mongo.CommandError{otherCode, "bar", []string{"otherError"}, "name", otherWrapped},
+				false,
+				false,
+				false,
+				false,
+				false,
+			},
+			{
+				"CommandError has code not message",
+				mongo.CommandError{matchCode, "bar", []string{}, "name", nil},
+				true,
+				false,
+				false,
+				false,
+				false,
+			},
+			{
+				"WriteException all in writeConcernError",
+				mongo.WriteException{
+					&mongo.WriteConcernError{"name", matchCode, "foo", nil},
+					nil,
+					[]string{label},
+				},
+				true,
+				true,
+				true,
+				true,
+				false,
+			},
+			{
+				"WriteException all in writeError",
+				mongo.WriteException{
+					nil,
+					mongo.WriteErrors{
+						mongo.WriteError{0, otherCode, "bar"},
+						mongo.WriteError{0, matchCode, "foo"},
+					},
+					[]string{"otherError"},
+				},
+				true,
+				false,
+				true,
+				true,
+				false,
+			},
+			{
+				"WriteException all false",
+				mongo.WriteException{
+					&mongo.WriteConcernError{"name", otherCode, "bar", nil},
+					mongo.WriteErrors{
+						mongo.WriteError{0, otherCode, "baz"},
+					},
+					[]string{"otherError"},
+				},
+				false,
+				false,
+				false,
+				false,
+				false,
+			},
+			{
+				"WriteException HasErrorCodeAndMessage false",
+				mongo.WriteException{
+					&mongo.WriteConcernError{"name", matchCode, "bar", nil},
+					mongo.WriteErrors{
+						mongo.WriteError{0, otherCode, "foo"},
+					},
+					[]string{"otherError"},
+				},
+				true,
+				false,
+				true,
+				false,
+				false,
+			},
+			{
+				"BulkWriteException all in writeConcernError",
+				mongo.BulkWriteException{
+					&mongo.WriteConcernError{"name", matchCode, "foo", nil},
+					nil,
+					[]string{label},
+				},
+				true,
+				true,
+				true,
+				true,
+				false,
+			},
+			{
+				"BulkWriteException all in writeError",
+				mongo.BulkWriteException{
+					nil,
+					[]mongo.BulkWriteError{
+						{mongo.WriteError{0, matchCode, "foo"}, &mongo.InsertOneModel{}},
+						{mongo.WriteError{0, otherCode, "bar"}, &mongo.InsertOneModel{}},
+					},
+					[]string{"otherError"},
+				},
+				true,
+				false,
+				true,
+				true,
+				false,
+			},
+			{
+				"BulkWriteException all false",
+				mongo.BulkWriteException{
+					&mongo.WriteConcernError{"name", otherCode, "bar", nil},
+					[]mongo.BulkWriteError{
+						{mongo.WriteError{0, otherCode, "baz"}, &mongo.InsertOneModel{}},
+					},
+					[]string{"otherError"},
+				},
+				false,
+				false,
+				false,
+				false,
+				false,
+			},
+			{
+				"BulkWriteException HasErrorCodeAndMessage false",
+				mongo.BulkWriteException{
+					&mongo.WriteConcernError{"name", matchCode, "bar", nil},
+					[]mongo.BulkWriteError{
+						{mongo.WriteError{0, otherCode, "foo"}, &mongo.InsertOneModel{}},
+					},
+					[]string{"otherError"},
+				},
+				true,
+				false,
+				true,
+				false,
+				false,
+			},
+		}
+		for _, tc := range testCases {
+			mt.Run(tc.name, func(mt *mtest.T) {
+				has := tc.err.HasErrorCode(matchCode)
+				assert.Equal(mt, has, tc.hasCode, "expected HasErrorCode to return %v, got %v", tc.hasCode, has)
+				has = tc.err.HasErrorLabel(label)
+				assert.Equal(mt, has, tc.hasLabel, "expected HasErrorLabel to return %v, got %v", tc.hasLabel, has)
+
+				// Check for full message and substring
+				has = tc.err.HasErrorMessage("foo")
+				assert.Equal(mt, has, tc.hasMessage, "expected HasErrorMessage to return %v, got %v", tc.hasMessage, has)
+				has = tc.err.HasErrorMessage("fo")
+				assert.Equal(mt, has, tc.hasMessage, "expected HasErrorMessage to return %v, got %v", tc.hasMessage, has)
+				has = tc.err.HasErrorCodeWithMessage(matchCode, "foo")
+				assert.Equal(mt, has, tc.hasCodeWithMessage, "expected HasErrorCodeWithMessage to return %v, got %v", tc.hasCodeWithMessage, has)
+				has = tc.err.HasErrorCodeWithMessage(matchCode, "fo")
+				assert.Equal(mt, has, tc.hasCodeWithMessage, "expected HasErrorCodeWithMessage to return %v, got %v", tc.hasCodeWithMessage, has)
+
+				assert.Equal(mt, errors.Is(tc.err, matchWrapped), tc.isResult, "expected errors.Is result to be %v", tc.isResult)
+			})
+		}
+	})
 }