errbase

Documentation

Index

• func DecodeError(ctx context.Context, enc EncodedError) error
• func FormatError(err error, s fmt.State, verb rune)
• func GetTypeMark(err error) errorspb.ErrorTypeMark
• func RegisterLeafDecoder(theType TypeKey, decoder LeafDecoder)
• func RegisterLeafEncoder(theType TypeKey, encoder LeafEncoder)
• func RegisterTypeMigration(previousPkgPath, previousTypeName string, newType error)
• func RegisterWrapperDecoder(theType TypeKey, decoder WrapperDecoder)
• func RegisterWrapperEncoder(theType TypeKey, encoder WrapperEncoder)
• func SetWarningFn(fn func(context.Context, string, ...interface{}))
• func TestingWithEmptyMigrationRegistry() (restore func())
• func UnwrapAll(err error) error
• func UnwrapOnce(err error) (cause error)
• type EncodedError
  • func EncodeError(ctx context.Context, err error) EncodedError
• type Formatter
• type LeafDecoder
• type LeafEncoder
• type Printer
• type SafeDetailPayload
  • func GetAllSafeDetails(err error) []SafeDetailPayload
  • func GetSafeDetails(err error) (payload SafeDetailPayload)
  • func (s *SafeDetailPayload) Fill(slice []string) []string
• type SafeDetailer
• type TypeKey
  • func GetTypeKey(err error) TypeKey
• type TypeKeyMarker
• type WrapperDecoder
• type WrapperEncoder

Functions

func DecodeError

func DecodeError(ctx context.Context, enc EncodedError) error

DecodeError decodes an error.

func FormatError

func FormatError(err error, s fmt.State, verb rune)

FormatError formats an error according to s and verb.

If the error implements errors.Formatter, FormatError calls its FormatError method of f with an errors.Printer configured according to s and verb, and writes the result to s.

Otherwise, if it is a wrapper, FormatError prints out its error prefix, then recurses on its cause.

Otherwise, its Error() text is printed.

func GetTypeMark

func GetTypeMark(err error) errorspb.ErrorTypeMark

GetTypeMark retrieves the ErrorTypeMark for a given error object. This is meant for use in the markers sub-package.

func RegisterLeafDecoder

func RegisterLeafDecoder(theType TypeKey, decoder LeafDecoder)

RegisterLeafDecoder can be used to register new leaf error types to the library. Registered types will be decoded using their own Go type when an error is decoded. Wrappers that have not been registered will be decoded using the opaqueLeaf type.

Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterLeafDecoder().

func RegisterLeafEncoder

func RegisterLeafEncoder(theType TypeKey, encoder LeafEncoder)

RegisterLeafEncoder can be used to register new leaf error types to the library. Registered types will be encoded using their own Go type when an error is encoded. Wrappers that have not been registered will be encoded using the opaqueLeaf type.

Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterLeafEncoder().

func RegisterTypeMigration

func RegisterTypeMigration(previousPkgPath, previousTypeName string, newType error)

RegisterTypeMigration tells the library that the type of the error given as 3rd argument was previously known with type previousTypeName, located at previousPkgPath.

The value of previousTypeName must be the result of calling reflect.TypeOf(err).String() on the original error object. This is usually composed as follows:

[*]<shortpackage>.<errortype>

For example, Go's standard error type has name "*errors.errorString". The asterisk indicates that `errorString` implements the `error` interface via pointer receiver.

Meanwhile, the singleton error type context.DeadlineExceeded has name "context.deadlineExceededError", without asterisk because the type implements `error` by value.

Remember that the short package name inside the error type name and the last component of the package path can be different. This is why they must be specified separately.

func RegisterWrapperDecoder

func RegisterWrapperDecoder(theType TypeKey, decoder WrapperDecoder)

RegisterWrapperDecoder can be used to register new wrapper types to the library. Registered wrappers will be decoded using their own Go type when an error is decoded. Wrappers that have not been registered will be decoded using the opaqueWrapper type.

Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterWrapperDecoder().

func RegisterWrapperEncoder

func RegisterWrapperEncoder(theType TypeKey, encoder WrapperEncoder)

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 registered will be encoded using the opaqueWrapper type.

Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterWrapperEncoder().

func SetWarningFn

func SetWarningFn(fn func(context.Context, string, ...interface{}))

SetWarningFn enables configuration of the warning function.

func TestingWithEmptyMigrationRegistry

func TestingWithEmptyMigrationRegistry() (restore func())

TestingWithEmptyMigrationRegistry is intended for use by tests.

func UnwrapAll

func UnwrapAll(err error) error

UnwrapAll accesses the root cause object of the error. If the error has no cause (leaf error), it is returned directly.

func UnwrapOnce

func UnwrapOnce(err error) (cause error)

UnwrapOnce accesses the direct cause of the error if any, otherwise returns nil.

It supports both errors implementing causer (`Cause()` method, from github.com/pkg/errors) and `Wrapper` (`Unwrap()` method, from the Go 2 error proposal).

Types

type EncodedError

type EncodedError = errorspb.EncodedError

EncodedError is the type of an encoded (and protobuf-encodable) error.

func EncodeError

func EncodeError(ctx context.Context, err error) EncodedError

EncodeError encodes an error.

type Formatter

type Formatter interface {
	error

	// FormatError prints the receiver's first error and returns the next error in
	// the error chain, if any.
	FormatError(p Printer) (next error)
}

A Formatter formats error messages.

type LeafDecoder

type LeafDecoder = func(ctx context.Context, msg string, safeDetails []string, payload proto.Message) error

LeafDecoder is to be provided (via RegisterLeafDecoder above) by additional wrapper types not yet known to this library. A nil return indicates that decoding was not successful.

type LeafEncoder

type LeafEncoder = func(ctx context.Context, err error) (msg string, safeDetails []string, payload proto.Message)

LeafEncoder is to be provided (via RegisterLeafEncoder above) by additional wrapper types not yet known to this library.

type Printer

type Printer interface {
	// Print appends args to the message output.
	Print(args ...interface{})

	// Printf writes a formatted string.
	Printf(format string, args ...interface{})

	// Detail reports whether error detail is requested.
	// After the first call to Detail, all text written to the Printer
	// is formatted as additional detail, or ignored when
	// detail has not been requested.
	// If Detail returns false, the caller can avoid printing the detail at all.
	Detail() bool
}

A Printer formats error messages.

The most common implementation of Printer is the one provided by package fmt during Printf (as of Go 1.13). Localization packages such as golang.org/x/text/message typically provide their own implementations.

type SafeDetailPayload

type SafeDetailPayload struct {
	// OriginalTypeName is the concrete type of the error that the details
	// are coming from.
	OriginalTypeName string
	// ErrorTypeMark is the mark of the error that the details are
	// coming from. This may contain a different type name than
	// OriginalTypeName in case an error type was migrated.
	ErrorTypeMark errorspb.ErrorTypeMark
	// SafeDetails are the PII-free strings.
	SafeDetails []string
}

SafeDetailPayload captures the safe strings for one level of wrapping.

func GetAllSafeDetails

func GetAllSafeDetails(err error) []SafeDetailPayload

GetAllSafeDetails collects the safe details from the given error object and all its causes. The details are collected from outermost to innermost level of cause.

func GetSafeDetails

func GetSafeDetails(err error) (payload SafeDetailPayload)

GetSafeDetails collects the safe details from the given error object. If it is a wrapper, only the details from the wrapper are returned.

func (*SafeDetailPayload) Fill

func (s *SafeDetailPayload) Fill(slice []string) []string

Fill can be used to concatenate multiple SafeDetailPayloads.

type SafeDetailer

type SafeDetailer interface {
	SafeDetails() []string
}

SafeDetailer is an interface that can be implemented by errors that can provide PII-free additional strings suitable for reporting or telemetry.

type TypeKey

type TypeKey string

TypeKey identifies an error for the purpose of looking up decoders. It is equivalent to the "family name" in ErrorTypeMarker.

func GetTypeKey

func GetTypeKey(err error) TypeKey

GetTypeKey retrieve the type key for a given error object. This is meant for use in combination with the Register functions.

type TypeKeyMarker

type TypeKeyMarker interface {
	ErrorKeyMarker() string
}

TypeKeyMarker can be implemented by errors that wish to extend their type name as seen by GetTypeKey().

type WrapperDecoder

type WrapperDecoder = func(ctx context.Context, cause error, msgPrefix string, safeDetails []string, payload proto.Message) error

WrapperDecoder is to be provided (via RegisterWrapperDecoder above) by additional wrapper types not yet known to this library. A nil return indicates that decoding was not successful.

type WrapperEncoder

type WrapperEncoder = func(ctx context.Context, err error) (msgPrefix string, safeDetails []string, payload proto.Message)

WrapperEncoder is to be provided (via RegisterWrapperEncoder above) by additional wrapper types not yet known to this library.