forked from hocken/wxg
-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
executable file
·105 lines (69 loc) · 4.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
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 [email protected]:gordin/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