throttle_machines 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c3f17388a485325a47d600dec9898d47b2d89a1beb457bd7d2cd150458009df
-  data.tar.gz: 1d70a4b143228755af8eb22de03e907fbbbe886c389c793f8ab8b9064f3f4845
+  metadata.gz: 21546f9777cfd269ba2461dd3a3200173591defc6f20effb84fa8b7fb254353c
+  data.tar.gz: 4f82a87423e163ba277c5707b65dc122b1f0ba047ed97c29b5a877c14af92d94
 SHA512:
-  metadata.gz: 48bd7a5b4cdd3b1ad461211879b439d41247764e75e35761eb56de7b010ac83242c303cf6fa3aa2b4b515a1c5d609497a79e305d6e847b79c5d3e9d82dd67bf2
-  data.tar.gz: f494acc74267e66616e179a74deaab41c189a481f407425210076d59d2f5e0d3e51baf183c4e6625975352577e171f2da303929fc40228b3235debb4c5810a60
+  metadata.gz: 61d639a39194c9d504871e2159a30ab89671d3f42f333d1f283ecc7a7fb1c238d948a5dfa3c336a6c05fec5e3065613d00610027fbdcf6af0d3df5277dc02a2a
+  data.tar.gz: b844e1d3ce3949c273e996972770f7d5f1aa1d3a5729da02d54651915bd826b327dd2826e96d4c09ac6ac921e720b437494ed3eac4d2c7b8db776e6f50244d3a

data/MIT-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

@@ -1,27 +1,201 @@
-# ThrottleMachines
+# ThrottleMachines 🚀
 
-ThrottleMachines provides advanced throttling and rate limiting mechanisms for distributed systems with intelligent backoff strategies, circuit breakers, and adaptive rate control.
+> **Ultra-thin rate limiting for the cosmos** - Where every request has its own trajectory through spacetime
 
-## Installation
+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.
 
-Add this line to your application's Gemfile:
+---
 
-```ruby
+## 🌌 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
+```
+
+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!
 ```
 
-And then execute:
+### 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 ∞*
+
+---
 
-    $ bundle install
+## The Fleet Admiral's Warning
 
-Or install it yourself as:
+So you built a microservice architecture because a YouTube video told you it was 'web scale'?
 
-    $ gem install throttle_machines
+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.
 
-## Note
+This is your life raft. Don't let go.
 
-This is a placeholder gem. The full implementation is coming soon.
+---
 
-## License
+**"In space, nobody can hear your servers scream. But with ThrottleMachines, they won't need to."**
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+*— Fleet Admiral J'Rao, Survivor of the Great DDoS Wars of 2019*

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb'].exclude('test/dummy/**/*')
+  t.verbose = false
+end
+
+task default: :test

data/lib/throttle_machines/async_limiter.rb

@@ -0,0 +1,134 @@
+# 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).
+  #
+  # Example:
+  #   limiter = ThrottleMachines::AsyncLimiter.new("quantum_comms",
+  #     limit: 100,
+  #     period: 60,
+  #     algorithm: :gcra
+  #   )
+  #
+  #   Async do
+  #     if limiter.allowed_async?
+  #       # Non-blocking operation
+  #     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/clock.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ThrottleMachines
+  # TestClock for time manipulation in tests
+  # This overrides the global monotonic_time method for testing
+  class TestClock
+    attr_accessor :current_time
+
+    def initialize(start_time = Time.now.to_f)
+      @current_time = start_time
+      
+      # Override the global monotonic_time method
+      ThrottleMachines.singleton_class.define_method(:monotonic_time) do
+        @current_time
+      end
+    end
+
+    def now
+      @current_time
+    end
+
+    def monotonic
+      @current_time
+    end
+
+    def advance(seconds)
+      @current_time += seconds
+    end
+
+    def travel_to(time)
+      @current_time = time.to_f
+    end
+
+    def reset
+      # Restore the original monotonic_time method
+      ThrottleMachines.singleton_class.define_method(:monotonic_time) do
+        BreakerMachines.monotonic_time
+      end
+    end
+  end
+end

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)
+        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:, &)
+      key ||= default_throttle_key
+
+      ThrottleMachines.limit(key, limit: limit, period: period, &)
+    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,25 @@
+# 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
+
+    initializer 'throttle_machines.configure_defaults' do |_app|
+      ThrottleMachines.configure do |config|
+        # Use Redis if available in Rails cache
+        if defined?(Redis) && Rails.cache.respond_to?(:redis)
+          config.store = ThrottleMachines::Stores::Redis.new(Rails.cache.redis)
+        end
+      end
+    end
+  end
+end