Binary Protocol

Easy, fast, writers and readers for implementing custom binary protocols in node.js.

Installation

Via npm:

npm install --save binary-protocol

Usage

Defining a protocol

var BinaryProtocol = require('binary-protocol');
 
var protocol = new BinaryProtocol();
 
// define a type called 'Bytes', which is simply
// a series of raw bytes prefixed by length.
protocol.define('Bytes', {
  read: function (propertyName) {
    this
    .pushStack({length: null, value: null}) // allocate a new object to read the data into.
    .Int32BE('length') // read a 32 bit integer into the `length` property.
    .tap(function (data) {
      if (data.length === -1) {
        // if the length is -1, then there are no bytes and the value is null.
        data.value = null;
        return;
      }
      this.raw('value', data.length); // read N bytes into a property called `value`
    })
    .popStack(propertyName, function (data) {
      // pop the interim value off the stack and insert the real value into `propertyName`
      return data.value;
    });
  },
  write: function (value) {
    if (value === null) {
      this.Int32BE(-1); // a length of -1 indicates a null value.
    }
    else {
      // value is a buffer
      this
      .Int32BE(value.length) // write the buffer length
      .raw(value); // write the raw buffer
    }
  }
});
 
// define a type called `String`, which is encoded as a length
// prefixed series of bytes.
protocol.define('String', {
  read: function (propertyName) {
    this
    .Bytes(propertyName) // read `Bytes` into the property name.
    .collect(function (data) {
      // collect the final data to return
      if (data[propertyName] !== null) {
        data[propertyName] = data[propertyName].toString('utf8');
      }
      return data;
    });
  },
  write: function (value) {
    this.Bytes(new Buffer(value, 'utf8'));
  }
});

Writing data

 
var writer = protocol.createWriter();
 
writer
.Int32BE(100) // op code
.String('admin') // user name
.String('password'); // password
 
var buffer = writer.buffer;
 
someWritableStream.write(buffer);
 

Reading data

var reader = protocol.createReader(buffer);
 
reader
.Int32BE('opCode')
.String('username')
.String('password');
 
console.log(reader.next()); // {opCode: 100, username: 'admin', password: 'password'}
 

Request / Response

You can also define aggregate commands which represent a request / response

protocol.define('Login', { write: function (data) { this .Int32BE(100) // op code .String(data.username) .String(data.password); }, read: function () { this .Int32BE('status') .tap(function (data) { if (data.status === 0) { return this.String('error'); } else { return this .String('nickname') .Int32BE('totalUnreadMessages'); } }); } });

var net = require('net'), client = net.createClient('localhost', 3030), commander = protocol.createCommander(client);

var details = { username: 'admin', password: 'password' };

commander.Login(details).then(function (response) { console.log(response); });

Running the tests

First, npm install, then npm test. Code coverage generated with npm run coverage.

License

MIT, see LICENSE.md.