speed_limiter 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee6151563233234c9c453843d4d3d98e8de465905e38e99437caaa6a0e258d6b
-  data.tar.gz: 9efaa7b0784d79a9a23c77015013519380d20b94645e39e725d390030ad48569
+  metadata.gz: 49d4e898db4491c876e3cdf95a157aa2b9b832444c10a62598dae6214204e864
+  data.tar.gz: f6c223a5b30ab88f844de353e9d4a893d40e629c7602ab521bf59d30a6e314e8
 SHA512:
-  metadata.gz: a9672f7b225e6325589c9bb8fae4cc76ad860024b9fbbcdb6f10edc5d4137ac593b4d6ac5370e6490b1ccc1186b0032bf20d572644ec8177afa783d5603cfe2d
-  data.tar.gz: 74020c4965b083e2cea5af94a05299455d2ee64060fc008e8fa9b7b5afacae0a587d432925ece9f7efb860388fa15886742d7c5d722751cdb877d6bf31d30110
+  metadata.gz: eb26517138fca5d75e5a43a45765ccc48b54586e9bc38b7b644663a8954f7102a513d36e6a8e94575561ad575256c52aa2c1931f481c1f65c64a6a83c663be08
+  data.tar.gz: 54edbdd81701def3bdc0c1ac738c835198245ca187cfe53393e3887c6a59691332d957d7c0d8cd7362feb3ba18e440524d075bbb493a7b61fc21c929de90a86f

data/.github/workflows/test.yml

@@ -18,6 +18,7 @@ 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]
@@ -37,8 +38,8 @@ jobs:
           ruby-version: ${{ matrix.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/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,65 @@ Or install it yourself as:
 
 ## Usage
 
+Limit the number of executions to 10 times per second.
+
 ```ruby
-# Limit the number of executions to 10 times per second
-SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1) do
-  # Do something
+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
+```
+
+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
+```
+
+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
 ```
 
 ### 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 +99,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 +126,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 +162,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,26 @@
+# frozen_string_literal: true
+
+require "speed_limiter/state"
+require "forwardable"
+
+module SpeedLimiter
+  # Execution status model
+  class State
+    extend Forwardable
+
+    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)
+
+    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,59 @@
+# 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
+
+    # @option params [String] :key key name
+    # @option params [Integer] :limit limit count per period
+    # @option params [Integer] :period period time (seconds)
+    # @option params [Proc] :on_throttled Block called when limit exceeded, with ttl(Float) and key as argument
+    # @yield [count] Block called to not reach limit
+    # @yieldparam count [Integer] count of period
+    # @yieldreturn [any] block return value
+    def initialize(config:, **params, &block)
+      @config = config
+      @params = ThrottleParams.new(config: config, **params)
+      @block = block
+    end
+    attr_reader :config, :params, :block
+
+    def_delegators(:params, :key, :redis_key, :limit, :period, :on_throttled, :create_state)
+
+    def throttle
+      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
+
+    private
+
+    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,26 @@
+# frozen_string_literal: true
+
+require "speed_limiter/state"
+
+module SpeedLimiter
+  # Throttle params model
+  class ThrottleParams
+    def initialize(config:, key:, limit:, period:, on_throttled: nil)
+      @config = config
+      @key = key
+      @limit = limit
+      @period = period
+      @on_throttled = on_throttled
+    end
+
+    attr_reader :config, :key, :limit, :period, :on_throttled
+
+    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.1.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
@@ -19,52 +20,15 @@ module SpeedLimiter
       @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
-
-    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
-      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
-    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")
+    # @param key [String] key name
+    # @param limit [Integer] limit count per period
+    # @param period [Integer] period time (seconds)
+    # @param on_throttled [Proc] Block called when limit exceeded, with ttl(Float) and key as argument
+    # @yield [count] Block called to not reach limit
+    # @yieldparam count [Integer] count of period
+    # @yieldreturn [any] block return value
+    def throttle(key, **params, &block)
+      Throttle.new(config: config, key: key, **params, &block).throttle
     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.1.0
 platform: ruby
 authors:
 - yuhei mukoyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-30 00:00:00.000000000 Z
+date: 2023-12-16 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