{"id":13994926,"url":"https://github.com/dryruby/rack-throttle","last_synced_at":"2025-05-16T14:03:24.630Z","repository":{"id":845695,"uuid":"571839","full_name":"dryruby/rack-throttle","owner":"dryruby","description":"Rack middleware for rate-limiting incoming HTTP requests.","archived":false,"fork":false,"pushed_at":"2023-03-01T13:13:11.000Z","size":148,"stargazers_count":945,"open_issues_count":7,"forks_count":116,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-13T09:09:01.704Z","etag":null,"topics":["rack","ruby","rubygems"],"latest_commit_sha":null,"homepage":"http://rubygems.org/gems/rack-throttle","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"goncalossilva/acts_as_paranoid","license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dryruby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2010-03-20T21:32:49.000Z","updated_at":"2025-04-23T13:14:38.000Z","dependencies_parsed_at":"2023-07-06T13:16:12.200Z","dependency_job_id":null,"html_url":"https://github.com/dryruby/rack-throttle","commit_stats":{"total_commits":118,"total_committers":23,"mean_commits":5.130434782608695,"dds":0.576271186440678,"last_synced_commit":"f70857d91c985be79026e88d53c8c4db69a94d0b"},"previous_names":["bendiken/rack-throttle"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryruby%2Frack-throttle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryruby%2Frack-throttle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryruby%2Frack-throttle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dryruby%2Frack-throttle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dryruby","download_url":"https://codeload.github.com/dryruby/rack-throttle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544142,"owners_count":22088807,"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":["rack","ruby","rubygems"],"created_at":"2024-08-09T14:03:10.855Z","updated_at":"2025-05-16T14:03:24.585Z","avatar_url":"https://github.com/dryruby.png","language":"Ruby","readme":"DEPRECATED We suggest using rack-attack instead\n===============================================\n\n\u003chttps://github.com/rack/rack-attack\u003e Accomplishes the same goal as rack-throttle,\nbut has more active maintenance, usage, and maturity. Please think about using rack-attack\nover rack-throttle.\n\nrack-throttle will still continue to exist to support legacy ruby applications (\u003c2.3), but\nwill not be getting new features added as it exists strictly to support existing apps.\n\nHTTP Request Rate Limiter for Rack Applications\n===============================================\n\nThis is [Rack][] middleware that provides logic for rate-limiting incoming\nHTTP requests to Rack applications. You can use `Rack::Throttle` with any\nRuby web framework based on Rack, including with Ruby on Rails and with\nSinatra.\n\n* \u003chttps://github.com/dryruby/rack-throttle\u003e\n\nFeatures\n--------\n\n* Throttles a Rack application by enforcing a minimum time interval between\n  subsequent HTTP requests from a particular client, as well as by defining\n  a maximum number of allowed HTTP requests per a given time period (per minute,\n  hourly, or daily).\n* Compatible with any Rack application and any Rack-based framework.\n* Stores rate-limiting counters in any key/value store implementation that\n  responds to `#[]`/`#[]=` (like Ruby's hashes) or to `#get`/`#set` (like\n  memcached or Redis).\n* Compatible with the [gdbm][] binding included in Ruby's standard library.\n* Compatible with the [memcached][], [memcache-client][], [memcache][] and\n  [redis][] gems.\n* Compatible with [Heroku][]'s [memcached add-on][Heroku memcache]\n  (currently available as a free beta service).\n\nExamples\n--------\n\n### Adding throttling to a Rails application\n\n```ruby\n# config/application.rb\nrequire 'rack/throttle'\n\nclass Application \u003c Rails::Application\n  config.middleware.use Rack::Throttle::Interval\nend\n```\n\n### Adding throttling to a Sinatra application\n\n```ruby\n#!/usr/bin/env ruby -rubygems\nrequire 'sinatra'\nrequire 'rack/throttle'\n\nuse Rack::Throttle::Interval\n\nget('/hello') { \"Hello, world!\\n\" }\n```\n\n### Adding throttling to a Rackup application\n\n```ruby\n#!/usr/bin/env rackup\nrequire 'rack/throttle'\n\nuse Rack::Throttle::Interval\n\nrun lambda { |env| [200, {'Content-Type' =\u003e 'text/plain'}, \"Hello, world!\\n\"] }\n```\n\n### Enforcing a minimum 3-second interval between requests\n\n```ruby\nuse Rack::Throttle::Interval, :min =\u003e 3.0\n```\n\n### Allowing a maximum of 1 request per second\n\n```ruby\nuse Rack::Throttle::Second,   :max =\u003e 1\n```\n\n### Allowing a maximum of 60 requests per minute\n\n```ruby\nuse Rack::Throttle::Minute,   :max =\u003e 60\n```\n\n### Allowing a maximum of 100 requests per hour\n\n```ruby\nuse Rack::Throttle::Hourly,   :max =\u003e 100\n```\n\n### Allowing a maximum of 1,000 requests per day\n\n```ruby\nuse Rack::Throttle::Daily,    :max =\u003e 1000\n```\n\n### Combining various throttling constraints into one overall policy\n\n```ruby\nuse Rack::Throttle::Daily,    :max =\u003e 1000  # requests\nuse Rack::Throttle::Hourly,   :max =\u003e 100   # requests\nuse Rack::Throttle::Minute,   :max =\u003e 60    # requests\nuse Rack::Throttle::Second,   :max =\u003e 1     # requests\nuse Rack::Throttle::Interval, :min =\u003e 3.0   # seconds\n```\n\n### Storing the rate-limiting counters in a GDBM database\n\n```ruby\nrequire 'gdbm'\n\nuse Rack::Throttle::Interval, :cache =\u003e GDBM.new('tmp/throttle.db')\n```\n\n### Storing the rate-limiting counters on a Memcached server\n\n```ruby\nrequire 'memcached'\n\nuse Rack::Throttle::Interval, :cache =\u003e Memcached.new, :key_prefix =\u003e :throttle\n```\n\n### Storing the rate-limiting counters on a Redis server\n\n```ruby\nrequire 'redis'\n\nuse Rack::Throttle::Interval, :cache =\u003e Redis.new, :key_prefix =\u003e :throttle\n```\n\nThrottling Strategies\n---------------------\n\n`Rack::Throttle` supports four built-in throttling strategies:\n\n* `Rack::Throttle::Interval`: Throttles the application by enforcing a\n  minimum interval (by default, 1 second) between subsequent HTTP requests.\n* `Rack::Throttle::Hourly`: Throttles the application by defining a\n  maximum number of allowed HTTP requests per hour (by default, 3,600\n  requests per 60 minutes, which works out to an average of 1 request per\n  second).\n* `Rack::Throttle::Daily`: Throttles the application by defining a\n  maximum number of allowed HTTP requests per day (by default, 86,400\n  requests per 24 hours, which works out to an average of 1 request per\n  second).\n* `Rack::Throttle::Minute`: Throttles the application by defining a\n  maximum number of allowed HTTP requests per minute (by default, 60\n  requests per 1 minute, which works out to an average of 1 request per\n  second).\n* `Rack::Throttle::Second`: Throttles the application by defining a\n  maximum number of allowed HTTP requests per second (by default, 1\n  request per second).\n* `Rack::Throttle::Rules`: Throttles the application by defining\n  different rules of allowed HTTP request per time_window based on the\n  request method and the request paths, or use a default.\n\nYou can fully customize the implementation details of any of these strategies\nby simply subclassing one of the aforementioned default implementations.\nAnd, of course, should your application-specific requirements be\nsignificantly more complex than what we've provided for, you can also define\nentirely new kinds of throttling strategies by subclassing the\n`Rack::Throttle::Limiter` base class directly.\n\n### Example\n\nCustomize the `max_per_second` to be different depending on the request's method.\n\n```ruby\nclass Rack::Throttle::RequestMethod \u003c Rack::Throttle::Second\n\n  def max_per_second(request = nil)\n    return (options[:max_per_second] || options[:max] || 1) unless request\n    if request.request_method == \"POST\"\n      4\n    else\n      10\n    end\n  end\n  alias_method :max_per_window, :max_per_second\n\nend\n```\n\nPassing the correct options for `Rules` strategy.\n\n```ruby\nrules = [\n  { method: \"POST\", limit: 5 },\n  { method: \"GET\", limit: 10 },\n  { method: \"GET\", path: \"/users/.*/profile\", limit: 3 },\n  { method: \"GET\", path: \"/users/.*/reset_password\", limit: 1 },\n  { method: \"GET\", path: \"/external/callback\", whitelisted: true }\n]\nip_whitelist = [\n  \"1.2.3.4\",\n  \"5.6.7.8\"\n]\ndefault = 10\n\n\nuse Rack::Throttle::Rules, rules: rules, ip_whitelist: ip_whitelist, default: default\n```\n\nThis configuration would allow a maximum of 3 profile requests per second (default), i\n1 reset password requests per second, 5 POST and 10 GET requests per second\n(always also based on the IPaddress). Additionally it would whitelist the external callback\nand add a ip-whitelisting for the given ips.\n\nRules are checked in this order:\n* ip whitelist\n* rules with `paths`,\n* rules with `methods` only,\n* `default`.\n\nIt is possible to set the time window for this strategy to: `:second` (default), `:minute`, `:hour` or `:day`, to change the check interval to these windows.\n\n```ruby\nuse Rack::Throttle::Rules, rules: rules, time_window: :minute\n```\n\n\nHTTP Client Identification\n--------------------------\n\nThe rate-limiting counters stored and maintained by `Rack::Throttle` are\nkeyed to unique HTTP clients.\n\nBy default, HTTP clients are uniquely identified by their IP address as\nreturned by `Rack::Request#ip`. If you wish to instead use a more granular,\napplication-specific identifier such as a session key or a user account\nname, you need only subclass a throttling strategy implementation and\noverride the `#client_identifier` method.\n\nHTTP Response Codes and Headers\n-------------------------------\n\n### 403 Forbidden (Rate Limit Exceeded)\n\nWhen a client exceeds their rate limit, `Rack::Throttle` by default returns\na \"403 Forbidden\" response with an associated \"Rate Limit Exceeded\" message\nin the response body.\n\nAn HTTP 403 response means that the server understood the request, but is\nrefusing to respond to it and an accompanying message will explain why.\nThis indicates an error on the client's part in exceeding the rate limits\noutlined in the acceptable use policy for the site, service, or API.\n\n### 503 Service Unavailable (Rate Limit Exceeded)\n\nHowever, there exists a widespread practice of instead returning a \"503\nService Unavailable\" response when a client exceeds the set rate limits.\nThis is technically dubious because it indicates an error on the server's\npart, which is certainly not the case with rate limiting - it was the client\nthat committed the oops, not the server.\n\nAn HTTP 503 response would be correct in situations where the server was\ngenuinely overloaded and couldn't handle more requests, but for rate\nlimiting an HTTP 403 response is more appropriate. Nonetheless, if you think\notherwise, `Rack::Throttle` does allow you to override the returned HTTP\nstatus code by passing in a `:code =\u003e 503` option when constructing a\n`Rack::Throttle::Limiter` instance.\n\nDependencies\n------------\n\n* [Rack](http://rubygems.org/gems/rack) (\u003e= 1.0.0)\n\nInstallation\n------------\n\nThe recommended installation method is via [RubyGems](http://rubygems.org/).\nTo install the latest official release of the gem, do:\n\n    % [sudo] gem install rack-throttle\n\nAuthors\n-------\n\n* [Arto Bendiken](https://gratipay.com/bendiken) - \u003chttp://ar.to/\u003e\n\nContributors\n------------\n\n* [Brendon Murphy](https://github.com/bemurphy)\n* [Hendrik Kleinwaechter](https://github.com/hendricius)\n* [Karel Minarik](https://github.com/karmi)\n* [Keita Urashima](https://github.com/ursm)\n* [Leonid Beder](https://github.com/lbeder)\n* [TJ Singleton](https://github.com/tjsingleton)\n* [Winfield Peterson](https://github.com/wpeterson)\n* [Dean Galvin](https://github.com/freekingdean)\n\nContributing\n------------\n\n* Do your best to adhere to the existing coding conventions and idioms.\n* Don't use hard tabs, and don't leave trailing whitespace on any line.\n  Before committing, run `git diff --check` to make sure of this.\n* Do document every method you add using [YARD][] annotations. Read the\n  [tutorial][YARD-GS] or just look at the existing code for examples.\n* Don't touch the gemspec or `VERSION` files. If you need to change them,\n  do so on your private branch only.\n* Do feel free to add yourself to the `CREDITS` file and the\n  corresponding list in the the `README`. Alphabetical order applies.\n* Don't touch the `AUTHORS` file. If your contributions are significant\n  enough, be assured we will eventually add you in there.\n\nLicense\n-------\n\nThis is free and unencumbered public domain software. For more information,\nsee \u003chttp://unlicense.org/\u003e or the accompanying `UNLICENSE` file.\n\n[Rack]:            http://rack.rubyforge.org/\n[gdbm]:            http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html\n[memcached]:       http://rubygems.org/gems/memcached\n[memcache-client]: http://rubygems.org/gems/memcache-client\n[memcache]:        http://rubygems.org/gems/memcache\n[redis]:           http://rubygems.org/gems/redis\n[Heroku]:          http://heroku.com/\n[Heroku memcache]: http://docs.heroku.com/memcache\n[YARD]:            http://yardoc.org/\n[YARD-GS]:         http://rubydoc.info/docs/yard/file/docs/GettingStarted.md\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdryruby%2Frack-throttle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdryruby%2Frack-throttle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdryruby%2Frack-throttle/lists"}