pecorino 0.7.2 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df8db59f2303035498ca51c54787f664fbc000148965e3782e188e26b90fea31
-  data.tar.gz: 7e67b40c92846045b0e38c8e706622d6114e307b49a8efaaec287db144734fdf
+  metadata.gz: 392d3fe294cb751ad452716ef2b569f48f536a57464bdac39379042c29aa8242
+  data.tar.gz: 36309ce687caa5e2d32bf5e5cc7c862e264a7065cf5f211062e9ae7f51118ced
 SHA512:
-  metadata.gz: 6906f549004f30b57bbf9c0ca9d2a36ba1183acf0aec863563786d9118d8f0a1094d0dc2b6eddcdeb7929be7af1f017df0063a5073a798c74cd2337888a4a3e0
-  data.tar.gz: d16cc4946a3205488afe0ab00cabc6f8a482e59751468513bec02fa0685ec77676db58b5bcb9d92d7d2fb7631e0a39fe823cfe2ecade824a0e241e45a37510fd
+  metadata.gz: 14b6cadec3609d946d786330e5c912e2ae57054ba6f740d4a0dd4b82bc4660417df2bd71e8ac97fa44990b47f20f60540d82a2299c5a176da4b8c191752f46ba
+  data.tar.gz: 5059d7a546df2a1a6822a70ed73290165f7506ba6f36f41daf3779cad158781768c004aa5bd063f24452c15dcb6d5889efd16362b3e79ef51e2f88bbcaffc3e8

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown - README.md CHANGELOG.md LICENSE.txt

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.7.4
+
+- Ensure deprecated ActiveRecord::Base.connection is replaced with ActiveRecord::Base.connection_pool.with_connection. This prevents permanent connection checkout
+
+## 0.7.3
+
+- Fix a number of YARD issues and generate both .rbi and .rbs typedefs
+
 ## 0.7.2
 
 - Set up a workable test harness for testing on both Rails 8 (Ruby 3.x) and Rails 7 (Ruby 2.x)

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+ruby ">= 3.0"
+gemspec
+
+gem "pg"
+gem "sqlite3"
+gem "activesupport", ">= 8"
+gem "rake", "~> 13.0"
+gem "minitest", "~> 5.0"
+gem "redis", "~> 5", "< 6"
+gem "yard"
+gem "standard"
+gem "sord"
+gem "redcarpet"

data/README.md

@@ -31,7 +31,7 @@ Once the installation is done you can use Pecorino to start defining your thrott
 We call this pattern **prefix usage** - apply throttle before allowing the action to proceed. This is more secure than registering an action after it has taken place.
 
 ```ruby
-throttle = Pecorino::Throttle.new(key: "password-attempts-#{request.ip}", over_time: 1.minute, capacity: 5, block_for: 30.minutes)
+throttle = Pecorino::Throttle.new(key: "password-attempts-#{the_request.ip}", over_time: 1.minute, capacity: 5, block_for: 30.minutes)
 throttle.request!
 ```
 In a Rails controller you can then rescue from this exception to render the appropriate response:
@@ -119,11 +119,11 @@ class WalletController < ApplicationController
   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
+    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
 ```
@@ -189,8 +189,10 @@ The Pecorino buckets and blocks are stateful. If you are not running tests with
 ```ruby
 setup do
   # Delete all transient records
-  ActiveRecord::Base.connection.execute("TRUNCATE TABLE pecorino_blocks")
-  ActiveRecord::Base.connection.execute("TRUNCATE TABLE pecorino_leaky_buckets")
+  ActiveRecord::Base.connection_pool.with_connection do |connection|
+    connection.execute("TRUNCATE TABLE pecorino_blocks")
+    connection.execute("TRUNCATE TABLE pecorino_leaky_buckets")
+  end
 end
 ```
 
@@ -201,7 +203,7 @@ If you are using Redis, you may want to ensure it gets truncated/reset for every
 If a throttle is triggered, Pecorino sets a "block" record for that throttle key. Any request to that throttle will fail until the block is lifted. If you are getting hammered by requests which are getting throttled, it might be a good idea to install a caching layer which will respond with a "rate limit exceeded" error even before hitting your database - until the moment when the block would be lifted. You can use any [ActiveSupport::Cache::Store](https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html) to store your blocks. If you have a fast Rails cache configured, create a wrapped throttle:
 
 ```ruby
-throttle = Pecorino::Throttle.new(key: "ip-#{request.ip}", capacity: 10, over_time: 2.seconds, block_for: 2.minutes)
+throttle = Pecorino::Throttle.new(key: "ip-#{the_request.ip}", capacity: 10, over_time: 2.seconds, block_for: 2.minutes)
 cached_throttle = Pecorino::CachedThrottle.new(Rails.cache, throttle)
 cached_throttle.request!
 ```
@@ -214,7 +216,7 @@ config.pecorino_throttle_cache = ActiveSupport::Cache::MemoryStore.new
 
 # in your controller
 
-throttle = Pecorino::Throttle.new(key: "ip-#{request.ip}", capacity: 10, over_time: 2.seconds, block_for: 2.minutes)
+throttle = Pecorino::Throttle.new(key: "ip-#{the_request.ip}", capacity: 10, over_time: 2.seconds, block_for: 2.minutes)
 cached_throttle = Pecorino::CachedThrottle.new(Rails.application.config.pecorino_throttle_cache, throttle)
 cached_throttle.request!
 ```
@@ -224,21 +226,24 @@ cached_throttle.request!
 Throttles and leaky buckets are transient resources. If you are using Postgres replication, it might be prudent to set the Pecorino tables to `UNLOGGED` which will exclude them from replication - and save you bandwidth and storage on your RR. To do so, add the following statements to your migration:
 
 ```ruby
-ActiveRecord::Base.connection.execute("ALTER TABLE pecorino_leaky_buckets SET UNLOGGED")
-ActiveRecord::Base.connection.execute("ALTER TABLE pecorino_blocks SET UNLOGGED")
+ActiveRecord::Base.connection_pool.with_connection do |connection|
+  connection.execute("ALTER TABLE pecorino_leaky_buckets SET UNLOGGED")
+  connection.execute("ALTER TABLE pecorino_blocks SET UNLOGGED")
+end
 ```
 
 ## Development
 
-After checking out the repo, set the Gemfile appropriate to your Ruby version and run Rake for tests, lint etc.
-Note that it is important to use the appropriate Gemfile per Ruby version and Rails version you want to test with. Due to some dependency shenanigans it is currently not very easy to have a single Gemfile.
+After checking out the repo, run `bundle install` and then do the thing you need to do.
+
+**Note:** CI runs other Gemfiles, because we can't test all Ruby versions and Rails versions just by swapping Gemfiles. If you need to debug something with a particular Ruby and Rails version, do this:
 
 ```bash
-$ rbenv local 2.7.7 && export BUNDLE_GEMFILE=gemfiles/Gemfile_ruby27_rails7 && bundle install
+$ bundle rbenv local 2.7.7 && export BUNDLE_GEMFILE=gemfiles/Gemfile_ruby27_rails7 && bundle install
 $ bundle exec rake
 ```
 
-Then proceed to develop as normal. CI will run both the oldest supported dependencies and newest supported dependencies. 
+Then proceed as normal. Make sure to unset `BUNDLE_GEMFILE` when you are done. CI will run both the oldest supported dependencies and newest supported dependencies. 
 
 ## Contributing
 

data/Rakefile

@@ -20,6 +20,7 @@ end
 
 task :generate_typedefs do
   `bundle exec sord rbi/pecorino.rbi`
+  `bundle exec sord rbi/pecorino.rbs`
 end
 
 task default: [:test, :standard, :generate_typedefs]

data/lib/pecorino/adapters/postgres_adapter.rb

@@ -30,7 +30,7 @@ class Pecorino::Adapters::PostgresAdapter
 
     # 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 = @model_class.connection.uncached { @model_class.connection.select_value(sql) } || 0.0
+    current_level = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_value(sql) } } || 0.0
     [current_level, capacity - current_level.abs < 0.01]
   end
 
@@ -83,7 +83,7 @@ class Pecorino::Adapters::PostgresAdapter
     # query as a repeat (since we use "select_one" 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
-    upserted = @model_class.connection.uncached { @model_class.connection.select_one(sql) }
+    upserted = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_one(sql) } }
     capped_level_after_fillup, at_capacity = upserted.fetch("level"), upserted.fetch("at_capacity")
     [capped_level_after_fillup, at_capacity]
   end
@@ -141,7 +141,7 @@ class Pecorino::Adapters::PostgresAdapter
         level AS level_after
     SQL
 
-    upserted = @model_class.connection.uncached { @model_class.connection.select_one(sql) }
+    upserted = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_one(sql) } }
     level_after = upserted.fetch("level_after")
     level_before = upserted.fetch("level_before")
     [level_after, level_after >= capacity, level_after != level_before]
@@ -159,19 +159,21 @@ class Pecorino::Adapters::PostgresAdapter
         blocked_until = GREATEST(EXCLUDED.blocked_until, t.blocked_until)
       RETURNING blocked_until
     SQL
-    @model_class.connection.uncached { @model_class.connection.select_value(block_set_query) }
+    @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_value(block_set_query) } }
   end
 
   def blocked_until(key:)
     block_check_query = @model_class.sanitize_sql_array([<<~SQL, key])
       SELECT blocked_until FROM pecorino_blocks WHERE key = ? AND blocked_until >= clock_timestamp() LIMIT 1
     SQL
-    @model_class.connection.uncached { @model_class.connection.select_value(block_check_query) }
+    @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_value(block_check_query) } }
   end
 
   def prune
-    @model_class.connection.execute("DELETE FROM pecorino_blocks WHERE blocked_until < NOW()")
-    @model_class.connection.execute("DELETE FROM pecorino_leaky_buckets WHERE may_be_deleted_after < NOW()")
+    @model_class.connection_pool.with_connection do |connection|
+      connection.execute("DELETE FROM pecorino_blocks WHERE blocked_until < NOW()")
+      connection.execute("DELETE FROM pecorino_leaky_buckets WHERE may_be_deleted_after < NOW()")
+    end
   end
 
   def create_tables(active_record_schema)

data/lib/pecorino/adapters/sqlite_adapter.rb

@@ -37,7 +37,7 @@ class Pecorino::Adapters::SqliteAdapter
 
     # 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 = @model_class.connection.uncached { @model_class.connection.select_value(sql) } || 0.0
+    current_level = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_value(sql) } } || 0.0
     [current_level, capacity - current_level.abs < 0.01]
   end
 
@@ -91,7 +91,7 @@ class Pecorino::Adapters::SqliteAdapter
     # query as a repeat (since we use "select_one" 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
-    upserted = @model_class.connection.uncached { @model_class.connection.select_one(sql) }
+    upserted = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_one(sql) } }
     capped_level_after_fillup, one_if_did_overflow = upserted.fetch("level"), upserted.fetch("did_overflow")
     [capped_level_after_fillup, one_if_did_overflow == 1]
   end
@@ -130,7 +130,7 @@ class Pecorino::Adapters::SqliteAdapter
       -- so that it can't be deleted between our INSERT and our UPDATE
         may_be_deleted_after = EXCLUDED.may_be_deleted_after
     SQL
-    @model_class.connection.execute(insert_sql)
+    @model_class.connection_pool.with_connection { |connection| connection.execute(insert_sql) }
 
     sql = @model_class.sanitize_sql_array([<<~SQL, query_params])
       -- With SQLite MATERIALIZED has to be used so that level_post is calculated before the UPDATE takes effect
@@ -156,7 +156,7 @@ class Pecorino::Adapters::SqliteAdapter
         level AS level_after
     SQL
 
-    upserted = @model_class.connection.uncached { @model_class.connection.select_one(sql) }
+    upserted = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_one(sql) } }
     level_after = upserted.fetch("level_after")
     level_before = upserted.fetch("level_before")
     [level_after, level_after >= capacity, level_after != level_before]
@@ -174,7 +174,7 @@ class Pecorino::Adapters::SqliteAdapter
         blocked_until = MAX(EXCLUDED.blocked_until, t.blocked_until)
       RETURNING blocked_until;
     SQL
-    blocked_until_s = @model_class.connection.uncached { @model_class.connection.select_value(block_set_query) }
+    blocked_until_s = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_value(block_set_query) } }
     Time.at(blocked_until_s)
   end
 
@@ -188,14 +188,16 @@ class Pecorino::Adapters::SqliteAdapter
       WHERE
         key = :key AND blocked_until >= :now_s LIMIT 1
     SQL
-    blocked_until_s = @model_class.connection.uncached { @model_class.connection.select_value(block_check_query) }
+    blocked_until_s = @model_class.connection_pool.with_connection { |connection| connection.uncached { connection.select_value(block_check_query) } }
     blocked_until_s && Time.at(blocked_until_s)
   end
 
   def prune
     now_s = Time.now.to_f
-    @model_class.connection.execute("DELETE FROM pecorino_blocks WHERE blocked_until < ?", now_s)
-    @model_class.connection.execute("DELETE FROM pecorino_leaky_buckets WHERE may_be_deleted_after < ?", now_s)
+    @model_class.connection_pool.with_connection do |connection|
+      connection.execute("DELETE FROM pecorino_blocks WHERE blocked_until < ?", now_s)
+      connection.execute("DELETE FROM pecorino_leaky_buckets WHERE may_be_deleted_after < ?", now_s)
+    end
   end
 
   def create_tables(active_record_schema)

data/lib/pecorino/cached_throttle.rb

@@ -15,6 +15,10 @@ class Pecorino::CachedThrottle
     @throttle = throttle
   end
 
+  # Increments the cached throttle by the given number of tokens. If there is currently a known cached block on that throttle
+  # an exception will be raised immediately instead of querying the actual throttle data. Otherwise the call gets forwarded
+  # to the underlying throttle.
+  #
   # @see Pecorino::Throttle#request!
   def request!(n = 1)
     blocked_state = read_cached_blocked_state
@@ -28,9 +32,9 @@ class Pecorino::CachedThrottle
     end
   end
 
-  # Returns cached `state` for the throttle if there is a currently active block for that throttle in the cache. Otherwise forwards to underlying throttle.
+  # Returns the cached `state` for the throttle if there is a currently active block for that throttle in the cache. Otherwise forwards to underlying throttle.
   #
-  # @see Pecorino::Throttle#request
+  # @see Pecorino::Throttle#request!
   def request(n = 1)
     blocked_state = read_cached_blocked_state
     return blocked_state if blocked_state&.blocked?

data/lib/pecorino/throttle.rb

@@ -91,7 +91,7 @@ class Pecorino::Throttle
 
   # The key for that throttle. Each key defines a unique throttle based on either a given name or
   # discriminators. If there is a component you want to key your throttle by, include it in the
-  # `key` keyword argument to the constructor, like `"t-ip-#{request.ip}"`
+  # `key` keyword argument to the constructor, like `"t-ip-#{your_rails_request.ip}"`
   #
   # @return [String]
   attr_reader :key
@@ -100,8 +100,8 @@ class Pecorino::Throttle
   # @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 adapter[Pecorino::Adapters::BaseAdapter] a compatible adapter
-  # @param leaky_bucket_options Options for `Pecorino::LeakyBucket.new`
-  # @see PecorinoLeakyBucket.new
+  # @param leaky_bucket_options Options for {Pecorino::LeakyBucket.new}
+  # @see Pecorino::LeakyBucket.new
   def initialize(key:, block_for: nil, adapter: Pecorino.adapter, **leaky_bucket_options)
     @adapter = adapter
     leaky_bucket_options.delete(:adapter)
@@ -129,16 +129,16 @@ class Pecorino::Throttle
   # 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:
   #
+  # If the method call returns it means that the request is not getting throttled.
+  #
   # @example
   #   begin
-  #      t.request!
-  #      Note.create!(note_params)
+  #     t.request!
+  #     Note.create!(note_params)
   #   rescue Pecorino::Throttle::Throttled => e
-  #      [429, {"Retry-After" => e.retry_after.to_s}, []]
+  #     [429, {"Retry-After" => e.retry_after.to_s}, []]
   #   end
-  #
-  # If the method call succeeds it means that the request is not getting throttled.
-  #
+  # @param n [Numeric] how many tokens to place into the bucket or remove from the bucket. May be fractional or negative.
   # @return [State] the state of the throttle after filling up the leaky bucket / trying to pass the block
   def request!(n = 1)
     request(n).tap do |state_after|
@@ -156,8 +156,8 @@ class Pecorino::Throttle
   #     Entry.create!(entry_params)
   #     t.request
   #   end
-  #
-  # @return [State] the state of the throttle after filling up the leaky bucket / trying to pass the block
+  # @param n [Numeric] how many tokens to place into the bucket or remove from the bucket. May be fractional or negative.
+  # @return [State] the state of the throttle after the attempt to fill up the leaky bucket
   def request(n = 1)
     existing_blocked_until = Pecorino::Block.blocked_until(key: @key, adapter: @adapter)
     return State.new(existing_blocked_until.utc) if existing_blocked_until
@@ -181,6 +181,7 @@ class Pecorino::Throttle
   # @example
   #   t.throttled { Slack.alert("Things are going wrong") }
   #
+  # @param blk The block to run. Will only run if the throttle accepts the call.
   # @return [Object] the return value of the block if the block gets executed, or `nil` if the call got throttled
   def throttled(&blk)
     return if request(1).blocked?

data/lib/pecorino/version.rb

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

data/lib/pecorino.rb

@@ -60,12 +60,12 @@ module Pecorino
 
   # Returns the database implementation for setting the values atomically. Since the implementation
   # differs per database, this method will return a different adapter depending on which database is
-  # being used
+  # being used.
   #
-  # @param adapter[Pecorino::Adapters::BaseAdapter]
+  # @return [Pecorino::Adapters::BaseAdapter]
   def self.default_adapter_from_main_database
     model_class = ActiveRecord::Base
-    adapter_name = model_class.connection.adapter_name
+    adapter_name = model_class.connection_pool.with_connection(&:adapter_name)
     case adapter_name
     when /postgres/i
       Pecorino::Adapters::PostgresAdapter.new(model_class)

data/rbi/pecorino.rbi

@@ -1,6 +1,6 @@
 # typed: strong
 module Pecorino
-  VERSION = T.let("0.7.1", T.untyped)
+  VERSION = T.let("0.7.3", T.untyped)
 
   # Deletes stale leaky buckets and blocks which have expired. Run this method regularly to
   # avoid accumulating too many unused rows in your tables.
@@ -36,18 +36,15 @@ module Pecorino
   sig { returns(Pecorino::Adapters::BaseAdapter) }
   def self.adapter; end
 
-  # sord omit - no YARD return type given, using untyped
   # Returns the database implementation for setting the values atomically. Since the implementation
   # differs per database, this method will return a different adapter depending on which database is
-  # being used
-  # 
-  # _@param_ `adapter`
-  sig { returns(T.untyped) }
+  # being used.
+  sig { returns(Pecorino::Adapters::BaseAdapter) }
   def self.default_adapter_from_main_database; end
 
   module Adapters
     # An adapter allows Pecorino throttles, leaky buckets and other
-    # resources to interfact to a data storage backend - a database, usually.
+    # resources to interface with a data storage backend - a database, usually.
     class BaseAdapter
       # Returns the state of a leaky bucket. The state should be a tuple of two
       # values: the current level (Float) and whether the bucket is now at capacity (Boolean)
@@ -503,9 +500,9 @@ module Pecorino
     # 
     # _@param_ `adapter` — a compatible adapter
     # 
-    # _@param_ `leaky_bucket_options` — Options for `Pecorino::LeakyBucket.new`
+    # _@param_ `leaky_bucket_options` — Options for {Pecorino::LeakyBucket.new}
     # 
-    # _@see_ `PecorinoLeakyBucket.new`
+    # _@see_ `Pecorino::LeakyBucket.new`
     sig do
       params(
         key: String,
@@ -526,7 +523,6 @@ module Pecorino
     sig { params(n_tokens: Float).returns(T::Boolean) }
     def able_to_accept?(n_tokens = 1); end
 
-    # sord omit - no YARD type given for "n", using untyped
     # Register that a request is being performed. Will raise Throttled
     # if there is a block in place for that throttle, or if the bucket cannot accept
     # this fillup and the block has just been installed as a result of this particular request.
@@ -534,28 +530,31 @@ module Pecorino
     # 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:
     # 
-    # If the method call succeeds it means that the request is not getting throttled.
+    # If the method call returns it means that the request is not getting throttled.
+    # 
+    # _@param_ `n` — how many tokens to place into the bucket or remove from the bucket. May be fractional or negative.
     # 
     # _@return_ — the state of the throttle after filling up the leaky bucket / trying to pass the block
     # 
     # ```ruby
     # begin
-    #    t.request!
-    #    Note.create!(note_params)
+    #   t.request!
+    #   Note.create!(note_params)
     # rescue Pecorino::Throttle::Throttled => e
-    #    [429, {"Retry-After" => e.retry_after.to_s}, []]
+    #   [429, {"Retry-After" => e.retry_after.to_s}, []]
     # end
     # ```
-    sig { params(n: T.untyped).returns(State) }
+    sig { params(n: Numeric).returns(State) }
     def request!(n = 1); end
 
-    # sord omit - no YARD type given for "n", using untyped
     # 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.
     # 
-    # _@return_ — the state of the throttle after filling up the leaky bucket / trying to pass the block
+    # _@param_ `n` — how many tokens to place into the bucket or remove from the bucket. May be fractional or negative.
+    # 
+    # _@return_ — the state of the throttle after the attempt to fill up the leaky bucket
     # 
     # ```ruby
     # if t.able_to_accept?
@@ -563,7 +562,7 @@ module Pecorino
     #   t.request
     # end
     # ```
-    sig { params(n: T.untyped).returns(State) }
+    sig { params(n: Numeric).returns(State) }
     def request(n = 1); end
 
     # Fillup the throttle with 1 request and then perform the passed block. This is useful to perform actions which should
@@ -571,6 +570,8 @@ module Pecorino
     # the passed block will be executed. If the throttle is in the blocked state or if the call puts the throttle in
     # the blocked state the block will not be executed
     # 
+    # _@param_ `blk` — The block to run. Will only run if the throttle accepts the call.
+    # 
     # _@return_ — the return value of the block if the block gets executed, or `nil` if the call got throttled
     # 
     # ```ruby
@@ -581,7 +582,7 @@ module Pecorino
 
     # The key for that throttle. Each key defines a unique throttle based on either a given name or
     # discriminators. If there is a component you want to key your throttle by, include it in the
-    # `key` keyword argument to the constructor, like `"t-ip-#{request.ip}"`
+    # `key` keyword argument to the constructor, like `"t-ip-#{your_rails_request.ip}"`
     sig { returns(String) }
     attr_reader :key
 
@@ -835,6 +836,9 @@ module Pecorino
 
     # sord omit - no YARD type given for "n", using untyped
     # sord omit - no YARD return type given, using untyped
+    # Increments the cached throttle by the given number of tokens. If there is currently a known cached block on that throttle
+    # an exception will be raised immediately instead of querying the actual throttle data. Otherwise the call gets forwarded
+    # to the underlying throttle.
     # 
     # _@see_ `Pecorino::Throttle#request!`
     sig { params(n: T.untyped).returns(T.untyped) }
@@ -842,9 +846,9 @@ module Pecorino
 
     # sord omit - no YARD type given for "n", using untyped
     # sord omit - no YARD return type given, using untyped
-    # Returns cached `state` for the throttle if there is a currently active block for that throttle in the cache. Otherwise forwards to underlying throttle.
+    # Returns the cached `state` for the throttle if there is a currently active block for that throttle in the cache. Otherwise forwards to underlying throttle.
     # 
-    # _@see_ `Pecorino::Throttle#request`
+    # _@see_ `Pecorino::Throttle#request!`
     sig { params(n: T.untyped).returns(T.untyped) }
     def request(n = 1); end