hammer

# Hammer

[![Build Status](https://github.com/ExHammer/hammer/actions/workflows/ci.yml/badge.svg)](https://github.com/ExHammer/hammer/actions/workflows/ci.yml)
[![Hex.pm](https://img.shields.io/hexpm/v/hammer.svg)](https://hex.pm/packages/hammer)
[![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/hammer)
[![Total Download](https://img.shields.io/hexpm/dt/hammer.svg)](https://hex.pm/packages/hammer)
[![License](https://img.shields.io/hexpm/l/hammer.svg)](https://github.com/ExHammer/hammer/blob/master/LICENSE.md)

**Hammer** is a rate-limiter for Elixir with pluggable storage backends. Hammer enables users to set limits on actions performed within specified time intervals, applying per-user or global limits on API requests, file uploads, and more.

## Installation

Hammer is [available in Hex](https://hex.pm/packages/hammer). Install by adding `:hammer` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:hammer, "~> 7.0"}
  ]
end
```

### Installing with Igniter

If you use [Igniter](https://hexdocs.pm/igniter), a single command adds the dependency, generates a
`MyApp.RateLimit` module and adds it to your application's supervision tree:

```sh
mix igniter.install hammer
```

Pass `--backend atomic` or `--backend redis` to pick a backend other than the default `:ets`.
The `redis` option also adds the [`hammer_backend_redis`](https://hex.pm/packages/hammer_backend_redis)
dependency. If Hammer is already in your project, run `mix hammer.install` directly.

Hammer has no global configuration: each limit is defined where it is checked, with
`MyApp.RateLimit.hit(key, scale, limit)`. See the [Tutorial](https://hexdocs.pm/hammer/tutorial.html)
for how to compose keys and use the limiter as a plug.

## Available Backends

Atomic backends are single-node rate limiting but will be the fastest option.

- [Hammer.ETS](https://hexdocs.pm/hammer/Hammer.ETS.html) (default, can be [distributed](./guides/distributed-ets.md))
- [Hammer.Atomic](https://hexdocs.pm/hammer/Hammer.Atomic.html)
- [Hammer.Redis](https://github.com/ExHammer/hammer-backend-redis)
- [Hammer.Mnesia](https://github.com/ExHammer/hammer-backend-mnesia)

## Available Algorithms:

Each backend supports multiple algorithms. Not all of them are available for all backends. The following table shows which algorithms are available for which backends.

| Algorithm | Backend |
| --------- | ------- |
| [Hammer.Atomic.FixWindow](https://hexdocs.pm/hammer/Hammer.Atomic.FixWindow.html) | [Hammer.Atomic](https://hexdocs.pm/hammer/Hammer.Atomic.html) |
| [Hammer.Atomic.FixWindowPerKey](https://hexdocs.pm/hammer/Hammer.Atomic.FixWindowPerKey.html) | [Hammer.Atomic](https://hexdocs.pm/hammer/Hammer.Atomic.html) |
| [Hammer.Atomic.LeakyBucket](https://hexdocs.pm/hammer/Hammer.Atomic.LeakyBucket.html) | [Hammer.Atomic](https://hexdocs.pm/hammer/Hammer.Atomic.html) |
| [Hammer.Atomic.TokenBucket](https://hexdocs.pm/hammer/Hammer.Atomic.TokenBucket.html) | [