db3ebd0df0 | ||
---|---|---|
.. | ||
LICENSE | ||
README.md | ||
debug.js | ||
http.js | ||
https.js | ||
index.js | ||
package.json |
README.md
Follow Redirects
Drop-in replacement for Node's http
and https
modules 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.
const { http, https } = require('follow-redirects');
http.get('http://bit.ly/900913', response => {
response.on('data', chunk => {
console.log(chunk);
});
}).on('error', 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.
const request = https.request({
host: 'bitly.com',
path: '/UHfDGO',
}, response => {
console.log(response.responseUrl);
// 'http://duckduckgo.com/robots.txt'
});
request.end();
Options
Global options
Global options are set directly on the follow-redirects
module:
const 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
Per-request options are set by passing an options
object:
const url = require('url');
const { http, https } = require('follow-redirects');
const options = url.parse('http://bit.ly/900913');
options.maxRedirects = 10;
options.beforeRedirect = (options, { headers }) => {
// Use this to adjust the request options upon redirecting,
// to inspect the latest response headers,
// or to cancel the request by throwing an error
if (options.hostname === "example.com") {
options.auth = "user:password";
}
};
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. -
beforeRedirect
(default:undefined
) – optionally change the requestoptions
on redirects, or abort the request by throwing an error. -
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.
Advanced usage
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:
const { http, https } = 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.
Browser Usage
Due to the way the browser works,
the http
and https
browser equivalents perform redirects by default.
By requiring follow-redirects
this way:
const http = require('follow-redirects/http');
const https = require('follow-redirects/https');
you can easily tell webpack and friends to replace
follow-redirect
by the built-in versions:
{
"follow-redirects/http" : "http",
"follow-redirects/https" : "https"
}
Contributing
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.
Debug Logging
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.