negotiation

negotiation

Negotiation allows you to negotiate protocols between a client and server. This allows you to ship multiple versions of your protocol and have the server/client reach a agreement about which protocol to use. We do assume that the server has all possible protocols registered and that the client tells the server which versions they support.

We have a strong preference for binary protocols so when they are available we will prefer them over anything else.

Installation

The module was written to be compatible with Node.js and browserify. The release are pushed in the public npm registry and can therefor be installed from the CLI by executing:

npm install --save negotiation

Install today and get our revolutionary Binary Boost Bonus for free!

Usage

In all API examples we assume that you've pre-required the module and initialized the code as following:

'use strict';

var Negotiation = require('negotiation');
  , n = new Negotiation();

negotiation.register

Register a new protocol in our negotiation instance. This method accepts 2 arguments.

1. The name of the protocol that you're adding. This will also be used again in the unique id that we're generating and returning in the available method.
2. The protocol that you register needs to be an object. This object should have the following properties:
   • binary Boolean that indicates if binary data is supported in the protocol, defaults to false.
   • version Version number of the protocol. Try to follow semver without pre-release tags and other kinds of bullshit. So just pure x.x.x based versioning as we parse out the numbers and generate score of it for sorting and ranking purposes. It defaults to 0.0.0.

You can also add more properties as this object will be returned by the negotiation.select method.

n.register('json', { binary: false, version: '0.0.1' });
n.register('ejson', { binary: true, version: '1.0.9' });

The method returns it self so you can chain it.

negotiation.select

Select a protocol out of the given list of supported protocols. This method accepts 2 arguments:

1. Array of available protocols.
2. Prefer boolean that indicates the preference of binary protocols over regular protocols. So even if they have a lower version number it will take the highest matching binary protocol.

var protocol = n.select(['foo@1.34.5', 'foo@1.35.0', 'foo@1.35.11']);

If no available protocols are given we will check all our supported protocols and return the one we prefer. If no matching protocol is found we will return undefined all other matches will return the set protocol.

negotiation.available

Return the id's of all available protocols that we send for the negotiation. By default it will return all non binary protocols as we're unsure if the host environment supports binary. If you want to include binary protocols pass in true as first argument.

var list = n.available();

var includingbinary = n.available(true);

This method will always return an array. Even if you didn't registry any protocols, it will just return an empty array.

negotiation.destroy

Fully destroy the created negotitation instance so it removes all references to the stored protocols and it can be garbage collected by the JavaScript engine. When you destroy it first the time it will return true and the second

• next times it will return false as it was already destroyed.

n.destroy();

License

MIT