Add context to errors, including automatic stack capture, cause chains, HTTP status code, user messages, and arbitrary values.
The package is largely based on http://github.com/go-errors/errors, with additional inspiration from https://github.com/go-errgo/errgo and https://github.com/amattn/deeperror.
go get github.com/ansel1/merry/v2
Wrapped errors work a lot like google's golang.org/x/net/context package: each wrapper error contains the inner error, a key, and a value. Like contexts, errors are immutable: adding a key/value to an error always creates a new error which wraps the original.
This package comes with built-in support for adding information to errors:
- stacktraces
- changing the error message
- HTTP status codes
- End user error messages
- causes
You can also add your own additional information.
The stack capturing feature can be turned off for better performance, though it's pretty fast. Benchmarks on an 2017 MacBook Pro, with go 1.10:
BenchmarkNew_withStackCapture-8 2000000 749 ns/op
BenchmarkNew_withoutStackCapture-8 20000000 64.1 ns/op
Merry errors are fully compatible with errors.Is, As, and Unwrap.
To add a stacktrace, a user message, and an HTTP code to an error:
err = merry.Wrap(err, WithUserMessagef("Username %s not found.", username), WithHTTPCode(404))
To fetch context information from error:
userMsg := UserMessage(err)
statusCode := HTTPCode(err)
stacktrace := Stacktrace(err)
To print full details of the error:
log.Printf("%v+", err) // or log.Println(merry.Details(err))
v1 used a fluent API style which proved awkward in some cases. In general, fluent APIs don't work that well in go, because they interfere with how interfaces are typically used to compose with other packages. v2 uses a functional options API style which more easily allows other packages to augment this one.
This also fixed bad smell with v1's APIs: they mostly returned a big, ugly merry.Error interface,
instead of plain error instances. v2 has a smaller, simpler API, which exclusively uses plain
errors.
v2 also implements a simpler and more robust integration with errors.Is/As/Unwrap. v2's functions will work with error wrapper chains even if those chains contain errors not created with this package, so long as those errors conform to the Unwrap() convention.
v2 allows more granular control over stacktraces: stack capture can be turned on or off on individual errors, overriding the global setting. External stacktraces can be used as well.
v1 has been reimplemented in terms of v2, and the versions are completely compatible, and can be mixed.
- Check out my HTTP client library: github.com/gemalto/requester
- Check out my log library: github.com/gemalto/flume
This package is licensed under the MIT license, see LICENSE.MIT for details.