View Source Nostrum.Store.RatelimitBucket behaviour (Nostrum v0.8.0)
Behaviour & dispatcher for storing ratelimit buckets.
purpose
Purpose
Calls to Discord's API are ratelimited, and we are informed about our
remaining calls by Discord after issuing them. This module concerns itself
with storing this information to prevent running into HTTP 429 errors. As
this is used mainly by Nostrum.Api.Ratelimiter, it is unlikely you need to
use it directly yourself.
configuration
Configuration
By default, nostrum will use Elixir.Nostrum.Store.RatelimitBucket.ETS to store ratelimit
buckets. To override this, set the [:stores, :ratelimit_buckets] setting on
nostrum's application configuration:
config :nostrum,
stores: %{
ratelimit_buckets: MyBot.Nostrum.Store.RatelimitBucket
}This setting must be set at compile time.
implementation
Implementation
If implementing your own ratelimit bucket store, in addition to the callbacks
of this module, you must also provide the function child_spec/1. The
recommended approach is to spawn a Supervisor to manage your store.
Link to this section Summary
Types
Individual bucket information for a route.
Latency between us and our latest call for this bucket, in milliseconds.
Remaining calls for a bucket.
Time at which a bucket resets, in milliseconds.
The route a bucket applies to.
Callbacks
Retrieve the child specification for starting this mapping under a supervisor.
Clean up entries in the bucket older than the given amount of milliseconds.
Retrieve bucket information by route.
Update the given bucket to have the given remaining calls.
Update the given bucket with full rate limit information.
Functions
Receive the time to wait before issuing more calls to the given route.
Link to this section Types
@type bucket() :: {route(), remaining(), reset_time(), latency()}
Individual bucket information for a route.
@type latency() :: pos_integer()
Latency between us and our latest call for this bucket, in milliseconds.
@type remaining() :: non_neg_integer()
Remaining calls for a bucket.
@type reset_time() :: pos_integer()
Time at which a bucket resets, in milliseconds.
@type route() :: String.t()
The route a bucket applies to.
The constant value "GLOBAL" is used for the global bucket.
Link to this section Callbacks
@callback child_spec(term()) :: Supervisor.child_spec()
Retrieve the child specification for starting this mapping under a supervisor.
@callback cleanup(pos_integer()) :: non_neg_integer()
Clean up entries in the bucket older than the given amount of milliseconds.
This function is called automatically by the ratelimiter in regular intervals.
Return the amount of deleted entries.
Retrieve bucket information by route.
If no information is available, return nil.
Update the given bucket to have the given remaining calls.
Normally used after issuing an API call for a previously used route.
@callback update(route(), remaining(), reset_time(), latency()) :: :ok
Update the given bucket with full rate limit information.
Whilst update/2 is based around the assumption that you only know the
remaining calls (for instance, after issuing one), this function is used
after receiving full rate limiting information after an API call.
Link to this section Functions
timeout_for(route, store \\ Nostrum.Store.RatelimitBucket.ETS)
View Source (since 0.8.0)Receive the time to wait before issuing more calls to the given route.
This function must only be called prior to issuing the actual API call: it will decrement the remaining calls counter from the given bucket.
Nostrum takes the API latency into account when issuing these calls, and uses the current time to determine when it expires. It is therefore assumed that each node has a relatively equal latency to the API, and the nodes have little to no time drift.