Starboard@mcsb/api / Exports / RateLimitDeferPolicy
Class: RateLimitDeferPolicy
Implementation of IDeferPolicy that is used to defer outgoing HTTP requests based on a set of three rate limit HTTP headers:
- A header indicating the total number of requests the client is allowed to make within the rate limit interval
- A header indicating the number of remaining requests the client is allowed to make until the next reset
- A header indicating the number of seconds remaining until the next reset
This class also allows short bursts of requests to flow through without being deferred, at the risk of later requests being deferred for longer. Bursting can be disabled by passing a burst ratio of 1.0.
The header names, default reset interval, built-in buffer, and burst settings can be configured via the constructor.
This class was primarily designed to work with the Hypixel API rate limits.
See
https://api.hypixel.net/#section/Introduction/Limits
Implements
Table of contents
Constructors
Methods
Constructors
constructor
• new RateLimitDeferPolicy(limitHeaderName?, remainingHeaderName?, resetHeaderName?, defaultResetInterval?, buffer?, burstCap?, burstInterval?, burstRequiredRatio?)
Constructor
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
limitHeaderName | string | "RateLimit-Limit" | The name of the header that contains the total request limit per reset interval. |
remainingHeaderName | string | "RateLimit-Remaining" | The name of the header that contains the remaining number of allowed requests in our current reset interval. |
resetHeaderName | string | "RateLimit-Reset" | The name of the header that contains the number of seconds until the next reset. |
defaultResetInterval | number | 300_000 | The default number of milliseconds between reset intervals. This is used to estimate the required debounce before we've received our first response via notify. |
buffer | number | 0.02 | A value between 0 and 1 representing how much of the total should NOT be used by the API. Setting this to 0 could result in requests towards the end of the reset interval hitting the rate limit. |
burstCap | number | 3 | Max number of allowed burst requests within each burst interval. To disable bursting, you can set this to 0. |
burstInterval | number | 3_000 | Length of each burst interval in milliseconds. Internally setInterval is used, so setting this to a value less than ~20 could have unintended effects. |
burstRequiredRatio | number | 0.5 | A value between 0 and 1 representing how many requests must be remaining within the current reset interval for bursting to be used. This can be set to 0 to have bursting enabled all the time, or 1 to disable bursting completely. |
Defined in
packages/api/src/defer/RateLimitDeferPolicy.ts:147
Methods
destroy
▸ destroy(): void
Destroy this RateLimitDeferPolicy instance, primarily by shutting down the burst interval. Failure to do so may leave your program hanging if you do not explicitly interrupt it.
Returns
void
Defined in
packages/api/src/defer/RateLimitDeferPolicy.ts:175
notify
▸ notify(res): void
Method used to notify an IDeferPolicy when a deferred task completes, i.e. when the deferred request's HTTP response comes back. This may be useful for retrieving rate limit data from the response, or for maintaining a record of how many requests are currently in transit to/from the API.
Parameters
| Name | Type | Description |
|---|---|---|
res | Response | The value of type T that is delivered with the notification. |
Returns
void
Implementation of
Defined in
packages/api/src/defer/RateLimitDeferPolicy.ts:238
poll
▸ poll(): Promise<void>
Async method that controls the flow of an upcoming task by resolving when it's time to start the task.
Returns
Promise<void>
A Promise that resolves when it is okay to start the next task. If the Promise never resolves, the task will never start.