irker is a specialized write-only IRC client intended to be used for shipping notification messages to IRC channels. The use case in mind when it was designed was broadcasting notifications from commit hooks in version-control systems.
irker is a socket server that listens on for UDP or TCP packets on port 6659 for textual request lines containing JSON objects and terminated by a newline. Each JSON object must have exactly two members: "to" specifying a destination or destination list, and "privmsg" specifying the message test. Examples:
{"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
{"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
{"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
If the channel part of the URL does not have one of the prefix characters “#”, “&”, or “+”, a “#” will be prepended to it before shipping.
The host part of the URL may have a port-number suffix separated by a colon, as shown in the third example; otherwise irker sends messages to the the default 6667 IRC port of each server.
irker takes the following options:
Takes a following value, setting the debugging level from it. This option will generally only be of interest to developers; consult the source code for details.
Write the program version to stdout and terminate.
Requests via UDP optimizes for lowest latency and network load by avoiding TCP connection setup time; the cost is that delivery is not reliable in the face of packet loss.
An irker instance with a publicly-accessible request socket could complicate blocking of IRC spam by making it easy for spammers to submit while hiding their IP addresses; the better way to deploy, then, is on places like project-hosting sites where the irker socket can be visible from commit-hook code but not exposed to the outside world. Priming your firewall with blocklists of IP addresses known to spew spam is always a good idea.
The absence of any option to set the service port is deliberate. If you think you need to do that, you have a problem better solved at your firewall.
IRC has a message length limit of 510 bytes and ignores any text after an embedded \n; generate your privmsg attribute values with appropriate care.
Eric S. Raymond <esr@snark.thyrsus.com>. See the
project page at http://www.catb.org/~esr/irker
for updates and other resources. The implementation uses the Python
IRC library by Joe Rosdahl and Jason R. Coombs.