salutem.core.maintenance — io.logicblocks/salutem.core 0.1.9-RC5

Provides an asynchronous maintenance pipeline for maintaining up-to-date results for the checks in a registry.

evaluation-state-store clj

(evaluation-state-store)

(evaluation-state-store logger)

Returns a ref containing empty evaluation state, used by the evaluator to keep track of in flight checks.

Optionally takes a cartus.core/Logger in which case any change to the ref is logged at debug level to the logger.

evaluator clj

(evaluator dependencies evaluation-channel)

(evaluator dependencies state-store evaluation-channel)

(evaluator dependencies evaluation-channel result-channel skip-channel)

(evaluator dependencies
           state-store
           evaluation-channel
           result-channel
           skip-channel)

Starts an evaluator process which evaluates checks.

The evaluator process ensures that only one evaluation of any check can be in progress at a time. It does so by keeping track of in flight checks in a state ref, which can be passed as an argument, useful in the case that multiple evaluators are working as competing consumers of an evaluation channel.

Takes the following parameters:

• dependencies: a map of dependencies used by the evaluator, currently supporting only a :logger entry with a cartus.core/Logger value.
• state-store: an optional ref containing evaluation state, best created by evaluation-state-store; defaults to an empty state store.
• evaluation-channel: a channel on which evaluation messages are received.
• result-channel: an optional channel on which result messages are sent; included in the map returned by the function; if not provided, a channel with a buffer of length 10 is used.
• skip-channel: an optional channel on which skipped evaluation messages are sent; included in the map returned by the function; if not provided, a channel with a sliding buffer of length 10 is used.

The evaluation messages received on the evaluation channel should include:

• :trigger-id: a trigger ID used to correlate multiple evaluations.
• :check: the check to be evaluated.
• :context: the context map to provide to the check.

The result messages sent on the result channel include:

• :trigger-id: the trigger ID passed in the evaluation message.
• :check: the evaluated check.
• :result: the result of evaluating the check.

If the provided evaluation channel is closed, the evaluator will in turn close the result channel and the skip channel.

maintain clj

(maintain registry-store)

(maintain registry-store
          {:keys [context interval notification-callback-fns trigger-channel
                  evaluation-channel result-channel skip-channel
                  updater-result-channel notifier-result-channel]
           :or {interval (t/new-duration 200 :millis)
                trigger-channel (async/chan (async/sliding-buffer 1))
                evaluation-channel (async/chan 10)
                result-channel (async/chan 10)
                skip-channel (async/chan (async/sliding-buffer 10))
                updater-result-channel (async/chan 10)
                context {}
                notification-callback-fns []
                notifier-result-channel (async/chan 10)}})

Constructs and starts a maintenance pipeline to maintain up-to-date results for the checks in the registry in the provided registry store atom.

The maintenance pipeline consists of a number of independent processes:

• a maintainer which triggers an attempt to refresh the results periodically,
• a refresher which requests evaluation of each outdated check on each refresh attempt,
• an evaluator which evaluates outdated checks to obtain a fresh result,
• an updater which updates the registry store atom with fresh check results,
• a notifier which calls callback functions when fresh check results are available.

The maintenance pipeline can be configured via an optional map which can contain the following options:

• :context: a map containing arbitrary context required by checks in order to run and passed to the check functions as the first argument; defaults to an empty map
• :interval: a salutem.core/duration describing the wait interval between attempts to refresh the results in the registry; defaults to 200 milliseconds
• :notification-callback-fns: a sequence of arity-2 functions, with the first argument being a check and the second argument being a result, which are called whenever a new result is available for a check; empty by default
• :trigger-channel: the channel on which trigger messages are sent, to indicate that a refresh of the registry should be attempted, defaults to a channel with a sliding buffer of length 1, i.e., in the case of a long running attempt, all but the latest trigger message will be dropped from the channel
• :evaluation-channel: the channel on which messages requesting evaluation of checks are sent, defaults to a channel with a buffer of size 10
• :result-channel: the channel on which results are placed after evaluation, defaults to a channel with a buffer of size 10
• :updater-result-channel: a tap of the result-channel which sends result messages on to the updater, defaults to a channel with a buffer of size 10
• :notifier-result-channel: a tap of the result-channel which sends result messages on to the notifier, defaults to a channel with a buffer of size 10

If the context map contains a :logger key with a cartus.core/Logger value, the maintenance pipeline will emit a number of log events throughout operation.

Returns the maintenance pipeline which can be passed to shutdown in order to stop operation.

maintainer clj

(maintainer dependencies registry-store context interval trigger-channel)

(maintainer dependencies
            registry-store
            context
            interval
            trigger-channel
            shutdown-channel)

Starts a maintainer process which periodically triggers a registry refresh.

Takes the following parameters:

• dependencies: a map of dependencies used by the maintainer, currently supporting only a :logger entry with a cartus.core/Logger value.
• registry-store: an atom containing the registry for which refreshes should be periodically triggered.
• context: a map containing arbitrary context required by checks in order to run and passed to the check functions as the first argument.
• interval: a salutem.core/duration describing the wait interval between refresh triggers.
• trigger-channel: the channel on which to send trigger messages.
• shutdown-channel: an optional channel which when closed, closes the trigger channel; included in the map returned by the function; if not provided, a channel with no buffer is used.

The trigger messages sent to the trigger channel include:

• :trigger-id: a monotonically increasing integer identifying the trigger.
• :registry: the registry which should be refreshed.
• :context: the context map to provide to checks.

notifier clj

(notifier dependencies callbacks result-channel)

Starts a notifier process which executes a number of notification callbacks with new results.

Takes the following parameters:

• dependencies: a map of dependencies used by the notifier, currently supporting only a :logger entry with a cartus.core/Logger value.
• callbacks: a sequence of arity-2 functions, with the first argument being a check and the second argument being a result, to call whenever a new result is available.
• result-channel: a channel on which result messages are received.

The result messages received on the result channel should include:

• :trigger-id: a trigger ID used to correlate multiple results.
• :check: the check that produced the result.
• :result: the result with which to update the registry.

refresher clj

(refresher dependencies trigger-channel)

(refresher dependencies trigger-channel evaluation-channel)

Starts a refresher process which triggers evaluation of outdated checks.

Takes the following parameters:

• dependencies: a map of dependencies used by the refresher, currently supporting only a :logger entry with a cartus.core/Logger value.
• trigger-channel: a channel on which trigger messages are received.
• evaluation-channel: an optional channel on which evaluation messages are sent; included in the map returned by the function; if not provided, a channel with a buffer of length 1 is used.

The trigger messages received on the trigger channel should include:

• :trigger-id: a monotonically increasing integer identifying the trigger.
• :registry: the registry which should be refreshed.
• :context: the context map to provide to checks.

The evaluation messages sent on the evaluation channel include:

• :trigger-id: the trigger ID from the trigger message.
• :check: the check which should be evaluated.
• :context: the context map to provide to the check.

If the provided trigger channel is closed, the refresher will in turn close the evaluation channel.

shutdown clj

(shutdown maintenance-pipeline)

Shuts down the maintenance pipeline preventing further updates to the registry.

updater clj

(updater dependencies registry-store result-channel)

Starts an updater process which updates the registry in a registry store with new results.

Takes the following parameters:

• dependencies: a map of dependencies used by the updater, currently supporting only a :logger entry with a cartus.core/Logger value.
• registry-store: an atom containing the registry which should be updated with new results.
• result-channel: a channel on which result messages are received.

The result messages received on the result channel should include:

• :trigger-id: a trigger ID used to correlate multiple results.
• :check: the check that produced the result.
• :result: the result with which to update the registry.