README
¶
Failure
The failure package builds upon the errors
package, implementing a strategy called Opaque errors which I first learned
about from an article Don't just check errors handle them gracefully
by Dave Cheney.
The failure package concentrates on an api that categories errors to better articulate your intent in code.
Usage
Server Failure
Describe general server errors. If I don't have a specific category for the
error I use this. When mapping to http errors this would map to 500
System Failure
Means the same thing as Server but you prefer the name System instead. Note
that you can not mix and match, meaning IsServer will not return true for a
System
Startup
Is used to indicate failures that prevented the system from starting up
Shutdown
Is used to signal a shutdown of the system.
Defer
Categorize errors that originated inside a defer call
BadRequest
Categories errors that occurred because the accepted request was bad in some way
Validation
Describes an error that occurred because some validation failed
Config
Describes a failure caused by invalid configuration
InvalidParam
Describes a failure cause by a bad function param or struct field
NotAuthorized, NotAuthenticated, Forbidden
Describe auth errors
NotFound
Describes a failure due to the absence of a resource
Multiple
This is a direct port of hashicorp multierror. Many thanks to the hard work and great code produced my the hashicorp team. I integrated their code into this codebase to produce a seamless api when using multiple errors in the failure package.
NOTE: if you're using this package just because of multiple errors then I would use the hashicorps instead. I simply repurposed their code to fit into the failure system because I liked the way it reads.
The Append function is used to create a list of errors. This function
behaves a lot like the Go built-in append function: it doesn't matter
if the first argument is nil, a failure.Error, or any other error,
the function behaves as you would expect.
var result error
if err := step1(); err != nil {
result = failure.Append(result, err)
}
if err := step2(); err != nil {
result = failure.Append(result, err)
}
return result
Customizing the formatting of the errors
By specifying a custom ErrorFormat, you can customize the format
of the Error() string function:
var result *failure.Multi
// ... accumulate errors here, maybe using Append
if result != nil {
result.Formatter = func([]error) string {
return "errors!"
}
}
Extracting an error
// Assume err is a failure value
err := somefunc()
if failure.IsMultiple(err) {
// It has it, and now errRich is populated.
}
var result []error
result, ok := failure.MultipleResult(err)
if ok {
// Result will be []error in the failure.Multi
}
Timeout
Describes failures that occurred because something took too long
General Usage
func(db *Client) Insert(ctx context.Context, model business.Model) error {
...
if !db.Validatea(model) {
return failure.Validation("Model is not valid")
}
out, err := db.api.Put(ctx, in)
if err != nil {
return failure.ToSystem(err, "db.api.Put failed for (%s)", in.ID)
}
...
}
func (h *Handler) Handle(ctx context.Context, w http.ResponseWrite, r http.Request) error {
...
if err = db.Insert(ctx, model); err != nil {
switch {
case: failure.IsValidation(err):
// Return 400
default:
// return 500
}
}
}
Documentation
¶
Overview ¶
Package failure implements an opaque error pattern based several of the most common types of errors that occur when developing microservices.
Index ¶
- Constants
- func BadRequest(format string, a ...interface{}) error
- func Config(format string, a ...interface{}) error
- func Defer(format string, a ...interface{}) error
- func Flatten(err error) error
- func Forbidden(format string, a ...interface{}) error
- func Ignore(format string, a ...interface{}) error
- func InvalidParam(format string, a ...interface{}) error
- func IsAnyAuthFailure(e error) bool
- func IsBadRequest(e error) bool
- func IsConfig(e error) bool
- func IsDefer(e error) bool
- func IsForbidden(e error) bool
- func IsIgnore(e error) bool
- func IsInvalidParam(e error) bool
- func IsMultiple(e error) bool
- func IsNotAuthenticated(e error) bool
- func IsNotAuthorized(e error) bool
- func IsNotFound(e error) bool
- func IsServer(err error) bool
- func IsShutdown(e error) bool
- func IsStartup(e error) bool
- func IsSystem(err error) bool
- func IsTimeout(e error) bool
- func IsValidation(e error) bool
- func ListFormatFn(es []error) string
- func MultiResult(e error) ([]error, bool)
- func NotAuthenticated(format string, a ...interface{}) error
- func NotAuthorized(format string, a ...interface{}) error
- func NotFound(format string, a ...interface{}) error
- func Server(format string, a ...interface{}) error
- func Shutdown(format string, a ...interface{}) error
- func Startup(format string, a ...interface{}) error
- func System(format string, a ...interface{}) error
- func Timeout(format string, a ...interface{}) error
- func ToBadRequest(e error, format string, a ...interface{}) error
- func ToConfig(e error, format string, a ...interface{}) error
- func ToDefer(e error, format string, a ...interface{}) error
- func ToForbidden(e error, format string, a ...interface{}) error
- func ToIgnore(e error, format string, a ...interface{}) error
- func ToInvalidParam(e error, format string, a ...interface{}) error
- func ToNotAuthenticated(e error, format string, a ...interface{}) error
- func ToNotAuthorized(e error, format string, a ...interface{}) error
- func ToNotFound(e error, format string, a ...interface{}) error
- func ToServer(e error, format string, a ...interface{}) error
- func ToShutdown(e error, format string, a ...interface{}) error
- func ToStartup(e error, format string, a ...interface{}) error
- func ToSystem(e error, format string, a ...interface{}) error
- func ToTimeout(e error, format string, a ...interface{}) error
- func ToValidation(e error, format string, a ...interface{}) error
- func Validation(format string, a ...interface{}) error
- func Wrap(err error, msg string, a ...interface{}) error
- type Group
- type Multi
- type MultiFormatFn
Constants ¶
const ( SystemMsg = "system failure" ServerMsg = "server failure" NotFoundMsg = "not found failure" NotAuthorizedMsg = "not authorized failure" NotAuthenticatedMsg = "not authenticated failure" ForbiddenMsg = "access is forbidden" ValidationMsg = "validation failure" DeferMsg = "failure occurred inside defer" IgnoreMsg = "ignore failure" ConfigMsg = "config failure" InvalidParamMsg = "invalid param failure" ShutdownMsg = "system shutdown failure" BadRequestMsg = "bad request" TimeoutMsg = "timeout failure" StartupMsg = "failure occurred during startup" )
Variables ¶
This section is empty.
Functions ¶
func BadRequest ¶ added in v0.6.0
BadRequest is used to signal that the app should shut down.
func Config ¶ added in v0.3.0
Config is used to signify that error occurred when processing the application configuration
func Flatten ¶ added in v0.9.0
Flatten flattens the given error, merging any *Errors together into a single *Error.
func Forbidden ¶ added in v0.7.0
Forbidden is used to signify either not authenticated or not authorized
func Ignore ¶
Ignore is used to signify that error should not be acted on, it's up to the handler to decide to log these errors or not.
func InvalidParam ¶ added in v0.4.0
InvalidParam is to indicate that the param of a function or any parameter in general is invalid
func IsAnyAuthFailure ¶ added in v0.7.0
IsAnyAuthFailure can be used to determine if any of the following we used: NotAuthenticated, NotAuthorized, Forbidden
func IsBadRequest ¶ added in v0.6.0
func IsForbidden ¶ added in v0.7.0
func IsInvalidParam ¶ added in v0.4.0
func IsMultiple ¶ added in v0.9.0
func IsNotAuthenticated ¶ added in v0.7.0
func IsNotAuthorized ¶ added in v0.7.0
func IsNotFound ¶
func IsShutdown ¶ added in v0.5.0
func IsValidation ¶
func ListFormatFn ¶ added in v0.9.0
ListFormatFn is a basic formatter that outputs the number of errors that occurred along with a bullet point list of the errors.
func MultiResult ¶ added in v0.9.0
func NotAuthenticated ¶ added in v0.7.0
NotAuthenticated is used to signify that a resource's identity verification failed. They are not who they claim to be
func NotAuthorized ¶ added in v0.7.0
NotAuthorized is used to signify that a resource does not have sufficient access to perform a given task
func NotFound ¶
NotFound is used to signify that whatever resource you were looking for does not exist and that fact it does not exist is an error.
func Server ¶
Server has the same meaning as Platform or System, it can be used instead if you don't like how Platform or System reads in your code.
func Startup ¶ added in v0.9.0
Startup is used to signify a failure preventing the system from starting up
func System ¶
System is has the same meaning as Platform or Server, it can be used instead if you don't like how Platform reads in your code
func Timeout ¶ added in v0.8.0
Timeout is used to signify that error because something was taking too long
func ToBadRequest ¶ added in v0.6.0
func ToForbidden ¶ added in v0.7.0
func ToIgnore ¶
ToIgnore converts `e` into the root cause of ignoreErr, it informs the system to ignore error. Used typically to log results and do not act on the error itself.
func ToInvalidParam ¶ added in v0.4.0
func ToNotAuthenticated ¶ added in v0.7.0
func ToNotAuthorized ¶ added in v0.7.0
func ToNotFound ¶
func ToShutdown ¶ added in v0.5.0
func ToValidation ¶
func Validation ¶
Validation is used to signify that a validation rule as been violated
Types ¶
type Group ¶ added in v0.9.0
type Group struct {
// contains filtered or unexported fields
}
Group is a collection of goroutines which return errors that need to be coalesced.
type Multi ¶ added in v0.9.0
type Multi struct {
Failures []error
Formatter MultiFormatFn
}
func Multiple ¶ added in v0.9.0
func Multiple(errs []error, opt ...MultiFormatFn) *Multi
func (*Multi) ErrorOrNil ¶ added in v0.9.0
ErrorOrNil returns an error interface if this Error represents a list of errors, or returns nil if the list of errors is empty. This function is useful at the end of accumulation to make sure that the value returned represents the existence of errors.
func (*Multi) Unwrap ¶ added in v0.9.0
Unwrap returns an error from Multi (or nil if there are no errors). This error returned will further support Unwrap to get the next error, etc. The order will match the order of Errors in the failure.Multi at the time of calling.
The resulting error supports errors.As/Is/Unwrap, so you can continue to use the stdlib errors package to introspect further.
This will perform a shallow copy of the errors slice. Any errors appended to this error after calling Unwrap will not be available until a new Unwrap is called on the failure.Multi.
func (*Multi) WrappedErrors ¶ added in v0.9.0
WrappedErrors returns the list of errors that this Error is wrapping. It is an implementation of the errwrap.Wrapper interface so that failure.Multi can be used with that library.
This method is not safe to be called concurrently. Unlike accessing the Failures field directly, this function also checks if the Multi is nil to prevent a null-pointer panic. It satisfies the errwrap.Wrapper interface.
Source Files