Documentation
¶
Overview ¶
Package errors provides a standard error definition for use in Reflow. Each error is assigned a class of error (kind) and an operation with optional arguments. Errors may be chained, and thus can be used to annotate upstream errors.
Errors may be serialized to- and deserialized from JSON, and thus shipped over network services.
Package errors provides functions Errorf and New as convenience constructors, so that users need import only one error package.
The API was inspired by package upspin.io/errors.
Index ¶
- Variables
- func E(args ...interface{}) error
- func Is(kind Kind, err error) bool
- func Match(err1, err2 error) bool
- func NonRetryable(err error) bool
- func Restartable(err error) bool
- func Transient(err error) bool
- func WithRetryableKinds(ctx context.Context, ks ...Kind) context.Context
- type Error
- type Kind
- type Multi
Constants ¶
This section is empty.
Variables ¶
var Errorf = fmt.Errorf
Errorf is an alternate spelling of fmt.Errorf.
var New = goerrors.New
New is an alternate spelling of errors.New.
var Separator = ":\n\t"
Separator is inserted between chained errors while rendering. The default value (":\n\t") is intended for interactive tools. A server can set this to a different value to be more log friendly.
Functions ¶
func E ¶
func E(args ...interface{}) error
E is used to construct errors. E constructs errors from a set of arguments; each of which must be one of the following types:
string The first string argument is taken as the error's Op; subsequent arguments are taken as the error's Arg. digest.Digest Taken as an Arg. Kind Taken as the error's Kind. error Taken as the error's underlying error.
If a Kind is provided, there is no further processing. If not, and an underlying error is provided, E attempts to interpret it as follows: (1) If the underlying error is another *Error, and there is no Kind argument, the Kind is inherited from the *Error. (2) If the underlying error has method Timeout() bool, it is invoked, and if it returns true, the error's kind is set to Timeout. (3) If the underlying error has method Temporary() bool, it is invoked, and if it returns true, the error's kind is set to Temporary. (4) If the underyling error is context.Canceled, the error's kind is set to Canceled. (5) If the underlying error is an os.IsNotExist error, the error's kind is set to NotExist.
func Is ¶
Is tells whether an error has a specified kind, except for the indeterminate kind Other. In the case an error has kind Other, the chain is traversed until a non-Other error is encountered.
func Match ¶
Match compares err1 with err2. If err1 has type Kind, Match reports whether err2's Kind is the same, otherwise, Match checks that every nonempty field in err1 has the same value in err2. If err1 is an *Error with a non-nil Err field, Match recurs to check that the two errors chain of underlying errors also match.
func NonRetryable ¶
NonRetryable tells whether error err is likely fatal, and thus not useful to retry. The passed in error must not be nil. Note that NonRetryable != !Restartable; these functions are not the inverse of each other. They each report on the errors they know to be either non-retryable or restartable, but there exist errors which don't belong to either category.
func Restartable ¶
Restartable determines if the provided error (must be non-nil) is restartable. Restartable errors include transient errors and network errors. Restartable traverses root causes and checks if any of the underlying causes are transient or network errors. Additionally, when traversing causes, any "github.com/grailbio/base/errors" error is recovered into "github.com/grailbio/reflow/errors" with its kind derived from base kind and severity.
func Transient ¶
Transient tells whether error err is likely transient, and thus may be usefully retried. The passed in error must not be nil.
func WithRetryableKinds ¶
WithRetryableKinds returns a child context of ctx with the given error kinds and any pre-existing ones. WithRetryableKinds should be used rather than directly setting the value to avoid overwriting any previously set retryable errors.
Types ¶
type Error ¶
type Error struct {
// Kind is the error's type.
Kind Kind
// Op is a one-word description of the operation that errored.
Op string
// Arg is an (optional) list of arguments to the operation.
Arg []string
// Err is this error's underlying error: this error is caused
// by Err.
Err error
}
Error defines a Reflow error. It is used to indicate an error associated with an operation (and arguments), and may wrap another error.
Errors should be constructed by errors.E.
func Recover ¶
Recover recovers any error into an *Error. If the passed-in err is already an *Error or nil, it is simply returned; otherwise it is wrapped.
func RecoverError ¶
RecoverError recovers a *Error from the given error, and if is of type: - *Error, it is returned as-is. - *baseerrors.Error, a *Error is returned with a translated Kind. RecoverError returns whether the given error was successfully recovered.
func (*Error) Error ¶
Error renders this error and its chain of underlying errors, separated by Separator.
func (*Error) ErrorSeparator ¶
ErrorSeparator renders this errors and its chain of underlying errors, separated by sep.
func (*Error) HTTPStatus ¶
HTTPStatus indicates the HTTP status that should be presented in conjunction with this error.
func (*Error) MarshalJSON ¶
MarshalJSON implements JSON marshalling for Error.
func (*Error) UnmarshalJSON ¶
UnmarshalJSON implements JSON unmarshalling for Error.
type Kind ¶
type Kind int
Kind denotes the type of the error. The error's kind is used to render the error message and also for interpretation.
const ( // Other denotes an unknown error. Other Kind = iota // Canceled denotes a cancellation error. Canceled // Timeout denotes a timeout error. Timeout // Temporary denotes a transient error. Temporary // NotExist denotes an error originating from a nonexistant resource. NotExist // NotAllowed denotes a permissions error. NotAllowed // NotSupported indicates the operation was not supported. NotSupported // TooManyTries indicates that the operation was retried too many times. TooManyTries // Integrity denotes an integrity check error. Integrity // ResourcesExhausted indicates that there were insufficient resources. ResourcesExhausted // Eval denotes an evaluation error. Eval Unavailable // Fatal denotes an unrecoverable error. Fatal // Invalid indicates an invalid state or data. Invalid // Net indicates a networking error. Net // Precondition indicates that a precondition was not met. Precondition // OOM indicates a out-of-memory error. OOM // Module indicates a reflow module error. Module // DockerExec indicates a reflow exec error. DockerExec )
func BaseToReflow ¶
func BaseToReflow(baseKind baseerrors.Kind, baseSeverity baseerrors.Severity) Kind
BaseToReflow interprets base error Kind and Severity to reflow error Kind.
func GetRetryableKinds ¶
GetRetryableKinds returns a slice of any retryable error kinds stored in ctx.
type Multi ¶
type Multi struct {
// contains filtered or unexported fields
}
Multi represents a composite error which combines multiple (non-nil) errors. Multi is useful in cases where there is a need to (concurrently) combine multiple (non-critical) errors into one.
Source Files