Hammer.Atomic.FixWindowPerKey (hammer v7.4.0)

Copy Markdown View Source

This module implements a per-key fixed window rate-limiting algorithm using Erlang's :atomics module for atomic counters.

Like the standard fixed window algorithm, requests are counted within a window of duration scale. Unlike the standard fixed window — which aligns every key to the same wall-clock boundary (multiples of scale since the Unix epoch) — this variant anchors each key's window to that key's first hit.

For example, with a scale of 60 seconds:

  • User A's first request at 12:00:37 → A's window runs until 12:01:37
  • User B's first request at 12:00:51 → B's window runs until 12:01:51

Once a key's window expires, the next hit for that key opens a fresh window starting at that moment.

The algorithm

  1. When a request comes in for a key:
    • If the key has an active window (expires_at > now), increment its atomic counter.
    • Otherwise, start a new window: reset the counter to increment and set expires_at = now + scale.
  2. If the counter is <= limit → allow. Otherwise → deny and return time until the current window expires.

When to use this vs :fix_window and :sliding_window

The 2x boundary burst that affects :fix_window is still theoretically possible here, just at a per-key boundary instead of a globally synchronized one. The practical benefit is that boundaries are not globally synchronized, so they are harder to exploit deterministically, and a key has to wait a full scale between burst opportunities.

This is essentially the same algorithm as the common Redis INCR + EXPIRE NX rate-limiting pattern.

Options

  • :clean_period - How often to run the cleanup process (in milliseconds). Defaults to 1 minute.
  • :key_older_than - Maximum age for entries (in milliseconds) past their expiry before they are removed during cleanup. Defaults to 24 hours.

Example

Example configuration:

MyApp.RateLimit.start_link(
  clean_period: :timer.minutes(5),
)

Example usage:

defmodule MyApp.RateLimit do
  use Hammer, backend: :atomic, algorithm: :fix_window_per_key
end

MyApp.RateLimit.start_link(clean_period: :timer.minutes(1))

# Allow 10 requests per second
MyApp.RateLimit.hit("user_123", 1000, 10)

Summary

Functions

expires_at(table, key, scale)

Returns the expiration time (in milliseconds) of the current window for a given key.

get(table, key, scale)

Returns the current count for a given key.

hit(table, key, scale, limit, increment)

Checks if a key is allowed to perform an action based on the per-key fixed window algorithm.

inc(table, key, scale, increment)

Increments the counter for a given key without performing a limit check.

set(table, key, scale, count)

Sets the counter for a given key, refreshing the window to now + scale.

Functions

expires_at(table, key, scale)

@spec expires_at(table :: atom(), key :: term(), scale :: pos_integer()) ::
  non_neg_integer()

Returns the expiration time (in milliseconds) of the current window for a given key.

Returns 0 if the key has no active window.

get(table, key, scale)

@spec get(table :: atom(), key :: term(), scale :: pos_integer()) :: non_neg_integer()

Returns the current count for a given key.

Returns 0 if the key has no active window (either never hit, or window has expired).

hit(table, key, scale, limit, increment)

@spec hit(
  table :: atom(),
  key :: term(),
  scale :: pos_integer(),
  limit :: pos_integer(),
  increment :: pos_integer()
) :: {:allow, non_neg_integer()} | {:deny, non_neg_integer()}

Checks if a key is allowed to perform an action based on the per-key fixed window algorithm.

inc(table, key, scale, increment)

@spec inc(
  table :: atom(),
  key :: term(),
  scale :: pos_integer(),
  increment :: pos_integer()
) :: non_neg_integer()

Increments the counter for a given key without performing a limit check.

set(table, key, scale, count)

@spec set(
  table :: atom(),
  key :: term(),
  scale :: pos_integer(),
  count :: non_neg_integer()
) :: non_neg_integer()

Sets the counter for a given key, refreshing the window to now + scale.