SockJS family:
- SockJS-client JavaScript client library
- SockJS-node Node.js server
- SockJS-erlang Erlang server
- SockJS-lua Lua/Luvit server
- SockJS-tornado Python/Tornado server
- vert.x Java/vert.x server
SockJS is a browser JavaScript library that provides a WebSocket-like object. SockJS gives you a coherent, cross-browser, Javascript API which creates a low latency, full duplex, cross-domain communication channel between the browser and the web server.
Under the hood SockJS tries to use native WebSockets first. If that fails it can use a variety of browser-specific transport protocols and presents them through WebSocket-like abstractions.
SockJS is intended to work for all modern browsers and in environments which don't support WebSocket protcol, for example behind restrictive corporate proxies.
SockJS-client does require a server counterpart:
- SockJS-node is a SockJS server for Node.js.
Philosophy:
- The API should follow HTML5 Websockets API as closely as possible.
- All the transports must support cross domain connections out of the box. It's possible and recommended to host SockJS server on different server than your main web site.
- There is a support for at least one streaming protocol for every major browser.
- Streaming transports should work cross-domain and should support cookies (for cookie-based sticky sessions).
- Polling transports are be used as a fallback for old browsers and hosts behind restrictive proxies.
- Connection establishment should be fast and lightweight.
- No Flash inside (no need to open port 843 - which doesn't work through proxies, no need to host 'crossdomain.xml', no need to wait for 3 seconds in order to detect problems)
Subscribe to SockJS mailing list for discussions and support.
SockJS comes with some QUnit tests and a few smoke tests (using SockJS-node on the server side). At the moment they are deployed in few places:
- http://sockjs.popcnt.org/ (hosted in Europe)
- http://sockjs.cloudfoundry.com/ (CloudFoundry, websockets disabled, loadbalanced)
- https://sockjs.cloudfoundry.com/ (CloudFoundry SSL, websockets disabled, loadbalanced)
- http://sockjs.herokuapp.com/ (Heroku, websockets disabled)
SockJS mimics WebSockets API
but instead of WebSocket
there is a SockJS
Javascript object.
First, you need to load SockJS JavaScript library, for example you can put that in your http head:
<script src="http://cdn.sockjs.org/sockjs-0.2.min.js">
</script>
After the script is loaded you can establish a connection with the SockJS server. Here's a simple example:
<script>
var sock = new SockJS('http://mydomain.com/my_prefix');
sock.onopen = function() {
console.log('open');
};
sock.onmessage = function(e) {
console.log('message', e.data);
};
sock.onclose = function() {
console.log('close');
};
</script>
Similar to 'WebSocket' class 'SockJS' constructor takes one, or more arguments:
var sockjs = new SockJS(url, _reserved, options);
Where options
is a hash which can contain:
-
debug (boolean)
Print some debugging messages using 'console.log'.
-
devel (boolean)
Development mode. Currently setting it disables caching of the 'iframe.html'.
-
protocols_whitelist (list of strings)
Sometimes it is useful to disable some fallback protocols. This option allows you to supply a list protocols that may be used by SockJS. By default all available protocols will be used, which is equivalent to supplying: "['websocket', 'xdr-streaming', 'xhr-streaming', 'iframe-eventsource', 'iframe-htmlfile', 'xdr-polling', 'xhr-polling', 'iframe-xhr-polling', 'jsonp-polling']"
Although the 'SockJS' object tries to emulate the 'WebSocket' behaviour, it's impossible to support all features. One of the important SockJS limitations is the fact that you're not allowed to open more than one SockJS connection to a single domain at a time. This limitation is caused by a in-browser limit of outgoing connections - usually browsers don't allow opening more than two outgoing connections to a single domain. Single SockJS session requires those two connections - one for downloading data, other for sending messages. Opening second SockJS session at the same time would most probably block and can result in both sessions timing out.
Opening more than one SockJS connection at a time is generally a bad practice. If you absolutely must do it, you can use mutliple subdomains, using different subdomain for every SockJS connection.
Browser | Websockets | Streaming | Polling |
---|---|---|---|
IE 6, 7 | no | no | jsonp-polling |
IE 8, 9 (cookies=no) | no | xdr-streaming † | xdr-polling † |
IE 8, 9 (cookies=yes) | no | iframe-htmlfile | iframe-xhr-polling |
Chrome 6-12 | hixie-76 | xhr-streaming | xhr-polling |
Chrome 14+ | hybi-10 | xhr-streaming | xhr-polling |
Firefox <10 | no ‡ | xhr-streaming | xhr-polling |
Firefox 10+ | hybi-10 | xhr-streaming | xhr-polling |
Safari 5 | hixie-76 | xhr-streaming | xhr-polling |
Opera 10.70+ | no ‡ | iframe-eventsource | iframe-xhr-polling |
Konqueror | no | no | jsonp-polling |
-
†: IE 8+ supports [XDomainRequest]1, which is esentially a modified AJAX/XHR that can do requests across domains. But unfortunately it doesn't send any cookies, which makes it inaproppriate for deployments when the load balancer uses JSESSIONID cookie to do sticky sessions.
-
‡: Firefox 4.0 and Opera 11.00 and shipped with disabled Websockets "hixie-76". They can still be enabled by manually changing a browser setting.
Transport | References |
---|---|
websocket (hixie-76) | [draft-hixie-thewebsocketprotocol-76]2 |
websocket (hybi-10) | [draft-ietf-hybi-thewebsocketprotocol-10]3 |
xhr-streaming | Transport using [Cross domain XHR]4 [streaming]5 capability (readyState=3). |
xdr-streaming | Transport using [XDomainRequest]1 [streaming]5 capability (readyState=3). |
iframe-eventsource | [EventSource]6 used from an [iframe via postMessage]7. |
iframe-htmlfile | [HtmlFile]8 used from an [iframe via postMessage]7. |
xhr-polling | Long-polling using [cross domain XHR]4. |
xdr-polling | Long-polling using [XDomainRequest]1. |
iframe-xhr-polling | Long-polling using normal AJAX from an [iframe via postMessage]7. |
jsonp-polling | Slow and old fashioned [JSONP polling]9. This transport will show "busy indicator" (aka: "spinning wheel") when sending data. |
In order to utilize best performance you should use the SockJS-client releases hosted on SockJS CDN. You should use a version of sockjs-client that supports the protocol used by your server. For example:
<script src="http://cdn.sockjs.org/sockjs-0.2.min.js">
</script>
A list of files hosted on a CDN is available here: http://sockjs.github.com/sockjs-client/ .
You can also use or CDN via https (using Cloud Front domain name):
<script src="https://d1fxtkz8shb9d2.cloudfront.net/sockjs-0.2.js">
</script>
For server-side deployment tricks, especially about load balancing and session stickiness, take a look at the SockJS-node readme.
SockJS-client needs Node.js for running a test server and JavaScript minification. If you want to work on SockJS-client source code, check out the git repo and follow this steps:
cd sockjs-client
npm install --dev
To generate JavaScript run:
make sockjs.js
To generate minified JavaScript run:
make sockjs.min.js
(To generate both run make build
.)
Once you compiled SockJS-client you may want to check if your changes
pass all the tests. To run the tests you need a server that can answer
various SockJS requests. A common way is to use SockJS-node
test
server for that. To run it (by default it will be listening on port 8081):
cd sockjs-node
npm install --dev
make build
make test_server
At this point you're ready to run a SockJS-client server that will server your freshly compiled JavaScript and various static http and javscript files (by default it will run on port 8080).
cd sockjs-client
make test
At that point you should have two web servers running: sockjs-node on 8081 and sockjs-client on 8080. When you open the browser on http://localhost:8080/ you should be able run the QUnit tests against your sockjs-node server.
If you look at your browser console you will see warnings like that:
Incompatibile SockJS! Main site uses: "a", the iframe: "b".
This is due to a fact that SockJS-node test server is using compiled
javascript from CDN, rather than your freshly compiled version. To fix
that you must amend sockjs_url
that is used by SockJS-node test
server. Edit the config.js
file:
vim sockjs-node/examples/test_server/config.js
And replace sockjs_url
setting which by default points to CDN:
sockjs_url: 'http://cdn.sockjs.org/sockjs-0.2.min.js',
to a freshly compiled sockjs, for example:
sockjs_url: 'http://localhost:8080/lib/sockjs.js',
Also, if you want to run tests agains SockJS server not running on
localhost:8081
you may want to edit the
tests/config.js
file.
Additionally, if you're doing more serious development consider using
make serve
, which will automatically reload the server when you
modify the source code.
There are various browser quirks which we don't intend to address:
- Pressing ESC in Firefox closes SockJS connection (described in socket.io thread).
- Jsonp-polling transport will show a "spinning wheel" (aka. "busy indicator") when sending data.
- In most of the browsers you can't open more than one SockJS connection to one domain at the same time (with the exception of native websockets).
- Although SockJS is trying to escape any strange Unicode characters (even invalid ones, like surrogates, it's advisable to use only valid characters. Using invalid characters is a bit slower, and may not work with SockJS servers that have a proper Unicode support.
- Having a global function called
onmessage
or such is probably a bad idea, as it could be called by the built-inpostMessage
API.
Footnotes
-
http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx ↩ ↩2 ↩3
-
http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76 ↩
-
http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 ↩
-
https://secure.wikimedia.org/wikipedia/en/wiki/XMLHttpRequest#Cross-domain_requests ↩ ↩2
-
https://developer.mozilla.org/en/DOM/window.postMessage ↩ ↩2 ↩3
-
http://cometdaily.com/2007/11/18/ie-activexhtmlfile-transport-part-ii/ ↩