callosum-client-tcp-rover

Stability: 1 - Experimental

TCP Client rover for Callosum: a self-balancing distributed services protocol.

Usage

var ClientRover = require('callosum-client-tcp-rover');
var clientRover = new ClientRover({
    ROVING_INTERVAL: 1000, // milliseconds
    servers: {
        'localhost:4040': {host: 'localhost', port: 4040},
        'localhost:4041': {host: 'localhost', port: 4041}
    }
});

clientRover.on('error', function (error) {
    console.log(error); 
});

clientRover.on('unreachable', function (id, server) {
    console.log('server with id ' + id + ' is unreachable');
    console.dir(server); // for example: {host: 'localhost', port: 4041}
});

clientRover.on('connection', function (slot, socket) {
    console.log('new connection with slot number ' + slot);
    // keep socket open or close it depending on client configuration and slot
});

// start requesting connections from servers every ROVING_INTERVAL
clientRover.start(); 

// add additional servers as they become available
clientRover.addServer('localhost:4042', {host: 'localhost', port: 4042});

// remove servers by id
clientRover.dropServer('localhost:4042');

Tests

npm test

Overview

TCP Client rover for Callosum: a self-balancing distributed services protocol.

The rover maintains a list of servers it was given (with follow-on updates) and every ROVING_INTERVAL selects a server at random to connect to. Upon connection, as dictated by the Callosum TCP Server Protocol, a slot number will be sent to the rover from the server. For example, for slot 13:

13\r\n

The rover will parse this slot number and then emit a connection event with the slot and the socket. It is then up to the TCP Client to decide whether the connection should be kept or not. Rover no longer maintains knowledge of it and goes to sleep until woken up again according to ROVING_INTERVAL.

Documentation

CallosumClientRover

Public API

• new CallosumClientRover(options)
• callosumClientRover.addServer(id, server)
• callosumClientRover.dropServer(id)
• callosumClientRover.start()
• Event 'connection'
• Event 'error'
• Event 'unreachable'

new CallosumClientRover(options)

• options: Object
  • ROVING_INTERVAL: Integer (Default: 1000) Interval in milliseconds between connection attempts.
  • servers: Object (Default: {}) Map, by id, of servers to initialize with.

Creates a new CallosumClientRover instance.

callosumClientRover.addServer(id, server)

• id: String Server identifier.
• server: Object
  • host: String Host.
  • port: Integer Port.

Adds the server to be considered for new connections.

callosumClientRover.connect()

CAUTION: reserved for internal use

Executes a connection attempt to a random server.

callosumClientRover.dropServer(id)

• id: String Server identifier.

Removes the server from being selected for new connections.

callosumClientRover.start()

Immediately attempts to connect to a random Callosum server and then continues the attempts every ROVING_INTERVAL.

Event connection

• function (slot, socket) {}
  • slot: Integer Slot number for this connection.
  • socket: Socket object The socket object for this connection.

Emitted when a successful connection to a random server is made.

Event error

• function (error) {}
  • error: Object An error that occurred.

Emitted when CallosumClientRover encounters an error. If no handler is registered, an exception will be thrown.

Event unreachable

• function (id, server) {}
  • id: String Id of the server that is unreachable.
  • server: Object
    • host: String Host.
    • port: Integer Port.

Emitted when a connection to a random server is attempted but the server is unreachable.

Sources

• Boxcar: A self-balacing distributed services protocol
• @IndeedEng: Boxcar: A self-balancing distributed services protocol