Irc:Dev

IRC Interface Plugin Developer Notes

The documentation regarding the codebase so that developers can hack, extend and contribute to this plugin development.

Plugin Structure

/Irc
    ChannelResponseChannel.php
    Fake_Irc.php
    ircmanager.php
    IrcPlugin.php
    irc_waiting_message.php
    README
    /extlib

ChannelResponseChannel.php contains a class extending IMChannel to allow responses to IRC channels instead of via PMs

Fake_Irc.php contains a class overriding the Phergie’s send method to return the raw IRC command to send

ircmanager.php contains the IM manager class

IrcPlugin.php contains the IM plugin class

irc_waiting_message.php contains the class representing a waiting message object from the database table

The extlib directory contains the Phergie library

Throttling Limitations

IRC servers limit the number of messages a client is allowed to send within a certain period of time. A server normally limits a client to no more than one message per second (over the course of a minute). StatusNet’s IM architecture polls the queue of messages waiting to be sent and tries to send each a number of times. The issue is that these attempts can all be in a very short space of time, ie, before another message is allowed to be sent.

The best solution to this problem would be to first insert messages into a database table then use the Delayed Queue to reinsert one message at a time into the regular queue after a set amount of time in which a message can be sent again. Once a message is sent, the next message is taken from the database table and placed into the Delayed Queue pending reinsertion into the regular queue.

It is necessary to insert messages into the Delayed Queue one at a time instead of inserting all the messages at once (each with a delay one second greater than the previous) because there is no guarantee that once reinserted into the regular queue, that the messages would be handled instantly. This could mean that a number of messages are sent one after another despite the intent to delay them.

Unfortunately, at the time of writing, the Delayed Queue was not complete so a workaround is in use. Messages waiting to be sent are inserted into a database table (irc_waiting_message, see below for more details). The polling timeout for the manager is set to 1 second if there are waiting messages and each time the idle method is called (once every second), it checks whether there are pending messages and sends one if it is a second since the last message was sent.

Due to messages needing to be sent to confirm whether nicknames are registered, messages can be marked as needing to be prioritised meaning they will be processed before regular messages. Messages to NickServ to confirm whether nicknames are registered are prioritised by setting the "prioritise" field of the database to 1 (this is handled earlier in the IrcPlugin when the raw data is enqueued).

Database Table irc_waiting_message

The irc_waiting_message table stores messages throttled and waiting to be sent

    Attribute       Information
    -------------   -------------
    id              ID of message
    data            Blob containing data required to send message
    prioritise      boolean representing whether a message should be prioritised for sending
    attempts        Number of attempts to send message
    created         Time when message was queued
    claimed         Time when message was claimed for sending