8000 GitHub - sockjs/sockjs-node at b6e9d5fe620824d1f033dc5efe38311ea880df77
[go: up one dir, main page]

Skip to content

sockjs/sockjs-node

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SockJS-node

npm versionDependencies

Supporting SockJS

Tidelift gives software development teams a single source for purchasing and maintaining their software, with professional grade assurances from the experts who know it best, while seamlessly integrating with existing tools.

Get supported sockjs with the Tidelift Subscription

SockJS family

Work in progress:

⚠️️ ATTENTION This is pre-release documentation. The documentation for the latest stable release is at: https://github.com/sockjs/sockjs-node/tree/v0.3.19 ️⚠️

What is SockJS?

SockJS is a JavaScript library (for browsers) 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, with WebSockets or without. This necessitates the use of a server, which this is one version of, for Node.js.

SockJS-node server

SockJS-node is a Node.js server side counterpart of SockJS-client browser library.

To install sockjs-node run:

npm install sockjs

A simplified echo SockJS server could look more or less like:

const http = require('http');
const sockjs = require('sockjs');

const echo = sockjs.createServer({ prefix:'/echo' });
echo.on('connection', function(conn) {
  conn.on('data', function(message) {
    conn.write(message);
  });
  conn.on('close', function() {});
});

const server = http.createServer();
echo.attach(server);
server.listen(9999, '0.0.0.0');

(Take look at examples directory for a complete version.)

Subscribe to SockJS mailing list for discussions and support.

SockJS-node API

The API design is based on common Node APIs like the Streams API or the Http.Server API.

Server class

SockJS module is generating a Server class, similar to Node.js http.createServer module.

const sockjs_server = sockjs.createServer(options);

Where options is a hash which can contain:

sockjs_url (string, required)
Transports which don't support cross-domain communication natively ('eventsource' to name one) use an iframe trick. A simple page is served from the SockJS server (using its foreign domain) and is placed in an invisible iframe. Code run from this iframe doesn't need to worry about cross-domain issues, as it's being run from domain local to the SockJS server. This iframe also does need to load SockJS javascript client library, and this option lets you specify its url (if you're unsure, point it to the latest minified SockJS client release, this is the default). You must explicitly specify this url on the server side for security reasons - we don't want the possibility of running any foreign javascript within the SockJS 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're using in normally.
prefix (string regex)
A url prefix for the server. All http requests which paths begins with selected prefix will be handled by SockJS. All other requests will be passed through, to previously registered handlers.
response_limit (integer)
Most streaming transports save responses on the client side and don't free memory used by delivered messages. Such transports need to be garbage-collected once in a while. `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.
transports (Array of strings)
List of transports to enable. Select from `eventsource`, `htmlfile`, `jsonp-polling`, `websocket`, `websocket-raw`, `xhr-polling`, and `xhr-streaming`.
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.
log (function(severity, message))
It's quite useful, especially for debugging, to see some messages printed by a SockJS-node library. This is done using this `log` function, which is by default set to nothing. If this behaviour annoys you for some reason, override `log` setting with a custom handler. The following `severities` are used: `debug` (miscellaneous logs), `info` (requests logs), `error` (serious errors, consider filing an issue).
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.
disconnect_delay (milliseconds)
The server sends a `close` event when a client receiving connection have not been seen for a while. This delay is configured by this setting. By default the `close` event will be emitted when a receiving connection wasn't seen for 5 seconds.
disable_cors (boolean)
Enabling this option will prevent 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. This also disables the iframe HTML endpoint.

Server instance

Once you have create Server instance you can hook it to the http.Server instance.

var http_server = http.createServer();
sockjs_server.attach(http_server);
http_server.listen(...);

Server instance is an EventEmitter, and emits following event:

Event: connection (connection)
A new connection has been successfully opened.

All http requests that don't go under the path selected by prefix will remain unanswered and will be passed to previously registered handlers. You must install your custom http handlers before calling attach. You can remove the SockJS handler later with detach.

Connection instance