hammer v4.0.0 Hammer View Source
Documentation for Hammer module.
This is the main API for the Hammer rate-limiter. This module assumes a backend pool has been started, most likely by the Hammer application.
Link to this section Summary
Functions
Check if the action you wish to perform is within the bounds of the rate-limit
Same as check_rate/3, but allows specifying a backend
Delete all buckets belonging to the provided id, including the current one. Effectively resets the rate-limit for the id
Same as delete_buckets/1, but allows specifying a backend
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
Same as inspect_bucket/3, but allows specifying a backend
Make a rate-checker function, with the given id
prefix, scale_ms and limit
Link to this section Functions
check_rate(id :: String.t, scale_ms :: integer, limit :: integer) :: {:allow, count :: integer} | {:deny, limit :: integer} | {:error, reason :: any}
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 millisecondslimit
: 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
check_rate(backend :: atom, id :: String.t, scale_ms :: integer, limit :: integer) :: {:allow, count :: integer} | {:deny, limit :: integer} | {:error, reason :: any}
Same as check_rate/3, but allows specifying a backend
delete_buckets(id :: String.t) :: {:ok, count :: integer} | {:error, reason :: any}
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}")
delete_buckets(backend :: atom, id :: String.t) :: {:ok, count :: integer} | {:error, reason :: any}
Same as delete_buckets/1, but allows specifying a backend
inspect_bucket(id :: String.t, scale_ms :: integer, limit :: integer) :: {:ok, {count :: integer, count_remaining :: integer, ms_to_next_bucket :: integer, created_at :: integer | nil, updated_at :: integer | nil}} | {:error, reason :: any}
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 millisecondslimit
: 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}}
inspect_bucket(backend :: atom, id :: String.t, scale_ms :: integer, limit :: integer) :: {:ok, {count :: integer, count_remaining :: integer, ms_to_next_bucket :: integer, created_at :: integer | nil, updated_at :: integer | nil}} | {:error, reason :: any}
Same as inspect_bucket/3, but allows specifying a backend
Make a rate-checker function, with the given id
prefix, scale_ms and limit.
Arguments:
id_prefix
: String prefix to theid
scale_ms
: Integer indicating size of bucket in millisecondslimit
: 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