connman v1.0.0

connman

For full documentation, please visit: http://overclocked.com/connman

connman

Connman is a very thin network connection manager for node.js. With connman you can create network connections or pools of connections that will re-establish connection in case of interrupted connectivity. The developer retains full and direct access to the node.js socket object. Rather than adding boilerplate code for listening to network events and cut-n-paste retry logic, connman offers simple setup and teardown for your connections. With callbacks for the connection event and any reset event, you can significantly simplify error management without any loss of performance or functionality.

Installation

npm install connman

Usage

Connect to a single resource

Setting up a connection requires three parameters: Host, Port, and Handler. The fourth parameter, options, can be provided to hand to the node.js socket construction call.

The handler must implement four methods:

• onConnect(socket) : This will be called once, upon initial, successful connection.
• onReset() : This will be called any time the network connection is dropped.
• onReconnect() : This will be called any time the network connection is restored.
• onData(buffer) : This will be called any time there is new data available from the connection.

Any of these methods may be no-ops, but between the time onReset and onReconnect are called, the socket passed to onConnect will probably throw exceptions. Also note, any results expected from the other end of the connection at the time onReset is called will be lost, and should either be dealt with or retransmitted after onReconnect.

So:

connect(port, host, handler, options)

Note that the optional options are the same as in the node.js socket constructor. Most use cases will not need to pass in options.

The following example demonstrates access to a single socket.

var cm = require('connman');

var sock;

function Conn() {
  this.sock = null;
}

Conn.prototype.onData(buff) {
  // read from the socket asynchronously.
}

Conn.prototype.onConnect(socket) {
  this.sock = socket;
  useSocket();
}

Conn.prototype.onReset() {
  stopSocket();
}

Conn.prototype.onReconnect() {
  useSocket();
}

cm.connect(11211, 'my.memcache.server.company.com', new Conn());

Using your socket.

Conn.prototype.onData(buffer) {
  console.log(buffer.toString('utf8');
}
Conn.prototype.onConnect(socket) {
  for(var i = 0; i < 100; i++) {
    socket.write('ping\r\n');
  }
}

Creating a pool

A pool takes a function that can create handler objects:

function handlerFactory() {
  return new Conn();
}

var myPool = cm.createPool('myPool', handlerFactory);

Finding a pool

var myPool = cm.getPool('myPool');

Adding a connection to a pool

myPool.addConnection(port, host, options);

Getting a connection from a pool

Connections are added to the pool in order, and may be accesed by index:

var socket = myPool.getConnection(3);

Getting a handler from a pool

Likewise, handlers may be accessed:

var handler = myPool.getHandler(3);

Shutting things down

Note that using the node library's socket.end() will not have the desired effect: the library will just reconnect immediately! Instead, use disconnect().

// Close an individual socket:
socket.disconnect();

// Close all sockets in a pool:
cm.getPool('myConnectionPool').disconnect();

// Close all sockets managed by connman:
cm.disconnectAll();