cockroachdb/errors

The cockroachdb/errors library is a drop-in replacement for Go's standard errors package and github.com/pkg/errors. It is designed for distributed systems, providing network portability for error objects. This allows error identity (via errors.Is()) to be maintained even after errors have been encoded and sent across a network, supporting forward compatibility between different software versions.

Key capabilities include:

• Network Portability: Transparent protobuf encoding/decoding with forward compatibility.
• PII Protection: Native support for PII-free (Personally Identifiable Information) details and safe reporting.
• Sentry Integration: An opt-in mechanism to automatically format and strip PII from error reports sent to Sentry.io.
• Rich Metadata: Support for stack traces, hints, details, assertion failures, issue tracker links, and secondary causes.

To create a custom leaf error type, implement the standard Go error interface. If your type already implements proto.Message (from gogoproto), the library will use it for encoding/decoding automatically.

If it does not implement proto.Message, you must provide a decoder function and register it using errors.RegisterLeafEncoder.

If your error type has fields that are not reflected in the Error() string and are not PII-free (meaning they cannot be exposed via errors.SafeDetailer), you must implement a custom encoder. Otherwise, the library can automatically encode the error message and any strings returned by SafeDetails().

// note: we use the gogoproto `proto` sub-package.
func yourDecode(_ string, _ []string, _ proto.Message) error {
   return &yourType{}
}

func init() {
   errors.RegisterLeafEncoder((*yourType)(nil), yourDecodeFunc)
}

To ensure that the %+v verb correctly formats your custom error types and recursively prints their causes, you should implement the fmt.Formatter interface and redirect to errors.FormatError.

Additionally, if your error type has payload data not visible in Error() that should be emitted during %+v formatting, implement the errors.SafeFormatter interface using SafeFormatError(p errors.Printer) (next error).

// Required for recursive %+v support
func (e *yourType) Format(s *fmt.State, verb rune) {
    errors.FormatError(e, s, verb)
}

// Optional: to include extra details in %+v output
func (w *withHTTPCode) SafeFormatError(p errors.Printer) (next error) {
    if p.Detail() {
        p.Printf("http code: %d", errors.Safe(w.code))
    }
    return w.cause
}

To create a custom wrapper error type, implement the error interface and the errors.Wrapper interface (by providing an Unwrap() method).

If your type does not implement proto.Message, you must provide a decoder function that handles the cause and register it using errors.RegisterWrapperDecoder. The library automatically handles the encoding/decoding of the cause error passed to the decoder.

func yourDecodeWrapper(cause error, _ string, _ []string, _ proto.Message) error {
   // Note: the library already takes care of encoding/decoding the cause.
   return &yourWrapperType{cause: cause}
}

func init() {
   errors.RegisterWrapperDecoder((*yourWrapperType)(nil), yourDecodeWrapper)
}

The library automatically redacts PII-unsafe strings when building Sentry reports. To ensure specific data is included in reports (making it 'safe'), use one of the following methods:

1. Use errors.Safe(): Wrap arguments in the ...f() constructors.

   err := errors.Newf("my code: %d", errors.Safe(123))

   The value 123 will be included in Sentry reports and is available via errors.GetSafeDetails()/GetAllSafeDetails().

2. Use errors.WithSafeDetails(): Attach arbitrary strings that are safe for reporting but not part of the main Error() message.

   err = errors.WithSafeDetails(err, "additional data: %s", errors.Safe("hello"))

3. Implement errors.SafeDetailer: For custom error types, implement the SafeDetails() []string method to provide a list of safe strings.

Most constructor and wrapper functions have a corresponding WithDepth variant (e.g., NewWithDepth, WrapWithDepth, JoinWithDepth, NewWithDepthf, WrapWithDepthf, AssertionFailedWithDepthf, HandleAsAssertionFailureDepth).

Use these when you need to manually control the depth at which the stack trace is captured, typically when wrapping errors in helper functions to avoid capturing the helper's own stack frame.

The library supports extracting 'Safe Details'—information attached to an error that is guaranteed to be free of Personally Identifiable Information (PII). This is useful for logging or displaying error information to users without compromising security.

• GetSafeDetails(err error) (payload SafeDetailPayload): Returns a single safe detail payload.
• GetAllSafeDetails(err error) []SafeDetailPayload: Returns all available safe detail payloads.

If you rename a Go package or an error type, existing errors transported over the network may no longer be recognized by errors.Is in newer versions of your software.

To maintain network portability, call errors.RegisterTypeMigration in an init() function to map the old path and type name to a new instance of the error type.

previousPath := "github.com/old/path/to/error/package"
previousTypeName := "oldpackage.oldErrorName"
newErrorInstance := &newTypeName{...}
errors.RegisterTypeMigration(previousPath, previousTypeName, newErrorInstance)

Domains allow you to categorize errors into logical groups (e.g., database errors vs. network errors). This helps in filtering and handling errors based on their origin.

• GetDomain(err error) Domain: Retrieves the domain of the error.
• NamedDomain(domainName string) Domain: Creates a new domain with the specified name.
• PackageDomain() Domain: Returns the domain associated with the current package.
• PackageDomainAtDepth(depth int) Domain: Returns the domain at a specific depth in the error chain.
• NotInDomain(err error, doms ...Domain) bool: Checks if the error is NOT in any of the specified domains.

If you define custom error types, you must register their encoding and decoding logic so they can be correctly serialized and deserialized during network transport. You can register encoders/decoders for both 'Leaf' errors (the root cause) and 'Wrapper' errors (errors that wrap other errors).

Available registration functions:

• RegisterLeafEncoder(typeName TypeKey, encoder LeafEncoder)
• RegisterLeafDecoder(typeName TypeKey, decoder LeafDecoder)
• RegisterWrapperEncoder(typeName TypeKey, encoder WrapperEncoder)
• RegisterWrapperDecoder(typeName TypeKey, decoder WrapperDecoder)
• RegisterMultiCauseEncoder(theType TypeKey, encoder MultiCauseEncoder)
• RegisterMultiCauseDecoder(theType TypeKey, decoder MultiCauseDecoder)