Merge pull request #115 from dhartunian/multierror-formatting

add formatting for multi-cause errors

Author: dhartunian

errbase/decode.go

@@ -57,6 +57,15 @@ func decodeLeaf(ctx context.Context, enc *errorspb.EncodedErrorLeaf) error {
 			return genErr
 		}
 		// Decoding failed, we'll drop through to opaqueLeaf{} below.
+	} else if decoder, ok := multiCauseDecoders[typeKey]; ok {
+		causes := make([]error, len(enc.MultierrorCauses))
+		for i, e := range enc.MultierrorCauses {
+			causes[i] = DecodeError(ctx, *e)
+		}
+		genErr := decoder(ctx, causes, enc.Message, enc.Details.ReportablePayload, payload)
+		if genErr != nil {
+			return genErr
+		}
 	} else {
 		// Shortcut for non-registered proto-encodable error types:
 		// if it already implements `error`, it's good to go.
@@ -174,3 +183,24 @@ type WrapperDecoder = func(ctx context.Context, cause error, msgPrefix string, s
 
 // registry for RegisterWrapperType.
 var decoders = map[TypeKey]WrapperDecoder{}
+
+// MultiCauseDecoder is to be provided (via RegisterMultiCauseDecoder
+// above) by additional multi-cause wrapper types not yet known by the
+// library. A nil return indicates that decoding was not successful.
+type MultiCauseDecoder = func(ctx context.Context, causes []error, msgPrefix string, safeDetails []string, payload proto.Message) error
+
+// registry for RegisterMultiCauseDecoder.
+var multiCauseDecoders = map[TypeKey]MultiCauseDecoder{}
+
+// RegisterMultiCauseDecoder can be used to register new multi-cause
+// wrapper types to the library. Registered wrappers will be decoded
+// using their own Go type when an error is decoded. Multi-cause
+// wrappers that have not been registered will be decoded using the
+// opaqueWrapper type.
+func RegisterMultiCauseDecoder(theType TypeKey, decoder MultiCauseDecoder) {
+	if decoder == nil {
+		delete(multiCauseDecoders, theType)
+	} else {
+		multiCauseDecoders[theType] = decoder
+	}
+}

errbase/encode.go

@@ -328,6 +328,28 @@ type LeafEncoder = func(ctx context.Context, err error) (msg string, safeDetails
 // registry for RegisterLeafEncoder.
 var leafEncoders = map[TypeKey]LeafEncoder{}
 
+// RegisterMultiCauseEncoder can be used to register new multi-cause
+// error types to the library. Registered types will be encoded using
+// their own Go type when an error is encoded. Multi-cause wrappers
+// that have not been registered will be encoded using the
+// opaqueWrapper type.
+func RegisterMultiCauseEncoder(theType TypeKey, encoder MultiCauseEncoder) {
+	// This implementation is a simple wrapper around `LeafEncoder`
+	// because we implemented multi-cause error wrapper encoding into a
+	// `Leaf` instead of a `Wrapper` for smoother backwards
+	// compatibility support. Exposing this detail to consumers of the
+	// API is confusing and hence avoided. The causes of the error are
+	// encoded separately regardless of this encoder's implementation.
+	RegisterLeafEncoder(theType, encoder)
+}
+
+// MultiCauseEncoder is to be provided (via RegisterMultiCauseEncoder
+// above) by additional multi-cause wrapper types not yet known to this
+// library. The encoder will automatically extract and encode the
+// causes of this error by calling `Unwrap()` and expecting a slice of
+// errors.
+type MultiCauseEncoder = func(ctx context.Context, err error) (msg string, safeDetails []string, payload proto.Message)
+
 // RegisterWrapperEncoder can be used to register new wrapper types to
 // the library. Registered wrappers will be encoded using their own
 // Go type when an error is encoded. Wrappers that have not been

errbase/format_error.go

@@ -102,7 +102,13 @@ func formatErrorInternal(err error, s fmt.State, verb rune, redactableOutput boo
 		// to enable stack trace de-duplication. This requires a
 		// post-order traversal. Since we have a linked list, the best we
 		// can do is a recursion.
-		p.formatRecursive(err, true /* isOutermost */, true /* withDetail */)
+		p.formatRecursive(
+			err,
+			true,  /* isOutermost */
+			true,  /* withDetail */
+			false, /* withDepth */
+			0,     /* depth */
+		)
 
 		// We now have all the data, we can render the result.
 		p.formatEntries(err)
@@ -146,7 +152,13 @@ func formatErrorInternal(err error, s fmt.State, verb rune, redactableOutput boo
 		// by calling FormatError(), in which case we'd get an infinite
 		// recursion. So we have no choice but to peel the data
 		// and then assemble the pieces ourselves.
-		p.formatRecursive(err, true /* isOutermost */, false /* withDetail */)
+		p.formatRecursive(
+			err,
+			true,  /* isOutermost */
+			false, /* withDetail */
+			false, /* withDepth */
+			0,     /* depth */
+		)
 		p.formatSingleLineOutput()
 		p.finishDisplay(verb)
 
@@ -195,7 +207,19 @@ func (s *state) formatEntries(err error) {
 	// Wraps: (N) <details>
 	//
 	for i, j := len(s.entries)-2, 2; i >= 0; i, j = i-1, j+1 {
-		fmt.Fprintf(&s.finalBuf, "\nWraps: (%d)", j)
+		s.finalBuf.WriteByte('\n')
+		// Extra indentation starts at depth==2 because the direct
+		// children of the root error area already printed on separate
+		// newlines.
+		for m := 0; m < s.entries[i].depth-1; m += 1 {
+			if m == s.entries[i].depth-2 {
+				s.finalBuf.WriteString("└─ ")
+			} else {
+				s.finalBuf.WriteByte(' ')
+				s.finalBuf.WriteByte(' ')
+			}
+		}
+		fmt.Fprintf(&s.finalBuf, "Wraps: (%d)", j)
 		entry := s.entries[i]
 		s.printEntry(entry)
 	}
@@ -330,12 +354,34 @@ func (s *state) formatSingleLineOutput() {
 // s.finalBuf is untouched. The conversion of s.entries
 // to s.finalBuf is done by formatSingleLineOutput() and/or
 // formatEntries().
-func (s *state) formatRecursive(err error, isOutermost, withDetail bool) {
+//
+// `withDepth` and `depth` are used to tag subtrees of multi-cause
+// errors for added indentation during printing. Once a multi-cause
+// error is encountered, all subsequent calls with set `withDepth` to
+// true, and increment `depth` during recursion. This information is
+// persisted into the generated entries and used later to display the
+// error with increased indentation based in the depth.
+func (s *state) formatRecursive(err error, isOutermost, withDetail, withDepth bool, depth int) int {
 	cause := UnwrapOnce(err)
+	numChildren := 0
 	if cause != nil {
-		// Recurse first.
-		s.formatRecursive(cause, false /*isOutermost*/, withDetail)
+		// Recurse first, which populates entries list starting from innermost
+		// entry. If we've previously seen a multi-cause wrapper, `withDepth`
+		// will be true, and we'll record the depth below ensuring that extra
+		// indentation is applied to this inner cause during printing.
+		// Otherwise, we maintain "straight" vertical formatting by keeping the
+		// parent callers `withDepth` value of `false` by default.
+		numChildren += s.formatRecursive(cause, false, withDetail, withDepth, depth+1)
+	}
+
+	causes := UnwrapMulti(err)
+	for _, c := range causes {
+		// Override `withDepth` to true for all child entries ensuring they have
+		// indentation applied during formatting to distinguish them from
+		// parents.
+		numChildren += s.formatRecursive(c, false, withDetail, true, depth+1)
 	}
+	// inserted := len(s.entries) - 1 - startChildren
 
 	// Reinitialize the state for this stage of wrapping.
 	s.wantDetail = withDetail
@@ -355,17 +401,19 @@ func (s *state) formatRecursive(err error, isOutermost, withDetail bool) {
 		bufIsRedactable = true
 		desiredShortening := v.SafeFormatError((*safePrinter)(s))
 		if desiredShortening == nil {
-			// The error wants to elide the short messages from inner
-			// causes. Do it.
-			s.elideFurtherCauseMsgs()
+			// The error wants to elide the short messages from inner causes.
+			// Read backwards through list of entries up to the number of new
+			// entries created "under" this one amount and mark `elideShort`
+			// true.
+			s.elideShortChildren(numChildren)
 		}
 
 	case Formatter:
 		desiredShortening := v.FormatError((*printer)(s))
 		if desiredShortening == nil {
 			// The error wants to elide the short messages from inner
 			// causes. Do it.
-			s.elideFurtherCauseMsgs()
+			s.elideShortChildren(numChildren)
 		}
 
 	case fmt.Formatter:
@@ -389,7 +437,7 @@ func (s *state) formatRecursive(err error, isOutermost, withDetail bool) {
 			if elideCauseMsg := s.formatSimple(err, cause); elideCauseMsg {
 				// The error wants to elide the short messages from inner
 				// causes. Do it.
-				s.elideFurtherCauseMsgs()
+				s.elideShortChildren(numChildren)
 			}
 		}
 
@@ -412,7 +460,7 @@ func (s *state) formatRecursive(err error, isOutermost, withDetail bool) {
 				if desiredShortening == nil {
 					// The error wants to elide the short messages from inner
 					// causes. Do it.
-					s.elideFurtherCauseMsgs()
+					s.elideShortChildren(numChildren)
 				}
 				break
 			}
@@ -421,16 +469,21 @@ func (s *state) formatRecursive(err error, isOutermost, withDetail bool) {
 			// If the error did not implement errors.Formatter nor
 			// fmt.Formatter, but it is a wrapper, still attempt best effort:
 			// print what we can at this level.
-			if elideCauseMsg := s.formatSimple(err, cause); elideCauseMsg {
+			elideChildren := s.formatSimple(err, cause)
+			// always elideChildren when dealing with multi-cause errors.
+			if len(causes) > 0 {
+				elideChildren = true
+			}
+			if elideChildren {
 				// The error wants to elide the short messages from inner
 				// causes. Do it.
-				s.elideFurtherCauseMsgs()
+				s.elideShortChildren(numChildren)
 			}
 		}
 	}
 
 	// Collect the result.
-	entry := s.collectEntry(err, bufIsRedactable)
+	entry := s.collectEntry(err, bufIsRedactable, withDepth, depth)
 
 	// If there's an embedded stack trace, also collect it.
 	// This will get either a stack from pkg/errors, or ours.
@@ -444,21 +497,22 @@ func (s *state) formatRecursive(err error, isOutermost, withDetail bool) {
 	// Remember the entry for later rendering.
 	s.entries = append(s.entries, entry)
 	s.buf = bytes.Buffer{}
+
+	return numChildren + 1
 }
 
-// elideFurtherCauseMsgs sets the `elideShort` field
-// on all entries added so far to `true`. Because these
-// entries are added recursively from the innermost
-// cause outward, we can iterate through all entries
-// without bound because the caller is guaranteed not
-// to see entries that it is the causer of.
-func (s *state) elideFurtherCauseMsgs() {
-	for i := range s.entries {
-		s.entries[i].elideShort = true
+// elideShortChildren takes a number of entries to set `elideShort` to
+// false. The reason a number of entries is needed is that we may be
+// eliding a subtree of causes in the case of a multi-cause error. In
+// the multi-cause case, we need to know how many of the prior errors
+// in the list of entries is a child of this subtree.
+func (s *state) elideShortChildren(newEntries int) {
+	for i := 0; i < newEntries; i++ {
+		s.entries[len(s.entries)-1-i].elideShort = true
 	}
 }
 
-func (s *state) collectEntry(err error, bufIsRedactable bool) formatEntry {
+func (s *state) collectEntry(err error, bufIsRedactable bool, withDepth bool, depth int) formatEntry {
 	entry := formatEntry{err: err}
 	if s.wantDetail {
 		// The buffer has been populated as a result of formatting with
@@ -495,6 +549,10 @@ func (s *state) collectEntry(err error, bufIsRedactable bool) formatEntry {
 		}
 	}
 
+	if withDepth {
+		entry.depth = depth
+	}
+
 	return entry
 }
 
@@ -712,6 +770,11 @@ type formatEntry struct {
 	// truncated to avoid duplication of entries. This is used to
 	// display a truncation indicator during verbose rendering.
 	elidedStackTrace bool
+
+	// depth, if positive, represents a nesting depth of this error as
+	// a causer of others. This is used with verbose printing to
+	// illustrate the nesting depth for multi-cause error wrappers.
+	depth int
 }
 
 // String is used for debugging only.
@@ -733,6 +796,12 @@ func (s *state) Write(b []byte) (n int, err error) {
 
 	for i, c := range b {
 		if c == '\n' {
+			//if s.needNewline > 0 {
+			//	for i := 0; i < s.needNewline-1; i++ {
+			//		s.buf.Write(detailSep[:len(sep)-1])
+			//	}
+			//	s.needNewline = 0
+			//}
 			// Flush all the bytes seen so far.
 			s.buf.Write(b[k:i])
 			// Don't print the newline itself; instead, prepare the state so
@@ -762,6 +831,11 @@ func (s *state) Write(b []byte) (n int, err error) {
 			s.notEmpty = true
 		}
 	}
+	//if s.needNewline > 0 {
+	//	for i := 0; i < s.needNewline-1; i++ {
+	//		s.buf.Write(detailSep[:len(sep)-1])
+	//	}
+	//}
 	s.buf.Write(b[k:])
 	return len(b), nil
 }
@@ -788,6 +862,9 @@ func (p *state) switchOver() {
 	p.buf = bytes.Buffer{}
 	p.notEmpty = false
 	p.hasDetail = true
+
+	// One of the newlines is accounted for in the switch over.
+	// p.needNewline -= 1
 }
 
 func (s *printer) Detail() bool {