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

check_rate(id, scale, limit)

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 bucket
  • scale (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}
delete_bucket(id)

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
inspect_bucket(id, scale, limit)

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 bucket
  • scale (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}
start_link(opts \\ [])

Starts the ExRated rate limit counter server.

stop(server)

Stop the rate limit counter server.