\href{http://badge.fury.io/js/sockjs}{\texttt{ }}

Sock\+JS family\+:


\begin{DoxyItemize}
\item \href{https://github.com/sockjs/sockjs-client}{\texttt{ Sock\+JS-\/client}} Java\+Script client library
\item \href{https://github.com/sockjs/sockjs-node}{\texttt{ Sock\+JS-\/node}} Node.\+js server
\item \href{https://github.com/sockjs/sockjs-erlang}{\texttt{ Sock\+JS-\/erlang}} Erlang server
\item \href{https://github.com/MrJoes/sockjs-tornado}{\texttt{ Sock\+JS-\/tornado}} Python/\+Tornado server
\item \href{https://github.com/eclipse/vert.x}{\texttt{ vert.\+x}} Java/vert.\+x server
\end{DoxyItemize}

Work in progress\+:


\begin{DoxyItemize}
\item \href{https://github.com/nyarly/sockjs-ruby}{\texttt{ Sock\+JS-\/ruby}}
\item \href{https://github.com/cgbystrom/sockjs-netty}{\texttt{ Sock\+JS-\/netty}}
\item \href{https://github.com/sdiehl/sockjs-gevent}{\texttt{ Sock\+JS-\/gevent}} (\href{https://github.com/njoyce/sockjs-gevent}{\texttt{ and a fork}})
\item \href{https://github.com/fafhrd91/pyramid_sockjs}{\texttt{ pyramid-\/\+Sock\+JS}}
\item \href{https://github.com/wildcloud/wildcloud-websockets}{\texttt{ wildcloud-\/websockets}}
\item \href{https://github.com/flaviogrossi/sockjs-cyclone}{\texttt{ Sock\+JS-\/cyclone}}
\item \href{https://github.com/Fugiman/sockjs-twisted/}{\texttt{ Sock\+JS-\/twisted}}
\item \href{https://github.com/Palmik/wai-sockjs}{\texttt{ wai-\/\+Sock\+JS}}
\item \href{https://github.com/vti/sockjs-perl}{\texttt{ Sock\+JS-\/perl}}
\item \href{https://github.com/igm/sockjs-go/}{\texttt{ Sock\+JS-\/go}}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27931}{}\doxysection{What is Sock\+JS?}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27931}
Sock\+JS is a Java\+Script library (for browsers) that provides a Web\+Socket-\/like object. Sock\+JS 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, with Web\+Sockets or without. This necessitates the use of a server, which this is one version of, for Node.\+js.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27932}{}\doxysection{Sock\+JS-\/node server}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27932}
Sock\+JS-\/node is a Node.\+js server side counterpart of \href{https://github.com/sockjs/sockjs-client}{\texttt{ Sock\+JS-\/client browser library}} written in Coffee\+Script.

To install {\ttfamily sockjs-\/node} run\+: \begin{DoxyVerb}npm install sockjs
\end{DoxyVerb}
 A simplified echo Sock\+JS server could look more or less like\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var http = require('http');}
\DoxyCodeLine{var sockjs = require('sockjs');}
\DoxyCodeLine{}
\DoxyCodeLine{var echo = sockjs.createServer();}
\DoxyCodeLine{echo.on('connection', function(conn) \{}
\DoxyCodeLine{    conn.on('data', function(message) \{}
\DoxyCodeLine{        conn.write(message);}
\DoxyCodeLine{    \});}
\DoxyCodeLine{    conn.on('close', function() \{\});}
\DoxyCodeLine{\});}
\DoxyCodeLine{}
\DoxyCodeLine{var server = http.createServer();}
\DoxyCodeLine{echo.installHandlers(server, \{prefix:'/echo'\});}
\DoxyCodeLine{server.listen(9999, '0.0.0.0'); }

\end{DoxyCode}


(Take look at \href{https://github.com/sockjs/sockjs-node/tree/master/examples/echo}{\texttt{ examples}} directory for a complete version.)

Subscribe to \href{https://groups.google.com/forum/\#!forum/sockjs}{\texttt{ Sock\+JS mailing list}} for discussions and support.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27933}{}\doxysubsection{Sock\+JS-\/node API}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27933}
The API design is based on common Node APIs like the \href{http://nodejs.org/docs/v0.5.8/api/streams.html}{\texttt{ Streams API}} or the \href{http://nodejs.org/docs/v0.5.8/api/http.html\#http.Server}{\texttt{ Http.\+Server API}}.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27934}{}\doxysubsubsection{Server class}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27934}
Sock\+JS module is generating a {\ttfamily Server} class, similar to \href{http://nodejs.org/docs/v0.5.8/api/http.html\#http.createServer}{\texttt{ Node.\+js http.\+create\+Server}} module.


\begin{DoxyCode}{0}
\DoxyCodeLine{var sockjs\_server = sockjs.createServer(options); }

\end{DoxyCode}


Where {\ttfamily options} is a hash which can contain\+:


\begin{DoxyDescription}
\item[sockjs\+\_\+url (string) ]Transports which don\textquotesingle{}t support cross-\/domain communication natively (\textquotesingle{}eventsource\textquotesingle{} to name one) use an iframe trick. A simple page is served from the Sock\+JS server (using its foreign domain) and is placed in an invisible iframe. Code run from this iframe doesn\textquotesingle{}t need to worry about cross-\/domain issues, as it\textquotesingle{}s being run from domain local to the Sock\+JS server. This iframe also does need to load Sock\+JS javascript client library, and this option lets you specify its url (if you\textquotesingle{}re unsure, point it to \href{https://cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js}{\texttt{ the latest minified Sock\+JS client release}}, this is the default). You must explicitly specify this url on the server side for security reasons -\/ we don\textquotesingle{}t want the possibility of running any foreign javascript within the Sock\+JS domain (aka cross site scripting attack). Also, sockjs javascript library is probably already cached by the browser -\/ it makes sense to reuse the sockjs url you\textquotesingle{}re using in normally.


\item[prefix (string regex) ]A url prefix for the server. All http requests which paths begins with selected prefix will be handled by Sock\+JS. All other requests will be passed through, to previously registered handlers.


\item[response\+\_\+limit (integer) ]Most streaming transports save responses on the client side and don\textquotesingle{}t free memory used by delivered messages. Such transports need to be garbage-\/collected once in a while. {\ttfamily response\+\_\+limit} sets a minimum number of bytes that can be send over a single http streaming request before it will be closed. After that client needs to open new request. Setting this value to one effectively disables streaming and will make streaming transports to behave like polling transports. The default value is 128K.


\item[websocket (boolean) ]Some load balancers don\textquotesingle{}t support websockets. This option can be used to disable websockets support by the server. By default websockets are enabled.


\item[jsessionid (boolean or function) ]Some hosting providers enable sticky sessions only to requests that have JSESSIONID cookie set. This setting controls if the server should set this cookie to a dummy value. By default setting JSESSIONID cookie is disabled. More sophisticated behaviour can be achieved by supplying a function.


\item[log (function(severity, message)) ]It\textquotesingle{}s quite useful, especially for debugging, to see some messages printed by a Sock\+JS-\/node library. This is done using this {\ttfamily log} function, which is by default set to {\ttfamily console.\+log}. If this behaviour annoys you for some reason, override {\ttfamily log} setting with a custom handler. The following {\ttfamily severities} are used\+: {\ttfamily debug} (miscellaneous logs), {\ttfamily info} (requests logs), {\ttfamily error} (serious errors, consider filing an issue).


\item[heartbeat\+\_\+delay (milliseconds) ]In order to keep proxies and load balancers from closing long running http requests we need to pretend that the connection is active and send a heartbeat packet once in a while. This setting controls how often this is done. By default a heartbeat packet is sent every 25 seconds. 


\item[disconnect\+\_\+delay (milliseconds) ]The server sends a {\ttfamily close} event when a client receiving connection have not been seen for a while. This delay is configured by this setting. By default the {\ttfamily close} event will be emitted when a receiving connection wasn\textquotesingle{}t seen for 5 seconds. 


\item[disable\+\_\+cors (boolean) ]Enabling this option will prevent \href{https://en.wikipedia.org/wiki/Cross-origin_resource_sharing}{\texttt{ CORS}} headers from being included in the HTTP response. Can be used when the sockjs client is known to be connecting from the same origin as the sockjs server. 
\end{DoxyDescription}\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27935}{}\doxysubsubsection{Server instance}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27935}
Once you have create {\ttfamily Server} instance you can hook it to the \href{http://nodejs.org/docs/v0.5.8/api/http.html\#http.createServer}{\texttt{ http.\+Server instance}}.


\begin{DoxyCode}{0}
\DoxyCodeLine{var http\_server = http.createServer();}
\DoxyCodeLine{sockjs\_server.installHandlers(http\_server, options);}
\DoxyCodeLine{http\_server.listen(...); }

\end{DoxyCode}


Where {\ttfamily options} can overshadow options given when creating {\ttfamily Server} instance.

{\ttfamily Server} instance is an \href{http://nodejs.org/docs/v0.4.10/api/events.html\#events.EventEmitter}{\texttt{ Event\+Emitter}}, and emits following event\+:


\begin{DoxyDescription}
\item[Event\+: connection (connection) ]A new connection has been successfully opened. 
\end{DoxyDescription}

All http requests that don\textquotesingle{}t go under the path selected by {\ttfamily prefix} will remain unanswered and will be passed to previously registered handlers. You must install your custom http handlers before calling {\ttfamily install\+Handlers}.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27936}{}\doxysubsubsection{Connection instance}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27936}
A {\ttfamily Connection} instance supports \href{http://nodejs.org/docs/v0.5.8/api/streams.html}{\texttt{ Node Stream API}} and has following methods and properties\+:


\begin{DoxyDescription}
\item[Property\+: readable (boolean) ]Is the stream readable?


\item[Property\+: writable (boolean) ]Is the stream writable?


\item[Property\+: remote\+Address (string) ]Last known IP address of the client.


\item[Property\+: remote\+Port (number) ]Last known port number of the client.


\item[Property\+: address (object) ]Hash with \textquotesingle{}address\textquotesingle{} and \textquotesingle{}port\textquotesingle{} fields.


\item[Property\+: headers (object) ]Hash containing various headers copied from last receiving request on that connection. Exposed headers include\+: {\ttfamily origin}, {\ttfamily referer} and {\ttfamily x-\/forwarded-\/for} (and friends). We explicitly do not grant access to {\ttfamily cookie} header, as using it may easily lead to security issues (for details read the section \char`\"{}\+Authorisation\char`\"{}).


\item[Property\+: url (string) ]\href{http://nodejs.org/docs/v0.4.10/api/http.html\#request.url}{\texttt{ Url}} property copied from last request.


\item[Property\+: pathname (string) ]{\ttfamily pathname} from parsed url, for convenience.


\item[Property\+: prefix (string) ]Prefix of the url on which the request was handled.


\item[Property\+: protocol (string) ]Protocol used by the connection. Keep in mind that some protocols are indistinguishable -\/ for example \char`\"{}xhr-\/polling\char`\"{} and \char`\"{}xdr-\/polling\char`\"{}.


\item[Property\+: ready\+State (integer) ]Current state of the connection\+: 0-\/connecting, 1-\/open, 2-\/closing, 3-\/closed.


\item[write(message) ]Sends a message over opened connection. A message must be a non-\/empty string. It\textquotesingle{}s illegal to send a message after the connection was closed (either after \textquotesingle{}close\textquotesingle{} or \textquotesingle{}end\textquotesingle{} method or \textquotesingle{}close\textquotesingle{} event).


\item[close(\mbox{[}code\mbox{]}, \mbox{[}reason\mbox{]}) ]Asks the remote client to disconnect. \textquotesingle{}code\textquotesingle{} and \textquotesingle{}reason\textquotesingle{} parameters are optional and can be used to share the reason of disconnection.


\item[end() ]Asks the remote client to disconnect with default \textquotesingle{}code\textquotesingle{} and \textquotesingle{}reason\textquotesingle{} values.


\end{DoxyDescription}

A {\ttfamily Connection} instance emits the following events\+:


\begin{DoxyDescription}
\item[Event\+: data (message) ]A message arrived on the connection. Message is a unicode string.


\item[Event\+: close () ]Connection was closed. This event is triggered exactly once for every connection. 
\end{DoxyDescription}

For example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{sockjs\_server.on('connection', function(conn) \{}
\DoxyCodeLine{    console.log('connection' + conn);}
\DoxyCodeLine{    conn.on('close', function() \{}
\DoxyCodeLine{        console.log('close ' + conn);}
\DoxyCodeLine{    \});}
\DoxyCodeLine{    conn.on('data', function(message) \{}
\DoxyCodeLine{        console.log('message ' + conn,}
\DoxyCodeLine{                    message);}
\DoxyCodeLine{    \});}
\DoxyCodeLine{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27937}{}\doxysubsubsection{Footnote}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27937}
A fully working echo server does need a bit more boilerplate (to handle requests unanswered by Sock\+JS), see the \href{https://github.com/sockjs/sockjs-node/tree/master/examples/echo}{\texttt{ {\ttfamily echo} example}} for a complete code.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27938}{}\doxysubsubsection{Examples}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27938}
If you want to see samples of running code, take a look at\+:


\begin{DoxyItemize}
\item \href{https://github.com/sockjs/sockjs-node/tree/master/examples/echo}{\texttt{ ./examples/echo}} directory, which contains a full example of a echo server.
\item \href{https://github.com/sockjs/sockjs-node/tree/master/examples/test_server}{\texttt{ ./examples/test\+\_\+server}} a standard Sock\+JS test server.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27939}{}\doxysubsection{Connecting to Sock\+JS-\/node without the client}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27939}
Although the main point of Sock\+JS it to enable browser-\/to-\/server connectivity, it is possible to connect to Sock\+JS from an external application. Any Sock\+JS server complying with 0.\+3 protocol does support a raw Web\+Socket url. The raw Web\+Socket url for the test server looks like\+:


\begin{DoxyItemize}
\item ws\+://localhost\+:8081/echo/websocket
\end{DoxyItemize}

You can connect any Web\+Socket RFC 6455 compliant Web\+Socket client to this url. This can be a command line client, external application, third party code or even a browser (though I don\textquotesingle{}t know why you would want to do so).

Note\+: This endpoint will {\itshape not send any heartbeat packets}.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27940}{}\doxysubsection{Deployment and load balancing}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27940}
There are two issues that need to be considered when planning a non-\/trivial Sock\+JS-\/node deployment\+: Web\+Socket-\/compatible load balancer and sticky sessions (aka session affinity).\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27941}{}\doxysubsubsection{Web\+Socket compatible load balancer}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27941}
Often Web\+Sockets don\textquotesingle{}t play nicely with proxies and load balancers. Deploying a Sock\+JS server behind Nginx or Apache could be painful.

Fortunately recent versions of an excellent load balancer \href{http://haproxy.1wt.eu/}{\texttt{ HAProxy}} are able to proxy Web\+Socket connections. We propose to put HAProxy as a front line load balancer and use it to split Sock\+JS traffic from normal HTTP data. Take a look at the sample \href{https://github.com/sockjs/sockjs-node/blob/master/examples/haproxy.cfg}{\texttt{ Sock\+JS 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.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27942}{}\doxysubsubsection{Sticky sessions}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27942}
If you plan deploying more than one Sock\+JS server, you must make sure that all HTTP requests for a single session will hit the same server. Sock\+JS has two mechanisms that can be useful to achieve that\+:


\begin{DoxyItemize}
\item Urls are prefixed with server and session id numbers, like\+: {\ttfamily /resource/$<$server\+\_\+number$>$/$<$session\+\_\+id$>$/transport}. This is useful for load balancers that support prefix-\/based affinity (HAProxy does).
\item {\ttfamily JSESSIONID} cookie is being set by Sock\+JS-\/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 necessary. HAProxy does support this method, as well as some hosting providers, for example Cloud\+Foundry. In order to enable this method on the client side, please supply a {\ttfamily cookie\+:true} option to Sock\+JS constructor.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27943}{}\doxysubsection{Development and testing}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27943}
If you want to work on Sock\+JS-\/node source code, you need to clone the git repo and follow these steps. First you need to install dependencies\+: \begin{DoxyVerb}cd sockjs-node
npm install
npm install --dev
ln -s .. node_modules/sockjs
\end{DoxyVerb}
 You\textquotesingle{}re ready to compile Coffee\+Script\+: \begin{DoxyVerb}make build
\end{DoxyVerb}
 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 Sock\+JS-\/node test server (by default listening on port 8081)\+: \begin{DoxyVerb}make test_server
\end{DoxyVerb}
 \hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27944}{}\doxysubsubsection{Sock\+JS-\/protocol Python tests}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27944}
To run it run something like\+: \begin{DoxyVerb}cd sockjs-protocol
make test_deps
./venv/bin/python sockjs-protocol.py
\end{DoxyVerb}
 For details see \href{https://github.com/sockjs/sockjs-protocol\#readme}{\texttt{ Sock\+JS-\/protocol README}}.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27945}{}\doxysubsubsection{Sock\+JS-\/client QUnit tests}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27945}
You need to start a second web server (by default listening on 8080) that is serving various static html and javascript files\+: \begin{DoxyVerb}cd sockjs-client
make test
\end{DoxyVerb}
 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 \href{http://localhost:8080/}{\texttt{ http\+://localhost\+:8080/}} you should be able run the QUnit tests against your sockjs-\/node server.

For details see \href{https://github.com/sockjs/sockjs-client\#readme}{\texttt{ Sock\+JS-\/client README}}.

Additionally, if you\textquotesingle{}re doing more serious development consider using {\ttfamily make serve}, which will automatically the server when you modify the source code.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27946}{}\doxysubsection{Various issues and design considerations}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27946}
\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27947}{}\doxysubsubsection{Authorisation}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27947}
Sock\+JS-\/node does not expose cookies to the application. This is done deliberately as using cookie-\/based authorisation with Sock\+JS simply doesn\textquotesingle{}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, Sock\+JS uses a middleman
\begin{DoxyItemize}
\item an iframe hosted from target Sock\+JS domain. That means the server will receive requests from the iframe, and not from the real domain. The domain of an iframe is the same as the Sock\+JS domain. The problem is that any website can embed the iframe and communicate with it -\/ and request establishing Sock\+JS connection. Using cookies for authorisation in this scenario will result in granting full access to Sock\+JS communication with your website from any website. This is a classic CSRF attack.
\end{DoxyItemize}

Basically -\/ cookies are not suited for Sock\+JS model. If you want to authorise a session -\/ provide a unique token on a page, send it as a first thing over Sock\+JS connection and validate it on the server side. In essence, this is how cookies work.\hypertarget{md_sfcode_node_modules_sockjs_README_autotoc_md27948}{}\doxysubsubsection{Deploying Sock\+JS on Heroku}\label{md_sfcode_node_modules_sockjs_README_autotoc_md27948}
Long polling is known to cause problems on Heroku, but \href{https://github.com/sockjs/sockjs-node/issues/57\#issuecomment-5242187}{\texttt{ workaround for Sock\+JS is available}}. 