Documentation ¶
Overview ¶
Package errors provides extra functionalities to that of Go's stdlib errors package.
Index ¶
- Constants
- Variables
- func DescWrap(descriptor ErrorDescriptor, details error) error
- func HasDescriptor(err error, desc ErrorDescriptor) bool
- func HasDescriptorText(err error, descText string) bool
- func IsAccessError(err error) bool
- func IsAccessForbidden(err error) bool
- func IsArgumentError(err error) bool
- func IsArgumentErrorWithName(err error, argName string) bool
- func IsAuthorizationInvalid(err error) bool
- func IsCallError(e error) bool
- func IsContextError(err error) bool
- func IsContextUnspecifiedError(err error) bool
- func IsEntInvalidError(err error) bool
- func IsEntNotFoundError(err error) bool
- func IsEntityError(err error) bool
- func IsValueMalformedError(err error) bool
- func UnwrapErrorSet(err error) []error
- func Wrap(contextMessage string, causeErr error) error
- type AccessError
- type AccessErrorBuilder
- type ArgumentError
- type ArgumentErrorBuilder
- func Arg(argName string, fields ...NamedError) ArgumentErrorBuilder
- func ArgD(argName string, desc ErrorDescriptor, fields ...NamedError) ArgumentErrorBuilder
- func ArgDW(argName string, desc ErrorDescriptor, detailingError error, ...) ArgumentErrorBuilder
- func ArgMW(argName, contextMessage string, err error, fields ...NamedError) ArgumentErrorBuilder
- func ArgMsg(argName, errMsg string, fields ...NamedError) ArgumentErrorBuilder
- func ArgUnspecified(argName string) ArgumentErrorBuilder
- func ArgValueUnsupported(argName string) ArgumentErrorBuilder
- func ArgW(argName string, err error, fields ...NamedError) ArgumentErrorBuilder
- type ArgumentErrorChecker
- type CallError
- type CallErrorSet
- type ContextError
- type EntityError
- func Ent(entityIdentifier string, err error) EntityError
- func EntFields(entityIdentifier string, fields ...EntityError) EntityError
- func EntInvalid(entityIdentifier string, details error) EntityError
- func EntMsg(entityIdentifier string, errMsg string) EntityError
- func EntNotFound(entityIdentifier string, details error) EntityError
- func UnwrapEntityErrorSet(err error) []EntityError
- type EntityErrorSet
- type ErrorDescriptor
- type ErrorSet
- type NamedError
- type NamedErrorBuilder
- type OperationError
- type OperationErrorBuilder
- type Unwrappable
- type ValueError
- type ValueErrorBuilder
- type ValueErrorDescriptor
Constants ¶
const ( // ErrEntityNotFound is used when the entity with the specified name // cannot be found in the system or the system does not want to tell // existence of the entity. ErrEntityNotFound = valueConstantErrorDescriptor("not found") // ErrEntityConflict is used when the process of creating a new entity // fails because an entity with the same name already exists. ErrEntityConflict = valueConstantErrorDescriptor("conflict") // ErrEntityUnreachable is used to describe that the system is unable // to reach the system responsible of the specified entity. ErrEntityUnreachable = valueConstantErrorDescriptor("unreachable") // ErrEntityGone is used to describe when an entity is no longer available. // // If the entity was sensitive, it's recommended to use ErrEntityNotFound // instaed. ErrEntityGone = valueConstantErrorDescriptor("gone") )
const ( // Value was not provided (nil) ErrValueUnspecified = valueConstantErrorDescriptor("unspecified") // Value was provided but empty ErrValueEmpty = valueConstantErrorDescriptor("empty") ErrValueMalformed = valueConstantErrorDescriptor("malformed") // The value provided does not match the one required by the system ErrValueMismatch = valueConstantErrorDescriptor("mismatch") // The value provided is currently not supported or not recognized by // the system ErrValueUnsupported = valueConstantErrorDescriptor("unsupported") ErrValueTypeUnsupported = valueConstantErrorDescriptor("type unsupported") // If everything else fails ErrValueInvalid = valueConstantErrorDescriptor("invalid") )
const ErrAccessForbidden = accessErrorDescriptor("forbidden")
const ErrAuthorizationInvalid = constantErrorDescriptor("authorization invalid")
const (
ErrPlaceholder = constantErrorDescriptor(placeholderErrorText)
)
const ( // ErrUnimplemented is used to declare that a functionality, or part of it, // has not been implemented. This could be well mapped to some protocols' // status code, e.g., HTTP's 501 and gRPC's 12 . ErrUnimplemented = constantErrorDescriptor("unimplemented") )
Variables ¶
var ( As = errors.As Is = errors.Is New = errors.New // Prefer Msg instead as it has better semantic Msg = errors.New Unwrap = errors.Unwrap )
Wraps Go's errors
Functions ¶
func DescWrap ¶
func DescWrap(descriptor ErrorDescriptor, details error) error
func HasDescriptor ¶
func HasDescriptor(err error, desc ErrorDescriptor) bool
func HasDescriptorText ¶
func IsAccessError ¶
func IsAccessForbidden ¶
func IsArgumentError ¶
func IsArgumentErrorWithName ¶
func IsAuthorizationInvalid ¶
func IsCallError ¶
func IsContextError ¶
func IsEntInvalidError ¶
func IsEntNotFoundError ¶
func IsEntityError ¶
func IsValueMalformedError ¶
func UnwrapErrorSet ¶
UnwrapErrorSet returns the contained error instances if err is indeed a ErrorSet.
Types ¶
type AccessError ¶
type AccessError interface { ContextError AccessError() AccessError }
An AccessError is a specialization of ContextError.
type AccessErrorBuilder ¶
type AccessErrorBuilder interface { AccessError // Desc returns a copy with descriptor is set to desc. Desc(desc ErrorDescriptor) AccessErrorBuilder // DescMsg sets the descriptor with the provided string. For the best // experience, descMsg should be defined as a constant so that the error // users could use it to identify an error. For non-constant descriptor // use the Wrap method. DescMsg(descMsg string) AccessErrorBuilder // Wrap returns a copy with wrapped error is set to detailingError. Wrap(detailingError error) AccessErrorBuilder }
func Access ¶
func Access() AccessErrorBuilder
TODO: should be Access(resourceIdentifiers ...string)
func AccessForbidden ¶
func AccessForbidden() AccessErrorBuilder
func AuthorizationInvalid ¶
func AuthorizationInvalid() AccessErrorBuilder
type ArgumentError ¶
type ArgumentError interface { CallError Unwrappable // ArgumentName returns the name of the offending argument. It might // be empty if there's only one argument. ArgumentName() string Descriptor() ErrorDescriptor FieldErrors() []NamedError }
ArgumentError abstracts all errors which was caused by error in one of the arguments in a function call. This class of error has the similar concept as 4xx status codes in HTTP, and thus can be mapped into one of these code when used in HTTP request handlers.
func AsArgumentError ¶
func AsArgumentError(err error) ArgumentError
AsArgumentError returns non-nil if err is indeed an ArgumentError.
type ArgumentErrorBuilder ¶
type ArgumentErrorBuilder interface { ArgumentError // Desc returns a copy with descriptor is set to desc. Desc(desc ErrorDescriptor) ArgumentErrorBuilder // DescMsg sets the descriptor with the provided string. For the best // experience, descMsg should be defined as a constant so that the error // users could use it to identify an error. For non-constant descriptor // use the Wrap method. DescMsg(descMsg string) ArgumentErrorBuilder // Hint provides a clue for the developers on how to fix the error. Hint(hintText string) ArgumentErrorBuilder Fieldset(fields ...NamedError) ArgumentErrorBuilder // Rewrap collects descriptor, wrapped, and fields from err and include // them into the new error. Rewrap(err error) ArgumentErrorBuilder // Wrap returns a copy with wrapped error is set to detailingError. Wrap(detailingError error) ArgumentErrorBuilder }
func Arg ¶
func Arg(argName string, fields ...NamedError) ArgumentErrorBuilder
func ArgD ¶
func ArgD(argName string, desc ErrorDescriptor, fields ...NamedError) ArgumentErrorBuilder
func ArgDW ¶
func ArgDW(argName string, desc ErrorDescriptor, detailingError error, fields ...NamedError) ArgumentErrorBuilder
func ArgMW ¶
func ArgMW(argName, contextMessage string, err error, fields ...NamedError) ArgumentErrorBuilder
func ArgMsg ¶
func ArgMsg(argName, errMsg string, fields ...NamedError) ArgumentErrorBuilder
func ArgUnspecified ¶
func ArgUnspecified(argName string) ArgumentErrorBuilder
ArgUnspecified describes that argument with name argName is unspecified.
func ArgValueUnsupported ¶
func ArgValueUnsupported(argName string) ArgumentErrorBuilder
ArgValueUnsupported creates an ArgumentError with name is set to the value of argName and descriptor is set to ErrValueUnsupported.
func ArgW ¶
func ArgW(argName string, err error, fields ...NamedError) ArgumentErrorBuilder
type ArgumentErrorChecker ¶
type ArgumentErrorChecker struct {
// contains filtered or unexported fields
}
func ArgumentErrorCheck ¶
func ArgumentErrorCheck(err error) ArgumentErrorChecker
func (ArgumentErrorChecker) HasDesc ¶
func (checker ArgumentErrorChecker) HasDesc(desc ErrorDescriptor) ArgumentErrorChecker
func (ArgumentErrorChecker) HasName ¶
func (checker ArgumentErrorChecker) HasName(argName string) ArgumentErrorChecker
func (ArgumentErrorChecker) HasWrapped ¶
func (checker ArgumentErrorChecker) HasWrapped(err error) ArgumentErrorChecker
func (ArgumentErrorChecker) IsTrue ¶
func (checker ArgumentErrorChecker) IsTrue() bool
type CallError ¶
func UnwrapCallErrorSet ¶
UnwrapCallErrorSet returns the contained CallError instances if err is indeed a CallErrorSet.
type CallErrorSet ¶
CallErrorSet is an interface to combine multiple CallError instances into a single CallError.
In some cases, it's prefered to have all call-related errors for a call a list. This way, the user could fix them all in one go.
func CallSet ¶
func CallSet(callErrors ...CallError) CallErrorSet
CallSet creates a compound error comprised of multiple instances of CallError. The resulting error is also a CallError.
type ContextError ¶
type ContextError interface { CallError ContextError() ContextError }
func Context ¶
func Context(details error, fields ...EntityError) ContextError
func ContextFields ¶
func ContextFields(fields ...EntityError) ContextError
func ContextUnspecified ¶
func ContextUnspecified() ContextError
func CtxM ¶
func CtxM(msg string, fields ...EntityError) ContextError
type EntityError ¶
type EntityError interface { Unwrappable EntityIdentifier() string }
EntityError is a class of errors describing errors in entities.
An entity here is defined as anything that has identifier associated to it. For example, a web page is an entity with its URL is the identifier.
func Ent ¶
func Ent(entityIdentifier string, err error) EntityError
Ent creates an instance of error that conforms EntityError. It takes entityIdentifier which could be the name, key or URL of an entity. The entityIdentifier should describe the 'what' while err describes the 'why'.
// Describes that the file ".config.yaml" does not exist. errors.Ent("./config.yaml", os.ErrNotExist) // Describes that the site "https://example.com" is unreachable. errors.Ent("https://example.com/", errors.Msg("unreachable"))
func EntFields ¶
func EntFields(entityIdentifier string, fields ...EntityError) EntityError
EntFields is used to create an error that describes multiple field errors of an entity.
func EntInvalid ¶
func EntInvalid(entityIdentifier string, details error) EntityError
EntInvalid creates an EntityError with err set to DataErrInvalid.
func EntMsg ¶
func EntMsg(entityIdentifier string, errMsg string) EntityError
EntMsg creates an instance of error from an entitity identifier and the error message which describes why the entity is considered error.
func EntNotFound ¶
func EntNotFound(entityIdentifier string, details error) EntityError
func UnwrapEntityErrorSet ¶
func UnwrapEntityErrorSet(err error) []EntityError
UnwrapEntityErrorSet returns the contained EntityError instances if err is indeed a EntityErrorSet.
type EntityErrorSet ¶
type EntityErrorSet interface { ErrorSet EntityErrors() []EntityError }
EntityErrorSet is an interface to combine multiple EntityError instances into a single error.
func EntSet ¶
func EntSet(entityErrors ...EntityError) EntityErrorSet
EntSet creates a compound error comprised of multiple instances of EntityError. Note that the resulting error is not an EntityError because it has no identity.
type ErrorDescriptor ¶
A ErrorDescriptor provides the description-part of an error.
In a good practice, an error contains an information about *what* and *why*. A ErrorDescriptor abstracts the answers to the *why*.
"User is not found" could be break down into "User" as the answer to the *what*, and "not found" as the answer to the *why*. Here, the ErrorDescriptor will contain the "not found".
This interface could be used to describe any *what*, like the method in "method not implemented". For specific to data, see DataDescriptorError.
func UnwrapDescriptor ¶
func UnwrapDescriptor(err error) ErrorDescriptor
type ErrorSet ¶
ErrorSet is an abstraction for an error that holds multiple errors. This is usually used for operations that collects all errors before returning.
type NamedError ¶
type NamedError interface { Unwrappable Name() string Value() any }
func UnwrapFieldErrors ¶
func UnwrapFieldErrors(err error) []NamedError
type NamedErrorBuilder ¶
type NamedErrorBuilder interface { NamedError // Desc returns a copy with descriptor is set to desc. Desc(desc ErrorDescriptor) NamedErrorBuilder // DescMsg sets the descriptor with the provided string. For the best // experience, descMsg should be defined as a constant so that the error // users could use it to identify an error. For non-constant descriptor // use the Wrap method. DescMsg(descMsg string) NamedErrorBuilder // Hint provides a clue for the developers on how to fix the error. Hint(hintText string) NamedErrorBuilder Fieldset(fields ...NamedError) NamedErrorBuilder // Rewrap collects descriptor, wrapped, and fields from err and include // them into the new error. Rewrap(err error) NamedErrorBuilder // Value provides the value associated to the name. Val(value any) NamedErrorBuilder // Wrap returns a copy with wrapped error is set to detailingError. Wrap(detailingError error) NamedErrorBuilder }
func N ¶
func N(name string) NamedErrorBuilder
func NamedValueMalformed ¶
func NamedValueMalformed(valueName string) NamedErrorBuilder
NamedValueMalformed creates an NamedValue with name is set to the value of valueName and descriptor is set to ErrValueMalformed.
func NamedValueUnsupported ¶
func NamedValueUnsupported(valueName string) NamedErrorBuilder
NamedValueUnsupported creates an NamedValue with name is set to the value of valueName and descriptor is set to ErrValueUnsupported.
type OperationError ¶
type OperationError interface { Unwrappable // Returns the name of the operation. OperationName() string }
type OperationErrorBuilder ¶
type OperationErrorBuilder interface { OperationError // Hint provides a clue for the developers on how to fix the error. Hint(hintText string) OperationErrorBuilder Params(params ...NamedError) OperationErrorBuilder // Wrap returns a copy with wrapped error is set to detailingError. Wrap(detailingError error) OperationErrorBuilder }
func Op ¶
func Op(operationName string, detailingError error) OperationErrorBuilder
type Unwrappable ¶
Unwrappable is an error which holds inner error, which usually provides the cause if this error.
type ValueError ¶
type ValueError interface { error ValueError() ValueError }
ValueError describes where the error is.
type ValueErrorBuilder ¶
type ValueErrorBuilder interface { ValueError // Wrap returns a copy with wrapped error is set to detailingError. Wrap(detailingError error) ValueErrorBuilder }
func ValueMalformed ¶
func ValueMalformed() ValueErrorBuilder
type ValueErrorDescriptor ¶
type ValueErrorDescriptor interface { ErrorDescriptor ValueErrorDescriptorString() string }