Hammer Rate-Limiting Library for Elixir

To implement a distributed, eventually consistent rate limiter across a cluster, you can combine Hammer with an ETS backend and use Phoenix.PubSub to broadcast hits.

Architecture

1. Local Counting: Use a module that calls use Hammer, backend: :ets to manage counters in local memory via ETS.
2. Broadcasting: When a hit occurs, broadcast an :inc message containing the key, scale, and increment value to a shared PubSub topic.
3. Synchronization: Run a GenServer (Listener) on every node that subscribes to the PubSub topic. When it receives an :inc message, it calls the local Hammer module to increment the counter, ensuring all nodes eventually reflect the same hit count.
4. Supervision: Wrap both the local Hammer module and the Listener process in a supervisor to manage their lifecycles.

defmodule MyApp.RateLimit do
  # 1. The local Hammer module using ETS
  defmodule Local do
    use Hammer, backend: :ets
  end

  # 2. The Listener that synchronizes remote hits
  defmodule Listener do
    use GenServer

    def start_link(opts) do
      pubsub = Keyword.fetch!(opts, :pubsub)
      topic = Keyword.fetch!(opts, :topic)
      GenServer.start_link(__MODULE__, {pubsub, topic})
    end

    def init({pubsub, topic}) do
      :ok = Phoenix.PubSub.subscribe(pubsub, topic)
      {:ok, []}
    end

    def handle_info({:inc, key, scale, increment}, state) do      
      _count = Local.inc(key, scale, increment)
      {:noreply, state}
    end
  end

  # 3. The main interface
  def hit(key, scale, limit, increment \ 1) do
    :ok = broadcast({:inc, key, scale, increment})
    Local.hit(key, scale, limit, increment)
  end

  # 4. Supervision setup
  def start_link(opts) do
    children = [{Local, opts}, {Listener, pubsub: @pubsub, topic: @topic}]
    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

To implement rate limiting, define a module that uses Hammer with a specific backend, start the process, and then call hit/3 to check if an action is allowed.

Core Concepts:

• Limit: Maximum number of actions allowed in a window.
• Scale: Duration of the time window (e.g., using :timer.minutes(1)).
• Key: A unique identifier (like a user ID) to scope the limit.

Return Values for hit/3:

• {:allow, count}: The action is permitted. count is the current number of hits in the window.
• {:deny, retry_after}: The action is denied. retry_after is the time in milliseconds to wait before retrying.

defmodule MyApp.RateLimit do
  use Hammer, backend: :ets
end

# Start the rate limiter process
MyApp.RateLimit.start_link()

user_id = 42
key = "upload_video:#{user_id}"
scale = :timer.minutes(1)
limit = 3

case MyApp.RateLimit.hit(key, scale, limit) do
  {:allow, _count} ->
    # upload the video
    :ok

  {:deny, retry_after} ->
    # deny the request
    {:error, :rate_limit, "try again in #{retry_after}ms"}
end

To use Hammer, you must define a module that uses the Hammer macro and specifies a backend. You then add this module to your application's supervision tree using start_link/1.

Using the ETS backend (In-memory)

For in-memory storage, use the :ets backend. You can provide a :clean_period to specify how often expired buckets are cleaned from the ETS table.

# Define
defmodule MyApp.RateLimit do
  use Hammer, backend: :ets
end

# Start in supervision tree
MyApp.RateLimit.start_link(clean_period: :timer.minutes(1))

Using the Redis backend (Distributed)

To persist data across multiple nodes, use the Hammer.Redis backend. Configuration options are the same as Redix, excluding :name which is derived from your module name.

# Define
defmodule MyApp.RateLimit do
  use Hammer, backend: Hammer.Redis
end

# Start with Redis host
MyApp.RateLimit.start_link(host: "redix.myapp.com")