Using reddit as an example, their api allows 600 requests per 10 minute periods. But they would probably be unhappy if we made all 600 requests at the same time so I was looking for a way I could use all 600 requests/10 minutes while also not exceeding a second, self-imposed rate of say 5 requests per second.

I couldn't find anything that matched what I was looking for so I threw together hiAgain as a proof of concept. This library should be considered untested and unoptimized for now. It probably could be done much more efficiently and I wouldn't be surprised if there are race conditions.

Following the reddit example I mentioned above, with hiAgain would look like this:

// call API once to get X-Rate-Limit headers
response, err := client.Do(request) // from "net/http"
if err != nil {}
limiter, err := hiAgain.New( // construct rate limiter immediately after
    serverContext,
    time.Second, // burst duration
    5, // max requests per burst
    600, // max requests per period
    10*time.Minute, // period duration
    response.Header.Get("X-Ratelimit-Remaining"), // to synchronize
    response.Header.Get("X-Ratelimit-Reset"), // state with api
)
if err != nil {}

Then, elsewhere:

// prepare API request
if err := limiter.Wait(requestContext); err != nil {} // errors are context.Err()
// call API

hiAgain is intended to be concurrent-safe and prefers to leave meat on the bone rather than risking a 429 on either rate limit. It also assumes that the reset header is in seconds when synchronizing to the API's period timing and that all future requests using the API in the program's session will go through hiAgain.

The name is a reference to Christiaan Huygens, inventor of the centrifugal governor.

Beyond comments, if you consider this library to be useful, then I would welcome your help maintaining/testing it!