WebSocket XMPP Gateway (WXG) - README

WXG (pronounce as "Wixig") is a Java-implementation of a gateway enabling communication with native XMPP[1] servers over the WebSocket protocol[2] and API[3], as specified in [4].

Until now, one of the common techniques in using XMPP in JS-powered Web applications was to make use of BOSH[5] and XMPP over BOSH[6]. However, with the advent of the WebSocket protocol and API already widely available in modern Web browsers, the unstable and slow BOSH technique should be replaced. Currently, most XMPP servers are not equipped with connectors for receiving and delivering stanzas over the WebSocket protocol as specified in [4].

The following scheme shows the basic functionality of WXG:

Client <----> ws(xmpp) <----> WXG <----> xmpp <----> XMPP Server

As such, WXG realizes two basic use cases:

1. When a client sends an XMPP stanza encapsulated in a WebSocket message, WXG "unpacks" the stanza and forwards it to the XMPP server natively.

2. When an XMPP server directs a stanza to one of its clients, WXG receives the native stanza, wraps it into a WebSocket message and forwards it to the client.

In the following we describe how to build, configure, and run WXG.

Prerequisites

• for running WXG, an installed Java Runtime Environment is required.
• for building WXG, an installed Java SDK is required.
• for performing automated builds of WXG, an installation of Apache Ant (http://ant.apache.org/) is required to run the bundled build script.

Check-out and build WXG

Perform the following steps to build WXG:

1. check out a copy of the git repository from github

   git clone git@github.com:hocken/wxg

2. change to the root directory of the WXG working copy

   cd wxg

3. perform an automated build using Apache Ant

   ant

The result of the building process is a JAR file wxg.jar

Configure WXG

Perform the following steps to configure WXG:

1. change to the conf directory relative to the WXG root directory

   cd ${WXG_HOME}/conf

2. edit the configuration file "server.xml" to your needs

All configurable parameters are documented in the configuration file.

Run WXG

Perform the following steps to run WXG:

1. change to the WXG root directory

2. run WXG

   java -jar wxg.jar

Access WXG from client-side

Open a new WebSocket and point it to ws://${WXG_HOSTNAME}:${WXG_PORT} where ${WXG_HOSTNAME} is the IP address or the hostname of the interface WXG is bound to and ${WXG_PORT} is the port specified in conf/server.xml. Keep in mind that according to [4] "xmpp" must be registered as subprotocol in the WebSocket object. WXG waits until the opening stream tag arrives and then reads the "to" attribute. Three options are available to define the hostname of the XMPP server to which the stream should be forwared:

1. Pass the desired hostname and port in the WebSocket URL Example: ws://localhost:8080/?xmpphost=jabber.com&xmppport=5222

2. Use the aliases db in conf/aliases.conf to rewrite the hostname set in the "to" attribute of the opening stream tag

3. Use the hostname set in the "to" attribute of the opening stream tag

The options are applied in the given order.

A simple testbed is available in ${WXG_HOME}/www/testbed.html. It can be accessed by pointing the browser to http://${WXG_HOSTNAME}:${WXG_PORT}/testbed.html (standard config: http://localhost:8080/testbed.html)

References

[1] P. Saint-Andre. Extensible Messaging and Presence Protocol (XMPP): Core. RFC3920. Oct 2004. http://www.ietf.org/rfc/rfc3920.txt [2] I. Fette. The WebSocket protocol. HyBi Working Group Internet Draft. Jun 2011. http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-09 [3] I. Hickson. The WebSocket API. W3C Editor's draft. Jun 2011. http://dev.w3.org/html5/websockets/ [4] J. Moffit, E. Cestari. An XMPP Sub-protocol for WebSocket. HyBi Working Group Internet Draft. Dec 2010. http://tools.ietf.org/html/draft-moffitt-xmpp-over-websocket-00 [5] I. Paterson, D. Smith, P. Saint-Andre, J. Moffitt. XEP-0124: Bidirectional-streams Over Synchronous HTTP (BOSH). XSF Draft Standard. Jul 2010. http://xmpp.org/extensions/xep-0124.html [6] I. Paterson, P. Saint-Andre. XEP-0206: XMPP Over BOSH. XSF Draft Standard. Jul 2010. http://xmpp.org/extensions/xep-0206.html