throttle_machines 0.3.3-x86_64-linux → 0.3.4-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8094e1210ce074e1bec5f730d483a1fd3968ffcc3b3cb10b2c1705313a6c3fee
-  data.tar.gz: 415ff2e1267150c4c466545cfeefe01e9ea30ba6502ddc7e510526bfcbe2679f
+  metadata.gz: 2c66ed002f19fead80fd931c2fef895b7ac3778437d72d9ff01642b1876ae7e4
+  data.tar.gz: 364c295404364d6206048e7a7f350907400450cfd47e73cbcd832294f00aa592
 SHA512:
-  metadata.gz: b1024d836469d3500560e115232ed349e72b584e734f1ee2d5c39c399c2a760274662383bb7d20f82b104cd2742216f6634e4c590bb7f4335158fa5bf1711220
-  data.tar.gz: 1ea545b6198221294e78abeb5240741d26d3d36f61581610fe508a21e4a32413a7596079d9cbd4973028bfa696262918faff497b6c0eaecfdcb90d4414c80056
+  metadata.gz: e73aacb0fadd1522578b92a81dc86e1a5ec3af3b15389d01558bc3030c90e84ced71f0a82404bd5fb07ac93e6b8e999912659263b70f367c9d83de22c2c3ef7f
+  data.tar.gz: 368c382b90c4621b237dac12fed6e8ba86198023e6b351ab3db591b76b33672942e0b3faf68124bc725ebf491ae81a6a3ece8731c41c601ffef80fb4ba9c17a8

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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: throttle_machines
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: x86_64-linux
 authors:
 - Abdelkader Boudih
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-27 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -70,16 +70,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
@@ -172,6 +172,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
@@ -181,6 +182,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
 - lib/throttle_machines_native/throttle_machines_native.so
 homepage: https://github.com/seuros/throttle_machines