follow-redirects/follow-redirects: Node.js module that automatically follows HTTP(S) redirects

_Follow Redirects_ is in need of funding

[!IMPORTANT]

Maintenance paused until funding found.

> follow-redirects is downloaded over 400 million times per month,

It has been maintained for over ten years by one volunteer,

who has no funds to provide update and security guarantees.

> What this means for you:

the package stays published and keeps working as it does today,

but there are no guarantees of bug fixes, security fixes,

or replies to issues and pull requests.

Security reports are handled best-effort only; see SECURITY.md.

> What can restart maintenance:

Even if only 0.1% of downloads paid $0.01, we'd be fully funded

with $4000 per month.

That's not the case, and that's okay,

but unfortunately also insufficient to continue.

We need to cover security triage, CVE handling, fixes, and releases.

Progress toward that goal will be posted here.

> If your company depends on follow-redirects,

directly or another library,

please sponsor on GitHub

or email us for invoice-based funding or a security support agreement.

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://en.wikipedia.org/', 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: 'en.wikipedia.org',
  path: '/',
}, response => {
  console.log(response.responseUrl);
  // 'http://duckduckgo.com/robots.txt'
});
request.end();

Options

Global options

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

const url = require('url');
const { http, https } = require('follow-redirects');
const options = url.parse('http://en.wikipedia.org/');
options.maxRedirects = 10;
options.beforeRedirect = (options, response, request) => {
  // Use this to adjust the request options upon redirecting,
  // to inspect the latest response headers,
  // or to cancel the request by throwing an error
// response.headers = the redirect response headers
  // response.statusCode = the redirect response code (eg. 301, 307, etc.)
// request.url = the requested URL that resulted in a redirect
  // request.headers = the headers in the request that resulted in a redirect
  // request.method = the method of the request that resulted in a redirect
  if (options.hostname === "example.org") {
    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 request options on redirects, or abort the request by throwing an error.

• 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() }

• trackRedirects (default: false) – whether to store the redirected response details into the redirects array on the response object.

• sensitiveHeaders (default: []) – names of headers to omit when making redirected requests (such as X-API-Key, X-Auth-Token…)

Advanced usage

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');

{
  "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.

Authors

• Ruben Verborgh
• Olivier Lalonde
• James Talmage

License

MIT License