{"id":13878007,"url":"https://github.com/WeTransfer/prorate","last_synced_at":"2025-07-16T14:30:37.218Z","repository":{"id":52932446,"uuid":"81929327","full_name":"WeTransfer/prorate","owner":"WeTransfer","description":"Redis-based rate limiter (with a leaky bucket implementation in Lua)","archived":false,"fork":false,"pushed_at":"2024-11-18T08:30:17.000Z","size":125,"stargazers_count":88,"open_issues_count":3,"forks_count":5,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-11-21T02:24:05.181Z","etag":null,"topics":["redis","throttling","wt-branch-protection-default-unsigned"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/WeTransfer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-14T09:37:30.000Z","updated_at":"2024-10-16T10:35:07.000Z","dependencies_parsed_at":"2024-09-10T19:34:38.148Z","dependency_job_id":"fbe199e9-2c5a-4853-bd40-a8000530709b","html_url":"https://github.com/WeTransfer/prorate","commit_stats":{"total_commits":87,"total_committers":14,"mean_commits":6.214285714285714,"dds":0.5977011494252873,"last_synced_commit":"d52ce972dbadb5d274328f61fb35604025225a14"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fprorate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fprorate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fprorate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeTransfer%2Fprorate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WeTransfer","download_url":"https://codeload.github.com/WeTransfer/prorate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226134226,"owners_count":17578778,"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":["redis","throttling","wt-branch-protection-default-unsigned"],"created_at":"2024-08-06T08:01:37.356Z","updated_at":"2024-11-24T06:31:43.230Z","avatar_url":"https://github.com/WeTransfer.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Prorate\n\nProvides a low-level time-based throttle. Is mainly meant for situations where\nusing something like Rack::Attack is not very useful since you need access to\nmore variables. Under the hood, this uses a Lua script that implements the\n[Leaky Bucket](https://en.wikipedia.org/wiki/Leaky_bucket) algorithm in a single\nthreaded and race condition safe way.\n\n[![Build Status](https://travis-ci.org/WeTransfer/prorate.svg?branch=master)](https://travis-ci.org/WeTransfer/prorate)\n[![Gem Version](https://badge.fury.io/rb/prorate.svg)](https://badge.fury.io/rb/prorate)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'prorate'\n```\n\nAnd then execute:\n\n```shell\nbundle install\n```\n\nOr install it yourself as:\n\n```shell\ngem install prorate\n```\n\n## Usage\n\nThe simplest mode of operation is throttling an endpoint, using the throttler\nbefore the action happens.\n\nWithin your Rails controller:\n\n```ruby\nt = Prorate::Throttle.new(\n    redis: Redis.new,\n    logger: Rails.logger,\n    name: \"throttle-login-email\",\n    limit: 20,\n    period: 5.seconds\n)\n# Add all the parameters that function as a discriminator.\nt \u003c\u003c request.ip \u003c\u003c params.require(:email)\n# ...and call the throttle! method\nt.throttle! # Will raise a Prorate::Throttled exception if the limit has been reached\n#\n# Your regular action happens after this point\n```\n\nTo capture that exception, in the controller\n\n```ruby\nrescue_from Prorate::Throttled do |e|\n  response.set_header('Retry-After', e.retry_in_seconds.to_s)\n  render nothing: true, status: 429\nend\n```\n\n### Throttling and checking status\n\nMore exquisite control can be achieved by combining throttling (see previous\nstep) and - in subsequent calls - checking the status of the throttle before\ninvoking the throttle. **When you call `throttle!`, you add tokens to the leaky bucket.**\n\nLet's say you have an endpoint that not only needs throttling, but you want to\nban [credential stuffers](https://en.wikipedia.org/wiki/Credential_stuffing)\noutright. This is a multi-step process:\n\n1. Respond with a 429 if the discriminators of the request would land in an\n  already blocking 'credential-stuffing'-throttle\n1. Run your regular throttling\n1. Perform your sign in action\n1. If the sign in was unsuccessful, add the discriminators to the\n  'credential-stuffing'-throttle\n\nIn your controller that would look like this:\n\n```ruby\nt = Prorate::Throttle.new(\n    redis: Redis.new,\n    logger: Rails.logger,\n    name: \"credential-stuffing\",\n    limit: 20,\n    period: 20.minutes\n)\n# Add all the parameters that function as a discriminator.\nt \u003c\u003c request.ip\n# And before anything else, check whether it is throttled\nif t.status.throttled?\n  response.set_header('Retry-After', t.status.remaining_throttle_seconds.to_s)\n  render(nothing: true, status: 429) and return\nend\n\n# run your regular throttles for the endpoint\nother_throttles.map(:throttle!)\n# Perform your sign in logic..\n\nuser = YourSignInLogic.valid?(\n  email: params[:email],\n  password: params[:password]\n)\n\n# Add the request to the credential stuffing throttle if we didn't succeed\nt.throttle! unless user\n\n# the rest of your action\n```\n\nTo capture that exception, in the controller\n\n```ruby\nrescue_from Prorate::Throttled do |e|\n  response.set_header('Retry-After', e.retry_in_seconds.to_s)\n  render nothing: true, status: 429\nend\n```\n\n## Using just the leaky bucket\n\nThere is also an object for using the heart of Prorate (the leaky bucket) without blocking or exceptions. This is useful\nif you want to implement a more generic rate limiting solution and customise it in a fancier way. The leaky bucket on\nit's own provides the following conveniences only:\n\n* Track the number of tokens added and the number of tokens that have leaked\n* Tracks whether a specific token fillup has overflown the bucket. This is only tracked momentarily if the bucket is limited\n\nLevel and leak rate are computed and provided as Floats instead of Integers (in the Throttle class).\nTo use it, employ the `LeakyBucket` object:\n\n```ruby\n# The leak_rate is in tokens per second\nleaky_bucket = Prorate::LeakyBucket.new(redis: Redis.new, redis_key_prefix: \"user123\", leak_rate: 0.8, bucket_capacity: 2)\nleaky_bucket.state.level #=\u003e will return 0.0\nleaky_bucket.state.full? #=\u003e will return \"false\"\nstate_after_add = leaky_bucket.fillup(2) #=\u003e returns a State object_\nstate_after_add.full? #=\u003e will return \"true\"\nstate_after_add.level #=\u003e will return 2.0\n```\n\n## Why Lua?\n\nProrate is implementing throttling using the \"Leaky Bucket\" algorithm and is extensively described [here](https://github.com/WeTransfer/prorate/blob/master/lib/prorate/throttle.rb). The implementation is using a Lua script, because is the only language available which runs _inside_ Redis. Thanks to the speed benefits of Lua the script runs fast enough to apply it on every throttle call.\n\nUsing a Lua script in Prorate helps us achieve the following guarantees:\n\n- **The script will run atomically.** The script is evaluated as a single Redis command. This ensures that the commands in the Lua script will never be interleaved with another client: they will always execute together.\n- **Any usages of time will use the Redis time.** Throttling requires a consistent and monotonic _time source_. The only monotonic and consistent time source which is usable in the context of Prorate, is the `TIME` result of Redis itself. We are throttling requests from different machines, which will invariably have clock drift between them. This way using the Redis server `TIME` helps achieve consistency.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/WeTransfer/prorate.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWeTransfer%2Fprorate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWeTransfer%2Fprorate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWeTransfer%2Fprorate/lists"}