{"id":17241186,"url":"https://github.com/recruitee/plug_limit","last_synced_at":"2025-04-14T03:14:33.761Z","repository":{"id":42433096,"uuid":"490279744","full_name":"Recruitee/plug_limit","owner":"Recruitee","description":"Rate limiting Plug module based on Redis Lua scripting.","archived":false,"fork":false,"pushed_at":"2023-01-04T15:07:53.000Z","size":83,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-14T03:13:46.576Z","etag":null,"topics":["elixir","phoenix","phoenix-framework","plug","rate-limiter","rate-limiting"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Recruitee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-09T12:46:46.000Z","updated_at":"2024-05-09T17:56:43.000Z","dependencies_parsed_at":"2023-02-02T16:47:18.262Z","dependency_job_id":null,"html_url":"https://github.com/Recruitee/plug_limit","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recruitee%2Fplug_limit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recruitee%2Fplug_limit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recruitee%2Fplug_limit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recruitee%2Fplug_limit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Recruitee","download_url":"https://codeload.github.com/Recruitee/plug_limit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813803,"owners_count":21165634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","phoenix","phoenix-framework","plug","rate-limiter","rate-limiting"],"created_at":"2024-10-15T06:08:00.902Z","updated_at":"2025-04-14T03:14:33.741Z","avatar_url":"https://github.com/Recruitee.png","language":"Elixir","readme":"# PlugLimit\n\n[![Hex Version](https://img.shields.io/hexpm/v/plug_limit)](https://hex.pm/packages/plug_limit)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen)](https://hexdocs.pm/plug_limit)\n[![CI](https://github.com/Recruitee/plug_limit/workflows/CI/badge.svg)](https://github.com/Recruitee/plug_limit/actions/workflows/ci.yml)\n\nRate limiting Plug module based on Redis Lua scripting.\n\n## Summary\nPlugLimit is using Redis Lua scripting to provide rate-limiting functionality for web applications\nbased on a Plug library. PlugLimit has a modular architecture: users can use their own Redis Lua\nscripts implementing custom rate limiting algorithms.\n\nSalient Redis Lua scripting feature is a race conditions resiliency which makes this library\na recommended solution for distributed systems (e.g.: Phoenix servers behind round robin load balancer).\n\nPlugLimit provides two built-in rate limiters: `PlugLimit.FixedWindow` and `PlugLimit.TokenBucket`.\n\n## Installation\nAdd `PlugLimit` library to your application dependencies:\n```elixir\ndef deps do\n  [\n    {:plug_limit, \"~\u003e 0.1.0\"}\n  ]\nend\n```\n\n## Usage\nPlugLimit is Redis client agnostic. In a first step you must define Elixir function executing Redis\ncommands, depending on Redis client of your choice:\n```elixir\n# config/config.exs\nconfig :plug_limit,\n  enabled?: true,\n  cmd: {MyApp.Redis, :command, []}\n```\n\n`MyApp.Redis.command/2` function must accept Redis command as a first argument and static MFA tuple\n`arg` as a second.\nIn most cases `:cmd` function will be a `Redix.command/3` or `:eredis.q/2,3` wrapper.\nExample naive [Redix](https://hex.pm/packages/redix) driver wrapper:\n```elixir\n#lib/my_app/redis.ex\ndef command(command, opts \\\\ [timeout: 500]) do\n  {:ok, pid} = Redix.start_link()\n  Redix.command(pid, command, opts)\n  :ok = Redix.stop(pid)\nend\n```\n\nPlugLimit is tested with both [Redix](https://hex.pm/packages/redix) and\n[eredis](https://hex.pm/packages/eredis) Redis clients.\n\nPhoenix Framework endpoint can be protected with fixed window rate-limiter by placing a\n`PlugLimit.FixedWindow` plug call in the request processing pipeline:\n```elixir\n#lib/my_app_web/router.ex\npipeline :high_cost_pipeline do\n  plug(PlugLimit.FixedWindow,\n    limit: 10,\n    ttl: 60,\n    key: {MyApp.RateLimiter, :user_key, [:high_cost_pipeline]}\n  )\n  # remaining pipeline plugs...\nend\n```\n\nRate limits for `:high_cost_pipeline` pipeline will be evaluated with Redis Lua script fixed window\nalgorithm. Client identified with `:key` will be allowed to issue 10 requests in 60 seconds time\nwindow.\n\nMFA tuple defined with `:key` option specifies user function which should provide Redis key\nused to uniquely identify given rate-limiter bucket. Redis rate-limiter key name should be derived\nfrom `Plug.Conn.t()` connection struct parameters.\nExample function to create Redis key name for rate-limiter throttling requests for a given user\nidentified by a connection assigned `:user_id`:\n```elixir\n#lib/my_app/rate_limiter.ex\ndef user_key(%Plug.Conn{assigns: %{user_id: user_id}}, prefix),\n   do: {:ok, [\"#{prefix}:#{user_id}\"]}\n```\n\nPlease refer to `PlugLimit` module documentation for detailed library configuration description and\n\"Redis Lua script rate limiters\" in LIMITERS.md file for Redis Lua scripts implementation\nguidelines.\n\n## TODO\n- [ ] Add leaky bucket rate limiting algorithm implementation.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecruitee%2Fplug_limit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecruitee%2Fplug_limit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecruitee%2Fplug_limit/lists"}