Documentation
¶
Overview ¶
Package errors provides a structured error implementation that makes it easy to set and inspect attributes like an error code, message or stack trace. Using an error wrapper like this throughout an entire application can streamline error handling, logging and debugging.
Errors can be build incrementally by chaining:
New(nil, "abc", InvalidArgument).WithPublicCode(1).WithPublicMessage("message")
Packages/components can define their own functions to create errors more conveniently. A package "xyz" that e.g. usually sets an error code and public message could use the following helper function:
func NewError(code ErrorCode, message string) error {
return New(nil, "xyz", code).WithPublicMessage(message)
}
Index ¶
- func HasInternalCode(err error, code int) bool
- func HasPublicCode(err error, code int) bool
- func Is(err error, code ErrorCode) bool
- func IsAbortedError(err error) bool
- func IsAlreadyExistsError(err error) bool
- func IsCancelledError(err error) bool
- func IsDeadlineExceededError(err error) bool
- func IsFailedPreconditionError(err error) bool
- func IsInternalError(err error) bool
- func IsInvalidArgumentError(err error) bool
- func IsNotFoundError(err error) bool
- func IsOutOfRangeError(err error) bool
- func IsPermissionDeniedError(err error) bool
- func IsUnauthenticatedError(err error) bool
- func IsUnavailableError(err error) bool
- func IsUnimplementedError(err error) bool
- func IsUnknownError(err error) bool
- func UnstackErrors(e error) []error
- type Error
- func (e Error) Error() string
- func (e Error) ToMap() map[string]interface{}
- func (e Error) With(key string, value interface{}) Error
- func (e Error) WithCode(code ErrorCode) Error
- func (e Error) WithInner(inner error) Error
- func (e Error) WithInternalCode(code int) Error
- func (e Error) WithInternalMessage(message string) Error
- func (e Error) WithOrigin(origin string) Error
- func (e Error) WithPublicCode(code int) Error
- func (e Error) WithPublicMessage(message string) Error
- type ErrorCode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasInternalCode ¶
Returns true if the given error is of type Error and has the given code set as the internal error code.
func HasPublicCode ¶
Returns true if the given error is of type Error and has the given code set as the public error code.
func IsAbortedError ¶
func IsAlreadyExistsError ¶
func IsCancelledError ¶
func IsDeadlineExceededError ¶
func IsInternalError ¶
func IsInvalidArgumentError ¶
func IsNotFoundError ¶
func IsOutOfRangeError ¶
func IsPermissionDeniedError ¶
func IsUnauthenticatedError ¶
func IsUnavailableError ¶
func IsUnimplementedError ¶
func IsUnknownError ¶
func UnstackErrors ¶
Return a slice of all the errors found by traversing inner errors.
Types ¶
type Error ¶
type Error struct {
Origin string
// Wrap another error with additional context.
Inner error
StackTrace []byte
// General error code, see comments on type ErrorCode.
Code ErrorCode
// Code or message that is safe to be provided to outside systems/clients/users,
// e.g. an http handler might return these in the response body if a request fails.
// Packages can use this to provide more specific error codes, e.g. 5 = "invalid username" or 6 = "password not strong enough".
// Note that a code should not be 0 since a zero value will be interpreted by this package as no error code set.
PublicCode int
PublicMessage string
// Code or message for internal use only. These could e.g. be written to application logs.
// Note that a code should not be 0 since a zero value will be interpreted by this package as no error code set.
InternalCode int
InternalMessage string
// Any additional key-value pairs can be added here.
KeyVals map[string]interface{}
}
Structured error that can contain additional context about an error, e.g. the component the error originated in, a strack trace or an internal error message. All fields are optional, although it usually makes sense to at least provide the origin and a general error code.
func (Error) ToMap ¶
Returns a map containing the non-zero field values of the error. Useful e.g. to log an error in JSON format.
func (Error) WithInternalCode ¶
func (Error) WithInternalMessage ¶
func (Error) WithOrigin ¶
func (Error) WithPublicCode ¶
func (Error) WithPublicMessage ¶
type ErrorCode ¶
type ErrorCode int
Instead of every package defining their own error codes, we can use a list of common error codes that apply to most situations. E.g. an error with code InvalidArgument might be returned by a function if one of its parameter values is invalid or by a http handler if the request body cannot be decoded because it is not in the correct format. Having a small set of common error codes is also useful to e.g. automatically determine an appropriate HTTP response code by inspecting the error returned from some service method. This approach is copied from protobuf/grpc (see e.g. https://grpc.github.io/grpc/core/md_doc_statuscodes.html).
const ( Unknown ErrorCode = iota Cancelled // Invalid argument was provided, e.g. an invalid date or malformed string. // In contrast to FailedPrecondition the argument is invalid regardless of the state of the system. InvalidArgument DeadlineExceeded NotFound AlreadyExists // Caller does not have permission to execute the operation. PermissionDenied // No or invalid authentication credentials were provided. Unauthenticated // System is not in the correct state to execute the operation. // E.g. in a banking application we cannot perform a transfer if an account doesn't contain any money. FailedPrecondition Aborted OutOfRange Unimplemented Internal )
Source Files