[ProdigyTom]

Changes

Exposes Auth0's rate-limit information (x-ratelimit-limit / -remaining / -reset) from every Management and Authentication API response, via an opt-in handler, so callers can monitor how close they are to the limit (the ask in #606).

• Auth0::Internal::Http::RateLimit — value object (limit, remaining as Integers; reset as a UTC Time). Blank/non-numeric header values become nil (never a misleading 0). Two builders: from_http_response (Management/RawClient, Net::HTTP) and from_headers (Authentication/HTTPProxy, RestClient).
• rate_limit_handler option on Auth0::Client, invoked with the parsed RateLimit after every response on both API paths.
• Every response is reported, including the 429s that trigger an automatic retry, so a handler watching remaining sees the point where it ran out.
• Non-breaking: the return value of API calls is unchanged. A handler error is caught and warned (so broken monitoring is visible) but never breaks a request.
• Management wiring attaches the handler to the generated client's raw client and raises if it can't (so a future internals change fails loudly rather than silently disabling the feature).
• All changes live in fernignored files (lib/auth0/internal/**, lib/auth0/mixins/**, lib/auth0/auth_client.rb), so they survive regeneration.
• README + EXAMPLES documentation and unit tests (value object, retried-request notification, token-rebuild re-attach, Authentication path, client wiring).

client = Auth0::Client.new(
  domain: ENV["AUTH0_DOMAIN"],
  client_id: ENV["AUTH0_CLIENT_ID"],
  client_secret: ENV["AUTH0_CLIENT_SECRET"],
  rate_limit_handler: ->(rl) { StatsD.gauge("auth0.rate_limit.remaining", rl.remaining) if rl.remaining }
)
client.users.get(id: "auth0|123") # handler fires with the response's rate limit

References

• Refs Rate limit data returned from API methods #606
• Note: this PR originally implemented Rate limit data returned from API methods #606 against v5; it has been updated in place to target the v6 architecture.

Testing

Unit tests under test/unit/ cover header parsing (symbol/dashed/mixed-case keys, 0 vs blank/non-numeric, reset + whitespace), notification on every response across a retried request, the handler error being swallowed, the Authentication-API path, and the client wiring (including re-attach after a token-triggered rebuild). Full rake test passes locally with no failures.

• This change adds unit test coverage
• This change adds integration test coverage
• This change has been tested on the latest version of Ruby

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors
• Rubocop passes on all added/modified files
• All active GitHub checks have passed

[kishore7snehil]

@ProdigyTom I can see some merge conflicts. Can you please resolve them? Post that I can take a look

[ProdigyTom]

@kishore7snehil my original change was against v5 and after the change to v6 I wasn't really able to resolve my merge conflicts in a way that still solved our problem. The rate limiting information gets dropped earlier in some generated code. So I wound up going a slightly different direction. let me know if it makes sense