connman

A persistent connection pool manager for node.js.

npm install connman
71 downloads in the last day
205 downloads in the last week
998 downloads in the last month

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 has five required parameters. Host and port, obviously. The following three callbacks are the interesting part:

onConnect : Called when the initial connection is established. This takes as one parameter node's socket object which the application can use for writing, additional configuration, or adding additional listeners. Connman will already have added all listeners required for handling interesting network abnormalities.

onReset : This is called when a network connection is lost. You must provide this, but it may be a no-op if you don't care to do anything. Some applications might want to drop a queue of callbacks waiting for server responses that are now never going to arrive, or suspend writes until the connection is re-established. When onReset passes back a function, this function is called when the connection is re-established. If none is passed back, onConnect will be called again when the connection is re-established.

onData : This is called whenever there is new data to be read from the socket. onData takes one parameter - the buffer containing server response.

So:

connect(port, host, onConnect, onData, onReset, [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 useSocket() {
  // Business logic that may involve writing to the socket.
}

function onData(buff) {
  // read data from the socket asynchronously.
}

// Callback to receive a newly created socket.
function onConnect(socket) {
  sock = socket;
  useSocket();
}

// Callback to handle any cleanup in the case of a network reset...
// This might be dropping or requeuing outstanding server requests waiting for a reply.
function onReset() {
  // Cleanup.
  return useSocket; // Hand back a new starting point.
}

cm.connect(11211, 'my.memcache.server.company.com', onConnect, onReset, onData);

Using your socket.

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

Finding your socket

If you need to access the socket object, you can always ask connman for it:

cm.getConnection(port, host);

Creating a pool

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

Finding a pool

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

Adding a connection to a pool

myPool.addConnection(port, host, onConnect, onReset, onData, options);

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();
npm loves you