engine.io-client

What is engine.io-client?

The engine.io-client npm package is a client-side library that provides bidirectional event-based communication between web clients and servers. It is the client component of the Engine.IO protocol, which is a transport layer built on top of WebSocket and other transport mechanisms to provide a reliable, low-latency connection for real-time applications.

What are engine.io-client's main functionalities?

Establishing a connection

This feature allows you to establish a connection to an Engine.IO server. The 'open' event is emitted when the connection is successfully established.

const eio = require('engine.io-client');
const socket = eio('ws://localhost');
socket.on('open', function(){
  console.log('Connection established');
});

Sending messages

Once a connection is established, you can send messages to the server using the 'send' method.

socket.send('Hello World!');

Receiving messages

You can listen for messages from the server with the 'message' event. The callback function receives the message data as its argument.

socket.on('message', function(data){
  console.log('Received message:', data);
});

Handling connection errors

The 'error' event is emitted when there is a connection error. The callback function receives the error object as its argument.

socket.on('error', function(error){
  console.error('Connection error:', error);
});

Closing the connection

The 'close' event is emitted when the connection is closed. The callback function receives the reason and a description as arguments.

socket.on('close', function(reason, description){
  console.log('Connection closed', reason, description);
});

Other packages similar to engine.io-client

socket.io-client

Socket.IO-client is a more feature-rich client-side library that provides real-time bidirectional event-based communication, similar to engine.io-client. It is built on top of engine.io-client and adds additional features like namespaces, rooms, and automatic reconnection.

ws

The 'ws' package is a simple WebSocket client and server implementation for Node.js. Unlike engine.io-client, it does not provide built-in mechanisms for features like automatic reconnection and binary data handling, but it allows for more control over the WebSocket connection.

faye-websocket

Faye-websocket is a WebSocket client and server for Node.js and Ruby. It provides a simple API for handling WebSocket connections but does not include the higher-level abstractions and fallback mechanisms that engine.io-client offers.

README

Engine.IO client

This is the client for Engine.IO, the implementation of transport-based cross-browser/cross-device bi-directional communication layer for Socket.IO.

How to use

Standalone

You can find an engine.io.js file in this repository, which is a standalone build you can use as follows:

<script src="/path/to/engine.io.js"></script>
<script>
  // eio = Socket
  var socket = eio('ws://localhost');
  socket.on('open', function(){
    socket.on('message', function(data){});
    socket.on('close', function(){});
  });
</script>

With browserify

Engine.IO is a commonjs module, which means you can include it by using require on the browser and package using browserify:

1. install the client package

   $ npm install engine.io-client
   

2. write your app code

   var socket = require('engine.io-client')('ws://localhost');
   socket.on('open', function(){
     socket.on('message', function(data){});
     socket.on('close', function(){});
   });
   

3. build your app bundle

   $ browserify app.js > bundle.js
   

4. include on your page

   <script src="/path/to/bundle.js"></script>
   

Sending and receiving binary

<script src="/path/to/engine.io.js"></script>
<script>
  var socket = new eio.Socket('ws://localhost/');
  socket.binaryType = 'blob';
  socket.on('open', function () {
    socket.send(new Int8Array(5));
    socket.on('message', function(blob){});
    socket.on('close', function(){ });
  });
</script>

Node.JS

Add engine.io-client to your package.json and then:

var socket = require('engine.io-client')('ws://localhost');
socket.on('open', function(){
  socket.on('message', function(data){});
  socket.on('close', function(){});
});

Features

• Lightweight
  • Lazyloads Flash transport
• Runs on browser and node.js seamlessly
• Transports are independent of Engine
  • Easy to debug
  • Easy to unit test
• Runs inside HTML5 WebWorker
• Can send and receive binary data
  • Receives as ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer in Node
  • When XHR2 or WebSockets are used, binary is emitted directly. Otherwise binary is encoded into base64 strings, and decoded when binary types are supported.
  • With browsers that don't support ArrayBuffer, an object { base64: true, data: dataAsBase64String } is emitted on the message event.

API

Socket

The client class. Mixes in Emitter. Exposed as eio in the browser standalone build.

Properties

• protocol (Number): protocol revision number
• binaryType (String) : can be set to 'arraybuffer' or 'blob' in browsers, and buffer or arraybuffer in Node. Blob is only used in browser if it's supported.

Events

• open
  • Fired upon successful connection.
• message
  • Fired when data is received from the server.
  • Arguments
    • String | ArrayBuffer: utf-8 encoded data or ArrayBuffer containing binary data
• close
  • Fired upon disconnection. In compliance with the WebSocket API spec, this event may be fired even if the open event does not occur (i.e. due to connection error or close()).
• error
  • Fired when an error occurs.
• flush
  • Fired upon completing a buffer flush
• drain
  • Fired after drain event of transport if writeBuffer is empty
• upgradeError
  • Fired if an error occurs with a transport we're trying to upgrade to.
• upgrade
  • Fired upon upgrade success, after the new transport is set

Methods

• constructor
  • Initializes the client
  • Parameters
    • String uri
    • Object: optional, options object
  • Options
    • agent (http.Agent): http.Agent to use, defaults to false (NodeJS only)
    • upgrade (Boolean): defaults to true, whether the client should try to upgrade the transport from long-polling to something better.
    • forceJSONP (Boolean): forces JSONP for polling transport.
    • forceBase64 (Boolean): forces base 64 encoding for polling transport even when XHR2 responseType is available and WebSocket even if the used standard supports binary.
    • timestampRequests (Boolean): whether to add the timestamp with each transport request. Note: this is ignored if the browser is IE or Android, in which case requests are always stamped (false)
    • timestampParam (String): timestamp parameter (t)
    • flashPath (String): path to flash client files with trailing slash
    • policyPort (Number): port the policy server listens on (843)
    • path (String): path to connect to, default is /engine.io
    • transports (Array): a list of transports to try (in order). Defaults to ['polling', 'websocket', 'flashsocket']. Engine always attempts to connect directly with the first one, provided the feature detection test for it passes.
    • rememberUpgrade (Boolean): defaults to false. If true and if the previous websocket connection to the server succeeded, the connection attempt will bypass the normal upgrade process and will initially try websocket. A connection attempt following a transport error will use the normal upgrade process. It is recommended you turn this on only when using SSL/TLS connections, or if you know that your network does not block websockets.
• send
  • Sends a message to the server
  • Parameters
    • String | ArrayBuffer | ArrayBufferView | Blob: data to send
    • Function: optional, callback upon drain
• close
  • Disconnects the client.

Transport

The transport class. Private. Inherits from EventEmitter.

Events

• poll: emitted by polling transports upon starting a new request
• pollComplete: emitted by polling transports upon completing a request
• drain: emitted by polling transports upon a buffer drain

Flash transport

In order for the Flash transport to work correctly, ensure the flashPath property points to the location where the files web_socket.js, swfobject.js and WebSocketMainInsecure.swf are located.

These files can be found here https://github.com/gimite/web-socket-js.git

Tests

engine.io-client is used to test engine. Running the engine.io test suite ensures the client works and vice-versa.

Browser tests are run using zuul. You can run the tests locally using the following command.

./node_modules/.bin/zuul --local 8080 -- test/index.js

Additionally, engine.io-client has a standalone test suite you can run with make test which will run node.js and browser tests. You must have zuul setup with a saucelabs account.

Support

The support channels for engine.io-client are the same as socket.io:

• irc.freenode.net #socket.io
• Google Groups
• Website

Development

To contribute patches, run tests or benchmarks, make sure to clone the repository:

git clone git://github.com/LearnBoost/engine.io-client.git

Then:

cd engine.io-client
npm install

See the Tests section above for how to run tests before submitting any patches.

License

MIT - Copyright (c) 2014 Automattic, Inc.