request-retry - HTTP(s) request retry on recoverable errors.
=========================================
When the connection fails with one of ECONNRESET
, ENOTFOUND
, ESOCKETTIMEDOUT
, ETIMEDOUT
, ECONNREFUSED
, EHOSTUNREACH
, EPIPE
, EAI_AGAIN
or when an HTTP 5xx error occurrs, the request will automatically be re-attempted as these are often recoverable errors and will go away on retry.
Usage
Request-retry is a drop-in replacement for request but adds two new options maxAttempts
and retryDelay
. It also adds one property to the response, attempts
. It supports callbacks or promises.
With callbacks
var request = ; ;
With promises
When you're using promises, you can pass the two following options:
fullResponse
(default true) - To resolve the promise with the full response or just the bodypromiseFactory
(default whenjs) - A function to allow the usage of a different promise implementation library
Using promiseFactory
option to use a different promise implementation library
// See the tests for different libraries usage examples /** * @param * @return */ { // With when.js return ; // With RSVP.js var Promise = Promise; return resolver;}
Installation
Install with npm.
npm install --save requestretry
How to define your own retry strategy
A retry strategy let you specify when request-retry should retry a request
/**
* @param {Null | Object} err
* @param {Object} response
* @param {Object} body
* @return {Boolean} true if the request should be retried
*/
function myRetryStrategy(err, response, body){
// retry the request if we had an error or if the response was a 'Bad Gateway'
return err || response.statusCode === 502;
}
request({
url: 'https://api.domain.com/v1/a/b'
json:true,
retryStrategy: myRetryStrategy
}, function(err, response, body){
// this callback will only be called when the request succeeded or after maxAttempts or on error
});
How to define your own delay strategy
A delay strategy let you specify how long request-retry should wait before trying again the request
/**
* @param {Null | Object} err
* @param {Object} response
* @param {Object} body
* @return {Number} number of milliseconds to wait before trying again the request
*/
function myDelayStrategy(err, response, body){
// set delay of retry to a random number between 500 and 3500 ms
return Math.floor(Math.random() * (3500 - 500 + 1) + 500);
}
request({
url: 'https://api.domain.com/v1/a/b'
json:true,
delayStrategy: myDelayStrategy // delayStrategy is called 1 less times than the maxAttempts set
}, function(err, response, body){
// this callback will only be called when the request succeeded or after maxAttempts or on error
});
request
options
Modifying You can use the defaults
method to provide default options like so:
var request = ;
API surface
As with request
, several helpers are provided for various HTTP methods and usage:
request(options [, callback])
.request(url [, callback])
- same asrequest(options [, callback])
.request(url, options [, callback])
- same asrequest(options [, callback])
.request.get(url [, callback])
- same asrequest(options [, callback])
, defaultsoptions.method
toGET
.request.get(url, options [, callback])
- same asrequest(options [, callback])
, defaultsoptions.method
toGET
.request.head(url)
- same asrequest(options [, callback])
, defaultsoptions.method
toHEAD
.request.post(url)
- same asrequest(options [, callback])
, defaultsoptions.method
toPOST
.request.put(url)
- same asrequest(options [, callback])
, defaultsoptions.method
toPUT
.request.patch(url)
- same asrequest(options [, callback])
, defaultsoptions.method
toPATCH
.request.del(url)
- same asrequest(options [, callback])
, defaultsoptions.method
toDELETE
.request.delete(url)
- same asrequest(options [, callback])
, defaultsoptions.method
toDELETE
.
Changelog
You want to support my work?
I maintain this project in my free time, if it helped you, well, I would be grateful to buy a beer thanks to your paypal or Bitcoins, donation!