throttle_machines 0.3.1-aarch64-linux → 0.3.4-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 509526a077fdf01abb15d9abe3f987b47860cfc2809c5ed6e013f14892419c88
-  data.tar.gz: ee7ceb36ff48952212f86594d91fc31e670dd87989c82f7097a4cb2c671d3e4d
+  metadata.gz: cf82a5943916b99c3c670f1a40f8b56846dd2271d0b1e52ac8d360b9f179980b
+  data.tar.gz: 27fac49e6a413ee51444304bdfaa048f992bb2ef6c28a5a4b06b2d9ac956bd94
 SHA512:
-  metadata.gz: 1545196f2c54252b9e7388d508e99b4449b2249a4d3eda4a02fe19fd73a87ae9498bccacc589822e0e20434c6d83bc4b941869ec0755275be4717d545d554197
-  data.tar.gz: 57a55483b2b3af696c09da7fe9998b260ac3486054cfccdb23feba512a06c9644eece4eac4ec8aa54f84946103a330542a3cf1ea9ac6e4a91dfa2cf4f7318b58
+  metadata.gz: c797ad1427d795c2003376798713b0c7ba9af1b63b3d927931e617a626b0fee4aed5febaac367f2ebf15d8fd5b4f7fa2f35e42f7df1bab64903c90c527ab180e
+  data.tar.gz: f6f38cccc1f50c4cac5b9ba62167e51daf99ce5fe09b18517a63d1f06563426ec35bfbb43780b981b19bda526795ba92628dad3edfbe09ccd5f7fd11d6c86403

data/README.md

@@ -100,6 +100,60 @@ end
 
 ---
 
+## Bounded in-memory storage
+
+The memory backend tracks at most **65536 entries**, shared across fixed-window
+counters, GCRA states, and token buckets, including when native speedups are loaded.
+
+```ruby
+ThrottleMachines.storage = ThrottleMachines::Storage::Memory.new(max_keys: 10_000)
+```
+
+When full, expired entries are reclaimed before admission. If no slot is
+available, new identities are throttled; active identities are never evicted
+to make room and can continue under their existing limits. Peeks also fail
+closed for untrackable identities. Capacity refusals use a one-second retry
+hint, not a reservation. At saturation, on-demand expiry scans run at most
+once per second, even with `auto_cleanup: false`.
+
+`max_keys` must be a non-negative integer; zero denies all identities. For
+direct storage callers, an untrackable fixed-window counter reads/increments
+as `Float::INFINITY` so it cannot pass a finite rate limit.
+
+This bounds entry count, not bytes: also bound untrusted identity lengths.
+Redis storage uses TTLs but has no application-level key cap; configure Redis
+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/native_speedup.rb

@@ -21,6 +21,7 @@ begin
       # Native GCRA implementation using Rust.
       module NativeGCRA
         def check_gcra_limit(key, emission_interval, delay_tolerance, ttl)
+          reclaim_capacity
           with_write_lock(key) do
             now = current_time
             state = @gcra_states[key] || { tat: 0.0 }
@@ -30,15 +31,20 @@ begin
               state[:tat], now, emission_interval, delay_tolerance
             ) => { allowed:, state: new_tat, retry_after: }
 
-            @gcra_states[key] = { tat: new_tat, expires_at: now + ttl } if allowed
+            if allowed && !store_entry(@gcra_states, key, { tat: new_tat, expires_at: now + ttl })
+              return capacity_gcra_refusal(now, delay_tolerance)
+            end
 
             { allowed: allowed, retry_after: retry_after, tat: new_tat }
           end
         end
 
         def peek_gcra_limit(key, _emission_interval, delay_tolerance)
+          reclaim_capacity
           with_read_lock(key) do
             now = current_time
+            return capacity_gcra_refusal(now, delay_tolerance) unless capacity_available?(@gcra_states, key)
+
             state = @gcra_states[key] || { tat: 0.0 }
 
             # Rust does the math
@@ -54,6 +60,7 @@ begin
       # Native Token Bucket implementation using Rust.
       module NativeTokenBucket
         def check_token_bucket(key, capacity, refill_rate, ttl)
+          reclaim_capacity
           with_write_lock(key) do
             now = current_time
             bucket = @token_buckets[key] || { tokens: capacity, last_refill: now }
@@ -64,7 +71,9 @@ begin
             ) => { allowed:, state: new_tokens, retry_after: }
 
             if allowed
-              @token_buckets[key] = { tokens: new_tokens, last_refill: now, expires_at: now + ttl }
+              unless store_entry(@token_buckets, key, { tokens: new_tokens, last_refill: now, expires_at: now + ttl })
+                return capacity_token_bucket_refusal
+              end
             end
 
             { allowed: allowed, retry_after: retry_after, tokens_remaining: new_tokens.floor }
@@ -72,8 +81,11 @@ begin
         end
 
         def peek_token_bucket(key, capacity, refill_rate)
+          reclaim_capacity
           with_read_lock(key) do
             now = current_time
+            return capacity_token_bucket_refusal unless capacity_available?(@token_buckets, key)
+
             bucket = @token_buckets[key] || { tokens: capacity, last_refill: now }
 
             # Rust does the math

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/storage/memory.rb

@@ -5,8 +5,20 @@ require 'concurrent'
 module ThrottleMachines
   module Storage
     class Memory < Base
+      DEFAULT_MAX_KEYS = 65_536
+      CAPACITY_RETRY_AFTER = 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
+
+        @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
@@ -31,6 +43,7 @@ module ThrottleMachines
       # Rate limiting operations
       def increment_counter(key, window, amount = 1)
         window_key = "#{key}:#{window}"
+        reclaim_capacity
 
         with_write_lock(window_key) do
           now = current_time
@@ -40,22 +53,24 @@ module ThrottleMachines
           if counter.nil? || counter[:expires_at] <= now
             # Create or reset counter atomically
             new_count = amount
-            @counters[window_key] = { count: new_count, expires_at: now + window }
+            stored = store_entry(@counters, window_key, { count: new_count, expires_at: now + window })
           else
             # Increment existing counter atomically
             new_count = counter[:count] + amount
-            @counters[window_key] = { count: new_count, expires_at: counter[:expires_at] }
+            stored = store_entry(@counters, window_key, { count: new_count, expires_at: counter[:expires_at] })
           end
-          new_count
+          # An untrackable counter must never look like an admitted request.
+          stored ? new_count : Float::INFINITY
         end
       end
 
       def get_counter(key, window)
         window_key = "#{key}:#{window}"
+        reclaim_capacity
 
         with_read_lock(window_key) do
           counter = @counters[window_key]
-          return 0 unless counter
+          return capacity_available?(@counters, window_key) ? 0 : Float::INFINITY unless counter
           return 0 if counter[:expires_at] <= current_time
 
           counter[:count]
@@ -67,7 +82,7 @@ module ThrottleMachines
 
         with_read_lock(window_key) do
           counter = @counters[window_key]
-          return 0 unless counter
+          return capacity_available?(@counters, window_key) ? 0 : CAPACITY_RETRY_AFTER unless counter
 
           ttl = counter[:expires_at] - current_time
           [ttl, 0].max
@@ -76,11 +91,12 @@ module ThrottleMachines
 
       def reset_counter(key, window)
         window_key = "#{key}:#{window}"
-        with_write_lock(window_key) { @counters.delete(window_key) }
+        with_write_lock(window_key) { delete_entry(@counters, window_key) }
       end
 
       # GCRA operations (atomic simulation)
       def check_gcra_limit(key, emission_interval, delay_tolerance, ttl)
+        reclaim_capacity
         with_write_lock(key) do
           now = current_time
           state = @gcra_states[key] || { tat: 0.0 }
@@ -90,7 +106,9 @@ module ThrottleMachines
 
           if allow
             new_tat = tat + emission_interval
-            @gcra_states[key] = { tat: new_tat, expires_at: now + ttl }
+            unless store_entry(@gcra_states, key, { tat: new_tat, expires_at: now + ttl })
+              return capacity_gcra_refusal(now, delay_tolerance)
+            end
           end
 
           {
@@ -102,8 +120,11 @@ module ThrottleMachines
       end
 
       def peek_gcra_limit(key, _emission_interval, delay_tolerance)
+        reclaim_capacity
         with_read_lock(key) do
           now = current_time
+          return capacity_gcra_refusal(now, delay_tolerance) unless capacity_available?(@gcra_states, key)
+
           state = @gcra_states[key] || { tat: 0.0 }
 
           tat = [state[:tat], now].max
@@ -119,6 +140,7 @@ module ThrottleMachines
 
       # Token bucket operations (atomic simulation)
       def check_token_bucket(key, capacity, refill_rate, ttl)
+        reclaim_capacity
         with_write_lock(key) do
           now = current_time
           bucket = @token_buckets[key] || { tokens: capacity, last_refill: now }
@@ -132,7 +154,9 @@ module ThrottleMachines
           # Check if we can consume a token
           if token_available?(bucket[:tokens], now, refill_rate)
             bucket[:tokens] = [bucket[:tokens] - 1, 0.0].max
-            @token_buckets[key] = bucket.merge(expires_at: now + ttl)
+            unless store_entry(@token_buckets, key, bucket.merge(expires_at: now + ttl))
+              return capacity_token_bucket_refusal
+            end
 
             {
               allowed: true,
@@ -152,8 +176,11 @@ module ThrottleMachines
       end
 
       def peek_token_bucket(key, capacity, refill_rate)
+        reclaim_capacity
         with_read_lock(key) do
           now = current_time
+          return capacity_token_bucket_refusal unless capacity_available?(@token_buckets, key)
+
           bucket = @token_buckets[key] || { tokens: capacity, last_refill: now }
 
           # Calculate tokens without modifying state
@@ -188,14 +215,17 @@ module ThrottleMachines
 
           # Clear matching keys from all stores
           [@counters, @gcra_states, @token_buckets].each do |store|
-            store.each_key do |k|
-              store.delete(k) if k&.match?(regex)
+            store.keys.each do |k|
+              with_write_lock(k) { delete_entry(store, k) } if k&.match?(regex)
             end
           end
         else
-          @counters.clear
-          @gcra_states.clear
-          @token_buckets.clear
+          @capacity_lock.synchronize do
+            @counters.clear
+            @gcra_states.clear
+            @token_buckets.clear
+            @stored_keys = 0
+          end
         end
       end
 
@@ -212,6 +242,57 @@ module ThrottleMachines
 
       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
+        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 capacity_gcra_refusal(now, delay_tolerance)
+        { allowed: false, retry_after: CAPACITY_RETRY_AFTER, tat: now + delay_tolerance + CAPACITY_RETRY_AFTER }
+      end
+
+      def capacity_token_bucket_refusal
+        { allowed: false, retry_after: CAPACITY_RETRY_AFTER, tokens_remaining: 0 }
+      end
+
+      # Run before taking any striped lock. At saturation, attempt expiry
+      # 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 @capacity_cleanup_lock.try_lock
+
+        begin
+          now = current_time
+          return if now < @next_capacity_cleanup_at
+
+          @next_capacity_cleanup_at = now + CAPACITY_RETRY_AFTER
+          clean_expired_entries
+        ensure
+          @capacity_cleanup_lock.unlock
+        end
+      end
+
       def with_read_lock(key, &block)
         lock_for(key).with_read_lock(&block)
       end
@@ -242,19 +323,14 @@ module ThrottleMachines
       def clean_expired_entries
         now = current_time
 
-        # Clean expired counters
-        @counters.each_pair do |key, data|
-          with_write_lock(key) { @counters.delete(key) } if data[:expires_at] && data[:expires_at] <= now
-        end
-
-        # Clean expired GCRA states
-        @gcra_states.each_pair do |key, data|
-          with_write_lock(key) { @gcra_states.delete(key) } if data[:expires_at] && data[:expires_at] <= now
-        end
-
-        # Clean expired token buckets
-        @token_buckets.each_pair do |key, data|
-          with_write_lock(key) { @token_buckets.delete(key) } if data[:expires_at] && data[:expires_at] <= now
+        [@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
+            end
+          end
         end
 
         # No breaker state cleanup: breaker state is managed by BreakerMachines

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.1'
+  VERSION = '0.3.4'
 end

data/lib/throttle_machines.rb

@@ -12,6 +12,7 @@ require 'breaker_machines'
 # Set up Zeitwerk loader
 loader = Zeitwerk::Loader.for_gem
 loader.ignore("#{__dir__}/throttle_machines/engine.rb") unless defined?(Rails::Engine)
+loader.ignore("#{__dir__}/throttle_machines/native_speedup.rb")
 loader.setup
 
 module ThrottleMachines
@@ -158,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.1
+  version: 0.3.4
 platform: aarch64-linux
 authors:
 - Abdelkader Boudih
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-14 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