Merge pull request #150 from glynnbird/plugin

Plugin support

Author: glynnbird

README.md

@@ -8,6 +8,7 @@ This is the official Cloudant library for Node.js.
   * [Callback Signature](#callback-signature)
   * [Password Authentication](#password-authentication)
   * [Cloudant Local](#cloudant-local)
+  * [Request Plugins](#request-plugins)
 * [API Reference](#api-reference)
 * [Authorization and API Keys](#authorization-and-api-keys)
   * [Generate an API key](#generate-an-api-key)
@@ -206,6 +207,69 @@ Cloudant({hostname:"companycloudant.local", username:"somebody", password:"someb
 })
 ~~~
 
+### Request Plugins
+
+This library can be used with one of three `request` plugins:
+
+1. `default` - the default [request](https://www.npmjs.com/package/request) library plugin. This uses Node.js's callbacks to communicate Cloudant's replies 
+back to your app and can be used to stream data using the Node.js [Stream API](https://nodejs.org/api/stream.html).
+2. `promises` - if you'd prefer to write code in the Promises style then the "promises" plugin turns each request into a Promise. This plugin cannot be used 
+stream data because instead of returning the HTTP request, we are simply returning a Promise instead.
+3. `retry` - on occasion, Cloudant's multi-tenant offerring may reply with an HTTP 429 response because you've exceed the number of API requests in a given amount of time. 
+The "retry" plugin will automatically retry your request with exponential back-off.
+4. custom plugin - you may also supply your own function which will be called to make API calls.
+
+#### The 'promises' Plugins
+
+When initialising the Cloudant library, you can opt to use the 'promises' plugin:
+
+```js
+var cloudant = Cloudant({url: myurl, plugin:'promises'});
+var mydb = cloudant.db.use('mydb');
+```
+
+Then the library will return a Promise for every asynchronous call:
+
+```js
+mydb.list().then(function(data) {
+  console.log(data);
+}).catch(function(err) {
+  console.log('something went wrong', err);
+});
+```
+
+#### The 'retry' plugin
+
+When initialising the Cloudant library, you can opt to use the 'retry' plugin:
+
+```js
+var cloudant = Cloudant({url: myurl, plugin:'retry'});
+var mydb = cloudant.db.use('mydb');
+```
+
+Then use the Cloudant library normally. You may also opt to configure the retry parameters:
+
+- retryAttempts - the maximum number of times the request will be attempted (default 3)
+- retryTimeout - the number of milliseconds after the first attempt that the second request will be tried; the timeout doubling with each subsequent attempt  (default 500)
+
+```js
+var cloudant = Cloudant({url: myurl, plugin:'retry', retryAttempts:5, retryTimeout:1000 });
+var mydb = cloudant.db.use('mydb');
+```
+
+#### Custom plugin
+
+When initialising the Cloudant library, you can supply your own plugin function:
+
+```js  
+  var doNothingPlugin = function(opts, callback) {
+    // don't do anything, just pretend that everything's ok.
+    callback(null, { statusCode:200 }, { ok: true});
+  };
+  var cloudant = Cloudant({url: myurl, plugin: doNothingPlugin});
+```
+
+Whenever the Cloudant library wishes to make an outgoing HTTP request, it will call your function instead of `request`. 
 
 ## API Reference
 

cloudant.js

@@ -25,39 +25,53 @@ var nanodebug = require('debug')('nano');
 var reconfigure = require('./lib/reconfigure.js')
 
 // This IS the Cloudant API. It is mostly nano, with a few functions.
-function Cloudant(credentials, callback) {
-  debug('Initialize', credentials);
+function Cloudant(options, callback) {
+  debug('Initialize', options);
 
   // Save the username and password for potential conversion to cookie auth.
-  var login = reconfigure.getCredentials(credentials);
+  var login = reconfigure.getOptions(options);
 
   // Convert the credentials into a URL that will work for cloudant. The
   // credentials object will become squashed into a string, which is fine
   // except for the .cookie option.
-  var cookie = credentials.cookie;
+  var cookie = options.cookie;
 
   var pkg = require('./package.json');
   var useragent = "nodejs-cloudant/" + pkg.version + " (Node.js " + process.version + ")";
   var requestDefaults = { headers: { "User-agent": useragent}, gzip:true  };
-  if (typeof credentials == "object") {
-    if (credentials.requestDefaults) {
-      requestDefaults = credentials.requestDefaults;
-      delete credentials.requestDefaults;
+  var theurl = null;
+  if (typeof options == "object") {
+    if (options.requestDefaults) {
+      requestDefaults = options.requestDefaults;
+      delete options.requestDefaults;
     }
-    credentials = reconfigure(credentials);
+    theurl = reconfigure(options);
   } else {
-    credentials = reconfigure({ url: credentials})
+    theurl = reconfigure({ url: options})
   }
 
   // keep connections alive by default
   if (requestDefaults && !requestDefaults.agent) {
-    var protocol = (credentials.match(/^https/))? require('https') : require('http');
+    var protocol = (theurl.match(/^https/))? require('https') : require('http');
     var agent = new protocol.Agent({ keepAlive:true });
     requestDefaults.agent = agent;
   } 
 
-  debug('Create underlying Nano instance, credentials=%j requestDefaults=%j', credentials, requestDefaults);
-  var nano = Nano({url:credentials, requestDefaults: requestDefaults, cookie: cookie, log: nanodebug});
+  // plugin a request library
+  var plugin = null;
+  if (options.plugin) {
+    if(typeof options.plugin === 'string') {
+      var plugintype = options.plugin || 'default';
+      debug('Using the "' + plugintype + '" plugin');
+      plugin =  require('./plugins/' + plugintype)(options);
+    } else if (typeof options.plugin === 'function') { 
+      debug('Using a custom plugin');
+      plugin = options.plugin;
+    }
+  }
+
+  debug('Create underlying Nano instance, options=%j requestDefaults=%j', options, requestDefaults);
+  var nano = Nano({url:theurl, request: plugin, requestDefaults: requestDefaults, cookie: cookie, log: nanodebug});
 
   // our own implementation of 'use' e.g. nano.use or nano.db.use
   // it includes all db-level functions

lib/reconfigure.js

@@ -47,9 +47,9 @@ module.exports = function(config) {
     if (match)
       config.account = match[1];
 
-    var credentials = getCredentials(config);
-    var username = credentials.username;
-    var password = credentials.password;
+    var options = getOptions(config);
+    var username = options.username;
+    var password = options.password;
 
     // Configure for Cloudant, either authenticated or anonymous.
     if (config.account && password) {
@@ -76,8 +76,8 @@ module.exports = function(config) {
   return outUrl;
 };
 
-module.exports.getCredentials = getCredentials;
-function getCredentials(config) {
+module.exports.getOptions = getOptions;
+function getOptions(config) {
   // The username is the account ("foo" for "foo.cloudant.com")
   // or the third-party API key.
   var result = {password:config.password, username: config.key || config.username || config.account};

package.json

@@ -17,8 +17,10 @@
     "database"
   ],
   "dependencies": {
+    "async": "^2.0.1",
     "debug": "2.2.0",
-    "nano": "6.2.0"
+    "nano": "6.2.0",
+    "request": "^2.53.0"
   },
   "devDependencies": {
     "dotenv": "1.2.0",

plugins/default.js

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2015 IBM Cloudant, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+
+// this the the 'default' request handler.
+// It is simply an instance of the popular 'request' npm module.
+// This is the simplest module to use as it supports JavaScript callbacks
+// and can be used for with the Node.js streaming API.
+
+module.exports = function(options) {
+  var requestDefaults = options.requestDefaults || {jar: false};
+  return require('request').defaults(requestDefaults);
+}

plugins/promises.js

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2015 IBM Cloudant, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+
+// this the the 'promises' request handler.
+// It is a function that returns a Promise and resolves the promise on success 
+// or rejects the Promise on failure
+
+var nullcallback = function() {};
+
+module.exports = function(options) {
+
+  var requestDefaults = options.requestDefaults || {jar: false};
+  var request = require('request').defaults(requestDefaults);
+  var myrequest = function(req, callback) {
+    if (typeof callback !== 'function') {
+      callback = nullcallback;
+    }
+    return new Promise(function(resolve, reject) {
+      request(req, function(err, h, b) {
+        var statusCode = h && h.statusCode || 500;
+        if (statusCode >= 200 && statusCode < 400) {
+          callback(null, h, b);
+          return resolve(b);
+        }
+        reject(err || b);
+        callback(err, h, b);
+      })
+    });
+  };
+
+  return myrequest;
+};
+    
+    

plugins/retry.js

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2015 IBM Cloudant, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+
+// this the the 'retry' request handler.
+// If CouchDB/Cloudant responds with a 429 HTTP code
+// the library will retry the request up to three
+// times with exponential backoff.
+// This module is unsuitable for streaming requests.
+var async = require('async');
+var debug = require('debug')('cloudant');
+
+module.exports = function(options) {
+  var requestDefaults = options.requestDefaults || {jar: false};
+  var request = require('request').defaults(requestDefaults);
+
+  var myrequest = function(req, callback) {
+    var attempts = 0;
+    var maxAttempts = options.retryAttempts || 3;
+    var firstTimeout = options.retryTimeout || 500; // ms
+    var timeout = 0; // ms
+    var statusCode = null;
+
+    // do the first function until the second function returns true
+    async.doUntil(function(done) {
+      attempts++;
+      if (attempts > 1) {
+        debug('attempt', attempts, 'timeout', timeout);
+      }
+      setTimeout(function() {
+        request(req, function(e, h, b) {
+          statusCode = h && h.statusCode || 500;
+          done(null, [e, h, b]);
+        });  
+      }, timeout);
+    }, function() {
+      // this function returns false for the first 'maxAttempts' 429s receieved
+      if (statusCode === 429 && attempts < maxAttempts) {
+        if (attempts === 1) {
+          timeout = firstTimeout;
+        } else {
+          timeout *= 2;
+        }
+        return false;
+      } 
+      return true;
+    }, function(e, results) {
+      callback(results[0], results[1], results[2])
+    });
+  };
+
+  return myrequest;
+};
+    
+    
+