Kaazing WebSocket Gateway
Orange guy with box of questions

How to Use the JavaScript IrcClient Client Library

Technologies used: IRC and JavaScript

This document contains the following sections:

Overview of IRC

Internet Relay Chat (IRC) is an open, TCP-based protocol for real-time instant messaging and conferencing. Using an IRC client, you can participate in group discussions by using channels (chat rooms) and you can send private messages to other IRC users. IRC servers can connect to other IRC servers to create an infrastructure in which IRC messages are routed in the most efficient way using a multicast architecture. Unlike non-multicasting protocols, like XMPP, each IRC message is sent just once.

IRC is a line-based protocol. IRC clients send single-line messages to the IRC server and receive single-line replies from other clients. IRC commands can be sent by prefixing them with a slash (/). For example, you can join a channel using the command /join #channelname. After you join a channel, you can send messages to other users on that channel by issuing the command /privmsg nickname (message). IRC clients often hide command syntax complexities from the user by providing an easy-to-use user interface (UI).

For more information on IRC, visit Wikipedia article about Internet Relay Chat and http://www.irc.org/.

IRC Servers and Networks

Applications built with the IrcClient JavaScript library connect to an IRC server. For example, the IRC demo in the Kaazing Gateway demo bundle is configured to connect to the hosted IRC server chat://freenode.net. You can also configure Kaazing Gateway to connect to another IRC server or network of IRC servers (hosted or local). The following are some of the most popular IRC networks:

  • EFnet
  • IRCnet
  • QuakeNet
  • Undernet
  • Freenode

WebSocket and IRC

WebSocket enables direct communication from the browser to an IRC server. Kaazing Gateway provides the IrcClient client library, which radically simplifies the application design and eliminates the need for using convoluted server- and client-side architectures to map server-side protocols to the browser over HTTP. Web developers can use the browser’s native JavaScript support and code directly against the back-end services without the need for custom Servlets or server-side programming.

Using the IrcClient JavaScript client library, you can take advantage of many IRC features, making JavaScript a first-class citizen in IRC messaging systems. The IrcClient JavaScript library uses Kaazing's ByteSocket client library, because IRC supports binary communication. Since the implementation is layered on top of ByteSocket, which uses WebSocket--and thus the entire stack of Kaazing HTML 5 Communications client libraries--applications developed using the IrcClient JavaScript library are provided with guaranteed persistence, reliability, and message-receipt acknowledgment all the way to the browser.

Taking a Look at the IRC Demo

Before you start, take a look at a demonstration that was built with the IrcClient JavaScript library: the IRC demo that is part of the Kaazing Gateway demo bundle. To see this demo in action, perform the following steps:

  1. Start the Kaazing WebSocket Gateway demo bundle as described in Getting Started.
  2. In a browser, navigate to http://localhost:8000/demo/demo.html#irc.

You can connect from the browser as well as from a desktop client such as Pidgin and send messages back and forth between the two clients. The demo intentionally exposes the IRC functionality in a plain and simple way. In an actual application you might choose to spend additional time on coding a compelling UI.

Configuring Kaazing Gateway to Connect to an IRC Server

The following is an example of the default configuration element for the IRC service, as specified in the configuration file KAAZING_HOME/conf/gateway-config.xml:

<!-- Proxy to Freenode IRC server -->
<service>
  <!-- ws:// scheme refers to WebSocket -->
  <!-- wss:// scheme refers to WebSocket (secure) -->
  <accept>ws://localhost:8000/freenode</accept>
  <accept>wss://localhost:9000/freenode</accept>

  <type>proxy</type>
  <properties>
    <connect>tcp://chat.freenode.net:6667</connect>
  </properties>

  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
  <cross-site-constraint>
    <allow-origin>https://localhost:9000</allow-origin>
  </cross-site-constraint>
</service>

As you can see, this service is configured to accept WebSocket IRC requests from the browser at ws://localhost:8000/freenode and securely at wss://localhost:9000/freenode and proxy these requests to the IRC server chat.freenode.net on port 6667 (IRC servers typically use port 6667).

To configure Kaazing Gateway to accept WebSocket requests at another URL or to connect to a different IRC server, you can edit KAAZING_HOME/conf/gateway-config.xml, update the values for the accept elements or change the connect property, save the file, and restart Kaazing Gateway. For example, the following configuration configures Kaazing Gateway to accept WebSocket IRC requests at ws://localhost:8010/irc and proxy those requests to a locally installed IRC server (localhost) on port 6667.

<!-- Proxy to Freenode IRC server -->
<service>
  <accept>ws://localhost:8010/irc</accept>

  <type>proxy</type>
  <properties>
    <connect>tcp://localhost:6667</connect>
  </properties>

  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
</service>

Using the IrcClient JavaScript Library in a Web Application

This section contains the following subsections:

Note: The IrcClient API is not finalized and is provided for evaluation purposes. Users of this protocol may have to change their code in future releases until the APIs are finalized. Your feedback is appreciated and can be provided at www.kaazing.org.

Creating the IrcClient Object

In this section you'll see how you create the IrcClient Object. Before you create the client object, open your Web application in your favorite editor and import the appropriate client libraries. In the <HEAD> section of your HTML Web application file, add the following script includes:

<script src="/html5/ByteSocket.js"></script>
<script src="/protocol/IrcClient.js"></script>

Since IRC supports binary communication, you must include a reference to the ByteSocket client library.

Next, create an instance of the IrcClient object as shown in the following example.

var client = new IrcClient();

Now that you have created an instance of the IrcClient object, you can use commands and attach callback functions to handle the interactions between the client and the IRC server. As with all the Kaazing protocols, there are two types of functions--command functions and asynchronous callback functions.

  • Command Functions--Client-initiated operations that are sent from the client to the IRC server. For example, to join an IRC channel, you use the join function. Some examples of IRC command functions are:
    • nick
    • list
    • join
    • privmsg
  • Asynchronous Callback Functions--Server messages that are sent from the IRC server to the client at any time (asynchronously). For example, when another person that is subscribed to the same channel that the client is subscribed to sends a message (privmsg) to the channel, the onprivmsg callback function is called on the client and the IRC client can process and display the message text on the Web application page. Some examples of IRC callback functions are:
    • onchannellist
    • onjoin
    • onprivmsg
    • onclose

Refer to the JavaScript API documentation for the complete list of all the IRC command and callback functions.

Joining an IRC Server

In this section, you'll see how you can join an IRC server. Joining an IRC server is a two-step process:

  1. First, you must connect to Kaazing Gateway, which is configured to proxy requests to the IRC server. To do this, you use the connect function and pass in the URL of the IRC service. This URL is the one specified in the accept element in the Kaazing Gateway configuration file KAAZING_HOME/conf/gateway-config.xml. By default it is ws://localhost:8000/freenode).

client.connect(url.value);

When you successfully connect, you receive the onopen callback.

  1. Next, connect to the IRC server. To do this, you must use the following commands:
  • Password (pass)--A command to supply a password for the user. Passwords are optional and not required on most IRC servers.
  • Nick Name (nick)--A command to request a nick name or user handle that the user connects with. Since names are not always immediately removed from the channel when a client disconnects and since IRC servers do not allow duplicate nick names, you may not be able to log in to the IRC server again with the same nick name after disconnecting.
  • User Name (user)--A command to associate a real name to your nick name.

The following example shows how you can use the onopen callback function to automatically log in a user:

client.onopen= function () {
  //optional password
  // client.pass(password.value);
  client.nick(username.value);
  client.user(username.value,realname.value);

};

Once you have joined an IRC server, you can use the IRC functions to perform the IRC commands.

Listing and Joining Channels

In this section, you'll see how you can list and join IRC channels.

Listing Channels

To get a list of available channels on your IRC server, you use the list command (with or without arguments). If you use the list command without any arguments, the onchannellist callback function returns all available channels. If you pass in the name or part of a name (for example, /list #kaazing) as an argument, the onchannellist callback function returns all available channels that match that string in a comma separated list, as shown in the following example.

client.list(arguments);

When the response is returned, you can process the names of channels inside the onchannellist callback function, as shown in the following example. You can then process the returned information in your Web application. The following example shows how you can populate a list of all available channels in the UI of your Web application:

client.onchannellist= function (message) {
  //do stuff
};

Joining Channels

To join a channel on your IRC server, you can call the join command, passing in the channel name (for example, /join #kaazing) as shown in the following example. The onjoin command returns a message object, which contains fields like the number of members and the channel's name.

client.join(arguments);

You can register the onjoin handler to process the information in the message object that the join command returns. You can use the returned information in the UI of your Web application as shown in the following example.

client.onjoin= function (message) {
  response("Number of Members: " + message.noOfMembers + " on Channel: " +     message.channelName);
};

Sending and Receiving Messages

In this section you will see how you can send and receive IRC messages.

Sending Messages

Once you have joined a channel, you can send messages to that channel. You can also send messages directly to other connected users. To send messages (to both users and channels), you use the privmsg command, passing in a user or channel name as the destination and a text string as the message, as shown in the following example.

client.privmsg(destination, message);

Receiving Messages

The callback function onprivmsg must be implemented to handle incoming IRC messages (private or on a channel). It can be used to display the messages in the UI as shown in the following example.

client.onprivmsg= function (message) {
  response("New message: " + message.nick+", Param:" + message.param + ",   Source:" + message.source);
};

Summary

As you have seen in this how-to, you can build Web applications that can communicate directly from the browser with an IRC server using the IrcClient JavaScript library. Thus, with the help of WebSocket the browser now enjoys the first-class citizenry of IRC communications that has long been enjoyed by desktop applications. Refer to the JavaScript API documentation for the complete list of all the IRC command and callback functions.