throttle_machines 0.0.0 → 0.1.1

data/lib/throttle_machines/hedged_request.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+module ThrottleMachines
+  # Hedged Request - Multi-path Navigation System
+  #
+  # Like sending scout ships on multiple routes to find the fastest path.
+  # The first ship to reach the destination wins, others are recalled.
+  #
+  # Reduces latency by racing multiple backends/attempts with staggered delays.
+  #
+  # Example:
+  #   hedged = ThrottleMachines::HedgedRequest.new(
+  #     delay: 0.05,     # 50ms between attempts
+  #     max_attempts: 3
+  #   )
+  #
+  #   result = hedged.run do |attempt|
+  #     case attempt
+  #     when 0 then primary_backend.get(key)
+  #     when 1 then secondary_backend.get(key)
+  #     when 2 then tertiary_backend.get(key)
+  #     end
+  #   end
+  class HedgedRequest
+    attr_reader :delay, :max_attempts, :timeout
+
+    def initialize(delay: 0.05, max_attempts: 2, timeout: nil)
+      @delay = delay
+      @max_attempts = max_attempts
+      @timeout = timeout
+      @executor = Concurrent::ThreadPoolExecutor.new(
+        min_threads: 1,
+        max_threads: max_attempts,
+        max_queue: max_attempts,
+        fallback_policy: :caller_runs
+      )
+    end
+
+    # Run hedged request with automatic cancellation of slower attempts
+    def run(&block)
+      raise ArgumentError, 'Block required' unless block
+
+      # Generate a unique request ID for tracking
+      request_id = "#{object_id}-#{Time.now.to_f}"
+
+      # Instrument the start of the hedged request
+      Instrumentation.hedged_request_started(request_id, attempts: @max_attempts)
+
+      # Use Concurrent::Promises for better async handling
+      futures = []
+      first_result = Concurrent::Promises.resolvable_future
+      start_time = Time.now.to_f
+
+      @max_attempts.times do |attempt|
+        # Schedule with delay
+        future = if attempt.zero?
+                   Concurrent::Promises.future { yield(attempt) }
+                 else
+                   Concurrent::Promises.schedule(@delay * attempt) { yield(attempt) }
+                 end
+
+        # Race to resolve first_result
+        future.then do |result|
+          if !first_result.resolved? && first_result.fulfill(result)
+            # This attempt won the race
+            duration = Time.now.to_f - start_time
+            Instrumentation.hedged_request_winner(request_id, attempt: attempt, duration: duration)
+          end
+          result
+        end.rescue do |error|
+          # Only reject if this was the last attempt and nothing succeeded
+          first_result.reject(error) if attempt == @max_attempts - 1 && !first_result.resolved?
+        end
+
+        futures << future
+      end
+
+      # Wait with optional timeout
+      if @timeout
+        # Use any_resolved_future with timeout
+        timeout_future = Concurrent::Promises.schedule(@timeout) do
+          raise TimeoutError, "Hedged request timed out after #{@timeout}s"
+        end
+
+        Concurrent::Promises.any_resolved_future(first_result, timeout_future).value!
+      else
+        first_result.value!
+      end
+    ensure
+      # Cancel pending futures
+      futures.each { |f| f.cancel if f.pending? }
+    end
+
+    # Run async version
+    def run_async(&)
+      Concurrent::Promises.future { run(&) }
+    end
+
+    # Shutdown the executor
+    def shutdown
+      @executor.shutdown
+      @executor.wait_for_termination(5)
+    end
+  end
+
+  # Convenience method
+  def self.hedged_request(**, &)
+    hedged = HedgedRequest.new(**)
+    begin
+      hedged.run(&)
+    ensure
+      hedged.shutdown
+    end
+  end
+end

data/lib/throttle_machines/instrumentation.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  # Instrumentation module for emitting events via ActiveSupport::Notifications
+  module Instrumentation
+    class << self
+      attr_writer :enabled, :backend
+
+      def enabled
+        @enabled = true if @enabled.nil?
+        @enabled
+      end
+
+      def backend
+        @backend ||= ActiveSupport::Notifications
+      end
+
+      def instrument(event_name, payload = {}, &)
+        if !enabled || backend.nil?
+          return yield if block_given?
+
+          return
+        end
+
+        full_event_name = "#{event_name}.throttle_machines"
+        backend.instrument(full_event_name, payload, &)
+      end
+
+      # Convenience methods for common events
+
+      # Rate limiter events
+      def rate_limit_checked(limiter, allowed:, remaining: nil)
+        payload = {
+          key: limiter.key,
+          limit: limiter.limit,
+          period: limiter.period,
+          algorithm: limiter.algorithm,
+          allowed: allowed,
+          remaining: remaining
+        }
+        instrument('rate_limit.checked', payload)
+      end
+
+      def rate_limit_allowed(limiter, remaining: nil)
+        payload = {
+          key: limiter.key,
+          limit: limiter.limit,
+          period: limiter.period,
+          algorithm: limiter.algorithm,
+          remaining: remaining
+        }
+        instrument('rate_limit.allowed', payload)
+      end
+
+      def rate_limit_throttled(limiter, retry_after: nil)
+        payload = {
+          key: limiter.key,
+          limit: limiter.limit,
+          period: limiter.period,
+          algorithm: limiter.algorithm,
+          retry_after: retry_after
+        }
+        instrument('rate_limit.throttled', payload)
+      end
+
+      # Circuit breaker events
+      def circuit_opened(breaker, failure_count:)
+        payload = {
+          key: breaker.key,
+          failure_threshold: breaker.failure_threshold,
+          timeout: breaker.timeout,
+          failure_count: failure_count
+        }
+        instrument('circuit_breaker.opened', payload)
+      end
+
+      def circuit_closed(breaker)
+        payload = {
+          key: breaker.key,
+          failure_threshold: breaker.failure_threshold,
+          timeout: breaker.timeout
+        }
+        instrument('circuit_breaker.closed', payload)
+      end
+
+      def circuit_half_opened(breaker)
+        payload = {
+          key: breaker.key,
+          failure_threshold: breaker.failure_threshold,
+          timeout: breaker.timeout,
+          half_open_requests: breaker.half_open_requests
+        }
+        instrument('circuit_breaker.half_opened', payload)
+      end
+
+      def circuit_success(breaker)
+        payload = {
+          key: breaker.key,
+          state: breaker.state
+        }
+        instrument('circuit_breaker.success', payload)
+      end
+
+      def circuit_failure(breaker, error: nil)
+        payload = {
+          key: breaker.key,
+          state: breaker.state,
+          error_class: error&.class&.name,
+          error_message: error&.message
+        }
+        instrument('circuit_breaker.failure', payload)
+      end
+
+      def circuit_rejected(breaker)
+        payload = {
+          key: breaker.key,
+          failure_threshold: breaker.failure_threshold,
+          timeout: breaker.timeout
+        }
+        instrument('circuit_breaker.rejected', payload)
+      end
+
+      # Cascade events
+      def cascade_triggered(primary_key, cascaded_key)
+        payload = {
+          primary_key: primary_key,
+          cascaded_key: cascaded_key
+        }
+        instrument('cascade.triggered', payload)
+      end
+
+      # Hedged request events
+      def hedged_request_started(request_id, attempts:)
+        payload = {
+          request_id: request_id,
+          max_attempts: attempts
+        }
+        instrument('hedged_request.started', payload)
+      end
+
+      def hedged_request_winner(request_id, attempt:, duration:)
+        payload = {
+          request_id: request_id,
+          winning_attempt: attempt,
+          duration: duration
+        }
+        instrument('hedged_request.winner', payload)
+      end
+    end
+
+    # Null backend for when ActiveSupport::Notifications is not available
+    class NullBackend
+      def instrument(_name, _payload = {})
+        yield if block_given?
+      end
+    end
+  end
+end

data/lib/throttle_machines/limiter.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class Limiter
+    attr_reader :key, :limit, :period, :algorithm, :storage
+
+    def initialize(key, limit:, period:, algorithm: :fixed_window, storage: nil)
+      @key = key
+      @limit = limit
+      @period = period
+      @algorithm = algorithm
+      @storage = storage || ThrottleMachines.storage
+    end
+
+    def allow?
+      allowed = case @algorithm
+                when :fixed_window
+                  # Don't increment here, just check
+                  count = @storage.get_counter(@key, @period)
+                  count < @limit
+                when :gcra
+                  result = @storage.peek_gcra_limit(
+                    @key,
+                    @period.to_f / @limit,  # emission_interval
+                    0                       # delay_tolerance (no burst)
+                  )
+                  result[:allowed]
+                when :token_bucket
+                  result = @storage.peek_token_bucket(
+                    @key,
+                    @limit,                 # capacity
+                    @limit.to_f / @period   # refill_rate
+                  )
+                  result[:allowed]
+                else
+                  raise ArgumentError, "Unknown algorithm: #{@algorithm}"
+                end
+
+      # Instrument the check
+      Instrumentation.rate_limit_checked(self, allowed: allowed, remaining: nil)
+
+      allowed
+    end
+
+    def throttle!
+      case @algorithm
+      when :fixed_window
+        # Increment and check atomically
+        count = @storage.increment_counter(@key, @period)
+        if count > @limit
+          Instrumentation.rate_limit_throttled(self, retry_after: retry_after)
+          raise ThrottledError, self
+        end
+      when :gcra
+        result = @storage.check_gcra_limit(
+          @key,
+          @period.to_f / @limit,  # emission_interval
+          0,                      # delay_tolerance (no burst)
+          (@period * 2).to_i      # ttl
+        )
+        unless result[:allowed]
+          Instrumentation.rate_limit_throttled(self, retry_after: retry_after)
+          raise ThrottledError, self
+        end
+      when :token_bucket
+        result = @storage.check_token_bucket(
+          @key,
+          @limit,                 # capacity
+          @limit.to_f / @period,  # refill_rate
+          (@period * 2).to_i      # ttl
+        )
+        unless result[:allowed]
+          Instrumentation.rate_limit_throttled(self, retry_after: retry_after)
+          raise ThrottledError, self
+        end
+      else
+        raise ArgumentError, "Unknown algorithm: #{@algorithm}"
+      end
+
+      # If we get here, the request was allowed
+      # Calculate remaining after the operation
+      remaining_count = begin
+        remaining
+      rescue StandardError
+        nil
+      end
+      Instrumentation.rate_limit_allowed(self, remaining: remaining_count)
+
+      yield if block_given?
+    end
+
+    def reset!
+      case @algorithm
+      when :fixed_window
+        @storage.reset_counter(@key, @period)
+      else
+        @storage.clear("#{@key}*")
+      end
+    end
+
+    def remaining
+      case @algorithm
+      when :fixed_window
+        count = @storage.get_counter(@key, @period)
+        [@limit - count, 0].max
+      when :gcra
+        # GCRA doesn't have a simple "remaining" count
+        # Just return 1 or 0 based on current state
+        result = @storage.peek_gcra_limit(
+          @key,
+          @period.to_f / @limit,
+          0
+        )
+        result[:allowed] ? 1 : 0
+      when :token_bucket
+        result = @storage.peek_token_bucket(
+          @key,
+          @limit,
+          @limit.to_f / @period
+        )
+        result[:tokens_remaining].to_i
+      else
+        0
+      end
+    end
+
+    def retry_after
+      case @algorithm
+      when :fixed_window
+        count = @storage.get_counter(@key, @period)
+        if count >= @limit
+          # Return the actual time remaining in the current window
+          @storage.get_counter_ttl(@key, @period)
+        else
+          0
+        end
+      when :gcra
+        result = @storage.peek_gcra_limit(
+          @key,
+          @period.to_f / @limit,
+          0
+        )
+        result[:retry_after]
+      when :token_bucket
+        result = @storage.peek_token_bucket(
+          @key,
+          @limit,
+          @limit.to_f / @period
+        )
+        result[:retry_after]
+      else
+        0
+      end
+    end
+
+    def to_h
+      {
+        key: @key,
+        limit: @limit,
+        period: @period,
+        algorithm: @algorithm,
+        remaining: remaining,
+        retry_after: retry_after
+      }
+    end
+  end
+end

data/lib/throttle_machines/middleware.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class Middleware
+    def initialize(app, store: nil, &config_block)
+      @app = app
+      @store = store || ThrottleMachines.configuration.store
+      @rules = []
+
+      instance_eval(&config_block) if config_block
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+
+      @rules.each do |rule|
+        next unless rule[:matcher].call(request)
+
+        key = rule[:key_generator].call(request)
+        limiter = ThrottleMachines.limiter(
+          key,
+          limit: rule[:limit],
+          period: rule[:period],
+          algorithm: rule[:algorithm]
+        )
+
+        return rate_limit_response(limiter) unless limiter.allow?
+      end
+
+      @app.call(env)
+    rescue ThrottledError => e
+      rate_limit_response(e.limiter)
+    end
+
+    def throttle(path, limit:, period:, by: :ip, algorithm: :gcra)
+      @rules << {
+        matcher: build_matcher(path),
+        key_generator: build_key_generator(by),
+        limit: limit,
+        period: period,
+        algorithm: algorithm
+      }
+    end
+
+    private
+
+    def build_matcher(path)
+      case path
+      when String
+        ->(request) { request.path == path }
+      when Regexp
+        ->(request) { request.path =~ path }
+      when Proc
+        path
+      else
+        ->(_request) { true }
+      end
+    end
+
+    def build_key_generator(by)
+      case by
+      when :ip
+        ->(request) { "ip:#{request.ip}" }
+      when Symbol
+        ->(request) { "#{by}:#{request.env['rack.session']&.dig(by)}" }
+      when Proc
+        by
+      else
+        ->(_request) { by.to_s }
+      end
+    end
+
+    def rate_limit_response(limiter)
+      headers = {
+        'Content-Type' => 'application/json',
+        'X-RateLimit-Limit' => limiter.limit.to_s,
+        'X-RateLimit-Remaining' => limiter.remaining.to_s,
+        'X-RateLimit-Reset' => (Time.now.to_i + limiter.retry_after).to_s,
+        'Retry-After' => limiter.retry_after.ceil.to_s
+      }
+
+      body = JSON.generate({
+                             error: 'Rate limit exceeded',
+                             retry_after: limiter.retry_after
+                           })
+
+      [429, headers, [body]]
+    end
+  end
+end

data/lib/throttle_machines/rack_middleware/allow2_ban.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class RackMiddleware
+    class Allow2Ban
+      attr_reader :name, :maxretry, :findtime, :bantime, :block
+
+      def initialize(name, options, &block)
+        @name = name
+        @block = block
+
+        @maxretry = options[:maxretry] || 5
+        @findtime = options[:findtime] || 60
+        @bantime = options[:bantime] || 300
+      end
+
+      def matched_by?(request)
+        discriminator = discriminator_for(request)
+        return false unless discriminator
+
+        # Allow2Ban resets fail2ban counters on successful requests
+        # We'll track successful requests and reset the breaker when threshold is met
+
+        success_key = "allow2ban:#{@name}:#{discriminator}"
+        fail_key = "fail2ban:#{@name}:#{discriminator}"
+
+        # Count successful requests
+        success_limiter = ThrottleMachines.limiter(
+          success_key,
+          limit: @maxretry,
+          period: @findtime,
+          algorithm: :fixed_window
+        )
+
+        # Check if we've had enough successful requests
+        if success_limiter.remaining.zero?
+          # Reset the fail2ban breaker
+          storage = ThrottleMachines.storage
+          storage.reset_breaker(fail_key)
+
+          # Reset our own counter
+          storage.reset_counter(success_key, @findtime)
+        else
+          # Increment success counter
+          begin
+            success_limiter.throttle!
+          rescue ThrottledError
+            # We've hit the limit, which triggers the reset above
+          end
+        end
+
+        false # Allow2Ban never blocks directly
+      end
+
+      private
+
+      def discriminator_for(request)
+        @block.call(request)
+      end
+    end
+  end
+end

data/lib/throttle_machines/rack_middleware/blocklist.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class RackMiddleware
+    class Blocklist
+      attr_reader :name, :block
+
+      def initialize(name, &block)
+        @name = name
+        @block = block
+      end
+
+      def matched_by?(request)
+        return false unless @block
+
+        if @block.call(request)
+          request.env['rack.attack.matched'] = @name
+          request.env['rack.attack.match_type'] = :blocklist
+          ThrottleMachines::RackMiddleware.instrument(request)
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end