follow-redirects 0.0.7 → 1.0.0

package/README.md

@@ -1,7 +1,8 @@
 ## Follow Redirects
 
-Drop in replacement for Nodes `http` and `https` that automatically follows redirects.
+Drop-in replacement for Nodes `http` and `https` that automatically follows redirects.
 
+[![npm version](https://badge.fury.io/js/follow-redirects.svg)](https://www.npmjs.com/package/follow-redirects)
 [![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)
@@ -18,8 +19,8 @@ Drop in replacement for Nodes `http` and `https` that automatically follows redi
 var http = require('follow-redirects').http;
 var https = require('follow-redirects').https;
 
-http.get('http://bit.ly/900913', function (res) {
-  res.on('data', function (chunk) {
+http.get('http://bit.ly/900913', function (response) {
+  response.on('data', function (chunk) {
     console.log(chunk);
   });
 }).on('error', function (err) {
@@ -27,36 +28,58 @@ http.get('http://bit.ly/900913', function (res) {
 });
 ```
 
-By default the number of redirects is limited to 5, but you can modify that globally or per request.
+You can inspect the final redirected URL through the `responseUrl` property on the `response`.
+If no redirection happened, `responseUrl` is the original request URL.
 
 ```javascript
-require('follow-redirects').maxRedirects = 10;   // Has global affect (be careful!)
-
 https.request({
   host: 'bitly.com',
   path: '/UHfDGO',
-  maxRedirects: 3   // per request setting
-}, function (res) {/* ... */});
+}, function (response) {
+  console.log(response.responseUrl);
+  // 'http://duckduckgo.com/robots.txt'
+});
 ```
 
-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.
+## Options
+### Global options
+Global options are set directly on the `follow-redirects` module:
 
 ```javascript
-https.request({
-  host: 'bitly.com',
-  path: '/UHfDGO',
-}, function (res) {
-  console.log(res.fetchedUrls);
-  // [ 'http://duckduckgo.com/robots.txt',  'http://bitly.com/UHfDGO' ]
-});
+var followRedirects = require('follow-redirects');
+followRedirects.maxRedirects = 10;
 ```
 
+The following global options are supported:
+
+- `maxRedirects` (default: `21`) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.
+
+
+### Per-request options
+Per-request options are set by passing an `options` object:
+
+```javascript
+var url = require('url');
+var followRedirects = require('follow-redirects');
+
+var options = url.parse('http://bit.ly/900913');
+options.maxRedirects = 10;
+http.request(options);
+```
+
+In addition to the [standard HTTP](https://nodejs.org/api/http.html#http_http_request_options_callback) and [HTTPS options](https://nodejs.org/api/https.html#https_https_request_options_callback),
+the following per-request options are supported:
+- `followRedirects` (default: `true`) – whether redirects should be followed.
+
+- `maxRedirects` (default: `21`) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.
+
+- `agents` (default: `undefined`) – sets the `agent` option per protocol, since HTTP and HTTPS use different agents. Example value: `{ http: new http.Agent(), https: new https.Agent() }`
+
+
 ## 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
+ If you are *only* targeting 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.
@@ -103,9 +126,9 @@ Pull Requests are always welcome. Please [file an issue](https://github.com/olal
 
 ## Authors
 
-Olivier Lalonde (olalonde@gmail.com)
-
-James Talmage (james@talmage.io)
+- Olivier Lalonde (olalonde@gmail.com)
+- James Talmage (james@talmage.io)
+- [Ruben Verborgh](https://ruben.verborgh.org/)
 
 ## License
 

package/index.js

@@ -1,4 +1,185 @@
-module.exports = require('./create')({
-  'http': require('http'),
-  'https': require('https')
+'use strict';
+var url = require('url');
+var assert = require('assert');
+var http = require('http');
+var https = require('https');
+var Writable = require('stream').Writable;
+var debug = require('debug')('follow-redirects');
+
+var nativeProtocols = {'http:': http, 'https:': https};
+var schemes = {};
+var exports = module.exports = {
+	maxRedirects: 21
+};
+// RFC7231§4.2.1: Of the request methods defined by this specification,
+// the GET, HEAD, OPTIONS, and TRACE methods are defined to be safe.
+var safeMethods = {GET: true, HEAD: true, OPTIONS: true, TRACE: true};
+
+// Create handlers that pass events from native requests
+var eventHandlers = Object.create(null);
+['abort', 'aborted', 'error'].forEach(function (event) {
+	eventHandlers[event] = function (arg) {
+		this._redirectable.emit(event, arg);
+	};
+});
+
+// An HTTP(S) request that can be redirected
+function RedirectableRequest(options, responseCallback) {
+	// Initialize the request
+	Writable.call(this);
+	this._options = options;
+	this._redirectCount = 0;
+
+	// Attach a callback if passed
+	if (responseCallback) {
+		this.on('response', responseCallback);
+	}
+
+	// React to responses of native requests
+	var self = this;
+	this._onNativeResponse = function (response) {
+		self._processResponse(response);
+	};
+
+	// Perform the first request
+	this._performRequest();
+}
+RedirectableRequest.prototype = Object.create(Writable.prototype);
+
+// Executes the next native request (initial or redirect)
+RedirectableRequest.prototype._performRequest = function () {
+	// If specified, use the agent corresponding to the protocol
+	// (HTTP and HTTPS use different types of agents)
+	var protocol = this._options.protocol;
+	if (this._options.agents) {
+		this._options.agent = this._options.agents[schemes[protocol]];
+	}
+
+	// Create the native request
+	var nativeProtocol = nativeProtocols[this._options.protocol];
+	var request = this._currentRequest =
+				nativeProtocol.request(this._options, this._onNativeResponse);
+	this._currentUrl = url.format(this._options);
+
+	// Set up event handlers
+	request._redirectable = this;
+	for (var event in eventHandlers) {
+		if (event) {
+			request.on(event, eventHandlers[event]);
+		}
+	}
+
+	// The first request is explicitly ended in RedirectableRequest#end
+	if (this._currentResponse) {
+		request.end();
+	}
+};
+
+// Processes a response from the current native request
+RedirectableRequest.prototype._processResponse = function (response) {
+	// RFC7231§6.4: The 3xx (Redirection) class of status code indicates
+	// that further action needs to be taken by the user agent in order to
+	// fulfill the request. If a Location header field is provided,
+	// the user agent MAY automatically redirect its request to the URI
+	// referenced by the Location field value,
+	// even if the specific status code is not understood.
+	var location = response.headers.location;
+	if (location && this._options.followRedirects !== false &&
+			response.statusCode >= 300 && response.statusCode < 400) {
+		// RFC7231§6.4: A client SHOULD detect and intervene
+		// in cyclical redirections (i.e., "infinite" redirection loops).
+		if (++this._redirectCount > this._options.maxRedirects) {
+			return this.emit('error', new Error('Max redirects exceeded.'));
+		}
+
+		// RFC7231§6.4.7: The 307 (Temporary Redirect) status code indicates
+		// that the target resource resides temporarily under a different URI
+		// and the user agent MUST NOT change the request method
+		// if it performs an automatic redirection to that URI.
+		if (response.statusCode !== 307) {
+			// RFC7231§6.4: Automatic redirection needs to done with
+			// care for methods not known to be safe […],
+			// since the user might not wish to redirect an unsafe request.
+			if (!(this._options.method in safeMethods)) {
+				this._options.method = 'GET';
+			}
+		}
+
+		// Perform the redirected request
+		var redirectUrl = url.resolve(this._currentUrl, location);
+		debug('redirecting to', redirectUrl);
+		Object.assign(this._options, url.parse(redirectUrl));
+		this._currentResponse = response;
+		this._performRequest();
+	} else {
+		// The response is not a redirect; return it as-is
+		response.responseUrl = this._currentUrl;
+		return this.emit('response', response);
+	}
+};
+
+// Aborts the current native request
+RedirectableRequest.prototype.abort = function () {
+	this._currentRequest.abort();
+};
+
+// Ends the current native request
+RedirectableRequest.prototype.end = function (data, encoding, callback) {
+	this._currentRequest.end(data, encoding, callback);
+};
+
+// Flushes the headers of the current native request
+RedirectableRequest.prototype.flushHeaders = function () {
+	this._currentRequest.flushHeaders();
+};
+
+// Sets the noDelay option of the current native request
+RedirectableRequest.prototype.setNoDelay = function (noDelay) {
+	this._currentRequest.setNoDelay(noDelay);
+};
+
+// Sets the socketKeepAlive option of the current native request
+RedirectableRequest.prototype.setSocketKeepAlive = function (enable, initialDelay) {
+	this._currentRequest.setSocketKeepAlive(enable, initialDelay);
+};
+
+// Sets the timeout option of the current native request
+RedirectableRequest.prototype.setTimeout = function (timeout, callback) {
+	this._currentRequest.setTimeout(timeout, callback);
+};
+
+// Writes buffered data to the current native request
+RedirectableRequest.prototype._write = function (chunk, encoding, callback) {
+	this._currentRequest.write(chunk, encoding, callback);
+};
+
+// Export a redirecting wrapper for each native protocol
+Object.keys(nativeProtocols).forEach(function (protocol) {
+	var scheme = schemes[protocol] = protocol.substr(0, protocol.length - 1);
+	var nativeProtocol = nativeProtocols[protocol];
+	var wrappedProtocol = exports[scheme] = Object.create(nativeProtocol);
+
+	// Executes an HTTP request, following redirects
+	wrappedProtocol.request = function (options, callback) {
+		if (typeof options === 'string') {
+			options = url.parse(options);
+			options.maxRedirects = exports.maxRedirects;
+		} else {
+			options = Object.assign({
+				maxRedirects: exports.maxRedirects,
+				protocol: protocol
+			}, options);
+		}
+		assert.equal(options.protocol, protocol, 'protocol mismatch');
+		debug('options', options);
+
+		return new RedirectableRequest(options, callback);
+	};
+
+	// Executes a GET request, following redirects
+	wrappedProtocol.get = function (options, callback) {
+		var request = wrappedProtocol.request(options, callback);
+		request.end();
+		return request;
+	};
 });

package/package.json

@@ -1,14 +1,10 @@
 {
   "name": "follow-redirects",
-  "version": "0.0.7",
+  "version": "1.0.0",
   "description": "HTTP and HTTPS modules that follow redirects.",
   "main": "index.js",
   "scripts": {
-    "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"
+    "test": "xo && BLUEBIRD_DEBUG=1 nyc mocha"
   },
   "repository": {
     "type": "git",
@@ -33,7 +29,8 @@
     "url": "http://www.syskall.com"
   },
   "contributors": [
-    "James Talmage <james@talmage.io>"
+    "James Talmage <james@talmage.io>",
+    "Ruben Verborgh <ruben@verborgh.org> (https://ruben.verborgh.org/)"
   ],
   "files": [
     "index.js",
@@ -42,19 +39,27 @@
     "https.js"
   ],
   "dependencies": {
-    "debug": "^2.2.0",
-    "stream-consume": "^0.1.0"
+    "debug": "^2.2.0"
   },
   "devDependencies": {
-    "bluebird": "^2.9.30",
+    "bluebird": "^3.4.0",
     "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"
+    "mocha": "^3.1.2",
+    "nyc": "^8.3.1",
+    "xo": "^0.17.0"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "nyc": {
+    "reporter": [
+      "lcov",
+      "text"
+    ]
+  },
+  "xo": {
+    "envs": [
+      "mocha"
+    ]
+  }
 }

package/create.js

@@ -1,162 +0,0 @@
-'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'];