Add a `shouldRetry` option

[TheHolyWaffle]

The default retry options ensure POST requests are not retried. This logic makes sense when the target HTTP server can respond.
However, when there is a network error such as a connection timeout or a DNS resolution that's taking too long, then a TypeError: fetch failed is thrown.

It would be convenient if these "network errors" were retried, regardless of the configured methods and statusCodes in the retry options 🙏

Refs:

• is-network-error: https://github.com/sindresorhus/is-network-error

[sholladay]

Indeed, we're bypassing the retry function if the request method doesn't match the retry options, before the request is sent.

If we wanted to retry network errors for every method, we would need to send the request first and wait to see the result.

The downside is that, technically speaking, if the server handles the POST but then fails to respond, or if the response fails to be received, then we'll see it as a network error, and it will be retried and potentially applied twice on the server. I'm curious how other HTTP clients, such as curl, handle this.

[sholladay]

From what I can tell, most other HTTP clients treat network errors as fatal for POST requests and do not retry. So, the same as what Ky does currently. And that's definitely the safer approach.

Here's what I propose. We keep the current behavior, but add an ability for the user to supply an idempotency key, which when present allows retries for all methods. The server has to cooperate and implement support for the key and handle it correctly, of course. But this enforces correctness from Ky's perspective.

[TheHolyWaffle]

I can see how an idempotency key can resolve this. However, in our scenario this is overkill because the server is not doing any irreversible modifications. So retrying is a safe operation and good enough. Also retrying does not require any changes to the server, unlike handling an idempotency key.

An alternative proposal, how about a shouldRetry config option? This can be a user-supplied function which is called with the HTTPError or TypeError in case of network issues. There the user can still decide to only retry when the error is a network error, and not a 4xx or 5xx response?

[sholladay]

I am fine with that, too. However, if all of your POST endpoints are always idempotent or reversible and you don't foresee that ever changing, then you don't need a new option. You can just set retry.methods.