HammerBackendEredisCluster

A clustered-Redis backend for the Hammer rate-limiter (Hammer v7+), built on eredis_cluster.

Keys embed a {hash tag} so every window of a key maps to the same cluster slot — the reason to pick this over the single-node official hammer-backend-redis.

Installation

Add hammer_backend_eredis_cluster to your list of dependencies in mix.exs:

def deps do
  [
    {:hammer_backend_eredis_cluster, "~> 2.0"},
    {:hammer, "~> 7.0"}
  ]
end

2.0.0 is also mirrored in the loopsocial org repo (hexpm:loopsocial), where it was first published while public package ownership was being restored — consumers pinned there can stay or drop the organization: option at their leisure.

Using Hammer 6? Stay on {:hammer_backend_eredis_cluster, "~> 1.0"} — 2.0 is the Hammer 7 port and drops the v6 Hammer.Backend behaviour (see the CHANGELOG).

Usage

Define a rate limiter and start it (typically under your supervision tree):

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

# The cluster connection is managed elsewhere
# (e.g. `config :eredis_cluster, init_nodes: [...]`):
MyApp.RateLimit.start_link([])

# Or let the limiter establish the connection:
MyApp.RateLimit.start_link(
  servers: [{"127.0.0.1", 7001}, {"127.0.0.1", 7002}],
  options: [username: "myuser", password: "mypassword"]
)

# Allow 10 requests per minute:
case MyApp.RateLimit.hit("user_123", :timer.minutes(1), 10) do
  {:allow, _count} -> :ok
  {:deny, retry_ms} -> {:error, {:rate_limited, retry_ms}}
end

use Hammer, backend: Hammer.EredisCluster accepts :cluster (eredis_cluster name, default :eredis_cluster_default), :prefix (Redis key prefix, default: the module name) and :algorithm (only :fix_window). See the Hammer.EredisCluster module docs.

Documentation

On hexdocs: https://hexdocs.pm/hammer_backend_eredis_cluster/

Run tests locally

Tests need a real Redis cluster. Either docker-compose up -d (see docker-compose.yml) and run tests with REDIS_CLUSTER_NODES=redis-master-1:6379,redis-master-2:6379,redis-master-3:6379, or start three local cluster-mode nodes on ports 7001-7003 (the default REDIS_CLUSTER_NODES):

for p in 7001 7002 7003; do
  redis-server --port $p --cluster-enabled yes --cluster-config-file /tmp/rc/node-$p.conf \
    --dir /tmp/rc --daemonize yes --save "" --appendonly no
done
redis-cli --cluster create 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003 \
  --cluster-replicas 0 --cluster-yes
mix test

Getting Help

If you're having trouble, open an issue on this repo.