PyLink/docs/technical/hooks-reference.md

PyLink hooks reference

Introduction

In PyLink, protocol modules communicate with plugins through a system of hooks. This has the benefit of being IRCd-independent, allowing most plugins to function regardless of the IRCd being used. Each hook payload is formatted as a Python list, with three arguments (numeric, command, args):

1. numeric: The sender of the message (UID).

2. command: The command name (hook name) of the payload. These are always UPPERCASE, and those starting with “PYLINK_” indicate hooks sent out by IRC objects themselves, that don’t require protocol modules to send.

3. args: The hook data (args), a Python dict, with different data keys depending on the command given.

Note that the ts key is automatically added (using the current time) to all hook data dicts that don’t include it - such a key should only be provided if the command the uplink IRCd send has a TS value itself.

Example syntax

The command :42XAAAAAB PRIVMSG #dev :test would result in the following raw hook data:

• ['42XAAAAAB', 'PRIVMSG', {'target': '#dev', 'text': 'test', 'ts': 1451174041}]

On UnrealIRCd, because SETHOST is mapped to CHGHOST, :GL SETHOST blah would return the raw hook data of this (with the nick converted into UID by the UnrealIRCd protocol module):

• ['001ZJZW01', 'CHGHOST', {'ts': 1451174512, 'target': '001ZJZW01', 'newhost': 'blah'}]

Some hooks, like MODE, are more complex and can include the entire state of a channel! This will be further described later. :GL MODE #chat +o PyLink-devel is converted into (pretty-printed for readability):

['001ZJZW01',
 'MODE',
 {'modes': [('+o', '38QAAAAAA')],
  'oldchan': IrcChannel({'modes': set(),
                        'prefixmodes': {'admins': set(),
                                        'halfops': set(),
                                        'ops': set(),
                                        'owners': set(),
                                        'voices': set()},
                        'topic': '',
                        'topicset': False,
                        'ts': 1451169448,
                        'users': {'38QAAAAAA', '001ZJZW01'}}),
  'target': '#chat',
  'ts': 1451174702}]

Core hooks

The following hooks, sent with their correct data keys, are required for PyLink’s basic functioning.

• ENDBURST: {}
  • The hook data here is empty.
  • This payload should be sent whenever a server finishes its burst, with the SID of the bursted server as the sender.
  • Plugins like Relay need this to know that the uplink has finished bursting all its users!
• PYLINK_DISCONNECT: {}
  • This is sent to plugins by IRC object instances whenever their network has disconnected. The sender (numeric) here is always None.
• PYLINK_SPAWNMAIN: {'olduser': olduserobj}

  • This is sent whenever Irc.spawnMain() is called to (re)spawn the main PyLink client, for example to rejoin it from a KILL. It basically tells plugins that the UID of the main PyLink client has changed, while giving them the old data too.

  • Example payload:

  • {'olduser': IrcUser({'away': '',
                       'channels': {'#chat'},
                       'host': 'pylink.local',
                       'ident': 'pylink',
                       'identified': False,
                       'ip': '0.0.0.0',
                       'manipulatable': True,
                       'modes': {('o', None)},
                       'nick': 'PyLink-devel',
                       'realhost': 'pylink.local',
                       'realname': 'PyLink development server',
                       'ts': 1452393682,
                       'uid': '7PYAAAAAE'}),
     'ts': 1452393899)}

IRC command hooks

The following hooks represent regular IRC commands sent between servers.

(under construction)