throttle_machines 0.2.4-x86_64-linux → 0.3.1-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b903b7c1264b244a780a3730bd09d7bdab11db1f28961910980d93d7722ff92e
-  data.tar.gz: d6229cb0f861acea1f76e99a8ec4bcd0c3217f10745467f6411c5383519fe84b
+  metadata.gz: c0e7b82b0a0e6aee13b28e5dff8d398583123ae16859094db1f5731563b6756a
+  data.tar.gz: 55eae369f9ff8d44e771ce1d30af98e81468c4e4590cb283121236dad134d726
 SHA512:
-  metadata.gz: f35c2f3f16752f64e34105a201f5854b157a0f5092972acb47310802400502474d3d74ca52852056b77932c442af3d76ab0edec0becdd0142a07d4c17a11159e
-  data.tar.gz: 7c20314309fda5045cc7109b03b79dcdac901cb1ce9e83011cf59f6f1906c24f3fd9e6db7b86aff3091deebd21fdbd02118db08d9bce43d7a3f5be6c06111d0c
+  metadata.gz: 9e2199d9db95a4b57fc42ed9d702a464e7efccc6a43312ef0e46e33b16cba5ec19bf6a1b684a8eaab2463d0ae89a4fcae063571a198a48b2d53a526f7a5730c5
+  data.tar.gz: b10d373aa0a749dddea669a8f50d1118c3101fb68b84a1411eed792457edae55e0f8cb0ecf43a389da389bc5884a9cead734df1a4a89687eb1027765ddc2bd56

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

@@ -86,7 +86,7 @@ module ThrottleMachines
           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
@@ -107,7 +107,7 @@ module ThrottleMachines
           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,
@@ -130,8 +130,8 @@ module ThrottleMachines
           bucket[:last_refill] = now
 
           # Check if we can consume a token
-          if bucket[:tokens] >= 1
-            bucket[:tokens] -= 1
+          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)
 
             {
@@ -161,11 +161,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

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'digest/sha1'
+
 module ThrottleMachines
   module Storage
     class Redis < Base
@@ -13,17 +15,18 @@ module ThrottleMachines
       INCREMENT_COUNTER_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'increment_counter.lua'))
       # Breaker scripts removed: breaker state is owned by BreakerMachines
 
+      # Redis caches scripts by the SHA1 of their source, so the SHAs are known
+      # without a SCRIPT LOAD round trip.
+      GCRA_SHA = Digest::SHA1.hexdigest(GCRA_SCRIPT)
+      TOKEN_BUCKET_SHA = Digest::SHA1.hexdigest(TOKEN_BUCKET_SCRIPT)
+      PEEK_GCRA_SHA = Digest::SHA1.hexdigest(PEEK_GCRA_SCRIPT)
+      PEEK_TOKEN_BUCKET_SHA = Digest::SHA1.hexdigest(PEEK_TOKEN_BUCKET_SCRIPT)
+
       def initialize(options = {})
         super
         @redis = options[:redis] || options[:client] || options[:pool]
         @prefix = options[:prefix] || 'throttle:'
 
-        # Cache scripts to avoid repeated script loads
-        @gcra_sha = nil
-        @token_bucket_sha = nil
-        @peek_gcra_sha = nil
-        @peek_token_bucket_sha = nil
-
         # Validate Redis connection
         validate_redis_connection!
       end
@@ -56,111 +59,53 @@ module ThrottleMachines
 
       # GCRA operations (atomic via Lua)
       def check_gcra_limit(key, emission_interval, delay_tolerance, ttl)
-        ensure_gcra_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @gcra_sha,
-            keys: [prefixed(key)],
-            argv: [emission_interval, delay_tolerance, ttl, current_time]
-          )
-        end
+        now = current_time
+        result = run_script(GCRA_SCRIPT, GCRA_SHA,
+                            keys: [prefixed(key)],
+                            argv: [emission_interval, delay_tolerance, ttl, now])
 
         allowed = result[0] == 1
-        tat = result[1]
-        now = current_time
+        tat = Float(result[1])
 
         {
           allowed: allowed,
           retry_after: allowed ? 0 : (tat - now - delay_tolerance),
           tat: tat
         }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @gcra_sha = nil
-        retry
       end
 
       # Token bucket operations (atomic via Lua)
       def check_token_bucket(key, capacity, refill_rate, ttl)
-        ensure_token_bucket_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @token_bucket_sha,
-            keys: [prefixed(key)],
-            argv: [capacity, refill_rate, ttl, current_time]
-          )
-        end
-
-        allowed = result[0] == 1
-        tokens = result[1]
+        result = run_script(TOKEN_BUCKET_SCRIPT, TOKEN_BUCKET_SHA,
+                            keys: [prefixed(key)],
+                            argv: [capacity, refill_rate, ttl, current_time])
 
-        {
-          allowed: allowed,
-          retry_after: allowed ? 0 : (1 - tokens) / refill_rate,
-          tokens_remaining: tokens.floor
-        }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @token_bucket_sha = nil
-        retry
+        token_bucket_result(result, refill_rate)
       end
 
       # Peek methods for non-consuming checks
       def peek_gcra_limit(key, emission_interval, delay_tolerance)
-        ensure_peek_gcra_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @peek_gcra_sha,
-            keys: [prefixed(key)],
-            argv: [emission_interval, delay_tolerance, current_time]
-          )
-        end
+        now = current_time
+        result = run_script(PEEK_GCRA_SCRIPT, PEEK_GCRA_SHA,
+                            keys: [prefixed(key)],
+                            argv: [emission_interval, delay_tolerance, now])
 
         allowed = result[0] == 1
-        tat = result[1]
-        now = current_time
+        tat = Float(result[1])
 
         {
           allowed: allowed,
           retry_after: allowed ? 0 : (tat - now - delay_tolerance),
           tat: tat
         }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @peek_gcra_sha = nil
-        retry
       end
 
       def peek_token_bucket(key, capacity, refill_rate)
-        ensure_peek_token_bucket_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @peek_token_bucket_sha,
-            keys: [prefixed(key)],
-            argv: [capacity, refill_rate, current_time]
-          )
-        end
+        result = run_script(PEEK_TOKEN_BUCKET_SCRIPT, PEEK_TOKEN_BUCKET_SHA,
+                            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
-        }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @peek_token_bucket_sha = nil
-        retry
+        token_bucket_result(result, refill_rate)
       end
 
       # No circuit breaker operations: breaker state is owned by BreakerMachines
@@ -188,24 +133,34 @@ module ThrottleMachines
 
       private
 
-      def prefixed(key)
-        "#{@prefix}#{key}"
-      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)
+        allowed = result[0] == 1
+        tokens = Float(result[1])
 
-      def ensure_gcra_script_loaded!
-        @ensure_gcra_script_loaded ||= with_redis { |r| r.script(:load, GCRA_SCRIPT) }
+        {
+          allowed: allowed,
+          retry_after: allowed ? 0 : (1 - tokens) / refill_rate,
+          tokens_remaining: allowed ? tokens.floor : 0
+        }
       end
 
-      def ensure_token_bucket_script_loaded!
-        @ensure_token_bucket_script_loaded ||= with_redis { |r| r.script(:load, TOKEN_BUCKET_SCRIPT) }
+      def prefixed(key)
+        "#{@prefix}#{key}"
       end
 
-      def ensure_peek_gcra_script_loaded!
-        @ensure_peek_gcra_script_loaded ||= with_redis { |r| r.script(:load, PEEK_GCRA_SCRIPT) }
-      end
+      # EVALSHA by the precomputed SHA. A server without the script cached (a
+      # restart, SCRIPT FLUSH, failover) answers NOSCRIPT; EVAL then runs the
+      # source once and caches it for later calls. Any other error propagates.
+      def run_script(script, sha, keys:, argv:)
+        with_redis do |redis|
+          redis.evalsha(sha, keys: keys, argv: argv)
+        rescue ::Redis::CommandError => e
+          raise unless e.message.include?('NOSCRIPT')
 
-      def ensure_peek_token_bucket_script_loaded!
-        @ensure_peek_token_bucket_script_loaded ||= with_redis { |r| r.script(:load, PEEK_TOKEN_BUCKET_SCRIPT) }
+          redis.eval(script, keys: keys, argv: argv)
+        end
       end
 
       def validate_redis_connection!

data/lib/throttle_machines/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: throttle_machines
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.1
 platform: x86_64-linux
 authors:
 - Abdelkader Boudih
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -72,42 +72,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.19'
+        version: '0.20'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.19'
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: chrono_machines
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.16'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.16'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement