{"id":25841255,"url":"https://github.com/nigelsmith/odo","last_synced_at":"2025-10-30T12:36:04.994Z","repository":{"id":62430140,"uuid":"90319530","full_name":"nigelsmith/odo","owner":"nigelsmith","description":"A simple GenServer based token bucket rate limiter written in Elixir","archived":false,"fork":false,"pushed_at":"2017-08-25T10:05:45.000Z","size":15,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-27T22:49:07.311Z","etag":null,"topics":["elixir","rate-limiting","token-bucket"],"latest_commit_sha":null,"homepage":null,"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/nigelsmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-04T23:51:50.000Z","updated_at":"2022-02-17T21:13:45.000Z","dependencies_parsed_at":"2022-11-01T20:07:48.284Z","dependency_job_id":null,"html_url":"https://github.com/nigelsmith/odo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelsmith%2Fodo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelsmith%2Fodo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelsmith%2Fodo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelsmith%2Fodo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nigelsmith","download_url":"https://codeload.github.com/nigelsmith/odo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241099763,"owners_count":19909601,"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-limiting","token-bucket"],"created_at":"2025-03-01T05:22:15.010Z","updated_at":"2025-10-30T12:36:04.860Z","avatar_url":"https://github.com/nigelsmith.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Odo\n\n## Description\n\nOdo is a simple, GenServer based, token bucket rate limiter for communicating with rate limtied APIs.  Full documentation \ncan be found at [https://hexdocs.pm/odo](https://hexdocs.pm/odo).\n\n## Installation\n\nThe package can be installed by adding `odo` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [{:odo, \"~\u003e 0.1.0\"}]\nend\n```\n\nyou will also need to list it in your applications unless using Elixir ~\u003e 1.4 which infers applications from\nyour dependency list.\n\n## Usage\n\nYou can create a new bucket like so:\n\n```elixir\nOdo.Bucket.new_bucket(\"my bucket\")\n```\n\nand to obtain a token:\n\n```elixir\nstatus = Odo.Bucket.get_token(\"my bucket\")\n```\n\nThe status return value will be one of the following forms.  When it's ok to proceed with your request you will receive\n`{:go, tokens_remaining, until}` with `until` being the time in milliseconds until he next tick or refill occurs.\n\nWhen the bucket is full the reply will be `{:stop, until}`, again with `until` measured in milliseconds letting you know\nwhen the next window of opportunity to make a request will open up.\n\n#### Configuration\n\nYou may also configure the bucket with the following options:\n\n```elixir\nOdo.Bucket.new_bucket(\"my bucket\", tokens: 20, tick_duration: 10_000, tick_refill_amount: 20, buffer: 200)\n```\n\n`tick_duration: value` specifies the intervals at which the bucket is refilled in milliseconds whilst `tick_refill_amount`\nprovides for the amount to add in each tick.  The `buffer: value` lets you provide a buffer to add to the tick duration.\nYou may want to do that in order to account for latency or other delays between the time you secure a token from the bucket\nand the time that the request to the remote API actually arrives.\n\nFor example, if you dispatch 10 requests within a 10 second window you can be sure that you do not exceed that amount,\nbut you do not have a guarantee about when those requests are actually delivered to the remote service.  If the latency\nbetween your client and the remote API varies, it is possible for a later request to arrive out of order and so fit\nwithin the earlier timing window of the remote service.  This won't usually matter unless you're pushing close to the\nrate limit of the remote API.\n\nIn any event, matching the characteristics and quirks of the remote service will still mean having to guard against\nrate limiting restrictions in your own code.\n \n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelsmith%2Fodo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnigelsmith%2Fodo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelsmith%2Fodo/lists"}