# `ExternalService.RateLimiter.Hammer`
[🔗](https://github.com/jvoegele/external_service/blob/main/lib/external_service/rate_limiter/hammer.ex#L1)

Rate limiter backend backed by a [Hammer](https://hexdocs.pm/hammer) rate
limiter module.

This is the supported route to **cluster-wide rate limiting**: point it at a
Hammer module using a shared backend (such as
[`hammer_backend_redis`](https://hexdocs.pm/hammer_backend_redis)) and every
node in the cluster meters against the same counters, so the external service
sees the limit you configured rather than that limit multiplied by your node
count.

Define and supervise a Hammer module as Hammer documents:

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

    children = [{MyApp.RateLimit, url: "redis://localhost:6379"}]

Then point a service at it:

    use ExternalService,
      rate_limit: [
        limit: 100,
        per: :timer.seconds(1),
        backend: {ExternalService.RateLimiter.Hammer, module: MyApp.RateLimit}
      ]

## Options

  * `:module` (required) - the Hammer rate limiter module to meter against.
  * `:key` - the Hammer key to meter under. Defaults to a key derived from the
    service name. Set this explicitly when several services (or several
    applications) should share one budget.

`:hammer` is **not** a dependency of this library. The backend calls `hit/3` on
the module you supply, which is Hammer's own API, so nothing needs to be added
to your dependencies beyond Hammer itself.

# `default_key`

```elixir
@spec default_key(ExternalService.service()) :: String.t()
```

The Hammer key used for a service when no `:key` option is given.

---

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