clj-foundation.errors — coconutpalm/clj-foundation 0.10.0

What is an error? Is nil an error? (Not always, but...) How can we describe functions that might return a result or that might fail? What about exceptions--they break referential transparency, but lots of code throws them anyway. What about functions that might need to retry because some external actor (e.g.: the network) might have intermittent failures?

Error handling is rarely clean, but this namespace provides some handy utilities to centralize some of the concerns and solve them once, reliably. ;-)

*log* clj

The current log implementation. Defaults to the metalog function.

exception-seq clj

Deprecated. Use errors/seq<- instead.

exception<- clj

(exception<- x)

Inputs: [x :- s/Any] Returns: Throwable

If x is already Throwable return it, else convert it into an exception using ex-info. The (:error-object result) will be the original value. This is intended--though not strictly required--to be used for values where (failure? value) is true.

expect-within clj

(expect-within timeout-millis predicate error-message)

Inputs: [timeout-millis :- s/Num predicate :- (=> s/Any []) error-message :- s/Str] Returns: s/Any

Expect the condition specified by predicate to become true within timeout-millis. If this does not happen, throws IllegalStateException including the error-message. On success, returns the truthy value that predicate returned.

failure? clj multimethod

A multimethod that determines if a computation has resulted in a failure. This allows the definition of what constitutes a failure to be extended to new types by the consumer.

An example of how this can function can be extended to new error types exists in this namespace where we extend failure? to include timeout errors.

log clj

(log level & more)

Inputs: [level :- s/Keyword & more :- [s/Any]] Returns: s/Any

Synopsis: (log :log-level & more)

The initial :log-level must be one of the keywords in log-levels. The remainder of the arguments are the objects that will be logged using log-string.

log-levels clj

The log levels supported by the metalogger mapped to numbers matching the log4j log levels.

The current log level keywords are: #{:trace :debug :info :warn :error :fatal}

log-string clj

(log-string log-objects)

Inputs: [log-objects :- [s/Any]] Returns: s/Str

Create a log string from a sequence of log objects. Parameters are reordered so that non-Throwables are first followed by Throwable objects. Non-Throwables are returned as their toString representation separated by commas. Throwables are represented by their stack traces, separated by " ==> ".

metalog clj

(metalog level-keyword & more)

The default log implementation if none is specified:

• println levels < :error to out
• println levels >= :error to err

must-be clj macro

(must-be message & body)

If body is truthy returns result of evaluating body, else throws IllegalArgumentException with message.

new-default-job clj

(new-default-job job-name tries pause-millis abort?-fn)

Create a Job object. Only public to make retry? testable.

not-failure clj

(not-failure value message)

Inputs: [value :- s/Any message :- s/Str] Returns: s/Any

If value is not a failure, returns it, else throws IllegalStateExceoption with the specified message

not-nil clj

(not-nil value name)

Inputs: [value :- s/Any name :- s/Str] Returns: s/Any

If value is not nil, returns it, else throws IllegalArgumentExceoption with the message "${name} cannot be nil"

retry clj

(retry tries pause-millis f & args)

Retry calling the specified function f & args while pausing pause-millis between attempts. Uncaught exceptions are considered errors. After tries attempts, the last caught exception is re-thrown.

retry* clj

(retry* tries pause-millis f & args)

Retry calling the specified function f & args while pausing pause-millis between attempts. Throwable objects, and uncaught exceptions are all considered errors. After tries attempts, the last error is returned.

retry-statements clj

(retry-statements tries pause-millis)

Specify a retry policy for a function that will be called later. tries is the number of retries allowed for the future function call, and pause-millis is the number of milliseconds to wait between retries.

Returns a multi-arity function. The initial parameter is the function to be called. The remaining parameters (if any) are that function's arguments.

retry-with-timeout clj

(retry-with-timeout job-name settings f & args)

Inputs: [job-name :- String settings :- RetrySettings f :- (=> s/Any [s/Any]) & args :- [s/Any]] Returns: s/Any

Retry (apply f args) up to tries times with pause-millis time in between invocation and a timeout value of timeout-millis. On failure, abort?-fn is called with a vector containing the unwrapped exception stack.

(failure is determined via the (failure? x) multimethod so clients can extend the set of values that are considered to be failures.)

If abort?-fn returns true, the errror is considered fatal and no more retries are attempted, even if retries were available.

If the last result is a failure, and that failure is Throwable, the exception is wrapped in a RuntimeException and rethrown.

If the last result is a TIMEOUT-ERROR, a runtime exception is thrown. Otherwise, the failure value itself is returned as the result.

retry? clj

(retry? job failure-value)

Inputs: [job failure-value :- s/Any] Returns: (s/enum :ABORT-MAX-RETRIES :ABORT-FATAL-ERROR :RETRY-FAILURE :RETRY-TIMEOUT)

Something failed. Examine the retry count and exact failure cause and determine if we can retry the operation. Internal API only; public so we can document using Schema and test.

RetrySettings clj

seq<- clj

(seq<- failure)

Inputs: [failure :- (s/pred failure? "(failure? failure) is truthy")] Returns: [Throwable]

Converts failures into seqs of exceptions. If the failure is already an exception (the common case), it returns a seq starting with the root exception, and recursively including (.getCause e) until there are no more causes.

If the failure is a seq, ensures that the result is a seq of excetions.

If the failure isn't already an exception or a seq, it is converted into one first using ex-info. In this case, the :cause in the ex-info map will be the original failure object.

set-global-metalogger clj

(set-global-metalogger f)

Inputs: [f :- (=> s/Any [s/Keyword s/Any])] Returns: s/Any

Set the clj-foundation metalogger globally. f must be a function of type (=> s/Any [s/Keyword s/Any])

stack-trace<- clj

(stack-trace<- e)

Inputs: [e :- Throwable] Returns: s/Str

Returns the stack trace(s) associated with e and its (.getCause)s as a String.

t-map->RetrySettings clj

throw-or clj

(throw-or value message f)

Inputs: [value :- s/Any message :- s/Str f :- (=> s/Any [s/Any])] Returns: s/Any

If value is a failure, wrap and throw it in an IllegalStateException with the specified message, else run function on the value and return the result

TIMEOUT-ERROR clj

A timeout error value

timeout? clj

(timeout? e)

True if (= TIMEOUT-ERROR e)

trace clj macro

(trace & more)

Like str but prepends the namespace and line/column of the call site.

try* clj macro

(try* body)

(try* body default-value-if-failure)

A variant of try that translates exceptions into return values or a specified default value. Note that body must be a single statement. If you need more than that, then wrap your statement inside a "do".

try*-timeout-millis clj macro

(try*-timeout-millis timeout-millis & body)

Execute body with a specified timeout inside a try* block so that thrown exceptions are returned.

On success, returns the result of executing body. On failure, returns either the failure exception or TIMEOUT-ERROR on timeout.