Using Apache Camel to implement an IRC bot

In this article I describe how to implement an IRC bot (automated conversation agent) using Apache Camel. Camel's IRC support is comprehensive, so the implementation of a simple bot is quite straightforward. The complexity comes, if it comes anywhere, in analysing the IRC conversation and generating suitable responses. My simple application is a little more complex than "Hello, World" in that respect, but not much more.

The Camel documentation explains the usage of the IRC support in detail. What the documentation doesn't do, unfortunately, is to give any guidance on how to use this support in a practical application. I was not able to find any full, practical examples that go beyond "Hello, World", so I have written one.

I have used the Quarkus framework to host my Camel routes, although that's just to make configuration easy. You could just as easily write a stand-alone Java application, or use Spring Boot as a framework. I won't be discussing framework issues at all in this article -- the actual Camel implementation is the same in all cases. I present some snippets of source code, but not the complete application. Full source code is available from my GitHub repository.

What an IRC bot does

Although it's somewhat old-fashioned, IRC is still widely used, particularly in IT organizations. A bot (presumably short for 'robot') is a piece of software that monitors IRC conversations, and provides automated responses where it is appropriate to do so.

A bot might, for example, detect people's names in a conversation, and automatically inject their contact details. Or it might provide timely alerts about certain events -- planned meetings, for example.

My example responds with sunrise and sunset times in a particular city. It's not necessarily a useful application, but it does demonstrate the essential features of a bot.

In practice, a bot might subscribe to particular IRC channels, and monitor conversation on those channels. Alternatively -- or, perhaps, in addition -- it might respond to personal messages outside of a channel. Camel's IRC support allows an application to subscribe to multiple channels, but it need not subscribe to any channels at all, and rely entirely on direct messages.

IRC clients differ in the way they allow users to send direct messages to other users (or bots). In most cases, however, you can fall back on the traditional command:

/msg some_nickname text...

My application handles both these forms of communication -- channel messages and direct messages. I would expect that, if a message is sent directly to the bot, it would always result in a response -- even if that response is an error message. However, most messages sent to a channel will, presumably, not evoke a response from the bot.

The screenshot below shows the bot at work, with the Hexchat IRC client providing the user part of the conversation. The bot, of course, does not have a specific client -- it is the client.

Note:
I'm assuming a reasonably thorough knowledge of Apache Camel in this article.

The basic Camel route

The essential outline of a Camel route that handles IRC conversations looks like this:

from ("irc:mynick@server:port?channels=foo,bar")
  // Work out if this message is for me. If it is,
  //   process it, and set the Camel body to the 
  //   reponse
  .to ("irc:mynick@server:port);

I've omitted a lot of detail, of course, but you can see that the actual IRC support is almost completely handled by Camel. The endpoint URI specifies the server, the bot's nickname, and channels to which to subscribe. You can connect to a TLS-encrypted IRC server using ircs rather than irc as the endpoint name, but you'll probably need additional configuration. Similarly, if the IRC server requires authentication, you'll need to specify credentials or a client certificate, depending on what the server accepts. These options are all described in the Camel documentation.

Notice that the .to() endpoint need not be the same IRC server as the one the from() endpoint is subscribed to -- in fact, it need not be an IRC server at all or, indeed, anything. However, if the targets of the from() and to() endpoints are the same server with the same credentials (if any), Camel is smart enough to realize that it can share a connection for both sending and receiving messages.

Is the message for me?

The bot probably won't respond to every message posted to every channel it monitors. However, it will most likely have to respond to messages directed directly to it, even if those messages can't be processed. Before making such a determination, however, the application will have to be sure that the message is even one that contains text.

The problem is that, once subscribed to a channel, the Camel route will receive every notification from the IRC server, including things like users joining and disconnecting. The type of the message is set by the Camel IRC consumer into an exchange header irc.messageType. All text messages are of type PRIVMSG. Although this name seems to denote a private message, all text messages are of this type -- this is the way the IRC protocol works.

Here is a way to specify in a Camel route that action is to be taken if the appropriate messageType header is set:

from ("irc:mynick@server:port?channels=foo,bar")
  .choice()
    .when (header ("irc.messageType").isEqualToIgnoreCase("PRIVMSG"))
      .to ("direct:privmsg")
    .end();

If the message is of the proper type, I'm sending it to another endpoint called privmsg. This is just for the purposes of organization: I could just embed the rest of the logic between when() and end(), but nesting these constructs can easily become unmanageable.

Assuming the message is of the correct type, the next thing to check is that it applies to this application. This will be true if either (a) it is directed to the application's IRC nickname, or (b) it contains some text that the application recognizes. For (a), we know that the message was sent specifically to this application if the irc.target header contains the application's nickname. If the message was sent to the channel, then this header will contain a channel name, which will always be preceded by "#".

For case (b) -- a channel message I recognize -- the logic might, in practice, be quite complex. In my simple application, however, I handle all channel messages that begin with suntimes, followed by a space.

Expressing these tests in a Camel route is a little fiddly and, to be frank, if the logic were even slightly more complicated than this, I would revert to using ordinary Java. Still, here's how it can be done using Camel:

from ("direct:privmsg")
  .choice()
    // The message is for me if irc.target is my own nick, or...
    .when (simple ("${header.irc.target} == '{{irc.mynick}}'"))
      .to ("direct://for_me")
    .end()
    .choice()
    // ... if the body starts with my keyword
    .when (simple ("${body} startsWith '{{irc.mykey}} '"))
      .to ("direct://for_me")
    .end();

Again to make things more readable, I've had this code invoke a new endpoint for_me when the message is definitely for this application.

Processing the message

I'm not brave enough to try to express the actual logic of the bot -- sunrise and sunset calculation -- as a Camel route. I've implemented the for_me endpoint as a direct call on a method in a Java class called IrcBean. The makeIrcResponse() method takes the message body -- which will be the IRC text -- as an argument, and returns the intended response as the new message body.

from ("direct:for_me")
  .bean (new IrcBean(), "makeIrcResponse(${body})")

Incidentally, if you are using the Quarkus framework, and intend to compile the application to native code and run without a Java JVM, you'll need to make special provision for the fact that IrcBean is loaded by name. The native compiler will not compile this class if it does not think it is aactually used. This is a fairly common problem with Camel, where loading classes by reflection is idiomatic. A simple way to tell the compiler that the class is loaded by reflection is to use a Quarkus annotation:

import io.quarkus.runtime.annotations.RegisterForReflection;

@RegisterForReflection
public class IrcBean
  {
  }

I'm not going to describe how the IRC message is processed in this application, because it's just a heap of mathematics. The processing of the message will, of course, depend entirely on what the bot actually does.

Where should I send the response?

It seems reasonable that, if the bot is processing a message that was sent to it directly, it should respond to the specific user that sent the message. However, if it was invoked by a channel message, it should respond to the channel.

We've already seen that the header irc.target will contain the name of the channel, if the message was sent to a channel. However, this header does not identify the sender, if the message was sent directly. In that case, we need to examine the irc.user.nick header, which will identify the sender's nickname.

To direct the message generated by the bot to the right place, we set the header irc.sendTo before invoking to(irc:...). To send to a channel, we use the channel name with its "#". To send to a user, we just use the user's nickname.

Closing remarks

I suspect that Camel's IRC support is not widely used; IRC itself is decreasingly prominent in the modern IT industry. However, Camel's support is extensive; with Camel, the outline of an IRC bot can be created in about a hundred lines of Java code.