errors, fmt: add support for wrapping multiple errors

An error which implements an "Unwrap() []error" method wraps all the
non-nil errors in the returned []error.

We replace the concept of the "error chain" inspected by errors.Is
and errors.As with the "error tree". Is and As perform a pre-order,
depth-first traversal of an error's tree. As returns the first
matching result, if any.

The new errors.Join function returns an error wrapping a list of errors.

The fmt.Errorf function now supports multiple instances of the %w verb.

For #53435.

Change-Id: Ib7402e70b68e28af8f201d2b66bd8e87ccfb5283
Reviewed-on: https://go-review.googlesource.com/c/go/+/432898
Reviewed-by: Cherry Mui <cherryyz@google.com>
Reviewed-by: Rob Pike <r@golang.org>
Run-TryBot: Damien Neil <dneil@google.com>
Reviewed-by: Joseph Tsai <joetsai@digital-static.net>

3 files changed, 94 insertions, 23 deletions

diff --git a/src/fmt/errors.go b/src/fmt/errors.go
index 4f4daf19e1..1fbd39f8f1 100644
--- a/src/fmt/errors.go
+++ b/src/fmt/errors.go
@@ -4,26 +4,48 @@
 
 package fmt
 
-import "errors"
+import (
+	"errors"
+	"sort"
+)
 
 // Errorf formats according to a format specifier and returns the string as a
 // value that satisfies error.
 //
 // If the format specifier includes a %w verb with an error operand,
-// the returned error will implement an Unwrap method returning the operand. It is
-// invalid to include more than one %w verb or to supply it with an operand
-// that does not implement the error interface. The %w verb is otherwise
-// a synonym for %v.
+// the returned error will implement an Unwrap method returning the operand.
+// If there is more than one %w verb, the returned error will implement an
+// Unwrap method returning a []error containing all the %w operands in the
+// order they appear in the arguments.
+// It is invalid to supply the %w verb with an operand that does not implement
+// the error interface. The %w verb is otherwise a synonym for %v.
 func Errorf(format string, a ...any) error {
 	p := newPrinter()
 	p.wrapErrs = true
 	p.doPrintf(format, a)
 	s := string(p.buf)
 	var err error
-	if p.wrappedErr == nil {
+	switch len(p.wrappedErrs) {
+	case 0:
 		err = errors.New(s)
-	} else {
-		err = &wrapError{s, p.wrappedErr}
+	case 1:
+		w := &wrapError{msg: s}
+		w.err, _ = a[p.wrappedErrs[0]].(error)
+		err = w
+	default:
+		if p.reordered {
+			sort.Ints(p.wrappedErrs)
+		}
+		var errs []error
+		for i, argNum := range p.wrappedErrs {
+			if i > 0 && p.wrappedErrs[i-1] == argNum {
+				continue
+			}
+			if e, ok := a[argNum].(error); ok {
+				errs = append(errs, e)
+			}
+		}
+		err = &wrapErrors{s, errs}
 	}
 	p.free()
 	return err
@@ -41,3 +63,16 @@ func (e *wrapError) Error() string {
 func (e *wrapError) Unwrap() error {
 	return e.err
 }
+
+type wrapErrors struct {
+	msg  string
+	errs []error
+}
+
+func (e *wrapErrors) Error() string {
+	return e.msg
+}
+
+func (e *wrapErrors) Unwrap() []error {
+	return e.errs
+}
diff --git a/src/fmt/errors_test.go b/src/fmt/errors_test.go
index 481a7b8403..4eb55faffe 100644
--- a/src/fmt/errors_test.go
+++ b/src/fmt/errors_test.go
@@ -7,6 +7,7 @@ package fmt_test
 import (
 	"errors"
 	"fmt"
+	"reflect"
 	"testing"
 )
 
@@ -20,6 +21,7 @@ func TestErrorf(t *testing.T) {
 		err        error
 		wantText   string
 		wantUnwrap error
+		wantSplit  []error
 	}{{
 		err:        fmt.Errorf("%w", wrapped),
 		wantText:   "inner error",
@@ -53,11 +55,29 @@ func TestErrorf(t *testing.T) {
 		err:      noVetErrorf("%w is not an error", "not-an-error"),
 		wantText: "%!w(string=not-an-error) is not an error",
 	}, {
-		err:      noVetErrorf("wrapped two errors: %w %w", errString("1"), errString("2")),
-		wantText: "wrapped two errors: 1 %!w(fmt_test.errString=2)",
+		err:       noVetErrorf("wrapped two errors: %w %w", errString("1"), errString("2")),
+		wantText:  "wrapped two errors: 1 2",
+		wantSplit: []error{errString("1"), errString("2")},
 	}, {
-		err:      noVetErrorf("wrapped three errors: %w %w %w", errString("1"), errString("2"), errString("3")),
-		wantText: "wrapped three errors: 1 %!w(fmt_test.errString=2) %!w(fmt_test.errString=3)",
+		err:       noVetErrorf("wrapped three errors: %w %w %w", errString("1"), errString("2"), errString("3")),
+		wantText:  "wrapped three errors: 1 2 3",
+		wantSplit: []error{errString("1"), errString("2"), errString("3")},
+	}, {
+		err:       noVetErrorf("wrapped nil error: %w %w %w", errString("1"), nil, errString("2")),
+		wantText:  "wrapped nil error: 1 %!w(<nil>) 2",
+		wantSplit: []error{errString("1"), errString("2")},
+	}, {
+		err:       noVetErrorf("wrapped one non-error: %w %w %w", errString("1"), "not-an-error", errString("3")),
+		wantText:  "wrapped one non-error: 1 %!w(string=not-an-error) 3",
+		wantSplit: []error{errString("1"), errString("3")},
+	}, {
+		err:       fmt.Errorf("wrapped errors out of order: %[3]w %[2]w %[1]w", errString("1"), errString("2"), errString("3")),
+		wantText:  "wrapped errors out of order: 3 2 1",
+		wantSplit: []error{errString("1"), errString("2"), errString("3")},
+	}, {
+		err:       fmt.Errorf("wrapped several times: %[1]w %[1]w %[2]w %[1]w", errString("1"), errString("2")),
+		wantText:  "wrapped several times: 1 1 2 1",
+		wantSplit: []error{errString("1"), errString("2")},
 	}, {
 		err:        fmt.Errorf("%w", nil),
 		wantText:   "%!w(<nil>)",
@@ -66,12 +86,22 @@ func TestErrorf(t *testing.T) {
 		if got, want := errors.Unwrap(test.err), test.wantUnwrap; got != want {
 			t.Errorf("Formatted error: %v\nerrors.Unwrap() = %v, want %v", test.err, got, want)
 		}
+		if got, want := splitErr(test.err), test.wantSplit; !reflect.DeepEqual(got, want) {
+			t.Errorf("Formatted error: %v\nUnwrap() []error = %v, want %v", test.err, got, want)
+		}
 		if got, want := test.err.Error(), test.wantText; got != want {
 			t.Errorf("err.Error() = %q, want %q", got, want)
 		}
 	}
 }
 
+func splitErr(err error) []error {
+	if e, ok := err.(interface{ Unwrap() []error }); ok {
+		return e.Unwrap()
+	}
+	return nil
+}
+
 type errString string
 
 func (e errString) Error() string { return string(e) }
diff --git a/src/fmt/print.go b/src/fmt/print.go
index 4eabda1ce8..b3dd43ce04 100644
--- a/src/fmt/print.go
+++ b/src/fmt/print.go
@@ -139,8 +139,8 @@ type pp struct {
 	erroring bool
 	// wrapErrs is set when the format string may contain a %w verb.
 	wrapErrs bool
-	// wrappedErr records the target of the %w verb.
-	wrappedErr error
+	// wrappedErrs records the targets of the %w verb.
+	wrappedErrs []int
 }
 
 var ppFree = sync.Pool{
@@ -171,10 +171,13 @@ func (p *pp) free() {
 	} else {
 		p.buf = p.buf[:0]
 	}
+	if cap(p.wrappedErrs) > 8 {
+		p.wrappedErrs = nil
+	}
 
 	p.arg = nil
 	p.value = reflect.Value{}
-	p.wrappedErr = nil
+	p.wrappedErrs = p.wrappedErrs[:0]
 	ppFree.Put(p)
 }
 
@@ -620,16 +623,12 @@ func (p *pp) handleMethods(verb rune) (handled bool) {
 		return
 	}
 	if verb == 'w' {
-		// It is invalid to use %w other than with Errorf, more than once,
-		// or with a non-error arg.
-		err, ok := p.arg.(error)
-		if !ok || !p.wrapErrs || p.wrappedErr != nil {
-			p.wrappedErr = nil
-			p.wrapErrs = false
+		// It is invalid to use %w other than with Errorf or with a non-error arg.
+		_, ok := p.arg.(error)
+		if !ok || !p.wrapErrs {
 			p.badVerb(verb)
 			return true
 		}
-		p.wrappedErr = err
 		// If the arg is a Formatter, pass 'v' as the verb to it.
 		verb = 'v'
 	}
@@ -1063,7 +1062,11 @@ formatLoop:
 				// Fast path for common case of ascii lower case simple verbs
 				// without precision or width or argument indices.
 				if 'a' <= c && c <= 'z' && argNum < len(a) {
-					if c == 'v' {
+					switch c {
+					case 'w':
+						p.wrappedErrs = append(p.wrappedErrs, argNum)
+						fallthrough
+					case 'v':
 						// Go syntax
 						p.fmt.sharpV = p.fmt.sharp
 						p.fmt.sharp = false
@@ -1158,6 +1161,9 @@ formatLoop:
 			p.badArgNum(verb)
 		case argNum >= len(a): // No argument left over to print for the current verb.
 			p.missingArg(verb)
+		case verb == 'w':
+			p.wrappedErrs = append(p.wrappedErrs, argNum)
+			fallthrough
 		case verb == 'v':
 			// Go syntax
 			p.fmt.sharpV = p.fmt.sharp