View Source Hammer behaviour (hammer v7.0.0-rc.3)

Hammer is a rate-limiting library for Elixir.

It provides a simple way for creating rate limiters, and comes with a built-in ETS backend.

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

# Start the rate limiter, in case of ETS it will create the ETS table and schedule cleanups
MyApp.RateLimit.start_link(clean_period: :timer.minutes(10))

# Check the rate limit allowing 10 requests per second
MyApp.RateLimit.hit("some-key", _scale = :timer.seconds(1), _limit = 10)

Summary

Types

count()

increment()

key()

limit()

scale()

Callbacks

get(key, scale)

Optional callback for getting the counter value for a key.

hit(key, scale, limit)

Checks if a key is allowed to perform an action, and increment the counter.

hit(key, scale, limit, increment)

Optional callback to check if a key is allowed to perform an action, and increment the counter.

inc(key, scale)

Same as inc/3 with increment set to 1.

inc(key, scale, increment)

Optional callback for incrementing a counter value for a kit without performing limit check.

set(key, scale, count)

Optional callback for setting the counter value for a key.

Functions

__using__(opts)

Use the Hammer library in a module to create a rate limiter.

Types

count()

@type count() :: pos_integer()

increment()

@type increment() :: non_neg_integer()

key()

@type key() :: term()

limit()

@type limit() :: pos_integer()

scale()

@type scale() :: pos_integer()

Callbacks

get(key, scale)

(optional)

@callback get(key(), scale()) :: count()

Optional callback for getting the counter value for a key.

Returns the current counter value.

hit(key, scale, limit)

@callback hit(key(), scale(), limit()) :: {:allow, count()} | {:deny, timeout()}

Checks if a key is allowed to perform an action, and increment the counter.

Same as hit/4 with increment set to 1.

hit(key, scale, limit, increment)

(optional)

@callback hit(key(), scale(), limit(), increment()) ::
  {:allow, count()} | {:deny, timeout()}

Optional callback to check if a key is allowed to perform an action, and increment the counter.

Returns {:allow, count} if the action is allowed, or {:deny, timeout} if the action is denied.

This is the only required callback.

inc(key, scale)

(optional)

@callback inc(key(), scale()) :: count()

Same as inc/3 with increment set to 1.

inc(key, scale, increment)

(optional)

@callback inc(key(), scale(), increment()) :: count()

Optional callback for incrementing a counter value for a kit without performing limit check.

Returns the new counter value.

set(key, scale, count)

(optional)

@callback set(key(), scale(), count()) :: count()

Optional callback for setting the counter value for a key.

Returns the new counter value.

Functions

using(opts)

(macro)

Use the Hammer library in a module to create a rate limiter.

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