bagofrequest

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']
});

Colophon

Developer's Guide

Build reports:

• Code complexity report
• Unit tests report
• Test coverage report
• Integration tests report
• API Documentation

Changelog

1.0.0