socketioMEANseed/server/node_modules/engine.io-client/README.md
server/node_modules/engine.io-client/README.mdRaw
1
2# Engine.IO client
3
4[](http://travis-ci.org/socketio/engine.io-client)
5[](http://badge.fury.io/js/engine.io-client)
6
7This is the client for [Engine.IO](http://github.com/socketio/engine.io),
8the implementation of transport-based cross-browser/cross-device
9bi-directional communication layer for [Socket.IO](http://github.com/socketio/socket.io).
10
11## How to use
12
13### Standalone
14
15You can find an `engine.io.js` file in this repository, which is a
16standalone build you can use as follows:
17
18```html
19<script src="/path/to/engine.io.js"></script>
20<script>
21 // eio = Socket
22 var socket = eio('ws://localhost');
23 socket.on('open', function(){
24 socket.on('message', function(data){});
25 socket.on('close', function(){});
26 });
27</script>
28```
29
30### With browserify
31
32Engine.IO is a commonjs module, which means you can include it by using
33`require` on the browser and package using [browserify](http://browserify.org/):
34
351. install the client package
36
37 ```bash
38 $ npm install engine.io-client
39 ```
40
411. write your app code
42
43 ```js
44 var socket = require('engine.io-client')('ws://localhost');
45 socket.on('open', function(){
46 socket.on('message', function(data){});
47 socket.on('close', function(){});
48 });
49 ```
50
511. build your app bundle
52
53 ```bash
54 $ browserify app.js > bundle.js
55 ```
56
571. include on your page
58
59 ```html
60 <script src="/path/to/bundle.js"></script>
61 ```
62
63### Sending and receiving binary
64
65```html
66<script src="/path/to/engine.io.js"></script>
67<script>
68 var socket = new eio.Socket('ws://localhost/');
69 socket.binaryType = 'blob';
70 socket.on('open', function () {
71 socket.send(new Int8Array(5));
72 socket.on('message', function(blob){});
73 socket.on('close', function(){ });
74 });
75</script>
76```
77
78### Node.JS
79
80Add `engine.io-client` to your `package.json` and then:
81
82```js
83var socket = require('engine.io-client')('ws://localhost');
84socket.on('open', function(){
85 socket.on('message', function(data){});
86 socket.on('close', function(){});
87});
88```
89
90### Node.js with certificates
91```js
92var opts = {
93 key: fs.readFileSync('test/fixtures/client.key'),
94 cert: fs.readFileSync('test/fixtures/client.crt'),
95 ca: fs.readFileSync('test/fixtures/ca.crt')
96};
97
98var socket = require('engine.io-client')('ws://localhost', opts);
99socket.on('open', function(){
100 socket.on('message', function(data){});
101 socket.on('close', function(){});
102});
103```
104
105### Node.js with extraHeaders
106```js
107var opts = {
108 extraHeaders: {
109 'X-Custom-Header-For-My-Project': 'my-secret-access-token',
110 'Cookie': 'user_session=NI2JlCKF90aE0sJZD9ZzujtdsUqNYSBYxzlTsvdSUe35ZzdtVRGqYFr0kdGxbfc5gUOkR9RGp20GVKza; path=/; expires=Tue, 07-Apr-2015 18:18:08 GMT; secure; HttpOnly'
111 }
112};
113
114var socket = require('engine.io-client')('ws://localhost', opts);
115socket.on('open', function(){
116 socket.on('message', function(data){});
117 socket.on('close', function(){});
118});
119```
120
121## Features
122
123- Lightweight
124- Runs on browser and node.js seamlessly
125- Transports are independent of `Engine`
126 - Easy to debug
127 - Easy to unit test
128- Runs inside HTML5 WebWorker
129- Can send and receive binary data
130 - Receives as ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer
131 in Node
132 - When XHR2 or WebSockets are used, binary is emitted directly. Otherwise
133 binary is encoded into base64 strings, and decoded when binary types are
134 supported.
135 - With browsers that don't support ArrayBuffer, an object { base64: true,
136 data: dataAsBase64String } is emitted on the `message` event.
137
138## API
139
140### Socket
141
142The client class. Mixes in [Emitter](http://github.com/component/emitter).
143Exposed as `eio` in the browser standalone build.
144
145#### Properties
146
147- `protocol` _(Number)_: protocol revision number
148- `binaryType` _(String)_ : can be set to 'arraybuffer' or 'blob' in browsers,
149 and `buffer` or `arraybuffer` in Node. Blob is only used in browser if it's
150 supported.
151
152#### Events
153
154- `open`
155 - Fired upon successful connection.
156- `message`
157 - Fired when data is received from the server.
158 - **Arguments**
159 - `String` | `ArrayBuffer`: utf-8 encoded data or ArrayBuffer containing
160 binary data
161- `close`
162 - Fired upon disconnection. In compliance with the WebSocket API spec, this event may be
163 fired even if the `open` event does not occur (i.e. due to connection error or `close()`).
164- `error`
165 - Fired when an error occurs.
166- `flush`
167 - Fired upon completing a buffer flush
168- `drain`
169 - Fired after `drain` event of transport if writeBuffer is empty
170- `upgradeError`
171 - Fired if an error occurs with a transport we're trying to upgrade to.
172- `upgrade`
173 - Fired upon upgrade success, after the new transport is set
174- `ping`
175 - Fired upon _flushing_ a ping packet (ie: actual packet write out)
176- `pong`
177 - Fired upon receiving a pong packet.
178
179#### Methods
180
181- **constructor**
182 - Initializes the client
183 - **Parameters**
184 - `String` uri
185 - `Object`: optional, options object
186 - **Options**
187 - `agent` (`http.Agent`): `http.Agent` to use, defaults to `false` (NodeJS only)
188 - `upgrade` (`Boolean`): defaults to true, whether the client should try
189 to upgrade the transport from long-polling to something better.
190 - `forceJSONP` (`Boolean`): forces JSONP for polling transport.
191 - `jsonp` (`Boolean`): determines whether to use JSONP when
192 necessary for polling. If disabled (by settings to false) an error will
193 be emitted (saying "No transports available") if no other transports
194 are available. If another transport is available for opening a
195 connection (e.g. WebSocket) that transport
196 will be used instead.
197 - `forceBase64` (`Boolean`): forces base 64 encoding for polling transport even when XHR2 responseType is available and WebSocket even if the used standard supports binary.
198 - `enablesXDR` (`Boolean`): enables XDomainRequest for IE8 to avoid loading bar flashing with click sound. default to `false` because XDomainRequest has a flaw of not sending cookie.
199 - `timestampRequests` (`Boolean`): whether to add the timestamp with each
200 transport request. Note: polling requests are always stamped unless this
201 option is explicitly set to `false` (`false`)
202 - `timestampParam` (`String`): timestamp parameter (`t`)
203 - `policyPort` (`Number`): port the policy server listens on (`843`)
204 - `path` (`String`): path to connect to, default is `/engine.io`
205 - `transports` (`Array`): a list of transports to try (in order).
206 Defaults to `['polling', 'websocket']`. `Engine`
207 always attempts to connect directly with the first one, provided the
208 feature detection test for it passes.
209 - `rememberUpgrade` (`Boolean`): defaults to false.
210 If true and if the previous websocket connection to the server succeeded,
211 the connection attempt will bypass the normal upgrade process and will initially
212 try websocket. A connection attempt following a transport error will use the
213 normal upgrade process. It is recommended you turn this on only when using
214 SSL/TLS connections, or if you know that your network does not block websockets.
215 - `pfx` (`String`): Certificate, Private key and CA certificates to use for SSL. Can be used in Node.js client environment to manually specify certificate information.
216 - `key` (`String`): Private key to use for SSL. Can be used in Node.js client environment to manually specify certificate information.
217 - `passphrase` (`String`): A string of passphrase for the private key or pfx. Can be used in Node.js client environment to manually specify certificate information.
218 - `cert` (`String`): Public x509 certificate to use. Can be used in Node.js client environment to manually specify certificate information.
219 - `ca` (`String`|`Array`): An authority certificate or array of authority certificates to check the remote host against.. Can be used in Node.js client environment to manually specify certificate information.
220 - `ciphers` (`String`): A string describing the ciphers to use or exclude. Consult the [cipher format list](http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT) for details on the format. Can be used in Node.js client environment to manually specify certificate information.
221 - `rejectUnauthorized` (`Boolean`): If true, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent. Can be used in Node.js client environment to manually specify certificate information.
222 - `perMessageDeflate` (`Object|Boolean`): parameters of the WebSocket permessage-deflate extension
223 (see [ws module](https://github.com/einaros/ws) api docs). Set to `false` to disable. (`true`)
224 - `threshold` (`Number`): data is compressed only if the byte size is above this value. This option is ignored on the browser. (`1024`)
225 - `extraHeaders` (`Object`): Headers that will be passed for each request to the server (via xhr-polling and via websockets). These values then can be used during handshake or for special proxies. Can only be used in Node.js client environment.
226 - `onlyBinaryUpgrades` (`Boolean`): whether transport upgrades should be restricted to transports supporting binary data (`false`)
227 - `requestTimeout` (`Number`): Timeout for xhr-polling requests in milliseconds (`0`)
228 - `forceNode` (`Boolean`): Uses NodeJS implementation for websockets - even if there is a native Browser-Websocket available, which is preferred by default over the NodeJS implementation. (This is useful when using hybrid platforms like nw.js or electron) (`false`, NodeJS only)
229 - `localAddress` (`String`): the local IP address to connect to
230- `send`
231 - Sends a message to the server
232 - **Parameters**
233 - `String` | `ArrayBuffer` | `ArrayBufferView` | `Blob`: data to send
234 - `Object`: optional, options object
235 - `Function`: optional, callback upon `drain`
236 - **Options**
237 - `compress` (`Boolean`): whether to compress sending data. This option is ignored and forced to be `true` on the browser. (`true`)
238- `close`
239 - Disconnects the client.
240
241### Transport
242
243The transport class. Private. _Inherits from EventEmitter_.
244
245#### Events
246
247- `poll`: emitted by polling transports upon starting a new request
248- `pollComplete`: emitted by polling transports upon completing a request
249- `drain`: emitted by polling transports upon a buffer drain
250
251## Tests
252
253`engine.io-client` is used to test
254[engine](http://github.com/socketio/engine.io). Running the `engine.io`
255test suite ensures the client works and vice-versa.
256
257Browser tests are run using [zuul](https://github.com/defunctzombie/zuul). You can
258run the tests locally using the following command.
259
260```
261./node_modules/.bin/zuul --local 8080 -- test/index.js
262```
263
264Additionally, `engine.io-client` has a standalone test suite you can run
265with `make test` which will run node.js and browser tests. You must have zuul setup with
266a saucelabs account.
267
268## Support
269
270The support channels for `engine.io-client` are the same as `socket.io`:
271 - irc.freenode.net **#socket.io**
272 - [Google Groups](http://groups.google.com/group/socket_io)
273 - [Website](http://socket.io)
274
275## Development
276
277To contribute patches, run tests or benchmarks, make sure to clone the
278repository:
279
280```bash
281git clone git://github.com/socketio/engine.io-client.git
282```
283
284Then:
285
286```bash
287cd engine.io-client
288npm install
289```
290
291See the `Tests` section above for how to run tests before submitting any patches.
292
293## License
294
295MIT - Copyright (c) 2014 Automattic, Inc.