https://github.com/exhammer/hammer-backend-redis

A Redis backend for for the Hammer rate-limiter
https://github.com/exhammer/hammer-backend-redis

elixir elixir-lang phoenix phoenix-framework rate-limiter rate-limiting redis

Last synced: 5 days ago
JSON representation

A Redis backend for for the Hammer rate-limiter

• Host: GitHub
• URL: https://github.com/exhammer/hammer-backend-redis
• Owner: ExHammer
• License: mit
• Created: 2017-06-20T20:22:51.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2024-12-30T06:34:21.000Z (25 days ago)
• Last Synced: 2025-01-11T21:06:09.133Z (12 days ago)
• Topics: elixir, elixir-lang, phoenix, phoenix-framework, rate-limiter, rate-limiting, redis
• Language: Elixir
• Homepage: https://hexdocs.pm/ExHammer/hammer-backend-redis
• Size: 157 KB
• Stars: 50
• Watchers: 4
• Forks: 30
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.md
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
# Hammer.Redis

[![Build Status](https://github.com/ExHammer/hammer-backend-redis/actions/workflows/ci.yml/badge.svg)](https://github.com/ExHammer/hammer-backend-redis/actions/workflows/ci.yml)

[![Hex.pm](https://img.shields.io/hexpm/v/hammer_backend_redis.svg)](https://hex.pm/packages/hammer_backend_redis)

[![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/hammer_backend_redis)

[![Total Download](https://img.shields.io/hexpm/dt/hammer_backend_redis.svg)](https://hex.pm/packages/hammer_backend_redis)

[![License](https://img.shields.io/hexpm/l/hammer_backend_redis.svg)](https://github.com/ExHammer/hammer-backend-redis/blob/master/LICENSE.md)

A Redis backend for the [Hammer](https://github.com/ExHammer/hammer) rate-limiter.

This backend is a thin [Redix](https://hex.pm/packages/redix) wrapper. A single connection is used per rate-limiter. It should be enough for most use-cases since packets for rate limiting requests are short (i.e. no head of line blocking) and Redis is OK with [pipelining](https://redis.io/learn/operate/redis-at-scale/talking-to-redis/client-performance-improvements#pipelining) (i.e. we don't block awaiting replies). Consider benchmarking before introducing more connections since TCP performance might be unintuitive. For possible pooling approaches, see Redix docs on [pooling](https://hexdocs.pm/redix/real-world-usage.html#name-based-pool) and also [PartitionSupervisor.](https://hexdocs.pm/elixir/1.17.3/PartitionSupervisor.html) Do not use poolboy or db_connection-like pools since they practically disable pipelining which leads to worse connection utilisation and worse performance.

The algorithm we are using is the first method described (called "bucketing") in [Rate Limiting with Redis](https://youtu.be/CRGPbCbRTHA?t=753).

In other sources it's sometimes called a "fixed window counter".

**TODO:** document ttl issues if servers are misconfigured

## Installation

Hammer-backend-redis

is [available in Hex](https://hex.pm/packages/hammer_backend_redis), the package

can be installed by adding `hammer_backend_redis` to your list of dependencies in `mix.exs`:

```elixir

def deps do

  [

    {:hammer_backend_redis, "~> 7.0"}

  ]

end

```

## Usage

Define the rate limiter:

```elixir

defmodule MyApp.RateLimit do

  use Hammer, backend: Hammer.Redis

end

```

And add it to your app's supervision tree:

```elixir

children = [

  {MyApp.RateLimit, url: "redis://localhost:6379"}

]

```

And that's it, calls to `MyApp.RateLimit.hit/3` and so on will use Redis to store

the rate-limit counters. See the [documentation](https://hexdocs.pm/hammer_backend_redis/Hammer.Redis.html) for more details.

## Run tests locally

You need a running Redis instance. One can be started locally using `docker compose up -d redis`.

See the [compose.yml](./compose.yml) for more details.

## Getting Help

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