nathanls/purplerelay repository overview

⁠PurpleRelay v1.0.1

PurpleRelay relays and routes messages from Pidgin/Finch⁠ to Discord⁠ utilizing D-BUS⁠ for IPC(inter-process communication).

PurpleRelay is configured through a routes.json file to filter incoming messages received through Pidgin using regular expressions that are then relayed to specified Discord channels. Any instant messaging / chat account that Pidgin supports or through plugins⁠ should theoretically be capable of being relayed to Discord.

Relaying is simple to set up and there is even a Docker image⁠ available utilizing Finch for a headless GUI-less setup.

⁠Table of contents

• Table of contents⁠
• Relay Configuration⁠
  • Reference⁠
  • Example⁠
• Docker⁠
  • Quick reference⁠
  • Start an instance⁠
  • Where to Store Data⁠
  • Docker Stack and Compose⁠
• Running from source⁠
  • Requirements⁠
  • Installing dependencies and running⁠

⁠Relay Configuration

All possible configuration for the bot is done in the routes.json file. There is a provided routes-example.json in this repo for a simple setup.

⁠Reference

• config: (dict) - Core config key-value pairs
  • token: (string, required) - The Discord bot token from Discord developers⁠ that will be used to join and send messages to relay target channels.
  • max_dbus_reconnect: (integer, default: 5) - The maximum number of D-BUS reconnection attempts to make in the event of a lost IPC connection to Pidgin/Finch before exiting with code 1. Set to 0 to disable and infinitely retry reconnecting to Pidgin/Finch.
  • bot_status: (bool, default: true) - Change the bot status color indicator for D-BUS errors or chat disconnects and set the activity indicator to display currently connected/total enabled Pidgin/Finch accounts. Setting this to false will disable updating the status indicator and activity so the bot will always appear as online(green).
• routes: (list, default: []) - A list containing multiple relay route dictionaries. A relay route dictionary defines a set of regex rules for input messages that can then be routed to multiple Discord targets channels.
  • route dictionary definition
    • name: (string, default: "relay_ID") - The identifier name used in logging and the console. This is simply an internal identifier and isn't relayed.
    • src: (string) - The service type of the source Pidgin/Finch account (ex: IRC, XMPP). This does nothing at the moment but may be implemented in the future for chat source specific overrides and handling.
    • filter_input_account: (string, default: .*) - The account input filter regex. A Pidgin/Finch message must match this and all other input regex filters to be relayed to targets. Regex DOTALL flag is enabled.
    • filter_input_sender: (string, default: .*) - The sender input filter regex. A Pidgin/Finch message must match this and all other input regex filters to be relayed to targets. Regex DOTALL flag is enabled.
    • filter_input_conversation: (string, default: .*) - The conversation input filter regex. A Pidgin/Finch message must match this and all other input regex filters to be relayed to targets. Regex DOTALL flag is enabled.
    • filter_input_message: (string, default: .*) - The message input filter regex. A Pidgin/Finch message must match this and all other input regex filters to be relayed to targets. Regex DOTALL flag is enabled.
    • filter_input_flags: (string, default: .*) - The flags input filter regex. A Pidgin/Finch message must match this and all other input regex filters to be relayed to targets. Regex DOTALL flag is enabled.
    • targets: (list, default: []) - A list containing multiple relay target dictionaries.
      • relay target dictionary definition
        • name: (string, default: "route_ID") - The identifier name used in logging and the console. This is simply an internal identifier and isn't relayed.
        • channel_id: (integer, required) - The target Discord channel ID.
        • title: (string, default: "") - The title prefixed to a relayed message. This title is included in the relayed message and can be anything.
        • embed: (bool, default: true) - Post message to this target as a Discord embed instead of plaintext.
        • embed_color: (integer, default: 4659341) - The color of a Discord embed (if embed=true).
        • timestamp: (bool, default: true) - Display the timestamp of the source message prefixed to relayed messages.
        • mention: (string, default: "") - The mention prefixed to relayed messages. Examples: "@here", "@everyone", "@group"
        • strip_mention: (bool, default: false) - Strips "@here" and "@everyone" from source messages before relaying the message. This option does not conflict with the "mention" setting for targets.
        • spam_control_seconds: (integer, default: false) - Do not relay a message if the same content has be successfully relayed in this many seconds ago. Setting this to 0 disables spam control and duplicate messages can be relayed.
• logger: (dict) - Logger configuration
  • log_purple_messages: (bool, default: true) - Logs all messages received by Pidgin/Finch into ./logs/purpleChat/. Includes time, account, sender, conversation, flags, message_raw/html, message text. Useful for building and testing input regex filters.
  • log_routed_messages: (bool, default: true) - Logs the message content and relay target channel id if the message was successfully relayed to ./logs/relayRoutes/
  • days_delete_after: (integer, default: 5) - Delete logs after this many days.

⁠Example

{
  "config": {
    "token": "",
    "max_dbus_reconnect": 5,
    "bot_status": true
  },
  "routes": [
    {
      "name": "RelayName",
      "src": "IRC",
      "filter_input_account": ".*",
      "filter_input_sender": ".*",
      "filter_input_conversation": ".*",
      "filter_input_message": ".*",
      "filter_input_flags": ".*",
      "targets": [
        {
          "name": "InternalRouteName",
          "channel_id": 123,
          "title": "Relay",
          "embed": true,
          "embed_color": 4659341,
          "timestamp": true,
          "mention": "@here",
          "strip_mention": true,
          "spam_control_seconds": 0
        }
      ]
    }
  ],
  "logger": {
      "log_purple_messages": true,
      "log_routed_messages": true,
      "days_delete_after": 5
  }
}

⁠Docker

The Docker variant of PurpleRelay uses Finch to provide a GUI-less connection to chat services for relaying to Discord.

⁠Supported tags and Dockerfile links

• stable⁠
• development⁠

⁠Quick reference

• Where to get help:

  Discord support server⁠

• Where to file issues:

  https://github.com/Nathan-LS/PurpleRelay/issues⁠

⁠Start an instance

This image uses a single Docker volume to persist the Finch config, logs, and routes.json. See volumes⁠ for information about Docker volumes.

See this guide⁠ for using Finch.

1. Create a named Docker volume.

   docker volume create relayvol
   

   Copy
2. Find the volume's mountpoint

   docker volume inspect relayvol | grep "Mountpoint"
   

   Copy
3. Place the configured routes.json file into the root of the volume's mountpoint.
4. Start PurpleRelay with the volume.

   docker run -it -v relayvol:/app --name myrelay nathanls/purplerelay
   

   Copy
5. Finch is started in the background on the container as a screen⁠ session named finch. You will need to exec into the container to initially sign into the chat accounts with Finch from another terminal session. If a volume is mounted at /app on the container the Finch config will persist across restarts. You can also manually edit files within the Pidgin/Finch config directory which would be located at /app/.purple on the container and volume.

   docker exec -it myrelay screen -r finch
   

   Copy

⁠Where to Store Data

Persist data through mounting named volumes to the /app directory within the container.

⁠Docker Stack and Compose

Example stack.yml for PurpleRelay:

version: '3.7'
services:
  purple:
    image: nathanls/purplerelay:stable
    deploy:
      restart_policy:
        condition: any
    volumes:
      - relayvol:/app
    networks:
      - purple-network

volumes:
  relayvol:

networks:
  purple-network:
    driver: overlay

⁠Running from source

⁠Requirements

• An operating system currently utilizing D-Bus (most Linux distributions)
• System packages for PyGObject⁠
• Python 3.7+ with packages from requirements.txt

⁠Installing dependencies and running

This section outlines the process for manually installing dependencies and running the application on Fedora⁠ if you choose not to utilize the Docker image of PurpleRelay.

Note: Package names and commands may differ between Linux distros.

1. Install Python3

   dnf install -y python38
   

   Copy

2. Install the PyGObject dependencies. See PyGObject install guide⁠

   dnf install -y gcc gobject-introspection-devel cairo-devel pkg-config python3-devel gtk3
   

   Copy

3. Clone and make a virtualenv

   mkdir ~/relay
   cd ~/relay
   git clone https://github.com/Nathan-LS/PurpleRelay.git
   cd PurpleRelay
   python3 -m venv venv
   source venv/bin/activate
   

   Copy

4. Install requirements

   pip3 install -r requirements.txt
   

   Copy

5. Rename routes-example.json to routes.json and add in your channel message routing. See Relay Configuration⁠ for information on configuration definitions.

   mv routes-example.json routes.json
   nano routes.json
   

   Copy

6. Make a Discord application/bot⁠ and copy the token to config->token in the routes.json file. See the relay-configuration⁠ on this document for config reference.

7. Ensure Pidgin or Finch is running and start the bot.

   ./venv/bin/python3 ./PurpleRelay
   

   Copy