use directories for structure

2020-05-26 10:37:57 +02:00
parent 66580d4847
commit ae4aaf2668
1287 changed files with 92093 additions and 13113 deletions
--- a/node_modules/request/README.md
+++ b/node_modules/request/README.md
@@ -1,3 +1,9 @@
+# Deprecated!
+
+As of Feb 11th 2020, request is fully deprecated. No new changes are expected land. In fact, none have landed for some time.
+
+For more information about why request is deprecated and possible alternatives refer to
+[this issue](https://github.com/request/request/issues/3142).

 # Request - Simplified HTTP client

@@ -16,9 +22,9 @@
 Request is designed to be the simplest way possible to make http calls. It supports HTTPS and follows redirects by default.

 ```js
-var request = require('request');
+const request = require('request');
 request('http://www.google.com', function (error, response, body) {
-  console.log('error:', error); // Print the error if one occurred
+  console.error('error:', error); // Print the error if one occurred
  console.log('statusCode:', response && response.statusCode); // Print the response status code if a response was received
  console.log('body:', body); // Print the HTML for the Google homepage.
 });
@@ -86,7 +92,7 @@ To easily handle errors when streaming requests, listen to the `error` event bef
 request
  .get('http://mysite.com/doodle.png')
  .on('error', function(err) {
-    console.log(err)
+    console.error(err)
  })
  .pipe(fs.createWriteStream('doodle.png'))
 ```
@@ -110,7 +116,7 @@ You can also `pipe()` from `http.ServerRequest` instances, as well as to `http.S
 ```js
 http.createServer(function (req, resp) {
  if (req.url === '/doodle.png') {
-    var x = request('http://mysite.com/doodle.png')
+    const x = request('http://mysite.com/doodle.png')
    req.pipe(x)
    x.pipe(resp)
  }
@@ -126,7 +132,7 @@ req.pipe(request('http://mysite.com/doodle.png')).pipe(resp)
 Also, none of this new functionality conflicts with requests previous features, it just expands them.

 ```js
-var r = request.defaults({'proxy':'http://localproxy.com'})
+const r = request.defaults({'proxy':'http://localproxy.com'})

 http.createServer(function (req, resp) {
  if (req.url === '/doodle.png') {
@@ -152,6 +158,8 @@ Several alternative interfaces are provided by the request team, including:
 - [`request-promise-native`](https://github.com/request/request-promise-native) (uses native Promises)
 - [`request-promise-any`](https://github.com/request/request-promise-any) (uses [any-promise](https://www.npmjs.com/package/any-promise) Promises)

+Also, [`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original), which is available from Node.js v8.0 can be used to convert a regular function that takes a callback to return a promise instead.
+

 [back to top](#table-of-contents)

@@ -183,7 +191,7 @@ For `multipart/form-data` we use the [form-data](https://github.com/form-data/fo


 ```js
-var formData = {
+const formData = {
  // Pass a simple key-value pair
  my_field: 'my_value',
  // Pass data via Buffers
@@ -218,8 +226,8 @@ For advanced cases, you can access the form-data object itself via `r.form()`. T

 ```js
 // NOTE: Advanced use-case, for normal use see 'formData' usage above
-var r = request.post('http://service.com/upload', function optionalCallback(err, httpResponse, body) {...})
-var form = r.form();
+const r = request.post('http://service.com/upload', function optionalCallback(err, httpResponse, body) {...})
+const form = r.form();
 form.append('my_field', 'my_value');
 form.append('my_buffer', Buffer.from([1, 2, 3]));
 form.append('custom_file', fs.createReadStream(__dirname + '/unicycle.jpg'), {filename: 'unicycle.jpg'});
@@ -314,11 +322,11 @@ detailed in [RFC 1738](http://www.ietf.org/rfc/rfc1738.txt). Simply pass the
 `user:password` before the host with an `@` sign:

 ```js
-var username = 'username',
+const username = 'username',
    password = 'password',
    url = 'http://' + username + ':' + password + '@some.server.com';

-request({url: url}, function (error, response, body) {
+request({url}, function (error, response, body) {
   // Do more stuff with 'body' here
 });
 ```
@@ -347,9 +355,9 @@ of stars and forks for the request repository. This requires a
 custom `User-Agent` header as well as https.

 ```js
-var request = require('request');
+const request = require('request');

-var options = {
+const options = {
  url: 'https://api.github.com/repos/request/request',
  headers: {
    'User-Agent': 'request'
@@ -358,7 +366,7 @@ var options = {

 function callback(error, response, body) {
  if (!error && response.statusCode == 200) {
-    var info = JSON.parse(body);
+    const info = JSON.parse(body);
    console.log(info.stargazers_count + " Stars");
    console.log(info.forks_count + " Forks");
  }
@@ -382,7 +390,7 @@ default signing algorithm is
 ```js
 // OAuth1.0 - 3-legged server side flow (Twitter example)
 // step 1
-var qs = require('querystring')
+const qs = require('querystring')
  , oauth =
    { callback: 'http://mysite.com/callback/'
    , consumer_key: CONSUMER_KEY
@@ -397,14 +405,14 @@ request.post({url:url, oauth:oauth}, function (e, r, body) {
  // verified with twitter that they are authorizing your app.

  // step 2
-  var req_data = qs.parse(body)
-  var uri = 'https://api.twitter.com/oauth/authenticate'
+  const req_data = qs.parse(body)
+  const uri = 'https://api.twitter.com/oauth/authenticate'
    + '?' + qs.stringify({oauth_token: req_data.oauth_token})
  // redirect the user to the authorize uri

  // step 3
  // after the user is redirected back to your server
-  var auth_data = qs.parse(body)
+  const auth_data = qs.parse(body)
    , oauth =
      { consumer_key: CONSUMER_KEY
      , consumer_secret: CONSUMER_SECRET
@@ -416,7 +424,7 @@ request.post({url:url, oauth:oauth}, function (e, r, body) {
    ;
  request.post({url:url, oauth:oauth}, function (e, r, body) {
    // ready to make signed requests on behalf of the user
-    var perm_data = qs.parse(body)
+    const perm_data = qs.parse(body)
      , oauth =
        { consumer_key: CONSUMER_KEY
        , consumer_secret: CONSUMER_SECRET
@@ -605,14 +613,14 @@ TLS/SSL Protocol options, such as `cert`, `key` and `passphrase`, can be
 set directly in `options` object, in the `agentOptions` property of the `options` object, or even in `https.globalAgent.options`. Keep in mind that, although `agentOptions` allows for a slightly wider range of configurations, the recommended way is via `options` object directly, as using `agentOptions` or `https.globalAgent.options` would not be applied in the same way in proxied environments (as data travels through a TLS connection instead of an http/https agent).

 ```js
-var fs = require('fs')
+const fs = require('fs')
    , path = require('path')
    , certFile = path.resolve(__dirname, 'ssl/client.crt')
    , keyFile = path.resolve(__dirname, 'ssl/client.key')
    , caFile = path.resolve(__dirname, 'ssl/ca.cert.pem')
    , request = require('request');

-var options = {
+const options = {
    url: 'https://api.some-server.com/',
    cert: fs.readFileSync(certFile),
    key: fs.readFileSync(keyFile),
@@ -629,13 +637,13 @@ In the example below, we call an API that requires client side SSL certificate
 (in PEM format) with passphrase protected private key (in PEM format) and disable the SSLv3 protocol:

 ```js
-var fs = require('fs')
+const fs = require('fs')
    , path = require('path')
    , certFile = path.resolve(__dirname, 'ssl/client.crt')
    , keyFile = path.resolve(__dirname, 'ssl/client.key')
    , request = require('request');

-var options = {
+const options = {
    url: 'https://api.some-server.com/',
    agentOptions: {
        cert: fs.readFileSync(certFile),
@@ -675,6 +683,25 @@ request.get({
 });
 ```

+The `ca` value can be an array of certificates, in the event you have a private or internal corporate public-key infrastructure hierarchy. For example, if you want to connect to https://api.some-server.com which presents a key chain consisting of:
+1. its own public key, which is signed by:
+2. an intermediate "Corp Issuing Server", that is in turn signed by: 
+3. a root CA "Corp Root CA";
+
+you can configure your request as follows:
+
+```js
+request.get({
+    url: 'https://api.some-server.com/',
+    agentOptions: {
+        ca: [
+          fs.readFileSync('Corp Issuing Server.pem'),
+          fs.readFileSync('Corp Root CA.pem')
+        ]
+    }
+});
+```
+
 [back to top](#table-of-contents)


@@ -687,7 +714,7 @@ The `options.har` property will override the values: `url`, `method`, `qs`, `hea
 A validation step will check if the HAR Request format matches the latest spec (v1.2) and will skip parsing if not matching.

 ```js
-  var request = require('request')
+  const request = require('request')
  request({
    // will be ignored
    method: 'GET',
@@ -802,11 +829,9 @@ The first argument can be either a `url` or an `options` object. The only requir
    work around this, either use [`request.defaults`](#requestdefaultsoptions)
    with your pool options or create the pool object with the `maxSockets`
    property outside of the loop.
- `timeout` - integer containing the number of milliseconds to wait for a
-server to send response headers (and start the response body) before aborting
-the request. Note that if the underlying TCP connection cannot be established,
-the OS-wide TCP connection timeout will overrule the `timeout` option ([the
-default in Linux can be anywhere from 20-120 seconds][linux-timeout]).
+- `timeout` - integer containing number of milliseconds, controls two timeouts.
+  - **Read timeout**: Time to wait for a server to send response headers (and start the response body) before aborting the request.
+  - **Connection timeout**: Sets the socket to timeout after `timeout` milliseconds of inactivity. Note that increasing the timeout beyond the OS-wide TCP connection timeout will not have any effect ([the default in Linux can be anywhere from 20-120 seconds][linux-timeout])

 [linux-timeout]: http://www.sekuda.com/overriding_the_default_linux_kernel_20_second_tcp_socket_connect_timeout

@@ -847,7 +872,7 @@ default in Linux can be anywhere from 20-120 seconds][linux-timeout]).
    - `download`: Duration of HTTP download (`timings.end` - `timings.response`)
    - `total`: Duration entire HTTP round-trip (`timings.end`)

- `har` - a [HAR 1.2 Request Object](http://www.softwareishard.com/blog/har-12-spec/#request), will be processed from HAR format into options overwriting matching values *(see the [HAR 1.2 section](#support-for-har-1.2) for details)*
+- `har` - a [HAR 1.2 Request Object](http://www.softwareishard.com/blog/har-12-spec/#request), will be processed from HAR format into options overwriting matching values *(see the [HAR 1.2 section](#support-for-har-12) for details)*
 - `callback` - alternatively pass the request's callback in the options object

 The callback argument gets 3 arguments:
@@ -880,13 +905,13 @@ instead, it **returns a wrapper** that has your default settings applied to it.
 For example:
 ```js
 //requests using baseRequest() will set the 'x-token' header
-var baseRequest = request.defaults({
+const baseRequest = request.defaults({
  headers: {'x-token': 'my-token'}
 })

 //requests using specialRequest() will include the 'x-token' header set in
 //baseRequest and will also include the 'special' header
-var specialRequest = baseRequest.defaults({
+const specialRequest = baseRequest.defaults({
  headers: {special: 'special value'}
 })
 ```
@@ -918,6 +943,17 @@ Function that creates a new cookie jar.
 request.jar()
 ```

+### response.caseless.get('header-name')
+
+Function that returns the specified response header field using a [case-insensitive match](https://tools.ietf.org/html/rfc7230#section-3.2)
+
+```js
+request('http://www.google.com', function (error, response, body) {
+  // print the Content-Type header even if the server returned it as 'content-type' (lowercase)
+  console.log('Content-Type is:', response.caseless.get('Content-Type')); 
+});
+```
+
 [back to top](#table-of-contents)


@@ -975,7 +1011,7 @@ request.get('http://10.255.255.1', {timeout: 1500}, function(err) {
 ## Examples:

 ```js
-  var request = require('request')
+  const request = require('request')
    , rand = Math.floor(Math.random()*100000000).toString()
    ;
  request(
@@ -1006,7 +1042,7 @@ while the response object is unmodified and will contain compressed data if
 the server sent a compressed response.

 ```js
-  var request = require('request')
+  const request = require('request')
  request(
    { method: 'GET'
    , uri: 'http://www.google.com'
@@ -1034,7 +1070,7 @@ the server sent a compressed response.
 Cookies are disabled by default (else, they would be used in subsequent requests). To enable cookies, set `jar` to `true` (either in `defaults` or `options`).

 ```js
-var request = request.defaults({jar: true})
+const request = request.defaults({jar: true})
 request('http://www.google.com', function () {
  request('http://images.google.com')
 })
@@ -1043,8 +1079,8 @@ request('http://www.google.com', function () {
 To use a custom cookie jar (instead of `request`’s global cookie jar), set `jar` to an instance of `request.jar()` (either in `defaults` or `options`)

 ```js
-var j = request.jar()
-var request = request.defaults({jar:j})
+const j = request.jar()
+const request = request.defaults({jar:j})
 request('http://www.google.com', function () {
  request('http://images.google.com')
 })
@@ -1053,9 +1089,9 @@ request('http://www.google.com', function () {
 OR

 ```js
-var j = request.jar();
-var cookie = request.cookie('key1=value1');
-var url = 'http://www.google.com';
+const j = request.jar();
+const cookie = request.cookie('key1=value1');
+const url = 'http://www.google.com';
 j.setCookie(cookie, url);
 request({url: url, jar: j}, function () {
  request('http://images.google.com')
@@ -1068,9 +1104,9 @@ which supports saving to and restoring from JSON files), pass it as a parameter
 to `request.jar()`:

 ```js
-var FileCookieStore = require('tough-cookie-filestore');
+const FileCookieStore = require('tough-cookie-filestore');
 // NOTE - currently the 'cookies.json' file must already exist!
-var j = request.jar(new FileCookieStore('cookies.json'));
+const j = request.jar(new FileCookieStore('cookies.json'));
 request = request.defaults({ jar : j })
 request('http://www.google.com', function() {
  request('http://images.google.com')
@@ -1080,16 +1116,16 @@ request('http://www.google.com', function() {
 The cookie store must be a
 [`tough-cookie`](https://github.com/SalesforceEng/tough-cookie)
 store and it must support synchronous operations; see the
-[`CookieStore` API docs](https://github.com/SalesforceEng/tough-cookie#cookiestore-api)
+[`CookieStore` API docs](https://github.com/SalesforceEng/tough-cookie#api)
 for details.

 To inspect your cookie jar after a request:

 ```js
-var j = request.jar()
+const j = request.jar()
 request({url: 'http://www.google.com', jar: j}, function () {
-  var cookie_string = j.getCookieString(url); // "key1=value1; key2=value2; ..."
-  var cookies = j.getCookies(url);
+  const cookie_string = j.getCookieString(url); // "key1=value1; key2=value2; ..."
+  const cookies = j.getCookies(url);
  // [{key: 'key1', value: 'value1', domain: "www.google.com", ...}, ...]
 })
 ```