Network retries

README.md

@@ -62,8 +62,8 @@ const stripe = Stripe('sk_test_...');
 
 ### Usage with TypeScript
 
-Stripe does not currently maintain typings for this package, but there are 
-community typings available from DefinitelyTyped. 
+Stripe does not currently maintain typings for this package, but there are
+community typings available from DefinitelyTyped.
 
 To install:
 
@@ -145,6 +145,15 @@ if (process.env.http_proxy) {
 }
 ```
 
+### Network retries
+
+Automatic network retries can be enabled with `setMaxNetworkRetries`. This will retry requests `n` times with exponential backoff if they fail due to connection, conflict or rate limiting errors. [Idempotency keys](https://stripe.com/docs/api/idempotent_requests) are added where appropriate to prevent duplication.
+
+```js
+// Retry a request once before giving up
+stripe.setMaxNetworkRetries(1);
+```
+
 ### Examining Responses
 
 Some information about the response which generated a resource is available

lib/StripeResource.js

@@ -3,6 +3,7 @@
 var http = require('http');
 var https = require('https');
 var path = require('path');
+var uuid = require('uuid/v4');
 
 var utils = require('./utils');
 var Error = require('./Error');
@@ -182,7 +183,11 @@ StripeResource.prototype = {
     };
   },
 
-  _errorHandler: function(req, callback) {
+  _generateConnectionErrorMessage: function(requestRetries) {
+    return 'An error occurred with our connection to Stripe.' + (requestRetries > 0 ? ' Request was retried ' + requestRetries + ' times.' : '');
+  },
+
+  _errorHandler: function(req, requestRetries, callback) {
     var self = this;
     return function(error) {
       if (req._isAborted) {
@@ -192,14 +197,61 @@ StripeResource.prototype = {
       callback.call(
         self,
         new Error.StripeConnectionError({
-          message: 'An error occurred with our connection to Stripe',
+          message: self._generateConnectionErrorMessage(requestRetries),
           detail: error,
         }),
         null
       );
     }
   },
 
+  _shouldRetry: function(res, numRetries) {
+    // Do not retry if we are out of retries.
+    if (numRetries >= this._stripe.getMaxNetworkRetries()) {
+      return false;
+    }
+
+    // Retry on connection error.
+    if (!res) {
+      return true;
+    }
+
+    // Retry on conflict, rate limit, and availability errors.
+    if (res.statusCode === 409 || res.statusCode === 503) {
+      return true;
+    }
+
+    // Retry on 5xx's, except POST's, which our idempotency framework
+    // would just replay as 500's again anyway.
+    if (res.statusCode >= 500 && res.req._requestEvent.method !== 'POST') {
+      return true;
+    }
+
+    return false;
+  },
+
+  _getSleepTimeInMS: function(numRetries) {
+    var initialNetworkRetryDelay = this._stripe.getInitialNetworkRetryDelay();
+    var maxNetworkRetryDelay = this._stripe.getMaxNetworkRetryDelay();
+
+    // Apply exponential backoff with initialNetworkRetryDelay on the
+    // number of numRetries so far as inputs. Do not allow the number to exceed
+    // maxNetworkRetryDelay.
+    var sleepSeconds = Math.min(
+      initialNetworkRetryDelay * Math.pow(numRetries - 1, 2),
+      maxNetworkRetryDelay
+    );
+
+    // Apply some jitter by randomizing the value in the range of
+    // (sleepSeconds / 2) to (sleepSeconds).
+    sleepSeconds *= 0.5 * (1 + Math.random());
+
+    // But never sleep less than the base sleep seconds.
+    sleepSeconds = Math.max(initialNetworkRetryDelay, sleepSeconds);
+
+    return sleepSeconds * 1000;
+  },
+
   _defaultHeaders: function(auth, contentLength, apiVersion) {
     var userAgentString = 'Stripe/v1 NodeBindings/' + this._stripe.getConstant('PACKAGE_VERSION');
 
@@ -258,7 +310,19 @@ StripeResource.prototype = {
       makeRequestWithData(null, utils.stringifyRequestData(data || {}));
     }
 
-    function makeRequest(apiVersion, headers) {
+    function retryRequest(requestFn, apiVersion, headers, requestRetries) {
+      requestRetries += 1;
+
+      return setTimeout(
+        requestFn,
+        self._getSleepTimeInMS(requestRetries),
+        apiVersion,
+        headers,
+        requestRetries
+      );
+    }
+
+    function makeRequest(apiVersion, headers, numRetries) {
       var timeout = self._stripe.getApiField('timeout');
       var isInsecureConnection = self._stripe.getApiField('protocol') == 'http';
 
@@ -274,6 +338,14 @@ StripeResource.prototype = {
         ciphers: 'DEFAULT:!aNULL:!eNULL:!LOW:!EXPORT:!SSLv2:!MD5',
       });
 
+      // If this is a POST and we allow multiple retries, set a idempotency key if one is not
+      // already provided.
+      if (method === 'POST' && self._stripe.getMaxNetworkRetries() > 0) {
+        if (!headers.hasOwnProperty('Idempotency-Key')) {
+          headers['Idempotency-Key'] = uuid();
+        }
+      }
+
       var requestEvent = utils.removeEmpty({
         api_version: apiVersion,
         account: headers['Stripe-Account'],
@@ -282,15 +354,31 @@ StripeResource.prototype = {
         path: path,
       });
 
+      var requestRetries = numRetries || 0;
+
       req._requestEvent = requestEvent;
 
       req._requestStart = Date.now();
 
       self._stripe._emitter.emit('request', requestEvent);
 
       req.setTimeout(timeout, self._timeoutHandler(timeout, req, callback));
-      req.on('response', self._responseHandler(req, callback));
-      req.on('error', self._errorHandler(req, callback));
+
+      req.on('response', function(res) {
+        if (self._shouldRetry(res, requestRetries)) {
+          return retryRequest(makeRequest, apiVersion, headers, requestRetries);
+        } else {
+          return self._responseHandler(req, callback)(res);
+        }
+      });
+
+      req.on('error', function(error) {
+        if (self._shouldRetry(null, requestRetries)) {
+          return retryRequest(makeRequest, apiVersion, headers, requestRetries);
+        } else {
+          return self._errorHandler(req, requestRetries, callback)(error);
+        }
+      });
 
       req.on('socket', function(socket) {
         if (socket.connecting) {
@@ -307,7 +395,6 @@ StripeResource.prototype = {
       });
     }
   },
-
 };
 
 module.exports = StripeResource;

lib/stripe.js

@@ -21,6 +21,9 @@ Stripe.USER_AGENT = {
 
 Stripe.USER_AGENT_SERIALIZED = null;
 
+Stripe.MAX_NETWORK_RETRY_DELAY_SEC = 2;
+Stripe.INITIAL_NETWORK_RETRY_DELAY_SEC = 0.5;
+
 var APP_INFO_PROPERTIES = ['name', 'version', 'url', 'partner_id'];
 
 var EventEmitter = require('events').EventEmitter;
@@ -142,6 +145,7 @@ function Stripe(key, version) {
     timeout: Stripe.DEFAULT_TIMEOUT,
     agent: null,
     dev: false,
+    maxNetworkRetries: 0,
   };
 
   this._prepResources();
@@ -247,6 +251,26 @@ Stripe.prototype = {
     return Stripe[c];
   },
 
+  getMaxNetworkRetries: function() {
+    return this.getApiField('maxNetworkRetries');
+  },
+
+  setMaxNetworkRetries: function(maxNetworkRetries) {
+    if ((maxNetworkRetries && typeof maxNetworkRetries !== 'number') || arguments.length < 1) {
+      throw new Error('maxNetworkRetries must be a number.');
+    }
+
+    this._setApiField('maxNetworkRetries', maxNetworkRetries);
+  },
+
+  getMaxNetworkRetryDelay: function() {
+    return this.getConstant('MAX_NETWORK_RETRY_DELAY_SEC');
+  },
+
+  getInitialNetworkRetryDelay: function() {
+    return this.getConstant('INITIAL_NETWORK_RETRY_DELAY_SEC');
+  },
+
   // Gets a JSON version of a User-Agent and uses a cached version for a slight
   // speed advantage.
   getClientUserAgent: function(cb) {

package.json

@@ -32,12 +32,14 @@
     "eslint": "^4.19.1",
     "eslint-plugin-chai-friendly": "^0.4.0",
     "mocha": "~5.0.5",
+    "nock": "^9.0.0",
     "nyc": "^11.3.0"
   },
   "dependencies": {
     "lodash.isplainobject": "^4.0.6",
     "qs": "~6.5.1",
-    "safe-buffer": "^5.1.1"
+    "safe-buffer": "^5.1.1",
+    "uuid": "^3.3.2"
   },
   "license": "MIT",
   "scripts": {