Merge 5d8f15b into 212570b

.gitignore

@@ -2,5 +2,6 @@ node_modules
 coverage
 .idea
 npm-debug.log
+.vscode
 package-lock.json
 .nyc_output

.travis.yml

@@ -2,7 +2,6 @@
 language: node_js
 
 node_js:
-  - node
   - 10
   - 8
   - 6

Fork.md

@@ -0,0 +1,28 @@
+# Fork Guidelines
+
+This fork is meant to always follow changes in the `upstream`.
+That is, there should be no changes done in this fork which would prevent drop in replacement of `postman-request` with `request`
+(and vice-versa)
+
+## Setting up for maintainance
+
+1. Clone this repository
+
+        git clone https://github.com/postmanlabs/postman-request.git
+
+2. Create another git origin, so that we can easily track upstream changes, and merge them as necessary.
+
+        git remote add upstreamrepo https://github.com/user/repo.git
+
+3. Fetch commits from the upstream
+
+        git fetch upstreamrepo
+
+4. Checkout a local branch from the upstream master
+
+        git checkout --track upstreamrepo/master -b upstreammaster
+
+You can now merge in upstream changes as required,
+
+    git checkout master
+    git merge upstreammaster

README.md

@@ -1,22 +1,30 @@
 
 # Request - Simplified HTTP client
 
-[![npm package](https://nodei.co/npm/request.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/request/)
-
-[![Build status](https://img.shields.io/travis/request/request/master.svg?style=flat-square)](https://travis-ci.org/request/request)
-[![Coverage](https://img.shields.io/codecov/c/github/request/request.svg?style=flat-square)](https://codecov.io/github/request/request?branch=master)
-[![Coverage](https://img.shields.io/coveralls/request/request.svg?style=flat-square)](https://coveralls.io/r/request/request)
-[![Dependency Status](https://img.shields.io/david/request/request.svg?style=flat-square)](https://david-dm.org/request/request)
-[![Known Vulnerabilities](https://snyk.io/test/npm/request/badge.svg?style=flat-square)](https://snyk.io/test/npm/request)
-[![Gitter](https://img.shields.io/badge/gitter-join_chat-blue.svg?style=flat-square)](https://gitter.im/request/request?utm_source=badge)
-
+This is a fork of the excellent `request` module, which is used inside Postman Runtime. It contains a few bugfixes that are not fixed in `request`:
+
+- Handling of old-style deflate responses: https://github.com/request/request/issues/2197
+- Correct encoding of URL Parameters: https://github.com/nodejs/node/issues/8321
+- Redirect behavior for 307 responses when Host header is set: https://github.com/request/request/issues/2666
+- Fix missing `content-length` header for streaming requests: https://github.com/request/request/issues/316
+- Exception handling for large form-data: https://github.com/request/request/issues/1561
+- Added feature to bind on stream emits via options
+- Allowed sending request body with HEAD method
+- Added option to retain `authorization` header when a redirect happens to a different hostname
+- Reinitialize FormData stream on 307 or 308 redirects
+- Respect form-data fields ordering
+- Fixed authentication leak in 307 and 308 redirects
+- Added `secureConnect` to timings and `secureHandshake` to timingPhases
+- Fixed `Request~getNewAgent` to account for `passphrase` while generating poolKey
+- Added support for extending the root CA certificates
+- Added `verbose` mode to bubble up low-level request-response information
 
 ## Super simple to use
 
 Request is designed to be the simplest way possible to make http calls. It supports HTTPS and follows redirects by default.
 
 ```js
-const request = require('request');
+const request = require('postman-request');
 request('http://www.google.com', function (error, response, body) {
   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
@@ -349,12 +357,12 @@ of stars and forks for the request repository. This requires a
 custom `User-Agent` header as well as https.
 
 ```js
-const request = require('request');
+const request = require('postman-request');
 
 const options = {
   url: 'https://api.github.com/repos/request/request',
   headers: {
-    'User-Agent': 'request'
+    'User-Agent': 'postman-request'
   }
 };
 
@@ -612,7 +620,7 @@ const fs = require('fs')
     , 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');
+    , request = require('postman-request');
 
 const options = {
     url: 'https://api.some-server.com/',
@@ -635,7 +643,7 @@ const fs = require('fs')
     , path = require('path')
     , certFile = path.resolve(__dirname, 'ssl/client.crt')
     , keyFile = path.resolve(__dirname, 'ssl/client.key')
-    , request = require('request');
+    , request = require('postman-request');
 
 const options = {
     url: 'https://api.some-server.com/',
@@ -679,7 +687,7 @@ 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: 
+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:
@@ -696,6 +704,115 @@ request.get({
 });
 ```
 
+### Using `options.verbose`
+
+Using this option the debug object holds low level request response information like remote address, negotiated ciphers etc. Example debug object:
+
+```js
+request({url: 'https://www.google.com', verbose: true}, function (error, response, body, debug) {
+  // debug:
+  /*
+  [
+    {
+      "request": {
+        "method": "GET",
+        "href": "https://www.google.com/",
+        "httpVersion": "1.1"
+      },
+      "session": {
+        "id": "9a1ac0d7-b757-48ad-861c-d59d6af5f43f",
+        "reused": false,
+        "data": {
+          "addresses": {
+            "local": {
+              "address": "8.8.4.4",
+              "family": "IPv4",
+              "port": 61632
+            },
+            "remote": {
+              "address": "172.217.31.196",
+              "family": "IPv4",
+              "port": 443
+            }
+          },
+          "tls": {
+            "reused": false,
+            "authorized": true,
+            "authorizationError": null,
+            "cipher": {
+              "name": "ECDHE-ECDSA-AES128-GCM-SHA256",
+              "version": "TLSv1/SSLv3"
+            },
+            "protocol": "TLSv1.2",
+            "ephemeralKeyInfo": {
+              "type": "ECDH",
+              "name": "X25519",
+              "size": 253
+            },
+            "peerCertificate": {
+              "subject": {
+                "country": "US",
+                "stateOrProvince": "California",
+                "locality": "Mountain View",
+                "organization": "Google LLC",
+                "commonName": "www.google.com",
+                "alternativeNames": "DNS:www.google.com"
+              },
+              "issuer": {
+                "country": "US",
+                "organization": "Google Trust Services",
+                "commonName": "Google Internet Authority G3"
+              },
+              "validFrom": "2019-03-01T09:46:35.000Z",
+              "validTo": "2019-05-24T09:25:00.000Z",
+              "fingerprint": "DF:6B:95:81:C6:03:EB:ED:48:EB:6C:CF:EE:FE:E6:1F:AD:01:78:34",
+              "serialNumber": "3A15F4C87FB4D33993D3EEB3BF4AE5E4"
+            }
+          }
+        }
+      },
+      "response": {
+        "statusCode": 200,
+        "httpVersion": "1.1"
+      },
+      "timingStart": 1552908287924,
+      "timingStartTimer": 805.690674,
+      "timings": {
+        "socket": 28.356426000000056,
+        "lookup": 210.3752320000001,
+        "connect": 224.57993499999998,
+        "secureConnect": 292.80315800000017,
+        "response": 380.61268100000007,
+        "end": 401.8332560000001
+      }
+    }
+  ]
+  */
+});
+```
+
+
+### Extending root CAs
+
+When this feature is enabled, the root CAs can be extended using the `extraCA` option. The file should consist of one or more trusted certificates in PEM format.
+
+This is similar to [NODE_EXTRA_CA_CERTS](https://nodejs.org/api/cli.html#cli_node_extra_ca_certs_file). But, if `options.ca` is specified, those will be extended as well.
+
+```js
+// enable extending CAs
+request.enableNodeExtraCACerts();
+
+// request with extra CA certs
+request.get({
+    url: 'https://api.some-server.com/',
+    extraCA: fs.readFileSync('Extra CA Certificates .pem')
+});
+
+// disable this feature
+request.disableNodeExtraCACerts()
+
+```
+
 [back to top](#table-of-contents)
 
 
@@ -708,7 +825,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
-  const request = require('request')
+  const request = require('postman-request')
   request({
     // will be ignored
     method: 'GET',
@@ -801,6 +918,7 @@ The first argument can be either a `url` or an `options` object. The only requir
 - `followRedirect` - follow HTTP 3xx responses as redirects (default: `true`). This property can also be implemented as function which gets `response` object as a single argument and should return `true` if redirects should continue or `false` otherwise.
 - `followAllRedirects` - follow non-GET HTTP 3xx responses as redirects (default: `false`)
 - `followOriginalHttpMethod` - by default we redirect to HTTP method GET. you can enable this property to redirect to the original HTTP method (default: `false`)
+- `followAuthorizationHeader` - retain `authorization` header when a redirect happens to a different hostname (default: `false`)
 - `maxRedirects` - the maximum number of redirects to follow (default: `10`)
 - `removeRefererHeader` - removes the referer header when a redirect happens (default: `false`). **Note:** if true, referer header set in the initial request is preserved during redirect chain.
 
@@ -829,6 +947,7 @@ The first argument can be either a `url` or an `options` object. The only requir
 
 [linux-timeout]: http://www.sekuda.com/overriding_the_default_linux_kernel_20_second_tcp_socket_connect_timeout
 
+- `maxResponseSize` - Abort request if the response size exceeds this threshold (bytes).
 ---
 
 - `localAddress` - local interface to bind for network connections.
@@ -848,6 +967,7 @@ The first argument can be either a `url` or an `options` object. The only requir
 
 ---
 
+- `disableUrlEncoding` - if `true`, it will not use postman-url-encoder to encode URL. It means that if URL is given as object, it will be used as it is without doing any encoding. But if URL is given as string, it will be encoded by Node while converting it to object.
 - `time` - if `true`, the request-response cycle (including all redirects) is timed at millisecond resolution. When set, the following properties are added to the response object:
   - `elapsedTime` Duration of the entire request/response in milliseconds (*deprecated*).
   - `responseStartTime` Timestamp when the response began (in Unix Epoch milliseconds) (*deprecated*).
@@ -856,13 +976,15 @@ The first argument can be either a `url` or an `options` object. The only requir
     - `socket` Relative timestamp when the [`http`](https://nodejs.org/api/http.html#http_event_socket) module's `socket` event fires. This happens when the socket is assigned to the request.
     - `lookup` Relative timestamp when the [`net`](https://nodejs.org/api/net.html#net_event_lookup) module's `lookup` event fires. This happens when the DNS has been resolved.
     - `connect`: Relative timestamp when the [`net`](https://nodejs.org/api/net.html#net_event_connect) module's `connect` event fires. This happens when the server acknowledges the TCP connection.
+    - `secureConnect`: Relative timestamp when the [`tls`](https://nodejs.org/api/tls.html#tls_event_secureconnect) module's `secureconnect` event fires. This happens when the handshaking process for a new connection has successfully completed.
     - `response`: Relative timestamp when the [`http`](https://nodejs.org/api/http.html#http_event_response) module's `response` event fires. This happens when the first bytes are received from the server.
     - `end`: Relative timestamp when the last bytes of the response are received.
   - `timingPhases` Contains the durations of each request phase. If there were redirects, the properties reflect the timings of the final request in the redirect chain:
     - `wait`: Duration of socket initialization (`timings.socket`)
     - `dns`: Duration of DNS lookup (`timings.lookup` - `timings.socket`)
-    - `tcp`: Duration of TCP connection (`timings.connect` - `timings.socket`)
-    - `firstByte`: Duration of HTTP server response (`timings.response` - `timings.connect`)
+    - `tcp`: Duration of TCP connection (`timings.connect` - `timings.lookup`)
+    - `secureHandshake`: Duration of SSL handshake (`timings.secureConnect` - `timings.connect`)
+    - `firstByte`: Duration of HTTP server response (`timings.response` - `timings.connect`|`timings.secureConnect`)
     - `download`: Duration of HTTP download (`timings.end` - `timings.response`)
     - `total`: Duration entire HTTP round-trip (`timings.end`)
 
@@ -961,7 +1083,7 @@ There are at least three ways to debug the operation of `request`:
 1. Launch the node process like `NODE_DEBUG=request node script.js`
    (`lib,request,otherlib` works too).
 
-2. Set `require('request').debug = true` at any time (this does the same thing
+2. Set `require('postman-request').debug = true` at any time (this does the same thing
    as #1).
 
 3. Use the [request-debug module](https://github.com/request/request-debug) to
@@ -1005,7 +1127,7 @@ request.get('http://10.255.255.1', {timeout: 1500}, function(err) {
 ## Examples:
 
 ```js
-  const request = require('request')
+  const request = require('postman-request')
     , rand = Math.floor(Math.random()*100000000).toString()
     ;
   request(
@@ -1036,7 +1158,7 @@ while the response object is unmodified and will contain compressed data if
 the server sent a compressed response.
 
 ```js
-  const request = require('request')
+  const request = require('postman-request')
   request(
     { method: 'GET'
     , uri: 'http://www.google.com'
@@ -1109,7 +1231,7 @@ 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
+store and it must support asynchronous operations; see the
 [`CookieStore` API docs](https://github.com/SalesforceEng/tough-cookie#api)
 for details.
 
@@ -1118,8 +1240,8 @@ To inspect your cookie jar after a request:
 ```js
 const j = request.jar()
 request({url: 'http://www.google.com', jar: j}, function () {
-  const cookie_string = j.getCookieString(url); // "key1=value1; key2=value2; ..."
-  const cookies = j.getCookies(url);
+  const cookie_string = j.getCookieStringSync(url); // "key1=value1; key2=value2; ..."
+  const cookies = j.getCookiesSync(url);
   // [{key: 'key1', value: 'value1', domain: "www.google.com", ...}, ...]
 })
 ```