gyng/betabot

Ruby bot with plugins. Has full IRC, basic Slack and Discord support.

betabot

* betabot has joined #teatime
<gyng> ~ping
<betabot> pong
<gyng> betabot: remind me about tea in 10 seconds
<betabot> Reminder in 0.0h set for 1970-01-01 00:00:10 UTC (UTC).
<betabot> 🔔 -0.0h gyng > gyng: tea

<gyng> ~install https://plugin.example.com/my_plugin/manifest.json save
<betabot> 🎉 Plugin pong installed.
<gyng> ~pong
<betabot> peng

betabot is a bot that aims to be protocol agnostic, easy to deploy and simple to develop for.

Features network adapters and plugin framework goodies (database ORM, web hooks, settings, install).

Has full IRC and basic Slack, Discord, and Matrix (unencrypted) support. Some useful plugins are also included. Not all included plugins support Slack, Discord, or Matrix right now.

Installation

You can choose either to use or not to use Docker to run betabot.

0. Download or clone this repository

   git clone https://github.com/gyng/betabot.git
   

First run

With Docker

GitHub Packages

0. Requirements: Docker, Docker Compose V2

1. Use the prebuilt image, or

2. Build the image from source. You might need to configure the ports used by the webserver and plugins.

   docker build . -t betabot
   

3. Create an admin account (auth level 5) with the wizard

   docker-compose run --entrypoint sh bot
   rake make_user
   
   # or with the command
   
   docker-compose run --entrypoint sh bot
   rake make_user_cmd[name,password,auth_level]
   

4. Configure the bot

5. Start the bot

   docker-compose up
   
   # or in detached mode
   
   docker-compose up -d
   

6. Install external plugins if wanted

   # for example, as an admin
   ~login user pass
   ~install https://raw.githubusercontent.com/gyng/betabot-example-plugin/master/manifest.json
   

7. See commands

   # For plugins
   ~help
   
   # For core triggers (admin)
   ~help core
   

Settings, accounts, databases, and the public directory are persisted with usage of Docker. The image needs to be rebuilt (easily with docker-compose up --build -d) when adapters or plugins are changed or added. As of now, the port mappings in docker-compose.yml must be changed manually when not using default ports.

In dev mode

This launches betabot in docker dev mode: the entire directory is mounted in an alpine container, and the bot is started. Note: restart: always is enabled, so you need to kill it to stop it.

CURRENT_UID=$(id -u):$(id -g) docker-compose -f docker-compose.dev.yml up --build
CURRENT_UID=$(id -u):$(id -g) docker-compose -f docker-compose.dev.yml up --build --detach

or run the script which runs docker-dev in detached mode

./docker-dev.sh

logs can be followed with docker log -f, and the ID can be found using docker ps.

Without Docker

1. Requirements: Ruby version >= 3.1.2, Bundler.

2. Install the gems with Bundler. You might need sqlite-dev and imagemagick packages installed on your system for gem installation.

   bundle install
   # or
   bundle install --path vendor
   

3. Create an admin account (auth level 5) with the wizard

   rake make_user
   

   or the command

   rake make_user_cmd[name,password,auth_level]
   

4. Configure the bot

5. Start the bot

   ruby start_bot.rb
   

Usage

Configuration

For bot settings, betabot will read from bot_settings.user.json. This file will be automatically created on startup if it does not exist. bot_settings.user.json is ignored in .gitignore, which makes it easier to update betabot using git.

cd lib/settings
cp bot_settings.default.json bot_settings.user.json

Settings files that may need changing:

• ./lib/settings/bot_settings.user.json (for web server configuration options check below)
• ./lib/settings/adapters/irc.json (and any per-adapter settings)
• ./lib/settings/adapters/slack.json (and any per-adapter settings)
• ./lib/settings/adapters/discord.json (and any per-adapter settings)
• (Optional) any plugin settings in ./lib/settings/plugins/

Add the adapters to be run on startup to the autostart key in bot_settings.user.json. Currently supported adapters are slack and irc.

Note that adapter and plugin settings files are generated with default settings on first run for a fresh install as of now. They do not exist before first run.

Discord

If using Discord, you will need to invite your bot instance to your server. Use the permissions generator and insert your client ID. An app can be created at the Discord developer dashboard. api_token refers to the app bot user's token.

Web server configuration details

• enabled – whether the webserver runs on startup
• link_url – the URL for plugins to use (eg. http://lollipop.hiphop:9999 or http://www.example.org)
• host – the listening host; leave this at 0.0.0.0 and it should work
• port – your listening port

Disable SSL verification

Run bot with BETABOT_SSL_NO_VERIFY=1.

BETABOT_SSL_NO_VERIFY=1 ruby start_bot.rb

(IRC) Calling the bot

BotNickname: command arg1 arg2 or (trigger_shorthand)command arg1 arg2

For example: !ping, MyBot: ping

A few default plugins

• image – Saves all image links and records data about them in a database. Images are saved in ./public/i. The image plugin also gives a random image link from the image database if the web server is running.
• entitle – Echos titles of uninformative URLs.
• entitleri – Uses imginfer search to guess the contents of image URLs.
• shipment – Tracks packages using Aftership requires setup of API keys
• mpcsync – Synchronizes playing of video files in MPC. Requires configuration of MPC addresses.
• script/macro – Script/Macro definition support.
• showtime – Checks Anilist for anime airing times requires setup of API keys
• unicode – Search for Unicode characters or emoji by description, and identify Unicode characters
• wolfram – Queries Wolfram|Alpha. requires setup of API keys

For all plugins, see the plugins and external_plugins directory.

Core commands

Use ~help core for help with core commands.

• help
• help [plugin]
• help core
• install [external_plugin_manifest_json_url]
• install [external_plugin_manifest_json_url] save
• update [external_plugin_name]
• update [external_plugin_name] save
• remove [external_plugin_name]
• remove [external_plugin_name] save
• plugin_check_list
• reset_plugin [plugin_name]
• blacklist
• blacklist_adapter [name]
• blacklist_plugin [name]
• blacklist_user [name regex]
• blacklist_content [name regex]
• unblacklist_adapter [name]
• unblacklist_plugin [name]
• unblacklist_user [name regex]
• unblacklist_content [name regex]
• login [nick] [pass]
• logout
• reload # (reloads plugins)
• restart
• shutdown
• useradd [accountname] [password] [authlevel 0-5]
• version

IRC core commands

Auth level 4 needed.

• reconnect
• disconnect
• join [channel]
• part [channel]
• nick [nick]
• defaultchan-add [server] [channel]
• defaultchan-rm [server] [channel]
• defaultchan-ls

Plugin management

As a command (Recommended)

As an admin account (auth >= 5):

~install <manifest_url>
~install <manifest_url> save
~update <plugin_name>
~remove <plugin_name>
~remove <plugin_name> save
~plugin_check_list

If save is supplied, the plugin will be added to the list of plugins to be checked for installation/updates on startup. These settings are saved to bot_settings.user.json.

The plugin might require dependencies. If so, run bundle install and restart the bot.

CLI (Not recommended)

rake install_plugin[$MANIFEST_URL]
rake update_plugin[$PLUGIN_NAME]
rake remove_plugin[$PLUGIN_NAME]

These commands do not provide options to update bot_settings.user.json and are therefore not recommended.

Plugin development

See: Plugin development

Tests

Docker: `docker-compose -f docker-compose.test.yml up --build

Tests can be run with bundle exec rspec. Current test coverage is very limited. Rubocop can be run with bundle exec rubocop.

The EventMachine reactor has to be set up and torn down for most specs so there is a helper method with_em(&block) included in spec_helper.rb.

Tests for plugins are to be placed inside a spec directory in the plugin directory. See the ping plugin for an example.

The project is linted with Rubocop, and will fail CI if any violations are found.

License

betabot is licensed under the MIT License.

betabot's Issues

Improve settings management

It is a mess right now. It

• makes upgrading via git annoying
• makes plugin development annoying: updated settings hashes for defaults do not get loaded until the JSON file is deleted

Ideally, default settings files should be checked in, and verified on plugin/adapter load. Empty .user.json files (eg, {}, or { api_key: 'CHANGE_ME' }should be generated on load if they do not exist.

A file structure might look like

- settings
  - defaults (checked in, verified on load)
    - adapters
    - plugins
      - ping.default.json
      - tell.default.json
    - bot.default.json
  - user
    - adapters
    - plugins
      - ping.user.json
    - bot.user.json

user.json files should not be checked into git.

Clean up blacklist core trigger implementation

Instead of blacklist_user, unblacklist_content etc., do a blacklist user add foo, blacklist user del foo.

Will need to do an enum check for the type (user, content, etc), since that is implicitly done using the former right now.

Improve first run experience

It's terrible having to run twice before being able to config. Maybe a ruby setup.rb will be nice.

Add types for Ruby 3

For a start, core, adapter, and plugin classes.

Tell: Add Slack support

Convert plugin system to use Git instead of zip files

This will make maintaining, publishing, and updating plugins easier, as there is no longer a publishing step.

• Rakefile tasks (convert existing ones to use git), maybe allow a tag option
• Move lib/plugins to plugins
• Update object loader in bot core
• Update Gemfile
• Remove packages directory

Fix Rubocop Security/Open exceptions

Most can be replaced with rest-client, which is included in the Gemfile.

Add address validation

Adapters should have validate_addr.

Split out docs for external plugin development

Nobody but me really needs to know the details of bundled plugin dev.

Core: Replace EventMachine with async

https://github.com/socketry/async

EventMachine is showing its age.

Add #address to Message class

This will let us serialize references to messages.

Use case:

Serialize remind timers so they persist between restarts.

Exceptions in plugins should never crash the bot

Right now it does, and is really scary. We can just wrap a begin-rescue-end around the plugin entry point.

Showtime: anilist token expiry check fails to renew expired token

Ctrl+C does not kill process and Sinatra

This is due to EventMachine refusing to die. SIGTERM and SIGINT need to be trapped. The webserver also needs to be killed if it exists.

See this example for details.

Add Slack adapter

Slack seems like a good fit for betabot since it's pretty much IRC++.

Also consider the differences in message format: adapter might require additional work to make plugins fit Slack better (eg. attach adapter name to messages so individual plugins can decide how to format text, or call adapter-specific-message methods).

API reference

Slack: Add slash command integrations

Need to figure out how to do this. Maybe pass the command map from core to adapters on startup.

Move the remind connection persistence hack into message

This will make it transparent to plugins.

Plugins using EventMachine do not work in Discord

Seems like discordrb is taking control of the EventMachine reactor? Timers added after @client.run do not trigger at all.

Let plugins indicate compatibility with adapters

So plugins specific to an adapter(s) can be loaded just for that adapter.

Remove rubyzip from Gemfile

It's no longer used now that plugins use git.

Add standardised plugin file naming convention

Should, as a forward-compatiable alternative, load from index.rb or main.rb or plugin.rb instead of pong.rb.

Add listener for health checks

Fix regexes for image and entitleri not breaking on whitespace

http://mylink some text matches the entire string instead of http://mylink.

Core: Explore replace WEBrick with falcon

Needs #74

https://github.com/socketry/falcon

Add raw field to core message

Slack has formatted text which is unescaped and stored in message.text. We want to preserve the original formatted message somewhere.

Dockerise betabot

Would be a pretty neat thing to have. Will need to persist the database and expose webserver ports.

Might need to move settings files around into a directory to be persisted. Databases should already be in a directory, check if the database constructor needs to be locked into the database directory.

Create convenience method to broadcast message without a handler to an existing message

• Message needs a broadcast static method
• Need references to adapters in plugins so messages have a proper origin attr

Add CI for Docker builds

It would be great if the Docker build process is tested.

See: https://docs.travis-ci.com/user/docker/

Add help for core commands

Right now it's only for plugins.

Image: Add exif plugin