pecorino 0.7.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df8db59f2303035498ca51c54787f664fbc000148965e3782e188e26b90fea31
-  data.tar.gz: 7e67b40c92846045b0e38c8e706622d6114e307b49a8efaaec287db144734fdf
+  metadata.gz: c0e0c8fa1a6bc734dc645b5b021264eda84bcadd1bec8da65c533a33cd243fb6
+  data.tar.gz: c6c053d8ed02f8e180786d4614c607087ca76b016b8acac35b35a3b3cb544391
 SHA512:
-  metadata.gz: 6906f549004f30b57bbf9c0ca9d2a36ba1183acf0aec863563786d9118d8f0a1094d0dc2b6eddcdeb7929be7af1f017df0063a5073a798c74cd2337888a4a3e0
-  data.tar.gz: d16cc4946a3205488afe0ab00cabc6f8a482e59751468513bec02fa0685ec77676db58b5bcb9d92d7d2fb7631e0a39fe823cfe2ecade824a0e241e45a37510fd
+  metadata.gz: 02207b3f3d52aa635a960c3914768237a25da4b4cdd7a5ad5da222adf44e738ac987f5182392d0617c60848c745fb0cc5225e2e2392dff50b6e83f58b703d191
+  data.tar.gz: 350d04b9e366d229d87146465574632a00e5e0c88eda7cbc540b494d8ab1d3520d87092f5ae6a6b11f0dd323cc7fd15436728c9b6210fe2264be384b0e9505b4

data/.yardopts

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

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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
 ```
@@ -201,7 +201,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 +214,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!
 ```
@@ -230,15 +230,16 @@ ActiveRecord::Base.connection.execute("ALTER TABLE pecorino_blocks SET UNLOGGED"
 
 ## 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/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.3"
 end

data/lib/pecorino.rb

@@ -60,9 +60,9 @@ 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

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
 

data/rbi/pecorino.rbs

@@ -0,0 +1,791 @@
+module Pecorino
+  VERSION: untyped
+
+  # 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!: () -> untyped
+
+  # sord warn - ActiveRecord::SchemaMigration wasn't able to be resolved to a constant in this project
+  # Creates the tables and indexes needed for Pecorino. Call this from your migrations like so:
+  # 
+  #     class CreatePecorinoTables < ActiveRecord::Migration[7.0]
+  #       def change
+  #         Pecorino.create_tables(self)
+  #       end
+  #     end
+  # 
+  # _@param_ `active_record_schema` — the migration through which we will create the tables
+  # 
+  # _@return_ — void
+  def self.create_tables: (ActiveRecord::SchemaMigration active_record_schema) -> untyped
+
+  # Allows assignment of an adapter for storing throttles. Normally this would be a subclass of `Pecorino::Adapters::BaseAdapter`, but
+  # you can assign anything you like. Set this in an initializer. By default Pecorino will use the adapter configured from your main
+  # database, but you can also create a separate database for it - or use Redis or memory storage.
+  # 
+  # _@param_ `adapter`
+  def self.adapter=: (Pecorino::Adapters::BaseAdapter adapter) -> Pecorino::Adapters::BaseAdapter
+
+  # Returns the currently configured adapter, or the default adapter from the main database
+  def self.adapter: () -> Pecorino::Adapters::BaseAdapter
+
+  # 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.
+  def self.default_adapter_from_main_database: () -> Pecorino::Adapters::BaseAdapter
+
+  module Adapters
+    # An adapter allows Pecorino throttles, leaky buckets and other
+    # 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)
+      # 
+      # _@param_ `key` — the key of the leaky bucket
+      # 
+      # _@param_ `capacity` — the capacity of the leaky bucket to limit to
+      # 
+      # _@param_ `leak_rate` — how many tokens leak out of the bucket per second
+      def state: (key: String, capacity: Float, leak_rate: Float) -> ::Array[untyped]
+
+      # Adds tokens to the leaky bucket. The return value is a tuple of two
+      # values: the current level (Float) and whether the bucket is now at capacity (Boolean)
+      # 
+      # _@param_ `key` — the key of the leaky bucket
+      # 
+      # _@param_ `capacity` — the capacity of the leaky bucket to limit to
+      # 
+      # _@param_ `leak_rate` — how many tokens leak out of the bucket per second
+      # 
+      # _@param_ `n_tokens` — how many tokens to add
+      def add_tokens: (
+                        key: String,
+                        capacity: Float,
+                        leak_rate: Float,
+                        n_tokens: Float
+                      ) -> ::Array[untyped]
+
+      # Adds tokens to the leaky bucket conditionally. If there is capacity, the tokens will
+      # be added. If there isn't - the fillup will be rejected. The return value is a triplet of
+      # the current level (Float), whether the bucket is now at capacity (Boolean)
+      # and whether the fillup was accepted (Boolean)
+      # 
+      # _@param_ `key` — the key of the leaky bucket
+      # 
+      # _@param_ `capacity` — the capacity of the leaky bucket to limit to
+      # 
+      # _@param_ `leak_rate` — how many tokens leak out of the bucket per second
+      # 
+      # _@param_ `n_tokens` — how many tokens to add
+      def add_tokens_conditionally: (
+                                      key: String,
+                                      capacity: Float,
+                                      leak_rate: Float,
+                                      n_tokens: Float
+                                    ) -> ::Array[untyped]
+
+      # sord duck - #to_f looks like a duck type, replacing with untyped
+      # sord warn - "Active Support Duration" does not appear to be a type
+      # sord omit - no YARD return type given, using untyped
+      # Sets a timed block for the given key - this is used when a throttle fires. The return value
+      # is not defined - the call should always succeed.
+      # 
+      # _@param_ `key` — the key of the block
+      # 
+      # _@param_ `block_for` — the duration of the block, in seconds
+      def set_block: (key: String, block_for: (untyped | SORD_ERROR_ActiveSupportDuration)) -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      # Returns the time until which a block for a given key is in effect. If there is no block in
+      # effect, the method should return `nil`. The return value is either a `Time` or `nil`
+      # 
+      # _@param_ `key` — the key of the block
+      def blocked_until: (key: String) -> untyped
+
+      # Deletes leaky buckets which have an expiry value prior to now and throttle blocks which have
+      # now lapsed
+      def prune: () -> void
+
+      # sord omit - no YARD type given for "active_record_schema", using untyped
+      # sord omit - no YARD return type given, using untyped
+      # Creates the database tables for Pecorino to operate, or initializes other
+      # schema-like resources the adapter needs to operate
+      def create_tables: (untyped active_record_schema) -> untyped
+    end
+
+    # An adapter for storing Pecorino leaky buckets and blocks in Redis. It uses Lua
+    # to enforce atomicity for leaky bucket operations
+    class RedisAdapter < Pecorino::Adapters::BaseAdapter
+      ADD_TOKENS_SCRIPT: untyped
+
+      # sord omit - no YARD type given for "redis_connection_or_connection_pool", using untyped
+      # sord omit - no YARD type given for "key_prefix:", using untyped
+      def initialize: (untyped redis_connection_or_connection_pool, ?key_prefix: untyped) -> void
+
+      # 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)
+      def state: (key: String, capacity: Float, leak_rate: Float) -> ::Array[untyped]
+
+      # Adds tokens to the leaky bucket. The return value is a tuple of two
+      # values: the current level (Float) and whether the bucket is now at capacity (Boolean)
+      def add_tokens: (
+                        key: String,
+                        capacity: Float,
+                        leak_rate: Float,
+                        n_tokens: Float
+                      ) -> ::Array[untyped]
+
+      # Adds tokens to the leaky bucket conditionally. If there is capacity, the tokens will
+      # be added. If there isn't - the fillup will be rejected. The return value is a triplet of
+      # the current level (Float), whether the bucket is now at capacity (Boolean)
+      # and whether the fillup was accepted (Boolean)
+      def add_tokens_conditionally: (
+                                      key: String,
+                                      capacity: Float,
+                                      leak_rate: Float,
+                                      n_tokens: Float
+                                    ) -> ::Array[untyped]
+
+      # sord duck - #to_f looks like a duck type, replacing with untyped
+      # sord warn - "Active Support Duration" does not appear to be a type
+      # sord omit - no YARD return type given, using untyped
+      # Sets a timed block for the given key - this is used when a throttle fires. The return value
+      # is not defined - the call should always succeed.
+      def set_block: (key: String, block_for: (untyped | SORD_ERROR_ActiveSupportDuration)) -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      # Returns the time until which a block for a given key is in effect. If there is no block in
+      # effect, the method should return `nil`. The return value is either a `Time` or `nil`
+      def blocked_until: (key: String) -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      def with_redis: () -> untyped
+
+      class RedisScript
+        # sord omit - no YARD type given for "script_filename", using untyped
+        def initialize: (untyped script_filename) -> void
+
+        # sord omit - no YARD type given for "redis", using untyped
+        # sord omit - no YARD type given for "keys", using untyped
+        # sord omit - no YARD type given for "argv", using untyped
+        # sord omit - no YARD return type given, using untyped
+        def load_and_eval: (untyped redis, untyped keys, untyped argv) -> untyped
+      end
+    end
+
+    # A memory store for leaky buckets and blocks
+    class MemoryAdapter
+      def initialize: () -> void
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      # 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)
+      def state: (key: untyped, capacity: untyped, leak_rate: untyped) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD type given for "n_tokens:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      # Adds tokens to the leaky bucket. The return value is a tuple of two
+      # values: the current level (Float) and whether the bucket is now at capacity (Boolean)
+      def add_tokens: (
+                        key: untyped,
+                        capacity: untyped,
+                        leak_rate: untyped,
+                        n_tokens: untyped
+                      ) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD type given for "n_tokens:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      # Adds tokens to the leaky bucket conditionally. If there is capacity, the tokens will
+      # be added. If there isn't - the fillup will be rejected. The return value is a triplet of
+      # the current level (Float), whether the bucket is now at capacity (Boolean)
+      # and whether the fillup was accepted (Boolean)
+      def add_tokens_conditionally: (
+                                      key: untyped,
+                                      capacity: untyped,
+                                      leak_rate: untyped,
+                                      n_tokens: untyped
+                                    ) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "block_for:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      # Sets a timed block for the given key - this is used when a throttle fires. The return value
+      # is not defined - the call should always succeed.
+      def set_block: (key: untyped, block_for: untyped) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      # Returns the time until which a block for a given key is in effect. If there is no block in
+      # effect, the method should return `nil`. The return value is either a `Time` or `nil`
+      def blocked_until: (key: untyped) -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      # Deletes leaky buckets which have an expiry value prior to now and throttle blocks which have
+      # now lapsed
+      def prune: () -> untyped
+
+      # sord omit - no YARD type given for "active_record_schema", using untyped
+      # sord omit - no YARD return type given, using untyped
+      # No-op
+      def create_tables: (untyped active_record_schema) -> untyped
+
+      # sord omit - no YARD type given for "key", using untyped
+      # sord omit - no YARD type given for "capacity", using untyped
+      # sord omit - no YARD type given for "leak_rate", using untyped
+      # sord omit - no YARD type given for "n_tokens", using untyped
+      # sord omit - no YARD type given for "conditionally", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def add_tokens_with_lock: (
+                                  untyped key,
+                                  untyped capacity,
+                                  untyped leak_rate,
+                                  untyped n_tokens,
+                                  untyped conditionally
+                                ) -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      def get_mono_time: () -> untyped
+
+      # sord omit - no YARD type given for "min", using untyped
+      # sord omit - no YARD type given for "value", using untyped
+      # sord omit - no YARD type given for "max", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def clamp: (untyped min, untyped value, untyped max) -> untyped
+
+      class KeyedLock
+        def initialize: () -> void
+
+        # sord omit - no YARD type given for "key", using untyped
+        # sord omit - no YARD return type given, using untyped
+        def lock: (untyped key) -> untyped
+
+        # sord omit - no YARD type given for "key", using untyped
+        # sord omit - no YARD return type given, using untyped
+        def unlock: (untyped key) -> untyped
+
+        # sord omit - no YARD type given for "key", using untyped
+        # sord omit - no YARD return type given, using untyped
+        def with: (untyped key) -> untyped
+      end
+    end
+
+    class SqliteAdapter
+      # sord omit - no YARD type given for "model_class", using untyped
+      def initialize: (untyped model_class) -> void
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def state: (key: untyped, capacity: untyped, leak_rate: untyped) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD type given for "n_tokens:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def add_tokens: (
+                        key: untyped,
+                        capacity: untyped,
+                        leak_rate: untyped,
+                        n_tokens: untyped
+                      ) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD type given for "n_tokens:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def add_tokens_conditionally: (
+                                      key: untyped,
+                                      capacity: untyped,
+                                      leak_rate: untyped,
+                                      n_tokens: untyped
+                                    ) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "block_for:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def set_block: (key: untyped, block_for: untyped) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def blocked_until: (key: untyped) -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      def prune: () -> untyped
+
+      # sord omit - no YARD type given for "active_record_schema", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def create_tables: (untyped active_record_schema) -> untyped
+    end
+
+    class PostgresAdapter
+      # sord omit - no YARD type given for "model_class", using untyped
+      def initialize: (untyped model_class) -> void
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def state: (key: untyped, capacity: untyped, leak_rate: untyped) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD type given for "n_tokens:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def add_tokens: (
+                        key: untyped,
+                        capacity: untyped,
+                        leak_rate: untyped,
+                        n_tokens: untyped
+                      ) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "capacity:", using untyped
+      # sord omit - no YARD type given for "leak_rate:", using untyped
+      # sord omit - no YARD type given for "n_tokens:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def add_tokens_conditionally: (
+                                      key: untyped,
+                                      capacity: untyped,
+                                      leak_rate: untyped,
+                                      n_tokens: untyped
+                                    ) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD type given for "block_for:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def set_block: (key: untyped, block_for: untyped) -> untyped
+
+      # sord omit - no YARD type given for "key:", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def blocked_until: (key: untyped) -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      def prune: () -> untyped
+
+      # sord omit - no YARD type given for "active_record_schema", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def create_tables: (untyped active_record_schema) -> untyped
+    end
+  end
+
+  # 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 Block
+    # Sets a block for the given key. The block will also be seen by the Pecorino::Throttle with the same key
+    # 
+    # _@param_ `key` — the key to set the block for
+    # 
+    # _@param_ `block_for` — the number of seconds or a time interval to block for
+    # 
+    # _@param_ `adapter` — the adapter to set the value in.
+    # 
+    # _@return_ — the time when the block will be released
+    def self.set!: (key: String, block_for: Float, ?adapter: Pecorino::Adapters::BaseAdapter) -> Time
+
+    # Returns the time until a certain block is in effect
+    # 
+    # _@param_ `key` — the key to get the expiry time for
+    # 
+    # _@param_ `adapter` — the adapter to get the value from
+    # 
+    # _@return_ — the time when the block will be released
+    def self.blocked_until: (key: String, ?adapter: Pecorino::Adapters::BaseAdapter) -> Time?
+  end
+
+  class Railtie < Rails::Railtie
+  end
+
+  # 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 Throttle
+    # _@param_ `key` — the key for both the block record and the leaky bucket
+    # 
+    # _@param_ `block_for` — 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` — a compatible adapter
+    # 
+    # _@param_ `leaky_bucket_options` — Options for {Pecorino::LeakyBucket.new}
+    # 
+    # _@see_ `Pecorino::LeakyBucket.new`
+    def initialize: (
+                      key: String,
+                      ?block_for: Numeric?,
+                      ?adapter: Pecorino::Adapters::BaseAdapter,
+                      **untyped leaky_bucket_options
+                    ) -> void
+
+    # 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!`. You may still use `able_to_accept?` to
+    # provide better UX to your users before they cause an action that would otherwise throttle.
+    # 
+    # _@param_ `n_tokens`
+    def able_to_accept?: (?Float n_tokens) -> bool
+
+    # 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.
+    # 
+    # 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.
+    # 
+    # _@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)
+    # rescue Pecorino::Throttle::Throttled => e
+    #   [429, {"Retry-After" => e.retry_after.to_s}, []]
+    # end
+    # ```
+    def request!: (?Numeric n) -> State
+
+    # 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.
+    # 
+    # _@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?
+    #   Entry.create!(entry_params)
+    #   t.request
+    # end
+    # ```
+    def request: (?Numeric n) -> State
+
+    # Fillup the throttle with 1 request and then perform the passed block. This is useful to perform actions which should
+    # be rate-limited - alerts, calls to external services and the like. If the call is allowed to proceed,
+    # 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
+    # t.throttled { Slack.alert("Things are going wrong") }
+    # ```
+    def throttled: () -> Object
+
+    # 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-#{your_rails_request.ip}"`
+    attr_reader key: String
+
+    # The state represents a snapshot of the throttle state in time
+    class State
+      # sord omit - no YARD type given for "blocked_until", using untyped
+      def initialize: (untyped blocked_until) -> void
+
+      # Tells whether this throttle still is in the blocked state.
+      # If the `blocked_until` value lies in the past, the method will
+      # return `false` - this is done so that the `State` can be cached.
+      def blocked?: () -> bool
+
+      attr_reader blocked_until: Time
+    end
+
+    # {Pecorino::Throttle} will raise this exception from `request!`. The exception can be used
+    # to do matching, for setting appropriate response headers, and for distinguishing between
+    # multiple different throttles.
+    class Throttled < StandardError
+      # sord omit - no YARD type given for "from_throttle", using untyped
+      # sord omit - no YARD type given for "state", using untyped
+      def initialize: (untyped from_throttle, untyped state) -> void
+
+      # Returns the `retry_after` value in seconds, suitable for use in an HTTP header
+      def retry_after: () -> Integer
+
+      # 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:
+      # 
+      # ```ruby
+      # begin
+      #   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
+      #   firewall.ban_ip(ip) if e.throttle == ip_addr_throttle
+      # end
+      # ```
+      attr_reader throttle: Throttle
+
+      # Returns the throttle state based on which the exception is getting raised. This can
+      # be used for caching the exception, because the state can tell when the block will be
+      # lifted. This can be used to shift the throttle verification into a faster layer of the
+      # system (like a blocklist in a firewall) or caching the state in an upstream cache. A block
+      # in Pecorino is set once and is active until expiry. If your service is under an attack
+      # and you know that the call is blocked until a certain future time, the block can be
+      # lifted up into a faster/cheaper storage destination, like Rails cache:
+      # 
+      # ```ruby
+      # begin
+      #   ip_addr_throttle.request!
+      # rescue Pecorino::Throttled => e
+      #   firewall.ban_ip(request.ip, ttl_seconds: e.state.retry_after)
+      #   render :rate_limit_exceeded
+      # end
+      # ```
+      # 
+      # ```ruby
+      # state = Rails.cache.read(ip_addr_throttle.key)
+      # return render :rate_limit_exceeded if state && state.blocked? # No need to call Pecorino for this
+      # 
+      # begin
+      #   ip_addr_throttle.request!
+      # rescue Pecorino::Throttled => e
+      #   Rails.cache.write(ip_addr_throttle.key, e.state, expires_in: (e.state.blocked_until - Time.now))
+      #   render :rate_limit_exceeded
+      # end
+      # ```
+      attr_reader state: Throttle::State
+    end
+  end
+
+  # 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 the database.
+  # 
+  # 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 LeakyBucket
+    # sord duck - #to_f looks like a duck type, replacing with untyped
+    # Creates a new LeakyBucket. The object controls 1 row in the database is
+    # specific to the bucket key.
+    # 
+    # _@param_ `key` — 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` — 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` — 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` — 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.
+    # 
+    # _@param_ `adapter` — a compatible adapter
+    def initialize: (
+                      key: String,
+                      capacity: Numeric,
+                      ?adapter: Pecorino::Adapters::BaseAdapter,
+                      ?leak_rate: Float?,
+                      ?over_time: untyped
+                    ) -> void
+
+    # Places `n` tokens in the bucket. If the bucket has less capacity than `n` tokens, the bucket will be filled to capacity.
+    # If the bucket has less capacity than `n` tokens, it will be filled to capacity. If the bucket is already full
+    # when the fillup is requested, the bucket stays at capacity.
+    # 
+    # 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.
+    # 
+    # _@param_ `n_tokens` — How many tokens to fillup by
+    # 
+    # _@return_ — the state of the bucket after the operation
+    def fillup: (Float n_tokens) -> State
+
+    # Places `n` tokens in the bucket. If the bucket has less capacity than `n` tokens, the fillup will be rejected.
+    # This can be used for "exactly once" semantics or just more precise rate limiting. Note that if the bucket has
+    # _exactly_ `n` tokens of capacity the fillup will be accepted.
+    # 
+    # 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.
+    # 
+    # _@param_ `n_tokens` — How many tokens to fillup by
+    # 
+    # _@return_ — the state of the bucket after the operation and whether the operation succeeded
+    # 
+    # ```ruby
+    # withdrawals = LeakyBuket.new(key: "wallet-#{user.id}", capacity: 200, over_time: 1.day)
+    # if withdrawals.fillup_conditionally(amount_to_withdraw).accepted?
+    #   user.wallet.withdraw(amount_to_withdraw)
+    # else
+    #   raise "You need to wait a bit before withdrawing more"
+    # end
+    # ```
+    def fillup_conditionally: (Float n_tokens) -> ConditionalFillupResult
+
+    # 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_ — the snapshotted state of the bucket at time of query
+    def state: () -> State
+
+    # 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`
+    def able_to_accept?: (Float n_tokens) -> bool
+
+    # sord omit - no YARD type given for :key, using untyped
+    # The key (name) of the leaky bucket
+    #   @return [String]
+    attr_reader key: untyped
+
+    # sord omit - no YARD type given for :leak_rate, using untyped
+    # The leak rate (tokens per second) of the bucket
+    #   @return [Float]
+    attr_reader leak_rate: untyped
+
+    # sord omit - no YARD type given for :capacity, using untyped
+    # The capacity of the bucket in tokens
+    #   @return [Float]
+    attr_reader capacity: untyped
+
+    # Returned from `.state` and `.fillup`
+    class State
+      # sord omit - no YARD type given for "level", using untyped
+      # sord omit - no YARD type given for "is_full", using untyped
+      def initialize: (untyped level, untyped is_full) -> void
+
+      # Tells whether the bucket was detected to be full when the operation on
+      # the LeakyBucket was performed.
+      def full?: () -> bool
+
+      # Returns the level of the bucket
+      attr_reader level: Float
+    end
+
+    # Same as `State` but also communicates whether the write has been permitted or not. A conditional fillup
+    # may refuse a write if it would make the bucket overflow
+    class ConditionalFillupResult < Pecorino::LeakyBucket::State
+      # sord omit - no YARD type given for "level", using untyped
+      # sord omit - no YARD type given for "is_full", using untyped
+      # sord omit - no YARD type given for "accepted", using untyped
+      def initialize: (untyped level, untyped is_full, untyped accepted) -> void
+
+      # Tells whether the bucket did accept the requested fillup
+      def accepted?: () -> bool
+    end
+  end
+
+  # The cached throttles can be used when you want to lift your throttle blocks into
+  # a higher-level cache. If you are dealing with clients which are hammering on your
+  # throttles a lot, it is useful to have a process-local cache of the timestamp when
+  # the blocks that are set are going to expire. If you are running, say, 10 web app
+  # containers - and someone is hammering at an endpoint which starts blocking -
+  # you don't really need to query your DB for every request. The first request indicated
+  # as "blocked" by Pecorino can write a cache entry into a shared in-memory table,
+  # and all subsequent calls to the same process can reuse that `blocked_until` value
+  # to quickly refuse the request
+  class CachedThrottle
+    # sord warn - ActiveSupport::Cache::Store wasn't able to be resolved to a constant in this project
+    # _@param_ `cache_store` — the store for the cached blocks. We recommend a MemoryStore per-process.
+    # 
+    # _@param_ `throttle` — the throttle to cache
+    def initialize: (ActiveSupport::Cache::Store cache_store, Pecorino::Throttle throttle) -> void
+
+    # 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!`
+    def request!: (?untyped n) -> untyped
+
+    # sord omit - no YARD type given for "n", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # 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!`
+    def request: (?untyped n) -> untyped
+
+    # sord omit - no YARD type given for "n", using untyped
+    # Returns `false` if there is a currently active block for that throttle in the cache. Otherwise forwards to underlying throttle.
+    # 
+    # _@see_ `Pecorino::Throttle#able_to_accept?`
+    def able_to_accept?: (?untyped n) -> bool
+
+    # sord omit - no YARD return type given, using untyped
+    # Does not run the block  if there is a currently active block for that throttle in the cache. Otherwise forwards to underlying throttle.
+    # 
+    # _@see_ `Pecorino::Throttle#throttled`
+    def throttled: () -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    # Returns the key of the throttle
+    # 
+    # _@see_ `Pecorino::Throttle#key`
+    def key: () -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    # Returns `false` if there is a currently active block for that throttle in the cache. Otherwise forwards to underlying throttle.
+    # 
+    # _@see_ `Pecorino::Throttle#able_to_accept?`
+    def state: () -> untyped
+
+    # sord omit - no YARD type given for "state", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def write_cache_blocked_state: (untyped state) -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    def read_cached_blocked_state: () -> untyped
+  end
+
+  # 
+  # Rails generator used for setting up Pecorino in a Rails application.
+  # Run it with +bin/rails g pecorino:install+ in your console.
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+    TEMPLATES: untyped
+
+    # sord omit - no YARD return type given, using untyped
+    # Generates monolithic migration file that contains all database changes.
+    def create_migration_file: () -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    def migration_version: () -> untyped
+  end
+end

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: pecorino
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.7.3
 platform: ruby
 authors:
 - Julik Tarkhanov
-autorequire:
 bindir: exe
 cert_chain: []
 date: 2025-04-01 00:00:00.000000000 Z
@@ -35,8 +34,10 @@ files:
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".standard.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -59,6 +60,7 @@ files:
 - 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
@@ -77,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
@@ -92,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: []