Add retry.resetTimeout option to reset timeout budget on each retry

Fixes #497

Author: sindresorhus

readme.md

@@ -256,9 +256,10 @@ Default:
 - `delay`: `attemptCount => 0.3 * (2 ** (attemptCount - 1)) * 1000`
 - `jitter`: `undefined`
 - `retryOnTimeout`: `false`
+- `resetTimeout`: `false`
 - `shouldRetry`: `undefined`
 
-An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, and custom retry logic.
+An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, `resetTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, timeout reset behavior, and custom retry logic.
 
 If `retry` is a number, it will be used as `limit` and other defaults will remain in place.
 
@@ -280,6 +281,8 @@ The `jitter` option adds random jitter to retry delays to prevent thundering her
 
 The `retryOnTimeout` option determines whether to retry when a request times out. By default, retries are not triggered following a [timeout](#timeout).
 
+The `resetTimeout` option gives each retry attempt the full `timeout` value instead of the remaining budget. By default, `timeout` is a total timeout across all retries, meaning later retries get progressively less time. When `resetTimeout` is `true`, each retry starts with a fresh timeout. If you need both per-request timeout and a total timeout cap, combine `resetTimeout: true` with `signal: AbortSignal.timeout(totalMs)`.
+
 The `shouldRetry` option provides custom retry logic that **takes precedence over the default retry checks** (`retryOnTimeout`, status code checks, etc.) for retriable methods. It is only called after the retry limit and method checks pass.
 
 **Note:** This is different from the `beforeRetry` hook:
@@ -320,6 +323,21 @@ const json = await ky('https://example.com', {
 }).json();
 ```
 
+**Resetting timeout on each retry:**
+
+```js
+import ky from 'ky';
+
+const json = await ky('https://example.com', {
+	timeout: 5000,
+	retry: {
+		limit: 3,
+		retryOnTimeout: true,
+		resetTimeout: true
+	}
+}).json();
+```
+
 **Using jitter to prevent thundering herd:**
 
 ```js
@@ -383,7 +401,8 @@ const json = await ky('https://example.com', {
 Type: `number | false`\
 Default: `10000`
 
-Timeout in milliseconds for getting a response, including any retries. Can not be greater than 2147483647.
+Timeout in milliseconds for getting a response, including any retries. Cannot be greater than 2147483647. Use [`retry.resetTimeout`](#retry) to give each retry attempt the full timeout instead of sharing a single budget across all attempts.
+
 If set to `false`, there will be no timeout.
 
 ##### hooks

source/core/Ky.ts

@@ -836,7 +836,7 @@ export class Ky {
 			return undefined;
 		}
 
-		if (this.#startTime === undefined) {
+		if (this.#startTime === undefined || this.#options.retry.resetTimeout) {
 			return this.#options.timeout;
 		}
 

source/types/options.ts

@@ -145,7 +145,7 @@ export type KyOptions = {
 	prefix?: URL | string;
 
 	/**
-	An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, and custom retry logic.
+	An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, `resetTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, timeout reset behavior, and custom retry logic.
 
 	If `retry` is a number, it will be used as `limit` and other defaults will remain in place.
 
@@ -171,7 +171,8 @@ export type KyOptions = {
 	retry?: RetryOptions | number;
 
 	/**
-	Timeout in milliseconds for getting a response, including any retries. Can not be greater than 2147483647.
+	Timeout in milliseconds for getting a response, including any retries. Cannot be greater than 2147483647. Use `retry.resetTimeout` to give each retry attempt the full timeout instead of sharing a single budget across all attempts.
+
 	If set to `false`, there will be no timeout.
 
 	@default 10000

source/types/retry.ts

@@ -123,6 +123,31 @@ export type RetryOptions = {
 	*/
 	retryOnTimeout?: boolean;
 
+	/**
+	Whether to reset the timeout for each retry attempt.
+
+	By default, the `timeout` option is a total timeout across all retries. When `resetTimeout` is `true`, each retry attempt gets the full `timeout` value instead of the remaining budget.
+
+	If you need both per-request timeout and a total timeout cap, combine `resetTimeout: true` with `signal: AbortSignal.timeout(totalMs)`.
+
+	@default false
+
+	@example
+	```
+	import ky from 'ky';
+
+	const json = await ky('https://example.com', {
+		timeout: 5000,
+		retry: {
+			limit: 3,
+			retryOnTimeout: true,
+			resetTimeout: true
+		}
+	}).json();
+	```
+	*/
+	resetTimeout?: boolean;
+
 	/**
 	A function to determine whether a retry should be attempted.
 

source/utils/normalize.ts

@@ -23,6 +23,7 @@ const defaultRetryOptions: InternalRetryOptions = {
 	delay: attemptCount => 0.3 * (2 ** (attemptCount - 1)) * 1000,
 	jitter: undefined,
 	retryOnTimeout: false,
+	resetTimeout: false,
 };
 
 export const normalizeRetryOptions = (retry: number | RetryOptions = {}): InternalRetryOptions => {

test/retry.ts

@@ -1610,6 +1610,92 @@ test('shouldRetry: error propagates if shouldRetry returns rejected Promise', as
 	);
 });
 
+test('resetTimeout: true - each retry gets the full timeout', async t => {
+	let requestCount = 0;
+
+	const server = await createHttpTestServer(t);
+	server.get('/', async (_request, response) => {
+		requestCount++;
+		if (requestCount <= 2) {
+			await delay(600);
+			response.end(fixture);
+			return;
+		}
+
+		response.end(fixture);
+	});
+
+	const result = await ky(server.url, {
+		timeout: 500,
+		retry: {
+			limit: 3,
+			retryOnTimeout: true,
+			resetTimeout: true,
+			delay: () => 0,
+		},
+	}).text();
+
+	t.is(result, fixture);
+	t.is(requestCount, 3);
+});
+
+test('resetTimeout: true - works with HTTP error retries that consume timeout budget', async t => {
+	let requestCount = 0;
+
+	const server = await createHttpTestServer(t);
+	server.get('/', async (_request, response) => {
+		requestCount++;
+		if (requestCount <= 2) {
+			// Each failed request takes 600ms, consuming most of a 1000ms budget.
+			// Without resetTimeout, the first retry would have only ~400ms left and time out.
+			await delay(600);
+			response.sendStatus(500);
+			return;
+		}
+
+		response.end(fixture);
+	});
+
+	const result = await ky(server.url, {
+		timeout: 1000,
+		retry: {
+			limit: 3,
+			resetTimeout: true,
+			delay: () => 0,
+		},
+	}).text();
+
+	t.is(result, fixture);
+	t.is(requestCount, 3);
+});
+
+test('resetTimeout: true does not imply retryOnTimeout', async t => {
+	let requestCount = 0;
+
+	const server = await createHttpTestServer(t);
+	server.get('/', async (_request, response) => {
+		requestCount++;
+		await delay(600);
+		response.end(fixture);
+	});
+
+	await t.throwsAsync(
+		ky(server.url, {
+			timeout: 500,
+			retry: {
+				limit: 3,
+				resetTimeout: true,
+				// `retryOnTimeout` defaults to false
+			},
+		}).text(),
+		{
+			name: 'TimeoutError',
+		},
+	);
+
+	t.is(requestCount, 1);
+});
+
 test('NetworkError wraps fetch network errors', async t => {
 	const error = await t.throwsAsync(
 		ky('https://example.com', {