eva.error — com.workiva/eva 2.0.4

*always-sanitize-exceptions* clj

*capture-flag* clj

deferror clj macro

(deferror error-name type generic-str)

(deferror error-name type generic-str required-keys)

Defines specialized versions of the recide.core/error and recide.core/raise macros, where the type and the 'generic' portion of the error message are static and required data are specified via the final sequence of keywords. Defines two macros (for compile-time errors). The first is a specialized constructor interned as <error-name>, analogous to recide.core/error, with the following signature: ([detail-msg data] [detail-msg data cause])

Also defined is a corresponding raise-<error-name> macro with the signature: ([detail-msg {:as extra-data}] [detail-msg {:as extra-data} cause])

Example: (deferror io-timeout :io/timeout "A network operation timed out" [:operation])

Use the defined constructor like so: (io-timeout "the gremlins endpoint failed to respond." {:operation 'gremlin-endpoint, :other-info :kazzam})

This will construct a recide error of the following form: {:eva/error :io/timeout :eva.error/msg "A network operation timed out: the gremlins endpoint failed to respond." :eva.error/data {:operation 'gremlin-endpoint, :other-info :kazzam} :eva.error.serialized-throwable/v2 <serialized-form>}

Using the generated raise-* macro is similar: (raise-io-timeout "the gremlins endpoint failed to respond." {:operation 'gremlin-endpoint, :other-info :kazzam}

In both macros, if :operation is left out of the data map, an exception will be thrown at compile-time because it was marked as required in deferror.

Uses ErrorForm: eva.error/eva-error-form

deferror-group clj macro

(deferror-group error-name namespace-key & subtypes)

Defines new specialized versions of the recide.core/error and recide.core/raise macros, for working with a namespaced family of error types. For each subtype, the 'generic' portion of the error message is static. Required data keywords can be specified both for the entire family of errors and for each subtype.

Both the constructor and raise-* macros have the same signature: ([detail-msg {:as extra-data}] [detail-msg {:as extra-data} cause])

Example: (deferror-group io-failure (:io.failure [:operation]) (timeout "A network operation timed out" [:timeout-ms]) (connection-reset "The other node reset the connection.")

An example of using the defined constructor is: (io-failure :timeout "the gremlins endpoint failed to respond." {:operation 'gremlin-endpoint, :timeout-ms 10000})

This will construct a recide error of the following form: {:eva/error :io.failure/timeout :eva.error/msg "A network operation timed out: the gremlins endpoint failed to respond." :eva.error/data {:operation 'gremlin-endpoint, :timeout-ms 10000} :eva.error.serialized-throwable/v2 <serialized-form>}

The generated raise-* macro uses the exact same syntax, but throws the constructed exception.

In both macros, a compile-time exception will be thrown if either :operation or :timeout-ms is left out of the data-map for :io.failure/timeout, because the entire family of errors requires :operation and the :timeout error in particular requires :timeout-ms.

Uses ErrorForm: eva.error/eva-error-form

error clj

(error type msg data)

(error type msg data cause)

Returns a recide error (IExceptionInfo) with the type (keyword), msg (string), data (map), and cause (Throwable). Merges the following map onto the ex-data:

For Example: {:recide/error recide.error.ErrorForm@447521e, :recide/type type}

ErrorForm definition: eva.error/eva-error-form

Constructor: eva.error$eva_exception

error-map clj

(error-map type msg data)

(error-map type msg data cause)

Returns a map representing a recide error with the type (keyword), msg (string), data map, and cause.

{eva.error/eva-error-form type, :eva/error msg, :eva.error/msg data, :eva.error/data cause, :eva.error/cause <serialized-form>}

ErrorForm definition: :eva.error.serialized-throwable/v2 Constructor: eva.error$eva_exception

error-map? clj

(error-map? x)

(error-map? x type)

Checks if the given hash-map is polymorphic to a recide error AND is constructed according to the following ErrorForm:

• eva.error/eva-error-form

So its shape should be: {:eva/error <type>, :eva.error/msg <msg>, :eva.error/data <data>, :eva.error/cause <cause>, :eva.error/error-code (<error-code-fn> <ex-info>), :eva.error.serialized-throwable/v2 <serialized-form>}

error? clj

(error? x)

(error? x type)

Checks if the given ex-info wraps a recide error AND is constructed according to the following ErrorForm:

• eva.error/eva-error-form

Thus converted from error to map form it would look like this: {:eva/error <type>, :eva.error/msg <msg>, :eva.error/data <data>, :eva.error/cause <cause>, :eva.error/error-code (<error-code-fn> <ex-info>), :eva.error.serialized-throwable/v2 <serialized-form>}

eva-error-form clj

eva-ex clj

(eva-ex fn-form)

an aspect for eva.error/with-api-error-handling

eva-exception clj

(eva-exception message data)

(eva-exception message data cause)

generic-error-type->error-code clj

handle-api-error clj

(handle-api-error e)

insist clj macro

(insist expr)

(insist expr message)

Same syntax as assert. If assertion is disabled, insistence will also be disabled. Throws an IExceptionInfo if expr does not evaluate to logical true. eva.error/eva-error-form is the constructor used.

Otherwise, it acts like recide/raise, constructing a recide error of the following form: {:eva/error :recide/assertion, :eva.error/msg msg, :eva.error/data <data>, :eva.error.serialized-throwable/v2 <serialized-form>}

When eva.error/capture-flag is true, this will also capture the bindings of symbols used in the assertion, inserting these values into the data map. eva.error/capture-flag is false by default, unless one of the following was true at class load: (1) env var is true: RECIDERE_CAPTURE_INSISTS (2) system property is set: recide.capture-insists

is-thrown? clj macro

(is-thrown? {:keys [msg-re error-codes http-code eva-code error-type unwrapper]
             :as tests}
            &
            body)

Utility macro that requires a literal map as its test argument.

Executes body, and asserts that either (a) its result is an EvaException or (b) it throws one. Optional additional tests:

• :msg-re is a regex code to match a substring of the exception message
• :error-codes is a collection of error codes to assert hasErrorCode on
• :http-code is the integer HTTP error mapped onto this exception
• :eva-code is the integer Eva error code
• :error-type matches the keyword type under :eva/error

If the body throws a different type of exception or something other than an EvaException, the optional key :unwrapper may be used to pull the EvaException off of this other value before any test assertions are made.

kw->memfns clj

override-codes clj

(override-codes overrides t)

Potentially retag error codes based on the type->code map passed in

overriding-codes clj macro

(overriding-codes overrides & body)

raise clj macro

(raise type msg data)

(raise type msg data cause)

Records this raise-site on the ErrorForm definition, and constructs an IExceptionInfo as a recide-style error.

ErrorForm: eva.error/eva-error-form Constructor: eva.error$eva_exception

Merges the following map onto the data: {:recide/error eva.error/eva-error-form, :eva/error type}

root-cause clj

(root-cause t)

Returns the initial cause of an exception or error by peeling off all of its wrappers

throwable->error-map clj

(throwable->error-map e)

Takes an error-map, error, or any Throwable, and converts it to a recide error-map conforming to the ErrorForm:

• eva.error/eva-error-form

The return map will be shaped like so:

{:eva/error <type>, :eva.error/msg <msg>, :eva.error/data <ex-data>, :eva.error/cause <cause>, :eva.error/error-code (<error-code-fn> <ex-info>), :eva.error.serialized-throwable/v2 <serialized-form>}

with-api-error-handling clj macro

(with-api-error-handling & body)

catches all non-EvaException throwables and wraps them with :eva/unknown-error.