README
¶
strongerrors
A simple Go package for defining common error classes.
Commonly in go applications you either end up defining lots of custom, seminal errors or even custom error types and checking directly against those types. A problem with this pattern is it becomes difficult to wrap errors with extra context without masking the underlying error and potentially causing an error check to miss. The errors package helps to solve some of this where you can use the errors.Wrap pattern to wrap errors and then errors.Cause() to traverse the causal chain. Unfortunately there still exists a problem of requiring deep knowledge and reliance on underlying packages that you may not even control in order to check errors against.
This package defines a common set of error interfaces that can be used in your packages to so that consumers of your package do not need to know about the real error types, or compare even seminal errors. This enables users to worry about the kind of failure rather than its underlying type. These interfaces can be bubbled all the way up the stack to produce proper error codes (or wrapped and converted to another error code) in your RPC of choice (e.g. http or GRPC).
This is mostly taken from github.com/moby/moby/api/errdefs which I helped create to solve some of the above issues in that codebase.
Example Usage
type errNotFound string
func(e errNotFound) Error() string {
return "not found: " + e
}
func(errNotFound) NotFound() {}
type Foo struct{}
func Get(id string) (*Foo, error) {
return nil, errNotFound(id)
}
func(w http.ResponseWriter, req *http.Request) {
id := getID(req)
f, err := Get(id)
if err != nil {
if IsNotFound(err) {
http.Error(w, err.Error(), http.StatusNotFound)
return
}
http.Error{(w, err.Error(), http.StatusInternalServerError)}
return
}
// yay there's a foo object
}
Alternatively, you can use one of the helper functions instead of defining your own error types:
func Get(id string) (*Foo, error) {
return nil, NotFound(errors.New("not found"))
}
There are also helpers for converting errors to status codes (or GRPC status errors), but you can also implement your own mapping.
if err != nil {
code, ok := status.HTTPCode(err)
if !ok {
// error type didn't match a defined type
}
http.Error(w, err.Error(), code)
return
}
err := status.FromGRPC(err)
switch {
case IsNotFound(err):
// do stuff
}
if err != nil {
return ToGRPC(err)
}
These errors can be used in conjuction with errors.Wrap from the erros package. To properly check the error type you should use the Is<Kind> helpers which checks the full causal chain.
Contributions
Contributions are always welcome. Keep in mind that the scope of this package is quite small, and the error classes should be kept to a minimum. The thing to keep in mind when thinking about new error classes is "How will the caller be able to react to this error". The existing errors should cover most error cases.
If you think we're missing a case open an issue so we can discuss it.
Documentation
¶
Overview ¶
Package strongerrors defines a set of error interfaces that packages should use for communicating classes of errors. Errors that cross the package boundary should implement one (and only one) of these interfaces.
Packages should not reference these interfaces directly, only implement them. To check if a particular error implements one of these interfaces, there are helper functions provided (e.g. `Is<SomeError>`) which can be used rather than asserting the interfaces directly. If you must assert on these interfaces, be sure to check the causal chain (`err.Cause()`).
A set of helper functions are provided to take any error and turn it into a specific error class. This frees you from defining the same error classes all over your code. However, you can still implement the error classes ony our own if you desire.
Index ¶
- func AlreadyExists(err error) error
- func Cancelled(err error) error
- func Conflict(err error) error
- func DataLoss(err error) error
- func Deadline(err error) error
- func Exhausted(err error) error
- func Forbidden(err error) error
- func FromContext(ctx context.Context) error
- func InvalidArgument(err error) error
- func IsAlreadyExists(err error) bool
- func IsCancelled(err error) bool
- func IsConflict(err error) bool
- func IsDataLoss(err error) bool
- func IsDeadline(err error) bool
- func IsExhausted(err error) bool
- func IsForbidden(err error) bool
- func IsInvalidArgument(err error) bool
- func IsNotFound(err error) bool
- func IsNotImplemented(err error) bool
- func IsNotModified(err error) bool
- func IsSystem(err error) bool
- func IsUnauthenticated(err error) bool
- func IsUnauthorized(err error) bool
- func IsUnavailable(err error) bool
- func IsUnknown(err error) bool
- func NotFound(err error) error
- func NotImplemented(err error) error
- func NotModified(err error) error
- func System(err error) error
- func Unauthenticated(err error) error
- func Unauthorized(err error) error
- func Unavailable(err error) error
- func Unknown(err error) error
- type ErrAlreadyExists
- type ErrCancelled
- type ErrConflict
- type ErrDataLoss
- type ErrDeadline
- type ErrExhausted
- type ErrForbidden
- type ErrInvalidArgument
- type ErrNotFound
- type ErrNotImplemented
- type ErrNotModified
- type ErrSystem
- type ErrUnauthenticated
- type ErrUnauthorized
- type ErrUnavailable
- type ErrUnknown
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AlreadyExists ¶
AlreadyExists is a helper to create an error of the class with the same name from any error type
func Cancelled ¶
Cancelled is a helper to create an error of the class with the same name from any error type
func Conflict ¶
Conflict is a helper to create an error of the class with the same name from any error type
func DataLoss ¶
DataLoss is a helper to create an error of the class with the same name from any error type
func Deadline ¶
Deadline is a helper to create an error of the class with the same name from any error type
func Exhausted ¶
Exhausted is a helper to create an error of the class with the same name from any error type
func Forbidden ¶
Forbidden is a helper to create an error of the class with the same name from any error type
func FromContext ¶
FromContext returns the error class from the passed in context
func InvalidArgument ¶
InvalidArgument is a helper to create an error of the class with the same name from any error type
func IsAlreadyExists ¶
IsAlreadyExists returns if the passed in error is a AlreadyExists error
func IsCancelled ¶
IsCancelled returns if the passed in error is an ErrCancelled
func IsConflict ¶
IsConflict returns if the passed in error is an ErrConflict
func IsDataLoss ¶
IsDataLoss returns if the passed in error is an ErrDataLoss
func IsDeadline ¶
IsDeadline returns if the passed in error is an ErrDeadline
func IsExhausted ¶
IsExhausted returns if the passed in error is an ErrDeadline
func IsForbidden ¶
IsForbidden returns if the passed in error is an ErrForbidden
func IsInvalidArgument ¶
IsInvalidArgument returns if the passed in error is an ErrInvalidParameter
func IsNotFound ¶
IsNotFound returns if the passed in error is an ErrNotFound
func IsNotImplemented ¶
IsNotImplemented returns if the passed in error is an ErrNotImplemented
func IsNotModified ¶
IsNotModified returns if the passed in error is a NotModified error
func IsUnauthenticated ¶
IsUnauthenticated returns if the the passed in error is an ErrUnauthenticated
func IsUnauthorized ¶
IsUnauthorized returns if the the passed in error is an ErrUnauthorized
func IsUnavailable ¶
IsUnavailable returns if the passed in error is an ErrUnavailable
func NotFound ¶
NotFound is a helper to create an error of the class with the same name from any error type
func NotImplemented ¶
NotImplemented is a helper to create an error of the class with the same name from any error type
func NotModified ¶
NotModified is a helper to create an error of the class with the same name from any error type
func System ¶
System is a helper to create an error of the class with the same name from any error type
func Unauthenticated ¶
Unauthenticated is a helper to create an error of the class with the same name from any error type
func Unauthorized ¶
Unauthorized is a helper to create an error of the class with the same name from any error type
func Unavailable ¶
Unavailable is a helper to create an error of the class with the same name from any error type
Types ¶
type ErrAlreadyExists ¶
type ErrAlreadyExists interface {
AlreadyExists()
}
ErrAlreadyExists is a special case of ErrNotModified which signals that the desired object already exists
type ErrCancelled ¶
type ErrCancelled interface {
Cancelled()
}
ErrCancelled signals that the action was cancelled.
type ErrConflict ¶
type ErrConflict interface {
Conflict()
}
ErrConflict signals that some internal state conflicts with the requested action and can't be performed. A change in state should be able to clear this error.
type ErrDataLoss ¶
type ErrDataLoss interface {
DataLoss()
}
ErrDataLoss indicates that data was lost or there is data corruption.
type ErrDeadline ¶
type ErrDeadline interface {
DeadlineExceeded()
}
ErrDeadline signals that the deadline was reached before the action completed.
type ErrExhausted ¶
type ErrExhausted interface {
Exhausted()
}
ErrExhausted indicates that the action cannot be performed because some resource is exhausted.
type ErrForbidden ¶
type ErrForbidden interface {
Forbidden()
}
ErrForbidden signals that the requested action cannot be performed under any circumstances. When a ErrForbidden is returned, the caller should never retry the action.
type ErrInvalidArgument ¶
type ErrInvalidArgument interface {
InvalidArgument()
}
ErrInvalidArgument signals that the user input is invalid
type ErrNotFound ¶
type ErrNotFound interface {
NotFound()
}
ErrNotFound signals that the requested object doesn't exist
type ErrNotImplemented ¶
type ErrNotImplemented interface {
NotImplemented()
}
ErrNotImplemented signals that the requested action/feature is not implemented on the system as configured.
type ErrNotModified ¶
type ErrNotModified interface {
NotModified()
}
ErrNotModified signals that an action can't be performed because it's already in the desired state
type ErrSystem ¶
type ErrSystem interface {
System()
}
ErrSystem signals that some internal error occurred. An example of this would be a failed mount request.
type ErrUnauthenticated ¶
type ErrUnauthenticated interface {
Unauthenticated()
}
ErrUnauthenticated is used to indicate that the caller cannot be identified.
type ErrUnauthorized ¶
type ErrUnauthorized interface {
}
ErrUnauthorized is used to signify that the user is not authorized to perform a specific action
type ErrUnavailable ¶
type ErrUnavailable interface {
}
ErrUnavailable signals that the requested action/subsystem is not available.
type ErrUnknown ¶
type ErrUnknown interface {
Unknown()
}
ErrUnknown signals that the kind of error that occurred is not known.
Source Files
Directories