got 11.4.0 → 11.6.0

package/dist/source/core/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedProtocolError = exports.ReadError = exports.TimeoutError = exports.UploadError = exports.CacheError = exports.HTTPError = exports.MaxRedirectsError = exports.RequestError = exports.setNonEnumerableProperties = exports.knownHookEvents = exports.withoutBody = exports.kIsNormalizedAlready = void 0;
 const util_1 = require("util");
 const stream_1 = require("stream");
 const fs_1 = require("fs");
@@ -11,7 +12,7 @@ const http_timer_1 = require("@szmarczak/http-timer");
 const cacheable_lookup_1 = require("cacheable-lookup");
 const CacheableRequest = require("cacheable-request");
 const decompressResponse = require("decompress-response");
-// @ts-ignore Missing types
+// @ts-expect-error Missing types
 const http2wrapper = require("http2-wrapper");
 const lowercaseKeys = require("lowercase-keys");
 const is_1 = require("@sindresorhus/is");
@@ -24,7 +25,11 @@ const options_to_url_1 = require("./utils/options-to-url");
 const weakable_map_1 = require("./utils/weakable-map");
 const get_buffer_1 = require("./utils/get-buffer");
 const dns_ip_version_1 = require("./utils/dns-ip-version");
+const is_response_ok_1 = require("./utils/is-response-ok");
 const deprecation_warning_1 = require("../utils/deprecation-warning");
+const normalize_arguments_1 = require("../as-promise/normalize-arguments");
+const calculate_retry_delay_1 = require("./calculate-retry-delay");
+const globalDnsCache = new cacheable_lookup_1.default();
 const kRequest = Symbol('request');
 const kResponse = Symbol('response');
 const kResponseSize = Symbol('responseSize');
@@ -41,10 +46,19 @@ const kTriggerRead = Symbol('triggerRead');
 const kBody = Symbol('body');
 const kJobs = Symbol('jobs');
 const kOriginalResponse = Symbol('originalResponse');
+const kRetryTimeout = Symbol('retryTimeout');
 exports.kIsNormalizedAlready = Symbol('isNormalizedAlready');
 const supportsBrotli = is_1.default.string(process.versions.brotli);
 exports.withoutBody = new Set(['GET', 'HEAD']);
-exports.knownHookEvents = ['init', 'beforeRequest', 'beforeRedirect', 'beforeError'];
+exports.knownHookEvents = [
+    'init',
+    'beforeRequest',
+    'beforeRedirect',
+    'beforeError',
+    'beforeRetry',
+    // Promise-Only
+    'afterResponse'
+];
 function validateSearchParameters(searchParameters) {
     // eslint-disable-next-line guard-for-in
     for (const key in searchParameters) {
@@ -62,6 +76,7 @@ const waitForOpenFile = async (file) => new Promise((resolve, reject) => {
     const onError = (error) => {
         reject(error);
     };
+    // Node.js 12 has incomplete types
     if (!file.pending) {
         resolve();
     }
@@ -93,13 +108,17 @@ exports.setNonEnumerableProperties = (sources, to) => {
                 writable: true,
                 configurable: true,
                 enumerable: false,
-                // @ts-ignore TS doesn't see the check above
+                // @ts-expect-error TS doesn't see the check above
                 value: source[name]
             };
         }
     }
     Object.defineProperties(to, properties);
 };
+/**
+An error to be thrown when a request fails.
+Contains a `code` property with error class code, like `ECONNREFUSED`.
+*/
 class RequestError extends Error {
     constructor(message, error, self) {
         var _a;
@@ -146,6 +165,10 @@ class RequestError extends Error {
     }
 }
 exports.RequestError = RequestError;
+/**
+An error to be thrown when the server redirects you more than ten times.
+Includes a `response` property.
+*/
 class MaxRedirectsError extends RequestError {
     constructor(request) {
         super(`Redirected ${request.options.maxRedirects} times. Aborting.`, {}, request);
@@ -153,6 +176,10 @@ class MaxRedirectsError extends RequestError {
     }
 }
 exports.MaxRedirectsError = MaxRedirectsError;
+/**
+An error to be thrown when the server response code is not 2xx nor 3xx if `options.followRedirect` is `true`, but always except for 304.
+Includes a `response` property.
+*/
 class HTTPError extends RequestError {
     constructor(response) {
         super(`Response code ${response.statusCode} (${response.statusMessage})`, {}, response.request);
@@ -160,6 +187,10 @@ class HTTPError extends RequestError {
     }
 }
 exports.HTTPError = HTTPError;
+/**
+An error to be thrown when a cache method fails.
+For example, if the database goes down or there's a filesystem error.
+*/
 class CacheError extends RequestError {
     constructor(error, request) {
         super(error.message, error, request);
@@ -167,6 +198,9 @@ class CacheError extends RequestError {
     }
 }
 exports.CacheError = CacheError;
+/**
+An error to be thrown when the request body is a stream and an error occurs while reading from that stream.
+*/
 class UploadError extends RequestError {
     constructor(error, request) {
         super(error.message, error, request);
@@ -174,6 +208,10 @@ class UploadError extends RequestError {
     }
 }
 exports.UploadError = UploadError;
+/**
+An error to be thrown when the request is aborted due to a timeout.
+Includes an `event` and `timings` property.
+*/
 class TimeoutError extends RequestError {
     constructor(error, timings, request) {
         super(error.message, error, request);
@@ -183,6 +221,9 @@ class TimeoutError extends RequestError {
     }
 }
 exports.TimeoutError = TimeoutError;
+/**
+An error to be thrown when reading from response stream fails.
+*/
 class ReadError extends RequestError {
     constructor(error, request) {
         super(error.message, error, request);
@@ -190,6 +231,9 @@ class ReadError extends RequestError {
     }
 }
 exports.ReadError = ReadError;
+/**
+An error to be thrown when given an unsupported protocol.
+*/
 class UnsupportedProtocolError extends RequestError {
     constructor(options) {
         super(`Unsupported protocol "${options.url.protocol}"`, {}, options);
@@ -208,6 +252,9 @@ const proxiedRequestEvents = [
 class Request extends stream_1.Duplex {
     constructor(url, options = {}, defaults) {
         super({
+            // This must be false, to enable throwing after destroy
+            // It is used for retry logic in Promise API
+            autoDestroy: false,
             // It needs to be zero because we're just proxying the data to another stream
             highWaterMark: 0
         });
@@ -219,6 +266,7 @@ class Request extends stream_1.Duplex {
         this[kStopReading] = false;
         this[kTriggerRead] = false;
         this[kJobs] = [];
+        this.retryCount = 0;
         // TODO: Remove this when targeting Node.js >= 12
         this._progressCallbacks = [];
         const unlockWrite = () => this._unlockWrite();
@@ -257,7 +305,7 @@ class Request extends stream_1.Duplex {
                     this.options = nonNormalizedOptions;
                 }
                 else {
-                    // @ts-ignore Common TypeScript bug saying that `this.constructor` is not accessible
+                    // @ts-expect-error Common TypeScript bug saying that `this.constructor` is not accessible
                     this.options = this.constructor.normalizeArguments(url, nonNormalizedOptions, defaults);
                 }
                 const { url: normalizedURL } = this.options;
@@ -276,6 +324,8 @@ class Request extends stream_1.Duplex {
                 for (const job of this[kJobs]) {
                     job();
                 }
+                // Prevent memory leak
+                this[kJobs].length = 0;
                 this.requestInitialized = true;
             }
             catch (error) {
@@ -345,6 +395,7 @@ class Request extends stream_1.Duplex {
             is_1.assert.any([is_1.default.string, is_1.default.object, is_1.default.array, is_1.default.undefined], options.https.certificate);
             is_1.assert.any([is_1.default.string, is_1.default.undefined], options.https.passphrase);
         }
+        is_1.assert.any([is_1.default.object, is_1.default.undefined], options.cacheOptions);
         // `options.method`
         if (is_1.default.string(options.method)) {
             options.method = options.method.toUpperCase();
@@ -442,6 +493,7 @@ class Request extends stream_1.Duplex {
             }
             // Set search params
             if (options.searchParams) {
+                // eslint-disable-next-line @typescript-eslint/no-base-to-string
                 options.url.search = options.searchParams.toString();
             }
             // Protocol check
@@ -475,7 +527,7 @@ class Request extends stream_1.Duplex {
                 getCookieString = util_1.promisify(getCookieString.bind(options.cookieJar));
                 options.cookieJar = {
                     setCookie,
-                    getCookieString
+                    getCookieString: getCookieString
                 };
             }
         }
@@ -483,12 +535,44 @@ class Request extends stream_1.Duplex {
         const { cache } = options;
         if (cache) {
             if (!cacheableStore.has(cache)) {
-                cacheableStore.set(cache, new CacheableRequest(((requestOptions, handler) => requestOptions[kRequest](requestOptions, handler)), cache));
+                cacheableStore.set(cache, new CacheableRequest(((requestOptions, handler) => {
+                    const result = requestOptions[kRequest](requestOptions, handler);
+                    // TODO: remove this when `cacheable-request` supports async request functions.
+                    if (is_1.default.promise(result)) {
+                        // @ts-expect-error
+                        // We only need to implement the error handler in order to support HTTP2 caching.
+                        // The result will be a promise anyway.
+                        result.once = (event, handler) => {
+                            if (event === 'error') {
+                                result.catch(handler);
+                            }
+                            else if (event === 'abort') {
+                                // The empty catch is needed here in case when
+                                // it rejects before it's `await`ed in `_makeRequest`.
+                                (async () => {
+                                    try {
+                                        const request = (await result);
+                                        request.once('abort', handler);
+                                    }
+                                    catch (_a) { }
+                                })();
+                            }
+                            else {
+                                /* istanbul ignore next: safety check */
+                                throw new Error(`Unknown HTTP2 promise event: ${event}`);
+                            }
+                            return result;
+                        };
+                    }
+                    return result;
+                }), cache));
             }
         }
+        // `options.cacheOptions`
+        options.cacheOptions = { ...options.cacheOptions };
         // `options.dnsCache`
         if (options.dnsCache === true) {
-            options.dnsCache = new cacheable_lookup_1.default();
+            options.dnsCache = globalDnsCache;
         }
         else if (!is_1.default.undefined(options.dnsCache) && !options.dnsCache.lookup) {
             throw new TypeError(`Parameter \`dnsCache\` must be a CacheableLookup instance or a boolean, got ${is_1.default(options.dnsCache)}`);
@@ -579,7 +663,7 @@ class Request extends stream_1.Duplex {
         options.maxRedirects = (_d = options.maxRedirects) !== null && _d !== void 0 ? _d : 0;
         // Set non-enumerable properties
         exports.setNonEnumerableProperties([defaults, rawOptions], options);
-        return options;
+        return normalize_arguments_1.default(options, defaults);
     }
     _lockWrite() {
         const onLockedWrite = () => {
@@ -665,7 +749,7 @@ class Request extends stream_1.Duplex {
         }
         this[kBodySize] = Number(headers['content-length']) || undefined;
     }
-    async _onResponse(response) {
+    async _onResponseBase(response) {
         const { options } = this;
         const { url } = options;
         this[kOriginalResponse] = response;
@@ -681,6 +765,7 @@ class Request extends stream_1.Duplex {
         typedResponse.request = this;
         typedResponse.isFromCache = response.fromCache || false;
         typedResponse.ip = this.ip;
+        typedResponse.retryCount = this.retryCount;
         this[kIsFromCache] = typedResponse.isFromCache;
         this[kResponseSize] = Number(response.headers['content-length']) || undefined;
         this[kResponse] = response;
@@ -718,7 +803,7 @@ class Request extends stream_1.Duplex {
         }
         if (options.followRedirect && response.headers.location && redirectCodes.has(statusCode)) {
             // We're being redirected, we don't care about the response.
-            // It'd be besto to abort the request, but we can't because
+            // It'd be best to abort the request, but we can't because
             // we would have to sacrifice the TCP connection. We don't want that.
             response.resume();
             if (this[kRequest]) {
@@ -765,7 +850,10 @@ class Request extends stream_1.Duplex {
                         delete options.headers.authorization;
                     }
                     if (options.username || options.password) {
+                        // TODO: Fix this ignore.
+                        // @ts-expect-error
                         delete options.username;
+                        // @ts-expect-error
                         delete options.password;
                     }
                 }
@@ -784,13 +872,9 @@ class Request extends stream_1.Duplex {
             }
             return;
         }
-        const limitStatusCode = options.followRedirect ? 299 : 399;
-        const isOk = (statusCode >= 200 && statusCode <= limitStatusCode) || statusCode === 304;
-        if (options.throwHttpErrors && !isOk) {
-            await this._beforeError(new HTTPError(typedResponse));
-            if (this.destroyed) {
-                return;
-            }
+        if (options.isStream && options.throwHttpErrors && !is_response_ok_1.isResponseOk(typedResponse)) {
+            this._beforeError(new HTTPError(typedResponse));
+            return;
         }
         response.on('readable', () => {
             if (this[kTriggerRead]) {
@@ -822,6 +906,15 @@ class Request extends stream_1.Duplex {
             destination.statusCode = statusCode;
         }
     }
+    async _onResponse(response) {
+        try {
+            await this._onResponseBase(response);
+        }
+        catch (error) {
+            /* istanbul ignore next: better safe than sorry */
+            this._beforeError(error);
+        }
+    }
     _onRequest(request) {
         const { options } = this;
         const { timeout, url } = options;
@@ -829,11 +922,14 @@ class Request extends stream_1.Duplex {
         this[kCancelTimeouts] = timed_out_1.default(request, timeout, url);
         const responseEventName = options.cache ? 'cacheableResponse' : 'response';
         request.once(responseEventName, (response) => {
-            this._onResponse(response);
+            void this._onResponse(response);
         });
         request.once('error', (error) => {
+            var _a;
             // Force clean-up, because some packages (e.g. nock) don't do this.
             request.destroy();
+            // Node.js <= 12.18.2 mistakenly emits the response `end` first.
+            (_a = request.res) === null || _a === void 0 ? void 0 : _a.removeAllListeners('end');
             if (error instanceof timed_out_1.TimeoutError) {
                 error = new TimeoutError(error, this.timings, this);
             }
@@ -853,14 +949,11 @@ class Request extends stream_1.Duplex {
             body.once('error', (error) => {
                 this._beforeError(new UploadError(error, this));
             });
-            body.once('end', () => {
-                delete options.body;
-            });
         }
         else {
             this._unlockWrite();
             if (!is_1.default.undefined(body)) {
-                this._writeRequest(body, null, () => { });
+                this._writeRequest(body, undefined, () => { });
                 currentRequest.end();
                 this._lockWrite();
             }
@@ -876,26 +969,30 @@ class Request extends stream_1.Duplex {
             // TODO: Remove `utils/url-to-options.ts` when `cacheable-request` is fixed
             Object.assign(options, url_to_options_1.default(url));
             // `http-cache-semantics` checks this
+            // TODO: Fix this ignore.
+            // @ts-expect-error
             delete options.url;
+            let request;
             // This is ugly
-            const cacheRequest = cacheableStore.get(options.cache)(options, response => {
-                const typedResponse = response;
-                const { req } = typedResponse;
+            const cacheRequest = cacheableStore.get(options.cache)(options, async (response) => {
                 // TODO: Fix `cacheable-response`
-                typedResponse._readableState.autoDestroy = false;
-                if (req) {
-                    req.emit('cacheableResponse', typedResponse);
+                response._readableState.autoDestroy = false;
+                if (request) {
+                    (await request).emit('cacheableResponse', response);
                 }
-                resolve(typedResponse);
+                resolve(response);
             });
             // Restore options
             options.url = url;
             cacheRequest.once('error', reject);
-            cacheRequest.once('request', resolve);
+            cacheRequest.once('request', async (requestOrPromise) => {
+                request = requestOrPromise;
+                resolve(request);
+            });
         });
     }
     async _makeRequest() {
-        var _a;
+        var _a, _b, _c, _d, _e;
         const { options } = this;
         const { headers } = options;
         for (const key in headers) {
@@ -921,7 +1018,7 @@ class Request extends stream_1.Duplex {
             // eslint-disable-next-line no-await-in-loop
             const result = await hook(options);
             if (!is_1.default.undefined(result)) {
-                // @ts-ignore Skip the type mismatch to support abstract responses
+                // @ts-expect-error Skip the type mismatch to support abstract responses
                 options.request = () => result;
                 break;
             }
@@ -961,14 +1058,20 @@ class Request extends stream_1.Duplex {
         // Prepare plain HTTP request options
         options[kRequest] = realFn;
         delete options.request;
+        // TODO: Fix this ignore.
+        // @ts-expect-error
         delete options.timeout;
         const requestOptions = options;
+        requestOptions.shared = (_b = options.cacheOptions) === null || _b === void 0 ? void 0 : _b.shared;
+        requestOptions.cacheHeuristic = (_c = options.cacheOptions) === null || _c === void 0 ? void 0 : _c.cacheHeuristic;
+        requestOptions.immutableMinTimeToLive = (_d = options.cacheOptions) === null || _d === void 0 ? void 0 : _d.immutableMinTimeToLive;
+        requestOptions.ignoreCargoCult = (_e = options.cacheOptions) === null || _e === void 0 ? void 0 : _e.ignoreCargoCult;
         // If `dnsLookupIpVersion` is not present do not override `family`
         if (options.dnsLookupIpVersion !== undefined) {
             try {
                 requestOptions.family = dns_ip_version_1.dnsLookupIpVersionToFamily(options.dnsLookupIpVersion);
             }
-            catch (_b) {
+            catch (_f) {
                 throw new Error('Invalid `dnsLookupIpVersion` option value');
             }
         }
@@ -1002,20 +1105,42 @@ class Request extends stream_1.Duplex {
             options.request = request;
             options.timeout = timeout;
             options.agent = agent;
+            // HTTPS options restore
+            if (options.https) {
+                if ('rejectUnauthorized' in options.https) {
+                    delete requestOptions.rejectUnauthorized;
+                }
+                if (options.https.checkServerIdentity) {
+                    // @ts-expect-error - This one will be removed when we remove the alias.
+                    delete requestOptions.checkServerIdentity;
+                }
+                if (options.https.certificateAuthority) {
+                    delete requestOptions.ca;
+                }
+                if (options.https.certificate) {
+                    delete requestOptions.cert;
+                }
+                if (options.https.key) {
+                    delete requestOptions.key;
+                }
+                if (options.https.passphrase) {
+                    delete requestOptions.passphrase;
+                }
+            }
             if (isClientRequest(requestOrResponse)) {
                 this._onRequest(requestOrResponse);
                 // Emit the response after the stream has been ended
             }
             else if (this.writable) {
                 this.once('finish', () => {
-                    this._onResponse(requestOrResponse);
+                    void this._onResponse(requestOrResponse);
                 });
                 this._unlockWrite();
                 this.end();
                 this._lockWrite();
             }
             else {
-                this._onResponse(requestOrResponse);
+                void this._onResponse(requestOrResponse);
             }
         }
         catch (error) {
@@ -1025,23 +1150,7 @@ class Request extends stream_1.Duplex {
             throw new RequestError(error.message, error, this);
         }
     }
-    async _beforeError(error) {
-        if (this.destroyed) {
-            return;
-        }
-        this[kStopReading] = true;
-        if (!(error instanceof RequestError)) {
-            error = new RequestError(error.message, error, this);
-        }
-        try {
-            const { response } = error;
-            if (response) {
-                response.setEncoding(this._readableState.encoding);
-                response.rawBody = await get_buffer_1.default(response);
-                response.body = response.rawBody.toString();
-            }
-        }
-        catch (_) { }
+    async _error(error) {
         try {
             for (const hook of this.options.hooks.beforeError) {
                 // eslint-disable-next-line no-await-in-loop
@@ -1053,6 +1162,87 @@ class Request extends stream_1.Duplex {
         }
         this.destroy(error);
     }
+    _beforeError(error) {
+        if (this[kStopReading]) {
+            return;
+        }
+        const { options } = this;
+        const retryCount = this.retryCount + 1;
+        this[kStopReading] = true;
+        if (!(error instanceof RequestError)) {
+            error = new RequestError(error.message, error, this);
+        }
+        const typedError = error;
+        const { response } = typedError;
+        void (async () => {
+            if (response && !response.body) {
+                response.setEncoding(this._readableState.encoding);
+                try {
+                    response.rawBody = await get_buffer_1.default(response);
+                }
+                catch (_a) { }
+                response.body = response.rawBody.toString();
+            }
+            if (this.listenerCount('retry') !== 0) {
+                let backoff;
+                try {
+                    let retryAfter;
+                    if (response && 'retry-after' in response.headers) {
+                        retryAfter = Number(response.headers['retry-after']);
+                        if (Number.isNaN(retryAfter)) {
+                            retryAfter = Date.parse(response.headers['retry-after']) - Date.now();
+                            if (retryAfter <= 0) {
+                                retryAfter = 1;
+                            }
+                        }
+                        else {
+                            retryAfter *= 1000;
+                        }
+                    }
+                    backoff = await options.retry.calculateDelay({
+                        attemptCount: retryCount,
+                        retryOptions: options.retry,
+                        error: typedError,
+                        retryAfter,
+                        computedValue: calculate_retry_delay_1.default({
+                            attemptCount: retryCount,
+                            retryOptions: options.retry,
+                            error: typedError,
+                            retryAfter,
+                            computedValue: 0
+                        })
+                    });
+                }
+                catch (error_) {
+                    void this._error(new RequestError(error_.message, error_, this));
+                    return;
+                }
+                if (backoff) {
+                    const retry = async () => {
+                        try {
+                            for (const hook of this.options.hooks.beforeRetry) {
+                                // eslint-disable-next-line no-await-in-loop
+                                await hook(this.options, typedError, retryCount);
+                            }
+                        }
+                        catch (error_) {
+                            void this._error(new RequestError(error_.message, error, this));
+                            return;
+                        }
+                        // Something forced us to abort the retry
+                        if (this.destroyed) {
+                            return;
+                        }
+                        this.destroy();
+                        this.emit('retry', retryCount, error);
+                    };
+                    this[kRetryTimeout] = setTimeout(retry, backoff);
+                    return;
+                }
+            }
+            void this._error(typedError);
+        })();
+    }
     _read() {
         this[kTriggerRead] = true;
         const response = this[kResponse];
@@ -1074,6 +1264,7 @@ class Request extends stream_1.Duplex {
             }
         }
     }
+    // Node.js 12 has incorrect types, so the encoding must be a string
     _write(chunk, encoding, callback) {
         const write = () => {
             this._writeRequest(chunk, encoding, callback);
@@ -1135,6 +1326,9 @@ class Request extends stream_1.Duplex {
     }
     _destroy(error, callback) {
         var _a;
+        this[kStopReading] = true;
+        // Prevent further retries
+        clearTimeout(this[kRetryTimeout]);
         if (kRequest in this) {
             this[kCancelTimeouts]();
             // TODO: Remove the next `if` when these get fixed:
@@ -1148,10 +1342,19 @@ class Request extends stream_1.Duplex {
         }
         callback(error);
     }
+    get _isAboutToError() {
+        return this[kStopReading];
+    }
+    /**
+    The remote IP address.
+    */
     get ip() {
         var _a;
         return (_a = this[kRequest]) === null || _a === void 0 ? void 0 : _a.socket.remoteAddress;
     }
+    /**
+    Indicates whether the request has been aborted or not.
+    */
     get aborted() {
         var _a, _b, _c;
         return ((_b = (_a = this[kRequest]) === null || _a === void 0 ? void 0 : _a.destroyed) !== null && _b !== void 0 ? _b : this.destroyed) && !((_c = this[kOriginalResponse]) === null || _c === void 0 ? void 0 : _c.complete);
@@ -1160,6 +1363,9 @@ class Request extends stream_1.Duplex {
         var _a;
         return (_a = this[kRequest]) === null || _a === void 0 ? void 0 : _a.socket;
     }
+    /**
+    Progress event for downloading (receiving a response).
+    */
     get downloadProgress() {
         let percent;
         if (this[kResponseSize]) {
@@ -1177,6 +1383,9 @@ class Request extends stream_1.Duplex {
             total: this[kResponseSize]
         };
     }
+    /**
+    Progress event for uploading (sending a request).
+    */
     get uploadProgress() {
         let percent;
         if (this[kBodySize]) {
@@ -1194,16 +1403,43 @@ class Request extends stream_1.Duplex {
             total: this[kBodySize]
         };
     }
+    /**
+    The object contains the following properties:
+
+    - `start` - Time when the request started.
+    - `socket` - Time when a socket was assigned to the request.
+    - `lookup` - Time when the DNS lookup finished.
+    - `connect` - Time when the socket successfully connected.
+    - `secureConnect` - Time when the socket securely connected.
+    - `upload` - Time when the request finished uploading.
+    - `response` - Time when the request fired `response` event.
+    - `end` - Time when the response fired `end` event.
+    - `error` - Time when the request fired `error` event.
+    - `abort` - Time when the request fired `abort` event.
+    - `phases`
+        - `wait` - `timings.socket - timings.start`
+        - `dns` - `timings.lookup - timings.socket`
+        - `tcp` - `timings.connect - timings.lookup`
+        - `tls` - `timings.secureConnect - timings.connect`
+        - `request` - `timings.upload - (timings.secureConnect || timings.connect)`
+        - `firstByte` - `timings.response - timings.upload`
+        - `download` - `timings.end - timings.response`
+        - `total` - `(timings.end || timings.error || timings.abort) - timings.start`
+
+    If something has not been measured yet, it will be `undefined`.
+
+    __Note__: The time is a `number` representing the milliseconds elapsed since the UNIX epoch.
+    */
     get timings() {
         var _a;
         return (_a = this[kRequest]) === null || _a === void 0 ? void 0 : _a.timings;
     }
+    /**
+    Whether the response was retrieved from the cache.
+    */
     get isFromCache() {
         return this[kIsFromCache];
     }
-    get _response() {
-        return this[kResponse];
-    }
     pipe(destination, options) {
         if (this[kStartedReading]) {
             throw new Error('Failed to pipe. The response has been emitted already.');