vnfmarket/src/main/webapp/vnfmarket/node_modules/ws/README.md

   1 [![Build Status](https://secure.travis-ci.org/einaros/ws.png)](http://travis-ci.org/einaros/ws)
   2
   3 # ws: a node.js websocket library #
   4
   5 `ws` is a simple to use websocket implementation, up-to-date against RFC-6455, and [probably the fastest WebSocket library for node.js](http://web.archive.org/web/20130314230536/http://hobbycoding.posterous.com/the-fastest-websocket-module-for-nodejs).
   6
   7 Passes the quite extensive Autobahn test suite. See http://einaros.github.com/ws for the full reports.
   8
   9 Comes with a command line utility, `wscat`, which can either act as a server (--listen), or client (--connect); Use it to debug simple websocket services.
  10
  11 ## Protocol support ##
  12
  13 * **Hixie draft 76** (Old and deprecated, but still in use by Safari and Opera. Added to ws version 0.4.2, but server only. Can be disabled by setting the `disableHixie` option to true.)
  14 * **HyBi drafts 07-12** (Use the option `protocolVersion: 8`, or argument `-p 8` for wscat)
  15 * **HyBi drafts 13-17** (Current default, alternatively option `protocolVersion: 13`, or argument `-p 13` for wscat)
  16
  17 _See the echo.websocket.org example below for how to use the `protocolVersion` option._
  18
  19 ## Usage ##
  20
  21 ### Installing ###
  22
  23 `npm install ws`
  24
  25 ### Sending and receiving text data ###
  26
  27 ```js
  28 var WebSocket = require('ws');
  29 var ws = new WebSocket('ws://www.host.com/path');
  30 ws.on('open', function() {
  31     ws.send('something');
  32 });
  33 ws.on('message', function(data, flags) {
  34     // flags.binary will be set if a binary data is received
  35     // flags.masked will be set if the data was masked
  36 });
  37 ```
  38
  39 ### Sending binary data ###
  40
  41 ```js
  42 var WebSocket = require('ws');
  43 var ws = new WebSocket('ws://www.host.com/path');
  44 ws.on('open', function() {
  45     var array = new Float32Array(5);
  46     for (var i = 0; i < array.length; ++i) array[i] = i / 2;
  47     ws.send(array, {binary: true, mask: true});
  48 });
  49 ```
  50
  51 Setting `mask`, as done for the send options above, will cause the data to be masked according to the websocket protocol. The same option applies for text data.
  52
  53 ### Server example ###
  54
  55 ```js
  56 var WebSocketServer = require('ws').Server
  57   , wss = new WebSocketServer({port: 8080});
  58 wss.on('connection', function(ws) {
  59     ws.on('message', function(message) {
  60         console.log('received: %s', message);
  61     });
  62     ws.send('something');
  63 });
  64 ```
  65
  66 ### Server sending broadcast data ###
  67
  68 ```js
  69 var WebSocketServer = require('ws').Server
  70   , wss = new WebSocketServer({port: 8080});
  71
  72 wss.broadcast = function(data) {
  73         for(var i in this.clients)
  74                 this.clients[i].send(data);
  75 };
  76 ```
  77
  78 ### Error handling best practices ###
  79
  80 ```js
  81 // If the WebSocket is closed before the following send is attempted
  82 ws.send('something');
  83
  84 // Errors (both immediate and async write errors) can be detected in an optional callback.
  85 // The callback is also the only way of being notified that data has actually been sent.
  86 ws.send('something', function(error) {
  87     // if error is null, the send has been completed,
  88     // otherwise the error object will indicate what failed.
  89 });
  90
  91 // Immediate errors can also be handled with try/catch-blocks, but **note**
  92 // that since sends are inherently asynchronous, socket write failures will *not*
  93 // be captured when this technique is used.
  94 try {
  95     ws.send('something');
  96 }
  97 catch (e) {
  98     // handle error
  99 }
 100 ```
 101
 102 ### echo.websocket.org demo ###
 103
 104 ```js
 105 var WebSocket = require('ws');
 106 var ws = new WebSocket('ws://echo.websocket.org/', {protocolVersion: 8, origin: 'http://websocket.org'});
 107 ws.on('open', function() {
 108     console.log('connected');
 109     ws.send(Date.now().toString(), {mask: true});
 110 });
 111 ws.on('close', function() {
 112     console.log('disconnected');
 113 });
 114 ws.on('message', function(data, flags) {
 115     console.log('Roundtrip time: ' + (Date.now() - parseInt(data)) + 'ms', flags);
 116     setTimeout(function() {
 117         ws.send(Date.now().toString(), {mask: true});
 118     }, 500);
 119 });
 120 ```
 121
 122 ### wscat against echo.websocket.org ###
 123
 124     $ npm install -g ws
 125     $ wscat -c ws://echo.websocket.org
 126     connected (press CTRL+C to quit)
 127     > hi there
 128     < hi there
 129     > are you a happy parrot?
 130     < are you a happy parrot?
 131
 132 ### Other examples ###
 133
 134 For a full example with a browser client communicating with a ws server, see the examples folder.
 135
 136 Note that the usage together with Express 3.0 is quite different from Express 2.x. The difference is expressed in the two different serverstats-examples.
 137
 138 Otherwise, see the test cases.
 139
 140 ### Running the tests ###
 141
 142 `make test`
 143
 144 ## API Docs ##
 145
 146 See the doc/ directory for Node.js-like docs for the ws classes.
 147
 148 ## License ##
 149
 150 (The MIT License)
 151
 152 Copyright (c) 2011 Einar Otto Stangvik &lt;einaros@gmail.com&gt;
 153
 154 Permission is hereby granted, free of charge, to any person obtaining
 155 a copy of this software and associated documentation files (the
 156 'Software'), to deal in the Software without restriction, including
 157 without limitation the rights to use, copy, modify, merge, publish,
 158 distribute, sublicense, and/or sell copies of the Software, and to
 159 permit persons to whom the Software is furnished to do so, subject to
 160 the following conditions:
 161
 162 The above copyright notice and this permission notice shall be
 163 included in all copies or substantial portions of the Software.
 164
 165 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
 166 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 167 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 168 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 169 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 170 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 171 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.