got 14.4.9 → 14.6.0

package/dist/source/core/options.d.ts

@@ -7,13 +7,15 @@ import type { Socket } from 'node:net';
 import CacheableLookup from 'cacheable-lookup';
 import http2wrapper, { type ClientHttp2Session } from 'http2-wrapper';
 import { type FormDataLike } from 'form-data-encoder';
-import type { StorageAdapter } from 'cacheable-request';
+import type { KeyvStoreAdapter } from 'keyv';
+import type KeyvType from 'keyv';
 import type ResponseLike from 'responselike';
 import type { IncomingMessageWithTimings } from '@szmarczak/http-timer';
 import type { CancelableRequest } from '../as-promise/types.js';
 import type { PlainResponse, Response } from './response.js';
 import type { RequestError } from './errors.js';
 import type { Delays } from './timed-out.js';
+type StorageAdapter = KeyvStoreAdapter | KeyvType | Map<any, any>;
 type Promisable<T> = T | Promise<T>;
 export type DnsLookupIpVersion = undefined | 4 | 6;
 type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;
@@ -37,9 +39,34 @@ export type PromiseCookieJar = {
     getCookieString: (url: string) => Promise<string>;
     setCookie: (rawCookie: string, url: string) => Promise<unknown>;
 };
+/**
+Utility type to override specific properties in a type.
+
+Uses `Omit` to remove properties before adding them back to ensure proper type replacement rather than intersection, which handles edge cases with optional/required properties correctly.
+*/
+type OverrideProperties<T, U> = Omit<T, keyof U> & U;
+/**
+Represents the runtime state of Options as seen by hooks after normalization.
+
+Some Options properties accept multiple input types but are normalized to a single type internally by the Options class setters. This type reflects the actual runtime types that hooks receive, ensuring type safety when accessing options within hook functions.
+*/
+export type NormalizedOptions = OverrideProperties<Options, {
+    url: URL | undefined;
+    dnsCache: CacheableLookup | undefined;
+    cache: StorageAdapter | undefined;
+    prefixUrl: string;
+}>;
 export type InitHook = (init: OptionsInit, self: Options) => void;
-export type BeforeRequestHook = (options: Options) => Promisable<void | Response | ResponseLike>;
-export type BeforeRedirectHook = (updatedOptions: Options, plainResponse: PlainResponse) => Promisable<void>;
+export type BeforeRequestHookContext = {
+    /**
+    The current retry count.
+
+    It will be `0` for the initial request and increment for each retry.
+    */
+    retryCount: number;
+};
+export type BeforeRequestHook = (options: NormalizedOptions, context: BeforeRequestHookContext) => Promisable<void | Response | ResponseLike>;
+export type BeforeRedirectHook = (updatedOptions: NormalizedOptions, plainResponse: PlainResponse) => Promisable<void>;
 export type BeforeErrorHook = (error: RequestError) => Promisable<RequestError>;
 export type BeforeRetryHook = (error: RequestError, retryCount: number) => Promisable<void>;
 export type AfterResponseHook<ResponseType = unknown> = (response: Response<ResponseType>, retryWithMergedOptions: (options: OptionsInit) => never) => Promisable<Response | CancelableRequest<Response>>;
@@ -140,6 +167,8 @@ export type Hooks = {
     /**
     Called right before making the request with `options.createNativeRequestOptions()`.
 
+    The second argument is a context object containing request state information.
+
     This hook is especially useful in conjunction with `got.extend()` when you want to sign your request.
 
     @default []
@@ -160,7 +189,7 @@ export type Hooks = {
             json: {payload: 'old'},
             hooks: {
                 beforeRequest: [
-                    options => {
+                    (options, context) => {
                         options.body = JSON.stringify({payload: 'new'});
                         options.headers['content-length'] = options.body.length.toString();
                     }
@@ -170,6 +199,28 @@ export type Hooks = {
     );
     ```
 
+    **Example using `context.retryCount`:**
+
+    ```
+    import got from 'got';
+
+    await got('https://httpbin.org/status/500', {
+        retry: {
+            limit: 2
+        },
+        hooks: {
+            beforeRequest: [
+                (options, context) => {
+                    // Only log on the initial request, not on retries
+                    if (context.retryCount === 0) {
+                        console.log('Making initial request');
+                    }
+                }
+            ]
+        }
+    });
+    ```
+
     **Tip:**
     > - You can indirectly override the `request` function by early returning a [`ClientRequest`-like](https://nodejs.org/api/http.html#http_class_http_clientrequest) instance or a [`IncomingMessage`-like](https://nodejs.org/api/http.html#http_class_http_incomingmessage) instance. This is very useful when creating a custom cache mechanism.
     > - [Read more about this tip](https://github.com/sindresorhus/got/blob/main/documentation/cache.md#advanced-caching-mechanisms).
@@ -272,9 +323,15 @@ export type Hooks = {
     > - When using the Stream API, this hook is ignored.
 
     **Note:**
-    > - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. If the retry is successful, all remaining `afterResponse` hooks will be called. In case of an error, `beforeRetry` hooks will be called instead.
+    > - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. By default, remaining `afterResponse` hooks are removed to prevent duplicate execution. To preserve remaining hooks on retry, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. In case of an error, `beforeRetry` hooks will be called instead.
     Meanwhile the `init`, `beforeRequest` , `beforeRedirect` as well as already executed `afterResponse` hooks will be skipped.
 
+    **Note:**
+    > - To preserve remaining `afterResponse` hooks after calling `retryWithMergedOptions`, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. This is useful when you want hooks to run on retried requests.
+
+    **Warning:**
+    > - Be cautious when using `preserveHooks: true`. If a hook unconditionally calls `retryWithMergedOptions` with `preserveHooks: true`, it will create an infinite retry loop. Always ensure hooks have proper conditional logic to avoid infinite retries.
+
     @example
     ```
     import got from 'got';
@@ -312,6 +369,37 @@ export type Hooks = {
         mutableDefaults: true
     });
     ```
+
+    @example
+    ```
+    // Example with preserveHooks
+    import got from 'got';
+
+    const instance = got.extend({
+        hooks: {
+            afterResponse: [
+                (response, retryWithMergedOptions) => {
+                    if (response.statusCode === 401) {
+                        return retryWithMergedOptions({
+                            headers: {
+                                authorization: getNewToken()
+                            },
+                            preserveHooks: true  // Keep remaining hooks
+                        });
+                    }
+
+                    return response;
+                },
+                (response) => {
+                    // This hook will run on the retried request
+                    // (the original request is interrupted when the first hook triggers a retry)
+                    console.log('Response received:', response.statusCode);
+                    return response;
+                }
+            ]
+        }
+    });
+    ```
     */
     afterResponse: AfterResponseHook[];
 };
@@ -337,7 +425,9 @@ Delays between retries counts with function `1000 * Math.pow(2, retry) + Math.ra
 The `calculateDelay` property is a `function` that receives an object with `attemptCount`, `retryOptions`, `error` and `computedValue` properties for current retry count, the retry options, error and default computed value.
 The function must return a delay in milliseconds (or a Promise resolving with it) (`0` return value cancels retry).
 
-__Note:__ When you provide `calculateDelay`, you take full control of retry decisions. The `limit` option is not automatically enforced - you must check `attemptCount` yourself or return `0` when `computedValue` is `0` to respect the default retry logic.
+The `enforceRetryRules` property is a `boolean` that, when set to `true`, enforces the `limit`, `methods`, `statusCodes`, and `errorCodes` options before calling `calculateDelay`. Your `calculateDelay` function is only invoked when a retry is allowed based on these criteria. When `false` (default), `calculateDelay` receives the computed value but can override all retry logic.
+
+__Note:__ When `enforceRetryRules` is `false`, you must check `computedValue` in your `calculateDelay` function to respect the default retry logic. When `true`, the retry rules are enforced automatically.
 
 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.
@@ -362,6 +452,7 @@ export type RetryOptions = {
     backoffLimit: number;
     noise: number;
     maxRetryAfter?: number;
+    enforceRetryRules?: boolean;
 };
 export type CreateConnectionFunction = (options: NativeRequestOptions, oncreate: (error: NodeJS.ErrnoException, socket: Socket) => void) => Socket;
 export type CheckServerIdentityFunction = (hostname: string, certificate: DetailedPeerCertificate) => NodeJS.ErrnoException | void;
@@ -381,6 +472,24 @@ export type HttpsOptions = {
     rejectUnauthorized?: NativeRequestOptions['rejectUnauthorized'];
     checkServerIdentity?: CheckServerIdentityFunction;
     /**
+    Server name for the [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) TLS extension.
+
+    This is useful when requesting to servers that don't have a proper domain name but use a certificate with a known CN/SAN.
+
+    @example
+    ```
+    import got from 'got';
+
+    // Request to IP address with specific servername for TLS
+    await got('https://192.168.1.100', {
+        https: {
+            serverName: 'example.com'
+        }
+    });
+    ```
+    */
+    serverName?: string;
+    /**
     Override the default Certificate Authorities ([from Mozilla](https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReport)).
 
     @example
@@ -427,6 +536,27 @@ export type HttpsOptions = {
     dhparam?: SecureContextOptions['dhparam'];
     ecdhCurve?: SecureContextOptions['ecdhCurve'];
     certificateRevocationLists?: SecureContextOptions['crl'];
+    /**
+    Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all!
+
+    The value is a numeric bitmask of the `SSL_OP_*` options from OpenSSL.
+
+    For example, to allow connections to legacy servers that do not support secure renegotiation, you can use `crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT`.
+
+    @example
+    ```
+    import crypto from 'node:crypto';
+    import got from 'got';
+
+    // Allow connections to servers with legacy renegotiation
+    await got('https://legacy-server.com', {
+        https: {
+            secureOptions: crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT
+        }
+    });
+    ```
+    */
+    secureOptions?: number;
 };
 export type PaginateData<BodyType, ElementType> = {
     response: Response<BodyType>;
@@ -553,6 +683,7 @@ export type OptionsError = NodeJS.ErrnoException & {
 export type OptionsInit = Except<Partial<InternalsType>, 'hooks' | 'retry'> & {
     hooks?: Partial<Hooks>;
     retry?: Partial<RetryOptions>;
+    preserveHooks?: boolean;
 };
 export default class Options {
     private _unixOptions?;
@@ -674,12 +805,29 @@ export default class Options {
 
     __Note #4__: This option is not enumerable and will not be merged with the instance defaults.
 
-    The `content-length` header will be automatically set if `body` is a `string` / `Buffer` / [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) / [`form-data` instance](https://github.com/form-data/form-data), and `content-length` and `transfer-encoding` are not manually set in `options.headers`.
+    The `content-length` header will be automatically set if `body` is a `string` / `Buffer` / typed array ([`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), etc.) / [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) / [`form-data` instance](https://github.com/form-data/form-data), and `content-length` and `transfer-encoding` are not manually set in `options.headers`.
 
     Since Got 12, the `content-length` is not automatically set when `body` is a `fs.createReadStream`.
+
+    You can use `Iterable` and `AsyncIterable` objects as request body, including Web [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream):
+
+    @example
+    ```
+    import got from 'got';
+
+    // Using an async generator
+    async function* generateData() {
+        yield 'Hello, ';
+        yield 'world!';
+    }
+
+    await got.post('https://httpbin.org/anything', {
+        body: generateData()
+    });
+    ```
     */
-    get body(): string | Buffer | Readable | Generator | AsyncGenerator | FormDataLike | undefined;
-    set body(value: string | Buffer | Readable | Generator | AsyncGenerator | FormDataLike | undefined);
+    get body(): string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | ArrayBufferView | undefined;
+    set body(value: string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | ArrayBufferView | undefined);
     /**
     The form body is converted to a query string using [`(new URLSearchParams(object)).toString()`](https://nodejs.org/api/url.html#url_constructor_new_urlsearchparams_obj).
 
@@ -692,7 +840,9 @@ export default class Options {
     get form(): Record<string, any> | undefined;
     set form(value: Record<string, any> | undefined);
     /**
-    JSON body. If the `Content-Type` header is not set, it will be set to `application/json`.
+    JSON request body. If the `content-type` header is not set, it will be set to `application/json`.
+
+    __Important__: This option only affects the request body you send to the server. To parse the response as JSON, you must either call `.json()` on the promise or set `responseType: 'json'` in the options.
 
     __Note #1__: If you provide this option, `got.stream()` will be read-only.
 
@@ -1007,7 +1157,9 @@ export default class Options {
     The `calculateDelay` property is a `function` that receives an object with `attemptCount`, `retryOptions`, `error` and `computedValue` properties for current retry count, the retry options, error and default computed value.
     The function must return a delay in milliseconds (or a Promise resolving with it) (`0` return value cancels retry).
 
-    __Note:__ When you provide `calculateDelay`, you take full control of retry decisions. The `limit` option is not automatically enforced - you must check `attemptCount` yourself or return `0` when `computedValue` is `0` to respect the default retry logic.
+    The `enforceRetryRules` property is a `boolean` that, when set to `true`, enforces the `limit`, `methods`, `statusCodes`, and `errorCodes` options before calling `calculateDelay`. Your `calculateDelay` function is only invoked when a retry is allowed based on these criteria. When `false` (default), `calculateDelay` receives the computed value but can override all retry logic.
+
+    __Note:__ When `enforceRetryRules` is `false`, you must check `computedValue` in your `calculateDelay` function to respect the default retry logic. When `true`, the retry rules are enforced automatically.
 
     By default, it retries *only* on the specified methods, status codes, and on these network errors:
 
@@ -1122,6 +1274,18 @@ export default class Options {
     set maxHeaderSize(value: number | undefined);
     get enableUnixSockets(): boolean;
     set enableUnixSockets(value: boolean);
+    /**
+    Throw an error if the server response's `content-length` header value doesn't match the number of bytes received.
+
+    This is useful for detecting truncated responses and follows RFC 9112 requirements for message completeness.
+
+    __Note__: Responses without a `content-length` header are not validated.
+    __Note__: When enabled and validation fails, a `ReadError` with code `ERR_HTTP_CONTENT_LENGTH_MISMATCH` will be thrown.
+
+    @default false
+    */
+    get strictContentLength(): boolean;
+    set strictContentLength(value: boolean);
     toJSON(): {
         headers: Headers;
         timeout: Delays;
@@ -1135,7 +1299,7 @@ export default class Options {
         h2session: ClientHttp2Session | undefined;
         decompress: boolean;
         prefixUrl: string | URL;
-        body: string | Buffer | Readable | Generator | AsyncGenerator | FormDataLike | undefined;
+        body: string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | ArrayBufferView | undefined;
         form: Record<string, any> | undefined;
         url: string | URL | undefined;
         cookieJar: PromiseCookieJar | ToughCookieJar | undefined;
@@ -1168,6 +1332,7 @@ export default class Options {
         setHost: boolean;
         maxHeaderSize: number | undefined;
         enableUnixSockets: boolean;
+        strictContentLength: boolean;
     };
     createNativeRequestOptions(): {
         ALPNProtocols: string[] | undefined;
@@ -1178,6 +1343,7 @@ export default class Options {
         pfx: PfxType;
         rejectUnauthorized: boolean | undefined;
         checkServerIdentity: CheckServerIdentityFunction | typeof checkServerIdentity;
+        servername: string | undefined;
         ciphers: string | undefined;
         honorCipherOrder: boolean | undefined;
         minVersion: import("tls").SecureVersion | undefined;
@@ -1187,6 +1353,7 @@ export default class Options {
         dhparam: string | Buffer<ArrayBufferLike> | undefined;
         ecdhCurve: string | undefined;
         crl: string | Buffer<ArrayBufferLike> | (string | Buffer<ArrayBufferLike>)[] | undefined;
+        secureOptions: number | undefined;
         lookup: {
             (hostname: string, family: import("cacheable-lookup").IPFamily, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
             (hostname: string, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
@@ -1196,7 +1363,11 @@ export default class Options {
             (hostname: string, options: import("cacheable-lookup").LookupOptions, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
         } | undefined;
         family: DnsLookupIpVersion;
-        agent: false | http.Agent | Agents | undefined;
+        agent: false | http.Agent | {
+            http2: {};
+            http?: HttpAgent | false;
+            https?: HttpsAgent | false;
+        } | undefined;
         setHost: boolean;
         method: Method;
         maxHeaderSize: number | undefined;
@@ -1229,11 +1400,9 @@ export default class Options {
         clientCertEngine?: string | undefined;
         privateKeyEngine?: string | undefined;
         privateKeyIdentifier?: string | undefined;
-        secureOptions?: number | undefined;
         secureProtocol?: string | undefined;
         sessionIdContext?: string | undefined;
         ticketKeys?: Buffer | undefined;
-        servername?: string | undefined;
         shared?: boolean;
         cacheHeuristic?: number;
         immutableMinTimeToLive?: number;