# `Hammer.Atomic.FixWindowPerKey`
[🔗](https://github.com/ExHammer/hammer/blob/v7.4.0/lib/hammer/atomic/fix_window_per_key.ex#L1)

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)

# `expires_at`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*