-
Notifications
You must be signed in to change notification settings - Fork 0
/
package.json
36 lines (36 loc) · 18 KB
/
package.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"name": "sockjs",
"author": {
"name": "Marek Majkowski"
},
"version": "0.3.8",
"description": "SockJS-node is a server counterpart of SockJS-client a JavaScript library that provides a WebSocket-like object in the browser. 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.",
"keywords": [
"websockets",
"websocket"
],
"homepage": "https://github.com/sockjs/sockjs-node",
"repository": {
"type": "git",
"url": "https://github.com/sockjs/sockjs-node.git"
},
"dependencies": {
"node-uuid": "1.3.3",
"faye-websocket": "0.7.0"
},
"devDependencies": {
"coffee-script": "1.2.x"
},
"main": "index",
"readme": "SockJS family:\n\n * [SockJS-client](https://github.com/sockjs/sockjs-client) JavaScript client library\n * [SockJS-node](https://github.com/sockjs/sockjs-node) Node.js server\n * [SockJS-erlang](https://github.com/sockjs/sockjs-erlang) Erlang server\n * [SockJS-tornado](https://github.com/MrJoes/sockjs-tornado) Python/Tornado server\n * [vert.x](https://github.com/purplefox/vert.x) Java/vert.x server\n\nWork in progress:\n\n * [SockJS-ruby](https://github.com/nyarly/sockjs-ruby)\n * [SockJS-netty](https://github.com/cgbystrom/sockjs-netty)\n * [SockJS-gevent](https://github.com/sdiehl/sockjs-gevent) ([and a fork](https://github.com/njoyce/sockjs-gevent))\n * [pyramid-SockJS](https://github.com/fafhrd91/pyramid_sockjs)\n * [wildcloud-websockets](https://github.com/wildcloud/wildcloud-websockets)\n * [SockJS-cyclone](https://github.com/flaviogrossi/sockjs-cyclone)\n * [SockJS-twisted](https://github.com/Fugiman/sockjs-twisted/)\n * [wai-SockJS](https://github.com/Palmik/wai-sockjs)\n * [SockJS-perl](https://github.com/vti/sockjs-perl)\n * [SockJS-go](https://github.com/igm/sockjs-go/)\n\nWhat is SockJS?\n===============\n\nSockJS is a JavaScript library (for browsers) that provides a WebSocket-like\nobject. SockJS gives you a coherent, cross-browser, Javascript API\nwhich creates a low latency, full duplex, cross-domain communication\nchannel between the browser and the web server, with WebSockets or without.\nThis necessitates the use of a server, which this is one version of, for Node.js.\n\n\nSockJS-node server\n==================\n\nSockJS-node is a Node.js server side counterpart of\n[SockJS-client browser library](https://github.com/sockjs/sockjs-client)\nwritten in CoffeeScript.\n\nTo install `sockjs-node` run:\n\n npm install sockjs\n\nFor additional security (true random numbers) you might want to\ninstall `rbytes` package - SockJS will use it if available:\n\n npm install rbytes\n\n\nA simplified echo SockJS server could look more or less like:\n\n```javascript\nvar http = require('http');\nvar sockjs = require('sockjs');\n\nvar echo = sockjs.createServer();\necho.on('connection', function(conn) {\n conn.on('data', function(message) {\n conn.write(message);\n });\n conn.on('close', function() {});\n});\n\nvar server = http.createServer();\necho.installHandlers(server, {prefix:'/echo'});\nserver.listen(9999, '0.0.0.0');\n```\n\n(Take look at\n[examples](https://github.com/sockjs/sockjs-node/tree/master/examples/echo)\ndirectory for a complete version.)\n\nSubscribe to\n[SockJS mailing list](https://groups.google.com/forum/#!forum/sockjs) for\ndiscussions and support.\n\n\nLive QUnit tests and smoke tests\n--------------------------------\n\n[SockJS-client](https://github.com/sockjs/sockjs-client) comes with\nsome QUnit tests and a few smoke tests that are using SockJS-node. At\nthe moment they are deployed in few places, just click to see if\nSockJS is working in your browser:\n\n * http://sockjs.popcnt.org/ and https://sockjs.popcnt.org/ (hosted in Europe)\n * http://sockjs.cloudfoundry.com/ (CloudFoundry, websockets disabled, loadbalanced)\n * https://sockjs.cloudfoundry.com/ (CloudFoundry SSL, websockets disabled, loadbalanced)\n\n\nSockJS-node API\n---------------\n\nThe API design is based on the common Node API's like\n[Streams API](http://nodejs.org/docs/v0.5.8/api/streams.html) or\n[Http.Server API](http://nodejs.org/docs/v0.5.8/api/http.html#http.Server).\n\n### Server class\n\nSockJS module is generating a `Server` class, similar to\n[Node.js http.createServer](http://nodejs.org/docs/v0.5.8/api/http.html#http.createServer)\nmodule.\n\n```javascript\nvar sockjs_server = sockjs.createServer(options);\n```\n\nWhere `options` is a hash which can contain:\n\n<dl>\n<dt>sockjs_url (string, required)</dt>\n<dd>Transports which don't support cross-domain communication natively\n ('eventsource' to name one) use an iframe trick. A simple page is\n served from the SockJS server (using its foreign domain) and is\n placed in an invisible iframe. Code run from this iframe doesn't\n need to worry about cross-domain issues, as it's being run from\n domain local to the SockJS server. This iframe also does need to\n load SockJS javascript client library, and this option lets you specify\n its url (if you're unsure, point it to\n <a href=\"http://cdn.sockjs.org/sockjs-0.3.min.js\">\n the latest minified SockJS client release</a>, this is the default).\n You must explicitly specify this url on the server side for security\n reasons - we don't want the possibility of running any foreign\n javascript within the SockJS domain (aka cross site scripting attack).\n Also, sockjs javascript library is probably already cached by the\n browser - it makes sense to reuse the sockjs url you're using in\n normally.</dd>\n\n<dt>prefix (string)</dt>\n<dd>A url prefix for the server. All http requests which paths begins\n with selected prefix will be handled by SockJS. All other requests\n will be passed through, to previously registered handlers.</dd>\n\n<dt>response_limit (integer)</dt>\n<dd>Most streaming transports save responses on the client side and\n don't free memory used by delivered messages. Such transports need\n to be garbage-collected once in a while. `response_limit` sets\n a minimum number of bytes that can be send over a single http streaming\n request before it will be closed. After that client needs to open\n new request. Setting this value to one effectively disables\n streaming and will make streaming transports to behave like polling\n transports. The default value is 128K.</dd>\n\n<dt>websocket (boolean)</dt>\n<dd>Some load balancers don't support websockets. This option can be used\n to disable websockets support by the server. By default websockets are\n enabled.</dd>\n\n<dt>jsessionid (boolean or function)</dt>\n<dd>Some hosting providers enable sticky sessions only to requests that\n have JSESSIONID cookie set. This setting controls if the server should\n set this cookie to a dummy value. By default setting JSESSIONID cookie\n is disabled. More sophisticated behaviour can be achieved by supplying\n a function.</dd>\n\n<dt>log (function(severity, message))</dt>\n<dd>It's quite useful, especially for debugging, to see some messages\n printed by a SockJS-node library. This is done using this `log`\n function, which is by default set to `console.log`. If this\n behaviour annoys you for some reason, override `log` setting with a\n custom handler. The following `severities` are used: `debug`\n (miscellaneous logs), `info` (requests logs), `error` (serious\n errors, consider filing an issue).</dd>\n\n<dt>heartbeat_delay (milliseconds)</dt>\n<dd>In order to keep proxies and load balancers from closing long\n running http requests we need to pretend that the connection is\n active and send a heartbeat packet once in a while. This setting\n controls how often this is done. By default a heartbeat packet is\n sent every 25 seconds. </dd>\n\n<dt>disconnect_delay (milliseconds)</dt>\n<dd>The server sends a `close` event when a client receiving\n connection have not been seen for a while. This delay is configured\n by this setting. By default the `close` event will be emitted when a\n receiving connection wasn't seen for 5 seconds. </dd>\n</dl>\n\n\n### Server instance\n\nOnce you have create `Server` instance you can hook it to the\n[http.Server instance](http://nodejs.org/docs/v0.5.8/api/http.html#http.createServer).\n\n```javascript\nvar http_server = http.createServer();\nsockjs_server.installHandlers(http_server, options);\nhttp_server.listen(...);\n```\n\nWhere `options` can overshadow options given when creating `Server`\ninstance.\n\n`Server` instance is an\n[EventEmitter](http://nodejs.org/docs/v0.4.10/api/events.html#events.EventEmitter),\nand emits following event:\n\n<dl>\n<dt>Event: connection (connection)</dt>\n<dd>A new connection has been successfully opened.</dd>\n</dl>\n\nAll http requests that don't go under the path selected by `prefix`\nwill remain unanswered and will be passed to previously registered\nhandlers. You must install your custom http handlers before calling\n`installHandlers`.\n\n### Connection instance\n\nA `Connection` instance supports\n[Node Stream API](http://nodejs.org/docs/v0.5.8/api/streams.html) and\nhas following methods and properties:\n\n<dl>\n<dt>Property: readable (boolean)</dt>\n<dd>Is the stream readable?</dd>\n\n<dt>Property: writable (boolean)</dt>\n<dd>Is the stream writable?</dd>\n\n<dt>Property: remoteAddress (string)</dt>\n<dd>Last known IP address of the client.</dd>\n\n<dt>Property: remotePort (number)</dt>\n<dd>Last known port number of the client.</dd>\n\n<dt>Property: address (object)</dt>\n<dd>Hash with 'address' and 'port' fields.</dd>\n\n<dt>Property: headers (object)</dt>\n<dd>Hash containing various headers copied from last receiving request\n on that connection. Exposed headers include: `origin`, `referer`\n and `x-forwarded-for` (and friends). We explicitly do not grant\n access to `cookie` header, as using it may easily lead to security\n issues (for details read the section \"Authorisation\").</dd>\n\n<dt>Property: url (string)</dt>\n<dd><a href=\"http://nodejs.org/docs/v0.4.10/api/http.html#request.url\">Url</a>\n property copied from last request.</dd>\n\n<dt>Property: pathname (string)</dt>\n<dd>`pathname` from parsed url, for convenience.</dd>\n\n<dt>Property: prefix (string)</dt>\n<dd>Prefix of the url on which the request was handled.</dd>\n\n<dt>Property: protocol (string)</dt>\n<dd>Protocol used by the connection. Keep in mind that some protocols\n are indistinguishable - for example \"xhr-polling\" and \"xdr-polling\".</dd>\n\n<dt>Property: readyState (integer)</dt>\n<dd>Current state of the connection:\n 0-connecting, 1-open, 2-closing, 3-closed.</dd>\n\n<dt>write(message)</dt>\n<dd>Sends a message over opened connection. A message must be a\n non-empty string. It's illegal to send a message after the connection was\n closed (either after 'close' or 'end' method or 'close' event).</dd>\n\n<dt>close([code], [reason])</dt>\n<dd>Asks the remote client to disconnect. 'code' and 'reason'\n parameters are optional and can be used to share the reason of\n disconnection.</dd>\n\n<dt>end()</dt>\n<dd>Asks the remote client to disconnect with default 'code' and\n 'reason' values.</dd>\n\n</dl>\n\nA `Connection` instance emits the following events:\n\n<dl>\n<dt>Event: data (message)</dt>\n<dd>A message arrived on the connection. Message is a unicode\n string.</dd>\n\n<dt>Event: close ()</dt>\n<dd>Connection was closed. This event is triggered exactly once for\n every connection.</dd>\n</dl>\n\nFor example:\n\n```javascript\nsockjs_server.on('connection', function(conn) {\n console.log('connection' + conn);\n conn.on('close', function() {\n console.log('close ' + conn);\n });\n conn.on('data', function(message) {\n console.log('message ' + conn,\n message);\n });\n});\n```\n\n### Footnote\n\nA fully working echo server does need a bit more boilerplate (to\nhandle requests unanswered by SockJS), see the\n[`echo` example](https://github.com/sockjs/sockjs-node/tree/master/examples/echo)\nfor a complete code.\n\n### Examples\n\nIf you want to see samples of running code, take a look at:\n\n * [./examples/echo](https://github.com/sockjs/sockjs-node/tree/master/examples/echo)\n directory, which contains a full example of a echo server.\n * [./examples/test_server](https://github.com/sockjs/sockjs-node/tree/master/examples/test_server) a standard SockJS test server.\n\n\nConnecting to SockJS-node without the client\n--------------------------------------------\n\nAlthough the main point of SockJS it to enable browser-to-server\nconnectivity, it is possible to connect to SockJS from an external\napplication. Any SockJS server complying with 0.3 protocol does\nsupport a raw WebSocket url. The raw WebSocket url for the test server\nlooks like:\n\n * ws://localhost:8081/echo/websocket\n\nYou can connect any WebSocket RFC 6455 compliant WebSocket client to\nthis url. This can be a command line client, external application,\nthird party code or even a browser (though I don't know why you would\nwant to do so).\n\n\nDeployment and load balancing\n-----------------------------\n\nThere are two issues that need to be considered when planning a\nnon-trivial SockJS-node deployment: WebSocket-compatible load balancer\nand sticky sessions (aka session affinity).\n\n### WebSocket compatible load balancer\n\nOften WebSockets don't play nicely with proxies and load balancers.\nDeploying a SockJS server behind Nginx or Apache could be painful.\n\nFortunately recent versions of an excellent load balancer\n[HAProxy](http://haproxy.1wt.eu/) are able to proxy WebSocket\nconnections. We propose to put HAProxy as a front line load balancer\nand use it to split SockJS traffic from normal HTTP data. Take a look\nat the sample\n[SockJS HAProxy configuration](https://github.com/sockjs/sockjs-node/blob/master/examples/haproxy.cfg).\n\nThe config also shows how to use HAproxy balancing to split traffic\nbetween multiple Node.js servers. You can also do balancing using dns\nnames.\n\n### Sticky sessions\n\nIf you plan deploying more than one SockJS server, you must make sure\nthat all HTTP requests for a single session will hit the same server.\nSockJS has two mechanisms that can be useful to achieve that:\n\n * Urls are prefixed with server and session id numbers, like:\n `/resource/<server_number>/<session_id>/transport`. This is\n useful for load balancers that support prefix-based affinity\n (HAProxy does).\n * `JSESSIONID` cookie is being set by SockJS-node. Many load\n balancers turn on sticky sessions if that cookie is set. This\n technique is derived from Java applications, where sticky sessions\n are often necessary. HAProxy does support this method, as well as\n some hosting providers, for example CloudFoundry. In order to\n enable this method on the client side, please supply a\n `cookie:true` option to SockJS constructor.\n\n\nDevelopment and testing\n-----------------------\n\nIf you want to work on SockJS-node source code, you need to clone the\ngit repo and follow these steps. First you need to install\ndependencies:\n\n cd sockjs-node\n npm install\n npm install --dev\n ln -s .. node_modules/sockjs\n\nYou're ready to compile CoffeeScript:\n\n make build\n\nIf compilation succeeds you may want to test if your changes pass all\nthe tests. Currently, there are two separate test suites. For both of\nthem you need to start a SockJS-node test server (by default listening\non port 8081):\n\n make test_server\n\n### SockJS-protocol Python tests\n\nTo run it run something like:\n\n cd sockjs-protocol\n make test_deps\n ./venv/bin/python sockjs-protocol-0.3.py\n\nFor details see\n[SockJS-protocol README](https://github.com/sockjs/sockjs-protocol#readme).\n\n### SockJS-client QUnit tests\n\nYou need to start a second web server (by default listening on 8080)\nthat is serving various static html and javascript files:\n\n cd sockjs-client\n make test\n\nAt that point you should have two web servers running: sockjs-node on\n8081 and sockjs-client on 8080. When you open the browser on\n[http://localhost:8080/](http://localhost:8080/) you should be able\nrun the QUnit tests against your sockjs-node server.\n\nFor details see\n[SockJS-client README](https://github.com/sockjs/sockjs-client#readme).\n\nAdditionally, if you're doing more serious development consider using\n`make serve`, which will automatically the server when you modify the\nsource code.\n\n\nVarious issues and design considerations\n----------------------------------------\n\n### Authorisation\n\nSockJS-node does not expose cookies to the application. This is done\ndeliberately as using cookie-based authorisation with SockJS simply\ndoesn't make sense and will lead to security issues.\n\nCookies are a contract between a browser and an http server, and are\nidentified by a domain name. If a browser has a cookie set for\nparticular domain, it will pass it as a part of all http requests to\nthe host. But to get various transports working, SockJS uses a middleman\n- an iframe hosted from target SockJS domain. That means the server\nwill receive requests from the iframe, and not from the real\ndomain. The domain of an iframe is the same as the SockJS domain. The\nproblem is that any website can embed the iframe and communicate with\nit - and request establishing SockJS connection. Using cookies for\nauthorisation in this scenario will result in granting full access to\nSockJS communication with your website from any website. This is a\nclassic CSRF attack.\n\nBasically - cookies are not suited for SockJS model. If you want to\nauthorise a session - provide a unique token on a page, send it as a\nfirst thing over SockJS connection and validate it on the server\nside. In essence, this is how cookies work.\n\n\n### Deploying SockJS on Heroku\n\nLong polling is known to cause problems on Heroku, but\n[workaround for SockJS is available](https://github.com/sockjs/sockjs-node/issues/57#issuecomment-5242187).\n",
"readmeFilename": "README.md",
"bugs": {
"url": "https://github.com/sockjs/sockjs-node/issues"
},
"_id": "sockjs@0.3.8",
"dist": {
"shasum": "b512849ed629f7ec2372ded3061bb05735ee45e9"
},
"_from": "sockjs@0.3.8",
"_resolved": "https://registry.npmjs.org/sockjs/-/sockjs-0.3.8.tgz"
}