callosum-server-tcp

Stability: 1 - Experimental

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

Usage

var CallosumServer = require('callosum-server-tcp');
var callosumServer = new CallosumServer({
    host: 'localhost',
    port: 4040
});

callosumServer.on('connection', function (conn) {
    // one of the active connections from clients that has been assigned a slot
    // do stuff with `conn` 
});

callosumServer.on('slot request', function (callback) {
    // assign a new slot
    var slot = /* pick lowest slot available (probably from a heap), ex: */ 0;
    return callback(slot); 
});

callosumServer.on('slot free', function (slot) {
    // free the slot
    // probably put it back on the heap 
});

callosumServer.listen(function () {
    console.log('server listening...'); 
});

Tests

npm test

Overview

TCP Server for Callosum, which is an open-source implementation of Indeed's Boxcar: A self-balancing distributed services protocol.

Callosum TCP Server Protocol

When a new client connects to a TCP CallosumServer, the server will respond with the slot number assigned to the connection by sending a slot number followed by \r\n. For example, for slot 13:

13\r\n

This is all the information necessary for a client to either accept the slot, and keep the connection, or reject the slot by breaking the connection.

Documentation

CallosumServer

• CallosumServer.listen(options, [callback])
• new CallosumServer(options)
• callosumServer.close([callback])
• callosumServer.listen([callback])
• Event 'connection'
• Event 'error'
• Event 'slot free'
• Event 'slot request'

CallosumServer.listen(options, [callback])

• options: See new CallosumServer(options) options.
• callback: See callosumServer.listen(callback) callback.
• Return: Object An instance of CallosumServer with server running.

Creates a new CallosumServer and starts the server.

new CallosumServer(options)

• options: Object
  • host: String (Default: undefined) Hostname for the server to listen on. If not specified, the server will accept connections directed to any IPv4 address (INADDR_ANY).
  • port: Integer (Default: 4040) Port number for the server to listen on.

Creates a new CallosumServer instance.

callosumServer.close([callback])

• callback: Function (Default: undefined) function () {} Optional callback to call once the server is stopped.

Stops the server from accepting new connections.

callosumServer.listen([callback])

• callback: Function (Default: undefined) function () {} Optional callback to call once the server is up.

Starts the server to listen to new connections.

Event connection

• function (connection) {}
  • connection: Socket object The connection object.

Emitted once the connection is assigned a new slot via a callback to the slot request event.

Event error

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

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

Event slot free

• function (slot) {}
  • slot: Integer Slot number to free.

Emitted when the a connection with previously assigned slot is broken.

Event slot request

• function (callback) {}
  • callback: Function function (error, slot) {} The callback to call with the next available slot number.

Emitted when a new connection from a client is made.

Sources

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