pecorino 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfcca80bad8895a9b45ed8a3ed0afe06b52a0c6a851d8506b102a82b5375c2a3
-  data.tar.gz: 7f57dd803797acfdf29a8d7cae31854528012af249887ae49e398b992a48f9d4
+  metadata.gz: 2f94aa734cb0bb50657f5484bbdd8bfcaabc7c2d6b7d9329361d41456ba49db6
+  data.tar.gz: 97e01c53e828092ce60be1412a288a70446ec9cc5ab783a6fa6e3ba147de1ee5
 SHA512:
-  metadata.gz: dea8f3c693c1d9b5412cdc50cd333d1de6b92d90ec1358ae3c3f5d03fef685649bccd4f6fcc8757e04aa7aba5b13411b325b69b374be0bf30a86d10c16977613
-  data.tar.gz: ee00695a622947cbdc14a300d73d06a850abd2357b3c1357e7904e7c93f2ea5513a4edbb98349a896b5b39cc57b08e889a221e78319e5344f778000dd7059f06
+  metadata.gz: 4d83ebb84009492403ca8950d181f4689b42782ab3f65f7fe5091cab92fc4f739ecd64625449ab784309a122f09e62525c262c71f3c602d3d538f4ac511a78e3
+  data.tar.gz: 93d3a2845713c6dc71ff1f35e5433fcbca6837fdb336db00a7e403e5719f1e65eadac7dc819301c8886d40dc3f99c59b196d64004145de786d0875c42b98e635

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.3.0] - 2024-01-18
+
+- 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
 
 - [Add support for SQLite](https://github.com/cheddar-me/pecorino/pull/9)

data/README.md

@@ -25,7 +25,7 @@ And then execute:
 Once the installation 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 = Pecorino::Throttle.new(key: "vault", over_time: 1.second, capacity: 5)
 throttle.request!
 ```
 In a Rails controller you can then rescue from this exception to render the appropriate response:
@@ -58,7 +58,7 @@ 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 = Pecorino::Throttle.new(key: "wallet_t_#{current_user.id}", over_time_: 1.hour, 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

data/lib/pecorino/leaky_bucket.rb

@@ -59,21 +59,40 @@ class Pecorino::LeakyBucket
     end
   end
 
+  # The key (name) of the leaky bucket
+  #   @return [String]
+  attr_reader :key
+
+  # The leak rate (tokens per second) of the bucket
+  #   @return [Float]
+  attr_reader :leak_rate
+
+  # The capacity of the bucket in tokens
+  #   @return [Float]
+  attr_reader :capacity
+
   # Creates a new LeakyBucket. The object controls 1 row in the database 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 leak_rate[Float] the leak rate of the bucket, in tokens per second.
+  #   Either `leak_rate` or `over_time` can be used, but not both.
+  # @param over_time[#to_f] over how many seconds the bucket will leak out to 0 tokens.
+  #   The value is assumed to be the number of seconds
+  #   - or a duration which returns the number of seconds from `to_f`.
+  #   Either `leak_rate` or `over_time` can be used, but not both.
   # @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:)
+  def initialize(key:, capacity:, leak_rate: nil, over_time: nil)
+    raise ArgumentError, "Either leak_rate: or over_time: must be specified" if leak_rate.nil? && over_time.nil?
+    raise ArgumentError, "Either leak_rate: or over_time: may be specified, but not both" if leak_rate && over_time
+    @leak_rate = leak_rate || (over_time.to_f / capacity)
     @key = key
-    @leak_rate = leak_rate.to_f
     @capacity = capacity.to_f
   end
 

data/lib/pecorino/throttle.rb

@@ -43,13 +43,14 @@ class Pecorino::Throttle
   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 block_for[Numeric] the number of seconds to block any further requests for. Defaults to time it takes
+  #   the bucket to leak out to the level of 0
   # @param leaky_bucket_options Options for `Pecorino::LeakyBucket.new`
   # @see PecorinoLeakyBucket.new
-  def initialize(key:, block_for: 30, **)
-    @key = key.to_s
-    @block_for = block_for.to_f
+  def initialize(key:, block_for: nil, **)
     @bucket = Pecorino::LeakyBucket.new(key:, **)
+    @key = key.to_s
+    @block_for = block_for ? block_for.to_f : (@bucket.capacity / @bucket.leak_rate)
   end
 
   # Tells whether the throttle will let this number of requests pass without raising

data/lib/pecorino/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pecorino
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Julik Tarkhanov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-01-09 00:00:00.000000000 Z
+date: 2024-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord