throttle_machines 0.1.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c498f9f097c1eac7384d573ea5e90b04e3850d6b236aae5a0f5b9bb0cdf29ae
-  data.tar.gz: 515fae0aad7083290b12cec368148e021ff9312fb026892fb4574fd89a1a0f6c
+  metadata.gz: 6450b4499ed28a6520bdc5d51a2c5bc7fcc55ba8e1f1e327def0ca9ab5c80d62
+  data.tar.gz: af1addd1f524c9f5663f3f241ce15bfb1aa9a6b5365463f3c9d453a9e03f0b05
 SHA512:
-  metadata.gz: ec8ac810c8696a93a44bcf305245eef336ce338418b82a5236e73fa919afda7125cee2ac391c0230419f136525ee1104723dc3a81e42517c4c0a48ebd6878d76
-  data.tar.gz: 3908d0866286abc0556b79160c8543da2b542ab3cfb55b2c2d636fc69bb0393196848f920714e89e4926d7e4450ae5de33329d0774ae4a0f8f59860bbbaad620
+  metadata.gz: 564076859ef7219e48060400a26295cffc830a74fbf82d757766753e19d2020fce390ce8b91b9daf996147689dd47fec0911037a34a0208cd160ec3d6009ac70
+  data.tar.gz: 39590d460f59b66a700487146ea3309aa8df4d9f3b31e0248acb1b0748bc04b3a26f9a55f52f18b4beb3fca7618a8142092b4d434f45a4ce833a265d8e2c5fdb

data/README.md

@@ -33,6 +33,9 @@ gem 'redis'
 
 # For planetary Rails integration
 gem 'rails' # or just railties
+
+# For fiber-safe async throttling
+gem 'async'
 ```
 
 Then initialize systems:

data/lib/throttle_machines/async_breaker.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class AsyncBreaker
+    class << self
+      def new(...)
+        ThrottleMachines.load_async_runtime!
+        BreakerMachines::AsyncCircuit.new(...)
+      end
+    end
+  end
+end

data/lib/throttle_machines/async_limiter.rb

@@ -1,16 +1,10 @@
 # frozen_string_literal: true
 
-require 'concurrent-ruby'
-
 module ThrottleMachines
-  # Async-aware rate limiter for fiber-safe operations
-  #
-  # Like quantum entanglement communications - allows multiple spacecraft
-  # to communicate simultaneously without interference, each in their own
-  # quantum state (fiber).
+  # Backward-compatible async-aware limiter class.
   #
   # Example:
-  #   limiter = ThrottleMachines::AsyncLimiter.new("quantum_comms",
+  #   limiter = ThrottleMachines::AsyncLimiter.new("api",
   #     limit: 100,
   #     period: 60,
   #     algorithm: :gcra
@@ -18,117 +12,13 @@ module ThrottleMachines
   #
   #   Async do
   #     if limiter.allowed_async?
-  #       # Non-blocking operation
+  #       # Currently allowed without consuming capacity
+  #     end
+  #
+  #     limiter.throttle_async(max_wait: 5) do
+  #       # Consumes capacity through the same atomic path as throttle!
   #     end
   #   end
   class AsyncLimiter < Limiter
-    def initialize(key, limit:, period:, algorithm: :fixed_window, storage: nil)
-      super
-      @fiber_storage = Concurrent::Map.new # Thread-safe fiber storage
-    end
-
-    # Async version of allowed? that's fiber-safe
-    def allowed_async?
-      allowed = if defined?(Async::Task) && Async::Task.current?
-                  # In async context, use fiber-local checking
-                  fiber_allowed?
-                else
-                  # Fall back to regular synchronous check
-                  allowed?
-                end
-
-      # Don't double-instrument when calling parent allowed?
-      return allowed unless defined?(Async::Task) && Async::Task.current?
-
-      # Instrument the async check
-      Instrumentation.rate_limit_checked(self, allowed: allowed, remaining: nil)
-      allowed
-    end
-
-    # Non-blocking check with async support
-    def check_async
-      if allowed_async?
-        yield if block_given?
-        true
-      else
-        false
-      end
-    end
-
-    # Async throttle with automatic retry
-    def throttle_async(max_wait: nil)
-      start_time = current_time
-
-      loop do
-        if allowed_async?
-          return yield if block_given?
-
-          return true
-        end
-
-        wait_time = retry_after
-
-        # Check if we've exceeded max wait time
-        if max_wait && (current_time - start_time + wait_time) > max_wait
-          raise ThrottleError, 'Maximum wait time exceeded'
-        end
-
-        # Non-blocking sleep in async context
-        if defined?(Async::Task) && Async::Task.current?
-          Async::Task.current.sleep(wait_time)
-        else
-          sleep(wait_time)
-        end
-      end
-    end
-
-    # Get current fiber's state
-    def fiber_state
-      fiber_id = Fiber.current.object_id
-      @fiber_storage.compute_if_absent(fiber_id) do
-        {
-          last_check: 0,
-          tokens: @limit.to_f
-        }
-      end
-    end
-
-    # Clean up fiber storage periodically
-    def cleanup_fiber_storage
-      current_fibers = ObjectSpace.each_object(Fiber).map(&:object_id)
-      @fiber_storage.each_key do |fiber_id|
-        @fiber_storage.delete(fiber_id) unless current_fibers.include?(fiber_id)
-      end
-    end
-
-    private
-
-    def fiber_allowed?
-      state = fiber_state
-      now = current_time
-
-      case @algorithm
-      when :token_bucket
-        # Refill tokens based on time passed
-        time_passed = now - state[:last_check]
-        tokens_to_add = time_passed * (@limit.to_f / @period)
-        state[:tokens] = [state[:tokens] + tokens_to_add, @limit.to_f].min
-        state[:last_check] = now
-
-        if state[:tokens] >= 1
-          state[:tokens] -= 1
-          true
-        else
-          false
-        end
-      else
-        # Delegate to parent for other algorithms
-        allowed?
-      end
-    end
-
-    def current_time
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    end
   end
 end

data/lib/throttle_machines/async_support.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Async/Fiber support for ThrottleMachines.
+#
+# The async gem is optional. When an Async task is active, waits yield back to
+# the scheduler; otherwise the limiter falls back to normal sleep.
+
+module ThrottleMachines
+  # Fiber-aware rate limiter helpers.
+  module AsyncSupport
+    def allowed_async?
+      allow?
+    end
+
+    alias allow_async? allowed_async?
+
+    def check_async
+      return false unless allowed_async?
+
+      yield if block_given?
+      true
+    end
+
+    def throttle_async(max_wait: nil, &block)
+      deadline = max_wait.nil? ? nil : ThrottleMachines.monotonic_time + max_wait.to_f
+
+      loop do
+        begin
+          throttle!
+        rescue ThrottledError => e
+          wait_time = [e.retry_after.to_f, 0.0].max
+
+          if deadline
+            remaining_wait = deadline - ThrottleMachines.monotonic_time
+            raise if remaining_wait <= 0 || wait_time > remaining_wait
+          end
+
+          sleep_for(wait_time)
+          next
+        end
+
+        return block.call if block
+
+        return true
+      end
+    end
+
+    private
+
+    # Use Async's fiber-aware sleep when in an async context.
+    def sleep_for(duration)
+      if (task = current_async_task)
+        task.sleep(duration)
+      else
+        sleep(duration)
+      end
+    end
+
+    def current_async_task
+      return nil unless defined?(::Async::Task)
+
+      if ::Async::Task.respond_to?(:current?)
+        ::Async::Task.current?
+      else
+        ::Async::Task.current
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end
+
+ThrottleMachines::Limiter.include(ThrottleMachines::AsyncSupport)
+
+warn "[ThrottleMachines] Async support loaded" if ENV['DEBUG_MATRYOSHKA']

data/lib/throttle_machines/controller_helpers.rb

@@ -21,10 +21,10 @@ module ThrottleMachines
       set_rate_limit_headers(limiter)
     end
 
-    def with_throttle(key = nil, limit:, period:, &)
+    def with_throttle(key = nil, limit:, period:, &block)
       key ||= default_throttle_key
 
-      ThrottleMachines.limit(key, limit: limit, period: period, &)
+      ThrottleMachines.limit(key, limit: limit, period: period, &block)
     rescue ThrottledError => e
       render_rate_limited(e.limiter)
     end

data/lib/throttle_machines/engine.rb

@@ -13,11 +13,6 @@ module ThrottleMachines
       end
     end
 
-    initializer 'throttle_machines.configure_defaults' do |_app|
-      ThrottleMachines.configure do |config|
-        # Use Rails.cache , user can override
-        config.store = Rails.cache
-      end
-    end
+    # No default Rails.cache binding; storage is managed by ThrottleMachines
   end
 end

data/lib/throttle_machines/hedged_breaker.rb

@@ -11,12 +11,12 @@ module ThrottleMachines
       )
     end
 
-    def run(&)
+    def run(&block)
       @hedged.run do |attempt|
         breaker = @breakers[attempt]
         next if breaker.nil?
 
-        breaker.call(&)
+        breaker.call(&block)
       end
     end
   end

data/lib/throttle_machines/hedged_request.rb

@@ -94,8 +94,8 @@ module ThrottleMachines
     end
 
     # Run async version
-    def run_async(&)
-      Concurrent::Promises.future { run(&) }
+    def run_async(&block)
+      Concurrent::Promises.future { run(&block) }
     end
 
     # Shutdown the executor

data/lib/throttle_machines/instrumentation.rb

@@ -15,7 +15,7 @@ module ThrottleMachines
         @backend ||= ActiveSupport::Notifications
       end
 
-      def instrument(event_name, payload = {}, &)
+      def instrument(event_name, payload = {}, &block)
         if !enabled || backend.nil?
           return yield if block_given?
 
@@ -23,7 +23,7 @@ module ThrottleMachines
         end
 
         full_event_name = "#{event_name}.throttle_machines"
-        backend.instrument(full_event_name, payload, &)
+        backend.instrument(full_event_name, payload, &block)
       end
 
       # Convenience methods for common events
@@ -66,9 +66,9 @@ module ThrottleMachines
       # Circuit breaker events
       def circuit_opened(breaker, failure_count:)
         payload = {
-          key: breaker.key,
-          failure_threshold: breaker.failure_threshold,
-          timeout: breaker.timeout,
+          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)
@@ -76,35 +76,35 @@ module ThrottleMachines
 
       def circuit_closed(breaker)
         payload = {
-          key: breaker.key,
-          failure_threshold: breaker.failure_threshold,
-          timeout: breaker.timeout
+          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.key,
-          failure_threshold: breaker.failure_threshold,
-          timeout: breaker.timeout,
-          half_open_requests: breaker.half_open_requests
+          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.key,
-          state: breaker.state
+          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.key,
-          state: breaker.state,
+          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
         }
@@ -113,9 +113,9 @@ module ThrottleMachines
 
       def circuit_rejected(breaker)
         payload = {
-          key: breaker.key,
-          failure_threshold: breaker.failure_threshold,
-          timeout: breaker.timeout
+          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

data/lib/throttle_machines/middleware.rb

@@ -2,9 +2,8 @@
 
 module ThrottleMachines
   class Middleware
-    def initialize(app, store: nil, &config_block)
+    def initialize(app, &config_block)
       @app = app
-      @store = store || ThrottleMachines.configuration.store
       @rules = []
 
       instance_eval(&config_block) if config_block

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

@@ -2,18 +2,7 @@
 
 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
-
+    class Allow2Ban < BanFilter
       def matched_by?(request)
         discriminator = discriminator_for(request)
         return false unless discriminator
@@ -34,12 +23,18 @@ module ThrottleMachines
 
         # 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 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
-          storage.reset_counter(success_key, @findtime)
+          ThrottleMachines.storage.reset_counter(success_key, @findtime)
         else
           # Increment success counter
           begin
@@ -51,12 +46,6 @@ module ThrottleMachines
 
         false # Allow2Ban never blocks directly
       end
-
-      private
-
-      def discriminator_for(request)
-        @block.call(request)
-      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

@@ -2,25 +2,12 @@
 
 module ThrottleMachines
   class RackMiddleware
-    class Blocklist
-      attr_reader :name, :block
+    # Blocks requests matching the configured block (returns true => blocked).
+    class Blocklist < ListFilter
+      private
 
-      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
+      def match_type
+        :blocklist
       end
     end
   end

data/lib/throttle_machines/rack_middleware/configuration.rb

@@ -32,27 +32,27 @@ module ThrottleMachines
       end
 
       # DSL Methods
-      def throttle(name, options = {}, &)
-        @throttles[name] = Throttle.new(name, options, &)
+      def throttle(name, options = {}, &block)
+        @throttles[name] = Throttle.new(name, options, &block)
       end
 
-      def track(name, options = {}, &)
-        @tracks[name] = Track.new(name, options, &)
+      def track(name, options = {}, &block)
+        @tracks[name] = Track.new(name, options, &block)
       end
 
-      def safelist(name = nil, &)
+      def safelist(name = nil, &block)
         if name
-          @safelists[name] = Safelist.new(name, &)
+          @safelists[name] = Safelist.new(name, &block)
         else
-          @anonymous_safelists << Safelist.new(nil, &)
+          @anonymous_safelists << Safelist.new(nil, &block)
         end
       end
 
-      def blocklist(name = nil, &)
+      def blocklist(name = nil, &block)
         if name
-          @blocklists[name] = Blocklist.new(name, &)
+          @blocklists[name] = Blocklist.new(name, &block)
         else
-          @anonymous_blocklists << Blocklist.new(nil, &)
+          @anonymous_blocklists << Blocklist.new(nil, &block)
         end
       end
 
@@ -64,12 +64,12 @@ module ThrottleMachines
         @anonymous_blocklists << Blocklist.new(nil) { |req| req.ip == ip_address }
       end
 
-      def fail2ban(name, options = {}, &)
-        @fail2bans[name] = Fail2Ban.new(name, options, &)
+      def fail2ban(name, options = {}, &block)
+        @fail2bans[name] = Fail2Ban.new(name, options, &block)
       end
 
-      def allow2ban(name, options = {}, &)
-        @allow2bans[name] = Allow2Ban.new(name, options, &)
+      def allow2ban(name, options = {}, &block)
+        @allow2bans[name] = Allow2Ban.new(name, options, &block)
       end
 
       # Check methods