Simple scenario behavior.

Implement this behaviour to create a scenario. Note the scenario must also implement Runbox.Scenario.Manifest, although all this can be done in a single module, see example below.

Simple scenario structure

Simple scenario has a single module that carries the whole logic of the scenario. The module specifies which logical topics it wants to consume (input_topics/0) and defines how messages from these topics are processed, updating its state and generating outputs along the way.

Usually you would use a single module for a scenario implementing both Manifest and this behavior. However, you can separate these two if you wish. Note that the name of the module must always be prefixed by the module name structure of the Manifest. E.g. if you have manifest module Scenarios.MyScenario the module implementing this behaviour can be named Scenarios.MyScenario.Logic but not Scenarios.MyScenarioLogic.

Before the processing is first started an init/1 callback is used to initialize the state. State is later used in the computation.

Each message in the specified topics is then processed by the handle_message/2 callback. This callback should contain the main logic of the scenario. Messages arrive sorted into this callback - you can assume the time is non-decreasing.

At minimum you must implement callbacks input_topics/0 and handle_message/2, see other callbacks available in this module and in Runbox.Scenario.Manifest to see what is possible in a scenario.

Determinism

Scenarios should be deterministic, meaning that if you run a scenario twice on the same data you get the same results. Scenarios shouldn't depend on any external resources other than topics and scenario configuration. Notably, scenarios shouldn't depend on current time. Scenario should always only work with time from the incoming messages, called external time.

You should avoid directly making side effects in a scenario. Scenario should instead produce output actions, which are instructions to perform specific side effects. Output actions are automatically performed by the scenario runtime in a deterministic manner. See Runbox.Scenario.OutputAction for the list of available output actions.

There are cases when you want to do some work at a specified point of the external time, for example to produce some output actions when the external time reaches noon. This can be also achieved in a deterministic manner via timeouts. You can register a timeout by returning a corresponding runtime instruction, see Runbox.Runtime.RuntimeInstruction.register_timeout/1 for more details. The message registered in a timeout will be then passed as is to your handle_message/2 callback exactly at the time you specify in its timestamp field.

State persistence

State used in the computation is automatically and periodically persisted. This makes it easier to restart the computation. You don't have to recompute all of the data again to get the final state, you just load the last savepoint and recompute from there.

By default the state is persisted in the same structure as is used in the scenario. However, if you wish you can implement get_state/1 and set_state/1 callbacks to transform the state before it is saved into a savepoint and after it is loaded from a savepoint.

Example

defmodule Scenarios.ServerTemperature do
  use Runbox.Scenario.Manifest
  use Runbox.Scenario.Simple

  alias Runbox.Scenario.Manifest
  alias Runbox.Scenario.OutputAction.Event
  alias Runbox.Scenario.OutputAction.UpsertAssetAttributes
  alias Runbox.Scenario.Type, as: ScenarioType
  alias Runbox.Message

  @impl Manifest
  def get_info do
    %Manifest{
      id: "server_temperature",
      name: "Server temperature",
      description: "Monitors server temperature and saves the data into Reality Network.",
      type: ScenarioType.simple()
    }
  end

  @impl Runbox.Scenario.Simple
  def init(_) do
    {:ok, [], %{last_temps: %{}}}
  end

  @impl Runbox.Scenario.Simple
  def input_topics do
    ["server_sensor"]
  end

  @impl Runbox.Scenario.Simple
  def handle_message(%Message{type: :temperature} = msg, state) do
    last_temp = Map.get(state.last_temps, msg.body.server, 0)

    if last_temp != msg.body.temperature do
      # temperature changed, update reality network
      event = %Event{
        type: "temp_change",
        template: "Temperature on ${actors.server} changed to ${params.temp}",
        actors: %{"server" => %{asset_type: "/assets/servers", asset_id: msg.body.server}},
        params: %{"temp" => msg.body.temperature},
        origin_messages: [msg.origin]
      }

      update_asset = %UpsertAssetAttributes{
        type: "/assets/servers",
        id: msg.body.server,
        attributes: %{"temp" => msg.body.temperature}
      }

      new_state = put_in(state.last_temps[msg.body.server], msg.body.temperature)
      {:ok, [event, update_asset], new_state}
    else
      # temperature didn't change, no need to do anything
      {:ok, [], state}
    end
  end

  # ignore other sensor data
  def handle_message(_, state) do
    {:ok, [], state}
  end
end