ChoreRunner.Chore behaviour (chore_runner v0.1.3)

Behaviour and DSL for chores.

Link to this section Summary

Callbacks

An optional callback function for defining a chore's inputs.

An optional callback function for defining a chore restriction.

A non-optional callback used to contain the main Chore logic.

Link to this section Types

Specs

t() :: %ChoreRunner.Chore{
  finished_at: DateTime.t(),
  id: String.t(),
  logs: [{unix_timestamp(), String.t()}],
  mod: module(),
  reporter: pid(),
  result: any(),
  started_at: DateTime.t(),
  task: Task.t(),
  values: %{required(atom()) => number()}
}
Link to this type

unix_timestamp()

Specs

unix_timestamp() :: integer()

Link to this section Callbacks

Specs

inputs() :: [ChoreRunner.Input.t()]

An optional callback function for defining a chore's inputs.

Expects a list of input function calls. The input functions provided are string, int, float, file, and bool. All input functions follow the same syntax. For example:

def inputs do
  [
    string(:name),
    int(:name2, [some: :option])
  ]
end

The supported options are

  • :description — a string description of the input, for UI use
  • :validators — a list of anonymous or captured validator functions. Valiator functions should accept a single argument as a parameter, but can return a variety of things, including:
    • an {:ok, value}, or {:error, reason} tuple
    • an :ok or :error atom
    • a true or false
    • any erlang value, or nil The positive values (:ok, true, non-falsey values) pass validation. The negative values (:error, false, nil) fail validation If a value is passed back as part of an {:ok, value} tuple, or by itself, that value is treated as the new value of the given input. This way, validators can also transform input if needed. If this callback is not defined, the default return is [], or no inputs.

Specs

restriction() :: :none | :self | :global

An optional callback function for defining a chore restriction.

The restriction can be either :none, :self, or :global

  • :none is no restrictions
  • :self prevents more than one of the same chore from running simultaneously across all connected nodes
  • :global prevents more than one of all chores with the restriction :global from running simultaneously across all connected nodes. This restriction does not affect non-:global chores. If this callback is not defined, the default return is :self

Specs

run(map()) :: {:ok, any()} | {:error, any()}

A non-optional callback used to contain the main Chore logic.

Accepts a map of input, always atom keyed. (When calling ChoreRunner.run_chore/2, a string keyed map will be intelligently converted to an atom-keyed map automatically) Only keys defined in the inputs/0 callback will be present in the input map, but defined inputs are not garaunteed to be present. The chore callback has access to several Reporter functions, used for live chore metrics and loggin. These functions are:

  • log(message) — Logs a string message with timestamp
  • set_counter(name, value) — Sets a named counter, expects an atom for a name and a number for a value
  • inc_counter(name, inc_value) — Increments a named counter. If the counter does not exist, it will default to 0, and then be incremented. Used negative values for decrements.
  • report_failed(reason_message) — Fails a chore, marking it as failed. The return value of the run/1 callback will be stored in the chore struct and forwarded to the final chore handling function.

Link to this section Functions

Link to this function

validate_input(chore, input)