Fix hook state leaks and fetch option forwarding

Clone nested retry options before init hooks run so hook mutations do not leak across requests.

Avoid canceling shared response bodies when an `afterResponse` hook wraps an existing body in a new `Response`.

Forward all non-standard, non-Ky options directly to `fetch()` instead of filtering against `Request`, which removes the obsolete vendor allowlist and preserves fetch-only extensions like dispatcher and Next.js next.

Author: sindresorhus

source/core/Ky.ts

@@ -21,6 +21,7 @@ import {
 	mergeHooks,
 	deletedParametersSymbol,
 } from '../utils/merge.js';
+import type {RetryOptions} from '../types/retry.js';
 import {normalizeRequestMethod, normalizeRetryOptions} from '../utils/normalize.js';
 import timeout from '../utils/timeout.js';
 import delay from '../utils/delay.js';
@@ -58,16 +59,35 @@ const createTextDecoder = (contentType: string): TextDecoder => {
 
 const invalidSchemaMessage = 'The `schema` argument must follow the Standard Schema specification';
 
+const cloneRetryOptions = (retry: RetryOptions | number): RetryOptions | number => {
+	if (typeof retry !== 'object') {
+		return retry;
+	}
+
+	// Clone nested arrays too so init hooks can mutate retry config without leaking state across requests.
+	return {
+		...retry,
+		...(retry.methods && {methods: [...retry.methods]}),
+		...(retry.statusCodes && {statusCodes: [...retry.statusCodes]}),
+		...(retry.afterStatusCodes && {afterStatusCodes: [...retry.afterStatusCodes]}),
+	};
+};
+
 // Shallow-clone mutable option properties so init hook mutations don't leak across requests.
 function cloneInitHookOptions(options: Options): Options {
-	return {
+	const clonedOptions: Options = {
 		...options,
 		json: cloneShallow(options.json),
-		retry: cloneShallow(options.retry)!,
 		context: cloneShallow(options.context)!,
 		headers: cloneShallow(options.headers)!,
 		searchParams: cloneShallow(options.searchParams) as SearchParamsOption | undefined,
 	};
+
+	if (options.retry !== undefined) {
+		clonedOptions.retry = cloneRetryOptions(options.retry);
+	}
+
+	return clonedOptions;
 }
 
 const validateJsonWithSchema = async (jsonValue: unknown, schema: StandardSchemaV1): Promise<unknown> => {
@@ -771,11 +791,12 @@ export class Ky {
 
 			// Cancel any response bodies we won't use to prevent memory leaks.
 			// Uses fire-and-forget since hooks may have cloned the response, creating tee branches that block cancellation.
-			if (clonedResponse !== nextResponse) {
+			// If the hook wrapped an existing body into a new Response, both Response objects can still point at the same stream.
+			if (clonedResponse !== nextResponse && clonedResponse.body !== nextResponse.body) {
 				this.#cancelResponseBody(clonedResponse);
 			}
 
-			if (response !== nextResponse) {
+			if (response !== nextResponse && response.body !== nextResponse.body) {
 				this.#cancelResponseBody(response);
 			}
 
@@ -881,7 +902,7 @@ export class Ky {
 			this.request = new globalThis.Request(this.request, {signal: this.#options.signal});
 		}
 
-		const nonRequestOptions = findUnknownOptions(this.request, this.#options);
+		const nonRequestOptions = findUnknownOptions(this.#options);
 		const retryRequest = this.#options.retry.limit > 0 ? this.request.clone() : undefined;
 		const request = this.#wrapRequestWithUploadProgress(this.request, this.#options.body ?? undefined);
 

source/core/constants.ts

@@ -259,13 +259,6 @@ export const kyOptionKeys: KyOptionsRegistry = {
 	context: true,
 };
 
-// Vendor-specific fetch options that should always be passed to fetch()
-// even if they appear on the Request object due to vendor patching.
-// See: https://github.com/sindresorhus/ky/issues/541
-export const vendorSpecificOptions = {
-	next: true, // Next.js cache revalidation (revalidate, tags)
-} as const;
-
 // Standard RequestInit options that should NOT be passed separately to fetch()
 // because they're already applied to the Request object.
 // Note: `dispatcher` and `priority` are NOT included here - they're fetch-only

source/utils/normalize.ts

@@ -37,13 +37,14 @@ export const normalizeRetryOptions = (retry: number | RetryOptions = {}): Intern
 		throw new Error('retry.methods must be an array');
 	}
 
-	retry.methods &&= retry.methods.map(method => method.toLowerCase());
-
 	if (retry.statusCodes && !Array.isArray(retry.statusCodes)) {
 		throw new Error('retry.statusCodes must be an array');
 	}
 
-	const normalizedRetry = Object.fromEntries(Object.entries(retry).filter(([, value]) => value !== undefined)) as RetryOptions;
+	const normalizedRetry = Object.fromEntries(Object.entries({
+		...retry,
+		methods: retry.methods?.map(method => method.toLowerCase()),
+	}).filter(([, value]) => value !== undefined)) as RetryOptions;
 
 	return {
 		...defaultRetryOptions,

source/utils/options.ts

@@ -1,9 +1,8 @@
-import {kyOptionKeys, requestOptionsRegistry, vendorSpecificOptions} from '../core/constants.js';
+import {kyOptionKeys, requestOptionsRegistry} from '../core/constants.js';
 import type {SearchParamsOption} from '../types/options.js';
 import {deletedParametersSymbol} from './merge.js';
 
 export const findUnknownOptions = (
-	request: Request,
 	options: Record<string, unknown>,
 ): Record<string, unknown> => {
 	const unknownOptions: Record<string, unknown> = {};
@@ -14,13 +13,12 @@ export const findUnknownOptions = (
 			continue;
 		}
 
-		// An option is passed to fetch() if:
-		// 1. It's not a standard RequestInit option (not in requestOptionsRegistry)
-		// 2. It's not a ky-specific option (not in kyOptionKeys)
-		// 3. Either:
-		//    a. It's not on the Request object, OR
-		//    b. It's a vendor-specific option that should always be passed (in vendorSpecificOptions)
-		if (!(key in requestOptionsRegistry) && !(key in kyOptionKeys) && (!(key in request) || key in vendorSpecificOptions)) {
+		// Forward every non-standard, non-Ky option to fetch().
+		// We intentionally do not check whether the key also exists on `Request`, because some runtimes
+		// patch `Request.prototype` with fetch-only extensions. For example, Next.js adds `next`, and the
+		// old `key in request` heuristic dropped it unless Ky kept a special-case allowlist.
+		// Passing all non-standard keys makes that allowlist unnecessary and preserves future fetch extensions too.
+		if (!(key in requestOptionsRegistry) && !(key in kyOptionKeys)) {
 			unknownOptions[key] = options[key];
 		}
 	}

test/fetch.ts

@@ -135,6 +135,34 @@ test('unknown options are passed to fetch', async t => {
 	await ky(fixture, {...options, fetch: customFetch}).text();
 });
 
+test('unknown options with falsy values are passed to fetch', async t => {
+	t.plan(3);
+
+	const customFetch: typeof fetch = async (request, init) => {
+		t.is(init.customNull, null);
+		t.is(init.customFalse, false);
+		t.is(init.customZero, 0);
+		return new Response(request.url);
+	};
+
+	await ky(fixture, {
+		customNull: null, customFalse: false, customZero: 0, fetch: customFetch,
+	}).text();
+});
+
+test('ky-specific options are not passed to fetch', async t => {
+	const customFetch: typeof fetch = async (request, init) => {
+		t.is(init.retry, undefined);
+		t.is(init.timeout, undefined);
+		t.is(init.hooks, undefined);
+		t.is(init.throwHttpErrors, undefined);
+		t.is(init.json, undefined);
+		return new Response(request.url);
+	};
+
+	await ky(fixture, {retry: 3, timeout: 5000, fetch: customFetch}).text();
+});
+
 test('fetch-only options like dispatcher are passed to fetch', async t => {
 	t.plan(1);
 
@@ -148,6 +176,35 @@ test('fetch-only options like dispatcher are passed to fetch', async t => {
 	await ky(fixture, {dispatcher: mockDispatcher, fetch: customFetch}).text();
 });
 
+test.serial('fetch-only options like dispatcher are passed to fetch even when Request is patched', async t => {
+	t.plan(1);
+
+	const mockDispatcher = {name: 'custom-agent'};
+	const originalDescriptor = Object.getOwnPropertyDescriptor(Request.prototype, 'dispatcher');
+
+	try {
+		Object.defineProperty(Request.prototype, 'dispatcher', {
+			value: undefined,
+			writable: true,
+			enumerable: true,
+			configurable: true,
+		});
+
+		const customFetch: typeof fetch = async (request, init) => {
+			t.is(init.dispatcher, mockDispatcher);
+			return new Response(request.url);
+		};
+
+		await ky(fixture, {dispatcher: mockDispatcher, fetch: customFetch}).text();
+	} finally {
+		if (originalDescriptor) {
+			Object.defineProperty(Request.prototype, 'dispatcher', originalDescriptor);
+		} else {
+			delete (Request.prototype as any).dispatcher;
+		}
+	}
+});
+
 test('priority option is passed to fetch', async t => {
 	t.plan(1);
 

test/hooks.ts

@@ -214,6 +214,71 @@ test('afterResponse hook can return the provided response', async t => {
 	t.true(originalResponse?.bodyUsed);
 });
 
+test('afterResponse hook can wrap the provided body in a new response', async t => {
+	const responseText = await ky('https://example.com', {
+		fetch: async () => new Response('ok', {
+			headers: {
+				'content-type': 'text/plain',
+			},
+		}),
+		hooks: {
+			afterResponse: [
+				({response}) => new Response(response.body, {
+					headers: response.headers,
+				}),
+			],
+		},
+	}).text();
+
+	t.is(responseText, 'ok');
+});
+
+test('afterResponse hook can wrap a streaming body in a new response', async t => {
+	const customFetch = createStreamFetch({text: 'streamed'});
+
+	const responseText = await ky('https://example.com', {
+		fetch: customFetch,
+		hooks: {
+			afterResponse: [
+				({response}) => new Response(response.body, {
+					headers: response.headers,
+				}),
+			],
+		},
+	}).text();
+
+	t.is(responseText, 'streamed');
+});
+
+test('afterResponse hook chain can forward the same body through multiple hooks', async t => {
+	let originalResponse: Response | undefined;
+
+	const customFetch = createStreamFetch({
+		text: 'chained',
+		onResponse(response) {
+			originalResponse = response;
+		},
+	});
+
+	const responseText = await ky('https://example.com', {
+		fetch: customFetch,
+		hooks: {
+			afterResponse: [
+				({response}) => new Response(response.body, {
+					headers: response.headers,
+				}),
+				({response}) => new Response(response.body, {
+					headers: response.headers,
+				}),
+			],
+		},
+	}).text();
+
+	t.is(responseText, 'chained');
+	// The original fetch response body should be cancelled since hooks created new wrappers
+	t.true(originalResponse?.bodyUsed);
+});
+
 test('afterResponse hook with multiple hooks cancels all unused clones', async t => {
 	let originalResponse: Response | undefined;
 	const clones: Response[] = [];
@@ -4725,6 +4790,81 @@ test('init hook in-place retry mutations do not leak across requests', async t =
 	t.deepEqual(seenLimits, [2, 2]);
 });
 
+test('init hook nested retry mutations do not leak across requests', async t => {
+	const seenMethods: string[][] = [];
+
+	const api = ky.extend({
+		retry: {
+			methods: ['get'],
+		},
+		hooks: {
+			init: [
+				options => {
+					seenMethods.push([...options.retry.methods]);
+					options.retry.methods.push('post');
+				},
+			],
+		},
+	});
+
+	const fetch: typeof globalThis.fetch = async () => new Response('ok');
+
+	await api.get('https://example.com', {fetch});
+	await api.get('https://example.com', {fetch});
+
+	t.deepEqual(seenMethods, [['get'], ['get']]);
+});
+
+test('init hook nested retry statusCodes mutations do not leak across requests', async t => {
+	const seenStatusCodes: number[][] = [];
+
+	const api = ky.extend({
+		retry: {
+			statusCodes: [500],
+		},
+		hooks: {
+			init: [
+				options => {
+					seenStatusCodes.push([...options.retry.statusCodes]);
+					options.retry.statusCodes.push(502);
+				},
+			],
+		},
+	});
+
+	const fetch: typeof globalThis.fetch = async () => new Response('ok');
+
+	await api.get('https://example.com', {fetch});
+	await api.get('https://example.com', {fetch});
+
+	t.deepEqual(seenStatusCodes, [[500], [500]]);
+});
+
+test('init hook nested retry afterStatusCodes mutations do not leak across requests', async t => {
+	const seenAfterStatusCodes: number[][] = [];
+
+	const api = ky.extend({
+		retry: {
+			afterStatusCodes: [429],
+		},
+		hooks: {
+			init: [
+				options => {
+					seenAfterStatusCodes.push([...options.retry.afterStatusCodes]);
+					options.retry.afterStatusCodes.push(503);
+				},
+			],
+		},
+	});
+
+	const fetch: typeof globalThis.fetch = async () => new Response('ok');
+
+	await api.get('https://example.com', {fetch});
+	await api.get('https://example.com', {fetch});
+
+	t.deepEqual(seenAfterStatusCodes, [[429], [429]]);
+});
+
 test('init hook in-place json mutations do not leak across requests', async t => {
 	let requestIdentifier = 0;
 	const seenRequestIdentifiers: string[] = [];

test/main.ts

@@ -778,6 +778,21 @@ test('timeout option is cancelled when the promise is resolved', async t => {
 	t.true(duration < 10);
 });
 
+test('normalizing retry options does not mutate the caller retry object', async t => {
+	const retry = {
+		methods: ['GET'],
+	};
+
+	await ky('https://example.com', {
+		fetch: async () => new Response('ok'),
+		retry,
+	}).text();
+
+	t.deepEqual(retry, {
+		methods: ['GET'],
+	});
+});
+
 test('searchParams option', async t => {
 	const server = await createHttpTestServer(t);