Add Rate Limiting Support

[thinkingserious]

We would like to add support for v3 Web API rate limits, as described here.

How would you like this to be implemented? Or please give a thumbs up to express your interest in us implementing to move this task up our queue.

PRs are always welcome as well :)

[awwa]

I believe this issue is about handleing the status 429 appropriately inside the library.

FYI:
My library rescues the TooManyRequests exception then sleep till x_ratelimit_remaining and retry.
This implementation will block the thread. I'm not sure this makes problem or not.

The make_request() method of the ruby-http-client may be appropriate spot to modify if I made same implementation.
https://github.com/sendgrid/ruby-http-client/blob/master/lib/ruby_http_client.rb#L169

def make_request(http, request)
  response = http.request(request)
  if response.status_code == 429
    duration = response.header['x_ratelimit_remaining'].to_i
    sleep duration if duration > 0
    retry
  end
  Response.new(response)
end

[BreadPaPa]

@thinkingserious Is this feature implemented or we need to handle 429 manually? Thanks.

[thinkingserious]

Hi @BreadPaPa,

Manually, currently. Please continue to follow this thread for updates.

With Best Regards,

Elme

[awj]

Agree with @awwa, this pretty much has to be patched into ruby-http-client.

API docs aren't clear on this, but it looks like X-RateLimit-Remaining is talking about how many requests are still possible, not how long to wait.

I wouldn't mind working on this. Initial idea would be to augment Sendgrid::Response with methods that wrap the X-RateLimit-* headers, or at least one that handles sleeping until the next reset. This would give end users easy ability to decide how to handle 429 statuses, but they'd have to inject that handling everywhere.

More appropriate would be to have the Client track the response's ratelimit state and consult it when issuing the next request. Auto-delaying the request until the next refresh is an option, but it will almost certainly need to be possible to disable it.

Any direction on auto vs. manual waiting for the rate limit? Maybe just both?

[awj]

Note: Above PR introduces a utility class to help users work with rate limit information. Can amend that PR or do another one for automatic rate limit handling.