{"id":18151431,"url":"https://github.com/jur0/limiter","last_synced_at":"2025-04-28T18:24:09.349Z","repository":{"id":57516832,"uuid":"74277165","full_name":"jur0/limiter","owner":"jur0","description":"Elixir GCRA rate limiter","archived":false,"fork":false,"pushed_at":"2017-03-08T17:34:12.000Z","size":16,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T07:54:49.019Z","etag":null,"topics":["elixir","rate-limiter","throttling"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jur0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-20T13:50:42.000Z","updated_at":"2024-02-14T08:41:38.000Z","dependencies_parsed_at":"2022-09-26T18:01:27.623Z","dependency_job_id":null,"html_url":"https://github.com/jur0/limiter","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jur0%2Flimiter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jur0%2Flimiter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jur0%2Flimiter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jur0%2Flimiter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jur0","download_url":"https://codeload.github.com/jur0/limiter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251363164,"owners_count":21577592,"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","rate-limiter","throttling"],"created_at":"2024-11-02T01:07:38.672Z","updated_at":"2025-04-28T18:24:09.334Z","avatar_url":"https://github.com/jur0.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Limiter\n\n[![Build Status](https://travis-ci.org/jur0/limiter.svg?branch=master)](https://travis-ci.org/jur0/limiter)\n[![Hex.pm](https://img.shields.io/hexpm/v/limiter.svg)](https://hex.pm/packages/limiter)\n\nRate limiter implementation of Generic Cell Rate Algorithm (GCRA).\n\nFor detailed information on how the algorithm works, please check the following\nlinks:\n\n  * [Rate limiting, Cells and GCRA](https://brandur.org/rate-limiting)\n  * [GCRA algorithm](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm)\n\nThe implementation is similar to Go `throttled` library:\n\n  * [Go throttled library](https://github.com/throttled/throttled)\n\n## Installation\n\nIf [available in Hex](https://hex.pm/docs/publish), the package can be installed as:\n\n  1. Add `limiter` to your list of dependencies in `mix.exs`:\n\n    ```elixir\n    def deps do\n      [{:limiter, \"~\u003e 0.1.2\"}]\n    end\n    ```\n\n  2. Ensure `limiter` is started before your application:\n\n    ```elixir\n    def application do\n      [applications: [:limiter]]\n    end\n    ```\n\n## Usage\n\nFirst off, a storage must be configured and started. Currently, the rate\nlimiter supports one implementation of the storage, which is\n`Limiter.Storage.ConCache`. Each implementation of the storage can have\ndifferent options.\n\nThe storage can be started in two ways:\n\n  * as a part of the `limiter`'s supervision tree - the config of the\n  `limiter`'s storage is in the config file. For example:\n\n    ```elixir\n    config :limiter,\n      storage: [{Limiter.Storage.ConCache, :limiter_con_cache}]\n\n    config :limiter, :limiter_con_cache,\n      ttl_check: 1_000\n    ```\n\n  * as a part of the supervision tree of the application which is using the\n  `limiter` (so the storage can be restarted with that application) -\n  `Limiter.Storage.ConCache` exports `start_link/1` function, so it can be\n  added to the supervision tree, for example:\n\n    ```elixir\n    children = [\n      ...\n      worker(Limiter.Storage.ConCache, [\n        [name: :limiter_con_cache, ttl_check: 1_000]\n      ])\n    ]\n    ...\n    Supervisor.start_link(children, ...)\n    ```\n\nThe `Limiter` module exports `checkout/5` with the following arguments:\n\n  * `storage` - tuple that contains the module used for storage\n  (`Limiter.Storage.ConCache`) and options for the given storage.\n  * `key` - the key associated with an action which is rate limited.\n  * `quantity` - the weight of an action. Typically it's set to `1`. The more\n  expensive actions may use greater value.\n  * `period` -  the period of time that along with `limit` defines the rate\n  limit.\n  * `limit` - the number of actions (in case the `quantity` is `1`) that\n  along with the `period` defines the rate limit.\n\nExample:\n\n```elixir\nLimiter.checkout({Limiter.Storage.ConCache, :limiter_con_cache}, \"key\", 1, 10_000, 5)\n```\n\nThe `Limiter.checkout/5` functions returns a struct (`Limiter.Result`) with the\nfollowing information:\n\n  * `allowed` - indicates if an action is allowed or rate limited.\n  * `remaining` - the number of actions that is allowed before reaching the rate\n  limit.\n  * `reset_after` - how long (in milliseconds) it will take for the given key\n  to get to the initial state.\n  * `retry_after` -  how long (in milliseconds) it will take for the next\n  action (associated with the given key) to be allowed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjur0%2Flimiter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjur0%2Flimiter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjur0%2Flimiter/lists"}