throttle_machines 0.2.4-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b903b7c1264b244a780a3730bd09d7bdab11db1f28961910980d93d7722ff92e
+  data.tar.gz: d6229cb0f861acea1f76e99a8ec4bcd0c3217f10745467f6411c5383519fe84b
+SHA512:
+  metadata.gz: f35c2f3f16752f64e34105a201f5854b157a0f5092972acb47310802400502474d3d74ca52852056b77932c442af3d76ab0edec0becdd0142a07d4c17a11159e
+  data.tar.gz: 7c20314309fda5045cc7109b03b79dcdac901cb1ce9e83011cf59f6f1906c24f3fd9e6db7b86aff3091deebd21fdbd02118db08d9bce43d7a3f5be6c06111d0c

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2025 Abdelkader Boudih
+
+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.

data/README.md

@@ -0,0 +1,204 @@
+# ThrottleMachines 🚀
+
+> **Ultra-thin rate limiting for the cosmos** - Where every request has its own trajectory through spacetime
+
+A precision-engineered Ruby rate limiting library built for interstellar traffic control.
+Whether you're throttling API calls, AI requests, or quantum communications, ThrottleMachines ensures your systems maintain perfect orbital stability.
+
+---
+
+## 🌌 Navigation
+
+* [🎯 Mission Control](docs/MISSION_CONTROL.md) - Quick start guide for captains
+* [🛸 Spacecraft Manual](docs/SPACECRAFT_MANUAL.md) - Understanding the fleet (algorithms)
+* [⚡ Warp Drive Configuration](docs/WARP_DRIVE.md) - Storage backends & performance
+* [🛡️ Shield Protocols](docs/SHIELD_PROTOCOLS.md) - Circuit breakers & defensive systems
+* [🌍 Planetary Integration](docs/PLANETARY_INTEGRATION.md) - Rails & Rack middleware
+* [🔬 Space Lab](docs/SPACE_LAB.md) - Testing in zero gravity
+* [📡 Telemetry](docs/TELEMETRY.md) - Monitoring & instrumentation
+* [🎮 Command Examples](docs/COMMAND_EXAMPLES.md) - Real mission scenarios
+* [📜 Mission Logs](docs/MISSION_LOGS.md) - Lessons from real incidents
+* [🚀 Advanced Features](docs/ADVANCED_FEATURES.md) - Next-generation capabilities
+
+---
+
+## 🚀 Launch Sequence
+
+```bash
+# Add to your ship's Gemfile
+gem 'throttle_machines'
+
+# For warp drive capabilities (Redis storage)
+gem 'redis'
+
+# For planetary Rails integration
+gem 'rails' # or just railties
+
+# For fiber-safe async throttling
+gem 'async'
+```
+
+Then initialize systems:
+```bash
+bundle install
+```
+
+---
+
+## 🎯 Quick Mission Brief
+
+### Basic Throttling - The Photon Torpedo Approach
+
+```ruby
+# Simple rate limiting - like controlling photon torpedo launches
+torpedo_limiter = ThrottleMachines.limiter("photon_launcher",
+  limit: 10,     # 10 torpedoes
+  period: 60     # per minute
+)
+
+# Check and consume approach
+if torpedo_limiter.allow?
+  torpedo_limiter.throttle!  # Consume one torpedo charge
+  launch_torpedo!
+else
+  puts "Torpedo bay recharging... Please wait."
+end
+
+# OR use the exception approach
+begin
+  torpedo_limiter.throttle!
+  launch_torpedo!
+rescue ThrottleMachines::ThrottledError => e
+  puts "Torpedo bay recharging... Retry after #{e.limiter.retry_after} seconds"
+end
+```
+
+### GCRA - The Federation Diplomatic Ship 🛸
+
+```ruby
+# GCRA: Like a diplomatic vessel that smoothly navigates traffic
+# Instead of sudden stops, it gracefully manages flow
+diplomatic_limiter = ThrottleMachines.limiter("federation_embassy",
+  limit: 100,
+  period: 60,
+  algorithm: :gcra  # Generic Cell Rate Algorithm
+)
+
+# GCRA ensures smooth traffic - no thundering herds at your space dock!
+```
+
+### Block Form - Fire and Forget 🎯
+
+```ruby
+# Use the block form for automatic throttling
+# This handles the throttle! and error handling for you
+ThrottleMachines.limit("warp_drive", limit: 5, period: 60) do
+  engage_warp_drive!  # This will be throttled automatically
+end
+# Raises ThrottledError if limit exceeded
+```
+
+---
+
+## 🌠 The Ultra-Thin Philosophy
+
+Like the best spacecraft, ThrottleMachines follows the principle of **ultra-thin design**:
+
+- **No bloat** - Every component serves a critical function
+- **No dependencies** - Operates in deep space without supply lines
+- **Pure Ruby propulsion** - No alien technology required
+- **Modular systems** - Swap components like ship modules
+
+---
+
+## ⚡ Warp Factor Features
+
+- **🚀 Multiple Algorithms** - GCRA, Token Bucket, Fixed Window, Sliding Window
+- **💫 Distributed Ready** - Redis backend for fleet coordination
+- **🔄 Async Support** - Fiber-safe operations for quantum communications
+- **🏃 Hedged Requests** - Multi-path navigation for reduced latency
+- **🎯 Microsecond Precision** - Navigate the cosmos with temporal accuracy
+- **🔌 Pluggable Storage** - Memory crystals or Redis quantum storage
+- **🌍 Rails Integration** - Seamless planetary docking procedures
+- **📡 Rack Middleware** - Universal translator for all spacecraft
+- **🔍 Full Instrumentation** - Real-time telemetry via ActiveSupport::Notifications
+- **⚡ Thread-Safe** - Safe for multi-threaded spacecraft operations
+- **🎭 Multiple Usage Patterns** - Check-first, exception-based, or block form
+
+---
+
+## 🌌 Why ThrottleMachines?
+
+In the vast expanse of cyberspace, your systems face:
+- **Asteroid fields** of concurrent requests
+- **Black holes** of resource exhaustion
+- **Alien attacks** from malicious actors
+- **Temporal anomalies** in distributed systems
+
+ThrottleMachines is your navigation system through these dangers, ensuring safe passage for every request in your fleet.
+
+---
+
+## 📜 Captain's Log
+
+See our [Mission Archives](CHANGELOG.md) for the full history of our voyages.
+
+---
+
+## 🤝 Join the Crew
+
+1. Signal your intent (`fork` the repository)
+2. Create your feature branch (`git checkout -b feature/quantum-throttling`)
+3. Document your modifications (`git commit -am 'Add quantum entanglement support'`)
+4. Transmit to mothership (`git push origin feature/quantum-throttling`)
+5. Request docking clearance (`Pull Request`)
+
+---
+
+## 📡 Distress Signals
+
+Found a breach in the hull? Encountered an unknown anomaly?
+- **Emergency beacon**: [GitHub Issues](https://github.com/seuros/throttle_machines/issues)
+- **Mission reports**: [Discussions](https://github.com/seuros/throttle_machines/discussions)
+
+---
+
+## 🎖️ Mission Credentials
+
+MIT License - See [LICENSE](LICENSE) for full transmission.
+
+---
+
+## A Message from the Temporal Defense Corps
+
+*The Quantum Navigation Computer flickers to life:*
+
+"Space is vast. Time is relative. And your API is getting hammered by a bot farm in Eastern Europe.
+
+Welcome to the temporal wars, where milliseconds matter and rate limits are the thin line between order and chaos. You think you're just limiting requests? No, pilot. You're manipulating the very fabric of spacetime to ensure fair resource distribution across the quantum multiverse of your distributed system.
+
+Every request has a trajectory. Every limit has a purpose. Every algorithm is a different spacecraft designed for a specific mission through the hostile void.
+
+The universe doesn't care about your startup's runway or your clever blog post about 'Building a Rate Limiter in 5 Minutes with Redis.' It cares about one immutable law:
+
+**Can your system maintain temporal stability when the thundering herd arrives?**
+
+If not, welcome aboard. We have algorithms."
+
+*— Quantum Navigation Computer, Log Entry ∞*
+
+---
+
+## The Fleet Admiral's Warning
+
+So you built a microservice architecture because a YouTube video told you it was 'web scale'?
+
+Now you're drowning in a sea of uncontrolled requests, cascade failures, and that one service that keeps calling your API 10,000 times per second because someone forgot to implement exponential backoff.
+
+This is your life raft. Don't let go.
+
+---
+
+**"In space, nobody can hear your servers scream. But with ThrottleMachines, they won't need to."**
+
+*— Fleet Admiral J'Rao, Survivor of the Great DDoS Wars of 2019*

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  # Backward-compatible async-aware limiter class.
+  #
+  # Example:
+  #   limiter = ThrottleMachines::AsyncLimiter.new("api",
+  #     limit: 100,
+  #     period: 60,
+  #     algorithm: :gcra
+  #   )
+  #
+  #   Async do
+  #     if limiter.allowed_async?
+  #       # 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
+  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/control.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  class Control
+    attr_reader :key, :limiter, :breaker, :retrier
+
+    def initialize(key)
+      @key = key
+      @rules = {}
+    end
+
+    def limit(rate:, per:, algorithm: :gcra)
+      @rules[:limit] = { rate: rate, period: per, algorithm: algorithm }
+      self
+    end
+
+    def break_on(failures:, within:, timeout: nil)
+      timeout ||= within
+      @rules[:breaker] = {
+        failure_threshold: failures,
+        timeout: timeout,
+        window: within
+      }
+      self
+    end
+
+    def retry_on_failure(times:, backoff: :exponential, base_delay: 1, max_delay: 60)
+      @rules[:retry] = {
+        max_attempts: times,
+        jitter: backoff,
+        base_delay: base_delay,
+        max_delay: max_delay
+      }
+      self
+    end
+
+    def call(&block)
+      setup_components
+
+      # Build execution chain: Retry -> Breaker -> Limiter -> User Code
+      execution_chain = block
+
+      # Wrap with rate limiter (innermost, checked first)
+      if @limiter
+        limiter_wrapped = execution_chain
+        execution_chain = proc { @limiter.throttle!(&limiter_wrapped) }
+      end
+
+      # Wrap with circuit breaker
+      if @breaker
+        breaker_wrapped = execution_chain
+        execution_chain = proc { @breaker.call(&breaker_wrapped) }
+      end
+
+      # Wrap with retry logic (outermost, handles all failures)
+      if @retrier
+        retry_wrapped = execution_chain
+        execution_chain = proc { @retrier.call(&retry_wrapped) }
+      end
+
+      execution_chain.call
+    end
+
+    private
+
+    def setup_components
+      if @rules[:limit] && !@limiter
+        @limiter = ThrottleMachines.limiter(@key,
+                                            limit: @rules[:limit][:rate],
+                                            period: @rules[:limit][:period],
+                                            algorithm: @rules[:limit][:algorithm])
+      end
+
+      if @rules[:breaker] && !@breaker
+        @breaker = BreakerMachines::Circuit.new(
+          @key,
+          failure_threshold: @rules[:breaker][:failure_threshold],
+          failure_window: @rules[:breaker][:window],
+          reset_timeout: @rules[:breaker][:timeout]
+        )
+      end
+
+      return unless @rules[:retry] && !@retrier
+
+      # Use ChronoMachines for retry functionality
+      policy_options = {
+        max_attempts: @rules[:retry][:max_attempts],
+        base_delay: @rules[:retry][:base_delay],
+        max_delay: @rules[:retry][:max_delay],
+        jitter_factor: @rules[:retry][:jitter] == :exponential ? 1.0 : 0.0
+      }
+      @retrier = ChronoMachines::Executor.new(policy_options)
+    end
+  end
+end

data/lib/throttle_machines/controller_helpers.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      if respond_to?(:helper_method) # No available in API Mode
+        helper_method :rate_limited?
+        helper_method :rate_limit_remaining
+      end
+    end
+
+    def throttle!(key = nil, limit:, period:, algorithm: :gcra)
+      key ||= default_throttle_key
+
+      limiter = ThrottleMachines.limiter(key, limit: limit, period: period, algorithm: algorithm)
+
+      render_rate_limited(limiter) unless limiter.allow?
+
+      set_rate_limit_headers(limiter)
+    end
+
+    def with_throttle(key = nil, limit:, period:, &block)
+      key ||= default_throttle_key
+
+      ThrottleMachines.limit(key, limit: limit, period: period, &block)
+    rescue ThrottledError => e
+      render_rate_limited(e.limiter)
+    end
+
+    def rate_limited?(key = nil, limit:, period:)
+      key ||= default_throttle_key
+      limiter = ThrottleMachines.limiter(key, limit: limit, period: period)
+      !limiter.allow?
+    end
+
+    def rate_limit_remaining(key = nil, limit:, period:)
+      key ||= default_throttle_key
+      limiter = ThrottleMachines.limiter(key, limit: limit, period: period)
+      limiter.remaining
+    end
+
+    private
+
+    def default_throttle_key
+      if current_user.respond_to?(:id)
+        "user:#{current_user.id}"
+      else
+        "ip:#{request.remote_ip}"
+      end
+    end
+
+    def render_rate_limited(limiter)
+      set_rate_limit_headers(limiter)
+
+      respond_to do |format|
+        format.json do
+          render json: {
+            error: 'Rate limit exceeded',
+            retry_after: limiter.retry_after
+          }, status: :too_many_requests
+        end
+
+        format.html do
+          render plain: "Rate limit exceeded. Please try again in #{limiter.retry_after} seconds.",
+                 status: :too_many_requests
+        end
+      end
+    end
+
+    def set_rate_limit_headers(limiter)
+      response.headers['X-RateLimit-Limit'] = limiter.limit.to_s
+      response.headers['X-RateLimit-Remaining'] = limiter.remaining.to_s
+      response.headers['X-RateLimit-Reset'] = (Time.now.to_i + limiter.retry_after).to_s
+      response.headers['Retry-After'] = limiter.retry_after.ceil.to_s
+    end
+  end
+end

data/lib/throttle_machines/dependency_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  # Error raised when dependencies aren't satisfied
+  class DependencyError < StandardError; end
+end

data/lib/throttle_machines/engine.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'throttle_machines/controller_helpers'
+require 'throttle_machines/middleware'
+
+module ThrottleMachines
+  class Engine < ::Rails::Engine
+    isolate_namespace ThrottleMachines
+
+    initializer 'throttle_machines.controller_helpers' do
+      ActiveSupport.on_load(:action_controller) do
+        include ThrottleMachines::ControllerHelpers
+      end
+    end
+
+    # No default Rails.cache binding; storage is managed by ThrottleMachines
+  end
+end

data/lib/throttle_machines/hedged_breaker.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  # Hedged request with circuit breaker integration
+  class HedgedBreaker
+    def initialize(breakers, delay: 0.05)
+      @breakers = Array(breakers)
+      @hedged = HedgedRequest.new(
+        delay: delay,
+        max_attempts: @breakers.size
+      )
+    end
+
+    def run(&block)
+      @hedged.run do |attempt|
+        breaker = @breakers[attempt]
+        next if breaker.nil?
+
+        breaker.call(&block)
+      end
+    end
+  end
+end

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(&block)
+      Concurrent::Promises.future { run(&block) }
+    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