throttle_machines 0.2.4-aarch64-linux

data/lib/throttle_machines/storage/memory.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module ThrottleMachines
+  module Storage
+    class Memory < Base
+      def initialize(options = {})
+        super
+        @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 }
+
+        # Background cleanup thread
+        @cleanup_interval = options[:cleanup_interval] || 60
+        @shutdown = false
+        @cleanup_thread = start_cleanup_thread if options[:auto_cleanup] != false
+
+        # Ensure cleanup on garbage collection
+        ObjectSpace.define_finalizer(self, self.class.finalizer(@cleanup_thread))
+      end
+
+      def self.finalizer(cleanup_thread)
+        proc { cleanup_thread&.kill }
+      end
+
+      # Rate limiting operations
+      def increment_counter(key, window, amount = 1)
+        window_key = "#{key}:#{window}"
+
+        with_write_lock(window_key) do
+          now = current_time
+          # Fetch fresh value inside the lock to ensure consistency
+          counter = @counters[window_key]
+
+          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 }
+          else
+            # Increment existing counter atomically
+            new_count = counter[:count] + amount
+            @counters[window_key] = { count: new_count, expires_at: counter[:expires_at] }
+          end
+          new_count
+        end
+      end
+
+      def get_counter(key, window)
+        window_key = "#{key}:#{window}"
+
+        with_read_lock(window_key) do
+          counter = @counters[window_key]
+          return 0 unless counter
+          return 0 if counter[:expires_at] <= current_time
+
+          counter[:count]
+        end
+      end
+
+      def get_counter_ttl(key, window)
+        window_key = "#{key}:#{window}"
+
+        with_read_lock(window_key) do
+          counter = @counters[window_key]
+          return 0 unless counter
+
+          ttl = counter[:expires_at] - current_time
+          [ttl, 0].max
+        end
+      end
+
+      def reset_counter(key, window)
+        window_key = "#{key}:#{window}"
+        with_write_lock(window_key) { @counters.delete(window_key) }
+      end
+
+      # GCRA operations (atomic simulation)
+      def check_gcra_limit(key, emission_interval, delay_tolerance, ttl)
+        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
+
+          if allow
+            new_tat = tat + emission_interval
+            @gcra_states[key] = { tat: new_tat, expires_at: now + ttl }
+          end
+
+          {
+            allowed: allow,
+            retry_after: allow ? 0 : (tat - now - delay_tolerance),
+            tat: tat
+          }
+        end
+      end
+
+      def peek_gcra_limit(key, _emission_interval, delay_tolerance)
+        with_read_lock(key) do
+          now = current_time
+          state = @gcra_states[key] || { tat: 0.0 }
+
+          tat = [state[:tat], now].max
+          allow = tat - now <= delay_tolerance
+
+          {
+            allowed: allow,
+            retry_after: allow ? 0 : (tat - now - delay_tolerance),
+            tat: tat
+          }
+        end
+      end
+
+      # Token bucket operations (atomic simulation)
+      def check_token_bucket(key, capacity, refill_rate, ttl)
+        with_write_lock(key) do
+          now = current_time
+          bucket = @token_buckets[key] || { tokens: capacity, last_refill: now }
+
+          # Refill tokens
+          elapsed = now - bucket[:last_refill]
+          tokens_to_add = elapsed * refill_rate
+          bucket[:tokens] = [bucket[:tokens] + tokens_to_add, capacity].min
+          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)
+
+            {
+              allowed: true,
+              retry_after: 0,
+              tokens_remaining: bucket[:tokens].floor
+            }
+          else
+            retry_after = (1 - bucket[:tokens]) / refill_rate
+
+            {
+              allowed: false,
+              retry_after: retry_after,
+              tokens_remaining: 0
+            }
+          end
+        end
+      end
+
+      def peek_token_bucket(key, capacity, refill_rate)
+        with_read_lock(key) do
+          now = current_time
+          bucket = @token_buckets[key] || { tokens: capacity, last_refill: now }
+
+          # Calculate tokens without modifying state
+          elapsed = now - bucket[:last_refill]
+          tokens_to_add = elapsed * refill_rate
+          current_tokens = [bucket[:tokens] + tokens_to_add, capacity].min
+
+          if current_tokens >= 1
+            {
+              allowed: true,
+              retry_after: 0,
+              tokens_remaining: (current_tokens - 1).floor
+            }
+          else
+            retry_after = (1 - current_tokens) / refill_rate
+
+            {
+              allowed: false,
+              retry_after: retry_after,
+              tokens_remaining: 0
+            }
+          end
+        end
+      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.each_key do |k|
+              store.delete(k) if k&.match?(regex)
+            end
+          end
+        else
+          @counters.clear
+          @gcra_states.clear
+          @token_buckets.clear
+        end
+      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?
+        @cleanup_thread = nil
+      end
+
+      private
+
+      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
+
+      def lock_for(key)
+        # Hash key to determine which lock to use
+        index = key.hash.abs % @lock_pool_size
+        @locks[index]
+      end
+
+      def start_cleanup_thread
+        Thread.new do
+          loop do
+            break if @shutdown
+
+            sleep @cleanup_interval
+            break if @shutdown
+
+            clean_expired_entries
+          end
+        end
+      end
+
+      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
+        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
+    end
+  end
+end

data/lib/throttle_machines/storage/null.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  module Storage
+    class Null < Base
+      # Rate limiting operations
+      def increment_counter(_key, _window, _amount = 1)
+        0
+      end
+
+      def get_counter(_key, _window)
+        0
+      end
+
+      def get_counter_ttl(_key, _window)
+        0
+      end
+
+      def reset_counter(_key, _window)
+        true
+      end
+
+      # GCRA operations
+      def check_gcra_limit(_key, _emission_interval, _delay_tolerance, _ttl)
+        {
+          allowed: true,
+          retry_after: 0,
+          tat: 0
+        }
+      end
+
+      def peek_gcra_limit(_key, _emission_interval, _delay_tolerance)
+        {
+          allowed: true,
+          retry_after: 0,
+          tat: 0
+        }
+      end
+
+      # Token bucket operations
+      def check_token_bucket(_key, capacity, _refill_rate, _ttl)
+        {
+          allowed: true,
+          retry_after: 0,
+          tokens_remaining: capacity
+        }
+      end
+
+      def peek_token_bucket(_key, capacity, _refill_rate)
+        {
+          allowed: true,
+          retry_after: 0,
+          tokens_remaining: capacity
+        }
+      end
+
+      # Utility operations
+      def clear(_pattern = nil)
+        true
+      end
+
+      def healthy?
+        true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+local key = KEYS[1]
+local emission_interval = tonumber(ARGV[1])
+local delay_tolerance = tonumber(ARGV[2])
+local ttl = tonumber(ARGV[3])
+local now = tonumber(ARGV[4])
+
+local tat = redis.call('GET', key)
+if not tat then
+  tat = 0
+else
+  tat = tonumber(tat)
+end
+
+tat = math.max(tat, now)
+local allow = (tat - now) <= delay_tolerance
+
+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 }

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

@@ -0,0 +1,9 @@
+local count = redis.call('INCRBY', KEYS[1], ARGV[1])
+local ttl = redis.call('TTL', KEYS[1])
+
+-- Set expiry if key is new (ttl == -2) or has no TTL (ttl == -1)
+if ttl <= 0 then
+  redis.call('EXPIRE', KEYS[1], ARGV[2])
+end
+
+return count

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

@@ -0,0 +1,16 @@
+local key = KEYS[1]
+local emission_interval = tonumber(ARGV[1])
+local delay_tolerance = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+
+local tat = redis.call('GET', key)
+if not tat then
+  tat = 0
+else
+  tat = tonumber(tat)
+end
+
+tat = math.max(tat, now)
+local allow = (tat - now) <= delay_tolerance
+
+return { allow and 1 or 0, tat }

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

@@ -0,0 +1,18 @@
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local refill_rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+
+local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
+local tokens = tonumber(bucket[1]) or capacity
+local last_refill = tonumber(bucket[2]) or now
+
+-- Calculate tokens without modifying
+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
+
+return { allow and 1 or 0, tokens_after }

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

@@ -0,0 +1,23 @@
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local refill_rate = tonumber(ARGV[2])
+local ttl = tonumber(ARGV[3])
+local now = tonumber(ARGV[4])
+
+local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
+local tokens = tonumber(bucket[1]) or capacity
+local last_refill = tonumber(bucket[2]) or now
+
+-- Refill tokens
+local elapsed = now - last_refill
+local tokens_to_add = elapsed * refill_rate
+tokens = math.min(tokens + tokens_to_add, capacity)
+
+local allow = tokens >= 1
+if allow then
+  tokens = tokens - 1
+  redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
+  redis.call('EXPIRE', key, ttl)
+end
+
+return { allow and 1 or 0, tokens }

data/lib/throttle_machines/storage/redis.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  module Storage
+    class Redis < Base
+      # Load Lua scripts from files
+      LUA_SCRIPTS_DIR = File.expand_path('redis', __dir__)
+
+      GCRA_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'gcra.lua'))
+      TOKEN_BUCKET_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'token_bucket.lua'))
+      PEEK_GCRA_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'peek_gcra.lua'))
+      PEEK_TOKEN_BUCKET_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'peek_token_bucket.lua'))
+      INCREMENT_COUNTER_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'increment_counter.lua'))
+      # Breaker scripts removed: breaker state is owned by BreakerMachines
+
+      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
+
+      # Rate limiting operations
+      def increment_counter(key, window, amount = 1)
+        window_key = prefixed("#{key}:#{window}")
+
+        # Use Lua script for atomic increment with TTL
+        with_redis do |redis|
+          redis.eval(INCREMENT_COUNTER_SCRIPT, keys: [window_key], argv: [amount, window.to_i])
+        end
+      end
+
+      def get_counter(key, window)
+        window_key = prefixed("#{key}:#{window}")
+        with_redis { |r| (r.get(window_key) || 0).to_i }
+      end
+
+      def get_counter_ttl(key, window)
+        window_key = prefixed("#{key}:#{window}")
+        ttl = with_redis { |r| r.ttl(window_key) }
+        [ttl, 0].max
+      end
+
+      def reset_counter(key, window)
+        window_key = prefixed("#{key}:#{window}")
+        with_redis { |r| r.del(window_key) }
+      end
+
+      # 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
+
+        allowed = result[0] == 1
+        tat = result[1]
+        now = current_time
+
+        {
+          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]
+
+        {
+          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
+      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
+
+        allowed = result[0] == 1
+        tat = result[1]
+        now = current_time
+
+        {
+          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
+
+        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
+      end
+
+      # No circuit breaker operations: breaker state is owned by BreakerMachines
+
+      # Utility operations
+      def clear(pattern = nil)
+        # Use SCAN instead of KEYS to avoid blocking in production
+        cursor = '0'
+        scan_pattern = pattern ? prefixed(pattern) : "#{@prefix}*"
+
+        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
+      end
+
+      def healthy?
+        with_redis { |r| r.ping == 'PONG' }
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def prefixed(key)
+        "#{@prefix}#{key}"
+      end
+
+      def ensure_gcra_script_loaded!
+        @ensure_gcra_script_loaded ||= with_redis { |r| r.script(:load, GCRA_SCRIPT) }
+      end
+
+      def ensure_token_bucket_script_loaded!
+        @ensure_token_bucket_script_loaded ||= with_redis { |r| r.script(:load, TOKEN_BUCKET_SCRIPT) }
+      end
+
+      def ensure_peek_gcra_script_loaded!
+        @ensure_peek_gcra_script_loaded ||= with_redis { |r| r.script(:load, PEEK_GCRA_SCRIPT) }
+      end
+
+      def ensure_peek_token_bucket_script_loaded!
+        @ensure_peek_token_bucket_script_loaded ||= with_redis { |r| r.script(:load, PEEK_TOKEN_BUCKET_SCRIPT) }
+      end
+
+      def validate_redis_connection!
+        raise ArgumentError, 'Redis client not provided' unless @redis
+
+        # Test connection
+        with_redis(&:ping)
+      rescue StandardError => e
+        raise ArgumentError, "Invalid Redis connection: #{e.message}"
+      end
+
+      def with_redis(&block)
+        if @redis.respond_to?(:with)
+          # Connection pool
+          @redis.with(&block)
+        else
+          # Regular Redis client
+          block.call(@redis)
+        end
+      end
+    end
+  end
+end

data/lib/throttle_machines/throttled_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class ThrottledError < StandardError
+    attr_reader :limiter
+
+    def initialize(limiter)
+      @limiter = limiter
+      super("Rate limit exceeded for #{limiter.key}")
+    end
+
+    delegate :retry_after, to: :@limiter
+  end
+end

data/lib/throttle_machines/version.rb

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