device_home/node_modules/engine.io-client/README.md

   1
   2 # Engine.IO client
   3
   4 [![Build Status](https://github.com/socketio/engine.io-client/workflows/CI/badge.svg)](https://github.com/socketio/engine.io-client/actions)
   5 [![NPM version](https://badge.fury.io/js/engine.io-client.svg)](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.