pecorino 0.7.1 → 0.7.3

data/test/leaky_bucket_test.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class LeakyBucketTest < ActiveSupport::TestCase
+  def memory_adapter
+    @adapter ||= Pecorino::Adapters::MemoryAdapter.new
+  end
+
+  # This test is performed multiple times since time is involved, and there can be fluctuations
+  # between the iterations
+  8.times do |n|
+    test "on iteration #{n} accepts a certain number of tokens and returns the new bucket level" do
+      bucket = Pecorino::LeakyBucket.new(key: Random.uuid, leak_rate: 1.1, capacity: 15, adapter: memory_adapter)
+      assert_in_delta bucket.state.level, 0, 0.0001
+
+      state = bucket.fillup(20)
+      assert_predicate state, :full?
+      assert_in_delta state.level, 15.0, 0.0001
+
+      sleep 0.2
+      assert_in_delta bucket.state.level, 14.77, 0.1
+
+      sleep 0.3
+      assert_in_delta bucket.state.level, 14.4, 0.1
+      assert_in_delta bucket.fillup(-3).level, 11.4, 0.1
+
+      assert_in_delta bucket.fillup(-300).level, 0, 0.1
+    end
+  end
+
+  test "exposes the parameters via reader methods" do
+    bucket = Pecorino::LeakyBucket.new(key: "some-bk", leak_rate: 1.1, capacity: 15, adapter: memory_adapter)
+    assert_equal bucket.key, "some-bk"
+    assert_equal bucket.leak_rate, 1.1
+    assert_equal bucket.capacity, 15.0
+  end
+
+  test "translates over_time into an appropriate leak_rate at instantiation" do
+    throttle = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 10, capacity: 20, adapter: memory_adapter)
+    assert_in_delta 2.0, throttle.leak_rate, 0.01
+  end
+
+  test "tells whether it is able to accept a value which will bring it to capacity" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, leak_rate: 1, capacity: 3, adapter: memory_adapter)
+    assert bucket.able_to_accept?(3)
+  end
+
+  test "allows either of leak_rate or over_time to be used" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, leak_rate: 1.1, capacity: 15, adapter: memory_adapter)
+    bucket.fillup(20)
+    sleep 0.2
+    assert_in_delta bucket.state.level, 14.77, 0.1
+
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 13.6, capacity: 15, adapter: memory_adapter)
+    bucket.fillup(20)
+    sleep 0.2
+    assert_in_delta bucket.state.level, 14.77, 0.1
+
+    assert_raises(ArgumentError) do
+      Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 13.6, leak_rate: 1.1, capacity: 15, adapter: memory_adapter)
+    end
+
+    assert_raises(ArgumentError) do
+      Pecorino::LeakyBucket.new(key: Random.uuid, capacity: 15, adapter: memory_adapter)
+    end
+  end
+
+  test "does not allow a bucket to be created with a negative value" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, leak_rate: 1.1, capacity: 15, adapter: memory_adapter)
+    assert_in_delta bucket.state.level, 0, 0.0001
+
+    state = bucket.fillup(-10)
+    assert_in_delta state.level, 0, 0.1
+  end
+
+  test "allows check for the bucket leaking out" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, leak_rate: 1.1, capacity: 15, adapter: memory_adapter)
+    assert_in_delta bucket.state.level, 0, 0.0001
+
+    state = bucket.fillup(10)
+    refute_predicate state, :full?
+
+    refute bucket.able_to_accept?(6)
+    assert bucket.able_to_accept?(4)
+    assert_in_delta bucket.state.level, 10.0, 0.1
+  end
+
+  test "allows the bucket to leak out completely" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, leak_rate: 2, capacity: 1, adapter: memory_adapter)
+    assert_predicate bucket.fillup(1), :full?
+
+    sleep(0.25)
+    assert_in_delta bucket.state.level, 0.5, 0.1
+
+    sleep(0.25)
+    assert_in_delta bucket.state.level, 0, 0.1
+  end
+
+  test "with conditional fillup, allows a freshly created bucket to be filled to capacity with one call" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 1.0, capacity: 1.0, adapter: memory_adapter)
+    assert bucket.fillup_conditionally(1.0).accepted?
+  end
+
+  test "with conditional fillup, refuses a fillup that would overflow" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 1.0, capacity: 1.0, adapter: memory_adapter)
+    refute bucket.fillup_conditionally(1.1).accepted?
+  end
+
+  test "with conditional fillup, allows an existing bucket to be filled to capacity on the second call (INSERT vs. UPDATE)" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 1.0, capacity: 1.0, adapter: memory_adapter)
+    bucket.fillup(0.0) # Ensure the bucket row gets created
+    assert bucket.fillup_conditionally(1.0).accepted?
+  end
+
+  test "with conditional fillup, allows an existing bucket to be filled to capacity in a sequence of calls" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 1.0, capacity: 1.0, adapter: memory_adapter)
+    assert bucket.fillup_conditionally(0.5).accepted?
+    assert bucket.fillup_conditionally(0.5).accepted?
+    refute bucket.fillup_conditionally(0.1).accepted?
+  end
+
+  test "with conditional fillup, allows an existing bucket to be filled close to capacity in a sequence of calls" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 1.0, capacity: 1.0, adapter: memory_adapter)
+    assert bucket.fillup_conditionally(0.5).accepted?
+    assert bucket.fillup_conditionally(0.4).accepted?
+    refute bucket.fillup_conditionally(0.2).accepted?
+  end
+
+  test "allows conditional fillup" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 1.0, capacity: 1.0, adapter: memory_adapter)
+
+    counter = 0
+    try_fillup = ->(fillup_by, should_have_reached_level, should_have_accepted) {
+      counter += 1
+      state = bucket.fillup_conditionally(fillup_by)
+      assert_equal should_have_accepted, state.accepted?, "Update #{counter} did_accept should be #{should_have_accepted}"
+      assert_in_delta should_have_reached_level, state.level, 0.1
+    }
+
+    try_fillup.call(1.1, 0.0, false) # Oversized fillup must be refused outright
+    try_fillup.call(0.3, 0.3, true)
+    try_fillup.call(0.3, 0.6, true)
+    try_fillup.call(0.3, 0.9, true)
+    try_fillup.call(0.3, 0.9, false) # Would take the bucket to 1.2, so must be rejected
+
+    sleep(0.2) # Leak out 0.2 tokens
+
+    try_fillup.call(0.3, 1.0, true)
+    try_fillup.call(-2, 0.0, true) # A negative fillup is permitted since it will never take the bucket above capacity
+    try_fillup.call(1.0, 1.0, true) # Filling up in one step should be permitted
+  end
+
+  test "allows conditional fillup even if the bucket leaks out to 0 between calls" do
+    bucket = Pecorino::LeakyBucket.new(key: Random.uuid, over_time: 0.5, capacity: 30, adapter: memory_adapter)
+    assert bucket.fillup_conditionally(29.6).accepted?
+    refute bucket.fillup_conditionally(1).accepted?
+    sleep 0.6 # Spend enough time to allow the bucket to leak out completely
+    assert bucket.fillup_conditionally(1).accepted?, "Once the bucket has leaked out to 0 the fillup should be accepted again"
+  end
+end

data/test/pecorino_test.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class PecorinoTest < ActiveSupport::TestCase
+  test "has a version number" do
+    refute_nil ::Pecorino::VERSION
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "pecorino"
+
+require "minitest/autorun"
+require "active_support"
+require "active_support/test_case"
+require "active_record"
+
+class ActiveSupport::TestCase
+end

data/test/throttle_test.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ThrottleTest < ActiveSupport::TestCase
+  def memory_adapter
+    @adapter ||= Pecorino::Adapters::MemoryAdapter.new
+  end
+
+  test "request! installs a block and then removes it and communicates the block using exceptions" do
+    throttle = Pecorino::Throttle.new(key: Random.uuid, over_time: 1.0, capacity: 30, adapter: memory_adapter)
+
+    state_after_first_request = throttle.request!
+    assert_kind_of Pecorino::Throttle::State, state_after_first_request
+
+    # It must be possible to make exactly 30 requests without getting throttled, even if the
+    # bucket does not leak out at all between the calls
+    29.times do
+      throttle.request!
+    end
+
+    # The 31st request must always fail, as it won't fit into the bucket anymore (even if some
+    # tokens have leaked out by this point)
+    err = assert_raises Pecorino::Throttle::Throttled do
+      throttle.request!
+    end
+    assert_equal throttle, err.throttle
+    assert_in_delta err.retry_after, 1, 0.1
+    assert_kind_of Pecorino::Throttle::State, err.state
+
+    # Sleep until the block gets released - the block gets for block_for, which is the time it takes the bucket
+    # to leak out to 0
+    sleep 1.1
+    assert_nothing_raised do
+      throttle.request!
+    end
+  end
+
+  test "allows the block_for parameter to be omitted" do
+    assert_nothing_raised do
+      Pecorino::Throttle.new(key: Random.uuid, over_time: 1, capacity: 30, adapter: memory_adapter)
+    end
+  end
+
+  test "still throttles using request() without raising exceptions" do
+    throttle = Pecorino::Throttle.new(key: Random.uuid, leak_rate: 30, capacity: 30, block_for: 3, adapter: memory_adapter)
+
+    20.times do
+      state = throttle.request
+      refute_predicate state, :blocked?
+    end
+
+    20.times do
+      throttle.request
+    end
+
+    state = throttle.request
+    assert_predicate state, :blocked?
+
+    assert_in_delta state.blocked_until - Time.now, 3, 0.5
+    sleep 0.5
+
+    # Ensure we are still throttled
+    state = throttle.request
+    assert_predicate state, :blocked?
+    assert_in_delta state.blocked_until - Time.now, 2.5, 0.5
+    assert_kind_of Time, state.blocked_until
+
+    sleep(3.05)
+    state = throttle.request
+    refute_predicate state, :blocked?
+  end
+
+  test "able_to_accept? returns the prediction whether the throttle will accept" do
+    throttle = Pecorino::Throttle.new(key: Random.uuid, leak_rate: 30, capacity: 30, block_for: 2, adapter: memory_adapter)
+
+    assert throttle.able_to_accept?
+    assert throttle.able_to_accept?(29)
+    refute throttle.able_to_accept?(31)
+
+    # Depending on timing either the 30th or the 31st request may start to throttle
+    assert_raises Pecorino::Throttle::Throttled do
+      loop { throttle.request! }
+    end
+    refute throttle.able_to_accept?
+
+    sleep 2.5
+    assert throttle.able_to_accept?
+  end
+
+  test "starts to throttle sooner with a higher fillup rate" do
+    throttle = Pecorino::Throttle.new(key: Random.uuid, leak_rate: 30, capacity: 30, block_for: 3, adapter: memory_adapter)
+
+    15.times do
+      throttle.request!(2)
+    end
+
+    # Depending on timing either the 31st or the 30th request may start to throttle
+    err = assert_raises Pecorino::Throttle::Throttled do
+      loop { throttle.request! }
+    end
+
+    assert_in_delta err.retry_after, 3, 0.5
+  end
+
+  test "throttled() calls the block just once" do
+    throttle = Pecorino::Throttle.new(key: Random.uuid, over_time: 60, capacity: 1, adapter: memory_adapter)
+
+    counter = 0
+
+    10.times do
+      throttle.throttled do
+        counter += 1
+      end
+    end
+
+    assert_equal 1, counter
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pecorino
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors:
 - Julik Tarkhanov
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-03-13 00:00:00.000000000 Z
+date: 2025-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -24,138 +23,6 @@ dependencies:
     - - ">="
       - !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: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  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: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: standard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: magic_frozen_string_literal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest-fail-fast
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: redis
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6'
 description: Pecorino allows you to define throttles and rate meters for your metered
   resources, all through your standard DB
 email:
@@ -167,12 +34,15 @@ files:
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".standard.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- gemfiles/Gemfile_ruby27_rails7
+- gemfiles/Gemfile_ruby30_rails8
 - lib/pecorino.rb
 - lib/pecorino/adapters/base_adapter.rb
 - lib/pecorino/adapters/memory_adapter.rb
@@ -189,6 +59,19 @@ files:
 - lib/pecorino/throttle.rb
 - lib/pecorino/version.rb
 - pecorino.gemspec
+- rbi/pecorino.rbi
+- rbi/pecorino.rbs
+- test/adapters/adapter_test_methods.rb
+- test/adapters/memory_adapter_test.rb
+- test/adapters/postgres_adapter_test.rb
+- test/adapters/redis_adapter_test.rb
+- test/adapters/sqlite_adapter_test.rb
+- test/block_test.rb
+- test/cached_throttle_test.rb
+- test/leaky_bucket_test.rb
+- test/pecorino_test.rb
+- test/test_helper.rb
+- test/throttle_test.rb
 homepage: https://github.com/cheddar-me/pecorino
 licenses:
 - MIT
@@ -196,7 +79,6 @@ 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
@@ -211,8 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Database-based rate limiter using leaky buckets
 test_files: []