speed_limiter 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcefe51efe099102f75381a902006faa8655f7207c7c971e0e0b0f356dc9c5e0
-  data.tar.gz: c3a3647ea48bb31a95dcd1bc70ddcb72c0402e4474c459e88271666021ba878f
+  metadata.gz: 573c75da906a932bbc66fb90a6b2dbeaf7aabe12773178c28b197c81de4be9f0
+  data.tar.gz: f01dd67d1f923a5d63a29d67239f6a0a348a1236396a9e14ebefcf4702e51198
 SHA512:
-  metadata.gz: bcfa6c8194738f83b7f688cc8211a79d10d8cee564a9b5099694c2730e71a1305c3d78dedad1b06654105d7da4b9070c9abb9d98aee97eca566eeaff32aed531
-  data.tar.gz: cb88e0be3f91a53919d019009c35cadad7e50a46e719f06405b13912f24f195030a06686e7d28241d30a26bdf516946b7f1ca37cb429473bda189815f85cc1c7
+  metadata.gz: f02a8e3fd56bd84f5bf5cf3eb3b24336a9805d04cf89f01fb53dcbc745125010e555f54bb2494689e05a0527819ab094d0eb461cb0cb3f876db0c423f684b123
+  data.tar.gz: c61501a41484331f0041b665407c1b0ff609f84f31ffac3f4b9725162aecdc1960f10ab8207cbce6a4a54b4790abdc532de70241e22eaaf2bc1db28833b97492

data/README.md

@@ -66,20 +66,34 @@ SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1, on_thrott
 end
 ```
 
+### raise_on_throttled option
+
+It raises an exception when the limit is exceeded.
+
+```ruby
+begin
+  SpeedLimiter.throttle('server_name/method_name', limit: 10, period: 1, raise_on_throttled: true) do
+    http.get(path)
+  end
+rescue SpeedLimiter::ThrottledError => e
+  logger.info(e.message) #=> "server_name/method_name rate limit exceeded. Retry after 0.9 seconds. limit=10, count=11, period=1"
+  e.state #=> <SpeedLimiter::State key=server_name/method_name count=11 ttl=0.9>
+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
+  rescue_from(SpeedLimiter::ThrottledError) do |e|
+    Rails.logger.warn("[#{e.class}] #{self.class} retry job. #{e.message}")
+    retry_job(wait: e.ttl, queue: 'low')
+  end
 
-    SpeedLimiter.throttle("slack", limit: 20, period: 1.minute, on_throttled: on_throttled) do
+  def perform(*args)
+    SpeedLimiter.throttle("slack", limit: 20, period: 1.minute, raise_on_throttled: true) do
       create_slack_channel(*args)
     end
-  rescue Slack::LimitExceeded => e
-    self.class.set(wait: e.ttl).perform_later(*args)
   end
 end
 ```

data/lib/speed_limiter/errors/limit_exceeded_error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module SpeedLimiter
+  module Errors
+    # SpeedLimiter limit exceeded Base Error
+    class LimitExceededError < StandardError
+      extend Forwardable
+
+      # @param state [SpeedLimiter::State]
+      def initialize(state)
+        @state = state
+        super(error_message)
+      end
+      attr_reader :state
+
+      # @!method key
+      #   @see SpeedLimiter::State#key
+      # @!method ttl
+      #   @see SpeedLimiter::State#ttl
+      # @!method count
+      #   @see SpeedLimiter::State#count
+      # @!method limit
+      #   @see SpeedLimiter::State#limit
+      # @!method period
+      #   @see SpeedLimiter::State#period
+      delegate %i[key ttl count limit period] => :@state
+
+      def error_message
+        "#{key} rate limit exceeded. Retry after #{ttl} seconds. limit=#{limit}, count=#{count}, period=#{period}"
+      end
+    end
+  end
+end

data/lib/speed_limiter/errors/throttled_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "speed_limiter/errors/limit_exceeded_error"
+
+module SpeedLimiter
+  module Errors
+    # SpeedLimiter::Throttled limit exceeded Error
+    class ThrottledError < LimitExceededError
+    end
+  end
+end

data/lib/speed_limiter/state.rb

@@ -19,7 +19,19 @@ module SpeedLimiter
 
     attr_reader :params, :count, :ttl
 
-    def_delegators(:params, :config, :key, :limit, :period, :on_throttled, :retry)
+    # @!method config
+    #   @see SpeedLimiter::ThrottleParams#config
+    # @!method key
+    #   @see SpeedLimiter::ThrottleParams#key
+    # @!method limit
+    #   @see SpeedLimiter::ThrottleParams#limit
+    # @!method period
+    #   @see SpeedLimiter::ThrottleParams#period
+    # @!method on_throttled
+    #   @see SpeedLimiter::ThrottleParams#on_throttled
+    # @!method retry
+    #   @see SpeedLimiter::ThrottleParams#retry
+    delegate %i[config key limit period on_throttled retry] => :@params
 
     def inspect
       "<#{self.class.name} key=#{key.inspect} count=#{count} ttl=#{ttl}>"

data/lib/speed_limiter/throttle.rb

@@ -13,6 +13,10 @@ module SpeedLimiter
     # @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, Class] :raise_on_throttled
+    #   Raise error when limit exceeded. If Class is given, it will be raised instead of SpeedLimiter::ThrottledError.
+    #   If you want to specify a custom error class, please specify a class that inherits from
+    #   SpeedLimiter::LimitExceededError or a class that accepts SpeedLimiter::State as an argument.
     # @option params [true, Hash] :retry Retry options. (see {Retryable.retryable} for details)
     def initialize(key, config:, **params)
       params[:key] = key.to_s
@@ -22,9 +26,11 @@ module SpeedLimiter
     end
     attr_reader :config, :params, :block
 
-    delegate %i[redis_client] => :config
+    delegate %i[redis_client] => :@config
 
-    delegate %i[key redis_key limit period on_throttled create_state] => :params
+    delegate %i[
+      key redis_key limit period on_throttled raise_on_throttled_class raise_on_throttled? create_state
+    ] => :@params
 
     # @yield [state]
     # @yieldparam state [SpeedLimiter::State]
@@ -72,8 +78,12 @@ module SpeedLimiter
       ttl = redis_client.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)
+      create_state(count: count, ttl: ttl).tap do |state|
+        raise raise_on_throttled_class, state if raise_on_throttled?
+
+        config.on_throttled.call(state) if config.on_throttled.respond_to?(:call)
+        on_throttled.call(state) if on_throttled.respond_to?(:call)
+      end
 
       ttl = redis_client.ttl(redis_key)
       return if ttl.negative?

data/lib/speed_limiter/throttle_params.rb

@@ -1,32 +1,82 @@
 # frozen_string_literal: true
 
 require "speed_limiter/state"
+require "speed_limiter/errors/throttled_error"
 
 module SpeedLimiter
   # Throttle params model
   class ThrottleParams
+    KNOWN_OPTIONS = %i[on_throttled retry raise_on_throttled].freeze
+
+    # @param config [SpeedLimiter::Config]
+    # @param key [String]
+    # @param limit [Integer] limit count per period
+    # @param period [Integer] period time (seconds)
+    # @param options [Hash] options
+    # @option options [Proc, #call] :on_throttled Block called when limit exceeded, with ttl(Float) and key as argument
+    # @option options [true, Class] :raise_on_throttled
+    #   Raise error when limit exceeded. If Class is given, it will be raised instead of SpeedLimiter::ThrottledError.
+    #   If you want to specify a custom error class, please specify a class that inherits from
+    #   SpeedLimiter::LimitExceededError or a class that accepts SpeedLimiter::State as an argument.
+    # @option options [true, Hash] :retry Retry options. (see {Retryable.retryable} for details)
     def initialize(config:, key:, limit:, period:, **options)
       @config = config
       @key = key
       @limit = limit
       @period = period
       @options = options
+
+      return unless (unknown_options = options.keys - KNOWN_OPTIONS).any?
+
+      raise ArgumentError, "Unknown options: #{unknown_options.join(', ')}"
     end
 
+    # @!method config
+    #   @return [SpeedLimiter::Config]
+    # @!method key
+    #   @return [String] Throttle key name
+    # @!method limit
+    #   @return [Integer] limit count per period
+    # @!method period
+    #   @return [Integer] period time (seconds)
     attr_reader :config, :key, :limit, :period
 
     def on_throttled
       @options[:on_throttled]
     end
 
+    # @return [Boolean, Class]
+    def raise_on_throttled
+      @options[:raise_on_throttled]
+    end
+
+    # @return [Boolean]
+    def raise_on_throttled?
+      !!raise_on_throttled
+    end
+
+    # @return [Class]
+    def raise_on_throttled_class
+      if raise_on_throttled.is_a?(Class)
+        raise_on_throttled
+      else
+        SpeedLimiter::Errors::ThrottledError
+      end
+    end
+
+    # @return [Boolean, Hash]
     def retry
       @options[:retry]
     end
 
+    # @return [String]
     def redis_key
       "#{config.prefix}:#{key}"
     end
 
+    # @param count [Integer, nil]
+    # @param ttl [Float, nil]
+    # @return [SpeedLimiter::State]
     def create_state(count: nil, ttl: nil)
       State.new(params: self, count: count, ttl: ttl)
     end

data/lib/speed_limiter/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: speed_limiter
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - yuhei mukoyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-13 00:00:00.000000000 Z
+date: 2024-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -45,6 +45,8 @@ files:
 - compose.yaml
 - lib/speed_limiter.rb
 - lib/speed_limiter/config.rb
+- lib/speed_limiter/errors/limit_exceeded_error.rb
+- lib/speed_limiter/errors/throttled_error.rb
 - lib/speed_limiter/redis.rb
 - lib/speed_limiter/state.rb
 - lib/speed_limiter/throttle.rb