follow-redirects 0.0.3 → 0.0.7

package/README.md

@@ -1,35 +1,23 @@
-`follow-redirects` extends http and https with the ability to follow
-HTTP redirects painlessly. It does not modify the native modules but
-instead offers its own http/https modules which inherit from the native
-modules. If you want to automatically follow redirects, all you need to
-do is replace: 
+## Follow Redirects
 
-```javascript
-var http = require('http');
-```
-
-by
-
-```javascript
-var http = require('follow-redirects').http;
-```
+Drop in replacement for Nodes `http` and `https` that automatically follows redirects.
 
-# Install
+[![Build Status](https://travis-ci.org/olalonde/follow-redirects.svg?branch=master)](https://travis-ci.org/olalonde/follow-redirects)
+[![Coverage Status](https://coveralls.io/repos/olalonde/follow-redirects/badge.svg?branch=master)](https://coveralls.io/r/olalonde/follow-redirects?branch=master)
+[![Code Climate](https://codeclimate.com/github/olalonde/follow-redirects/badges/gpa.svg)](https://codeclimate.com/github/olalonde/follow-redirects)
+[![Dependency Status](https://david-dm.org/olalonde/follow-redirects.svg)](https://david-dm.org/olalonde/follow-redirects)
+[![devDependency Status](https://david-dm.org/olalonde/follow-redirects/dev-status.svg)](https://david-dm.org/olalonde/follow-redirects#info=devDependencies)
 
-    npm install follow-redirects
+[![NPM](https://nodei.co/npm/follow-redirects.png?downloads=true)](https://nodei.co/npm/follow-redirects/)
 
-# Usage
+`follow-redirects` provides [request](https://nodejs.org/api/http.html#http_http_request_options_callback) and [get](https://nodejs.org/api/http.html#http_http_get_options_callback)
+ methods that behave identically to those found on the native [http](https://nodejs.org/api/http.html#http_http_request_options_callback) and [https](https://nodejs.org/api/https.html#https_https_request_options_callback)
+ modules, with the exception that they will seamlessly follow redirects.
 
 ```javascript
-
 var http = require('follow-redirects').http;
 var https = require('follow-redirects').https;
 
-/* 
- * http and https are just like Node.js' http and https modules except 
- * that they follow redirects seamlessly. 
- */
-
 http.get('http://bit.ly/900913', function (res) {
   res.on('data', function (chunk) {
     console.log(chunk);
@@ -37,21 +25,88 @@ http.get('http://bit.ly/900913', function (res) {
 }).on('error', function (err) {
   console.error(err);
 });
+```
+
+By default the number of redirects is limited to 5, but you can modify that globally or per request.
 
-/*
- * You can optionnally pass the maxRedirect option which defaults to 5
- */
+```javascript
+require('follow-redirects').maxRedirects = 10;   // Has global affect (be careful!)
 
 https.request({
   host: 'bitly.com',
   path: '/UHfDGO',
-  maxRedirects: 3
+  maxRedirects: 3   // per request setting
+}, function (res) {/* ... */});
+```
+
+You can inspect the redirection chain from the `fetchedUrls` array on the `response`.
+The array is populated in reverse order, so the original url you requested will be the
+last element, while the final redirection point will be at index 0.
+
+```javascript
+https.request({
+  host: 'bitly.com',
+  path: '/UHfDGO',
 }, function (res) {
-  res.on('data', function (chunk) {
-    console.log(chunk);
-  });
-}).on('error', function (err) {
-  console.error(err);
+  console.log(res.fetchedUrls);
+  // [ 'http://duckduckgo.com/robots.txt',  'http://bitly.com/UHfDGO' ]
 });
+```
+
+## Browserify Usage
+
+Due to the way `XMLHttpRequest` works, the `browserify` versions of `http` and `https` already follow redirects.
+ If you are *only* targetting the browser, then this library has little value for you. If you want to write cross
+ platform code for node and the browser, `follow-redirects` provides a great solution for making the native node
+ modules behave the same as they do in browserified builds in the browser. To avoid bundling unnecessary code
+ you should tell browserify to swap out `follow-redirects` with the standard modules when bundling.
+ To make this easier, you need to change how you require the modules:
+
+```javascript
+var http = require('follow-redirects/http');
+var https = require('follow-redirects/https');
+```
+
+You can then replace `follow-redirects` in your browserify configuration like so:
+
+```javascript
+"browser": {
+  "follow-redirects/http"  : "http",
+  "follow-redirects/https" : "https"
+}
+```
 
+The `browserify-http` module has not kept pace with node development, and no long behaves identically to the native
+ module when running in the browser. If you are experiencing problems, you may want to check out
+ [browserify-http-2](https://www.npmjs.com/package/http-browserify-2). It is more actively maintained and
+ attempts to address a few of the shortcomings of `browserify-http`. In that case, your browserify config should
+ look something like this:
+
+```javascript
+"browser": {
+  "follow-redirects/http"  : "browserify-http-2/http",
+  "follow-redirects/https" : "browserify-http-2/https"
+}
 ```
+
+## Contributing
+
+Pull Requests are always welcome. Please [file an issue](https://github.com/olalonde/follow-redirects/issues)
+ detailing your proposal before you invest your valuable time. Additional features and bug fixes should be accompanied
+ by tests. You can run the test suite locally with a simple `npm test` command.
+
+## Debug Logging
+
+`follow-redirects` uses the excellent [debug](https://www.npmjs.com/package/debug) for logging. To turn on logging
+ set the environment variable `DEBUG=follow-redirects` for debug output from just this module. When running the test
+ suite it is sometimes advantageous to set `DEBUG=*` to see output from the express server as well.
+
+## Authors
+
+Olivier Lalonde (olalonde@gmail.com)
+
+James Talmage (james@talmage.io)
+
+## License
+
+MIT: [http://olalonde.mit-license.org](http://olalonde.mit-license.org)

package/create.js

@@ -0,0 +1,162 @@
+'use strict';
+var url = require('url');
+var debug = require('debug')('follow-redirects');
+var assert = require('assert');
+var consume = require('stream-consume');
+
+module.exports = function(_nativeProtocols) {
+  var nativeProtocols = {};
+
+  var publicApi = {
+    maxRedirects: 5
+  };
+
+  for (var p in _nativeProtocols) {
+    /* istanbul ignore else */
+    if (_nativeProtocols.hasOwnProperty(p)) {
+      // http://www.ietf.org/rfc/rfc2396.txt - Section 3.1
+      assert(/^[A-Z][A-Z\+\-\.]*$/i.test(p), JSON.stringify(p) + ' is not a valid scheme name');
+      generateWrapper(p, _nativeProtocols[p]);
+    }
+  }
+
+  return publicApi;
+
+  function execute(options) {
+    var clientRequest;
+    var fetchedUrls = [];
+
+    return (clientRequest = cb());
+
+    function cb(res) {
+      // skip the redirection logic on the first call.
+      if (res) {
+        var fetchedUrl = url.format(options);
+        fetchedUrls.unshift(fetchedUrl);
+
+        if (!isRedirect(res)) {
+          res.fetchedUrls = fetchedUrls;
+          return options.userCallback(res);
+        }
+
+        // we are going to follow the redirect, but in node 0.10 we must first attach a data listener
+        // to consume the stream and send the 'end' event
+        consume(res);
+
+        // need to use url.resolve() in case location is a relative URL
+        var redirectUrl = url.resolve(fetchedUrl, res.headers.location);
+        debug('redirecting to', redirectUrl);
+
+        // clean all the properties related to the old url away, and copy from the redirect url
+        wipeUrlProps(options);
+        extend(options, url.parse(redirectUrl));
+      }
+
+      if (fetchedUrls.length > options.maxRedirects) {
+        var err = new Error('Max redirects exceeded.');
+        return forwardError(err);
+      }
+
+      options.nativeProtocol = nativeProtocols[options.protocol];
+      options.defaultRequest = defaultMakeRequest;
+
+      var req = (options.makeRequest || defaultMakeRequest)(options, cb, res);
+
+      if (res) {
+        req.on('error', forwardError);
+      }
+      return req;
+    }
+
+    function defaultMakeRequest(options, cb, res) {
+      if (res) {
+        // This is a redirect, so use only GET methods
+        options.method = 'GET';
+      }
+
+      var req = options.nativeProtocol.request(options, cb);
+
+      if (res) {
+        // We leave the user to call `end` on the first request
+        req.end();
+      }
+
+      return req;
+    }
+
+    // bubble errors that occur on the redirect back up to the initiating client request
+    // object, otherwise they wind up killing the process.
+    function forwardError (err) {
+      clientRequest.emit('error', err);
+    }
+  }
+
+  function generateWrapper (scheme, nativeProtocol) {
+    var wrappedProtocol = scheme + ':';
+    var H = function() {};
+    H.prototype = nativeProtocols[wrappedProtocol] = nativeProtocol;
+    H = new H();
+    publicApi[scheme] = H;
+
+    H.request = function(options, callback) {
+      return execute(parseOptions(options, callback, wrappedProtocol));
+    };
+
+    // see https://github.com/joyent/node/blob/master/lib/http.js#L1623
+    H.get = function(options, callback) {
+      options = parseOptions(options, callback, wrappedProtocol);
+      var req = execute(options);
+      req.end();
+      return req;
+    };
+  }
+
+  // returns a safe copy of options (or a parsed url object if options was a string).
+  // validates that the supplied callback is a function
+  function parseOptions (options, callback, wrappedProtocol) {
+    assert.equal(typeof callback, 'function', 'callback must be a function');
+    if ('string' === typeof options) {
+      options = url.parse(options);
+      options.maxRedirects = publicApi.maxRedirects;
+    } else {
+      options = extend({
+        maxRedirects: publicApi.maxRedirects,
+        protocol: wrappedProtocol
+      }, options);
+    }
+    assert.equal(options.protocol, wrappedProtocol, 'protocol mismatch');
+    options.protocol = wrappedProtocol;
+    options.userCallback = callback;
+
+    debug('options', options);
+    return options;
+  }
+};
+
+// copies source's own properties onto destination and returns destination
+function extend(destination, source) {
+  for (var i in source) {
+    if (source.hasOwnProperty(i)) {
+      destination[i] = source[i];
+    }
+  }
+  return destination;
+}
+
+// to redirect the result must have
+// a statusCode between 300-399
+// and a `Location` header
+function isRedirect (res) {
+  return (res.statusCode >= 300 && res.statusCode <= 399 &&
+  'location' in res.headers);
+}
+
+// nulls all url related properties on the object.
+// required on node <10
+function wipeUrlProps(options) {
+  for (var i = 0, l = urlProps.length; i < l; ++i) {
+    options[urlProps[i]] = null;
+  }
+}
+var urlProps = ['protocol', 'slashes', 'auth', 'host', 'port', 'hostname',
+  'hash', 'search', 'query', 'pathname', 'path', 'href'];

package/http.js

@@ -0,0 +1 @@
+module.exports = require('./').http;

package/https.js

@@ -0,0 +1 @@
+module.exports = require('./').https;

package/index.js

@@ -1,109 +1,4 @@
-var nativeHttps = require('https'),
-  nativeHttp = require('http'),
-  url = require('url'),
-  _ = require('underscore');
-
-var maxRedirects = module.exports.maxRedirects = 5;
-
-var protocols = {
-  https: nativeHttps,
-  http: nativeHttp
-};
-
-// Only use GETs on redirects
-for (var protocol in protocols) {
-  // h is either our cloned http or https object
-  var h =  function() {};
-  h.prototype = protocols[protocol];
-  h = new h();
-
-  module.exports[protocol] = h;
-
-  h.request = function (h) {
-    return function (options, callback, redirectOptions) {
-
-      redirectOptions = redirectOptions || {};
-
-      var max = (typeof options === 'object' && 'maxRedirects' in options) ? options.maxRedirects : exports.maxRedirects;
-
-      var redirect = _.extend({
-        count: 0,
-        max: max,
-        clientRequest: null,
-        userCallback: callback
-      }, redirectOptions);
-
-      //console.log(redirect.count);
-      //console.log(redirect.max);
-      /**
-       * Emit error if too many redirects
-       */
-      if (redirect.count > redirect.max) {
-        var err = new Error('Max redirects exceeded. To allow more redirects, pass options.maxRedirects property.');
-        redirect.clientRequest.emit('error', err);
-        return redirect.clientRequest;
-      }
-
-      redirect.count++;
-
-      /**
-       * Parse URL from options
-       */
-      var reqUrl;
-      if (typeof options === 'string') {
-        reqUrl = options;
-      }
-      else {
-        reqUrl = url.format(_.extend({ protocol: protocol }, options));
-      }
-
-      /*
-       * Build client request
-       */
-      var clientRequest = h.__proto__.request(options, redirectCallback(reqUrl, redirect));
-
-      // Save user's clientRequest so we can emit errors later
-      if (!redirect.clientRequest) redirect.clientRequest = clientRequest;
-
-      /**
-       * ClientRequest callback for redirects
-       */
-      function redirectCallback (reqUrl, redirect) {
-        return function (res) {
-          // status must be 300-399 for redirects
-          if (res.statusCode < 300 || res.statusCode > 399) {
-            //console.log('[' + res.statusCode + '] callback user on url ' + reqUrl);
-            return redirect.userCallback(res);
-          }
-
-          // no `Location:` header => nowhere to redirect
-          if (!('location' in res.headers)) {
-            //console.log('[no location header] callback user on url ' + reqUrl);
-            return redirect.userCallback(res);
-          }
-
-          // save the original clientRequest to our redirectOptions so we can emit errors later
-
-          // need to use url.resolve() in case location is a relative URL
-          var redirectUrl = url.resolve(reqUrl, res.headers['location']);
-          // we need to call the right api (http vs https) depending on protocol
-          var proto = url.parse(redirectUrl).protocol;
-          proto = proto.substr(0, proto.length - 1);
-          //console.log('Redirecting from ' + reqUrl + ' to ' + redirectUrl);
-          return module.exports[proto].get(redirectUrl, redirectCallback(reqUrl, redirect), redirect);
-        };
-      }
-
-      return clientRequest;
-    }
-  }(h);
-
-  // see https://github.com/joyent/node/blob/master/lib/http.js#L1623
-  h.get = function (h) {
-    return function (options, cb, redirectOptions) {
-      var req = h.request(options, cb, redirectOptions);
-      req.end();
-      return req;
-    };
-  }(h);
-}
+module.exports = require('./create')({
+  'http': require('http'),
+  'https': require('https')
+});

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "follow-redirects",
-  "version": "0.0.3",
+  "version": "0.0.7",
   "description": "HTTP and HTTPS modules that follow redirects.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "npm run cover && npm run lint && npm run style",
+    "lint": "jshint *.js test/*.js test/**/*.js",
+    "style": "jscs *.js && jscs test/*.js test/**/*.js --config=test/.jscsrc",
+    "cover": "BLUEBIRD_DEBUG=1 istanbul cover ./node_modules/.bin/_mocha",
+    "debug": "BLUEBIRD_DEBUG=1 mocha"
   },
   "repository": {
     "type": "git",
     "url": "git@github.com:olalonde/follow-redirects.git"
   },
-  "homepage": "",
+  "homepage": "https://github.com/olalonde/follow-redirects",
+  "bugs": {
+    "url": "https://github.com/olalonde/follow-redirects/issues"
+  },
   "keywords": [
     "http",
     "https",
@@ -21,15 +28,33 @@
     "utility"
   ],
   "author": {
-    "name": "Olivier Lalonde"
-    , "email": "olalonde@gmail.com"
-    , "url": "http://www.syskall.com"
+    "name": "Olivier Lalonde",
+    "email": "olalonde@gmail.com",
+    "url": "http://www.syskall.com"
   },
+  "contributors": [
+    "James Talmage <james@talmage.io>"
+  ],
+  "files": [
+    "index.js",
+    "create.js",
+    "http.js",
+    "https.js"
+  ],
   "dependencies": {
-    "underscore": ""
+    "debug": "^2.2.0",
+    "stream-consume": "^0.1.0"
   },
   "devDependencies": {
-    "colors": ""
+    "bluebird": "^2.9.30",
+    "concat-stream": "^1.5.0",
+    "coveralls": "^2.11.2",
+    "express": "^4.13.0",
+    "istanbul": "^0.3.17",
+    "jscs": "^1.13.1",
+    "jshint": "^2.8.0",
+    "mocha": "^2.2.5",
+    "semver": "~4.3.6"
   },
-  "license": "BSD"
+  "license": "MIT"
 }

package/.npmignore

@@ -1,15 +0,0 @@
-lib-cov
-*.seed
-*.log
-*.csv
-*.dat
-*.out
-*.pid
-*.gz
-
-pids
-logs
-results
-
-node_modules
-npm-debug.log

package/test/index.js

@@ -1,82 +0,0 @@
-var https = require('../').https,
-  http = require('../').http,
-  nativeHttps = require('https'),
-  nativeHttp = require('http');
-
-require('colors');
-
-var urls = [
-  'http://bit.ly/900913'
-  /*,
-  {
-    type: 'https',
-    host: 'bitly.com',
-    path: '/UHfDGO',
-    maxRedirects: 10
-  }
- */
-];
-
-require('../').maxRedirects = 6;
-
-
-var libs = {
-  http: {
-    //native: nativeHttp,
-    follow: http
-  },
-  https: {
-    //native: nativeHttps,
-    follow: https
-  }
-};
-
-urls.forEach(function (url) {
-
-  var proto = 'http';
-  if (typeof url === 'string' && url.substr(0, 5) === 'https') {
-      proto = 'https';
-  }
-  else if (url.type === 'https') {
-      proto = 'https';
-  }
-  for (var key in libs[proto]) {
-    var lib = libs[proto][key];
-    /**
-     * Test .get
-     */
-    console.log((proto + '.' + 'get(' + url + ')').blue);
-    lib.get(url, function(res) {
-      //console.log('statusCode: ', res.statusCode);
-      //console.log('headers: ', res.headers);
-
-      res.on('data', function(d) {
-        console.log(('Data received ').red);
-        console.log(d.toString());
-      });
-
-    }).on('error', function(e) {
-      console.error(e);
-    });
-
-    /**
-     * Test .request
-     */
-    console.log((proto + '.' + 'request(' + url + ')').blue);
-    var request = http.request;
-    var req = request(url, function(res) {
-      //console.log('STATUS: ' + res.statusCode);
-      //console.log('HEADERS: ' + JSON.stringify(res.headers));
-      res.setEncoding('utf8');
-      res.on('data', function (chunk) {
-        console.log('BODY: ' + chunk);
-      });
-    });
-
-    req.on('error', function(e) {
-      console.log('problem with request: ' + e.message);
-    });
-
-    req.end();
-  };
-});