Add rate limiting retry middleware

[bluekeyes]

It would be helpful if the client creator provided an option to enable delays and retries in case of rate limiting. This should be optional because GitHub's hourly buckets mean you might have to wait a long time to try again. This also implies there should be an option for a maximum wait time, so if the retry header is past this value, the request can fail immediately. I expect this will be most useful if accidentally hitting the abuse limits (where the wait time is probably minutes), but could also be useful for regular limits.

[bluekeyes]

One catch: if an event blocks waiting to retry and then additional events are processed while it is waiting, the final observed state may be inconsistent. For instance, consider Policy Bot:

1. A pull request event happens, Policy Bot reads and caches partial PR state, and then blocks on the last read API call
2. A comment event happens while the first one is blocked, Policy Bot evaluates and posts a success status
3. The first event unblocks, finishes evaluating to pending (it does not see the comment from 2) and then "reverts" the status on the pull request in GitHub

Theoretically, the event in 2 will also block due to the non-expired rate limit, and the first event will wake up first, but this still seems like a potential race condition.

[adityakrmishra]

Hi @bluekeyes I am currently analyzing this issue and will file a PR for it shortly.

[hiSandog]

The consistency concern argues for exposing rate-limit information as a typed result (RetryAt, limit kind, maximum wait exceeded) rather than sleeping inside a request that already holds partially observed event state. An application could then discard that handler attempt and schedule the original delivery for a fresh replay after the reset, preserving its own ordering/idempotency policy. If blocking retry is still offered, it should honor context.Context cancellation and default to retrying only idempotent requests.