connman -- A Socket Manager for Node.js
connman is a simple interface to the node.js Socket class that simplifies the common use cases of connection management, optimized for long lived persistent connections. Connman handles the business of re-establishing broken connections for you, and simplifies event notifications to the bare miniimum so that your application can clean up any outstanding business for a dropped connection, and move on as soon as the connection is repaired. Best of all, connman does not mediate the socket object, so there is no magic involved, and there is no performance impact to using this library.
Also, view the annotated source.
Stable Version: 2.0.0
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.
- Bug fix: pool getConnection should return the socket, not the internal Connection object.
- Revise callback model to take an object rather than bare functions in order to preserve context.
- Documentation Complete
- Test script written, and validated
- Connection recovery logic
- Pool and connection management
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.
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.
Using your socket.
Creating a pool
A pool takes a function that can create handler objects:
Finding a pool
Adding a connection to a pool
Getting a Connection from a Pool
Connections are added to the pool in order, and may be accesed by index:
Getting a Handler from a Pool
Likewise, handlers may be accessed:
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().
In the test directory there is a simple script 'runTest.sh' that sets up a flaky echo server, and drives traffic to the echo server through both individual connections and a managed pool. Running this script should generate no errors, and lots of messages about correct server responses and restarts. This is also an additional example of usage.