Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
WebSocket emulation - Javascript client

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
tests
.gitignore
COPYING
Changelog
LICENSE-MIT-SockJS
Makefile
README.md
VERSION-GEN
package.json
version

README.md

SockJS

SockJS is a JavaScript library that creates a WebSockets-like object, which allows low latency full duplex communication between browsers and your web servers.

SockJS tries to use WebSockets, but it can use different transports for browsers that don't support HTML5 or are running behind a restrictive proxy.

Philosophy:

  • All the transports support cross domain connections out of the box. It's possible and recommended to host SockJS server on different domain 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.
  • 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)
  • Connection establishment should be fast and lightweight.
  • The API should follow HTML5 Websockets API as closely as possible (but we're not there yet).

Subscribe to SockJS mailing list for discussions and support.

Live QUnit tests and smoke tests

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:

Example

SockJS mimics WebSockets API, instead of WebSocket there is 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 sockjs = new SockJS('http://mydomain.com/my_prefix');
  sockjs.onopen = function() {
      console.log('open', e.data);
  };
  sockjs.onmessage = function(e) {
      console.log('message', e.data);
  };
  sockjs.onclose = function(e) {
      console.log('close', e.data);
  };
</script>

SockJS-client API

SockJS class

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.

Supported transports (#1)

Protocol Browser
WebSocket hixie-76 Chrome 6-12, Safari 5, Firefox 4 (disabled), Opera 11 (disabled)
WebSocket hybi-10 Chrome 14+, Firefox 6+
IFrame via postMessage + EventSource Opera 10.70+, Firefox 3.5+
XDR (CORS) streaming IE 8 (no cookies), Firefox 3.5+, Safari 4+, Chrome 3+
IFrame via postMessage + HtmlFile IE 8 (with cookies)
XDR (CORS) polling IE 8, Firefox 3.5+, Safari 4+, Chrome 3+ (through misbehaving proxy)
IFrame via postMessage + XHR polling Opera 9+
JsonP polling (rough and slow fallback)

Supported transports (#2)

Transport Target browsers Good loadbalancer required Behaving proxy required
WebSocket Chrome, Safari, Firefox 6+ yes yes
IFrame + EventSource Opera 10.70+ no yes
IFrame + HtmlFile IE 8 (cookies=yes) no yes
XHR streaming (CORS) IE 8 (cookies=no), Firefox <6 no yes
XHR polling (CORS) Chrome, Safari, Firefox, IE 8 no no
IFrame + XHR polling Opera no no
JsonP polling any no no

Deployment

There should be a proper CDN to host generated javascript for SockJS, 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.

Development

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:

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.)

Testing

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:8000/ . It serves static QUnit files and serves a simple SockJS.

To run QUnit tests simply point your browser at http://127.0.0.1:8000/.

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.

Something went wrong with that request. Please try again.