Drop-in replacement for Nodes http
and https
that automatically follows redirects.
follow-redirects
provides request and get
methods that behave identically to those found on the native http and https
modules, with the exception that they will seamlessly follow redirects.
var http = require('follow-redirects').http;
var https = require('follow-redirects').https;
http.get('http://bit.ly/900913', function (response) {
response.on('data', function (chunk) {
console.log(chunk);
});
}).on('error', function (err) {
console.error(err);
});
You can inspect the final redirected URL through the responseUrl
property on the response
.
If no redirection happened, responseUrl
is the original request URL.
https.request({
host: 'bitly.com',
path: '/UHfDGO',
}, function (response) {
console.log(response.responseUrl);
// 'http://duckduckgo.com/robots.txt'
});
Global options are set directly on the follow-redirects
module:
var followRedirects = require('follow-redirects');
followRedirects.maxRedirects = 10;
followRedirects.maxBodyLength = 20 * 1024 * 1024; // 20 MB
The following global options are supported:
-
maxRedirects
(default:21
) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted. -
maxBodyLength
(default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted.
Per-request options are set by passing an options
object:
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 and HTTPS options, 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. -
maxBodyLength
(default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted. -
agents
(default:undefined
) – sets theagent
option per protocol, since HTTP and HTTPS use different agents. Example value:{ http: new http.Agent(), https: new https.Agent() }
-
trackRedirects
(default:false
) – whether to store the redirected response details into theredirects
array on the response object.
By default, follow-redirects
will use the Node.js default implementations
of http
and https
.
To enable features such as caching and/or intermediate request tracking,
you might instead want to wrap follow-redirects
around custom protocol implementations:
var followRedirects = require('follow-redirects').wrap({
http: require('your-custom-http'),
https: require('your-custom-https'),
});
Such custom protocols only need an implementation of the request
method.
Due to the way XMLHttpRequest
works, the browserify
versions of http
and https
already follow redirects.
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.
To make this easier, you need to change how you require the modules:
var http = require('follow-redirects/http');
var https = require('follow-redirects/https');
You can then replace follow-redirects
in your browserify configuration like so:
"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. 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:
"browser": {
"follow-redirects/http" : "browserify-http-2/http",
"follow-redirects/https" : "browserify-http-2/https"
}
Pull Requests are always welcome. Please file an issue
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.
follow-redirects
uses the excellent 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.
- Olivier Lalonde ([email protected])
- James Talmage ([email protected])
- Ruben Verborgh