throttle_machines 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a080af0b8e5ed4c52fc3f7df63757a7b8a91beb76124f49ddd6ff06ae02e8072
-  data.tar.gz: f4ee5682bb2c846e4ec69364da967127285d186b379d76c2b378bdb99ff92675
+  metadata.gz: 96de7185407f842a40836226124ee468c5a0ad1095bac184203709c6266ec095
+  data.tar.gz: 6118f412afbd4bb20929ae3d441eb807cd63154cb9a4ac8b35a7ceb5e4421d0d
 SHA512:
-  metadata.gz: 7d10328c5affbb67291563d9190c7395b6800c2e9b7085789afcf7e891693c3d00116d5d63dc6bf634eb7b96e6c60e74e65118629702ca7bedc68e7867f90a21
-  data.tar.gz: eed2c6323e3ba2f52901ef5280d1fee89ca5e0a8d9f0e316c54ca7151e2870f452a5f59d30096b8d216aa37f4585beb96213ab5190f07d157d8ec31310d1ceb6
+  metadata.gz: 2f64ad8aa766a9e77186c9384807c6dece25d4c22779467bbcafc5b5b317e56cdca5cfdad5b9dd9f4c36ea9d3921a0f6d47c2baa82ec6565d579a6b417dec679
+  data.tar.gz: 83e7acf78d640b8bf3f6849f7c25c1446c49446885bd11ef334dbda4e7ba8dcc2efed5ac4e26cb9dc4def031fa1d25b1d62ae26860b8482d25c6397ba555feda

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/async_support.rb

@@ -22,26 +22,25 @@ module ThrottleMachines
     end
 
     def throttle_async(max_wait: nil, &block)
-      deadline = max_wait.nil? ? nil : ThrottleMachines.monotonic_time + max_wait.to_f
-
-      loop do
-        begin
-          throttle!
-        rescue ThrottledError => e
-          wait_time = [e.retry_after.to_f, 0.0].max
-
-          if deadline
-            remaining_wait = deadline - ThrottleMachines.monotonic_time
-            raise if remaining_wait <= 0 || wait_time > remaining_wait
+      caller_budget = DeadlineMachines.current
+
+      DeadlineMachines.with_deadline(max_wait) do |budget|
+        loop do
+          begin
+            throttle!
+          rescue ThrottledError => e
+            caller_budget&.check!
+            wait_time = [e.retry_after.to_f, 0.0].max
+            raise if budget.clamp_sleep(wait_time) < wait_time
+
+            sleep_for(wait_time)
+            next
           end
 
-          sleep_for(wait_time)
-          next
-        end
+          return block.call if block
 
-        return block.call if block
-
-        return true
+          return true
+        end
       end
     end
 

data/lib/throttle_machines/control.rb

@@ -27,7 +27,7 @@ module ThrottleMachines
     def retry_on_failure(times:, backoff: :exponential, base_delay: 1, max_delay: 60)
       @rules[:retry] = {
         max_attempts: times,
-        jitter: backoff,
+        backoff: backoff,
         base_delay: base_delay,
         max_delay: max_delay
       }
@@ -87,7 +87,8 @@ module ThrottleMachines
         max_attempts: @rules[:retry][:max_attempts],
         base_delay: @rules[:retry][:base_delay],
         max_delay: @rules[:retry][:max_delay],
-        jitter_factor: @rules[:retry][:jitter] == :exponential ? 1.0 : 0.0
+        backoff_strategy: @rules[:retry][:backoff],
+        jitter_factor: @rules[:retry][:backoff] == :exponential ? 1.0 : 0.0
       }
       @retrier = ChronoMachines::Executor.new(policy_options)
     end

data/lib/throttle_machines/hedged_request.rb

@@ -56,9 +56,9 @@ module ThrottleMachines
       @max_attempts.times do |attempt|
         # Schedule with delay
         future = if attempt.zero?
-                   Concurrent::Promises.future { yield(attempt) }
+                   Concurrent::Promises.future_on(@executor) { yield(attempt) }
                  else
-                   Concurrent::Promises.schedule(@delay * attempt) { yield(attempt) }
+                   Concurrent::Promises.schedule_on(@executor, @delay * attempt) { yield(attempt) }
                  end
 
         # Race to resolve first_result
@@ -88,9 +88,6 @@ module ThrottleMachines
       else
         first_result.value!
       end
-    ensure
-      # Cancel pending futures
-      futures.each { |f| f.cancel if f.pending? }
     end
 
     # Run async version

data/lib/throttle_machines/limiter.rb

@@ -10,6 +10,8 @@ module ThrottleMachines
       @period = period
       @algorithm = algorithm
       @storage = storage || ThrottleMachines.storage
+      validate_algorithm!
+      validate_rate!
     end
 
     def allow?
@@ -93,8 +95,10 @@ module ThrottleMachines
       case @algorithm
       when :fixed_window
         @storage.reset_counter(@key, @period)
-      else
-        @storage.clear("#{@key}*")
+      when :gcra
+        @storage.reset_gcra(@key)
+      when :token_bucket
+        @storage.reset_token_bucket(@key)
       end
     end
 
@@ -163,5 +167,22 @@ module ThrottleMachines
         retry_after: retry_after
       }
     end
+
+    private
+
+    def validate_rate!
+      raise ArgumentError, "limit must be positive, got #{@limit.inspect}" unless @limit.is_a?(Numeric) && @limit.positive?
+      raise ArgumentError, "period must be positive, got #{@period.inspect}" unless @period.is_a?(Numeric) && @period.positive?
+    end
+
+    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,58 +3,94 @@
 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 reset_gcra],
+        token_bucket: %i[check_token_bucket peek_token_bucket reset_token_bucket]
+      }.freeze
+
+      HEALTH_KEY = 'throttle_machines:health'
+
+      # What a backend puts between a limiter's key and the state it appends.
+      KEY_SEPARATOR = ':'
+
+      GLOB_WILDCARD = '*'
+      GLOB_SPECIALS = /[*?\[\]\\]/
+
       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
+
+      def reset_gcra(key)
+        raise NotImplementedError, "#{self.class} does not implement #reset_gcra"
       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
+
+      def reset_token_bucket(key)
+        raise NotImplementedError, "#{self.class} does not implement #reset_token_bucket"
       end
 
       # Utility operations
       def clear(pattern = nil)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class} does not implement #clear"
+      end
+
+      # Deletes every entry this key owns, whatever algorithm wrote it.
+      def reset_key(key)
+        raise NotImplementedError, "#{self.class} does not implement #reset_key"
       end
 
       def healthy?
-        raise NotImplementedError
+        get_counter(HEALTH_KEY, 1)
+        true
+      rescue StandardError
+        false
       end
 
       def with_timeout(timeout, &block)
-        Timeout.timeout(timeout, &block)
-      rescue Timeout::Error
-        nil
+        DeadlineMachines.check!
+        Timeout.timeout(DeadlineMachines.clamp_sleep(timeout), &block)
       end
 
       # Rounding slack for time comparisons, in units of the clock's precision.
@@ -63,6 +99,18 @@ module ThrottleMachines
 
       protected
 
+      def owned_by?(stored_key, key)
+        stored_key == key || stored_key.start_with?("#{key}#{KEY_SEPARATOR}")
+      end
+
+      def escape_glob(literal)
+        literal.gsub(GLOB_SPECIALS) { |char| "\\#{char}" }
+      end
+
+      def glob_to_regexp(glob)
+        Regexp.new("\\A#{Regexp.escape(glob).gsub(Regexp.escape(GLOB_WILDCARD), '.*')}\\z")
+      end
+
       # Times are running sums and differences of float seconds, so an
       # on-schedule arrival can miss an exact boundary by a few ulps. The slack
       # scales with the clock's magnitude.

data/lib/throttle_machines/storage/cache.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  module Storage
+    class Cache < Base
+      # The wildcard a caller's pattern keeps; everything else is a literal.
+      PATTERN_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)
+        delete_matched(matcher_for("#{@prefix}#{KEY_SEPARATOR}#{pattern || GLOB_WILDCARD}"))
+      end
+
+      # The window and the bucket index a counter was written under are unknown
+      # here, so the counters go by a prefix of the key's own namespace.
+      def reset_key(key)
+        delete_matched(prefix_matcher("#{@prefix}#{KEY_SEPARATOR}#{key}#{KEY_SEPARATOR}"))
+      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 delete_matched(matcher)
+        @cache.delete_matched(matcher)
+      rescue NotImplementedError
+        raise UnsupportedOperationError,
+              "#{@cache.class} cannot delete by pattern; reset limiters individually with Limiter#reset!"
+      end
+
+      def matcher_for(glob)
+        return glob.gsub(PATTERN_SPECIALS) { |char| "\\#{char}" } if @cache.respond_to?(:redis)
+
+        Regexp.new("^#{Regexp.escape(glob).gsub(Regexp.escape(GLOB_WILDCARD), '.*')}")
+      end
+
+      def prefix_matcher(literal)
+        return "#{escape_glob(literal)}#{GLOB_WILDCARD}" if @cache.respond_to?(:redis)
+
+        # ActiveSupport only prepends a store's namespace to a `^` source.
+        Regexp.new("^#{Regexp.escape(literal)}")
+      end
+
+      def wall_time
+        Time.now.to_f
+      end
+    end
+  end
+end

data/lib/throttle_machines/storage/memory.rb

@@ -7,37 +7,36 @@ module ThrottleMachines
     class Memory < Base
       DEFAULT_MAX_KEYS = 65_536
       CAPACITY_RETRY_AFTER = 1.0
+      DEFAULT_CLEANUP_INTERVAL = 60
+      DEFAULT_LOCK_POOL_SIZE = 32
+      SHUTDOWN_GRACE = 1.0
 
       def initialize(options = {})
         super
-        @max_keys = options.fetch(:max_keys, DEFAULT_MAX_KEYS)
-        unless @max_keys.is_a?(Integer) && @max_keys >= 0
-          raise ArgumentError, 'max_keys must be a non-negative integer'
-        end
+        max_keys = options.fetch(:max_keys, DEFAULT_MAX_KEYS)
+        raise ArgumentError, 'max_keys must be a non-negative integer' unless max_keys.is_a?(Integer) && max_keys >= 0
+
+        @state = State.new(
+          max_keys: max_keys,
+          lock_pool_size: options[:lock_pool_size] || DEFAULT_LOCK_POOL_SIZE,
+          cleanup_interval: options[:cleanup_interval] || DEFAULT_CLEANUP_INTERVAL
+        )
+        @counters = @state.counters
+        @gcra_states = @state.gcra_states
+        @token_buckets = @state.token_buckets
 
-        @stored_keys = 0
-        @capacity_lock = Mutex.new
         @capacity_cleanup_lock = Mutex.new
         @next_capacity_cleanup_at = -Float::INFINITY
-        @counters = Concurrent::Hash.new
-        @gcra_states = Concurrent::Hash.new
-        @token_buckets = Concurrent::Hash.new
-
-        # Use a striped lock pattern - pool of locks for fine-grained concurrency
-        @lock_pool_size = options[:lock_pool_size] || 32
-        @locks = Array.new(@lock_pool_size) { Concurrent::ReadWriteLock.new }
+        @cleanup_thread = nil
 
-        # Background cleanup thread
-        @cleanup_interval = options[:cleanup_interval] || 60
-        @shutdown = false
-        @cleanup_thread = start_cleanup_thread if options[:auto_cleanup] != false
+        return if options[:auto_cleanup] == false
 
-        # Ensure cleanup on garbage collection
+        @cleanup_thread = @state.start_cleanup_thread
         ObjectSpace.define_finalizer(self, self.class.finalizer(@cleanup_thread))
       end
 
       def self.finalizer(cleanup_thread)
-        proc { cleanup_thread&.kill }
+        proc { cleanup_thread.kill }
       end
 
       # Rate limiting operations
@@ -113,7 +112,7 @@ module ThrottleMachines
 
           {
             allowed: allow,
-            retry_after: allow ? 0 : (tat - now - delay_tolerance),
+            retry_after: allow ? 0.0 : (tat - now - delay_tolerance),
             tat: tat
           }
         end
@@ -132,12 +131,16 @@ module ThrottleMachines
 
           {
             allowed: allow,
-            retry_after: allow ? 0 : (tat - now - delay_tolerance),
+            retry_after: allow ? 0.0 : (tat - now - delay_tolerance),
             tat: tat
           }
         end
       end
 
+      def reset_gcra(key)
+        with_write_lock(key) { delete_entry(@gcra_states, key) }
+      end
+
       # Token bucket operations (atomic simulation)
       def check_token_bucket(key, capacity, refill_rate, ttl)
         reclaim_capacity
@@ -160,7 +163,7 @@ module ThrottleMachines
 
             {
               allowed: true,
-              retry_after: 0,
+              retry_after: 0.0,
               tokens_remaining: bucket[:tokens].floor
             }
           else
@@ -191,7 +194,7 @@ module ThrottleMachines
           if token_available?(current_tokens, now, refill_rate)
             {
               allowed: true,
-              retry_after: 0,
+              retry_after: 0.0,
               tokens_remaining: [current_tokens - 1, 0].max.floor
             }
           else
@@ -206,65 +209,58 @@ module ThrottleMachines
         end
       end
 
+      def reset_token_bucket(key)
+        with_write_lock(key) { delete_entry(@token_buckets, key) }
+      end
+
       # No circuit breaker operations here: breaker state is owned by BreakerMachines
 
       # Utility operations
       def clear(pattern = nil)
         if pattern
-          regex = Regexp.new(pattern.gsub('*', '.*'))
-
-          # Clear matching keys from all stores
-          [@counters, @gcra_states, @token_buckets].each do |store|
-            store.keys.each do |k|
-              with_write_lock(k) { delete_entry(store, k) } if k&.match?(regex)
-            end
-          end
+          regex = glob_to_regexp(pattern)
+          delete_where { |stored_key| stored_key.match?(regex) }
         else
-          @capacity_lock.synchronize do
-            @counters.clear
-            @gcra_states.clear
-            @token_buckets.clear
-            @stored_keys = 0
-          end
+          @state.clear_all
         end
       end
 
+      def reset_key(key)
+        delete_where { |stored_key| owned_by?(stored_key, key) }
+      end
+
       def healthy?
         true
       end
 
       def shutdown
-        @shutdown = true
-        @cleanup_thread&.join(1) # Wait up to 1 second for graceful shutdown
-        @cleanup_thread&.kill if @cleanup_thread&.alive?
+        @state.shutdown!
+        @cleanup_thread&.join(SHUTDOWN_GRACE)
+        @cleanup_thread&.kill
         @cleanup_thread = nil
+        ObjectSpace.undefine_finalizer(self)
       end
 
       private
 
-      # Called with the key's write lock held. The short admission lock makes
-      # the cap atomic across stripes and all three stores.
-      def store_entry(store, key, value)
-        @capacity_lock.synchronize do
-          new_key = !store.key?(key)
-          return false if new_key && @stored_keys >= @max_keys
-
-          store[key] = value
-          @stored_keys += 1 if new_key
-          true
+      def delete_where
+        @state.stores.each do |store|
+          store.keys.each do |stored_key|
+            with_write_lock(stored_key) { delete_entry(store, stored_key) } if yield(stored_key)
+          end
         end
       end
 
+      def store_entry(store, key, value)
+        @state.store_entry(store, key, value)
+      end
+
       def delete_entry(store, key)
-        @capacity_lock.synchronize do
-          value = store.delete(key)
-          @stored_keys -= 1 if value
-          value
-        end
+        @state.delete_entry(store, key)
       end
 
       def capacity_available?(store, key)
-        @capacity_lock.synchronize { store.key?(key) || @stored_keys < @max_keys }
+        @state.capacity_available?(store, key)
       end
 
       def capacity_gcra_refusal(now, delay_tolerance)
@@ -279,7 +275,7 @@ module ThrottleMachines
       # cleanup at most once per second, even with auto_cleanup disabled.
       # Rejected identity sprays must not trigger a full scan on every call.
       def reclaim_capacity
-        return unless @capacity_lock.synchronize { @stored_keys >= @max_keys }
+        return unless @state.saturated?
         return unless @capacity_cleanup_lock.try_lock
 
         begin
@@ -294,49 +290,133 @@ module ThrottleMachines
       end
 
       def with_read_lock(key, &block)
-        lock_for(key).with_read_lock(&block)
+        @state.with_read_lock(key, &block)
       end
 
       def with_write_lock(key, &block)
-        lock_for(key).with_write_lock(&block)
+        @state.with_write_lock(key, &block)
       end
 
-      def lock_for(key)
-        # Hash key to determine which lock to use
-        index = key.hash.abs % @lock_pool_size
-        @locks[index]
+      def clean_expired_entries
+        @state.clean_expired_entries
       end
 
-      def start_cleanup_thread
-        Thread.new do
-          loop do
-            break if @shutdown
+      # Holds every map, lock and counter the cleanup worker sweeps.
+      class State
+        attr_reader :counters, :gcra_states, :token_buckets
+
+        def initialize(max_keys:, lock_pool_size:, cleanup_interval:)
+          @max_keys = max_keys
+          @cleanup_interval = cleanup_interval
+          @stored_keys = 0
+          @capacity_lock = Mutex.new
+          @counters = Concurrent::Hash.new
+          @gcra_states = Concurrent::Hash.new
+          @token_buckets = Concurrent::Hash.new
+
+          # Use a striped lock pattern - pool of locks for fine-grained concurrency
+          @lock_pool_size = lock_pool_size
+          @locks = Array.new(lock_pool_size) { Concurrent::ReadWriteLock.new }
+          @shutdown = false
+        end
+
+        def start_cleanup_thread
+          Thread.new do
+            loop do
+              break if @shutdown
 
-            sleep @cleanup_interval
-            break if @shutdown
+              sleep @cleanup_interval
+              break if @shutdown
 
-            clean_expired_entries
+              clean_expired_entries
+            end
           end
         end
-      end
 
-      def clean_expired_entries
-        now = current_time
-
-        [@counters, @gcra_states, @token_buckets].each do |store|
-          store.keys.each do |key|
-            with_write_lock(key) do
-              # Re-read under the lock: a writer may have refreshed the TTL.
-              data = store[key]
-              delete_entry(store, key) if data && data[:expires_at] && data[:expires_at] <= now
+        def shutdown!
+          @shutdown = true
+        end
+
+        def stores
+          [@counters, @gcra_states, @token_buckets]
+        end
+
+        def stored_keys
+          @capacity_lock.synchronize { @stored_keys }
+        end
+
+        def saturated?
+          @capacity_lock.synchronize { @stored_keys >= @max_keys }
+        end
+
+        def with_read_lock(key, &block)
+          lock_for(key).with_read_lock(&block)
+        end
+
+        def with_write_lock(key, &block)
+          lock_for(key).with_write_lock(&block)
+        end
+
+        # Called with the key's write lock held. The short admission lock makes
+        # the cap atomic across stripes and all three stores.
+        def store_entry(store, key, value)
+          @capacity_lock.synchronize do
+            new_key = !store.key?(key)
+            return false if new_key && @stored_keys >= @max_keys
+
+            store[key] = value
+            @stored_keys += 1 if new_key
+            true
+          end
+        end
+
+        def delete_entry(store, key)
+          @capacity_lock.synchronize do
+            value = store.delete(key)
+            @stored_keys -= 1 if value
+            value
+          end
+        end
+
+        def capacity_available?(store, key)
+          @capacity_lock.synchronize { store.key?(key) || @stored_keys < @max_keys }
+        end
+
+        def clear_all
+          @capacity_lock.synchronize do
+            @counters.clear
+            @gcra_states.clear
+            @token_buckets.clear
+            @stored_keys = 0
+          end
+        end
+
+        def clean_expired_entries
+          now = ThrottleMachines.monotonic_time
+
+          stores.each do |store|
+            store.keys.each do |key|
+              with_write_lock(key) do
+                # Re-read under the lock: a writer may have refreshed the TTL.
+                data = store[key]
+                delete_entry(store, key) if data && data[:expires_at] && data[:expires_at] <= now
+              end
             end
           end
+
+          # No breaker state cleanup: breaker state is managed by BreakerMachines
+        rescue StandardError => e
+          # Log error but don't crash cleanup thread
+          warn "ThrottleMachines: Cleanup error: #{e.message}"
         end
 
-        # No breaker state cleanup: breaker state is managed by BreakerMachines
-      rescue StandardError => e
-        # Log error but don't crash cleanup thread
-        warn "ThrottleMachines: Cleanup error: #{e.message}"
+        private
+
+        def lock_for(key)
+          # Hash key to determine which lock to use
+          index = key.hash.abs % @lock_pool_size
+          @locks[index]
+        end
       end
     end
   end

data/lib/throttle_machines/storage/null.rb

@@ -37,6 +37,10 @@ module ThrottleMachines
         }
       end
 
+      def reset_gcra(_key)
+        true
+      end
+
       # Token bucket operations
       def check_token_bucket(_key, capacity, _refill_rate, _ttl)
         {
@@ -54,11 +58,19 @@ module ThrottleMachines
         }
       end
 
+      def reset_token_bucket(_key)
+        true
+      end
+
       # Utility operations
       def clear(_pattern = nil)
         true
       end
 
+      def reset_key(_key)
+        true
+      end
+
       def healthy?
         true
       end

data/lib/throttle_machines/storage/redis.rb

@@ -22,6 +22,9 @@ module ThrottleMachines
       PEEK_GCRA_SHA = Digest::SHA1.hexdigest(PEEK_GCRA_SCRIPT)
       PEEK_TOKEN_BUCKET_SHA = Digest::SHA1.hexdigest(PEEK_TOKEN_BUCKET_SCRIPT)
 
+      # Keys a single SCAN round trip asks for.
+      SCAN_BATCH = 100
+
       def initialize(options = {})
         super
         @redis = options[:redis] || options[:client] || options[:pool]
@@ -74,6 +77,10 @@ module ThrottleMachines
         }
       end
 
+      def reset_gcra(key)
+        delete_state(key)
+      end
+
       # Token bucket operations (atomic via Lua)
       def check_token_bucket(key, capacity, refill_rate, ttl)
         result = run_script(TOKEN_BUCKET_SCRIPT, TOKEN_BUCKET_SHA,
@@ -83,6 +90,10 @@ module ThrottleMachines
         token_bucket_result(result, refill_rate)
       end
 
+      def reset_token_bucket(key)
+        delete_state(key)
+      end
+
       # Peek methods for non-consuming checks
       def peek_gcra_limit(key, emission_interval, delay_tolerance)
         now = current_time
@@ -112,17 +123,14 @@ module ThrottleMachines
 
       # Utility operations
       def clear(pattern = nil)
-        # Use SCAN instead of KEYS to avoid blocking in production
-        cursor = '0'
-        scan_pattern = pattern ? prefixed(pattern) : "#{@prefix}*"
+        delete_matching(pattern ? prefixed(pattern) : "#{@prefix}#{GLOB_WILDCARD}")
+      end
 
-        with_redis do |redis|
-          loop do
-            cursor, keys = redis.scan(cursor, match: scan_pattern, count: 100)
-            redis.del(*keys) unless keys.empty?
-            break if cursor == '0'
-          end
-        end
+      # The window a counter was written under is unknown here, so the counters
+      # go by a glob over the key's own namespace; the key itself is a literal.
+      def reset_key(key)
+        delete_state(key)
+        delete_matching("#{escape_glob(prefixed(key))}#{KEY_SEPARATOR}#{GLOB_WILDCARD}")
       end
 
       def healthy?
@@ -133,6 +141,23 @@ module ThrottleMachines
 
       private
 
+      def delete_state(key)
+        with_redis { |r| r.del(prefixed(key)) }
+      end
+
+      # SCAN instead of KEYS, to avoid blocking in production.
+      def delete_matching(scan_pattern)
+        cursor = '0'
+
+        with_redis do |redis|
+          loop do
+            cursor, keys = redis.scan(cursor, match: scan_pattern, count: SCAN_BATCH)
+            redis.del(*keys) unless keys.empty?
+            break if cursor == '0'
+          end
+        end
+      end
+
       # `result` is [allowed, tokens]: the balance after an admission, or the
       # fractional balance a refusal waits on. Matches Storage::Memory.
       def token_bucket_result(result, refill_rate)

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.4.0'
 end

data/lib/throttle_machines.rb

@@ -7,6 +7,7 @@ require 'active_support/core_ext/class/attribute'
 
 # Ecosystem dependencies
 require 'chrono_machines'
+require 'deadline_machines'
 require 'breaker_machines'
 
 # Set up Zeitwerk loader
@@ -75,7 +76,7 @@ module ThrottleMachines
 
     def reset!(key = nil)
       if key
-        storage.clear("#{key}*")
+        storage.reset_key(key)
       else
         storage.clear
         # Reset storage instance to force recreation with defaults
@@ -98,19 +99,16 @@ module ThrottleMachines
     end
 
     def break_circuit(key, failures:, timeout:, &block)
-      # Delegate to BreakerMachines; use reset_timeout for open duration
-      breaker = BreakerMachines::Circuit.new(
-        key,
-        failure_threshold: failures,
-        reset_timeout: timeout
-      )
-      breaker.call(&block)
+      BreakerMachines::Registry.instance.get_or_create_dynamic_circuit(
+        key, self, { failure_threshold: failures, reset_timeout: timeout }
+      ).call(&block)
     end
 
     def retry_with(max_attempts: 3, backoff: :exponential, &block)
       # Delegate to chrono_machines
       policy_options = {
         max_attempts: max_attempts,
+        backoff_strategy: backoff,
         jitter_factor: backoff == :exponential ? 1.0 : 0.0
       }
       ChronoMachines.retry(policy_options, &block)
@@ -159,6 +157,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.4.0
 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
@@ -93,6 +93,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: deadline_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -185,6 +199,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 +209,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: