callosum-client-tcp-rover v0.1.0
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
: ObjectROVING_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
: Objecthost
: 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
: Objecthost
: String Host.port
: Integer Port.
Emitted when a connection to a random server is attempted but the server is unreachable.
Sources
11 years ago