SockJS family:
- SockJS-client JavaScript client library
- SockJS-node Node.js server
- SockJS-protocol protocol documentation
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.
- 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://majek.github.com/sockjs-client/sockjs-latest.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. {
console.log('open');
};
sock. {
console.log('message', e.data);
};
sock. {
console.log('close');
};
</script>Similar to 'WebSocket' class 'SockJS' constructor takes one, or more arguments:
var sockjs = new SockJS(url, protocols, options);Where options is a hash which can contain:
- debug (boolean)
- Print more debugging messages using 'console.log'.
- devel (boolean)
- Development mode. Currently settint it affects only caching of 'iframe.html'.
- cookie (boolean)
- Disables transports which doesn't support cookies (ie: XDR on IE). Usefull for load balancing based on sticky sessions provided by JSESSIONID cookie.
| Protocol | Browser |
|---|---|
| [WebSocket hixie-76]1 | Chrome 6-12, Safari 5, Firefox 4 (disabled), Opera 11 (disabled) |
| [WebSocket hybi-10]2 | Chrome 14+, Firefox 6+ |
| [IFrame via postMessage]3 + [EventSource]4 | Opera 10.70+, Firefox 3.5+ |
| [XDR (CORS) streaming]5 | IE 8 (no cookies), Firefox 3.5+, Safari 4+, Chrome 3+ |
| [IFrame via postMessage]3 + [HtmlFile]6 | IE 8 (with cookies) |
| [XDR (CORS) polling]7 | IE 8, Firefox 3.5+, Safari 4+, Chrome 3+ (through misbehaving proxy) |
| [IFrame via postMessage]3 + XHR polling | Opera 9+ |
| [JsonP polling]8 | (rough and slow fallback) |
| Transport | Target browsers | Good loadbalancer required | Behaving proxy required |
|---|---|---|---|
| WebSocket | Chrome, Safari, Firefox 6+ | yes | yes |
| XHR streaming (CORS) | IE 8 (cookie=no), Firefox <6 | no | yes |
| IFrame + EventSource | Opera 10.70+ | no | yes |
| IFrame + HtmlFile | IE 8 (cookie=yes) | no | yes |
| XHR polling (CORS) | Chrome, Safari, Firefox, IE 8 | no | no |
| IFrame + XHR polling | Opera | no | no |
| JsonP polling | any | no | no |
There should be a proper CDN to host generated SockJS library, but there isn't one yet. In the meantime you can use releases hosted on Github: http://majek.github.com/sockjs-client/ .
For server-side deployment tricks, especially about load balancing and session stickiness, take a look at the SockJS-node readme.
SockJS-client uses Node.js for testing and Javascript minification. If you want to play with SockJS code, check out the git repo and follow this steps:
cd sockjs-client
npm install
(SockJS-client uses SockJS-node for testing, you may want to link 'node_modules/sockjs' to directory with cloned SockJS-node.)
To generate javascript run:
make sockjs.js
To generate minified javascript run:
make sockjs.min.js
(To generate both run make build.)
To run qunit tests, type:
make test
This command runs script 'tests/server.js' which starts a web server that listens on http://127.0.0.1:8080/ . It serves static QUnit files and serves a simple SockJS.
To run QUnit tests simply point your browser at http://127.0.0.1:8080/.
If you want the javascript to be recompiled when the source files are
modified and automatically restart the http server run make serve.
You will need 'inotifywait' command from package inotify-tools.
Footnotes
-
http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76 ↩
-
http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 ↩
-
https://developer.mozilla.org/en/DOM/window.postMessage ↩ ↩2 ↩3
-
http://cometdaily.com/2007/11/18/ie-activexhtmlfile-transport-part-ii/ ↩
-
https://secure.wikimedia.org/wikipedia/en/wiki/XMLHttpRequest#Cross-domain_requests ↩