ExRated v1.2.2 ExRated
An Elixir OTP GenServer that provides the ability to manage rate limiting for any process that needs it. This rate limiter is based on the concept of a 'token bucket'. You can read more here:
http://en.wikipedia.org/wiki/Token_bucket
This application started as a direct port of the Erlang 'raterlimiter' project created by Alexander Sorokin (https://github.com/Gromina/raterlimiter, gromina@gmail.com, http://alexsorokin.ru) and the primary credit for the functionality goes to him. This has been implemented in Elixir as a learning experiment and I hope you find it useful. Pull requests are welcome.
Summary
Functions
Check if the action you wish to take is within the rate limit bounds and increment the buckets counter by 1 and its updated_at timestamp
Delete bucket to reset the counter
Inspect bucket to get count, count_remaining, ms_to_next_bucket, created_at, updated_at. This function is free of side-effects and should be called with the same arguments you would use for check_rate
if you intended to increment and check the bucket counter
Starts the ExRated rate limit counter server
Stop the rate limit counter server
Functions
Specs
check_rate(id :: String.t, scale :: integer, limit :: integer) ::
{:ok, count :: integer} |
{:error, limit :: integer}
Check if the action you wish to take is within the rate limit bounds and increment the buckets counter by 1 and its updated_at timestamp.
Arguments:
id
(String) name of the bucketscale
(Integer) of time in ms until the bucket rolls over. (e.g. 60_000 = empty bucket every minute)limit
(Integer) the max size of a counter the bucket can hold.
Examples
# Limit to 2500 API requests in one day.
iex> ExRated.check_rate("my-bucket", 86400000, 2500)
{:ok, 1}
Specs
delete_bucket(id :: String.t) :: :ok | :error
Delete bucket to reset the counter.
Arguments:
id
(String) name of the bucket
Example - Reset counter for my-bucket
iex> ExRated.check_rate("my-bucket", 86400000, 2500)
{:ok, 1}
iex> ExRated.delete_bucket("my-bucket")
:ok
Specs
inspect_bucket(id :: String.t, scale :: integer, limit :: integer) ::
{:ok, count :: integer} |
{:error, limit :: integer}
Inspect bucket to get count, count_remaining, ms_to_next_bucket, created_at, updated_at. This function is free of side-effects and should be called with the same arguments you would use for check_rate
if you intended to increment and check the bucket counter.
Arguments:
id
(String) name of the bucketscale
(Integer) of time the bucket you want to inspect was created with.limit
(Integer) representing the max counter size the bucket was created with.
Example - Reset counter for my-bucket
ExRated.inspect_bucket("my-bucket", 86400000, 2500)
{0, 2500, 29389699, nil, nil}
ExRated.check_rate("my-bucket", 86400000, 2500)
{:ok, 1}
ExRated.inspect_bucket("my-bucket", 86400000, 2500)
{1, 2499, 29381612, 1450281014468, 1450281014468}