Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Branch: master
Fetching contributors…

Cannot retrieve contributors at this time

259 lines (187 sloc) 6.6 KB


HTTP pool and load balancer for node.

Build Status


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

var servers =

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

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

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




var Pool = require('poolee')

var pool = new Pool(
  http                     // the http module to use (require('http') or require('https'))
  [ ""       // array of endpoints in "host:port" form
  , ""
  ,                        // options
  { maxPending: 1000       // maximum number of outstanding request to allow
  , maxSockets: 20         // 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 a 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:

  { 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 (more useful with and pool.put)

  { 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) {


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'


Adds a node to the pool given its hostname as a string. The node will start in the healthy state.



Removes a node to the pool given its hostname as a string. Note that in the case of hosts with duplicate names, all instances of the specified name will be removed from the pool.




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

Jump to Line
Something went wrong with that request. Please try again.