SockJS-node is a Node.js server side counterpart of SockJS-client browser library written in CoffeeScript.
npm install sockjs
(If you see
rbytes dependecy failing, don't worry, it's optional, SockJS-node will work fine without it.)
An simplified echo SockJS server could look more or less like:
var http = ;var sockjs = ;var echo = sockjs;echo;var server = http;echo;server;
(Take look at examples directory for a complete version.)
Subscribe to SockJS mailing list for discussions and support.
SockJS-client comes with some QUnit tests and a few smoke tests that are using SockJS-node. At the moment they are deployed in few places, just click to see if SockJS is working in your browser:
SockJS module is generating a
Server class, similar to
var sockjs_server = sockjs;
options is a hash which can contain:
Once you have create
Server instance you can hook it to the
var http_server = http;sockjs_server;http_server;
options can overshadow options given when creating
Server instance is an
and emits following event:
All http requests that don't go under the path selected by
will remain unanswered and will be passed to previously registered
handlers. You must install your custom http handlers before calling
Connection instance supports
Node Stream API and
has following methods and properties:
Connection instance emits the following events:
A fully working echo server does need a bit more boilerplate (to
handle requests unanswered by SockJS), see the
for a complete code.
If you want to see samples of running code, take a look at:
Although the main point of SockJS it to enable browser-to-server connectivity, it is possible to connect to SockJS from an external application. Any SockJS server complying with 0.3 protocol does support a raw WebSocket url. The raw WebSocket url for the test server looks like:
You can connect any WebSocket RFC 6455 compliant WebSocket client to this url. This can be a command line client, external application, third party code or even a browser (though I don't know why you would want to do so).
There are two issues that needs to be considered when planning a non-trivial SockJS-node deployment: WebSocket-compatible load balancer and sticky sessions (aka session affinity).
Often WebSockets don't play nicely with proxies and load balancers. Deploying a SockJS server behind Nginx or Apache could be painful.
Fortunetely recent versions of an excellent load balancer HAProxy are able to proxy WebSocket connections. We propose to put HAProxy as a front line load balancer and use it to split SockJS traffic from normal HTTP data. Take a look at the sample SockJS HAProxy configuration.
The config also shows how to use HAproxy balancing to split traffic between multiple Node.js servers. You can also do balancing using dns names.
If you plan depling more than one SockJS server, you must make sure that all HTTP requests for a single session will hit the same server. SockJS has two mechanisms that can be usefull to achieve that:
/resource/<server_number>/<session_id>/transport. This is usefull for load balancers that support prefix-based affinity (HAProxy does).
JSESSIONIDcookie is being set by SockJS-node. Many load balancers turn on sticky sessions if that cookie is set. This technique is derived from Java applications, where sticky sessions are often neccesary. HAProxy does support this method, as well as some hosting providers, for example CloudFoundry. In order to enable this method on the client side, please supply a
cookie:trueoption to SockJS constructor.
If you want to work on SockJS-node source code, you need to clone the git repo and follow these steps. First you need to install dependencies:
cd sockjs-node npm install --dev ln -s .. node_modules/sockjs
You're ready to compile CoffeeScript:
If compilation succeeds you may want to test if your changes pass all the tests. Currently, there are two separate test suites. For both of them you need to start a SockJS-node test server (by default listening on port 8081):
To run it run something like:
cd sockjs-protocol make test_deps ./venv/bin/python sockjs-protocol-0.3.py
For details see SockJS-protocol README.
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.
For details see SockJS-client README.
Additionally, if you're doing more serious development consider using
make serve, which will automatically the server when you modify the
SockJS-node does not expose cookies to the application. This is done deliberately as using cookie-based authorization with SockJS simply doesn't make sense and will lead to security issues.
Cookies are a contract between a browser and an http server, and are identified by a domain name. If a browser has a cookie set for particular domain, it will pass it as a part of all http requests to the host. But to get various transports working, SockJS uses a middleman
Basically - cookies are not suited for SockJS model. If you want to authorize a session - provide a unique token on a page, send it as a first thing over SockJS connection and validate it on the server side. In essence, this is how cookies work.
Long polling is known to cause problems on Heroku, but workaround for SockJS is available.