Bagofrequest NPM

Bag Of Request

Bag Of Request contains request utility functions.

bagofrequest#request

Send http request using mikeal/request, with the following additional features:

status code-based response handlers registration
wildcard status code support (e.g. 2xx, 50x)
unexpected status code error handling with request body included in message
request retry with increasing delay and maximum retries
proxy setting based on env vars http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY
proxy exclusion for localhost and 127.0.0.1
request timeout of 30 seconds
follow redirects
accepts self-signed SSL certificates
all of the above defaults can be overridden

bagofrequest#proxy

Proxy retrieval based on URL and environment variables:

if URL uses http, then sets proxy to http_proxy or HTTP_PROXY
if URL uses https, then sets proxy to htps_proxy or HTTPS_PROXY, otherwise fallback to http_proxy or HTTP_PROXY
if URL does not have a protocol, assume http protocol
if URL is not provided, then set proxy to http_proxy or HTTP_PROXY, otherwise fallback to https_proxy or HTTPS_PROXY
proxy will be ignored if host is on no_proxy or NO_PROXY when provided, otherwise ignore 127.0.0.1 and localhost

Installation

npm install bagofrequest

or as a dependency in package.json file:

"dependencies": {
  "bagofrequest": "x.y.z"
}

Usage

var bag = require('bagofrequest');

Request:

// send http get request with query strings, timeout, and specified status code-based handlers
bag.request('get', 'http://somehost', {
    queryStrings: {
      param1: 'value1',
      param2: 'value2'
    },
    timeout: 30000,
    handlers: {
      '2xx': function (result, cb) {
        cb(null, result.somedata);
      },
      404: function (result, cb) {
        cb(new Error('Item ' + result.itemId + ' cannot be found'));
      }
    }
  },
  function (err, result) {
    // response with unexpected status code (no registered handler) will be passed as error
  });

// send http post request
bag.request('post', 'http://somehost', {
    headers: {
      'content-type': 'application/json'
    },
    json: {
      prop1: 'value1',
      prop2: 'value2'
    }
  },
  function (err, result) {
  });

// send request with options to override any bagofrequest defaults (will be passed to mikeal/request)
bag.request('get', 'http://somehost', {
    requestOpts: {
      foo: 'bar'
    }
  },
  function (err, result) {
  });

// send request with retry settings
bag.request('get', 'http://somehost', {
    retry: {
      errorCodes: true, // retry on any error
      statusCodes: [404, 503], // retry when response status code is 404 or 503
      scale: 0.5, // increase delay by half on each retry
      delay: 1000, // wait 1 second before retrying
      maxRetries: 10 // only retry 10 times at most
    }
  },
  function (err, result) {
  });

// send request with custom proxy
bag.request('get', 'http://somehost', {
    proxy: 'http://user:pass@someproxy:1234'
  },
  function (err, result) {
  });

Proxy:

// get proxy based on URL protocol
// will return undefined when host is localhost or 127.0.0.1
var proxy = bag.proxy('https://somehost');

// get proxy with custom proxy exclusion
var proxy = bag.proxy('http://somelocalhost', {
  noProxyHosts: ['somelocalhost']
});