PageRenderTime 57ms CodeModel.GetById 45ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

/swf/src/main/resources/scripts/node_modules/follow-redirects/README.md

https://github.com/venkatramanm/swf-all
Markdown | 148 lines | 111 code | 37 blank | 0 comment | 0 complexity | f0c3354112f9e67cdbb0e8856439597b MD5 | raw file
  1## Follow Redirects
  2
  3Drop-in replacement for Node's `http` and `https` modules that automatically follows redirects.
  4
  5[![npm version](https://img.shields.io/npm/v/follow-redirects.svg)](https://www.npmjs.com/package/follow-redirects)
  6[![Build Status](https://github.com/follow-redirects/follow-redirects/workflows/CI/badge.svg)](https://github.com/follow-redirects/follow-redirects/actions)
  7[![Coverage Status](https://coveralls.io/repos/follow-redirects/follow-redirects/badge.svg?branch=master)](https://coveralls.io/r/follow-redirects/follow-redirects?branch=master)
  8[![npm downloads](https://img.shields.io/npm/dm/follow-redirects.svg)](https://www.npmjs.com/package/follow-redirects)
  9[![Sponsor on GitHub](https://img.shields.io/static/v1?label=Sponsor&message=%F0%9F%92%96&logo=GitHub)](https://github.com/sponsors/RubenVerborgh)
 10
 11`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)
 12 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)
 13 modules, with the exception that they will seamlessly follow redirects.
 14
 15```javascript
 16const { http, https } = require('follow-redirects');
 17
 18http.get('http://bit.ly/900913', response => {
 19  response.on('data', chunk => {
 20    console.log(chunk);
 21  });
 22}).on('error', err => {
 23  console.error(err);
 24});
 25```
 26
 27You can inspect the final redirected URL through the `responseUrl` property on the `response`.
 28If no redirection happened, `responseUrl` is the original request URL.
 29
 30```javascript
 31const request = https.request({
 32  host: 'bitly.com',
 33  path: '/UHfDGO',
 34}, response => {
 35  console.log(response.responseUrl);
 36  // 'http://duckduckgo.com/robots.txt'
 37});
 38request.end();
 39```
 40
 41## Options
 42### Global options
 43Global options are set directly on the `follow-redirects` module:
 44
 45```javascript
 46const followRedirects = require('follow-redirects');
 47followRedirects.maxRedirects = 10;
 48followRedirects.maxBodyLength = 20 * 1024 * 1024; // 20 MB
 49```
 50
 51The following global options are supported:
 52
 53- `maxRedirects` (default: `21`) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.
 54
 55- `maxBodyLength` (default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted.
 56
 57### Per-request options
 58Per-request options are set by passing an `options` object:
 59
 60```javascript
 61const url = require('url');
 62const { http, https } = require('follow-redirects');
 63
 64const options = url.parse('http://bit.ly/900913');
 65options.maxRedirects = 10;
 66options.beforeRedirect = (options, { headers }) => {
 67  // Use this to adjust the request options upon redirecting,
 68  // to inspect the latest response headers,
 69  // or to cancel the request by throwing an error
 70  if (options.hostname === "example.com") {
 71    options.auth = "user:password";
 72  }
 73};
 74http.request(options);
 75```
 76
 77In 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),
 78the following per-request options are supported:
 79- `followRedirects` (default: `true`) – whether redirects should be followed.
 80
 81- `maxRedirects` (default: `21`) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.
 82
 83- `maxBodyLength` (default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted.
 84
 85- `beforeRedirect` (default: `undefined`) – optionally change the request `options` on redirects, or abort the request by throwing an error.
 86
 87- `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() }`
 88
 89- `trackRedirects` (default: `false`) – whether to store the redirected response details into the `redirects` array on the response object.
 90
 91
 92### Advanced usage
 93By default, `follow-redirects` will use the Node.js default implementations
 94of [`http`](https://nodejs.org/api/http.html)
 95and [`https`](https://nodejs.org/api/https.html).
 96To enable features such as caching and/or intermediate request tracking,
 97you might instead want to wrap `follow-redirects` around custom protocol implementations:
 98
 99```javascript
100const { http, https } = require('follow-redirects').wrap({
101  http: require('your-custom-http'),
102  https: require('your-custom-https'),
103});
104```
105
106Such custom protocols only need an implementation of the `request` method.
107
108## Browser Usage
109
110Due to the way the browser works,
111the `http` and `https` browser equivalents perform redirects by default.
112
113By requiring `follow-redirects` this way:
114```javascript
115const http = require('follow-redirects/http');
116const https = require('follow-redirects/https');
117```
118you can easily tell webpack and friends to replace
119`follow-redirect` by the built-in versions:
120
121```json
122{
123  "follow-redirects/http"  : "http",
124  "follow-redirects/https" : "https"
125}
126```
127
128## Contributing
129
130Pull Requests are always welcome. Please [file an issue](https://github.com/follow-redirects/follow-redirects/issues)
131 detailing your proposal before you invest your valuable time. Additional features and bug fixes should be accompanied
132 by tests. You can run the test suite locally with a simple `npm test` command.
133
134## Debug Logging
135
136`follow-redirects` uses the excellent [debug](https://www.npmjs.com/package/debug) for logging. To turn on logging
137 set the environment variable `DEBUG=follow-redirects` for debug output from just this module. When running the test
138 suite it is sometimes advantageous to set `DEBUG=*` to see output from the express server as well.
139
140## Authors
141
142- [Ruben Verborgh](https://ruben.verborgh.org/)
143- [Olivier Lalonde](mailto:olalonde@gmail.com)
144- [James Talmage](mailto:james@talmage.io)
145
146## License
147
148[MIT License](https://github.com/follow-redirects/follow-redirects/blob/master/LICENSE)