Expose Management API rate limit info via a client callback

[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

[kishore7snehil]

This reaches into the generated Management client for its @raw_client by instance variable, and the if raw_client means that if a future regeneration renames or restructures that variable, the handler just never gets attached and the feature goes quiet with no error anywhere. This file is kept across regeneration but the generated class it reaches into is not, so the two can drift apart and nothing would flag it.

We should be handling this carefully.

[ProdigyTom]

I have made this raise a Auth0::Unsupported error for now so that a future internals change surfaces immediately instead of silently skipping.

I'm using the ivar because the generated Auth0::Management doesn't expose its raw client, and since that class is regenerated, we can't add an accessor from our side without it being clobbered. If you'd be open to exposing a public reader for the raw client on the generated Management class, I would switch to it and drop the instance_variable_get entirely.

[kishore7snehil]

A public reader on Auth0::Management would be the cleaner fix, but that class is generated, so a hand edit would be overwritten on the next regen. It would need to come from the Fern side, so not blocking this PR on it.

The respond_to? check with the raise is enough for now, since a rename would fail loudly instead of silently dropping the handler.

One small question on the error. Auth0::Unsupported is part of the HTTP error family, and this isn't an HTTP failure. Would a plain Auth0::Exception fit better here?