Documentation
¶
Overview ¶
Package errors implements the custom error handling code of acmeproxy.
The design of the errors package is heavily inspired by "Error handling in Upspin" (Pike, Gerrand; https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html).
Index ¶
- func HasCause(err error, cause error) bool
- func IsKind(err error, kind Kind) bool
- func Log(logger log.Logger, err error)
- func LogFunc(logger log.Logger, f func() error)
- func Match(tmpl, err error) bool
- func New(args ...interface{}) error
- func Wrap(err error, args ...interface{}) error
- type Collection
- type Error
- type Kind
- type Op
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasCause ¶
HasCause returns true if the error err has the error cause in its chain of wrapped errors. It returns false otherwise.
func Match ¶
Match returns true iff err matches the template error tmpl.
Match checks that both tmpl and err are of type *Error. If this is the case Match compares every non-zero field of tmpl with the respective field in err. If this is not the case it checks the error string of tmpl and err for equality.
Match recursively checks tmpl.Err and err.Err if they are set.
func New ¶
func New(args ...interface{}) error
New creates a new Error.
It accepts an arbitrary number of arguments of the following types:
Op
The operation during which an error occurred and New was called.
Usually the name of the method creating the error. Never the function
or method returning an error.
Kind
The kind of an error. Callers may treat errors differently based
on their Kind. If Kind is not specified Unspecified is used as
default. Errors with kind Unspecified should always be treated as
fatal errors.
error
An error returned by another function or method.
string
A string to use as a detailed error message. The string should
follow the usual Go conventions for error messages, i.e. it should
start with a lower case letter and be relatively short but
meaningful.
If more than one argument of the above types is passed, the first passed wins. Arguments of other types than the above are silently ignored.
If New is called without any arguments it returns nil. It is rather pointless to call New without any arguments. Future versions of New might choose to panic instead. It is thus better to not call New without arguments.
Types ¶
type Collection ¶
type Collection []error
Collection contains multiple errors that occurred during an operation.
func Append ¶
func Append(c Collection, err error, args ...interface{}) Collection
Append add err to the collection c, if err is not nil.
It does so by calling Wrap with err and args. If the return value of Wrap is not nil it gets appended to c.
func (Collection) Error ¶
func (c Collection) Error() string
Error formats the collection c as a string.
If c is empty the empty string is returned. If c has size one the return value of the Error method of the only entry is returned. Otherwise the return value of Error of each entry in c is prefixed with '* ' and added on a separate line to the returned string.
func (Collection) ErrorOrNil ¶
func (c Collection) ErrorOrNil() error
ErrorOrNil returns c if c is not nil and has a size greater 0. Otherwise it returns nil.
type Error ¶
type Error struct {
Op Op
Kind Kind
// Msg is a message detailing the error further. It should follow the
// usual Go conventions for messages in errors, i.e. start with a lower-case
// letter and be relatively short but meaningful,
Msg string
// Err references an error which led to this error being returned. Err
// is used to build a trace of errors.
Err error
}
Error represents an error within acmeproxy.
The fields of Error provide additional detail about the error. Any of Error's fields may be left unset if it is not applicable for the error.
The field Err allows the error to reference another error. This allows to build a chain of errors. If the referenced error is an instance of Error itself the Op fields of the errors in the chain can be used to build a trace which should lead to the root cause of the error.
type Kind ¶
type Kind int
Kind categorizes the nature of an error.
Errors of different kind may be treated with different severities. Code may decide to use the Kind of an error to translate it into a response for a client.
const ( // Unspecified is the default value for the an Error's Kind if nothing else // was specified. Code should treat errors of Kind Unspecified as fatal. Unspecified Kind = iota // NotFound shows that an error was returned because something could not // be found. Callers may choose to continue with a fallback for the thing // that could not be found, or abort the operation. NotFound // InvalidArgument shows that an opperation was called with one or more // invalid arguments. This usually indicates a client error. An HTTP API // might return a status 400 Bad Request response. InvalidArgument )
Source Files