throttle_machines 0.0.0 → 0.1.1

data/lib/throttle_machines/storage/memory.rb

@@ -0,0 +1,373 @@
+# 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
+        @breaker_states = 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
+
+      # Circuit breaker operations
+      def get_breaker_state(key)
+        # First try with read lock
+        state = with_read_lock("breaker:#{key}") do
+          @breaker_states[key] || { state: :closed, failures: 0, last_failure: nil }
+        end
+
+        # Check if we need to transition from open to half-open
+        if state[:state] == :open && state[:opens_at] && current_time >= state[:opens_at]
+          # Release read lock and acquire write lock
+          with_write_lock("breaker:#{key}") do
+            # Re-check condition after acquiring write lock
+            current_state = @breaker_states[key]
+            if current_state && current_state[:state] == :open && current_state[:opens_at] && current_time >= current_state[:opens_at]
+              @breaker_states[key] = current_state.merge(
+                state: :half_open,
+                half_open_attempts: 0
+              )
+            end
+            @breaker_states[key] || { state: :closed, failures: 0, last_failure: nil }
+          end
+        else
+          state
+        end
+      end
+
+      def record_breaker_success(key, _timeout, half_open_requests = 1)
+        with_write_lock("breaker:#{key}") do
+          state = @breaker_states[key]
+          return unless state
+
+          case state[:state]
+          when :half_open
+            attempts = (state[:half_open_attempts] || 0) + 1
+            if attempts >= half_open_requests
+              @breaker_states.delete(key)
+            else
+              @breaker_states[key] = state.merge(half_open_attempts: attempts)
+            end
+          when :closed
+            # Reset failure count on success
+            @breaker_states[key] = state.merge(failures: 0) if state[:failures].positive?
+          end
+        end
+      end
+
+      def record_breaker_failure(key, threshold, timeout)
+        with_write_lock("breaker:#{key}") do
+          state = @breaker_states[key] || { state: :closed, failures: 0 }
+          now = current_time
+
+          case state[:state]
+          when :closed
+            failures = state[:failures] + 1
+            @breaker_states[key] = if failures >= threshold
+                                     {
+                                       state: :open,
+                                       failures: failures,
+                                       last_failure: now,
+                                       opens_at: now + timeout
+                                     }
+                                   else
+                                     state.merge(failures: failures, last_failure: now)
+                                   end
+          when :half_open
+            @breaker_states[key] = {
+              state: :open,
+              failures: state[:failures],
+              last_failure: now,
+              opens_at: now + timeout
+            }
+          end
+
+          @breaker_states[key]
+        end
+      end
+
+      def trip_breaker(key, timeout)
+        with_write_lock("breaker:#{key}") do
+          now = current_time
+          @breaker_states[key] = {
+            state: :open,
+            failures: 0,
+            last_failure: now,
+            opens_at: now + timeout
+          }
+        end
+      end
+
+      def reset_breaker(key)
+        with_write_lock("breaker:#{key}") { @breaker_states.delete(key) }
+      end
+
+      # Utility operations
+      def clear(pattern = nil)
+        if pattern
+          regex = Regexp.new(pattern.gsub('*', '.*'))
+
+          # Clear matching keys from all stores
+          [@counters, @gcra_states, @token_buckets, @breaker_states].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
+          @breaker_states.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, &)
+        lock_for(key).with_read_lock(&)
+      end
+
+      def with_write_lock(key, &)
+        lock_for(key).with_write_lock(&)
+      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
+
+        # Clean closed breaker states and expired open states
+        @breaker_states.each_pair do |key, data|
+          should_delete = false
+
+          # Clean closed states that have been idle
+          should_delete = true if data[:state] == :closed && data[:failures].zero?
+
+          # Clean expired open states (older than 2x timeout)
+          if data[:opens_at] && now > data[:opens_at] + ((data[:opens_at] - (data[:last_failure] || now)) * 2)
+            should_delete = true
+          end
+
+          with_write_lock("breaker:#{key}") { @breaker_states.delete(key) } if should_delete
+        end
+      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,88 @@
+# 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
+
+      # Circuit breaker operations
+      def get_breaker_state(_key)
+        { state: :closed, failures: 0, last_failure: nil }
+      end
+
+      def record_breaker_success(_key, _timeout, _half_open_requests = 1)
+        true
+      end
+
+      def record_breaker_failure(_key, _threshold, _timeout)
+        { state: :closed, failures: 0, last_failure: nil }
+      end
+
+      def trip_breaker(_key, _timeout)
+        true
+      end
+
+      def reset_breaker(_key)
+        true
+      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/get_breaker_state.lua

@@ -0,0 +1,23 @@
+local data = redis.call('HGETALL', KEYS[1])
+if #data == 0 then
+  return {}
+end
+
+local state = {}
+for i = 1, #data, 2 do
+  state[data[i]] = data[i + 1]
+end
+
+-- Auto-transition from open to half-open if timeout passed
+if state['state'] == 'open' and state['opens_at'] then
+  local now = tonumber(ARGV[1])
+  local opens_at = tonumber(state['opens_at'])
+  
+  if now >= opens_at then
+    redis.call('HSET', KEYS[1], 'state', 'half_open', 'half_open_attempts', '0')
+    state['state'] = 'half_open'
+    state['half_open_attempts'] = '0'
+  end
+end
+
+return state

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/record_breaker_failure.lua

@@ -0,0 +1,24 @@
+local state = redis.call('HGET', KEYS[1], 'state') or 'closed'
+local now = ARGV[3]
+local timeout = tonumber(ARGV[2])
+
+if state == 'half_open' then
+  -- Failure in half-open state, just re-open the circuit
+  redis.call('HMSET', KEYS[1],
+    'state', 'open',
+    'opens_at', tonumber(now) + timeout,
+    'last_failure', now
+  )
+else -- state is 'closed' or nil
+  local failures = redis.call('HINCRBY', KEYS[1], 'failures', 1)
+  redis.call('HSET', KEYS[1], 'last_failure', now)
+  
+  if failures >= tonumber(ARGV[1]) then
+    redis.call('HMSET', KEYS[1],
+      'state', 'open',
+      'opens_at', tonumber(now) + timeout
+    )
+  end
+end
+
+redis.call('EXPIRE', KEYS[1], timeout * 2)

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

@@ -0,0 +1,16 @@
+local state = redis.call('HGET', KEYS[1], 'state')
+
+if state == 'half_open' then
+  -- Increment half-open attempts and potentially close the circuit
+  local attempts = redis.call('HINCRBY', KEYS[1], 'half_open_attempts', 1)
+  
+  if attempts >= tonumber(ARGV[1]) then
+    redis.call('DEL', KEYS[1])
+  end
+elseif state == 'closed' then
+  -- Reset failure count on success in closed state
+  local failures = redis.call('HGET', KEYS[1], 'failures')
+  if failures and tonumber(failures) > 0 then
+    redis.call('HSET', KEYS[1], 'failures', 0)
+  end
+end

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 }