doc/readme.xquery

   1 OVERVIEW
   2 ========
   3
   4 The extension query mechanism provides a means by which servers may
   5 send queries to other servers and receive replies.  Obviously,
   6 ordinary ircu servers have no need of this mechanism, but it allows
   7 pseudo-server services to communicate with each other.  Additionally,
   8 extensions have been made to the iauth protocol (see readme.iauth) to
   9 allow iauth instances to send and receive extension queries.  This
  10 could be used, for instance, to submit client information for
  11 immediate proxy scanning by a centralized service, or to query a
  12 centralized database for log-in parameters.
  13
  14 DETAILED DESCRIPTION
  15 ====================
  16
  17 The extension query mechanism consists of a pair of commands, the
  18 XQUERY command (token XQ) and the XREPLY command (token XR).  Servers
  19 and IRC operators may send an XQUERY, naming a target service, an
  20 opaque "routing" token, and the query; the target service is expected
  21 to reply with an XREPLY, which will include the routing token from the
  22 query and the service's reply to the query.
  23
  24 The query syntax is:
  25
  26   <prefix> XQ <target> <routing> :<query>
  27
  28 where <target> is the target service's numeric nick, <routing> is the
  29 opaque "routing" token, and <query> is the query for the service to
  30 act upon.  IRC operators may also issue queries, using the XQUERY
  31 command with the same parameters, with <target> permitted to be a
  32 server name mask; this is largely intended for debugging purposes.
  33 Ordinary users cannot issue XQUERY commands, in order to encourage use
  34 of the regular PRIVMSG and NOTICE commands.
  35
  36 The reply syntax is:
  37
  38   <prefix> XR <target> <routing> :<reply>
  39
  40 where <target> is the origin of the original query, <routing> is the
  41 opaque "routing" token from the query, and <reply> is the service's
  42 reply to the query.  This command can only be issued by servers.
  43
  44 USE WITH IAUTH
  45 ==============
  46
  47 Three message extensions have been made to the iauth protocol.  An
  48 iauth instance can issue an XQUERY through the use of the "X" client
  49 message with the following syntax:
  50
  51   X <servername> <routing> :<query>
  52
  53 If <servername> is not presently linked to the network, ircu will
  54 respond with an "x" server message, having the following syntax:
  55
  56   <id> x <servername> <routing> :Server not online
  57
  58 If, on the other hand, <servername> names a valid, on-line server,
  59 ircu will prepend "iauth:" to the "routing" token and forward the
  60 query to that server.  If an XREPLY is received from the service, ircu
  61 will strip off the "iauth:" prefix on the "routing" token and send the
  62 reply to the iauth instance with the "X" server message:
  63
  64   <id> X <servername> <routing> :<reply>
  65
  66 Having the "iauth:" prefix on the "routing" token enables future ircu
  67 extensions which wish to use the extension query mechanism to be
  68 differentiated from extension queries originated from iauth.
  69
  70 RATIONALE
  71 =========
  72
  73 The extension query mechanism was originated as part of an effort to
  74 establish a reliable login-on-connect system for Undernet.  Previous
  75 attempts at such a system required out-of-band parallel connections,
  76 and could possibly result in a compromise of hidden IPs (such as the
  77 IP of X's database server).  Further, without extensive extensions to
  78 GNUWorld, certain login restrictions--such as the maximum logged-in
  79 client count--could not be reliably enforced.  By providing an in-band
  80 signalling mechanism that iauth can make direct use of, these problems
  81 are eliminated; the only remaining problem is what to do if iauth is
  82 unable to communicate with the login service, which can be solved
  83 through policy decisions and timeouts implemented within the iauth
  84 instance.
  85
  86 The rationale for the opaque "routing" token is to provide pairing
  87 between replies and queries.  The lack of such pairing is one of the
  88 shortcomings of the IRC protocol, as specified in RFC 1459; only one
  89 Undernet extension has attempted to provide such a pairing--a
  90 little-used extension to the /WHO command.  In an iauth context, such
  91 pairing is critical; otherwise, iauth could potentially apply a reply
  92 to the wrong client.  Although the pairing could be part of the query,
  93 it makes sense to make it part of the base protocol message, making it
  94 explicit.  This also allows ircu to add routing data to the token,
  95 making it possible for more extensions than just iauth to make use of
  96 extension queries.