pecorino 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3a2879a7549a5e41367824a5abccc4fa6cf54b8d78dd1b042f97e8a7bb5f401
-  data.tar.gz: 870bac3b9a9cb8e6dfca8b738022deb25db8d8ce33b027a9f3dd2268e3000971
+  metadata.gz: c0e0c8fa1a6bc734dc645b5b021264eda84bcadd1bec8da65c533a33cd243fb6
+  data.tar.gz: c6c053d8ed02f8e180786d4614c607087ca76b016b8acac35b35a3b3cb544391
 SHA512:
-  metadata.gz: 83f230bf892dd891ef913238c1bc403cc5d9734afaea5b66698109e8792b93197af0de10fc6a9a7716dcbc64ead32acf75c64f13e60708bcd9855e9840e5e203
-  data.tar.gz: b6d4bcbb64558f08082f2603d3c791c6b951ef993fb0090e8e2b5998edeae4346dec618e667f365f0f9042453a29b148327a78e5c789f5bea602d6aadd9d5e62
+  metadata.gz: 02207b3f3d52aa635a960c3914768237a25da4b4cdd7a5ad5da222adf44e738ac987f5182392d0617c60848c745fb0cc5225e2e2392dff50b6e83f58b703d191
+  data.tar.gz: 350d04b9e366d229d87146465574632a00e5e0c88eda7cbc540b494d8ab1d3520d87092f5ae6a6b11f0dd323cc7fd15436728c9b6210fe2264be384b0e9505b4

data/.github/workflows/ci.yml

@@ -1,21 +1,46 @@
 name: CI
 
 on:
-  - push
+  pull_request:
+  push:
+    branches: [ main ]
 
 env:
+  PGHOST: localhost
+  PGUSER: postgres
+  PGPASSWORD: postgres
   BUNDLE_PATH: vendor/bundle
 
 jobs:
+  lint:
+    name: "Lint"
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/Gemfile_ruby27_rails7 # Linting should always align with the minimum Ruby version
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7.7
+          bundler-cache: true
+
+      - name: Lint code for consistent style
+        run: bundle exec standardrb
+
   test:
-    name: Tests
-    runs-on: ubuntu-22.04
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+    name: "Tests"
+    runs-on: ubuntu-latest
     strategy:
+      fail-fast: false # We want both to run to completion
       matrix:
-        ruby:
-          - '2.7'
-          - '3.2'
+        gemfile_and_ruby:
+          - ["/gemfiles/Gemfile_ruby27_rails7", "2.7.7"]
+          - ["/gemfiles/Gemfile_ruby30_rails8", "3.2.2"]
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile_and_ruby[0] }}
     services:
       postgres:
         image: postgres
@@ -30,19 +55,17 @@ jobs:
         ports:
           - 6379:6379
     steps:
-      - name: Checkout
+      - name: Install packages
+        run: sudo apt-get update && sudo apt-get install --no-install-recommends -y curl libjemalloc2 sqlite3
+
+      - name: Checkout code
         uses: actions/checkout@v4
-      - name: Setup Ruby
+
+      - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: ${{ matrix.ruby }}
+          ruby-version:  ${{ matrix.gemfile_and_ruby[1] }}
           bundler-cache: true
-      - name: "Tests and Lint"
-        run: bundle exec rake
-        env:
-          PGHOST: localhost
-          PGUSER: postgres
-          PGPASSWORD: postgres
-          TESTOPTS: "--fail-fast"
-        #   MYSQL_HOST: 127.0.0.1
-        #   MYSQL_PORT: 3306
+
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -7,4 +7,5 @@
 /spec/reports/
 /tmp/
 Gemfile.lock
+gemfiles/*.lock
 .ruby-version

data/.yardopts

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

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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)
+
 ## 0.7.1
 
 - Release dependency constraint to permit Rails 8 (not thoroughly validated yet)

data/Gemfile

@@ -2,5 +2,16 @@
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in pecorino.gemspec
+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
 ```
@@ -182,12 +182,26 @@ We recommend running the following bit of code every couple of hours (via cron o
 Pecorino.prune!
 ```
 
+## Testing your application
+
+The Pecorino buckets and blocks are stateful. If you are not running tests with a transaction rollback, the rate limiters that got hit in a test case may interfere with other test cases you are running. Normally you will not notice this (if you are using the same database as the rest of your models), but we recommend adding this section to your global test case setup:
+
+```ruby
+setup do
+  # Delete all transient records
+  ActiveRecord::Base.connection.execute("TRUNCATE TABLE pecorino_blocks")
+  ActiveRecord::Base.connection.execute("TRUNCATE TABLE pecorino_leaky_buckets")
+end
+```
+
+If you are using Redis, you may want to ensure it gets truncated/reset for every test case - or that parallel test case runners [each use a separate Redis database.](https://redis.io/docs/latest/commands/select/)
+
 ## Using cached throttles
 
 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!
 ```
@@ -200,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!
 ```
@@ -216,9 +230,16 @@ ActiveRecord::Base.connection.execute("ALTER TABLE pecorino_blocks SET UNLOGGED"
 
 ## Development
 
-After checking out the repo, run `bundle`. Then, run `rake test` to run the tests.
+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
+$ bundle rbenv local 2.7.7 && export BUNDLE_GEMFILE=gemfiles/Gemfile_ruby27_rails7 && bundle install
+$ bundle exec rake
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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

@@ -3,6 +3,9 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 require "standard/rake"
+require "yard"
+
+YARD::Rake::YardocTask.new(:doc)
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -15,4 +18,13 @@ task :format do
   `bundle exec magic_frozen_string_literal .`
 end
 
-task default: [:test, :standard]
+task :generate_typedefs do
+  `bundle exec sord rbi/pecorino.rbi`
+  `bundle exec sord rbi/pecorino.rbs`
+end
+
+task default: [:test, :standard, :generate_typedefs]
+
+# When building the gem, generate typedefs beforehand,
+# so that they get included
+Rake::Task["build"].enhance(["generate_typedefs"])

data/gemfiles/Gemfile_ruby27_rails7

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+ruby ">= 2.7", "< 3.0"
+
+gemspec path: ".."
+
+gem "pg"
+gem "sqlite3", "< 1.7"
+gem "activesupport", "< 8.0"
+gem "rake", "~> 13.0"
+gem "minitest", "~> 5.0"
+gem "redis", "~> 5", "< 6"
+gem "yard"
+gem "standard"
+gem "rubocop", "< 1.65" # "`EnsureNode#body` is deprecated and will be changed"...
+gem "magic_frozen_string_literal"
+gem "sord"

data/gemfiles/Gemfile_ruby30_rails8

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+ruby ">= 3.0"
+gemspec path: ".."
+
+gem "pg"
+gem "sqlite3"
+gem "activesupport", ">= 8"
+gem "rake", "~> 13.0"
+gem "minitest", "~> 5.0"
+gem "redis", "~> 5", "< 6"
+gem "yard" # Not used under this Ruby version but the Rakefile includes it
+gem "standard" # Not used but the Rakefile includes it

data/lib/pecorino/adapters/base_adapter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # 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 Pecorino::Adapters::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)

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.1"
+  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/pecorino.gemspec

@@ -23,24 +23,11 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+    `git ls-files -z`.split("\x0")
   end
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  # Uncomment to register a new dependency of your gem
   spec.add_dependency "activerecord", ">= 7"
-  spec.add_development_dependency "pg"
-  spec.add_development_dependency "sqlite3"
-  spec.add_development_dependency "activesupport", ">= 7"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "standard"
-  spec.add_development_dependency "magic_frozen_string_literal"
-  spec.add_development_dependency "minitest-fail-fast"
-  spec.add_development_dependency "redis", "~> 5", "< 6"
-
-  # For more information and examples about making a new gem, checkout our
-  # guide at: https://bundler.io/guides/creating_gem.html
 end