Add retry policies

[seanmonstar]

This adds retry policies, somewhat kind of like redirect policies. This includes a new ClientBuilder::retry() method, and a reqwest::retry module to build a retry policy.

Example

let retries = reqwest::retry::for_host("api.github.com")
    .classify_fn(|req_rep| {
        if req_rep.status() == Some(SERVICE_UNAVAILABLE) {
            req_rep.retryable()
        } else {
            req_rep.success()
       }
    })

Closes #316
Closes #2577

[AMDmi3]

The default retry behavior of a Client is to only retry requests where an error or low-level protocol NACK is encountered that is known to be safe to retry

Do I understand correctly with 0.12.22 retries were not possible at all, and now the default policy is to enable some retries?

In that case it's a breaking change. I alone have two cases affected by this, one is API client that maintains fixed request rate and will be banned as soon as it exceeds the maximum, which becomes possible after suddenly introduced retries. Another case is generic link checker which a) maintains strict politeness policy of no more than 1/3RPS (it implements its own retry and redirect handling, and each request must as well be subject to throttling) and b) must strictly report each failure as-is.

I suggest to yank this release and re-release as 0.13. And if I may express an opinion, I'd strongly prefer any extra logic on top of base HTTP request functionality to be opt-in. That includes redirect handling, but since you already have these enabled by default, the statement may be limited to "any new extra logic". Otherwise, each library user would have to go through ClientBuilder documentation to check for features which may interfere with their logic and need to be disabled, and repeat this before each dependency update.

[seanmonstar]

Do I understand correctly with 0.12.22 retries were not possible at all, and now the default policy is to enable some retries?

Nope. This is behavior that has been inside the reqwest client for a long while, and now you can finally customize it.

It's never automatically interpreted any status code, but in something like HTTP/2 where a signal can indicate "I'm closing this connection and everything above stream id 123 has been ignored", then reqwest would retry those on a new connection. That's the default. Now, you can disable that by providing a retry::never().

[AMDmi3]

Thank you for the explanation! This way it looks good wrt. breaking changes, and I'm no longer sure whether it's a good or bad default. From the point of strict rate limiting it is probably not, but at the same time it's a kind of failure you don't expect without having complete understanding of how persistent HTTP connections work. I may only suggest now to add a few words explaining what low-level protocol NACK and safe to retry are, e.g. that these are related to reopening persistent HTTP sessions when needed, as again, for those without HTTP internals understanding, the current wording may be misleading.