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.

• 🎯 Mission Control - Quick start guide for captains
• 🛸 Spacecraft Manual - Understanding the fleet (algorithms)
• ⚡ Warp Drive Configuration - Storage backends & performance
• 🛡️ Shield Protocols - Circuit breakers & defensive systems
• 🌍 Planetary Integration - Rails & Rack middleware
• 🔬 Space Lab - Testing in zero gravity
• 📡 Telemetry - Monitoring & instrumentation
• 🎮 Command Examples - Real mission scenarios
• 📜 Mission Logs - Lessons from real incidents
• 🚀 Advanced Features - Next-generation capabilities

# 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:

bundle install

# 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: 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!

# 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

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

• 🚀 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

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.

See our Mission Archives for the full history of our voyages.

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)

Found a breach in the hull? Encountered an unknown anomaly?

• Emergency beacon: GitHub Issues
• Mission reports: Discussions

MIT License - See LICENSE for full transmission.

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 ∞

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