Documentation for Hammer module.

Usage example:

use Hammer, backend: Hammer.Backend.ETS

The following functions are created:

check_rate(id::String.t, scale_ms::integer, limit::integer)

Check if the action you wish to perform is within the bounds of the rate-limit.

Args:

• id: String name of the bucket. Usually the bucket name is comprised of some fixed prefix, with some dynamic string appended, such as an IP address or user id.
• scale_ms: Integer indicating size of bucket in milliseconds
• limit: Integer maximum count of actions within the bucket

Returns either {:allow, count}, {:deny, limit} or {:error, reason}

Example:

user_id = 42076
case  check_rate("file_upload:#{user_id}", 60_000, 5) do
  {:allow, _count} ->
    # do the file upload
  {:deny, _limit} ->
    # render an error page or something
end

inspect_bucket(id::String.t, scale_ms::integer, 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. Usually the bucket name is comprised of some fixed prefix, with some dynamic string appended, such as an IP address or user id.
• scale_ms: Integer indicating size of bucket in milliseconds
• limit: Integer maximum count of actions within the bucket

Returns either {:ok, {count, count_remaining, ms_to_next_bucket, created_at, updated_at}, or {:error, reason}.

Example:

inspect_bucket("file_upload:2042", 60_000, 5)
{:ok, {1, 2499, 29381612, 1450281014468, 1450281014468}}

delete_buckets(id::String.t)

Delete all buckets belonging to the provided id, including the current one. Effectively resets the rate-limit for the id.

Arguments:

• id: String name of the bucket

Returns either {:ok, count} where count is the number of buckets deleted, or {:error, reason}.

Example:

user_id = 2406
{:ok, _count} = delete_buckets("file_uploads:#{user_id}")

make_rate_checker

Make a rate-checker function, with the given id prefix, scale_ms and limit.

Arguments:

• id_prefix: String prefix to the id
• scale_ms: Integer indicating size of bucket in milliseconds
• limit: Integer maximum count of actions within the bucket

Returns a function which accepts an id suffix, which will be combined with the id_prefix. Calling this returned function is equivalent to: Hammer.check_rate("#{id_prefix}#{id}", scale_ms, limit)

Example:

chat_rate_limiter = make_rate_checker("send_chat_message:", 60_000, 20)
user_id = 203517
case chat_rate_limiter.(user_id) do
  {:allow, _count} ->
    # allow chat message
  {:deny, _limit} ->
    # deny
end