pecorino 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cd65abe4917de817a0b0b08672376d5a7dd1e16c01b3a4e0c47ff1467600a1e
-  data.tar.gz: 58ca1578813b7a5bcc058d9a37a869e778a1614b736becced4bc82f78efba2c5
+  metadata.gz: fbbf2138b0295606f7a2a217aa41f30bcd1d1b994a9e079f810b5c0088045714
+  data.tar.gz: b1b594fbdbeb1d1e4f2019a50869b0ba038eb161d4385d36707e5b74d82eedb6
 SHA512:
-  metadata.gz: bbbcdc936bef119b1b02695dc626f8421576a619414f4493a541876562ca3cf5136dcdd1a796c9c08cd6cc2a8345be8ac7fecd8f6371fddc9b480bd26d017296
-  data.tar.gz: cd4e2ba40164eb0c9f56e17aeef656727703cb98f7e70cedaafa3d9af9202195f9c0e1a1dbc3dfdb411f277f31e84a6a2641d5f81bf85d6d07b3b92937877cbd
+  metadata.gz: 4b3b0ba688ae6b04d85943b03da908c140db2d2ec7a326da8e87a54e4fa6a077a7b36d4a8ba29a9ed051762d771c036d0f3d2599c8d48d40f5073810a5524234
+  data.tar.gz: cc7b1d692935a8af49ec479fd3c5c98ea65749879ecaf22addeaeb285eedf37406df755c6dfa17d379d6cbcb07bc96150573b1262bbb98d4509ba1170fc195d9

data/CHANGELOG.md

@@ -1,4 +1,8 @@
-## [0.5.0] - 2024-02-11
+## 0.6.0
+
+- Add `Pecorino::Block` for setting blocks directly. These are available both to `Throttle` with the same key and on their own. This can be used to set arbitrary blocks without having to configure a `Throttle` first.
+
+## 0.5.0
 
 - Add `CachedThrottle` for caching the throttle blocks. This allows protection to the database when the throttle is in a blocked state.
 - Add `Throttle#throttled` for silencing alerts
@@ -6,11 +10,11 @@
 - Allow accessing `Throttle::State` from the `Throttled` exception so that the blocked throttle state can be cached downstream (in Rails cache, for example)
 - Make `Throttle#request!` return the new state if there was no exception raised
 
-## [0.4.1] - 2024-02-11
+## 0.4.1
 
 - Make sure Pecorino works on Ruby 2.7 as well by removing 3.x-exclusive syntax
 
-## [0.4.0] - 2024-01-22
+## 0.4.0
 
 - Use Bucket#connditional_fillup inside Throttle and throttle only when the capacity _would_ be exceeded, as opposed
   to throttling when capacity has already been exceeded. This allows for finer-grained throttles such as
@@ -21,17 +25,17 @@
 - Allow "conditional fillup" - only add tokens to the leaky bucket if the bucket has enough space.
 - Fix `over_time` leading to incorrect `leak_rate`. The divider/divisor were swapped, leading to the inverse leak rate getting computed.
 
-## [0.3.0] - 2024-01-18
+## 0.3.0
 
 - Allow `over_time` in addition to `leak_rate`, which is a more intuitive parameter to tweak
 - Set default `block_for` to the time it takes the bucket to leak out completely instead of 30 seconds
 
-## [0.2.0] - 2024-01-09
+## 0.2.0
 
 - [Add support for SQLite](https://github.com/cheddar-me/pecorino/pull/9)
 - [Use comparisons in SQL to determine whether the leaky bucket did overflow](https://github.com/cheddar-me/pecorino/pull/8)
 - [Change the way Structs are defined to appease Tapioca/Sorbet](https://github.com/cheddar-me/pecorino/pull/6)
 
-## [0.1.0] - 2023-10-30
+## 0.1.0
 
 - Initial release

data/README.md

@@ -1,10 +1,10 @@
 # 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 a rate limiter based on the concept of leaky buckets, or more specifically - based on the [generic cell rate](https://brandur.org/rate-limiting) algorithm. 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 PostgreSQL or SQLite database (at the moment there is no MySQL support, we would be delighted if you could add it).
 
-If you would like to know more about the leaky bucket algorithm: [this article](http://live.julik.nl/2022/08/the-unreasonable-effectiveness-of-leaky-buckets) or the [Wikipedia article](https://en.wikipedia.org/wiki/Leaky_bucket) are both good starting points.
+If you would like to know more about the leaky bucket algorithm: [this article](http://live.julik.nl/2022/08/the-unreasonable-effectiveness-of-leaky-buckets) or the [Wikipedia article](https://en.wikipedia.org/wiki/Leaky_bucket) are both good starting points. [This Wikipedia article](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm) describes the generic cell rate algorithm in more detail as well.
 
 ## Installation
 
@@ -103,6 +103,58 @@ end
 
 This way, every time there is an error on the "fancy AI service" the throttle will be triggered, and if it overflows - a subsequent request will be blocked.
 
+## A note on database transactions
+
+Pecorino uses your main database. When calling the `Throttle` or `LeakyBucket` objects, SQL queries will be performed by Pecorino and those queries may result in changes to data. If you are currently inside a database transaction, your bucket topups or set blocks may get reverted. For example, imagine you have a controller like this:
+
+```ruby
+class WalletController < ApplicationController
+  rescue_from Pecorino::Throttle::Throttled do |e|
+    response.set_header('Retry-After', e.retry_after.to_s)
+    render nothing: true, status: 429
+  end
+
+  def withdraw
+     Wallet.transaction do
+       t = Pecorino::Throttle.new("wallet_#{current_user.id}_max_withdrawal", capacity: 200_00, over_time: 5.minutes)
+       t.request!(10_00)
+       current_user.wallet.withdraw(Money.new(10, "EUR"))
+     end
+  end
+end
+```
+
+what will happen is that even though the `withdraw()` call is not going to be performed, the increment of the throttle will not either, because the exception will result in a `ROLLBACK`.
+
+If you need to use Pecorino in combination with transactions, you will need to design with that in mind. Either call `Throttle` before entering the `transaction do`:
+
+```ruby
+def withdraw
+  t = Pecorino::Throttle.new("wallet_#{current_user.id}_max_withdrawal", capacity: 200_00, over_time: 5.minutes)
+  t.request!(10_00)
+  Wallet.transaction do
+    current_user.wallet.withdraw(Money.new(10, "EUR"))
+  end
+end
+```
+
+or use the `request()` method instead to still commit:
+
+```ruby
+def withdraw
+  Wallet.transaction do
+    t = Pecorino::Throttle.new("wallet_#{current_user.id}_max_withdrawal", capacity: 200_00, over_time: 5.minutes)
+    throttle_state = t.request(10_00)
+    return render(nothing: true, status: 429) if throttle_state.blocked?
+
+    current_user.wallet.withdraw(Money.new(10, "EUR"))
+  end
+end
+```
+
+Note also that this behaviour might be desirable for your use case (that the throttle and the data update together in
+a transactional manner) – it just helps to be aware of it.
+
 ## Using just the leaky bucket
 
 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:

data/lib/pecorino/block.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Provides access to Pecorino blocks - same blocks which get set when a throttle triggers. The blocks
+# are just keys in the data store which have an expiry value. This can be useful if you want to restrict
+# access to a resource for an arbitrary timespan.
+class Pecorino::Block
+  # Sets a block for the given key. The block will also be seen by the Pecorino::Throttle with the same key
+  #
+  # @param key[String] the key to set the block for
+  # @param block_for[Float] the number of seconds or a time interval to block for
+  # @return [Time] the time when the block will be released
+  def self.set!(key:, block_for:)
+    Pecorino.adapter.set_block(key: key, block_for: block_for)
+    Time.now + block_for
+  end
+
+  # Returns the time until a certain block is in effect
+  #
+  # @return [Time,nil] the time when the block will be released
+  def self.blocked_until(key:)
+    t = Pecorino.adapter.blocked_until(key: key)
+    (t && t > Time.now) ? t : nil
+  end
+end

data/lib/pecorino/throttle.rb

@@ -156,7 +156,7 @@ class Pecorino::Throttle
   #
   # @return [State] the state of the throttle after filling up the leaky bucket / trying to pass the block
   def request(n = 1)
-    existing_blocked_until = Pecorino.adapter.blocked_until(key: @key)
+    existing_blocked_until = Pecorino::Block.blocked_until(key: @key)
     return State.new(existing_blocked_until.utc) if existing_blocked_until
 
     # Topup the leaky bucket, and if the topup gets rejected - block the caller
@@ -165,7 +165,7 @@ class Pecorino::Throttle
       State.new(nil)
     else
       # and set the block if the fillup was rejected
-      fresh_blocked_until = Pecorino.adapter.set_block(key: @key, block_for: @block_for)
+      fresh_blocked_until = Pecorino::Block.set!(key: @key, block_for: @block_for)
       State.new(fresh_blocked_until.utc)
     end
   end

data/lib/pecorino/version.rb

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

data/lib/pecorino.rb

@@ -4,14 +4,15 @@ require "active_support/concern"
 require "active_record/sanitization"
 
 require_relative "pecorino/version"
-require_relative "pecorino/leaky_bucket"
-require_relative "pecorino/throttle"
 require_relative "pecorino/railtie" if defined?(Rails::Railtie)
-require_relative "pecorino/cached_throttle"
 
 module Pecorino
   autoload :Postgres, "pecorino/postgres"
   autoload :Sqlite, "pecorino/sqlite"
+  autoload :LeakyBucket, "pecorino/leaky_bucket"
+  autoload :Block, "pecorino/block"
+  autoload :Throttle, "pecorino/throttle"
+  autoload :CachedThrottle, "pecorino/cached_throttle"
 
   # Deletes stale leaky buckets and blocks which have expired. Run this method regularly to
   # avoid accumulating too many unused rows in your tables.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pecorino
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Julik Tarkhanov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-11 00:00:00.000000000 Z
+date: 2024-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -154,6 +154,7 @@ files:
 - README.md
 - Rakefile
 - lib/pecorino.rb
+- lib/pecorino/block.rb
 - lib/pecorino/cached_throttle.rb
 - lib/pecorino/install_generator.rb
 - lib/pecorino/leaky_bucket.rb