README.md (12413B)
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 7 This is the client for [Engine.IO](http://github.com/socketio/engine.io), 8 the implementation of transport-based cross-browser/cross-device 9 bi-directional communication layer for [Socket.IO](http://github.com/socketio/socket.io). 10 11 ## How to use 12 13 ### Standalone 14 15 You can find an `engine.io.js` file in this repository, which is a 16 standalone 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 32 Engine.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 35 1. install the client package 36 37 ```bash 38 $ npm install engine.io-client 39 ``` 40 41 1. 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 51 1. build your app bundle 52 53 ```bash 54 $ browserify app.js > bundle.js 55 ``` 56 57 1. 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 80 Add `engine.io-client` to your `package.json` and then: 81 82 ```js 83 var socket = require('engine.io-client')('ws://localhost'); 84 socket.on('open', function(){ 85 socket.on('message', function(data){}); 86 socket.on('close', function(){}); 87 }); 88 ``` 89 90 ### Node.js with certificates 91 ```js 92 var 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 98 var socket = require('engine.io-client')('ws://localhost', opts); 99 socket.on('open', function(){ 100 socket.on('message', function(data){}); 101 socket.on('close', function(){}); 102 }); 103 ``` 104 105 ### Node.js with extraHeaders 106 ```js 107 var 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 114 var socket = require('engine.io-client')('ws://localhost', opts); 115 socket.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 142 The client class. Mixes in [Emitter](http://github.com/component/emitter). 143 Exposed 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 - `withCredentials` (`Boolean`): defaults to `true`, whether to include credentials (cookies, authorization headers, TLS client certificates, etc.) with cross-origin XHR polling requests. 200 - `timestampRequests` (`Boolean`): whether to add the timestamp with each 201 transport request. Note: polling requests are always stamped unless this 202 option is explicitly set to `false` (`false`) 203 - `timestampParam` (`String`): timestamp parameter (`t`) 204 - `policyPort` (`Number`): port the policy server listens on (`843`) 205 - `path` (`String`): path to connect to, default is `/engine.io` 206 - `transports` (`Array`): a list of transports to try (in order). 207 Defaults to `['polling', 'websocket']`. `Engine` 208 always attempts to connect directly with the first one, provided the 209 feature detection test for it passes. 210 - `transportOptions` (`Object`): hash of options, indexed by transport name, overriding the common options for the given transport 211 - `rememberUpgrade` (`Boolean`): defaults to false. 212 If true and if the previous websocket connection to the server succeeded, 213 the connection attempt will bypass the normal upgrade process and will initially 214 try websocket. A connection attempt following a transport error will use the 215 normal upgrade process. It is recommended you turn this on only when using 216 SSL/TLS connections, or if you know that your network does not block websockets. 217 - `pfx` (`String`|`Buffer`): Certificate, Private key and CA certificates to use for SSL. Can be used in Node.js client environment to manually specify certificate information. 218 - `key` (`String`): Private key to use for SSL. Can be used in Node.js client environment to manually specify certificate information. 219 - `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. 220 - `cert` (`String`): Public x509 certificate to use. Can be used in Node.js client environment to manually specify certificate information. 221 - `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. 222 - `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. 223 - `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. 224 - `perMessageDeflate` (`Object|Boolean`): parameters of the WebSocket permessage-deflate extension 225 (see [ws module](https://github.com/einaros/ws) api docs). Set to `false` to disable. (`true`) 226 - `threshold` (`Number`): data is compressed only if the byte size is above this value. This option is ignored on the browser. (`1024`) 227 - `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. 228 - `onlyBinaryUpgrades` (`Boolean`): whether transport upgrades should be restricted to transports supporting binary data (`false`) 229 - `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) 230 - `localAddress` (`String`): the local IP address to connect to 231 - **Polling-only options** 232 - `requestTimeout` (`Number`): Timeout for xhr-polling requests in milliseconds (`0`) 233 - **Websocket-only options** 234 - `protocols` (`Array`): a list of subprotocols (see [MDN reference](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Subprotocols)) 235 - `send` 236 - Sends a message to the server 237 - **Parameters** 238 - `String` | `ArrayBuffer` | `ArrayBufferView` | `Blob`: data to send 239 - `Object`: optional, options object 240 - `Function`: optional, callback upon `drain` 241 - **Options** 242 - `compress` (`Boolean`): whether to compress sending data. This option is ignored and forced to be `true` on the browser. (`true`) 243 - `close` 244 - Disconnects the client. 245 246 ### Transport 247 248 The transport class. Private. _Inherits from EventEmitter_. 249 250 #### Events 251 252 - `poll`: emitted by polling transports upon starting a new request 253 - `pollComplete`: emitted by polling transports upon completing a request 254 - `drain`: emitted by polling transports upon a buffer drain 255 256 ## Tests 257 258 `engine.io-client` is used to test 259 [engine](http://github.com/socketio/engine.io). Running the `engine.io` 260 test suite ensures the client works and vice-versa. 261 262 Browser tests are run using [zuul](https://github.com/defunctzombie/zuul). You can 263 run the tests locally using the following command. 264 265 ``` 266 ./node_modules/.bin/zuul --local 8080 -- test/index.js 267 ``` 268 269 Additionally, `engine.io-client` has a standalone test suite you can run 270 with `make test` which will run node.js and browser tests. You must have zuul setup with 271 a saucelabs account. 272 273 ## Support 274 275 The support channels for `engine.io-client` are the same as `socket.io`: 276 - irc.freenode.net **#socket.io** 277 - [Google Groups](http://groups.google.com/group/socket_io) 278 - [Website](http://socket.io) 279 280 ## Development 281 282 To contribute patches, run tests or benchmarks, make sure to clone the 283 repository: 284 285 ```bash 286 git clone git://github.com/socketio/engine.io-client.git 287 ``` 288 289 Then: 290 291 ```bash 292 cd engine.io-client 293 npm install 294 ``` 295 296 See the `Tests` section above for how to run tests before submitting any patches. 297 298 ## License 299 300 MIT - Copyright (c) 2014 Automattic, Inc.