Pylons: Modern Async Eggdrop in Pure Python

Overview

Pylons is a flexible and extensible IRC bot network using a hub-and-leaf architecture. It implements a central hub bot managing multiple leaf bots, allowing for distributed IRC presence and easy scalability.

Version History

v1.0.0: Initial release with basic hub and leaf functionality
v1.1.0: Added plugin support and dynamic command handling
v1.2.0: Implemented encryption for hub-leaf communication
v1.3.0: Added support for IPv6 and improved error handling
v1.4.0: Introduced dynamic configuration updates (UPDATECONF commands)
v1.5.0: Improved nickname collision handling, added random username/realname generation, and enhanced ban evasion techniques

Features

Centralized hub bot managing multiple leaf bots
Secure communication between hub and leaf bots using custom encryption
Plugin system for easy extension of functionality
Support for both IPv4 and IPv6
Dynamic nick generation using Pokémon names with collision avoidance
Random, RFC-compliant username and realname generation for improved ban evasion
Automatic reconnection and error recovery
Runtime configuration updates
Kickban detection and automatic rejoin attempts
Improved handling of Unicode characters to prevent crashes

How It Works

The hub bot starts and listens for incoming connections from leaf bots.
Leaf bots connect to the hub and receive their initial configuration and available commands.
The hub bot manages all leaf bots, broadcasting commands and updates as necessary.
Leaf bots connect to IRC servers and channels based on their configuration from the hub.
Commands entered in the hub are executed across all connected leaf bots.
Dynamic Plugin creation that allows on-the-fly unloading and loading to broadcast new configurations to the links

Command List

test: Send a test message to the channel
join <channel>: Join a new channel
leave <channel>: Leave a channel
nick: Change nickname (generates a new random Pokémon-based nickname)
UPDATECONF <address> <port>: Update hub configuration
UPDATECONF.IRC <server> <port> <channel> [channel_password] [-ssl]: Update IRC configuration

Setup and Usage

Hub Bot

Clone the repository:

git clone https://github.com/strangeprogram/pylons.git
cd pylons

Run the hub bot:

python pylon.py --hub-address 0.0.0.0 --hub-port 8888 --server irc.example.com --port 6667 --channel "#your-channel"

Add --ssl if your IRC server uses SSL.

Leaf Bot

Run the leaf bot, pointing it to your hub:
```
python shard.py hub.example.com 8888
```
Replace hub.example.com with the address of your hub bot.

New Features and Improvements

Nickname Collision Handling: The hub now maintains a dictionary of used nicknames, ensuring unique nicks across all leaf bots.
Random Username and Realname Generation: Each leaf bot now generates random, RFC-compliant usernames and realnames for each connection, making it harder to create regex patterns for bans.
Kickban Detection: Leaf bots now detect kicks and bans, attempting to rejoin channels automatically with a limited number of retries.
Unicode Handling: Improved handling of non-UTF-8 characters in IRC messages to prevent bot crashes.
Enhanced SSL Support: Better SSL context handling for more secure connections.

Plugin Development

To create a new plugin:

Create a new Python file in the plugins directory.
Define a class that inherits from BasePlugin.
Implement the on_command method and define a commands property.

Example:

from hub_bot import BasePlugin

class MyPlugin(BasePlugin):
    async def on_command(self, sender, channel, command, args):
        if command == "hello":
            return {"type": "action", "action": "send_message", "channel": channel, "message": "Hello, World!"}

    @property
    def commands(self):
        return {"hello": "Say hello"}

Requirements

Python 3.7+
asyncio

License

This project is licensed under the GPL License - see the LICENSE file for details.

4.3 KiB Raw Blame History