got 9.3.2 → 9.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "got",
-	"version": "9.3.2",
+	"version": "9.6.0",
 	"description": "Simplified HTTP requests",
 	"license": "MIT",
 	"repository": "sindresorhus/got",
@@ -34,9 +34,9 @@
 		"electron"
 	],
 	"dependencies": {
-		"@sindresorhus/is": "^0.12.0",
-		"@szmarczak/http-timer": "^1.1.0",
-		"cacheable-request": "^5.1.0",
+		"@sindresorhus/is": "^0.14.0",
+		"@szmarczak/http-timer": "^1.1.2",
+		"cacheable-request": "^6.0.0",
 		"decompress-response": "^3.3.0",
 		"duplexer3": "^0.1.4",
 		"get-stream": "^4.1.0",
@@ -47,22 +47,22 @@
 		"url-parse-lax": "^3.0.0"
 	},
 	"devDependencies": {
-		"ava": "1.0.0-rc.1",
+		"ava": "^1.1.0",
 		"coveralls": "^3.0.0",
 		"delay": "^4.1.0",
 		"form-data": "^2.3.3",
 		"get-port": "^4.0.0",
-		"np": "^3.0.4",
+		"np": "^3.1.0",
 		"nyc": "^13.1.0",
 		"p-event": "^2.1.0",
 		"pem": "^1.13.2",
 		"proxyquire": "^2.0.1",
-		"sinon": "^7.1.0",
+		"sinon": "^7.2.2",
 		"slow-stream": "0.0.4",
 		"tempfile": "^2.0.0",
 		"tempy": "^0.2.1",
-		"tough-cookie": "^2.4.3",
-		"xo": "^0.23.0"
+		"tough-cookie": "^3.0.0",
+		"xo": "^0.24.0"
 	},
 	"ava": {
 		"concurrency": 4

package/readme.md

@@ -35,15 +35,16 @@ Got is for Node.js. For browsers, we recommend [Ky](https://github.com/sindresor
 - [Errors with metadata](#errors)
 - [JSON mode](#json)
 - [WHATWG URL support](#url)
-- [Hooks](https://github.com/sindresorhus/got#hooks)
+- [Hooks](#hooks)
 - [Instances with custom defaults](#instances)
 - [Composable](advanced-creation.md#merging-instances)
 - [Electron support](#useelectronnet)
 - [Used by ~2000 packages and ~500K repos](https://github.com/sindresorhus/got/network/dependents)
 - Actively maintained
 
-[See how Got compares to other HTTP libraries](#comparison)
+[Moving from Request?](migration-guides.md)
 
+[See how Got compares to other HTTP libraries](#comparison)
 
 ## Install
 
@@ -154,7 +155,7 @@ Returns a `Stream` instead of a `Promise`. This is equivalent to calling `got.st
 
 Type: `string` `Buffer` `stream.Readable` [`form-data` instance](https://github.com/form-data/form-data)
 
-*If you provide this option, `got.stream()` will be read-only.*
+**Note:** If you provide this option, `got.stream()` will be read-only.
 
 The body that will be sent with a `POST` request.
 
@@ -166,9 +167,9 @@ The `content-length` header will be automatically set if `body` is a `string` /
 
 Type: [`tough.CookieJar` instance](https://github.com/salesforce/tough-cookie#cookiejar)
 
-Cookie support. You don't have to care about parsing or how to store them. [Example.](#cookies)
+**Note:** If you provide this option, `options.headers.cookie` will be overridden.
 
-**Note:** `options.headers.cookie` will be overridden.
+Cookie support. You don't have to care about parsing or how to store them. [Example.](#cookies)
 
 ###### encoding
 
@@ -182,25 +183,23 @@ Default: `'utf8'`
 Type: `boolean`<br>
 Default: `false`
 
-*If you provide this option, `got.stream()` will be read-only.*
+**Note:** If you provide this option, `got.stream()` will be read-only.
+**Note:** `body` must be a plain object. It will be converted to a query string using [`(new URLSearchParams(object)).toString()`](https://nodejs.org/api/url.html#url_constructor_new_urlsearchparams_obj).
 
 If set to `true` and `Content-Type` header is not set, it will be set to `application/x-www-form-urlencoded`.
 
-`body` must be a plain object. It will be converted to a query string using [`(new URLSearchParams(object)).toString()`](https://nodejs.org/api/url.html#url_constructor_new_urlsearchparams_obj).
-
 ###### json
 
 Type: `boolean`<br>
 Default: `false`
 
-*If you use `got.stream()`, this option will be ignored.*
+**Note:** If you use `got.stream()`, this option will be ignored.
+**Note:** `body` must be a plain object or array and will be stringified.
 
 If set to `true` and `Content-Type` header is not set, it will be set to `application/json`.
 
 Parse response body with `JSON.parse` and set `accept` header to `application/json`. If used in conjunction with the `form` option, the `body` will the stringified as querystring and the response parsed as JSON.
 
-`body` must be a plain object or array and will be stringified.
-
 ###### query
 
 Type: `string` `Object<string, string|number>` [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
@@ -258,8 +257,9 @@ Default:
 - methods: `GET` `PUT` `HEAD` `DELETE` `OPTIONS` `TRACE`
 - statusCodes: [`408`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) [`413`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) [`429`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) [`500`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) [`502`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) [`503`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) [`504`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504)
 - maxRetryAfter: `undefined`
+- errorCodes: `ETIMEDOUT` `ECONNRESET` `EADDRINUSE` `ECONNREFUSED` `EPIPE` `ENOTFOUND` `ENETUNREACH` `EAI_AGAIN`
 
-An object representing `retries`, `methods`, `statusCodes` and `maxRetryAfter` fields for the time until retry, allowed methods, allowed status codes and maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time.
+An object representing `retries`, `methods`, `statusCodes`, `maxRetryAfter` and `errorCodes` fields for the time until retry, allowed methods, allowed status codes, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time and allowed error codes.
 
 If `maxRetryAfter` is set to `undefined`, it will use `options.timeout`.<br>
 If [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header is greater than `maxRetryAfter`, it will cancel the request.
@@ -268,12 +268,15 @@ Delays between retries counts with function `1000 * Math.pow(2, retry) + Math.ra
 
 The `retries` property can be a `number` or a `function` with `retry` and `error` arguments. The function must return a delay in milliseconds (`0` return value cancels retry).
 
-**Note:** It retries only on the specified methods, status codes, and on these network errors:
+By default, it retries *only* on the specified methods, status codes, and on these network errors:
 - `ETIMEDOUT`: One of the [timeout](#timeout) limits were reached.
 - `ECONNRESET`: Connection was forcibly closed by a peer.
 - `EADDRINUSE`: Could not bind to any free port.
 - `ECONNREFUSED`: Connection was refused by the server.
 - `EPIPE`: The remote side of the stream being written has been closed.
+- `ENOTFOUND`: Couldn't resolve the hostname to an IP address.
+- `ENETUNREACH`: No internet connection.
+- `EAI_AGAIN`: DNS lookup timed out.
 
 ###### followRedirect
 
@@ -348,6 +351,17 @@ Type: `Object<string, Function[]>`
 
 Hooks allow modifications during the request lifecycle. Hook functions may be async and are run serially.
 
+###### hooks.init
+
+Type: `Function[]`<br>
+Default: `[]`
+
+Called with plain [request options](#options), right before their normalization. This is especially useful in conjunction with [`got.extend()`](#instances) and [`got.create()`](advanced-creation.md) when the input needs custom handling.
+
+See the [Request migration guide](migration-guides.md#breaking-changes) for an example.
+
+**Note**: This hook must be synchronous!
+
 ###### hooks.beforeRequest
 
 Type: `Function[]`<br>
@@ -357,7 +371,7 @@ Called with [normalized](source/normalize-arguments.js) [request options](#optio
 
 See the [AWS section](#aws) for an example.
 
-**Note**: If you modify the `body` you will need to modify the `content-length` header too, because it has already been computed and assigned.
+**Note:** If you modify the `body` you will need to modify the `content-length` header too, because it has already been computed and assigned.
 
 ###### hooks.beforeRedirect
 
@@ -444,10 +458,47 @@ const instance = got.extend({
 });
 ```
 
+###### hooks.beforeError
+
+Type: `Function[]`<br>
+Default: `[]`
+
+Called with an `Error` instance. The error is passed to the hook right before it's thrown. This is especially useful when you want to have more detailed errors.
+
+**Note**: Errors thrown while normalizing input options are thrown directly and not part of this hook.
+
+```js	
+const got = require('got');	
+
+got('api.github.com/some-endpoint', {	
+	hooks: {	
+		onError: [	
+			error => {	
+				const {response} = error;	
+ 				if (response && response.body) {	
+					error.name = 'GitHubError';	
+					error.message = `${response.body.message} (${error.statusCode})`;	
+				}
+
+ 				return error;	
+			}	
+		]	
+	}	
+});	
+```
+
 #### Response
 
 The response object will typically be a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage), however, if returned from the cache it will be a [response-like object](https://github.com/lukechilds/responselike) which behaves in the same way.
 
+##### request
+
+Type: `Object`
+
+**Note:** This is not a [http.ClientRequest](https://nodejs.org/api/http.html#http_class_http_clientrequest).
+
+- `gotOptions` - The options that were set on this request.
+
 ##### body
 
 Type: `string` `Object` *(depending on `options.json`)*
@@ -489,7 +540,7 @@ The object contains the following properties:
 	- `download` - `timings.end - timings.response`
 	- `total` - `timings.end - timings.start` or `timings.error - timings.start`
 
-**Note**: The time is a `number` representing the milliseconds elapsed since the UNIX epoch.
+**Note:** The time is a `number` representing the milliseconds elapsed since the UNIX epoch.
 
 ##### fromCache
 
@@ -511,7 +562,7 @@ The number of times the request was retried.
 
 #### Streams
 
-**Note**: Progress events, redirect events and request/response events can also be used with promises.
+**Note:** Progress events, redirect events and request/response events can also be used with promises.
 
 #### got.stream(url, [options])
 
@@ -523,7 +574,7 @@ Returns a [duplex stream](https://nodejs.org/api/stream.html#stream_class_stream
 
 `request` event to get the request object of the request.
 
-**Tip**: You can use `request` event to abort request:
+**Tip:** You can use `request` event to abort request:
 
 ```js
 got.stream('github.com')
@@ -626,7 +677,7 @@ client.get('/demo');
 })();
 ```
 
-*Need more control over the behavior of Got? Check out the [`got.create()`](advanced-creation.md).*
+**Tip:** Need more control over the behavior of Got? Check out the [`got.create()`](advanced-creation.md).
 
 #### got.mergeOptions(parentOptions, newOptions)
 
@@ -658,7 +709,7 @@ The default Got options.
 
 ## Errors
 
-Each error contains (if available) `body`, `statusCode`, `statusMessage`, `host`, `hostname`, `method`, `path`, `protocol` and `url` properties to make debugging easier.
+Each error contains `host`, `hostname`, `method`, `path`, `protocol`, `url` and `gotOptions` properties to make debugging easier.
 
 In Promise mode, the `response` is attached to the error.
 
@@ -676,15 +727,15 @@ When reading from response stream fails.
 
 #### got.ParseError
 
-When `json` option is enabled, server response code is 2xx, and `JSON.parse` fails.
+When `json` option is enabled, server response code is 2xx, and `JSON.parse` fails. Includes `statusCode` and `statusMessage` properties.
 
 #### got.HTTPError
 
-When the server response code is not 2xx. Includes `statusCode`, `statusMessage`, and `redirectUrls` properties.
+When the server response code is not 2xx. Includes `body`, `statusCode`, `statusMessage`, and `redirectUrls` properties.
 
 #### got.MaxRedirectsError
 
-When the server redirects you more than ten times. Includes a `redirectUrls` property, which is an array of the URLs Got was redirected to before giving up.
+When the server redirects you more than ten times. Includes a `statusCode`, `statusMessage`, and `redirectUrls` property which is an array of the URLs Got was redirected to before giving up.
 
 #### got.UnsupportedProtocolError
 
@@ -696,7 +747,7 @@ When the request is aborted with `.cancel()`.
 
 #### got.TimeoutError
 
-When the request is aborted due to a [timeout](#timeout)
+When the request is aborted due to a [timeout](#timeout). Includes an `event` property.
 
 ## Aborting the request
 
@@ -1002,7 +1053,7 @@ const custom = got.extend({
 })();
 ```
 
-*Need to merge some instances into a single one? Check out [`got.mergeInstances()`](advanced-creation.md#merging-instances).*
+**Tip:** Need to merge some instances into a single one? Check out [`got.mergeInstances()`](advanced-creation.md#merging-instances).
 
 ### Experimental HTTP2 support
 
@@ -1022,86 +1073,147 @@ const h2got = got.extend({request});
 
 ## Comparison
 
-|                       |     `got`    |   `request`  | `node-fetch` |    `axios`   |
-|-----------------------|:------------:|:------------:|:------------:|:------------:|
-| HTTP/2 support        |      ❔      |       ✖      |       ✖      |       ✖      |
-| Browser support       |       ✖      |       ✖      |       ✔*     |       ✔      |
-| Electron support      |       ✔      |       ✖      |       ✖      |       ✖      |
-| Promise API           |       ✔      |       ✔      |       ✔      |       ✔      |
-| Stream API            |       ✔      |       ✔      | Node.js only |       ✖      |
-| Request cancelation   |       ✔      |       ✖      |       ✖      |       ✔      |
-| RFC compliant caching |       ✔      |       ✖      |       ✖      |       ✖      |
-| Cookies (out-of-box)  |       ✔      |       ✔      |       ✖      |       ✖      |
-| Follows redirects     |       ✔      |       ✔      |       ✔      |       ✔      |
-| Retries on failure    |       ✔      |       ✖      |       ✖      |       ✖      |
-| Progress events       |       ✔      |       ✖      |       ✖      | Browser only |
-| Handles gzip/deflate  |       ✔      |       ✔      |       ✔      |       ✔      |
-| Advanced timeouts     |       ✔      |       ✖      |       ✖      |       ✖      |
-| Timings               |       ✔      |       ✔      |       ✖      |       ✖      |
-| Errors with metadata  |       ✔      |       ✖      |       ✖      |       ✔      |
-| JSON mode             |       ✔      |       ✔      |       ✖      |       ✔      |
-| Custom defaults       |       ✔      |       ✔      |       ✖      |       ✔      |
-| Composable            |       ✔      |       ✖      |       ✖      |       ✖      |
-| Hooks                 |       ✔      |       ✖      |       ✖      |       ✔      |
-| Issues open           |   ![][gio]   |   ![][rio]   |   ![][nio]   |   ![][aio]   |
-| Issues closed         |   ![][gic]   |   ![][ric]   |   ![][nic]   |   ![][aic]   |
-| Downloads             |    ![][gd]   |    ![][rd]   |    ![][nd]   |    ![][ad]   |
-| Coverage              |    ![][gc]   |    ![][rc]   |    ![][nc]   |    ![][ac]   |
-| Build                 |    ![][gb]   |    ![][rb]   |    ![][nb]   |    ![][ab]   |
-| Bugs                  |   ![][gbg]   |   ![][rbg]   |   ![][nbg]   |   ![][abg]   |
-| Dependents            |   ![][gdp]   |   ![][rdp]   |   ![][ndp]   |   ![][adp]   |
-| Install size          |   ![][gis]   |   ![][ris]   |   ![][nis]   |   ![][ais]   |
+|                       |      `got`     | [`request`][r0] | [`node-fetch`][n0] |  [`axios`][a0]  |  [`superagent`][s0]  |
+|-----------------------|:--------------:|:---------------:|:------------------:|:---------------:|:--------------------:|
+| HTTP/2 support        |        ❔       |        ✖       |          ✖         |        ✖       |          ✔\*\*      |
+| Browser support       |        ✖       |        ✖       |          ✔\*       |        ✔       |          ✔          |
+| Electron support      |        ✔       |        ✖       |          ✖         |        ✖       |          ✖          |
+| Promise API           |        ✔       |        ✔       |          ✔         |        ✔       |          ✔          |
+| Stream API            |        ✔       |        ✔       |    Node.js only    |        ✖       |          ✔          |
+| Request cancelation   |        ✔       |        ✖       |          ✔         |        ✔       |          ✔          |
+| RFC compliant caching |        ✔       |        ✖       |          ✖         |        ✖       |          ✖          |
+| Cookies (out-of-box)  |        ✔       |        ✔       |          ✖         |        ✖       |          ✖          |
+| Follows redirects     |        ✔       |        ✔       |          ✔         |        ✔       |          ✔          |
+| Retries on failure    |        ✔       |        ✖       |          ✖         |        ✖       |          ✔          |
+| Progress events       |        ✔       |        ✖       |          ✖         |  Browser only  |          ✔          |
+| Handles gzip/deflate  |        ✔       |        ✔       |          ✔         |        ✔       |          ✔          |
+| Advanced timeouts     |        ✔       |        ✖       |          ✖         |        ✖       |          ✖          |
+| Timings               |        ✔       |        ✔       |          ✖         |        ✖       |          ✖          |
+| Errors with metadata  |        ✔       |        ✖       |          ✖         |        ✔       |          ✖          |
+| JSON mode             |        ✔       |        ✔       |          ✖         |        ✔       |          ✔          |
+| Custom defaults       |        ✔       |        ✔       |          ✖         |        ✔       |          ✖          |
+| Composable            |        ✔       |        ✖       |          ✖         |        ✖       |          ✔          |
+| Hooks                 |        ✔       |        ✖       |          ✖         |        ✔       |          ✖          |
+| Issues open           | [![][gio]][g1] | [![][rio]][r1]  |   [![][nio]][n1]   |  [![][aio]][a1] |   [![][sio]][s1]    |
+| Issues closed         | [![][gic]][g2] | [![][ric]][r2]  |   [![][nic]][n2]   |  [![][aic]][a2] |   [![][sic]][s2]    |
+| Downloads             | [![][gd]][g3]  |  [![][rd]][r3]  |   [![][nd]][n3]    |  [![][ad]][a3]  |   [![][sd]][s3]     |
+| Coverage              | [![][gc]][g4]  |  [![][rc]][r4]  |   [![][nc]][n4]    |  [![][ac]][a4]  |       unknown       |
+| Build                 | [![][gb]][g5]  |  [![][rb]][r5]  |   [![][nb]][n5]    |  [![][ab]][a5]  |   [![][sb]][s5]     |
+| Bugs                  | [![][gbg]][g6] | [![][rbg]][r6]  |   [![][nbg]][n6]   |  [![][abg]][a6] |   [![][sbg]][s6]    |
+| Dependents            | [![][gdp]][g7] | [![][rdp]][r7]  |   [![][ndp]][n7]   |  [![][adp]][a7] |   [![][sdp]][s7]    |
+| Install size          | [![][gis]][g8] | [![][ris]][r8]  |   [![][nis]][n8]   |  [![][ais]][a8] |   [![][sis]][s8]    |
 
 \* It's almost API compatible with the browser `fetch` API.<br>
+\*\* Need to switch the protocol manually.<br>
 ❔ Experimental support.
 
+<!-- GITHUB -->
+[r0]: https://github.com/request/request
+[n0]: https://github.com/bitinn/node-fetch
+[a0]: https://github.com/axios/axios
+[s0]: https://github.com/visionmedia/superagent
+
 <!-- ISSUES OPEN -->
-[gio]: https://img.shields.io/github/issues/sindresorhus/got.svg
-[rio]: https://img.shields.io/github/issues/request/request.svg
-[nio]: https://img.shields.io/github/issues/bitinn/node-fetch.svg
-[aio]: https://img.shields.io/github/issues/axios/axios.svg
+[gio]: https://badgen.net/github/open-issues/sindresorhus/got?label
+[rio]: https://badgen.net/github/open-issues/request/request?label
+[nio]: https://badgen.net/github/open-issues/bitinn/node-fetch?label
+[aio]: https://badgen.net/github/open-issues/axios/axios?label
+[sio]: https://badgen.net/github/open-issues/visionmedia/superagent?label
+
+[g1]: https://github.com/sindresorhus/got/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
+[r1]: https://github.com/request/request/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
+[n1]: https://github.com/bitinn/node-fetch/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
+[a1]: https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
+[s1]: https://github.com/visionmedia/superagent/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
 
 <!-- ISSUES CLOSED -->
-[gic]: https://img.shields.io/github/issues-closed/sindresorhus/got.svg
-[ric]: https://img.shields.io/github/issues-closed/request/request.svg
-[nic]: https://img.shields.io/github/issues-closed/bitinn/node-fetch.svg
-[aic]: https://img.shields.io/github/issues-closed/axios/axios.svg
+[gic]: https://badgen.net/github/closed-issues/sindresorhus/got?label
+[ric]: https://badgen.net/github/closed-issues/request/request?label
+[nic]: https://badgen.net/github/closed-issues/bitinn/node-fetch?label
+[aic]: https://badgen.net/github/closed-issues/axios/axios?label
+[sic]: https://badgen.net/github/closed-issues/visionmedia/superagent?label
+
+[g2]: https://github.com/sindresorhus/got/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
+[r2]: https://github.com/request/request/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
+[n2]: https://github.com/bitinn/node-fetch/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
+[a2]: https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
+[s2]: https://github.com/visionmedia/superagent/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
 
 <!-- DOWNLOADS -->
-[gd]: https://img.shields.io/npm/dm/got.svg
-[rd]: https://img.shields.io/npm/dm/request.svg
-[nd]: https://img.shields.io/npm/dm/node-fetch.svg
-[ad]: https://img.shields.io/npm/dm/axios.svg
+[gd]: https://badgen.net/npm/dm/got?label
+[rd]: https://badgen.net/npm/dm/request?label
+[nd]: https://badgen.net/npm/dm/node-fetch?label
+[ad]: https://badgen.net/npm/dm/axios?label
+[sd]: https://badgen.net/npm/dm/superagent?label
+
+[g3]: https://www.npmjs.com/package/got
+[r3]: https://www.npmjs.com/package/request
+[n3]: https://www.npmjs.com/package/node-fetch
+[a3]: https://www.npmjs.com/package/axios
+[s3]: https://www.npmjs.com/package/superagent
 
 <!-- COVERAGE -->
-[gc]: https://coveralls.io/repos/github/sindresorhus/got/badge.svg?branch=master
-[rc]: https://coveralls.io/repos/github/request/request/badge.svg?branch=master
-[nc]: https://coveralls.io/repos/github/bitinn/node-fetch/badge.svg?branch=master
-[ac]: https://coveralls.io/repos/github/mzabriskie/axios/badge.svg?branch=master
+[gc]: https://badgen.net/coveralls/c/github/sindresorhus/got?label
+[rc]: https://badgen.net/coveralls/c/github/request/request?label
+[nc]: https://badgen.net/coveralls/c/github/bitinn/node-fetch?label
+[ac]: https://badgen.net/coveralls/c/github/mzabriskie/axios?label
+
+[g4]: https://coveralls.io/github/sindresorhus/got
+[r4]: https://coveralls.io/github/request/request
+[n4]: https://coveralls.io/github/bitinn/node-fetch
+[a4]: https://coveralls.io/github/mzabriskie/axios
 
 <!-- BUILD -->
-[gb]: https://travis-ci.org/sindresorhus/got.svg?branch=master
-[rb]: https://travis-ci.org/request/request.svg?branch=master
-[nb]: https://travis-ci.org/bitinn/node-fetch.svg?branch=master
-[ab]: https://travis-ci.org/axios/axios.svg?branch=master
+[gb]: https://badgen.net/travis/sindresorhus/got?label
+[rb]: https://badgen.net/travis/request/request?label
+[nb]: https://badgen.net/travis/bitinn/node-fetch?label
+[ab]: https://badgen.net/travis/axios/axios?label
+[sb]: https://badgen.net/travis/visionmedia/superagent?label
+
+[g5]: https://travis-ci.org/sindresorhus/got
+[r5]: https://travis-ci.org/request/request
+[n5]: https://travis-ci.org/bitinn/node-fetch
+[a5]: https://travis-ci.org/axios/axios
+[s5]: https://travis-ci.org/visionmedia/superagent
 
 <!-- BUGS -->
-[gbg]: https://badgen.net/github/label-issues/sindresorhus/got/bug/open
-[rbg]: https://badgen.net/github/label-issues/request/request/Needs%20investigation/open
-[nbg]: https://badgen.net/github/label-issues/bitinn/node-fetch/bug/open
-[abg]: https://badgen.net/github/label-issues/axios/axios/bug/open
+[gbg]: https://badgen.net/github/label-issues/sindresorhus/got/bug/open?label
+[rbg]: https://badgen.net/github/label-issues/request/request/Needs%20investigation/open?label
+[nbg]: https://badgen.net/github/label-issues/bitinn/node-fetch/bug/open?label
+[abg]: https://badgen.net/github/label-issues/axios/axios/bug/open?label
+[sbg]: https://badgen.net/github/label-issues/visionmedia/superagent/Bug/open?label
+
+[g6]: https://github.com/sindresorhus/got/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug
+[r6]: https://github.com/request/request/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A"Needs+investigation"
+[n6]: https://github.com/bitinn/node-fetch/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug
+[a6]: https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug
+[s6]: https://github.com/visionmedia/superagent/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3ABug
 
 <!-- DEPENDENTS -->
-[gdp]: https://badgen.net/npm/dependents/got
-[rdp]: https://badgen.net/npm/dependents/request
-[ndp]: https://badgen.net/npm/dependents/node-fetch
-[adp]: https://badgen.net/npm/dependents/axios
+[gdp]: https://badgen.net/npm/dependents/got?label
+[rdp]: https://badgen.net/npm/dependents/request?label
+[ndp]: https://badgen.net/npm/dependents/node-fetch?label
+[adp]: https://badgen.net/npm/dependents/axios?label
+[sdp]: https://badgen.net/npm/dependents/superagent?label
+
+[g7]: https://www.npmjs.com/package/got?activeTab=dependents
+[r7]: https://www.npmjs.com/package/request?activeTab=dependents
+[n7]: https://www.npmjs.com/package/node-fetch?activeTab=dependents
+[a7]: https://www.npmjs.com/package/axios?activeTab=dependents
+[s7]: https://www.npmjs.com/package/visionmedia?activeTab=dependents
 
 <!-- INSTALL SIZE -->
-[gis]: https://packagephobia.now.sh/badge?p=got
-[ris]: https://packagephobia.now.sh/badge?p=request
-[nis]: https://packagephobia.now.sh/badge?p=node-fetch
-[ais]: https://packagephobia.now.sh/badge?p=axios
+[gis]: https://badgen.net/packagephobia/install/got?label
+[ris]: https://badgen.net/packagephobia/install/request?label
+[nis]: https://badgen.net/packagephobia/install/node-fetch?label
+[ais]: https://badgen.net/packagephobia/install/axios?label
+[sis]: https://badgen.net/packagephobia/install/superagent?label
+
+[g8]: https://packagephobia.now.sh/result?p=got
+[r8]: https://packagephobia.now.sh/result?p=request
+[n8]: https://packagephobia.now.sh/result?p=node-fetch
+[a8]: https://packagephobia.now.sh/result?p=axios
+[s8]: https://packagephobia.now.sh/result?p=superagent
 
 
 ## Related

package/source/as-promise.js

@@ -81,6 +81,7 @@ const asPromise = options => {
 
 					resolve(response);
 				}
+
 				return;
 			}
 

package/source/as-stream.js

@@ -83,6 +83,7 @@ module.exports = options => {
 
 		return result;
 	};
+
 	proxy.unpipe = stream => {
 		piped.delete(stream);
 		return unpipe(stream);

package/source/errors.js

@@ -5,7 +5,7 @@ const PCancelable = require('p-cancelable');
 const is = require('@sindresorhus/is');
 
 class GotError extends Error {
-	constructor(message, error, opts) {
+	constructor(message, error, options) {
 		super(message);
 		Error.captureStackTrace(this, this.constructor);
 		this.name = 'GotError';
@@ -15,13 +15,14 @@ class GotError extends Error {
 		}
 
 		Object.assign(this, {
-			host: opts.host,
-			hostname: opts.hostname,
-			method: opts.method,
-			path: opts.path,
-			socketPath: opts.socketPath,
-			protocol: opts.protocol,
-			url: opts.href
+			host: options.host,
+			hostname: options.hostname,
+			method: options.method,
+			path: options.path,
+			socketPath: options.socketPath,
+			protocol: options.protocol,
+			url: options.href,
+			gotOptions: options
 		});
 	}
 }
@@ -29,29 +30,29 @@ class GotError extends Error {
 module.exports.GotError = GotError;
 
 module.exports.CacheError = class extends GotError {
-	constructor(error, opts) {
-		super(error.message, error, opts);
+	constructor(error, options) {
+		super(error.message, error, options);
 		this.name = 'CacheError';
 	}
 };
 
 module.exports.RequestError = class extends GotError {
-	constructor(error, opts) {
-		super(error.message, error, opts);
+	constructor(error, options) {
+		super(error.message, error, options);
 		this.name = 'RequestError';
 	}
 };
 
 module.exports.ReadError = class extends GotError {
-	constructor(error, opts) {
-		super(error.message, error, opts);
+	constructor(error, options) {
+		super(error.message, error, options);
 		this.name = 'ReadError';
 	}
 };
 
 module.exports.ParseError = class extends GotError {
-	constructor(error, statusCode, opts, data) {
-		super(`${error.message} in "${urlLib.format(opts)}": \n${data.slice(0, 77)}...`, error, opts);
+	constructor(error, statusCode, options, data) {
+		super(`${error.message} in "${urlLib.format(options)}": \n${data.slice(0, 77)}...`, error, options);
 		this.name = 'ParseError';
 		this.statusCode = statusCode;
 		this.statusMessage = http.STATUS_CODES[this.statusCode];
@@ -59,7 +60,7 @@ module.exports.ParseError = class extends GotError {
 };
 
 module.exports.HTTPError = class extends GotError {
-	constructor(response, opts) {
+	constructor(response, options) {
 		const {statusCode} = response;
 		let {statusMessage} = response;
 
@@ -68,7 +69,8 @@ module.exports.HTTPError = class extends GotError {
 		} else {
 			statusMessage = http.STATUS_CODES[statusCode];
 		}
-		super(`Response code ${statusCode} (${statusMessage})`, {}, opts);
+
+		super(`Response code ${statusCode} (${statusMessage})`, {}, options);
 		this.name = 'HTTPError';
 		this.statusCode = statusCode;
 		this.statusMessage = statusMessage;
@@ -78,8 +80,8 @@ module.exports.HTTPError = class extends GotError {
 };
 
 module.exports.MaxRedirectsError = class extends GotError {
-	constructor(statusCode, redirectUrls, opts) {
-		super('Redirected 10 times. Aborting.', {}, opts);
+	constructor(statusCode, redirectUrls, options) {
+		super('Redirected 10 times. Aborting.', {}, options);
 		this.name = 'MaxRedirectsError';
 		this.statusCode = statusCode;
 		this.statusMessage = http.STATUS_CODES[this.statusCode];
@@ -88,15 +90,15 @@ module.exports.MaxRedirectsError = class extends GotError {
 };
 
 module.exports.UnsupportedProtocolError = class extends GotError {
-	constructor(opts) {
-		super(`Unsupported protocol "${opts.protocol}"`, {}, opts);
+	constructor(options) {
+		super(`Unsupported protocol "${options.protocol}"`, {}, options);
 		this.name = 'UnsupportedProtocolError';
 	}
 };
 
 module.exports.TimeoutError = class extends GotError {
-	constructor(error, opts) {
-		super(error.message, {code: 'ETIMEDOUT'}, opts);
+	constructor(error, options) {
+		super(error.message, {code: 'ETIMEDOUT'}, options);
 		this.name = 'TimeoutError';
 		this.event = error.event;
 	}

package/source/index.js

@@ -22,6 +22,16 @@ const defaults = {
 				502,
 				503,
 				504
+			],
+			errorCodes: [
+				'ETIMEDOUT',
+				'ECONNRESET',
+				'EADDRINUSE',
+				'ECONNREFUSED',
+				'EPIPE',
+				'ENOTFOUND',
+				'ENETUNREACH',
+				'EAI_AGAIN'
 			]
 		},
 		headers: {

package/source/known-hook-events.js

@@ -1,6 +1,8 @@
 'use strict';
 
 module.exports = [
+	'beforeError',
+	'init',
 	'beforeRequest',
 	'beforeRedirect',
 	'beforeRetry',

package/source/normalize-arguments.js

@@ -4,7 +4,6 @@ const urlLib = require('url');
 const is = require('@sindresorhus/is');
 const urlParseLax = require('url-parse-lax');
 const lowercaseKeys = require('lowercase-keys');
-const isRetryOnNetworkErrorAllowed = require('./utils/is-retry-on-network-error-allowed');
 const urlToOptions = require('./utils/url-to-options');
 const isFormData = require('./utils/is-form-data');
 const merge = require('./merge');
@@ -12,8 +11,15 @@ const knownHookEvents = require('./known-hook-events');
 
 const retryAfterStatusCodes = new Set([413, 429, 503]);
 
-// `preNormalize` handles static things (lowercasing headers; normalizing baseUrl, timeout, retry)
-// While `normalize` does `preNormalize` + handles things which need to be reworked when user changes them
+// `preNormalize` handles static options (e.g. headers).
+// For example, when you create a custom instance and make a request
+// with no static changes, they won't be normalized again.
+//
+// `normalize` operates on dynamic options - they cannot be saved.
+// For example, `body` is everytime different per request.
+// When it's done normalizing the new options, it performs merge()
+// on the prenormalized options and the normalized ones.
+
 const preNormalize = (options, defaults) => {
 	if (is.nullOrUndefined(options.headers)) {
 		options.headers = {};
@@ -50,13 +56,15 @@ const preNormalize = (options, defaults) => {
 	} else if (is.object(options.timeout)) {
 		options.gotTimeout = options.timeout;
 	}
+
 	delete options.timeout;
 
 	const {retry} = options;
 	options.retry = {
 		retries: 0,
 		methods: [],
-		statusCodes: []
+		statusCodes: [],
+		errorCodes: []
 	};
 
 	if (is.nonEmptyObject(defaults) && retry !== false) {
@@ -83,6 +91,10 @@ const preNormalize = (options, defaults) => {
 		options.retry.statusCodes = new Set(options.retry.statusCodes);
 	}
 
+	if (is.array(options.retry.errorCodes)) {
+		options.retry.errorCodes = new Set(options.retry.errorCodes);
+	}
+
 	return options;
 };
 
@@ -96,7 +108,7 @@ const normalize = (url, options, defaults) => {
 	if (defaults) {
 		options = merge({}, defaults.options, options ? preNormalize(options, defaults.options) : {});
 	} else {
-		options = merge({}, options ? preNormalize(options) : {});
+		options = merge({}, preNormalize(options));
 	}
 
 	if (!is.string(url) && !is.object(url)) {
@@ -112,11 +124,7 @@ const normalize = (url, options, defaults) => {
 			url = urlToOptions(new URL(url, options.baseUrl));
 		} else {
 			url = url.replace(/^unix:/, 'http://$&');
-
 			url = urlParseLax(url);
-			if (url.auth) {
-				throw new Error('Basic authentication must be done with the `auth` option');
-			}
 		}
 	} else if (is(url) === 'URL') {
 		url = urlToOptions(url);
@@ -125,6 +133,14 @@ const normalize = (url, options, defaults) => {
 	// Override both null/undefined with default protocol
 	options = merge({path: ''}, url, {protocol: url.protocol || 'https:'}, options);
 
+	for (const hook of options.hooks.init) {
+		const called = hook(options);
+
+		if (is.promise(called)) {
+			throw new TypeError('The `init` hook must be a synchronous function');
+		}
+	}
+
 	const {baseUrl} = options;
 	Object.defineProperty(options, 'baseUrl', {
 		set: () => {
@@ -138,6 +154,7 @@ const normalize = (url, options, defaults) => {
 		if (!is.string(query)) {
 			options.query = (new URLSearchParams(query)).toString();
 		}
+
 		options.path = `${options.path.split('?')[0]}?${options.query}`;
 		delete options.query;
 	}
@@ -210,29 +227,27 @@ const normalize = (url, options, defaults) => {
 				return 0;
 			}
 
-			if (error !== null) {
-				if (!isRetryOnNetworkErrorAllowed(error) && (!options.retry.methods.has(error.method) || !options.retry.statusCodes.has(error.statusCode))) {
-					return 0;
-				}
-
-				if (Reflect.has(error, 'headers') && Reflect.has(error.headers, 'retry-after') && retryAfterStatusCodes.has(error.statusCode)) {
-					let after = Number(error.headers['retry-after']);
-					if (is.nan(after)) {
-						after = Date.parse(error.headers['retry-after']) - Date.now();
-					} else {
-						after *= 1000;
-					}
-
-					if (after > options.retry.maxRetryAfter) {
-						return 0;
-					}
+			if ((!error || !options.retry.errorCodes.has(error.code)) && (!options.retry.methods.has(error.method) || !options.retry.statusCodes.has(error.statusCode))) {
+				return 0;
+			}
 
-					return after;
+			if (Reflect.has(error, 'headers') && Reflect.has(error.headers, 'retry-after') && retryAfterStatusCodes.has(error.statusCode)) {
+				let after = Number(error.headers['retry-after']);
+				if (is.nan(after)) {
+					after = Date.parse(error.headers['retry-after']) - Date.now();
+				} else {
+					after *= 1000;
 				}
 
-				if (error.statusCode === 413) {
+				if (after > options.retry.maxRetryAfter) {
 					return 0;
 				}
+
+				return after;
+			}
+
+			if (error.statusCode === 413) {
+				return 0;
 			}
 
 			const noise = Math.random() * 100;

package/source/request-as-event-emitter.js

@@ -33,6 +33,19 @@ module.exports = (options, input) => {
 	const getCookieString = options.cookieJar ? util.promisify(options.cookieJar.getCookieString.bind(options.cookieJar)) : null;
 	const agents = is.object(options.agent) ? options.agent : null;
 
+	const emitError = async error => {
+		try {
+			for (const hook of options.hooks.beforeError) {
+				// eslint-disable-next-line no-await-in-loop
+				error = await hook(error);
+			}
+
+			emitter.emit('error', error);
+		} catch (error2) {
+			emitter.emit('error', error2);
+		}
+	};
+
 	const get = async options => {
 		const currentUrl = redirectString || requestUrl;
 
@@ -92,6 +105,9 @@ module.exports = (options, input) => {
 				response.retryCount = retryCount;
 				response.timings = timings;
 				response.redirectUrls = redirects;
+				response.request = {
+					gotOptions: options
+				};
 
 				const rawCookies = response.headers['set-cookie'];
 				if (options.cookieJar && rawCookies) {
@@ -119,26 +135,26 @@ module.exports = (options, input) => {
 
 						redirects.push(redirectString);
 
-						const redirectOpts = {
+						const redirectOptions = {
 							...options,
 							...urlToOptions(redirectURL)
 						};
 
 						for (const hook of options.hooks.beforeRedirect) {
 							// eslint-disable-next-line no-await-in-loop
-							await hook(redirectOpts);
+							await hook(redirectOptions);
 						}
 
-						emitter.emit('redirect', response, redirectOpts);
+						emitter.emit('redirect', response, redirectOptions);
 
-						await get(redirectOpts);
+						await get(redirectOptions);
 						return;
 					}
 				}
 
 				getResponse(response, options, emitter);
 			} catch (error) {
-				emitter.emit('error', error);
+				emitError(error);
 			}
 		};
 
@@ -163,7 +179,7 @@ module.exports = (options, input) => {
 				}
 
 				if (emitter.retry(error) === false) {
-					emitter.emit('error', error);
+					emitError(error);
 				}
 			});
 
@@ -195,29 +211,29 @@ module.exports = (options, input) => {
 					request.end(uploadComplete);
 				}
 			} catch (error) {
-				emitter.emit('error', new RequestError(error, options));
+				emitError(new RequestError(error, options));
 			}
 		};
 
 		if (options.cache) {
 			const cacheableRequest = new CacheableRequest(fn.request, options.cache);
-			const cacheReq = cacheableRequest(options, handleResponse);
+			const cacheRequest = cacheableRequest(options, handleResponse);
 
-			cacheReq.once('error', error => {
+			cacheRequest.once('error', error => {
 				if (error instanceof CacheableRequest.RequestError) {
-					emitter.emit('error', new RequestError(error, options));
+					emitError(new RequestError(error, options));
 				} else {
-					emitter.emit('error', new CacheError(error, options));
+					emitError(new CacheError(error, options));
 				}
 			});
 
-			cacheReq.once('request', handleRequest);
+			cacheRequest.once('request', handleRequest);
 		} else {
 			// Catches errors thrown by calling fn.request(...)
 			try {
 				handleRequest(fn.request(options, handleResponse));
 			} catch (error) {
-				emitter.emit('error', new RequestError(error, options));
+				emitError(new RequestError(error, options));
 			}
 		}
 	};
@@ -228,7 +244,7 @@ module.exports = (options, input) => {
 		try {
 			backoff = options.retry.retries(++retryCount, error);
 		} catch (error2) {
-			emitter.emit('error', error2);
+			emitError(error2);
 			return;
 		}
 
@@ -242,7 +258,7 @@ module.exports = (options, input) => {
 
 					await get(options);
 				} catch (error) {
-					emitter.emit('error', error);
+					emitError(error);
 				}
 			};
 
@@ -288,7 +304,7 @@ module.exports = (options, input) => {
 
 			await get(options);
 		} catch (error) {
-			emitter.emit('error', error);
+			emitError(error);
 		}
 	});
 

package/source/utils/timed-out.js

@@ -82,9 +82,16 @@ module.exports = (request, delays, options) => {
 	}
 
 	if (delays.socket !== undefined) {
-		request.setTimeout(delays.socket, () => {
+		const socketTimeoutHandler = () => {
 			timeoutHandler(delays.socket, 'socket');
-		});
+		};
+
+		request.setTimeout(delays.socket, socketTimeoutHandler);
+
+		// `request.setTimeout(0)` causes a memory leak.
+		// We can just remove the listener and forget about the timer - it's unreffed.
+		// See https://github.com/sindresorhus/got/issues/690
+		cancelers.push(() => request.removeListener('timeout', socketTimeoutHandler));
 	}
 
 	if (delays.lookup !== undefined && !request.socketPath && !net.isIP(hostname || host)) {

package/source/utils/is-retry-on-network-error-allowed.js

@@ -1,20 +0,0 @@
-'use strict';
-
-const WHITELIST = new Set([
-	'ETIMEDOUT',
-	'ECONNRESET',
-	'EADDRINUSE',
-	'ECONNREFUSED',
-	'EPIPE',
-	'ENOTFOUND',
-	'ENETUNREACH',
-	'EAI_AGAIN'
-]);
-
-module.exports = error => {
-	if (error && WHITELIST.has(error.code)) {
-		return true;
-	}
-
-	return false;
-};