Add totalTimeout option and make timeout be per retry

[sindresorhus]

Fixes #497

[sindresorhus]

In aac83fa, I changed Ky to make timeout apply to the whole operation. However, doing some research now, I realize most HTTP clients across languages treat timeout as per-attempt by default:

• got (JS): timeout.request is per-attempt
• reqwest (Rust): timeout() is per-attempt
• httpx (Python): timeout is per-attempt
• requests (Python): timeout is per-attempt
• Guzzle (PHP): timeout is per-attempt

The only exception is axios-retry, which defaults to total (with a shouldResetTimeout opt-in).

So, I'm wondering whether we should make retry.resetTimeout true by default.

Thoughts?

[sholladay]

The most intuitive model to me is where I provide the numRetries and the timeout for each attempt, and the total timeout of the operation is just the natural product of those inputs. So, basically what those other libraries are doing and resetTimeout = true.

That said, I think it's perfectly valid to want to also timeout the whole operation. The current behavior seems kind of backwards to me, though. It says, "By default, timeout is a total timeout across all retries, meaning later retries get progressively less time." If I were writing retry logic by hand, I would give successive retries equal or more time, not less.

[sindresorhus]

I found a better approach. totalTimeout option. With the new design, timeout just works the way everyone expects. If you also need a total cap, you opt into it explicitly with totalTimeout.

[sholladay]

I think it's pretty good but the difference between the timeout options is a little unclear at first glance. Maybe we should rename them?

• timeout -> attemptTimeout or retryTimeout (or retry.timeout)
• totalTimeout -> timeout

[sindresorhus]

Every major HTTP client uses plain timeout to mean per-request. So I think that's what people expect of a timeout option. totalTimeout is just a nice added bonus feature.

[sindresorhus]

I have tried to make the docs clearer though.