throttle_machines 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a080af0b8e5ed4c52fc3f7df63757a7b8a91beb76124f49ddd6ff06ae02e8072
-  data.tar.gz: f4ee5682bb2c846e4ec69364da967127285d186b379d76c2b378bdb99ff92675
+  metadata.gz: 72c8aa3de40f786c3636692e1c843a3bc06f74e5e18070c8192ada2b4b5dc1af
+  data.tar.gz: e13536b0ee7936a34e7012598fa053bdfac68f90cc0bf3d89eee93908bc02e70
 SHA512:
-  metadata.gz: 7d10328c5affbb67291563d9190c7395b6800c2e9b7085789afcf7e891693c3d00116d5d63dc6bf634eb7b96e6c60e74e65118629702ca7bedc68e7867f90a21
-  data.tar.gz: eed2c6323e3ba2f52901ef5280d1fee89ca5e0a8d9f0e316c54ca7151e2870f452a5f59d30096b8d216aa37f4585beb96213ab5190f07d157d8ec31310d1ceb6
+  metadata.gz: 210c43367129d549efa9527e01cc37621763c5b8cc818bc3bd980f2304b487792d7138d711c8e621970199534b59e16e3f5604c0ba69061d0fe00837c3bba4c1
+  data.tar.gz: 400a4dbe1e43b61ffc79b60ef9bf85819edaa0204294264e4c582d871a0f4086c867181377db507fd45a186b1caf663e78aef90711d811591e96387ab070c7f7

data/README.md

@@ -126,6 +126,34 @@ memory limits separately. Evicting active Redis keys can reset their limits.
 
 ---
 
+## Rails cache storage
+
+`Storage::Cache` keeps fixed-window counters in any `ActiveSupport::Cache`
+store, so limits share Solid Cache, Redis, or Memcached with the rest of the app
+(and with `BreakerMachines::Storage::Cache`).
+
+```ruby
+ThrottleMachines.storage = ThrottleMachines::Storage::Cache.new(cache_store: Rails.cache)
+# or, inside Rails: config.default_storage = :cache
+```
+
+Windows align to the Unix epoch and each one is its own cache entry, admitted
+with a single atomic `increment`. On Solid Cache with PostgreSQL, the first
+increments of a window can race and undercount by the number of concurrent
+first requests.
+
+It supports `:fixed_window` only; the cache API has no atomic read-modify-write
+for GCRA or token buckets. A limiter built with an algorithm its storage lacks
+raises `ArgumentError` on construction, for custom backends too.
+
+When the store fails to count (an outage, `NullStore`), requests are admitted.
+Pass `fail_closed: true` to throttle them instead. `clear` deletes only this
+backend's keys and needs `delete_matched`; on Solid Cache and Memcached it
+raises `ThrottleMachines::UnsupportedOperationError`, so reset single limiters
+with `Limiter#reset!`.
+
+---
+
 ## 🌠 The Ultra-Thin Philosophy
 
 Like the best spacecraft, ThrottleMachines follows the principle of **ultra-thin design**:

data/lib/throttle_machines/limiter.rb

@@ -10,6 +10,7 @@ module ThrottleMachines
       @period = period
       @algorithm = algorithm
       @storage = storage || ThrottleMachines.storage
+      validate_algorithm!
     end
 
     def allow?
@@ -163,5 +164,17 @@ module ThrottleMachines
         retry_after: retry_after
       }
     end
+
+    private
+
+    def validate_algorithm!
+      unless Storage::Base::ALGORITHM_OPERATIONS.key?(@algorithm)
+        raise ArgumentError, "Unknown algorithm: #{@algorithm.inspect}"
+      end
+      return unless @storage.respond_to?(:supports?)
+      return if @storage.supports?(@algorithm)
+
+      raise ArgumentError, "#{@storage.class} does not support the #{@algorithm.inspect} algorithm"
+    end
   end
 end

data/lib/throttle_machines/storage/base.rb

@@ -3,52 +3,70 @@
 module ThrottleMachines
   module Storage
     class Base
+      ALGORITHM_OPERATIONS = {
+        fixed_window: %i[increment_counter get_counter get_counter_ttl reset_counter],
+        gcra: %i[check_gcra_limit peek_gcra_limit],
+        token_bucket: %i[check_token_bucket peek_token_bucket]
+      }.freeze
+
+      HEALTH_KEY = 'throttle_machines:health'
+
       def initialize(options = {})
         @options = options
       end
 
+      def supports?(algorithm)
+        operations = ALGORITHM_OPERATIONS[algorithm]
+        return false unless operations
+
+        operations.all? { |operation| self.class.instance_method(operation).owner != Base }
+      end
+
       # Rate limiting operations
       def increment_counter(key, window, amount = 1)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #increment_counter"
       end
 
       def get_counter(key, window)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #get_counter"
       end
 
       def get_counter_ttl(key, window)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #get_counter_ttl"
       end
 
       def reset_counter(key, window)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #reset_counter"
       end
 
       # GCRA operations (atomic)
       def check_gcra_limit(key, emission_interval, delay_tolerance, ttl)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #check_gcra_limit"
       end
 
       def peek_gcra_limit(key, emission_interval, delay_tolerance)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #peek_gcra_limit"
       end
 
       # Token bucket operations (atomic)
       def check_token_bucket(key, capacity, refill_rate, ttl)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #check_token_bucket"
       end
 
       def peek_token_bucket(key, capacity, refill_rate)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #peek_token_bucket"
       end
 
       # Utility operations
       def clear(pattern = nil)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #clear"
       end
 
       def healthy?
-        raise NotImplementedError
+        get_counter(HEALTH_KEY, 1)
+        true
+      rescue StandardError
+        false
       end
 
       def with_timeout(timeout, &block)

data/lib/throttle_machines/storage/cache.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  module Storage
+    class Cache < Base
+      GLOB_SPECIALS = /[?\[\]\\]/
+
+      def initialize(options = {})
+        super
+        @cache = options[:cache_store] || (defined?(Rails) && Rails.cache)
+        raise ArgumentError, 'Cache storage requires a cache_store outside Rails' unless @cache
+
+        @prefix = options[:prefix] || 'throttle_machines'
+        @fail_closed = options.fetch(:fail_closed, false)
+      end
+
+      def increment_counter(key, window, amount = 1)
+        count = @cache.increment(window_key(key, window), amount, expires_in: window.to_f.ceil + 1)
+        count || (@fail_closed ? Float::INFINITY : 0)
+      end
+
+      def get_counter(key, window)
+        @cache.read(window_key(key, window), raw: true).to_i
+      end
+
+      def get_counter_ttl(_key, window)
+        window = positive_window(window)
+        window - (wall_time % window)
+      end
+
+      def reset_counter(key, window)
+        @cache.delete(window_key(key, window))
+      end
+
+      def clear(pattern = nil)
+        @cache.delete_matched(matcher_for("#{@prefix}:#{pattern || '*'}"))
+      rescue NotImplementedError
+        raise UnsupportedOperationError,
+              "#{@cache.class} cannot delete by pattern; reset limiters individually with Limiter#reset!"
+      end
+
+      def healthy?
+        !@cache.increment("#{@prefix}:health", 1, expires_in: 60).nil?
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def window_key(key, window)
+        window = positive_window(window)
+        "#{@prefix}:#{key}:#{window}:#{(wall_time / window).floor}"
+      end
+
+      def positive_window(window)
+        window = window.to_f
+        raise ArgumentError, "window must be positive, got #{window}" unless window.positive?
+
+        window
+      end
+
+      def matcher_for(glob)
+        return glob.gsub(GLOB_SPECIALS) { |char| "\\#{char}" } if @cache.respond_to?(:redis)
+
+        Regexp.new("^#{Regexp.escape(glob).gsub('\*', '.*')}")
+      end
+
+      def wall_time
+        Time.now.to_f
+      end
+    end
+  end
+end

data/lib/throttle_machines/unsupported_operation_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class UnsupportedOperationError < StandardError; end
+end

data/lib/throttle_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ThrottleMachines
-  VERSION = '0.3.3'
+  VERSION = '0.3.4'
 end

data/lib/throttle_machines.rb

@@ -159,6 +159,8 @@ module ThrottleMachines
       case symbol
       when :memory
         Storage::Memory.new
+      when :cache
+        Storage::Cache.new
       when :redis
         raise ArgumentError, 'Redis storage requires redis gem' unless defined?(Redis)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: throttle_machines
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -69,16 +69,16 @@ dependencies:
   name: breaker_machines
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.20'
+        version: 0.22.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.20'
+        version: 0.22.1
 - !ruby/object:Gem::Dependency
   name: chrono_machines
   requirement: !ruby/object:Gem::Requirement
@@ -185,6 +185,7 @@ files:
 - lib/throttle_machines/rack_middleware/throttle.rb
 - lib/throttle_machines/rack_middleware/track.rb
 - lib/throttle_machines/storage/base.rb
+- lib/throttle_machines/storage/cache.rb
 - lib/throttle_machines/storage/memory.rb
 - lib/throttle_machines/storage/null.rb
 - lib/throttle_machines/storage/redis.rb
@@ -194,6 +195,7 @@ files:
 - lib/throttle_machines/storage/redis/peek_token_bucket.lua
 - lib/throttle_machines/storage/redis/token_bucket.lua
 - lib/throttle_machines/throttled_error.rb
+- lib/throttle_machines/unsupported_operation_error.rb
 - lib/throttle_machines/version.rb
 homepage: https://github.com/seuros/throttle_machines
 licenses: