Feature Request: API throttling reset information

[Iizuki]

Summary

The API should communicate when the ratelimit quota resets.

Issue

Currently the API only returns X-RateLimit-Limit and X-RateLimit-Remaining headers. This isn't quite enough to implement a robust, limit respecting API client. You can observe that the limit runs out but then what? How long to wait until continuing?

A client with side sliding window limit still sometimes hits 429, even when you leave a couple seconds leeway.

Solutions

X-RateLimit-Reset header

The commonly used X-RateLimit-Reset tells how long till the quota resets. Perhaps there's already support for this in the framework?

RateLimit header

This is the modern solution described in this internet draft. The idea is pack all of the info into one header in a standardized format. It supports more complex ratelimit algorithms as well.

(The spec also includes RateLimit-Policy header.)

[snipe]

If anyone wants to take a stab at this, this info and this info might help. We have our stuff set up slightly differently so it won't be quite as straightforward, but it's likely do-able.

[snipe]

Actually, I think we already have those headers. (These tests are currently failing because the numbers aren't right for the test, but...)

   FAILED  Tests\Feature\ApiRateLimitTest > rate limit
  Header [X-Ratelimit-Limit] was found, but value [120] does not match [10].
Failed asserting that '120' matches expected 10.

  at tests/Feature/ApiRateLimitTest.php:17
     13▕
     14▕         $this->actingAsForApi(User::factory()->viewUsers()->create())
     15▕             ->getJson(route('api.users.me'))
     16▕             ->assertOk()
  ➜  17▕             ->assertHeader('X-Ratelimit-Limit', 10)
     18▕             ->assertHeader('X-Ratelimit-Remaining', 9);
     19▕     }
     20▕
     21▕     public function testRateLimitDecreasesRemaining()

  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   FAILED  Tests\Feature\ApiRateLimitTest > rate limit decreases remaining
  Header [X-Ratelimit-Remaining] was found, but value [119] does not match [10].
Failed asserting that '119' matches expected 10.

  at tests/Feature/ApiRateLimitTest.php:27
     23▕         for ($x = 0; $x < 10; $x++) {
     24▕             $this->actingAsForApi(User::factory()->viewUsers()->create())
     25▕                 ->getJson(route('api.users.me'))
     26▕                 ->assertOk()
  ➜  27▕                 ->assertHeader('X-Ratelimit-Remaining', 10 - $x);
     28▕             }
     29▕
     30▕         $this->getJson(route('api.users.me'))
     31▕             ->assertStatus(429)

[snipe]

I have a PR up at #16986 - do you want to try to test that and see if it does what you need?