README

socket-pool

Node socket pool for persistent TCP/IPC connections

Install

$ npm install socket-pool --save

Usage

import Pool from 'socket-pool'

const pool = new Pool({
  connect: {
    host: 'localhost',
    port: 2181
  },

  // Defaults to `3000`
  connectTimeout: 3000,

  pool: {
    // the options of generic-pool
    max: 100,
    min: 10
  }

  // other options of net.Socket
})

pool.acquire()
.then(socket => {
  socket.on('data', chunk => {
    // concat chunks

    // To re-use TCP connections, it is better NOT to end or destroy a socket
    // after data received.
    // Some mechanism could be used to tell the client if there is no more
    // chunks, such as:
    // - design a protocol to define the content-length of the incoming chunks.
    if (dataFinished) {
      // Release the socket resource,
      // then it can be required again.
      socket.release()
    }
  })
})

// And then, the usage of `socket` is nearly the same as `new net.Socket`

new Pool({connect, pool, ...socketOptions})

pool Object the options of generic-pool, and the value is simply passed
connectTimeout Number=3000 the milliseconds socket pool will wait for a socket to connect to the server before timing out. Defaults to 3000 milliseconds.
socketOptions Object the options of new net.Socket(options) of the vanilla node.js. The only difference is that the option socketOptions.allowHalfOpen defaults to true. If half-opened TCP connections are not allowed, allowHalfOpen should be explicit set to false. But setting this to false is kind of silly, since that's the whole purpose of this lib.

connect `Object`

If connect.path is specified, then other socket options will be ignored, and it is only for IPC connections.

path String the same argument of socket.connect(path) of the vanilla node.js

Otherwise, it is for TCP connections, available options are:

port
host
localAddress
localPort
family
hints
lookup

pool.acquire()

Returns Promise.

Promise.resolve(socket) If the socket is successful connected
Promise.reject(error) If there are any errors
- error SocketError|TimeoutError

import {
  // If connectTimeout is specified and timed out to connect to server
  TimeoutError,
  // Socket error
  SocketError
} from 'socket-pool'

pool.acquire()
.then(
  socket => {
    // do something with socket
  },

  error => {
    console.log(error instanceof SocketError || error instanceof TimeoutError)
    // true
  }
)

The acquired socket is a wrapped net.Socket instance which will be destroyed when 'end' event occurs, and some additional methods are available:

socket.release()

The socket-pool-specified method to release the socket to the pool

socket.destroy()

Destroy the socket instance.

License

MIT

Usage no npm install needed!