engine.io-parser

What is engine.io-parser?

The engine.io-parser npm package is designed for encoding and decoding packets used by engine.io, which is a transport layer for real-time data exchange between a client and a server. It handles the framing of messages for transport over various real-time protocols and supports binary data.

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

Encoding messages

This feature allows you to encode a message packet into a format suitable for transport over the network. The `encodePacket` function takes a packet object and a callback function that receives the encoded packet.

const { encodePacket } = require('engine.io-parser');
const packet = { type: 'message', data: 'hello' };
encodePacket(packet, false, (encodedPacket) => {
  // handle the encoded packet
});

Decoding messages

This feature allows you to decode a message packet that was received from the network. The `decodePacket` function takes an encoded packet and the type of data ('string' or 'binary') and returns the decoded packet object.

const { decodePacket } = require('engine.io-parser');
const encodedPacket = '2hello'; // example of an encoded message packet
const packet = decodePacket(encodedPacket, 'string');
// handle the decoded packet

Support for binary data

This feature provides support for encoding and decoding binary data. The `encodePacket` and `decodePacket` functions can handle binary data when the second argument is set to `true` for binary.

const { encodePacket, decodePacket } = require('engine.io-parser');
const binaryData = new ArrayBuffer(100);
const packet = { type: 'message', data: binaryData };
encodePacket(packet, true, (encodedPacket) => {
  // handle the encoded packet with binary data
});
const decodedPacket = decodePacket(encodedPacket, 'binary');
// handle the decoded packet with binary data

Other packages similar to engine.io-parser

ws

The 'ws' package provides a WebSocket client and server implementation. It allows for real-time communication similar to engine.io-parser but is focused on the WebSocket protocol specifically, whereas engine.io-parser is part of the engine.io ecosystem which can fall back to other transport mechanisms if WebSockets are not available.

socket.io-parser

The 'socket.io-parser' is used by Socket.IO to encode and decode messages. It is similar to engine.io-parser but is tailored for the Socket.IO framework, which builds on top of engine.io to provide additional features like rooms, namespaces, and middleware support.

json-socket

The 'json-socket' package is a wrapper around the Node.js net library that adds a layer for seamless JSON message sending. It is similar to engine.io-parser in that it handles message framing, but it is specifically designed for TCP sockets and does not support the variety of transport layers that engine.io-parser does.

README

engine.io-parser

This is the JavaScript parser for the engine.io protocol encoding, shared by both engine.io-client and engine.io.

How to use

Standalone

The parser can encode/decode packets, payloads, and payloads as binary with the following methods: encodePacket, decodePacket, encodePayload, decodePayload, encodePayloadAsBinary, decodePayloadAsBinary.

The browser-side parser also includes encodePayloadAsArrayBuffer and encodePayloadAsBlob.

Example:

var parser = require('engine.io-parser');

var data = new Buffer(5);
for (var i = 0; i < data.length; i++) { data[i] = i; }

parser.encodePacket({ type: 'message', data: data }, function(encoded) {
  var decodedData = parser.decodePacket(encoded); // { type: 'message', data: data }
});

With browserify

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

1. install the parser package

   npm install engine.io-parser
   

2. write your app code

   var parser = require('engine.io-parser');
   
   var testBuffer = new Int8Array(10);
   for (var i = 0; i < testBuffer.length; i++) testBuffer[i] = i;
   
   var packets = [{ type: 'message', data: testBuffer.buffer }, { type: 'message', data: 'hello' }];
   
   parser.encodePayload(packets, function(encoded) {
     parser.decodePayload(encoded,
       function(packet, index, total) {
         var isLast = index + 1 == total;
         if (!isLast) {
           var buffer = new Int8Array(packet.data); // testBuffer
         } else {
           var message = packet.data; // 'hello'
         }
       });
   });
   

3. build your app bundle

   $ browserify app.js > bundle.js
   

4. include on your page

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

Features

• Runs on browser and node.js seamlessly
• Runs inside HTML5 WebWorker
• Can encode and decode packets
  • Encodes from/to ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer in Node

API

Note: cb(type) means the type is a callback function that contains a parameter of type type when called.

Node

• encodePacket

  • Encodes a packet.
  • Parameters
    • Object: the packet to encode, has type and data.
      • data: can be a String, Number, Buffer, ArrayBuffer
    • Boolean: optional, binary support
    • Function: callback, returns the encoded packet (cb(String))

• decodePacket

  • Decodes a packet. Data also available as an ArrayBuffer if requested.
  • Returns data as String or (Blob on browser, ArrayBuffer on Node)
  • Parameters
    • String | ArrayBuffer: the packet to decode, has type and data
    • String: optional, the binary type

• encodeBase64Packet

  • Encodes a packet with binary data in a base64 string (String)
  • Parameters
    • Object: the packet to encode, has type and data
    • Function: callback, returns the base64 encoded message (cb(String))

• decodeBase64Packet

  • Decodes a packet encoded in a base64 string.
  • Parameters
    • String: the base64 encoded message
    • String: optional, the binary type

• encodePayload

  • Encodes multiple messages (payload).
  • If any contents are binary, they will be encoded as base64 strings. Base64 encoded strings are marked with a b before the length specifier
  • Parameters
    • Array: an array of packets
    • Boolean: optional, binary support
    • Function: callback, returns the encoded payload (cb(String))

• decodePayload

  • Decodes data when a payload is maybe expected. Possible binary contents are decoded from their base64 representation.
  • Parameters
    • String: the payload
    • String: optional, the binary type
    • Function: callback, returns (cb(Object: packet, Number:packet index, Number:packet total))

• encodePayloadAsBinary

  • Encodes multiple messages (payload) as binary.
  • Parameters
    • Array: an array of packets
    • Function: callback, returns the encoded payload (cb(Buffer))

• decodePayloadAsBinary

  • Decodes data when a payload is maybe expected. Strings are decoded by interpreting each byte as a key code for entries marked to start with 0. See description of encodePayloadAsBinary.
  • Parameters
    • Buffer: the buffer
    • String: optional, the binary type
    • Function: callback, returns the decoded packet (cb(Object))

Browser

• encodePayloadAsArrayBuffer
  • Encodes multiple messages (payload) as binary.
  • Parameters
    • Array: an array of packets
    • Function: callback, returns the encoded payload (cb(ArrayBuffer))
• encodePayloadAsBlob
  • Encodes multiple messages (payload) as blob.
  • Parameters
    • Array: an array of packets
    • Function: callback, returns the encoded payload (cb(Blob))

Tests

Standalone tests can be run with make test which will run both node.js and browser tests.

Browser tests are run using zuul. (You must have zuul setup with a saucelabs account.)

You can run the tests locally using the following command:

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

Support

The support channels for engine.io-parser 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-parser.git

Then:

cd engine.io-parser
npm install

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

License

MIT