pecorino 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a78723f311ad1a8b214716714e1b0ba5cf51e5860811612eaa931430cd7008ba
+  data.tar.gz: 89489e7423c8196e5644ee6166b4cd7520c54ed1bfefa627937c4c26f8b934fe
+SHA512:
+  metadata.gz: 36f3d6f7dfe4dc9ed21ba46fc2f79f2899cc38538c9220aacc9c6a9ca35d1f83de4d46f957ce1df782cc6bc19f5d531ca193398d6b8e2fe9bad3548dc43d88a9
+  data.tar.gz: 49f2acdb92bd5077a59eb47dafd335ec11ffb7639d5316d1fca39d851fad5c04460bf2054f5bc1856e41b12bca06b53207548023bf87a5900701bafd0df975e7

data/.github/workflows/main.yml

@@ -0,0 +1,16 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.6.3
+        bundler-cache: true
+    - name: Run the default task
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.ruby-version

@@ -0,0 +1 @@
+3.1.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-10-30
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at me@julik.nl. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in pecorino.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -0,0 +1,156 @@
+PATH
+  remote: .
+  specs:
+    pecorino (0.1.0)
+      activerecord (~> 7)
+      pg
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.0.4)
+      actionpack (= 7.0.4)
+      activesupport (= 7.0.4)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (7.0.4)
+      actionpack (= 7.0.4)
+      activejob (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
+      mail (>= 2.7.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.0.4)
+      actionpack (= 7.0.4)
+      actionview (= 7.0.4)
+      activejob (= 7.0.4)
+      activesupport (= 7.0.4)
+      mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
+      rails-dom-testing (~> 2.0)
+    actionpack (7.0.4)
+      actionview (= 7.0.4)
+      activesupport (= 7.0.4)
+      rack (~> 2.0, >= 2.2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (7.0.4)
+      actionpack (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.0.4)
+      activesupport (= 7.0.4)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (7.0.4)
+      activesupport (= 7.0.4)
+      globalid (>= 0.3.6)
+    activemodel (7.0.4)
+      activesupport (= 7.0.4)
+    activerecord (7.0.4)
+      activemodel (= 7.0.4)
+      activesupport (= 7.0.4)
+    activestorage (7.0.4)
+      actionpack (= 7.0.4)
+      activejob (= 7.0.4)
+      activerecord (= 7.0.4)
+      activesupport (= 7.0.4)
+      marcel (~> 1.0)
+      mini_mime (>= 1.1.0)
+    activesupport (7.0.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    builder (3.2.4)
+    concurrent-ruby (1.1.10)
+    crass (1.0.6)
+    erubi (1.11.0)
+    globalid (1.0.0)
+      activesupport (>= 5.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    loofah (2.19.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (1.0.2)
+    method_source (1.0.0)
+    mini_mime (1.1.2)
+    minitest (5.16.3)
+    net-imap (0.3.1)
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.1.3)
+      timeout
+    net-smtp (0.3.2)
+      net-protocol
+    nio4r (2.5.8)
+    nokogiri (1.13.8-x86_64-darwin)
+      racc (~> 1.4)
+    pg (1.3.2)
+    racc (1.6.0)
+    rack (2.2.4)
+    rack-test (2.0.2)
+      rack (>= 1.3)
+    rails (7.0.4)
+      actioncable (= 7.0.4)
+      actionmailbox (= 7.0.4)
+      actionmailer (= 7.0.4)
+      actionpack (= 7.0.4)
+      actiontext (= 7.0.4)
+      actionview (= 7.0.4)
+      activejob (= 7.0.4)
+      activemodel (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
+      bundler (>= 1.15.0)
+      railties (= 7.0.4)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.3)
+      loofah (~> 2.3)
+    railties (7.0.4)
+      actionpack (= 7.0.4)
+      activesupport (= 7.0.4)
+      method_source
+      rake (>= 12.2)
+      thor (~> 1.0)
+      zeitwerk (~> 2.5)
+    rake (13.0.6)
+    thor (1.2.1)
+    timeout (0.3.0)
+    tzinfo (2.0.5)
+      concurrent-ruby (~> 1.0)
+    websocket-driver (0.7.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.6.1)
+
+PLATFORMS
+  x86_64-darwin-19
+
+DEPENDENCIES
+  activesupport (~> 7)
+  minitest (~> 5.0)
+  pecorino!
+  rails (~> 7)
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.3.5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Julik Tarkhanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# Pecorino
+
+Pecorino is a rate limiter based on the concept of leaky buckets. It uses your DB as the storage backend for the throttles. It is compact, easy to install, and does not require additional infrastructure. The approach used by Pecorino has been previously used by [prorate](https://github.com/WeTransfer/prorate) with Redis, and that approach has proven itself.
+
+Pecorino is designed to integrate seamlessly into any Rails application using a Postgres database (at the moment there is no MySQL support, we would be delighted if you could add it).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pecorino'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install pecorino
+
+## Usage
+
+First, add and run the migration to create the pecorino tables:
+
+    $ bin/rails g pecorino:install
+    $ bin/rails db:migrate
+
+Once that is done, you can use Pecorino to start defining your throttles. Imagine you have a resource called `vault` and you want to limit the number of updates to it to 5 per second. To achieve that, instantiate a new `Throttle` in your controller or job code, and then trigger it using `Throttle#request!`. A call to `request!` registers 1 token getting added to the bucket. If the bucket is full, or the throttle is currently in "block" mode (has recently been triggered), a `Pecorino::Throttle::Throttled` exception will be raised.
+
+```ruby
+throttle = Pecorino::Throttle.new(key: "vault", leak_rate: 5, capacity: 5)
+throttle.request!
+```
+
+The exception has an attribute called `retry_after` which you can use to render the appropriate 429 response.
+
+Although this approach might be susceptible to race conditions, you can interrogate your throttle before potentially causing an exception - and display an appropriate error message if the throttle would trigger anyway:
+
+```ruby
+return render :capacity_exceeded unless throttle.able_to_accept?
+```
+
+If you are dealing with a metered resource (like throughput, money, amount of storage...) you can supply the number of tokens to either `request!` or `able_to_accept?` to indicate the desired top-up of the leaky bucket. For example, if you are maintaining user wallets and want to ensure no more than 100 dollars may be taken from the wallet within a certain amount of time, you can do it like so:
+
+```ruby
+throttle = Pecorino::Throttle.new(key: "wallet_t_#{current_user.id}", leak_rate: 100 / 60.0 / 60.0, capacity: 100, block_for: 60*60*3)
+throttle.request!(20) # Attempt to withdraw 20 dollars
+throttle.request!(20) # Attempt to withdraw 20 dollars more
+throttle.request!(20) # Attempt to withdraw 20 dollars more
+throttle.request!(20) # Attempt to withdraw 20 dollars more
+throttle.request!(20) # Attempt to withdraw 20 dollars more
+throttle.request!(2) # Attempt to withdraw 2 dollars more, will raise `Throttled` and block withdrawals for 3 hours
+```
+
+Sometimes you don't want to use a throttle, but you want to track the amount added to the leaky bucket over time. A lower-level abstraction is available for that purpose in the form of the `LeakyBucket` class. It will not raise any exceptions and will not install blocks, but will permit you to track a bucket's state over time:
+
+
+```ruby
+b = Pecorino::LeakyBucket.new(key: "some_b", capacity: 100, leak_rate: 5)
+b.fillup(2) #=> Pecorino::LeakyBucket::State(full?: false, level: 2.0)
+sleep 0.2
+b.state #=> Pecorino::LeakyBucket::State(full?: false, level: 1.8)
+```
+
+Check out the inline YARD documentation for more options.
+
+## Cleaning out stale locks from the database
+
+We recommend running the following bit of code every couple of hours (via cron or similar) to delete the stale blocks and leaky buckets from the system:
+
+    Pecorino.prune!
+
+## Development
+
+After checking out the repo, run `bundle. Then, run `rake test` to run the tests.
+
+To 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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/julik/pecorino. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/julik/pecorino/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Pecorino project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/julik/pecorino/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/pecorino/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Pecorino
+  #
+  # Rails generator used for setting up GoodJob in a Rails application.
+  # Run it with +bin/rails g good_job:install+ in your console.
+  #
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+
+    TEMPLATES = File.join(File.dirname(__FILE__))
+    source_paths << TEMPLATES
+
+    class_option :database, type: :string, aliases: %i(--db), desc: "The database for your migration. By default, the current environment's primary database is used."
+
+    # Generates monolithic migration file that contains all database changes.
+    def create_migration_file
+      migration_template 'migrations/create_pecorino_tables.rb.erb', File.join(db_migrate_path, "create_pecorino_tables.rb")
+    end
+
+    private
+
+    def migration_version
+      "[#{ActiveRecord::VERSION::STRING.to_f}]"
+    end
+  end
+end

data/lib/pecorino/leaky_bucket.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+# This offers just the leaky bucket implementation with fill control, but without the timed lock.
+# It does not raise any exceptions, it just tracks the state of a leaky bucket in Postgres.
+#
+# Leak rate is specified directly in tokens per second, instead of specifying the block period.
+# The bucket level is stored and returned as a Float which allows for finer-grained measurement,
+# but more importantly - makes testing from the outside easier.
+#
+# Note that this implementation has a peculiar property: the bucket is only "full" once it overflows.
+# Due to a leak rate just a few microseconds after that moment the bucket is no longer going to be full
+# anymore as it will have leaked some tokens by then. This means that the information about whether a
+# bucket has become full or not gets returned in the bucket `State` struct right after the database
+# update gets executed, and if your code needs to make decisions based on that data it has to use
+# this returned state, not query the leaky bucket again. Specifically:
+#
+#     state = bucket.fillup(1) # Record 1 request
+#     state.full? #=> true, this is timely information
+#
+# ...is the correct way to perform the check. This, however, is not:
+#
+#     bucket.fillup(1)
+#     bucket.state.full? #=> false, some time has passed after the topup and some tokens have already leaked
+#
+# The storage use is one DB row per leaky bucket you need to manage (likely - one throttled entity such
+# as a combination of an IP address + the URL you need to procect). The `key` is an arbitrary string you provide.
+class Pecorino::LeakyBucket
+  class State < Struct.new(:level, :full)
+    # Returns the level of the bucket after the operation on the LeakyBucket
+    # object has taken place. There is a guarantee that no tokens have leaked
+    # from the bucket between the operation and the freezing of the State
+    # struct.
+    #
+    # @!attribute [r] level
+    #   @return [Float]
+
+    # Tells whether the bucket was detected to be full when the operation on
+    # the LeakyBucket was performed. There is a guarantee that no tokens have leaked
+    # from the bucket between the operation and the freezing of the State
+    # struct.
+    #
+    # @!attribute [r] full
+    #   @return [Boolean]
+
+    alias_method :full?, :full
+
+    # Returns the bucket level of the bucket state as a Float
+    #
+    # @return [Float]
+    def to_f
+      level.to_f
+    end
+
+    # Returns the bucket level of the bucket state rounded to an Integer
+    #
+    # @return [Integer]
+    def to_i
+      level.to_i
+    end
+  end
+
+  # Creates a new LeakyBucket. The object controls 1 row in Postgres which is
+  # specific to the bucket key.
+  #
+  # @param key[String] the key for the bucket. The key also gets used
+  #   to derive locking keys, so that operations on a particular bucket
+  #   are always serialized.
+  # @param leak_rate[Float] the leak rate of the bucket, in tokens per second
+  # @param capacity[Numeric] how many tokens is the bucket capped at.
+  #   Filling up the bucket using `fillup()` will add to that number, but
+  #   the bucket contents will then be capped at this value. So with
+  #   bucket_capacity set to 12 and a `fillup(14)` the bucket will reach the level
+  #   of 12, and will then immediately start leaking again.
+  def initialize(key:, leak_rate:, capacity:)
+    @key = key
+    @leak_rate = leak_rate.to_f
+    @capacity = capacity.to_f
+  end
+
+  # Places `n` tokens in the bucket. Once tokens are placed, the bucket is set to expire
+  # within 2 times the time it would take it to leak to 0, regardless of how many tokens
+  # get put in - since the amount of tokens put in the bucket will always be capped
+  # to the `capacity:` value you pass to the constructor. Calling `fillup` also deletes
+  # leaky buckets which have expired.
+  #
+  # @param n_tokens[Float]
+  # @return [State] the state of the bucket after the operation
+  def fillup(n_tokens)
+    add_tokens(n_tokens.to_f)
+  end
+
+  # Returns the current state of the bucket, containing the level and whether the bucket is full.
+  # Calling this method will not perform any database writes.
+  #
+  # @return [State] the snapshotted state of the bucket at time of query
+  def state
+    conn = ActiveRecord::Base.connection
+    query_params = {
+      key: @key,
+      capa: @capacity.to_f,
+      leak_rate: @leak_rate.to_f
+    }
+    # The `level` of the bucket is what got stored at `last_touched_at` time, and we can
+    # extrapolate from it to see how many tokens have leaked out since `last_touched_at` -
+    # we don't need to UPDATE the value in the bucket here
+    sql = ActiveRecord::Base.sanitize_sql_array([<<~SQL, query_params])
+      SELECT
+        GREATEST(
+          0.0, LEAST(
+            :capa,
+            t.level - (EXTRACT(EPOCH FROM (clock_timestamp() - t.last_touched_at)) * :leak_rate)
+          )
+        )
+      FROM 
+        pecorino_leaky_buckets AS t
+      WHERE
+        key = :key
+    SQL
+
+    # If the return value of the query is a NULL it means no such bucket exists,
+    # so we assume the bucket is empty
+    current_level = conn.uncached { conn.select_value(sql) } || 0.0
+
+    State.new(current_level, (@capacity - current_level).abs < 0.01)
+  end
+
+  # Tells whether the bucket can accept the amount of tokens without overflowing.
+  # Calling this method will not perform any database writes. Note that this call is
+  # not race-safe - another caller may still overflow the bucket. Before performing
+  # your action, you still need to call `fillup()` - but you can preemptively refuse
+  # a request if you already know the bucket is full.
+  #
+  # @param n_tokens[Float]
+  # @return [boolean]
+  def able_to_accept?(n_tokens)
+    (state.level + n_tokens) < @capacity
+  end
+
+  private
+
+  def add_tokens(n_tokens)
+    conn = ActiveRecord::Base.connection
+
+    # Take double the time it takes the bucket to empty under normal circumstances
+    # until the bucket may be deleted.
+    may_be_deleted_after_seconds = (@capacity.to_f / @leak_rate.to_f) * 2.0
+
+    # Create the leaky bucket if it does not exist, and update
+    # to the new level, taking the leak rate into account - if the bucket exists.
+    query_params = {
+      key: @key,
+      capa: @capacity.to_f,
+      delete_after_s: may_be_deleted_after_seconds,
+      leak_rate: @leak_rate.to_f,
+      fillup: n_tokens.to_f
+    }
+    sql = ActiveRecord::Base.sanitize_sql_array([<<~SQL, query_params])
+      INSERT INTO pecorino_leaky_buckets AS t
+        (key, last_touched_at, may_be_deleted_after, level)
+      VALUES
+        (
+          :key,
+          clock_timestamp(),
+          clock_timestamp() + ':delete_after_s second'::interval,
+          GREATEST(0.0,
+            LEAST(
+              :capa,
+              :fillup
+            )
+          )
+        )
+      ON CONFLICT (key) DO UPDATE SET
+        last_touched_at = EXCLUDED.last_touched_at,
+        may_be_deleted_after = EXCLUDED.may_be_deleted_after,
+        level = GREATEST(0.0,
+          LEAST(
+              :capa,
+              t.level + :fillup - (EXTRACT(EPOCH FROM (EXCLUDED.last_touched_at - t.last_touched_at)) * :leak_rate)
+          )
+        )
+      RETURNING level
+    SQL
+
+    # Note the use of .uncached here. The AR query cache will actually see our
+    # query as a repeat (since we use "select_value" for the RETURNING bit) and will not call into Postgres
+    # correctly, thus the clock_timestamp() value would be frozen between calls. We don't want that here.
+    # See https://stackoverflow.com/questions/73184531/why-would-postgres-clock-timestamp-freeze-inside-a-rails-unit-test
+    level_after_fillup = conn.uncached { conn.select_value(sql) }
+
+    State.new(level_after_fillup, (@capacity - level_after_fillup).abs < 0.01)
+  end
+end

data/lib/pecorino/migrations/create_raclette_tables.rb.erb

@@ -0,0 +1,5 @@
+class CreatePecorinoTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    Pecorino.create_tables(self)
+  end
+end

data/lib/pecorino/railtie.rb

@@ -0,0 +1,7 @@
+module Pecorino
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative "install_generator"
+    end
+  end
+end

data/lib/pecorino/throttle.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Provides a throttle with a block based on the `LeakyBucket`. Once a bucket fills up,
+# a block will be installed and an exception will be raised. Once a block is set, no
+# checks will be done on the leaky bucket - any further requests will be refused until
+# the block is lifted. The block time can be arbitrarily higher or lower than the amount
+# of time it takes for the leaky bucket to leak out
+class Pecorino::Throttle
+  class State < Struct.new(:blocked_until)
+    # Tells whether this throttle is blocked, either due to the leaky bucket having filled up
+    # or due to there being a timed block set because of an earlier event of the bucket having
+    # filled up
+    def blocked?
+      blocked_until ? true : false
+    end
+
+    def retry_after
+      (blocked_until - Time.now.utc).ceil
+    end
+  end
+
+  class Throttled < StandardError
+    # Returns the throttle which raised the exception. Can be used to disambiguiate between
+    # multiple Throttled exceptions when multiple throttles are applied in a layered fashion:
+    #
+    #      ip_addr_throttle.request!
+    #      user_email_throttle.request!
+    #      db_insert_throttle.request!(n_items_to_insert)
+    #    rescue Pecorino::Throttled => e
+    #      deliver_notification(user) if e.throttle == user_email_throttle
+    #
+    # @return [Throttle]
+    attr_reader :throttle
+
+    # Returns the `retry_after` value in seconds, suitable for use in an HTTP header
+    attr_reader :retry_after
+
+    def initialize(from_throttle, state)
+      @throttle = from_throttle
+      @retry_after = state.retry_after
+      super("Block in effect until #{state.blocked_until.iso8601}")
+    end
+  end
+
+  # @param key[String] the key for both the block record and the leaky bucket
+  # @param block_for[Numeric] the number of seconds to block any further requests for
+  # @param leaky_bucket_options Options for `Pecorino::LeakyBucket.new`
+  # @see PecorinoLeakyBucket.new
+  def initialize(key:, block_for: 30, **leaky_bucket_options)
+    @key = key.to_s
+    @block_for = block_for.to_f
+    @bucket = Pecorino::LeakyBucket.new(key:, **leaky_bucket_options)
+  end
+
+  # Tells whether the throttle will let this number of requests pass without raising
+  # a Throttled. Note that this is not race-safe. Another request could overflow the bucket
+  # after you call `able_to_accept?` but before you call `throttle!`. So before performing
+  # the action you still need to call `throttle!`
+  #
+  # @param n_tokens[Float]
+  # @return [boolean]
+  def able_to_accept?(n_tokens = 1)
+    conn = ActiveRecord::Base.connection
+    !blocked_until(conn) && @bucket.able_to_accept?(n_tokens)
+  end
+
+  # Register that a request is being performed. Will raise Throttled
+  # if there is a block in place on that key, or if the bucket has been filled up
+  # and a block has been put in place as a result of this particular request.
+  #
+  # The exception can be rescued later to provide a 429 response. This method is better
+  # to use before performing the unit of work that the throttle is guarding:
+  #
+  # @example      t.request!
+  #               Note.create!(note_params)
+  #            rescue Pecorino::Throttle::Throttled => e
+  #               [429, {"Retry-After" => e.retry_after.to_s}, []]
+  #
+  # If the method call succeeds it means that the request is not getting throttled.
+  #
+  # @return void
+  def request!(n = 1)
+    state = request(n)
+    raise Throttled.new(self, state) if state.blocked?
+  end
+
+  # Register that a request is being performed. Will not raise any exceptions but return
+  # the time at which the block will be lifted if a block resulted from this request or
+  # was already in effect. Can be used for registering actions which already took place,
+  # but should result in subsequent actions being blocked in subsequent requests later.
+  #
+  # @example    unless t.able_to_accept?
+  #       Note.create!(note_params)
+  #       t.request
+  #     else
+  #       raise "Throttled or block in effect"
+  #     end
+  #
+  # @return [State] the state of the throttle after filling up the leaky bucket / trying to pass the block
+  def request(n = 1)
+    conn = ActiveRecord::Base.connection
+    existing_blocked_until = blocked_until(conn)
+    return State.new(existing_blocked_until.utc) if existing_blocked_until
+
+    # Topup the leaky bucket
+    return State.new(nil) unless @bucket.fillup(n.to_f).full?
+
+    # and set the block if we reached it
+    query_params = {key: @key, block_for: @block_for}
+    block_set_query = ActiveRecord::Base.sanitize_sql_array([<<~SQL, query_params])
+      INSERT INTO pecorino_blocks AS t
+        (key, blocked_until)
+      VALUES
+        (:key, NOW() + ':block_for seconds'::interval)
+      ON CONFLICT (key) DO UPDATE SET
+        blocked_until = GREATEST(EXCLUDED.blocked_until, t.blocked_until)
+      RETURNING blocked_until;
+    SQL
+
+    fresh_blocked_until = conn.uncached { conn.select_value(block_set_query) }
+    State.new(fresh_blocked_until.utc)
+  end
+
+  private
+
+  def blocked_until(via_connection)
+    block_check_query = ActiveRecord::Base.sanitize_sql_array([<<~SQL, @key])
+      SELECT blocked_until FROM pecorino_blocks WHERE key = ? AND blocked_until >= NOW() LIMIT 1
+    SQL
+    via_connection.uncached { via_connection.select_value(block_check_query) }
+  end
+end

data/lib/pecorino/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pecorino
+  VERSION = "0.1.0"
+end

data/lib/pecorino.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "pecorino/version"
+require_relative "pecorino/leaky_bucket"
+require_relative "pecorino/throttle"
+require_relative "pecorino/railtie" if defined?(Rails::Railtie)
+
+module Pecorino
+  # Deletes stale leaky buckets and blocks which have expired. Run this method regularly to
+  # avoid accumulating too many unused rows in your tables.
+  #
+  # @return void
+  def self.prune!
+    # Delete all the old blocks here (if we are under a heavy swarm of requests which are all
+    # blocked it is probably better to avoid the big delete)
+    ActiveRecord::Base.connection.execute("DELETE FROM pecorino_blocks WHERE blocked_until < NOW()")
+
+    # Prune buckets which are no longer used. No "uncached" needed here since we are using "execute"
+    ActiveRecord::Base.connection.execute("DELETE FROM pecorino_leaky_buckets WHERE may_be_deleted_after < NOW()")
+  end
+
+
+  # Creates the tables and indexes needed for Pecorino. Call this from your migrations like so:
+  # class CreatePecorinoTables < ActiveRecord::Migration<%= migration_version %>
+  #
+  #     def change
+  #       Pecorino.create_tables(self)
+  #     end
+  #
+  # @param active_record_schema[ActiveRecord::SchemaMigration] the migration through which we will create the tables
+  # @return void
+  def self.create_tables(active_record_schema)
+    active_record_schema.create_table :pecorino_leaky_buckets, id: :uuid do |t|
+      t.string :key, null: false
+      t.float :level, null: false
+      t.datetime :last_touched_at, null: false
+      t.datetime :may_be_deleted_after, null: false
+    end
+    active_record_schema.add_index :pecorino_leaky_buckets, [:key], unique: true
+    active_record_schema.add_index :pecorino_leaky_buckets, [:may_be_deleted_after]
+
+    active_record_schema.create_table :pecorino_blocks, id: :uuid do |t|
+      t.string :key, null: false
+      t.datetime :blocked_until, null: false
+    end
+    active_record_schema.add_index :pecorino_blocks, [:key], unique: true
+    active_record_schema.add_index :pecorino_blocks, [:blocked_until]
+  end
+end

data/pecorino.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/pecorino/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "pecorino"
+  spec.version       = Pecorino::VERSION
+  spec.authors       = ["Julik Tarkhanov"]
+  spec.email         = ["me@julik.nl"]
+
+  spec.summary       = "Database-based rate limiter using leaky buckets"
+  spec.description   = "Pecorino allows you to define throttles and rate meters for your metered resources, all through your standard DB"
+  spec.homepage      = "https://github.com/cheddar-me/pecorino"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.4.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to 'https://mygemserver.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/cheddar-me/pecorino"
+  spec.metadata["changelog_uri"] = "https://github.com/cheddar-me/pecorino/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "activerecord", "~> 7"
+  spec.add_dependency "pg"
+  spec.add_development_dependency "activesupport", "~> 7"
+  spec.add_development_dependency "rails", "~> 7"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: pecorino
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Julik Tarkhanov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-11-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+description: Pecorino allows you to define throttles and rate meters for your metered
+  resources, all through your standard DB
+email:
+- me@julik.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/pecorino.rb
+- lib/pecorino/install_generator.rb
+- lib/pecorino/leaky_bucket.rb
+- lib/pecorino/migrations/create_raclette_tables.rb.erb
+- lib/pecorino/railtie.rb
+- lib/pecorino/throttle.rb
+- lib/pecorino/version.rb
+- pecorino.gemspec
+homepage: https://github.com/cheddar-me/pecorino
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cheddar-me/pecorino
+  source_code_uri: https://github.com/cheddar-me/pecorino
+  changelog_uri: https://github.com/cheddar-me/pecorino/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Database-based rate limiter using leaky buckets
+test_files: []