Xbus routing
============

Provides actors that route messages to different outputs based on the data
inside the payload.

Services
--------

``routing.imperative-router``
'''''''''''''''''''''''''''''

Imperative router extract an output name from the message content and send the
envelope to this output.

Settings:

- ``extract-output-jq``: A jq_ program that produces a string value from the
  message content.

Example:

With this sample configuration, the imperative router will use the value of the
"output" field of the message content.

.. code-block:: yaml

   service:
     type: routing.imperative-router
     settings:
        extract-output-jq: .output

``routing.table-router``
'''''''''''''''''''''''''

Table router extract a key from the message content, then lookup in a routing
table to find the output name.

The routing table can be managed externaly or maintained by the table updater
actor.

Settings:

- ``extract-key-jq``: A jq_ program that produces a string value from the
  message content.
- ``store.backend``: The backend to use for storing the routing table.
  See below for the available backends.
- ``store.<option>``: the backend specific settings (see below)

Example:

With this sample configuration, the table router will use the value of the
"contract-no" field of the message content as key for a table lookup.

.. code-block:: yaml

   service:
     type: routing.table-router
     settings:
        extract-key-jq: .account-no
        store.backend: postgres
        store.dsn: postgres://user:password@host/dbname
        store.tablename: routing-table

Complex jq_ expressions can be used to create composite keys. Here, we concat
the contact type and contract number to build a key:

.. code-block:: yaml

    extract-key-jq: "\(.contract-type)-\(.contract-no)"

``routing.table-updater``
'''''''''''''''''''''''''

The table updater extract a key and a value from the message content, then
update the routing table.

Settings:

- ``extract-key-jq``: A jq_ program that produces a string value from the
  message content.
- ``extract-value-jq``: A jq_ program that produces a string value from the
  message content.
- ``store.backend``: The backend to use for storing the routing table.
  See below for the available backends.
- ``store.<option>``: the backend specific settings (see below)

Example:

With this sample configuration, the table updater will use the value of the
"contract-no" field of the message content as key and the value of the
"agency-ref" as value for a table update.

.. code-block:: yaml

   service:
     type: routing.table-updater
     settings:
        extract-key-jq: .account-no
        extract-value-jq: .agency-ref
        store.backend: postgres
        store.dsn: postgres://user:password@host/dbname
        store.tablename: routing-table

``routing.table-deleter``
'''''''''''''''''''''''''

The table deleter extracts a key from the message content, then
removes the corresponding entry from the routing table.

Settings:

- ``extract-key-jq``: A jq_ program that produces a string value from the
  message content.
- ``store.backend``: The backend to use for storing the routing table.
  See below for the available backends.
- ``store.<option>``: the backend specific settings (see below)

Example:

With this sample configuration, the table deleter will use the value of the
"contract-no" field of the message content as key.

.. code-block:: yaml

   service:
     type: routing.table-deleter
     settings:
        extract-key-jq: .account-no
        store.backend: postgres
        store.dsn: postgres://user:password@host/dbname
        store.tablename: routing-table

Table backends
--------------

``postgres``
''''''''''''

Stores the routing table in a postgresql database.

Settings:

- ``dsn``: The database DSN (required)
- ``tablename``: The table name (required)
- ``keycolumn``: The key column name (default: "key")
- ``valuecolumn``: The value column name (default: "value")
- ``autocreate``: If true, autocreate the routing table if missing

``memory``
''''''''''

Stores the routing table in memory.

.. note::

    This backend is for testing purpose only and
    is *not* persistent.

Settings:

- ``name``: A store name. If multiple actors in a single instance use the same
  name, they will share their routing table.


.. _jq: https://stedolan.github.io/jq/