Add retryCount to beforeRequest hook context

Fixes #1866

Author: sindresorhus

documentation/9-hooks.md

@@ -107,12 +107,15 @@ console.log(headers.Secret);
 **Default: `[]`**
 
 ```ts
-(options: Options) => Promisable<void | Response | ResponseLike>
+(options: Options, context: BeforeRequestHookContext) => Promisable<void | Response | ResponseLike>
 ```
 
 Called right before making the request with `options.createNativeRequestOptions()`.\
 This hook is especially useful in conjunction with `got.extend()` when you want to sign your request.
 
+The second parameter is a context object with the following properties:
+- `retryCount` - The current retry count (0 for the initial request, 1+ for retries).
+
 **Note:**
 > - Got will make no further changes to the request before it is sent.
 
@@ -128,7 +131,7 @@ const response = await got.post(
 		json: {payload: 'old'},
 		hooks: {
 			beforeRequest: [
-				options => {
+				(options, context) => {
 					options.body = JSON.stringify({payload: 'new'});
 					options.headers['content-length'] = Buffer.byteLength(options.body).toString();
 				}
@@ -138,6 +141,28 @@ const response = await got.post(
 );
 ```
 
+You can use `context.retryCount` to conditionally modify behavior based on whether it's the initial request or a retry:
+
+```js
+import got from 'got';
+
+const response = await got('https://httpbin.org/status/500', {
+	retry: {
+		limit: 2
+	},
+	hooks: {
+		beforeRequest: [
+			(options, context) => {
+				// Only log on 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](cache.md#advanced-caching-mechanisms).

source/core/index.ts

@@ -1219,7 +1219,7 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 
 		for (const hook of options.hooks.beforeRequest) {
 			// eslint-disable-next-line no-await-in-loop
-			const result = await hook(options as NormalizedOptions);
+			const result = await hook(options as NormalizedOptions, {retryCount: this.retryCount});
 
 			if (!is.undefined(result)) {
 				// @ts-expect-error Skip the type mismatch to support abstract responses

source/core/options.ts

@@ -91,7 +91,17 @@ export type NormalizedOptions = OverrideProperties<Options, {
 }>;
 
 export type InitHook = (init: OptionsInit, self: Options) => void;
-export type BeforeRequestHook = (options: NormalizedOptions) => Promisable<void | Response | ResponseLike>;
+
+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>;
@@ -195,6 +205,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 []
@@ -215,7 +227,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();
 					}
@@ -225,6 +237,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).

test/hooks.ts

@@ -367,6 +367,62 @@ test('beforeRequest allows modifications', withServer, async (t, server, got) =>
 	t.is(body.foo, 'bar');
 });
 
+test('beforeRequest is called with context', withServer, async (t, server, got) => {
+	server.get('/', echoHeaders);
+
+	await got({
+		hooks: {
+			beforeRequest: [
+				(_options, context) => {
+					t.truthy(context);
+					t.is(typeof context.retryCount, 'number');
+				},
+			],
+		},
+	});
+});
+
+test('beforeRequest context has retryCount 0 on initial request', withServer, async (t, server, got) => {
+	server.get('/', echoHeaders);
+
+	await got({
+		hooks: {
+			beforeRequest: [
+				(_options, context) => {
+					t.is(context.retryCount, 0);
+				},
+			],
+		},
+	});
+});
+
+test('beforeRequest context retryCount increments on retries', withServer, async (t, server, got) => {
+	server.get('/', (_request, response) => {
+		response.statusCode = 500;
+		response.end();
+	});
+
+	const retryCounts: number[] = [];
+
+	await t.throwsAsync(got({
+		retry: {
+			limit: 2,
+		},
+		hooks: {
+			beforeRequest: [
+				(_options, context) => {
+					retryCounts.push(context.retryCount);
+				},
+			],
+		},
+	}), {instanceOf: HTTPError});
+
+	t.is(retryCounts.length, 3);
+	t.is(retryCounts[0], 0); // Initial request
+	t.is(retryCounts[1], 1); // First retry
+	t.is(retryCounts[2], 2); // Second retry
+});
+
 test('returning HTTP response from a beforeRequest hook', withServer, async (t, server, got) => {
 	server.get('/', echoUrl);