throttle_machines 0.0.0 → 0.1.1

data/lib/throttle_machines/storage/redis.rb

@@ -0,0 +1,294 @@
+# 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'))
+      GET_BREAKER_STATE_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'get_breaker_state.lua'))
+      RECORD_BREAKER_SUCCESS_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'record_breaker_success.lua'))
+      RECORD_BREAKER_FAILURE_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'record_breaker_failure.lua'))
+
+      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
+
+      # Circuit breaker operations
+      def get_breaker_state(key)
+        breaker_key = prefixed("breaker:#{key}")
+
+        # Use Lua script for atomic read and potential state transition
+        result = with_redis do |redis|
+          redis.eval(GET_BREAKER_STATE_SCRIPT, keys: [breaker_key], argv: [current_time])
+        end
+
+        return { state: :closed, failures: 0, last_failure: nil } if result.empty?
+
+        # Convert hash from Lua to Ruby format
+        state = {}
+        result.each_slice(2) { |k, v| state[k] = v }
+
+        {
+          state: state['state'].to_sym,
+          failures: state['failures'].to_i,
+          last_failure: state['last_failure']&.to_f,
+          opens_at: state['opens_at']&.to_f,
+          half_open_attempts: state['half_open_attempts']&.to_i
+        }
+      end
+
+      def record_breaker_success(key, _timeout, half_open_requests = 1)
+        breaker_key = prefixed("breaker:#{key}")
+
+        # Use Lua script for atomic success recording
+        with_redis do |redis|
+          redis.eval(RECORD_BREAKER_SUCCESS_SCRIPT, keys: [breaker_key], argv: [half_open_requests])
+        end
+      end
+
+      def record_breaker_failure(key, threshold, timeout)
+        breaker_key = prefixed("breaker:#{key}")
+        now = current_time
+
+        # Use Lua script for atomic failure recording
+        with_redis do |redis|
+          redis.eval(RECORD_BREAKER_FAILURE_SCRIPT, keys: [breaker_key], argv: [threshold, timeout, now])
+        end
+
+        get_breaker_state(key)
+      end
+
+      def trip_breaker(key, timeout)
+        breaker_key = prefixed("breaker:#{key}")
+        now = current_time
+
+        with_redis do |redis|
+          redis.hmset(breaker_key,
+                      'state', 'open',
+                      'failures', 0,
+                      'last_failure', now,
+                      'opens_at', now + timeout)
+          redis.expire(breaker_key, (timeout * 2).to_i)
+        end
+      end
+
+      def reset_breaker(key)
+        with_redis { |r| r.del(prefixed("breaker:#{key}")) }
+      end
+
+      # 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(&)
+        if @redis.respond_to?(:with)
+          # Connection pool
+          @redis.with(&)
+        else
+          # Regular Redis client
+          yield @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.1.1'
+end

data/lib/throttle_machines.rb

@@ -1,9 +1,134 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'timeout'
+require 'zeitwerk'
+require 'active_support/configurable'
+
+# Ecosystem dependencies
+require 'chrono_machines'
+require 'breaker_machines'
+
+# Set up Zeitwerk loader
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/throttle_machines/engine.rb") unless defined?(Rails::Engine)
+loader.setup
+
 module ThrottleMachines
-  VERSION = "0.0.0"
-  
-  def self.version
-    VERSION
+  include ActiveSupport::Configurable
+
+  # Define configuration options with defaults
+  config_accessor :default_limit, default: 100
+  config_accessor :default_period, default: 60 # 1 minute
+  config_accessor :default_storage, default: :memory
+  config_accessor :clock, default: nil
+  config_accessor :instrumentation_enabled, default: true
+  config_accessor :instrumentation_backend
+  config_accessor :_storage_instance
+
+  class << self
+    # Delegate monotonic time to BreakerMachines for consistency
+    delegate :monotonic_time, to: :BreakerMachines
+
+    def configure
+      yield(config) if block_given?
+
+      # Apply instrumentation settings
+      Instrumentation.enabled = config.instrumentation_enabled
+      Instrumentation.backend = config.instrumentation_backend if config.instrumentation_backend
+    end
+
+    def storage
+      config._storage_instance ||= create_storage(config.default_storage)
+    end
+
+    def storage=(value)
+      config._storage_instance = create_storage(value)
+    end
+
+    def reset!(key = nil)
+      if key
+        storage.clear("#{key}*")
+      else
+        storage.clear
+        # Reset storage instance to force recreation with defaults
+        config._storage_instance = nil
+        # Re-apply instrumentation settings from the configuration
+        Instrumentation.enabled = config.instrumentation_enabled
+        Instrumentation.backend = config.instrumentation_backend
+      end
+    end
+
+    def control(key, &block)
+      control = Control.new(key)
+      control.instance_eval(&block) if block
+      control
+    end
+
+    def limit(key, limit:, period:, algorithm: :fixed_window, &)
+      limiter = limiter(key, limit: limit, period: period, algorithm: algorithm)
+      limiter.throttle!(&)
+    end
+
+    def break_circuit(key, failures:, timeout:, &)
+      # Delegate to breaker_machines
+      breaker = BreakerMachines::Circuit.new(
+        key: key,
+        failure_threshold: failures,
+        timeout: timeout
+      )
+      breaker.call(&)
+    end
+
+    def retry_with(max_attempts: 3, backoff: :exponential, &)
+      # Delegate to chrono_machines
+      policy_options = {
+        max_attempts: max_attempts,
+        jitter_factor: backoff == :exponential ? 1.0 : 0.0
+      }
+      ChronoMachines.retry(policy_options, &)
+    end
+
+    def limiter(key, limit:, period:, algorithm: :fixed_window)
+      Limiter.new(key, limit: limit, period: period, algorithm: algorithm, storage: storage)
+    end
+
+    private
+
+    def create_storage(storage)
+      case storage
+      when Symbol
+        create_storage_from_symbol(storage)
+      when Class
+        storage.new
+      when Storage::Base
+        storage
+      else
+        raise ArgumentError, "Invalid storage: #{storage.inspect}"
+      end
+    end
+
+    def create_storage_from_symbol(symbol)
+      case symbol
+      when :memory
+        Storage::Memory.new
+      when :redis
+        raise ArgumentError, 'Redis storage requires redis gem' unless defined?(Redis)
+
+        raise ArgumentError, 'Redis storage requires a Redis client instance. ' \
+                             'Configure with: config.storage = Storage::Redis.new(redis: Redis.new)'
+
+      when :null
+        Storage::Null.new
+      else
+        raise ArgumentError, "Unknown storage type: #{symbol}"
+      end
+    end
   end
-end
+
+  # Auto-configure with defaults
+  configure
+
+  CircuitOpenError = BreakerMachines::CircuitOpenError
+  RetryExhaustedError = ChronoMachines::MaxRetriesExceededError
+end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: throttle_machines
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.1
 platform: ruby
 authors:
-- seuros
+- Abdelkader Boudih
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -23,18 +23,121 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-description: ThrottleMachines provides intelligent throttling and rate limiting mechanisms
-  for distributed systems. This is a placeholder gem - full implementation coming
-  soon.
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: breaker_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: chrono_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: ThrottleMachines provides ultra-thin, elegant rate limiting with temporal
+  precision for distributed systems.
 email:
 - terminale@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.txt
+- LICENSE
 - README.md
+- Rakefile
 - lib/throttle_machines.rb
+- lib/throttle_machines/async_limiter.rb
+- lib/throttle_machines/control.rb
+- lib/throttle_machines/controller_helpers.rb
+- lib/throttle_machines/dependency_error.rb
+- lib/throttle_machines/engine.rb
+- lib/throttle_machines/hedged_breaker.rb
+- lib/throttle_machines/hedged_request.rb
+- lib/throttle_machines/instrumentation.rb
+- lib/throttle_machines/limiter.rb
+- lib/throttle_machines/middleware.rb
+- lib/throttle_machines/rack_middleware.rb
+- lib/throttle_machines/rack_middleware/allow2_ban.rb
+- lib/throttle_machines/rack_middleware/blocklist.rb
+- lib/throttle_machines/rack_middleware/configuration.rb
+- lib/throttle_machines/rack_middleware/fail2_ban.rb
+- lib/throttle_machines/rack_middleware/request.rb
+- lib/throttle_machines/rack_middleware/safelist.rb
+- lib/throttle_machines/rack_middleware/throttle.rb
+- lib/throttle_machines/rack_middleware/track.rb
+- lib/throttle_machines/storage/base.rb
+- lib/throttle_machines/storage/memory.rb
+- lib/throttle_machines/storage/null.rb
+- lib/throttle_machines/storage/redis.rb
+- lib/throttle_machines/storage/redis/gcra.lua
+- lib/throttle_machines/storage/redis/get_breaker_state.lua
+- lib/throttle_machines/storage/redis/increment_counter.lua
+- lib/throttle_machines/storage/redis/peek_gcra.lua
+- lib/throttle_machines/storage/redis/peek_token_bucket.lua
+- lib/throttle_machines/storage/redis/record_breaker_failure.lua
+- lib/throttle_machines/storage/redis/record_breaker_success.lua
+- lib/throttle_machines/storage/redis/token_bucket.lua
+- lib/throttle_machines/throttled_error.rb
+- lib/throttle_machines/version.rb
 homepage: https://github.com/seuros/throttle_machines
 licenses:
 - MIT
@@ -42,6 +145,7 @@ metadata:
   homepage_uri: https://github.com/seuros/throttle_machines
   source_code_uri: https://github.com/seuros/throttle_machines
   changelog_uri: https://github.com/seuros/throttle_machines/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -49,7 +153,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -58,5 +162,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Advanced throttling and rate limiting for distributed systems
+summary: Advanced Rate limiting for Ruby applications
 test_files: []

data/LICENSE.txt

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2025 seuros
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.