coreplugin: sanity check: make sure irc.connected is set after 2 seconds & mention how setting this is neccessary in docs

coreplugin.py

@@ -265,3 +265,13 @@ def reload(irc, source, args):
         return
     if unload(irc, source, args):
         load(irc, source, args)
+
+def main(irc=None):
+    # This is a global sanity check, to make sure the protocol module is doing
+    # its job.
+    if irc and not irc.connected.wait(2):
+        log.warning('(%s) IRC network %s (protocol %s) has not set '
+                    'irc.connected state after 2 seconds - this may be an '
+                    'in the protocol module code, and will cause plugins like '
+                    'relay to not work correctly!', irc.name, irc.name,
+                    irc.protoname)

docs/technical/pmodule-spec.md

@@ -18,6 +18,8 @@ Protocol modules have some *very* ***important*** jobs. If any of these aren't d
 
 5) Implement a series of camelCase `commandServer/Client` functions - plugins use these for sending outgoing commands. See the `Outbound commands` section below for a list of which ones are needed.
 
+6) Set the threaded event `irc.connected` (via `irc.connected.set()`) when the initial connection + burst phase is complete. This is important for plugins like relay that do state checking, and they will fail to work if this is not set.
+
 ## Core functions
 
 The following functions *must* be implemented by any protocol module within its main class, since they are used by the IRC internals.

pylink

@@ -42,6 +42,8 @@ if __name__ == '__main__':
 
     for network in conf.conf['servers']:
         proto = utils.getProtoModule(conf.conf['servers'][network]['protocol'])
-        world.networkobjects[network] = classes.Irc(network, proto, conf.conf)
+        world.networkobjects[network] = irc = classes.Irc(network, proto, conf.conf)
+        log.debug('Calling main() function of coreplugin on network %s', irc.name)
+        coreplugin.main(irc)
     world.started.set()
     log.info("loaded plugins: %s", world.plugins)