Documentation ¶
Overview ¶
Package vice provides bad behaviours for Go 2/1.13+ error values.
vice defines common types of errors, as seen in existing packages, as expressed through methods on the errors of the form:
IsXXX() bool
Errors of these types can be created and checked by vice. When used with Go 2 error value wrapping, intermediate code layers don't have to know about the behaviours or types of errors, and may add additional information, without altering how the error is handled in the topmost layer:
// Create an error when your database can't find a user record err := vice.New(vice.NotFound, "user not found") // many intermediate layers of code, passing the error on, and wrapping it // ... // In your central request handler middleware if vice.Is(err, vice.NotFound) { // respond appropriately to the client }
Index ¶
- func Errorf(v Vice, format string, a ...interface{}) error
- func Is(err error, v Vice) bool
- func New(v Vice, text string) error
- func Seal(err error, v Vice, text string) error
- func Sealf(err error, v Vice, format string, a ...interface{}) error
- func Wrap(err error, v Vice, text string) error
- func Wrapf(err error, v Vice, format string, a ...interface{}) error
- type Vice
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Errorf ¶
Errorf returns an error that formats as the format specifier text, and implements the behaviour described by the given Vice.
The returned error contains a Frame set to the caller's location and implements Formatter to show this information when printed with details.
func Is ¶
Is reports whether any error in err's chain implements the behaviour described by the provided Vice, v.
Example ¶
package main import ( "fmt" "github.com/jbowes/vice" ) func main() { err := vice.New(vice.Timeout, "request timed out") fmt.Println(vice.Is(err, vice.Timeout)) }
Output: true
Example (CheckingOtherImplementors) ¶
package main import ( "fmt" "github.com/jbowes/vice" ) // DatabaseError implements the error interface, and the Closed error value // interface, but is not an error generated or defined in vice. type DatabaseError struct { closed bool } func (d *DatabaseError) Error() string { return "database error" } func (d *DatabaseError) Closed() bool { return d.closed } func someDatabaseOperation() error { return &DatabaseError{closed: true} } func main() { if err := someDatabaseOperation(); vice.Is(err, vice.Closed) { fmt.Println("database is already closed") } }
Output: database is already closed
Example (ErrorChain) ¶
package main import ( "fmt" "github.com/jbowes/vice" ) func main() { err := vice.New(vice.Timeout, "request timed out") err2 := vice.Wrap(err, vice.Closed, "connection closed") fmt.Println(vice.Is(err2, vice.Timeout)) }
Output: true
func New ¶
New returns an error that formats as the given text, and implements the behaviour described by the given Vice.
The returned error contains a Frame set to the caller's location and implements Formatter to show this information when printed with details.
func Seal ¶
Seal returns an error wrapping err with the supplied text, and a frame from the caller's stack. The returned error implements the behaviour described by the given Vice. If err is nil, Wrap returns nil.
The error returned does not implment the Unwrap method.
Example ¶
package main import ( "fmt" "github.com/jbowes/vice" ) func main() { err := vice.New(vice.Timeout, "request timed out") // Seal prevents programmatic inspection of any errors lower in the chain err2 := vice.Seal(err, vice.Closed, "connection closed") fmt.Println(vice.Is(err2, vice.Timeout)) }
Output: false
func Sealf ¶
Sealf returns an error wrapping err with the supplied format specifier, and a frame from the caller's stack. The returned error implements the behaviour described by the given Vice. If err is nil, Wrap returns nil.
The error returned does not implment the Unwrap method.
func Wrap ¶
Wrap returns an error wrapping err with the supplied text, and a frame from the caller's stack. The returned error implements the behaviour described by the given Vice. If err is nil, Wrap returns nil.
The error returned implments the Unwrap method, for programatically extracting the error chain.
func Wrapf ¶
Wrapf returns an error wrapping err with the supplied format specifier, and a frame from the caller's stack. The returned error implements the behaviour described by the given Vice. If err is nil, Wrap returns nil.
The error returned implments the Unwrap method, for programatically extracting the error chain.
Types ¶
type Vice ¶
type Vice uint64
Vice is the type used to enumerate all common behaviours for errors.
const ( // NoVice indicates there is an unknown error. NoVice Vice = 0 // Timeout means the operation has timed out before the end of the // operation. Timeout Vice = 1 << iota // Temporary indicates a temporary underlying issue. The consumer should // retry. Temporary // Closed means the consumer closed the connection to the underlying // service. Closed // AuthRequired indicates the operation needs authentication, but none is // provided. AuthRequired // AuthFailed indicates the operation could not be authenticated using the // provided authentication schema. AuthFailed // Permission indicates that the consumer does not have permissions to // execute the specified operation. Permission // Conflict indicates that an attempt to create a resource failed because it // already exists. Conflict // InvalidArgument indicates the client provided bad input. This differs // from PreconditionFailed as this is based on the given arguments rather // than the state of the system. For example, an invalid HTTP scheme. InvalidArgument // NotFound indicates that a requested resource was not found. NotFound // Internal indicates that the service expected different behaviour than it // produced. If you see one of these errors, the service is very broken. Internal // Canceled means the operation has been canceled, typically by the // consumer. Canceled // PreconditionFailed indicates that the state of the system does not meet the // requirements to fulfull the request. // For example, a directory to be deleted may be non-empty, an rmdir // operation is applied to a non-directory, etc. PreconditionFailed )
The common error behaviours.
Excluding NoVice, each value corresponds to an interface with a single method of the same name as the value that returns a bool.
For example, the Closed Vice is used to create and check for errors that implement:
interface { Closed() bool }
func ForError ¶ added in v0.2.0
ForError returns a wrapped vice type found for the given error.
This loops over all types to determine if the the error wraps that type. This means this function is not deterministic if multiple `Wrap()` calls have been used on the given error. To make sure it is deterministic, use the `Seal()` method.
If the error is not wrapped or sealed with this package, it will return NoVice.
This can be useful for map lookups to map specific types to descriptive messages.