README

BOSCAR

Bidirectional Object Stream Control As Remote Procedure Calls. And how!

About

BOSCAR is a subset of the JSON-RPC 2.0 specification with one restriction, which is that params and result must be positional ([]), not named. In addition, it introduces a mechanism for describing streams. When a result of an RPC contains a string matching either:

boscar:readable:{uuid}
boscar:writable:{uuid}

Where {uuid} is a univeral unique identifier. Upon processing result matching this format, the client should expose a readable or writable stream interface, where reading from this pointer is performed by listening for or sending JSON-RPC "notification" payloads where the method name matches the original string value and the params array represents items to be read from or written to the virtual stream.

This allows servers implementing BOSCAR to pass streams back to clients as result parameters. Individual JSON-RPC payloads are separated by \r\n (a carriage return followed by a newline) over a bidirectional stream. This package implements the protocol over TCP or Unix Domain Sockets.

Install

npm install boscar --save

Usage

Server:

const { Readable } = require('stream');
const boscar = require('boscar');
const server = new boscar.Server({
  example(word, times, callback) {
    let count = 0;
    callback(null, new Readable({
      read() {
        if (count < times) {
          this.push(word.replace('ee', 'oo'));
          count++;
        } else {
          this.push(null);
        }
      },
      objectMode: true // NB: Streams passed to BOSCAR must be in objectMode
    }));
  }
});

server.listen(8080);

Client:

const boscar = require('boscar');
const client = new boscar.Client();

client.connect(8080);
client.invoke('example', ['beep', 3], (err, stream) => {
  stream.pipe(process.stdout); // => 'boop boop boop'
});

License

Provided under the terms of the GNU Lesser General Public License Version 3.

boscardeprecated

Usage no npm install needed!