mirror of
https://github.com/ceph/ceph-csi.git
synced 2025-06-13 02:33:34 +00:00
rebase: vendor files required for kmip
Signed-off-by: Rakshith R <rar@redhat.com>
This commit is contained in:
88
vendor/github.com/ansel1/merry/v2/README.md
generated
vendored
Normal file
88
vendor/github.com/ansel1/merry/v2/README.md
generated
vendored
Normal file
@ -0,0 +1,88 @@
|
||||
merry [](https://github.com/ansel1/merry/actions?query=branch%3Amaster+workflow%3ABuild+) [](https://godoc.org/github.com/ansel1/merry/v2) [](https://goreportcard.com/report/github.com/ansel1/merry/v2)
|
||||
=====
|
||||
|
||||
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.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
go get github.com/ansel1/merry/v2
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
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.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
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 -> v2
|
||||
--------
|
||||
|
||||
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.
|
||||
|
||||
Plugs
|
||||
-----
|
||||
|
||||
- Check out my HTTP client library: [github.com/gemalto/requester](https://github.com/gemalto/requester)
|
||||
- Check out my log library: [github.com/gemalto/flume](https://github.com/gemalto/flume)
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
This package is licensed under the MIT license, see LICENSE.MIT for details.
|
Reference in New Issue
Block a user