cockroachdb/errors: Go errors with network portability

This library aims to be used as a drop-in replacement to github.com/pkg/errors and Go's standard errors package. It also provides network portability of error objects, in ways suitable for distributed systems with mixed-version software compatibility.

It also provides native and comprehensive support for PII-free details and an opt-in Sentry.io reporting mechanism that automatically formats error details and strips them of PII.

See also the design RFC.

Table of contents:

• Features
• How to use
• What comes out of an error?
• Available error leaves
• Available wrapper constructors
• Providing PII-free details
• Building your own error types
• Error composition (summary)
• API (not constructing error objects)

Features

"Forward compatibility" above refers to the ability of this library to recognize and properly handle network communication of error types it does not know about, for example when a more recent version of a software package sends a new error object to another system running an older version of the package.

How to use

• construct errors with errors.New(), etc as usual, but also see the other error leaf constructors below.
• wrap errors with errors.Wrap() as usual, but also see the other wrappers below.
• test error identity with errors.Is() as usual. Unique in this library: this works even if the error has traversed the network! Also, errors.IsAny() to recognize two or more reference errors.
• replace uses of os.IsPermission(), os.IsTimeout(), os.IsExist() and os.IsNotExist() by their analog in sub-package oserror so that they can peek through layers of wrapping.
• access error causes with errors.UnwrapOnce() / errors.UnwrapAll() (note: errors.Cause() and errors.Unwrap() also provided for compatibility with other error packages).
• encode/decode errors to protobuf with errors.EncodeError() / errors.DecodeError().
• extract PII-free safe details with errors.GetSafeDetails().
• extract human-facing hints and details with errors.GetAllHints()/errors.GetAllDetails() or errors.FlattenHints()/errors.FlattenDetails().
• produce detailed Sentry.io reports with errors.BuildSentryReport() / errors.ReportError().
• implement your own error leaf types and wrapper types:
  • implement the error and errors.Wrapper interfaces as usual.
  • register encode/decode functions: call errors.Register{Leaf,Wrapper}{Encoder,Decoder}() in a init() function in your package.
  • implement Format() that redirects to errors.FormatError().
  • see the section Building your own error types below.

What comes out of an error?

Available error leaves

An error leaf is an object that implements the error interface, but does not refer to another error via a Unwrap() or Cause() method.

• New(string) error, Newf(string, ...interface{}) error, Errorf(string, ...interface{}) error: leaf errors with message

  • when to use: common error cases.
  • what it does: also captures the stack trace at point of call and redacts the provided message for safe reporting.
  • how to access the detail: Error(), regular Go formatting. Details in Sentry report.
  • see also: Section Error composition below. errors.NewWithDepth() variants to customize at which call depth the stack trace is captured.

• AssertionFailedf(string, ...interface{}) error, NewAssertionFailureWithWrappedErrf(error, string, ...interface{}) error: signals an assertion failure / programming error.

  • when to use: when an invariant is violated; when an unreachable code path is reached.
  • what it does: also captures the stack trace at point of call, redacts the provided strings for safe reporting, prepares a hint to inform a human user.
  • how to access the detail: IsAssertionFailure()/HasAssertionFailure(), format with %+v, Safe details included in Sentry reports.
  • see also: Section Error composition below. errors.AssertionFailedWithDepthf() variant to customize at which call depth the stack trace is captured.

• Handled(error) error, Opaque(error) error, HandledWithMessage(error, string) error: captures an error cause but make it invisible to Unwrap() / Is().

  • when to use: when a new error occurs while handling an error, and the original error must be "hidden".
  • what it does: captures the cause in a hidden field. The error message is preserved unless the ...WithMessage() variant is used.
  • how to access the detail: format with %+v, redacted details reported in Sentry reports.

• UnimplementedError(IssueLink, string) error: captures a message string and a URL reference to an external resource to denote a feature that was not yet implemented.

  • when to use: to inform (human) users that some feature is not implemented yet and refer them to some external resource.
  • what it does: captures the message, URL and detail in a wrapper. The URL and detail are considered safe for reporting.
  • how to access the detail: errors.GetAllHints(), errors.FlattenHints(), format with %+v, URL and detail included in Sentry report (not the message).
  • see also: errors.WithIssueLink() below for errors that are not specifically about unimplemented features.

Available wrapper constructors

An error wrapper is an object that implements the error interface, and also refers to another error via an Unwrap() (preferred) and/or Cause() method.

All wrapper constructors can be applied safely to a nil error: they behave as no-ops in this case:

// The following:
// if err := foo(); err != nil {
//    return errors.Wrap(err, "foo")
// }
// return nil
//
// is not needed. Instead, you can use this:
return errors.Wrap(foo(), "foo")

• Wrap(error, string) error, Wrapf(error, string, ...interface{}) error:

  • when to use: on error return paths.
  • what it does: combines WithMessage(), WithStack(), WithSafeDetails().
  • how to access the details: Error(), regular Go formatting. Details in Sentry report.
  • see also: Section Error composition below. WrapWithDepth() variants to customize at which depth the stack trace is captured.

• WithSecondaryError(error, error) error: annotate an error with a secondary error.

  • when to use: when an additional error occurs in the code that is handling a primary error. Consider using errors.CombineErrors() instead (see below).
  • what it does: it captures the secondary error but hides it from errors.Is().
  • how to access the detail: format with %+v, redacted recursively in Sentry reports.
  • see also: errors.CombineErrors()

• CombineErrors(error, error) error: combines two errors into one.

  • when to use: when two operations occur concurrently and either can return an error, and only one final error must be returned.
  • what it does: returns either of its arguments if the other is nil, otherwise calls `WithSecondaryE