Add request parameter to ky.retry() for custom retry requests

Author: sindresorhus

readme.md

@@ -880,6 +880,16 @@ Type: `string`
 
 Reason for the retry. This will be included in the error message passed to `beforeRetry` hooks, allowing you to distinguish between different types of forced retries.
 
+##### request
+
+Type: `Request`
+
+Custom request to use for the retry.
+
+This allows you to modify or completely replace the request during a forced retry. The custom request becomes the starting point for the retry - `beforeRetry` hooks can still further modify it if needed.
+
+**Note:** The custom request's `signal` will be replaced with Ky's managed signal to handle timeouts and user-provided abort signals correctly. If the original request body has been consumed, you must provide a new body or clone the request before consuming.
+
 #### Example
 
 ```js
@@ -905,6 +915,30 @@ const api = ky.extend({
 							reason: 'RATE_LIMIT'
 						});
 					}
+
+					// Retry with a modified request (e.g., fallback endpoint)
+					if (data.error?.code === 'FALLBACK_TO_BACKUP') {
+						return ky.retry({
+							request: new Request('https://backup-api.com/endpoint', {
+								method: request.method,
+								headers: request.headers,
+							}),
+							reason: 'Switching to backup endpoint'
+						});
+					}
+
+					// Retry with refreshed authentication
+					if (data.error?.code === 'TOKEN_REFRESH' && data.newToken) {
+						return ky.retry({
+							request: new Request(request, {
+								headers: {
+									...Object.fromEntries(request.headers),
+									'Authorization': `Bearer ${data.newToken}`
+								}
+							}),
+							reason: 'Retrying with refreshed token'
+						});
+					}
 				}
 			}
 		],

source/core/Ky.ts

@@ -179,7 +179,7 @@ export class Ky {
 	readonly #options: InternalOptions;
 	#originalRequest?: Request;
 	readonly #userProvidedAbortSignal?: AbortSignal;
-	#cachedNormalizedOptions?: NormalizedOptions;
+	#cachedNormalizedOptions: NormalizedOptions | undefined;
 
 	// eslint-disable-next-line complexity
 	constructor(input: Input, options: Options = {}) {
@@ -275,11 +275,7 @@ export class Ky {
 				throw new Error('Request streams are not supported in your environment. The `duplex` option for `Request` is not available.');
 			}
 
-			const originalBody = this.request.body;
-			if (originalBody) {
-				// Pass original body to calculate size correctly (before it becomes a stream)
-				this.request = streamRequest(this.request, this.#options.onUploadProgress, this.#options.body);
-			}
+			this.request = this.#wrapRequestWithUploadProgress(this.request, this.#options.body ?? undefined);
 		}
 	}
 
@@ -394,6 +390,16 @@ export class Ky {
 			// Only use user-provided signal for delay, not our internal abortController
 			await delay(ms, this.#userProvidedAbortSignal ? {signal: this.#userProvidedAbortSignal} : {});
 
+			// Apply custom request from forced retry before beforeRetry hooks
+			// Ensure the custom request has the correct managed signal for timeouts and user aborts
+			if (error instanceof ForceRetryError && error.customRequest) {
+				const managedRequest = this.#options.signal
+					? new globalThis.Request(error.customRequest, {signal: this.#options.signal})
+					: new globalThis.Request(error.customRequest);
+
+				this.#assignRequest(managedRequest);
+			}
+
 			for (const hook of this.#options.hooks.beforeRetry) {
 				// eslint-disable-next-line no-await-in-loop
 				const hookResult = await hook({
@@ -403,9 +409,8 @@ export class Ky {
 					retryCount: this.#retryCount,
 				});
 
-				// If a Request is returned, use it for the retry
 				if (hookResult instanceof globalThis.Request) {
-					this.request = hookResult;
+					this.#assignRequest(hookResult);
 					break;
 				}
 
@@ -441,14 +446,14 @@ export class Ky {
 				{retryCount: this.#retryCount},
 			);
 
-			if (result instanceof Request) {
-				this.request = result;
-				break;
-			}
-
 			if (result instanceof Response) {
 				return result;
 			}
+
+			if (result instanceof globalThis.Request) {
+				this.#assignRequest(result);
+				break;
+			}
 		}
 
 		const nonRequestOptions = findUnknownOptions(this.request, this.#options);
@@ -472,4 +477,17 @@ export class Ky {
 
 		return this.#cachedNormalizedOptions;
 	}
+
+	#assignRequest(request: Request): void {
+		this.#cachedNormalizedOptions = undefined;
+		this.request = this.#wrapRequestWithUploadProgress(request);
+	}
+
+	#wrapRequestWithUploadProgress(request: Request, originalBody?: BodyInit): Request {
+		if (!this.#options.onUploadProgress || !request.body) {
+			return request;
+		}
+
+		return streamRequest(request, this.#options.onUploadProgress, originalBody ?? this.#options.body ?? undefined);
+	}
 }

source/core/constants.ts

@@ -81,6 +81,39 @@ export type ForceRetryOptions = {
 	This will be included in the error message passed to `beforeRetry` hooks, allowing you to distinguish between different types of forced retries.
 	*/
 	reason?: string;
+
+	/**
+	Custom request to use for the retry.
+
+	This allows you to modify or completely replace the request during a forced retry. The custom request becomes the starting point for the retry - `beforeRetry` hooks can still further modify it if needed.
+
+	**Note:** The custom request's `signal` will be replaced with Ky's managed signal to handle timeouts and user-provided abort signals correctly. If the original request body has been consumed, you must provide a new body or clone the request before consuming.
+
+	@example
+	```
+	// Fallback to a different endpoint
+	return ky.retry({
+		request: new Request('https://backup-api.com/endpoint', {
+			method: request.method,
+			headers: request.headers,
+		}),
+		reason: 'Falling back to backup API'
+	});
+
+	// Retry with refreshed authentication token
+	const data = await response.clone().json();
+	return ky.retry({
+		request: new Request(request, {
+			headers: {
+				...Object.fromEntries(request.headers),
+				'Authorization': `Bearer ${data.newToken}`
+			}
+		}),
+		reason: 'Retrying with refreshed token'
+	});
+	```
+	*/
+	request?: Request;
 };
 
 /**
@@ -121,6 +154,30 @@ const api = ky.extend({
 							reason: 'RATE_LIMIT'
 						});
 					}
+
+					// Retry with a modified request (e.g., fallback endpoint)
+					if (data.error?.code === 'FALLBACK_TO_BACKUP') {
+						return ky.retry({
+							request: new Request('https://backup-api.com/endpoint', {
+								method: request.method,
+								headers: request.headers,
+							}),
+							reason: 'Switching to backup endpoint'
+						});
+					}
+
+					// Retry with refreshed authentication
+					if (data.error?.code === 'TOKEN_REFRESH' && data.newToken) {
+						return ky.retry({
+							request: new Request(request, {
+								headers: {
+									...Object.fromEntries(request.headers),
+									'Authorization': `Bearer ${data.newToken}`
+								}
+							}),
+							reason: 'Retrying with refreshed token'
+						});
+					}
 				}
 			}
 		],

source/errors/ForceRetryError.ts

@@ -8,10 +8,12 @@ export class ForceRetryError extends Error {
 	override name = 'ForceRetryError' as const;
 	customDelay: number | undefined;
 	reason: string | undefined;
+	customRequest: Request | undefined;
 
 	constructor(options?: ForceRetryOptions) {
 		super(options?.reason ? `Forced retry: ${options.reason}` : 'Forced retry');
 		this.customDelay = options?.delay;
 		this.reason = options?.reason;
+		this.customRequest = options?.request;
 	}
 }