Add Go 1.20 errors.Join support

This commit introduces a drop-in replacement of the go errors lib `Join` method which constructs a simple multi-cause error object. Some simple unit tests are added and `Join` wrappers are also integrated into the datadriven formatting test. Our existing format code for multi-cause errors is compatible with this new type which allows us to remove the custom formatter from the implementation. The public Join API contains wrappers that automatically attach stacktraces to the join errors. Signed-off-by: Steve Coffman <[email protected]>
cockroachdb · Aug 22, 2023 · 5a7989c · 5a7989c
1 parent f0a2a69
commit 5a7989c
Show file tree

Hide file tree

Showing 17 changed files with 2,451 additions and 1 deletion.
diff --git a/errutil/utilities.go b/errutil/utilities.go
@@ -15,6 +15,7 @@
 package errutil
 
 import (
+	"github.com/cockroachdb/errors/join"
 	"github.com/cockroachdb/errors/secondary"
 	"github.com/cockroachdb/errors/withstack"
 	"github.com/cockroachdb/redact"
@@ -158,3 +159,10 @@ func WrapWithDepthf(depth int, err error, format string, args ...interface{}) er
 	err = withstack.WithStackDepth(err, depth+1)
 	return err
 }
+
+// JoinWithDepth constructs a Join error with the provided list of
+// errors as arguments, and wraps it in a `WithStackDepth` to capture a
+// stacktrace alongside.
+func JoinWithDepth(depth int, errs ...error) error {
+	return withstack.WithStackDepth(join.Join(errs...), depth+1)
+}
diff --git a/errutil_api.go b/errutil_api.go
@@ -192,3 +192,19 @@ func HandleAsAssertionFailureDepth(depth int, origErr error) error {
 // - it also supports recursing through causes with Cause().
 // - if it detects an API use error, its panic object is a valid error.
 func As(err error, target interface{}) bool { return errutil.As(err, target) }
+
+// Join returns an error that wraps the given errors.
+// Any nil error values are discarded.
+// Join returns nil if errs contains no non-nil values.
+// The error formats as the concatenation of the strings obtained
+// by calling the Error method of each element of errs, with a newline
+// between each string. A stack trace is also retained.
+func Join(errs ...error) error {
+	return errutil.JoinWithDepth(1, errs...)
+}
+
+// JoinWithDepth is like Join but the depth at which the call stack is
+// captured can be specified.
+func JoinWithDepth(depth int, errs ...error) error {
+	return errutil.JoinWithDepth(depth+1, errs...)
+}
diff --git a/errutil_api_test.go b/errutil_api_test.go
@@ -2,6 +2,7 @@ package errors_test
 
 import (
 	"fmt"
+	"strings"
 	"testing"
 
 	"github.com/cockroachdb/errors"
@@ -17,3 +18,14 @@ func TestUnwrap(t *testing.T) {
 	// (per API documentation)
 	tt.Check(errors.Unwrap(e) == nil)
 }
+
+// More detailed testing of Join is in datadriven_test.go. Here we make
+// sure that the public API includes the stacktrace wrapper.
+func TestJoin(t *testing.T) {
+	e := errors.Join(errors.New("abc123"), errors.New("def456"))
+	printed := fmt.Sprintf("%+v", e)
+	expected := `Error types: (1) *withstack.withStack (2) *join.joinError (3) *withstack.withStack (4) *errutil.leafError (5) *withstack.withStack (6) *errutil.leafError`
+	if !strings.Contains(printed, expected) {
+		t.Errorf("Expected: %s to contain: %s", printed, expected)
+	}
+}
diff --git a/fmttests/datadriven_test.go b/fmttests/datadriven_test.go
@@ -37,6 +37,7 @@ import (
 	"github.com/cockroachdb/errors/errutil"
 	"github.com/cockroachdb/errors/hintdetail"
 	"github.com/cockroachdb/errors/issuelink"
+	"github.com/cockroachdb/errors/join"
 	"github.com/cockroachdb/errors/report"
 	"github.com/cockroachdb/errors/safedetails"
 	"github.com/cockroachdb/errors/secondary"
@@ -276,6 +277,9 @@ var wrapCommands = map[string]commandFn{
 		ctx = logtags.AddTag(ctx, "safe", redact.Safe(456))
 		return contexttags.WithContextTags(err, ctx)
 	},
+	"join": func(err error, args []arg) error {
+		return join.Join(err, errutil.New(strfy(args)))
+	},
 }
 
 var noPrefixWrappers = map[string]bool{
@@ -300,6 +304,7 @@ var noPrefixWrappers = map[string]bool{
 	"stack":             true,
 	"tags":              true,
 	"telemetry":         true,
+	"join":              true,
 }
 
 var wrapOnlyExceptions = map[string]string{}
@@ -329,6 +334,7 @@ func init() {
 		// means they don't match.
 		"nofmt",
 		"errorf",
+		"join",
 	} {
 		wrapOnlyExceptions[v] = `
 accept %\+v via Formattable.*IRREGULAR: not same as %\+v

diff --git a/fmttests/testdata/format/wrap-fmt b/fmttests/testdata/format/wrap-fmt
@@ -2251,6 +2251,197 @@ Type: "*fmttests.errFmt"
 Title: "×"
 (NO STACKTRACE)
 
+run
+fmt innerone innertwo
+join outerthree outerfour
+
+accept %\+v via Formattable.*IRREGULAR: not same as %\+v
+accept %\#v via Formattable.*IRREGULAR: not same as %\#v
+
+require (?s)
+----
+&join.joinError{
+    errs: {
+        &fmttests.errFmt{msg:"innerone\ninnertwo"},
+        &withstack.withStack{
+            cause: &errutil.leafError{msg:"outerthree\nouterfour"},
+            stack: &stack{...},
+        },
+    },
+}
+=====
+===== non-redactable formats
+=====
+== %#v
+&join.joinError{
+    errs: {
+        &fmttests.errFmt{msg:"innerone\ninnertwo"},
+        &withstack.withStack{
+            cause: &errutil.leafError{msg:"outerthree\nouterfour"},
+            stack: &stack{...},
+        },
+    },
+}
+== Error()
+innerone
+innertwo
+outerthree
+outerfour
+== %v = Error(), good
+== %s = Error(), good
+== %q = quoted Error(), good
+== %x = hex Error(), good
+== %X = HEX Error(), good
+== %+v
+innerone
+(1) innerone
+  | innertwo
+  | outerthree
+  | outerfour
+Wraps: (2) attached stack trace
+  -- stack trace:
+  | github.com/cockroachdb/errors/fmttests.glob...funcNN...
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/errors/fmttests.TestDatadriven.func2.1
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirective.func1
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirective
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirectiveOrSubTest
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runTestInternal
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.RunTest
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/errors/fmttests.TestDatadriven.func2
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.Walk
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.Walk.func1
+  | <tab><path>:<lineno>
+  | testing.tRunner
+  | <tab><path>:<lineno>
+  | runtime.goexit
+  | <tab><path>:<lineno>
+└─ Wraps: (3) outerthree
+  | outerfour
+Wraps: (4) innerone
+  | innertwo
+  | -- this is innerone
+  | innertwo's
+  | multi-line leaf payload
+Error types: (1) *join.joinError (2) *withstack.withStack (3) *errutil.leafError (4) *fmttests.errFmt
+== %#v via Formattable() = %#v, good
+== %v via Formattable() = Error(), good
+== %s via Formattable() = %v via Formattable(), good
+== %q via Formattable() = quoted %v via Formattable(), good
+== %+v via Formattable() == %+v, good
+=====
+===== redactable formats
+=====
+== printed via redact Print(), ok - congruent with %v
+‹innerone›
+‹innertwo›
+‹outerthree›
+‹outerfour›
+== printed via redact Printf() %v = Print(), good
+== printed via redact Printf() %s = Print(), good
+== printed via redact Printf() %q, refused - good
+== printed via redact Printf() %x, refused - good
+== printed via redact Printf() %X, refused - good
+== printed via redact Printf() %+v, ok - congruent with %+v
+‹innerone›
+(1) ‹innerone›
+  | ‹innertwo›
+  | ‹outerthree›
+  | ‹outerfour›
+Wraps: (2) attached stack trace
+  -- stack trace:
+  | github.com/cockroachdb/errors/fmttests.glob...funcNN...
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/errors/fmttests.TestDatadriven.func2.1
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirective.func1
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirective
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirectiveOrSubTest
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runTestInternal
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.RunTest
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/errors/fmttests.TestDatadriven.func2
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.Walk
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.Walk.func1
+  | <tab><path>:<lineno>
+  | testing.tRunner
+  | <tab><path>:<lineno>
+  | runtime.goexit
+  | <tab><path>:<lineno>
+└─ Wraps: (3) outerthree
+  | outerfour
+Wraps: (4) ‹innerone›
+‹  | innertwo›
+‹  | -- this is innerone›
+‹  | innertwo's›
+‹  | multi-line leaf payload›
+Error types: (1) *join.joinError (2) *withstack.withStack (3) *errutil.leafError (4) *fmttests.errFmt
+=====
+===== Sentry reporting
+=====
+== Message payload
+×
+(1) ×
+  | ×
+  | ×
+  | ×
+Wraps: (2) attached stack trace
+  -- stack trace:
+  | github.com/cockroachdb/errors/fmttests.glob...funcNN...
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/errors/fmttests.TestDatadriven.func2.1
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirective.func1
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirective
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runDirectiveOrSubTest
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.runTestInternal
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.RunTest
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/errors/fmttests.TestDatadriven.func2
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.Walk
+  | <tab><path>:<lineno>
+  | github.com/cockroachdb/datadriven.Walk.func1
+  | <tab><path>:<lineno>
+  | testing.tRunner
+  | <tab><path>:<lineno>
+  | runtime.goexit
+  | <tab><path>:<lineno>
+└─ Wraps: (3) outerthree
+  | outerfour
+Wraps: (4) ×
+×
+×
+×
+×
+Error types: (1) *join.joinError (2) *withstack.withStack (3) *errutil.leafError (4) *fmttests.errFmt
+-- report composition:
+*join.joinError
+== Extra "error types"
+github.com/cockroachdb/errors/join/*join.joinError (*::)
+== Exception 1 (Module: "error domain: <none>")
+Type: "*join.joinError"
+Title: "×"
+(NO STACKTRACE)
+
 run
 fmt innerone innertwo
 migrated outerthree outerfour