ForwardXMPP
===========

Overview
--------

FowardXMPP is a bot that connects to an XMPP/Jabber server and forwards messages that it receives. You control what messages it forwards, where it forwards those messages to, and how the forwards are formatted through a simple configuration file.

The configuration file
----------------------

This package includes a ``ConfigExample.ini`` file that you can use as a basis for your own configuration file. By default ForwardXMPP looks for a configuration file in ``~/.config/forwardxmpp/config.ini``, or if it's run as root, ``/etc/forwardxmpp/config.ini``. You can specify a different configuration file location with the ``--config-file`` switch.

Bot connection
~~~~~~~~~~~~~~

Settings for the entire bot are configured in a ``[Bot]`` section::

  [Bot]
  jid = node@example.org/ForwardBot
  password = ExamplePassword
  nickname = FowardBot
  loglevel = warning

``jid`` and ``password`` are the required details for the bot's connection. The bot will use ``nickname`` when it joins MUCs and sends message, if specified.

Logs are written to standard error. The ``loglevel`` setting controls how much is logged. You can specify ``debug``, ``info``, ``warning``, ``error``, or ``critical``.

Forwarding rules
~~~~~~~~~~~~~~~~

Any sections in the configuration file with ``Forward `` at the start of their name define a rule for how messages are forwarded. Those sections look like this::

  [Forward .com messages to bizdev]
  from = @example\.com($|/)
  to = bizdev@example.org
  format = Message from {from.full}: {body}

You can specify as many forwarding rules as you like. You are only limited by the resources available to the bot.

The ``from`` setting is a `Python regular expression <https://docs.python.org/library/re.html#regular-expression-syntax>`_. When the sender's JID matches this regular expression, the message will be forwarded using the rules in the rest of the section.

**NOTE**: The regular expression is checked against the *entire* JID, including the resource. If you want to check for the end of the domain, use ``($|/)`` as this example, to check for the end of the JID or the beginning of the resource.

The ``to`` setting is a JID where the message is forwarded. It can be a specific user or a MUC. When the bot first connects to a server, it will query all the places it might forward messages, and join any MUCs that are specified.

The ``format`` setting is optional and defines the text of the forwarded message. It is a `Python format string <https://docs.python.org/library/string.html#format-string-syntax>`_ that can use the following variables:

* ``type``: The type of the original XMPP message, i.e., ``chat`` or ``groupchat``.
* ``body``: The body of the original XMPP message.
* ``from``: A JID object representing the sender of the original message. You can access the following attributes:
  * ``from.full``: The sender's entire JID
  * ``from.bare``: The sender's JID with the resource omitted
  * ``from.node``: The node of the sender's JID (the part before the @)
  * ``from.domain``: The domain of the sender's JID
  * ``from.resource``: The resource of the sender's JID
* ``to``: A JID object representing the recipient of the original message. Currently this will always belong to the bot. ``to`` has all the same attributes as ``from``.

You can forward the same message(s) to multiple different destinations by
defining multiple forward rules with the same ``from`` setting and different
``to`` settings.