proposal: x/time/rate: allow setting available tokens in Limiter

[mitar]

Proposal Details

Currently, golang.org/x/time/rate.Limiter allows setting limit and burst, but not available buckets.

I am interested in the use case where I use Limiter to limit my own calls towards a 3rd party API endpoint. Many APIs, including the expired RFC draft return in response to API calls a header which tells how many more requests you can make before hitting a limit, for example, something like RateLimit-Remaining header or something like that, Anthropic returns anthropic-ratelimit-requests-remaining.

I am proposing that Limiter get SetTokens(float64) method which would allow updating current's available tokens so that it can be kept in sync with the 3rd party server. There might be reasons why Limiter would get out of sync with the server, for example, user is calling some additional requests not through the limiter, or there were requests consumed prior to starting the limiter which the program is unaware of and has to sync the initial state with the server.

[gabyhelp]

Related Issues and Documentation

• proposal: x/time/rate: add tokens apart of time #53204
• x/time/rate: expose the number of remaining tokens #50035 (closed)
• proposal: x/time/rate: expose number of available tokens for metrics/testing #18233
• x/time/rate: convert Limit to an Interface #43003

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[ianlancetaylor]

CC @Sajmani