View Source Hammer (hammer v6.2.1)

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.

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.

Same as check_rate/3, but allows the increment number to be specified. This is useful for limiting apis which have some idea of 'cost', where the cost of each hit can be specified.

Same as check_rate_inc/4, 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.

Functions

Link to this function

check_rate(id, scale_ms, limit)

View Source
@spec 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 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
Link to this function

check_rate(backend, id, scale_ms, limit)

View Source
@spec 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.

Link to this function

check_rate_inc(id, scale_ms, limit, increment)

View Source
@spec check_rate_inc(
  id :: String.t(),
  scale_ms :: integer(),
  limit :: integer(),
  increment :: integer()
) ::
  {:allow, count :: integer()}
  | {:deny, limit :: integer()}
  | {:error, reason :: any()}

Same as check_rate/3, but allows the increment number to be specified. This is useful for limiting apis which have some idea of 'cost', where the cost of each hit can be specified.

Link to this function

check_rate_inc(backend, id, scale_ms, limit, increment)

View Source
@spec check_rate_inc(
  backend :: atom(),
  id :: String.t(),
  scale_ms :: integer(),
  limit :: integer(),
  increment :: integer()
) ::
  {:allow, count :: integer()}
  | {:deny, limit :: integer()}
  | {:error, reason :: any()}

Same as check_rate_inc/4, but allows specifying a backend.

@spec 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}")
Link to this function

delete_buckets(backend, id)

View Source
@spec delete_buckets(backend :: atom(), id :: String.t()) ::
  {:ok, count :: integer()} | {:error, reason :: any()}

Same as delete_buckets/1, but allows specifying a backend

Link to this function

inspect_bucket(id, scale_ms, limit)

View Source
@spec 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 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}}
Link to this function

inspect_bucket(backend, id, scale_ms, limit)

View Source
@spec 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

Link to this function

make_rate_checker(id_prefix, scale_ms, limit)

View Source
@spec make_rate_checker(
  id_prefix :: String.t(),
  scale_ms :: integer(),
  limit :: integer()
) ::
  (id :: String.t() ->
     {:allow, count :: integer()}
     | {:deny, limit :: integer()}
     | {:error, reason :: any()})

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
Link to this function

make_rate_checker(backend, id_prefix, scale_ms, limit)

View Source
@spec make_rate_checker(
  backend :: atom(),
  id_prefix :: String.t(),
  scale_ms :: integer(),
  limit :: integer()
) ::
  (id :: String.t() ->
     {:allow, count :: integer()}
     | {:deny, limit :: integer()}
     | {:error, reason :: any()})