HTTP pool and load balancer for node.

var Pool = require("poolee")
var http = require("http")

var servers =
  ["127.0.0.1:8886"
  ,"127.0.0.1:8887"
  ,"127.0.0.1:8888"
  ,"127.0.0.1:8889"]

var postData = '{"name":"Danny Coates"}'

var pool = new Pool(http, servers, options)

pool.request(
  { method: "PUT"
  , path: "/users/me"
  }
, postData
, function (error, response, body) {
    if (error) {
      console.error(error.message)
      return
    }
    if(response.statusCode === 201) {
      console.log("put succeeded")
    }
    else {
      console.log(response.statusCode)
      console.log(body)
    }
  }
)

var Pool = require('poolee')
//...

var pool = new Pool(
  http                     // the http module to use (require('http') or require('https'))
  ,
  [ "127.0.0.1:1337"       // array of endpoints in "host:port" form
  , "127.0.0.1:1338"
  ]
  ,                        // options
  { maxPending: 1000       // maximum number of outstanding request to allow
  , maxSockets: 200        // max sockets per endpoint Agent
  , timeout: 60000         // request timeout in ms
  , resolution: 1000       // timeout check interval (see below)
  , keepAlive: false       // use an alternate Agent that does http keep-alive properly
  , ping: undefined        // health check url
  , pingTimeout: 2000      // ping timeout in ms
  , retryFilter: undefined // see below
  , retryDelay: 20         // see below
  , maxRetries: 5          // see below
  , name: undefined        // optional string
  , agentOptions: undefined// an object for passing options directly to the Http Agent
  }
)

Once this threshold is reached, requests will return an error to the callback as a signal to slow down the rate of requests.

Pending requests have their timeouts checked at this rate. If your timeout is 60000 and resolution is 1000, the request will timeout no later than 60999

The default http Agent does keep-alive in a stupid way. If you want it to work how you'd expect it to set this to true.

All valid http responses aren't necessarily a "success". This function lets you check the response before calling the request callback. Returning a "truthy" value will retry the request.

For instance, we may want to always retry 500 responses by default:

options.retryFilter = function (
    options  // the request.options
  , response // the http response object
  , body     // the response body
  ) {
  return response.statusCode === 500
}

If the returned value is true the next attempt will be delayed using exponential backoff; if its Number it will delay the next attempt by that many ms (useful for Retry-After headers)

Pool uses exponential backoff when retrying requests. This value is a scaling factor of the time (ms) to wait. Here's how it works:

Math.random() * Math.pow(2, attemptNumber) * retryDelay

If retryDelay is 20, attemptNumber 1 (the first retry) will delay at most 40ms

The maximum number of attempts to make after the first request fails. This only takes effect if maxRetries < pool size.

These options are passed directly to the underlying Agents used in the pool. This is nice for passing options like cert and key that are required for client certificates.

When an endpoint is unresponsive the pool will not use it for requests. The ping url gives a downed endpoint a way to rejoin the pool. If an endpoint is marked unhealthy and a ping url is given, the endpoint will make requests to its ping url until it gets a 200 response, based on the resolution time.

If the ping url is undefined, the endpoint will never be marked unhealthy.

An http request. The pool sends the request to one of it's endpoints. If it fails, the pool may retry the request on other endpoints until it succeeds or reaches options.attempts number of tries. When data is a Stream, only 1 attempt will be made

The first argument may be a url path. If the callback has 3 arguments the full response body will be returned

pool.request('/users/me', function (error, response, body) {})

The first argument may be an options object. Here's the default values:

pool.request(
  { path: undefined        // the request path (required)
  , method: 'GET'
  , data: undefined        // request body, may be a string, buffer, or stream
  , headers: {}            // extra http headers to send
  , retryFilter: undefined // see below
  , attempts: pool.length  // or at least 2, at most options.maxRetries + 1
  , retryDelay: 20         // retries wait with exponential backoff times this number of ms
  , timeout: 60000         // ms to wait before timing out the request
  , encoding: 'utf8'       // response body encoding
  , stream: false          // stream instead of buffer response body
  }
  ,
  function (error, response, body) {}
)

The request body may be the second argument, instead of options.data (more useful with pool.post and pool.put)

pool.request(
  { path: '/foo' }
  , 'hi there'
  , function (error, response, body) {}
)

A callback with 2 arguments will stream the response and not buffer the response body.

pool.request('/foo', function (error, response) {
  response.pipe(somewhere)
})

Just a synonym for request

Same arguments as request that sets options.method = 'PUT'. Nice for putting :)

pool.put('/tweet/me', 'Hello World!', function (error, response) {})

Same arguments as request that sets options.method = 'POST'

Same arguments as request that sets options.method = 'DELETE'

Emits the request duration and options after each request

Emits the error of why a request is being retried

Emits the request when a request times out

Emits the endpoint when a node changes state between healthy/unhealthy