feat: use error information to calculate backoff

[aisbergg]

I like the implementation concept of go-retry, but it doesn't support backoff calculation based on the response. My use case: Calculate the backoff delay based on different HTTP responses. For example a 427 HTTP response would take the "Retry-After" header into consideration while a 5XX response would do something different.

Essentially I changed the Backoff interface as such:

type Backoff interface {
	// Next takes the error and returns the time duration to wait and the
	// processed error. A duration less than zero signals the backoff to stop
	// and to not retry again.
	Next(err error) (time.Duration, error)
}

This way the backoff calculation can work on error information (e.g. HTTP response information) and modify the (retry-)error if necessary.

There are some other changes mixed in this PR. I just thought I would show you, maybe you are interested into integrating stuff like this (I know it is quite a lot os changes...).

[sethvargo]

Hi @aisbergg

Thank you for opening a PR. Unfortunately we should not change the interface, as there are downstream consumers and packages that depend on the existing interface.

For HTTP Retry-After, I don't think you would need to use this library. You could just sleep for the header's returned value.

I'd definitely accept some of the documentation updates though!

[aisbergg]

Cherry Pick what you like, I don't mind. The PR is more like 'FYI' style.

Regarding the Retry-After header, the current backoff calculation cannot distinguish between different errors. I could just wait like 60s and hope that this would take care of it, but that would be inappropriate for other errors, like temporary Network errors. I do use my changes for different requests as well, like GraphQL, which may contain retry information inside the payload, so yeah, I need some mechanism to deal with this.

[github-actions]

This pull request has been automatically locked since there has not
been any recent activity after it was closed. Please open a new
issue for related bugs.