Limitex

A pure Elixir distributed rate limiter based on the Token Bucket algorithm.

Limitex uses sharded ETS tables with write and read concurrency enabled, node clustering is not handled, something like libcluster is recomended.

Installation

You can add this package to your project dependencies:

# mix.exs
def deps do
  [
    {:limitex, git: "https://github.com/pggalaviz/limitex.git"}
  ]
end

Usage

Limitex exports a single function: check_rate/3 and check_rate/4.

• check_rate(id, bucket_time, limit)
• check_rate(id, bucket_time, limit, increment)

which return an {:ok, count} or {:error, :rate_limited} tuples.

Parameters

• id is a string to identify who's requesting the action, it can be composed of a unique part such as an IP address or a user ID, plus some action identifier (see example below).

• bucket_time is the amount of time you want to rate limit the action for the ID, must be given in milliseconds.

• limit is an integer which determines how many times we're allowed to perform the action in the given time.

• increment each time you call the function, the count to reach the limit is increased by 1 as a default, you can alternatively pass an arbitrary integer to increase the limit.

Examples

Inside your app you can call it inside any function:

defmodule MyApp.Upload do

  def upload(video_data, user_id) do
    case Limitex.check_rate("upload:#{user_id}", 60_000, 5) do
      {:ok, _count} ->
        # upload the video, somehow
      {:error, :rate_limited} ->
        # deny the request
    end
  end

end

So in the above example we'll limit user's uploads to 5 every 60 seconds.

Configuration

Limitex will perform scheduled cleanups to remove expired buckets, to handle this, we should provide a cleanup interval and an expiry:

# inside config.exs

config :limitex,
  cleanup_interval: 60_000,
  expiry: 300_000

Table cleanups will be scheduled every minute in this example (defaults to 5 minutes), and will delete buckets where expiry has already passed, it's important to give a value greater than the biggest bucket we create (the bucket_time param in check_rate function).

So if we're creating a bucket of 1 hour: Limitex.check_rate("some_id", 3_600_000, 20) we should give a bigger number in our config to prevent cleanup to delete buckets which are not yet expired:

# inside config.exs

config :limitex,
  expiry: 3_800_000

expiry defaults to 15 minutes.

Benchmarks

Basic benchmarks can be run with mix bench.