throttle_machines 0.2.4-aarch64-linux

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 = {}, &block)
+        if !enabled || backend.nil?
+          return yield if block_given?
+
+          return
+        end
+
+        full_event_name = "#{event_name}.throttle_machines"
+        backend.instrument(full_event_name, payload, &block)
+      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.respond_to?(:name) ? breaker.name : breaker.to_s),
+          failure_threshold: (breaker.respond_to?(:configuration) ? breaker.configuration[:failure_threshold] : nil),
+          timeout: (breaker.respond_to?(:configuration) ? breaker.configuration[:reset_timeout] : nil),
+          failure_count: failure_count
+        }
+        instrument('circuit_breaker.opened', payload)
+      end
+
+      def circuit_closed(breaker)
+        payload = {
+          key: (breaker.respond_to?(:name) ? breaker.name : breaker.to_s),
+          failure_threshold: (breaker.respond_to?(:configuration) ? breaker.configuration[:failure_threshold] : nil),
+          timeout: (breaker.respond_to?(:configuration) ? breaker.configuration[:reset_timeout] : nil)
+        }
+        instrument('circuit_breaker.closed', payload)
+      end
+
+      def circuit_half_opened(breaker)
+        payload = {
+          key: (breaker.respond_to?(:name) ? breaker.name : breaker.to_s),
+          failure_threshold: (breaker.respond_to?(:configuration) ? breaker.configuration[:failure_threshold] : nil),
+          timeout: (breaker.respond_to?(:configuration) ? breaker.configuration[:reset_timeout] : nil),
+          half_open_requests: (breaker.respond_to?(:configuration) ? breaker.configuration[:half_open_calls] : nil)
+        }
+        instrument('circuit_breaker.half_opened', payload)
+      end
+
+      def circuit_success(breaker)
+        payload = {
+          key: (breaker.respond_to?(:name) ? breaker.name : breaker.to_s),
+          state: (breaker.respond_to?(:to_h) ? breaker.to_h[:state] : nil)
+        }
+        instrument('circuit_breaker.success', payload)
+      end
+
+      def circuit_failure(breaker, error: nil)
+        payload = {
+          key: (breaker.respond_to?(:name) ? breaker.name : breaker.to_s),
+          state: (breaker.respond_to?(:to_h) ? breaker.to_h[:state] : nil),
+          error_class: error&.class&.name,
+          error_message: error&.message
+        }
+        instrument('circuit_breaker.failure', payload)
+      end
+
+      def circuit_rejected(breaker)
+        payload = {
+          key: (breaker.respond_to?(:name) ? breaker.name : breaker.to_s),
+          failure_threshold: (breaker.respond_to?(:configuration) ? breaker.configuration[:failure_threshold] : nil),
+          timeout: (breaker.respond_to?(:configuration) ? breaker.configuration[:reset_timeout] : nil)
+        }
+        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,89 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class Middleware
+    def initialize(app, &config_block)
+      @app = app
+      @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/native_speedup.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# Native speedup for ThrottleMachines using Rust FFI.
+#
+# This module is automatically loaded when the native extension is available.
+# It prepends optimized implementations onto Storage::Memory.
+#
+# Environment controls:
+#   DISABLE_MATRYOSHKA_NATIVE=1       - Disable all matryoshka native extensions
+#   DISABLE_THROTTLE_MACHINES_NATIVE=1 - Disable only throttle_machines native
+#   DEBUG_MATRYOSHKA=1                 - Log which backend is loaded
+
+return if ENV["DISABLE_MATRYOSHKA_NATIVE"]
+return if ENV["DISABLE_THROTTLE_MACHINES_NATIVE"]
+
+begin
+  require "throttle_machines_native/throttle_machines_native"
+
+  module ThrottleMachines
+    module Storage
+      # Native GCRA implementation using Rust.
+      module NativeGCRA
+        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 }
+
+            # Rust does the math
+            ThrottleMachinesNative.gcra_check(
+              state[:tat], now, emission_interval, delay_tolerance
+            ) => { allowed:, state: new_tat, retry_after: }
+
+            @gcra_states[key] = { tat: new_tat, expires_at: now + ttl } if allowed
+
+            { allowed: allowed, retry_after: retry_after, tat: new_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 }
+
+            # Rust does the math
+            ThrottleMachinesNative.gcra_peek(
+              state[:tat], now, delay_tolerance
+            ) => { allowed:, state: tat, retry_after: }
+
+            { allowed: allowed, retry_after: retry_after, tat: tat }
+          end
+        end
+      end
+
+      # Native Token Bucket implementation using Rust.
+      module NativeTokenBucket
+        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 }
+
+            # Rust does the math
+            ThrottleMachinesNative.token_bucket_check(
+              bucket[:tokens], bucket[:last_refill], now, capacity, refill_rate
+            ) => { allowed:, state: new_tokens, retry_after: }
+
+            if allowed
+              @token_buckets[key] = { tokens: new_tokens, last_refill: now, expires_at: now + ttl }
+            end
+
+            { allowed: allowed, retry_after: retry_after, tokens_remaining: new_tokens.floor }
+          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 }
+
+            # Rust does the math
+            ThrottleMachinesNative.token_bucket_peek(
+              bucket[:tokens], bucket[:last_refill], now, capacity, refill_rate
+            ) => { allowed:, state: tokens, retry_after: }
+
+            { allowed: allowed, retry_after: retry_after, tokens_remaining: tokens.floor }
+          end
+        end
+      end
+    end
+  end
+
+  # Prepend native implementations
+  ThrottleMachines::Storage::Memory.prepend(ThrottleMachines::Storage::NativeGCRA)
+  ThrottleMachines::Storage::Memory.prepend(ThrottleMachines::Storage::NativeTokenBucket)
+
+  warn "[ThrottleMachines] Native speedup loaded" if ENV["DEBUG_MATRYOSHKA"]
+rescue LoadError => e
+  warn "[ThrottleMachines] Native speedup unavailable: #{e.message}" if ENV["DEBUG_MATRYOSHKA"]
+end

data/lib/throttle_machines/rack_middleware/allow2_ban.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class RackMiddleware
+    class Allow2Ban < BanFilter
+      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 (use BreakerMachines circuit)
+          breaker = BreakerMachines::Registry.instance.get_or_create_dynamic_circuit(
+            fail_key,
+            self,
+            failure_threshold: @maxretry,
+            failure_window: @findtime,
+            reset_timeout: @bantime
+          )
+          breaker.hard_reset
+
+          # Reset our own counter
+          ThrottleMachines.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
+    end
+  end
+end

data/lib/throttle_machines/rack_middleware/ban_filter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class RackMiddleware
+    # Base class for Fail2Ban and Allow2Ban filters.
+    #
+    # Both are configured with the same maxretry/findtime/bantime thresholds and
+    # derive a discriminator from the request via the supplied block. The ban
+    # logic itself lives in each subclass.
+    class BanFilter
+      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
+
+      private
+
+      def discriminator_for(request)
+        @block.call(request)
+      end
+    end
+  end
+end

data/lib/throttle_machines/rack_middleware/blocklist.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class RackMiddleware
+    # Blocks requests matching the configured block (returns true => blocked).
+    class Blocklist < ListFilter
+      private
+
+      def match_type
+        :blocklist
+      end
+    end
+  end
+end