Hammer

A rate-limiter for Elixir, with pluggable storage backends.

New! Hammer-Plug

We've just released a new helper-library to make adding rate-limiting to your Phoenix (or other plug-based) application even easier: Hammer.Plug.

Installation

Hammer is available in Hex, the package can be installed by adding hammer to your list of dependencies in mix.exs:

def deps do
  [{:hammer, "~> 6.0"}]
end

Documentation

On hexdocs: https://hexdocs.pm/hammer/frontpage.html

The Tutorial is an especially good place to start.

Usage

Example:

defmodule MyApp.VideoUpload do

  def upload(video_data, user_id) do
    case Hammer.check_rate("upload_video:#{user_id}", 60_000, 5) do
      {:allow, _count} ->
        # upload the video, somehow
      {:deny, _limit} ->
        # deny the request
    end
  end

end

The Hammer module provides the following functions:

check_rate(id, scale_ms, limit)
check_rate_inc(id, scale_ms, limit, increment)
inspect_bucket(id, scale_ms, limit)
delete_buckets(id)

Backends are configured via Mix.Config:

config :hammer,
  backend: {Hammer.Backend.ETS, [expiry_ms: 60_000 * 60 * 4,
                                 cleanup_interval_ms: 60_000 * 10]}

See the Tutorial for more.

See the Hammer Testbed app for an example of using Hammer in a Phoenix application.

Available Backends

Hammer.Backend.ETS (provided with Hammer for testing and dev purposes, not very good for production use)
Hammer.Backend.Redis
Hammer.Backend.Mnesia (beta)

Getting Help

If you're having trouble, either open an issue on this repo, or reach out to the maintainers (@shanekilkelly) on Twitter.

Acknowledgements

Hammer was inspired by the ExRated library, by grempe.

ryanwinchester / hammer