Engine.IO: the realtime engine

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

How to use

Server

(A) Listening on a port

var engine = require('engine.io');
var server = engine.listen(80);

server.on('connection', function(socket){
  socket.send('utf 8 string');
  socket.send(Buffer.from([0, 1, 2, 3, 4, 5])); // binary data
});

(B) Intercepting requests for a http.Server

var engine = require('engine.io');
var http = require('http').createServer().listen(3000);
var server = engine.attach(http);

server.on('connection', function (socket) {
  socket.on('message', function(data){ });
  socket.on('close', function(){ });
});

(C) Passing in requests

var engine = require('engine.io');
var server = new engine.Server();

server.on('connection', function(socket){
  socket.send('hi');
});

// …
httpServer.on('upgrade', function(req, socket, head){
  server.handleUpgrade(req, socket, head);
});
httpServer.on('request', function(req, res){
  server.handleRequest(req, res);
});

Client

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

For more information on the client refer to the
engine-client repository.

What features does it have?

• Maximum reliability. Connections are established even in the presence of:
  • proxies and load balancers.
  • personal firewall and antivirus software.
  • for more information refer to Goals and Architecture sections
• Minimal client size aided by:
  • lazy loading of flash transports.
  • lack of redundant transports.
• Scalable
  • load balancer friendly
• Future proof
• 100% Node.JS core style
  • No API sugar (left for higher level projects)
  • Written in readable vanilla JavaScript

API

Server

Top-level

These are exposed by require('engine.io'):

Events

• flush
  • Called when a socket buffer is being flushed.
  • Arguments
    • Socket: socket being flushed
    • Array: write buffer
• drain
  • Called when a socket buffer is drained
  • Arguments
    • Socket: socket being flushed

Properties

• protocol (Number): protocol revision number
• Server: Server class constructor
• Socket: Socket class constructor
• Transport (Function): transport constructor
• transports (Object): map of available transports

Methods

• ()

  • Returns a new Server instance. If the first argument is an http.Server then the
    new Server instance will be attached to it. Otherwise, the arguments are passed
    directly to the Server constructor.
  • Parameters
    • http.Server: optional, server to attach to.
    • Object: optional, options object (see Server#constructor api docs below)

  The following are identical ways to instantiate a server and then attach it.

var httpServer; // previously created with `http.createServer();` from node.js api.

// create a server first, and then attach
var eioServer = require('engine.io').Server();
eioServer.attach(httpServer);

// or call the module as a function to get `Server`
var eioServer = require('engine.io')();
eioServer.attach(httpServer);

// immediately attach
var eioServer = require('engine.io')(httpServer);

// with custom options
var eioServer = require('engine.io')(httpServer, {
  maxHttpBufferSize: 1e3
});

• listen
  • Creates an http.Server which listens on the given port and attaches WS
    to it. It returns 501 Not Implemented for regular http requests.
  • Parameters
    • Number: port to listen on.
    • Object: optional, options object
    • Function: callback for listen.
  • Options
    • All options from Server.attach method, documented below.
    • Additionally See Server constructor below for options you can pass for creating the new Server
  • Returns Server

var engine = require('engine.io');
var server = engine.listen(3000, {
  pingTimeout: 2000,
  pingInterval: 10000
});

server.on('connection', /* ... */);

• attach
  • Captures upgrade requests for a http.Server. In other words, makes
    a regular http.Server WebSocket-compatible.
  • Parameters
    • http.Server: server to attach to.
    • Object: optional, options object
  • Options
    • All options from Server.attach method, documented below.
    • Additionally See Server constructor below for options you can pass for creating the new Server
  • Returns Server a new Server instance.

var engine = require('engine.io');
var httpServer = require('http').createServer().listen(3000);
var server = engine.attach(httpServer, {
  wsEngine: 'uws' // requires having uws as dependency
});

server.on('connection', /* ... */);

Server

The main server/manager. Inherits from EventEmitter.

Events

• connection
  • Fired when a new connection is established.
  • Arguments
    • Socket: a Socket object

Properties

Important: if you plan to use Engine.IO in a scalable way, please
keep in mind the properties below will only reflect the clients connected
to a single process.

• clients (Object): hash of connected clients by id.
• clientsCount (Number): number of connected clients.

Methods

• constructor
  • Initializes the server
  • Parameters
    • Object: optional, options object
  • Options
    • pingTimeout (Number): how many ms without a pong packet to
      consider the connection closed (5000)
    • pingInterval (Number): how many ms before sending a new ping
      packet (25000)
    • upgradeTimeout (Number): how many ms before an uncompleted transport upgrade is cancelled (10000)
    • maxHttpBufferSize (Number): how many bytes or characters a message
      can be, before closing the session (to avoid DoS). Default
      value is 10E7.
    • allowRequest (Function): A function that receives a given handshake
      or upgrade request as its first parameter, and can decide whether to
      continue or not. The second argument is a function that needs to be
      called with the decided information: fn(err, success), where
      success is a boolean value where false means that the request is
      rejected, and err is an error code.
    • transports (<Array> String): transports to allow connections
      to (['polling', 'websocket'])
    • allowUpgrades (Boolean): whether to allow transport upgrades
      (true)
    • perMessageDeflate (`Object