speed_limiter 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee6151563233234c9c453843d4d3d98e8de465905e38e99437caaa6a0e258d6b
-  data.tar.gz: 9efaa7b0784d79a9a23c77015013519380d20b94645e39e725d390030ad48569
+  metadata.gz: b360a3c2df8c37b8ac47eec08222e784ef475966c5938c93f1206e56c2ec353d
+  data.tar.gz: 34a890cdbdf74a0fcb25b2140c124ec6f6487ebf2aec4115084fabbc2a437ddd
 SHA512:
-  metadata.gz: a9672f7b225e6325589c9bb8fae4cc76ad860024b9fbbcdb6f10edc5d4137ac593b4d6ac5370e6490b1ccc1186b0032bf20d572644ec8177afa783d5603cfe2d
-  data.tar.gz: 74020c4965b083e2cea5af94a05299455d2ee64060fc008e8fa9b7b5afacae0a587d432925ece9f7efb860388fa15886742d7c5d722751cdb877d6bf31d30110
+  metadata.gz: 0ed1f8c6f934e2955b5fd398f6cead553eff69e3e93cb2816a6a3cb41f61fe0848980b0fe1310d17f531ce8f4266de80b0599b7416d1c4d4d8bbda9a61f92c43
+  data.tar.gz: 6ef932d30fc72b180b2e968b3f57e75621b15d36b1afc33488cd80a2fa1e0c26802650db1902f97fac29c4294905f12abe17fdb1c99b7200772f77f7c5bab89e

data/.github/workflows/lint.yml

@@ -12,7 +12,7 @@ jobs:
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/.github/workflows/test.yml

@@ -18,27 +18,45 @@ jobs:
     timeout-minutes: 10
 
     strategy:
+      max-parallel: 6
       matrix:
-        ruby-version: ['3.0', '3.1', '3.2', ruby-head]
-        redis-version: ['5.0', '6.0', '6.2', '7.0', '7.2', latest]
+        set:
+          - ruby-version: '3.0'
+            redis-version: '7.2'
+          - ruby-version: '3.1'
+            redis-version: '7.2'
+          - ruby-version: '3.2'
+            redis-version: '5.0'
+          - ruby-version: '3.2'
+            redis-version: '6.0'
+          - ruby-version: '3.2'
+            redis-version: '6.2'
+          - ruby-version: '3.2'
+            redis-version: '7.0'
+          - ruby-version: '3.2'
+            redis-version: '7.2'
+          - ruby-version: '3.2'
+            redis-version: latest
+          - ruby-version: ruby-head
+            redis-version: '7.2'
 
     services:
       redis:
-        image: redis:${{ matrix.redis-version }}
+        image: redis:${{ matrix.set.redis-version }}
         ports:
           - 6379:6379
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - name: Set up Ruby ${{ matrix.ruby-version }}
+      - name: Set up Ruby ${{ matrix.set.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: ${{ matrix.ruby-version }}
+          ruby-version: ${{ matrix.set.ruby-version }}
           bundler-cache: true
 
-      - name: Rackup test throttle server
-        run: bundle exec pumad -C throttle_server/puma.rb throttle_server/config.ru
+      - name: Rackup test web server
+        run: bundle exec rake throttle_server:start_daemon
 
       - name: Run tests
         run: bundle exec rspec -fd

data/.rubocop.yml

@@ -18,3 +18,6 @@ Rspec/MultipleExpectations:
 Rspec/ExampleLength:
   Enabled: false
 
+Metrics/BlockLength:
+  Exclude:
+    - 'Rakefile'

data/Gemfile

@@ -13,6 +13,7 @@ group :development do
   gem "rack-attack", "~> 6.7"
   gem "rackup", "~> 2.1"
   gem "rake"
+  gem "retryable"
   gem "rspec"
   gem "rubocop"
   gem "rubocop-rake"

data/README.md

@@ -1,12 +1,14 @@
-[![lint](https://github.com/seibii/speed_limiter/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/seibii/speed_limiter/actions/workflows/lint.yml) [![test](https://github.com/seibii/speed_limiter/actions/workflows/test.yml/badge.svg)](https://github.com/seibii/speed_limiter/actions/workflows/test.yml) [![Gem Version](https://badge.fury.io/rb/speed_limiter.svg)](https://badge.fury.io/rb/speed_limiter) [![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
+[![lint](https://github.com/seibii/speed_limiter/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/seibii/speed_limiter/actions/workflows/lint.yml) [![test](https://github.com/seibii/speed_limiter/actions/workflows/test.yml/badge.svg)](https://github.com/seibii/speed_limiter/actions/workflows/test.yml) [![Gem Version](https://badge.fury.io/rb/speed_limiter.svg)](https://badge.fury.io/rb/speed_limiter) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
 
 # SpeedLimiter
 
 <img src="README_image.jpg" width="400px" />
 
-This is a Gem for execution limits in multi-process and multi-threaded environments. By using Redis, you can limit execution across multiple processes and threads.
+SpeedLimiter is a gem that limits the number of executions per unit of time.
+By default, it achieves throttling through sleep.
+
+You can also use the `on_throttled` event to raise an exception instead of sleeping, or to re-enqueue the task.
 
-It was mainly created to avoid hitting access limits to the API server.
 
 ## Installation
 
@@ -26,19 +28,107 @@ Or install it yourself as:
 
 ## Usage
 
+Limit the number of executions to 10 times per second.
+
+```ruby
+SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1) do |state|
+  puts state #=> <SpeedLimiter::State key=server_name/method_name count=1 ttl=0>
+  http.get(path)
+end
+
+# or
+
+throttle_limit_10_par_sec = SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1)
+
+throttle_limit_10_par_sec.call do |state|
+  puts state #=> <SpeedLimiter::State key=server_name/method_name count=1 ttl=0>
+  http.get(path)
+end
+```
+
+It returns the result of the block execution.
+
+```ruby
+result = SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1) do
+  http.get(path)
+end
+puts result.code #=> 200
+```
+
+### on_throttled option
+
+Specify the process when the limit is exceeded.
+
+```ruby
+on_throttled = proc { |state| logger.info("limit exceeded #{state.key} #{state.ttl}") }
+SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1, on_throttled: on_throttled) do
+  http.get(path)
+end
+```
+
+Reinitialize the queue instead of sleeping when the limit is reached in ActiveJob.
+
+```ruby
+class CreateSlackChannelJob < ApplicationJob
+  def perform(*args)
+    on_throttled = proc do |state|
+      raise Slack::LimitExceeded, state.ttl if state.ttl > 5
+    end
+
+    SpeedLimiter.throttle("slack", limit: 20, period: 1.minute, on_throttled: on_throttled) do
+      create_slack_channel(*args)
+    end
+  rescue Slack::LimitExceeded => e
+    self.class.set(wait: e.ttl).perform_later(*args)
+  end
+end
+```
+
+### retry option
+
+To use the `retry:` option, you need to introduce the [Retryable gem](https://github.com/nfedyashev/retryable).
+By specifying the options of the Retryable gem, you can retry when an exception occurs.
+
 ```ruby
-# Limit the number of executions to 10 times per second
+# Gemfile
+gem 'retryable'
+```
+
+```ruby
+SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1, retry: { tries: 3, on: OpenURI::HTTPError }) do
+  http.get(path)
+end
+
+# equivalent to
 SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1) do
-  # Do something
+  Retryable.retryable(tries: 3, on: OpenURI::HTTPError) do
+    http.get(path)
+  end
+end
+```
+
+`retry: true` or `retry: {}` is default use of `Retryable.configure`.
+
+```ruby
+SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1, retry: true) do
+  http.get(path)
 end
 ```
 
-### Configuration
+## Configuration
+
+### Redis configuration
+
+Redis can be specified as follows
+
+1. default url `redis://localhost:6379/0`
+2. `SPEED_LIMITER_REDIS_URL` environment variable
+3. Configure `SpeedLimiter.configure`
 
 ```ruby
 # config/initializers/speed_limiter.rb
 SpeedLimiter.configure do |config|
-  config.redis_url = ENV['SPEED_LIMITER_REDIS_URL'] || 'redis://localhost:6379/2'
+  config.redis_url = ENV.fetch('SPEED_LIMITER_REDIS_URL', 'redis://localhost:6379/2')
 end
 ```
 
@@ -51,6 +141,20 @@ SpeedLimiter.configure do |config|
 end
 ```
 
+### Other configuration defaults
+
+```ruby
+SpeedLimiter.configure do |config|
+   config.redis_url = ENV.fetch("SPEED_LIMITER_REDIS_URL", "redis://localhost:6379/0")
+   config.redis = nil
+   config.no_limit = false # If true, it will not be throttled
+   config.prefix = "speed_limiter" # Redis key prefix
+   config.on_throttled = nil # Proc to be executed when the limit is exceeded
+end
+```
+
+### Example
+
 If you do not want to impose a limit in the test environment, please set it as follows.
 
 ```ruby
@@ -64,6 +168,24 @@ RSpec.configure do |config|
 end
 ```
 
+If you want to detect the limit in the test environment, please set it as follows.
+
+```ruby
+Rspec.describe do
+  around do |example|
+    SpeedLimiter.config.on_throttled = proc { |state| raise "limit exceeded #{state.key} #{state.ttl}" }
+
+    example.run
+
+    SpeedLimiter.config.on_throttled = nil
+  end
+
+  it do
+    expect { over_limit_method }.to raise_error('limit exceeded key_name [\d.]+')
+  end
+end
+```
+
 ## Compatibility
 
 SpeedLimiter officially supports the following Ruby implementations and Redis :
@@ -82,11 +204,11 @@ You can also run bin/console for an interactive prompt that will allow you to ex
 
 ### rspec
 
-Start a web server and Redis for testing with the following command.
+Start a test web server and Redis for testing with the following command.
 
-```
-$ rake test:throttle_server
-$ docker compose up
+```console
+$ rake throttle_server:start_daemon # or rake throttle_server:start
+$ docker compose up -d
 ```
 
 After that, please run the test with the following command.

data/Rakefile

@@ -12,9 +12,33 @@ RuboCop::RakeTask.new
 
 task default: :spec
 
-namespace :test do
-  desc "Run rackup for throttle server daemon"
-  task :throttle_server do
+namespace :throttle_server do
+  desc "Run rackup for Throttle server"
+  task :start do
     system "puma -C throttle_server/puma.rb throttle_server/config.ru"
   end
+
+  desc "Run rackup for Throttle server daemon"
+  task :start_daemon do
+    system "pumad -C throttle_server/puma.rb throttle_server/config.ru"
+  end
+
+  desc "Stop the Throttle server daemon"
+  task :stop do
+    pid_file = "throttle_server/tmp/puma.pid"
+
+    if File.exist?(pid_file)
+      pid = File.read(pid_file).to_i
+      begin
+        Process.kill("TERM", pid)
+        puts "Throttle server (PID: #{pid}) has been stopped."
+      rescue Errno::ESRCH
+        puts "Throttle server (PID: #{pid}) not found. It might have already stopped."
+      rescue StandardError => e
+        puts "Failed to stop Throttle server (PID: #{pid}): #{e.message}"
+      end
+    else
+      puts "PID file not found. Is the Throttle server running?"
+    end
+  end
 end

data/lib/speed_limiter/config.rb

@@ -3,13 +3,14 @@
 module SpeedLimiter
   # config model
   class Config
-    attr_accessor :redis_url, :redis, :no_limit, :prefix
+    attr_accessor :redis_url, :redis, :no_limit, :prefix, :on_throttled
 
     def initialize
-      @redis_url = "redis://localhost:6379/0"
+      @redis_url = ENV.fetch("SPEED_LIMITER_REDIS_URL", "redis://localhost:6379/0")
       @redis = nil
       @no_limit = false
       @prefix = "speed_limiter"
+      @on_throttled = nil
     end
 
     alias no_limit? no_limit

data/lib/speed_limiter/redis.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SpeedLimiter
+  # Redis wrapper
+  class Redis
+    def initialize(redis)
+      @redis = redis
+    end
+    attr_reader :redis
+
+    def ttl(key)
+      redis.pttl(key) / 1000.0
+    end
+
+    def increment(key, period) # rubocop:disable Metrics/MethodLength
+      if supports_expire_nx?
+        count, ttl = redis.pipelined do |pipeline|
+          pipeline.incrby(key, 1)
+          pipeline.call(:expire, key, period.to_i, "NX")
+        end
+      else
+        count, ttl = redis.pipelined do |pipeline|
+          pipeline.incrby(key, 1)
+          pipeline.ttl(key)
+        end
+        redis.expire(key, period.to_i) if ttl.negative?
+      end
+
+      [count, ttl]
+    end
+
+    private
+
+    def supports_expire_nx?
+      return @supports_expire_nx if defined?(@supports_expire_nx)
+
+      redis_versions = redis.info("server")["redis_version"]
+      @supports_expire_nx = Gem::Version.new(redis_versions) >= Gem::Version.new("7.0.0")
+    end
+  end
+end

data/lib/speed_limiter/state.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "speed_limiter/state"
+require "forwardable"
+
+module SpeedLimiter
+  # Execution status model
+  class State
+    extend Forwardable
+
+    # @param params [SpeedLimiter::ThrottleParams]
+    # @param count [Integer] current count
+    # @param ttl [Float] remaining time to reset
+    def initialize(params:, count:, ttl:)
+      @params = params
+      @count = count
+      @ttl = ttl
+    end
+
+    attr_reader :params, :count, :ttl
+
+    def_delegators(:params, :config, :key, :limit, :period, :on_throttled, :retry)
+
+    def inspect
+      "<#{self.class.name} key=#{key.inspect} count=#{count} ttl=#{ttl}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/speed_limiter/throttle.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "speed_limiter/redis"
+require "speed_limiter/throttle_params"
+
+module SpeedLimiter
+  # with actual throttle limits
+  class Throttle
+    extend Forwardable
+
+    # @param key [String, #to_s] Throttle key name
+    # @option params [Integer] :limit limit count per period
+    # @option params [Integer] :period period time (seconds)
+    # @option params [Proc, #call] :on_throttled Block called when limit exceeded, with ttl(Float) and key as argument
+    # @option params [true, Hash] :retry Retry options. (see {Retryable.retryable} for details)
+    def initialize(key, config:, **params)
+      params[:key] = key.to_s
+
+      @config = config
+      @params = ThrottleParams.new(config: config, **params)
+    end
+    attr_reader :config, :params, :block
+
+    delegate %i[key redis_key limit period on_throttled create_state] => :params
+
+    # @yield [state]
+    # @yieldparam state [SpeedLimiter::State]
+    # @return [any] block return value
+    def call(&block)
+      if use_retryable?
+        Retryable.retryable(**retryable_options) { run_block(&block) }
+      else
+        run_block(&block)
+      end
+    end
+
+    private
+
+    def use_retryable?
+      return false if params.retry == false || params.retry.nil?
+
+      unless Gem::Specification.find_by_name("retryable")
+        raise ArgumentError, "To use the 'retry' option, you need to install the Retryable gem."
+      end
+
+      require "retryable"
+      params.retry.is_a?(Hash) || params.retry == true
+    end
+
+    def retryable_options
+      return {} if params.retry == true
+
+      params.retry
+    end
+
+    def run_block(&block)
+      return block.call(create_state) if config.no_limit?
+
+      loop do
+        count, ttl = redis.increment(redis_key, period)
+
+        break(block.call(create_state(count: count, ttl: ttl))) if count <= limit
+
+        wait_for_interval(count)
+      end
+    end
+
+    def wait_for_interval(count)
+      ttl = redis.ttl(redis_key)
+      return if ttl.negative?
+
+      config.on_throttled.call(create_state(count: count, ttl: ttl)) if config.on_throttled.respond_to?(:call)
+      on_throttled.call(create_state(count: count, ttl: ttl)) if on_throttled.respond_to?(:call)
+
+      ttl = redis.ttl(redis_key)
+      return if ttl.negative?
+
+      sleep ttl
+    end
+
+    def redis
+      @redis ||= SpeedLimiter::Redis.new(config.redis || ::Redis.new(url: config.redis_url))
+    end
+  end
+end

data/lib/speed_limiter/throttle_params.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "speed_limiter/state"
+
+module SpeedLimiter
+  # Throttle params model
+  class ThrottleParams
+    def initialize(config:, key:, limit:, period:, **options)
+      @config = config
+      @key = key
+      @limit = limit
+      @period = period
+      @options = options
+    end
+
+    attr_reader :config, :key, :limit, :period
+
+    def on_throttled
+      @options[:on_throttled]
+    end
+
+    def retry
+      @options[:retry]
+    end
+
+    def redis_key
+      "#{config.prefix}:#{key}"
+    end
+
+    def create_state(count: nil, ttl: nil)
+      State.new(params: self, count: count, ttl: ttl)
+    end
+  end
+end

data/lib/speed_limiter/version.rb

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

data/lib/speed_limiter.rb

@@ -2,6 +2,7 @@
 
 require "speed_limiter/version"
 require "speed_limiter/config"
+require "speed_limiter/throttle"
 require "redis"
 
 # Call speed limiter
@@ -15,56 +16,19 @@ module SpeedLimiter
       yield(config)
     end
 
-    def redis
-      @redis ||= config.redis || Redis.new(url: config.redis_url)
-    end
-
-    def throttle(key, limit:, period:, &block)
-      return block&.call if config.no_limit?
-
-      key_name = "#{config.prefix}:#{key}"
-      loop do
-        count = increment(key_name, period)
-
-        break(block&.call) if count <= limit
-
-        wait_for_interval(key_name)
-      end
-    end
-
-    private
+    # @param key (see Throttle#initialize)
+    # @option (see Throttle#initialize)
+    # @yield (see Throttle#call)
+    # @yieldparam (see Throttle#call)
+    # @return Return value of block if argument contains block, otherwise Throttle instance
+    def throttle(key, **params, &block)
+      throttle = Throttle.new(key, config: config, **params)
 
-    def wait_for_interval(key)
-      pttl = redis.pttl(key)
-      ttl = pttl / 1000.0
-
-      return if ttl.negative?
-
-      sleep ttl
-    end
-
-    def increment(key, period) # rubocop:disable Metrics/MethodLength
-      if supports_expire_nx?
-        count, = redis.pipelined do |pipeline|
-          pipeline.incrby(key, 1)
-          pipeline.call(:expire, key, period.to_i, "NX")
-        end
+      if block
+        throttle.call(&block)
       else
-        count, ttl = redis.pipelined do |pipeline|
-          pipeline.incrby(key, 1)
-          pipeline.ttl(key)
-        end
-        redis.expire(key, period.to_i) if ttl.negative?
+        throttle
       end
-
-      count
-    end
-
-    def supports_expire_nx?
-      return @supports_expire_nx if defined?(@supports_expire_nx)
-
-      redis_versions = redis.info("server")["redis_version"]
-      @supports_expire_nx = Gem::Version.new(redis_versions) >= Gem::Version.new("7.0.0")
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: speed_limiter
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - yuhei mukoyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-30 00:00:00.000000000 Z
+date: 2024-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -45,8 +45,12 @@ files:
 - compose.yaml
 - lib/speed_limiter.rb
 - lib/speed_limiter/config.rb
+- lib/speed_limiter/redis.rb
+- lib/speed_limiter/state.rb
+- lib/speed_limiter/throttle.rb
+- lib/speed_limiter/throttle_params.rb
 - lib/speed_limiter/version.rb
-- speed_limitter.gemspec
+- speed_limiter.gemspec
 - throttle_server/config.ru
 - throttle_server/puma.rb
 - throttle_server/tmp/.keep
@@ -71,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: Limit the frequency of execution across multiple threads and processes