throttle_machines 0.3.0 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3b31d5fbfe9776c3fce6b2dfa90a77932536992f5a182313bb36b12f58d04af
-  data.tar.gz: db51e8f4c56ac00ce340debbc10202614ec68bf2d3dc64596705c529897df6fd
+  metadata.gz: a080af0b8e5ed4c52fc3f7df63757a7b8a91beb76124f49ddd6ff06ae02e8072
+  data.tar.gz: f4ee5682bb2c846e4ec69364da967127285d186b379d76c2b378bdb99ff92675
 SHA512:
-  metadata.gz: e4ffd7243f769547032d4ec7e15c7e390142e0b22f178a6eff6f651d10fd7fba31389bb80f6ff843c81ce1491528c1e70c9e57c4c7f02da6d4d71b61d0ed3bcc
-  data.tar.gz: 28e290c3e45461f6491e156594c4625be6b6073d8856a5448038c2a872323ecfa1532d31deb18dac35dd9b8dfa91614f6cb3df076dbaaba122e102d7efcff265
+  metadata.gz: 7d10328c5affbb67291563d9190c7395b6800c2e9b7085789afcf7e891693c3d00116d5d63dc6bf634eb7b96e6c60e74e65118629702ca7bedc68e7867f90a21
+  data.tar.gz: eed2c6323e3ba2f52901ef5280d1fee89ca5e0a8d9f0e316c54ca7151e2870f452a5f59d30096b8d216aa37f4585beb96213ab5190f07d157d8ec31310d1ceb6

data/README.md

@@ -100,6 +100,32 @@ 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.
+
+---
+
 ## 🌠 The Ultra-Thin Philosophy
 
 Like the best spacecraft, ThrottleMachines follows the principle of **ultra-thin design**:

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

@@ -57,8 +57,28 @@ module ThrottleMachines
         nil
       end
 
+      # Rounding slack for time comparisons, in units of the clock's precision.
+      # Matches the native core.
+      SLACK_ULPS = 64
+
       protected
 
+      # 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.
+      def rounding_slack(time)
+        Float::EPSILON * SLACK_ULPS * [time.abs, 1.0].max
+      end
+
+      def gcra_allowed?(tat, now, delay_tolerance)
+        tat - now <= delay_tolerance + rounding_slack(tat)
+      end
+
+      # Whether a token is available, allowing for rounding in the refill.
+      def token_available?(tokens, now, refill_rate)
+        tokens >= 1 - (rounding_slack(now) * refill_rate)
+      end
+
       def current_time
         # Use monotonic time for consistency with BreakerMachines
         ThrottleMachines.monotonic_time

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,21 +91,24 @@ 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 }
 
           tat = [state[:tat], now].max
-          allow = tat - now <= delay_tolerance
+          allow = gcra_allowed?(tat, now, delay_tolerance)
 
           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,12 +120,15 @@ 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
-          allow = tat - now <= delay_tolerance
+          allow = gcra_allowed?(tat, now, delay_tolerance)
 
           {
             allowed: allow,
@@ -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 }
@@ -130,9 +152,11 @@ module ThrottleMachines
           bucket[:last_refill] = now
 
           # Check if we can consume a token
-          if bucket[:tokens] >= 1
-            bucket[:tokens] -= 1
-            @token_buckets[key] = bucket.merge(expires_at: now + ttl)
+          if token_available?(bucket[:tokens], now, refill_rate)
+            bucket[:tokens] = [bucket[:tokens] - 1, 0.0].max
+            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
@@ -161,11 +188,11 @@ module ThrottleMachines
           tokens_to_add = elapsed * refill_rate
           current_tokens = [bucket[:tokens] + tokens_to_add, capacity].min
 
-          if current_tokens >= 1
+          if token_available?(current_tokens, now, refill_rate)
             {
               allowed: true,
               retry_after: 0,
-              tokens_remaining: (current_tokens - 1).floor
+              tokens_remaining: [current_tokens - 1, 0].max.floor
             }
           else
             retry_after = (1 - current_tokens) / refill_rate
@@ -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/storage/redis/gcra.lua

@@ -12,11 +12,15 @@ else
 end
 
 tat = math.max(tat, now)
-local allow = (tat - now) <= delay_tolerance
+-- The TAT is a running sum of emission intervals, so an on-schedule arrival
+-- can overshoot the tolerance by a few ulps; the slack scales with the clock.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(tat), 1)
+local allow = (tat - now) <= delay_tolerance + slack
 
 if allow then
   local new_tat = tat + emission_interval
   redis.call('SET', key, new_tat, 'EX', ttl)
 end
 
-return { allow and 1 or 0, tat }
+-- Redis truncates Lua numbers in replies to integers; send the TAT as text.
+return { allow and 1 or 0, string.format('%.17g', tat) }

data/lib/throttle_machines/storage/redis/peek_gcra.lua

@@ -11,6 +11,10 @@ else
 end
 
 tat = math.max(tat, now)
-local allow = (tat - now) <= delay_tolerance
+-- The TAT is a running sum of emission intervals, so an on-schedule arrival
+-- can overshoot the tolerance by a few ulps; the slack scales with the clock.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(tat), 1)
+local allow = (tat - now) <= delay_tolerance + slack
 
-return { allow and 1 or 0, tat }
+-- Redis truncates Lua numbers in replies to integers; send the TAT as text.
+return { allow and 1 or 0, string.format('%.17g', tat) }

data/lib/throttle_machines/storage/redis/peek_token_bucket.lua

@@ -12,7 +12,13 @@ local elapsed = now - last_refill
 local tokens_to_add = elapsed * refill_rate
 tokens = math.min(tokens + tokens_to_add, capacity)
 
-local allow = tokens >= 1
-local tokens_after = allow and (tokens - 1) or 0
+-- `elapsed` carries the clock's rounding; a token due exactly now may come
+-- out a hair short of 1. The slack scales with the clock, as in the native core.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(now), 1) * refill_rate
+local allow = tokens >= 1 - slack
+-- Admitted: tokens left after this request. Refused: the fractional balance,
+-- which retry_after is computed from.
+local tokens_after = allow and math.max(tokens - 1, 0) or tokens
 
-return { allow and 1 or 0, tokens_after }
+-- Redis truncates Lua numbers in replies to integers; send the count as text.
+return { allow and 1 or 0, string.format('%.17g', tokens_after) }

data/lib/throttle_machines/storage/redis/token_bucket.lua

@@ -13,11 +13,15 @@ local elapsed = now - last_refill
 local tokens_to_add = elapsed * refill_rate
 tokens = math.min(tokens + tokens_to_add, capacity)
 
-local allow = tokens >= 1
+-- `elapsed` carries the clock's rounding; a token due exactly now may come
+-- out a hair short of 1. The slack scales with the clock, as in the native core.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(now), 1) * refill_rate
+local allow = tokens >= 1 - slack
 if allow then
-  tokens = tokens - 1
+  tokens = math.max(tokens - 1, 0)
   redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
   redis.call('EXPIRE', key, ttl)
 end
 
-return { allow and 1 or 0, tokens }
+-- Redis truncates Lua numbers in replies to integers; send the count as text.
+return { allow and 1 or 0, string.format('%.17g', tokens) }

data/lib/throttle_machines/storage/redis.rb

@@ -59,13 +59,13 @@ module ThrottleMachines
 
       # GCRA operations (atomic via Lua)
       def check_gcra_limit(key, emission_interval, delay_tolerance, ttl)
+        now = current_time
         result = run_script(GCRA_SCRIPT, GCRA_SHA,
                             keys: [prefixed(key)],
-                            argv: [emission_interval, delay_tolerance, ttl, current_time])
+                            argv: [emission_interval, delay_tolerance, ttl, now])
 
         allowed = result[0] == 1
-        tat = result[1]
-        now = current_time
+        tat = Float(result[1])
 
         {
           allowed: allowed,
@@ -80,25 +80,18 @@ module ThrottleMachines
                             keys: [prefixed(key)],
                             argv: [capacity, refill_rate, ttl, current_time])
 
-        allowed = result[0] == 1
-        tokens = result[1]
-
-        {
-          allowed: allowed,
-          retry_after: allowed ? 0 : (1 - tokens) / refill_rate,
-          tokens_remaining: tokens.floor
-        }
+        token_bucket_result(result, refill_rate)
       end
 
       # Peek methods for non-consuming checks
       def peek_gcra_limit(key, emission_interval, delay_tolerance)
+        now = current_time
         result = run_script(PEEK_GCRA_SCRIPT, PEEK_GCRA_SHA,
                             keys: [prefixed(key)],
-                            argv: [emission_interval, delay_tolerance, current_time])
+                            argv: [emission_interval, delay_tolerance, now])
 
         allowed = result[0] == 1
-        tat = result[1]
-        now = current_time
+        tat = Float(result[1])
 
         {
           allowed: allowed,
@@ -112,14 +105,7 @@ module ThrottleMachines
                             keys: [prefixed(key)],
                             argv: [capacity, refill_rate, current_time])
 
-        allowed = result[0] == 1
-        tokens_remaining = result[1]
-
-        {
-          allowed: allowed,
-          retry_after: allowed ? 0 : (1 - tokens_remaining) / refill_rate,
-          tokens_remaining: tokens_remaining.floor
-        }
+        token_bucket_result(result, refill_rate)
       end
 
       # No circuit breaker operations: breaker state is owned by BreakerMachines
@@ -147,6 +133,19 @@ module ThrottleMachines
 
       private
 
+      # `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)
+        allowed = result[0] == 1
+        tokens = Float(result[1])
+
+        {
+          allowed: allowed,
+          retry_after: allowed ? 0 : (1 - tokens) / refill_rate,
+          tokens_remaining: allowed ? tokens.floor : 0
+        }
+      end
+
       def prefixed(key)
         "#{@prefix}#{key}"
       end

data/lib/throttle_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ThrottleMachines
-  VERSION = '0.3.0'
+  VERSION = '0.3.3'
 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: throttle_machines
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.3
 platform: ruby
 authors:
 - Abdelkader Boudih