### CI/CD Integration: Test Script Example

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

A bash script demonstrating how to integrate ThrottleMachines testing into a CI/CD pipeline. It includes starting the server, running tests, analyzing results, and checking for expected throttling events.

```shell
#!/bin/bash
# CI test script

# Start server in background
./start_server.sh &
SERVER_PID=$!

# Wait for server to start
sleep 5

# Run tests
./test_rate_limiting_ab.sh

# Analyze results
./analyze_instrumentation_log.rb --json > test_results.json

# Check for expected rate limiting
THROTTLED=$(./analyze_instrumentation_log.rb -e throttled --json | jq '.events | length')
if [ "$THROTTLED" -lt 5 ]; then
  echo "❌ Expected throttling events not found"
  exit 1
fi

# Cleanup
kill $SERVER_PID
echo "✅ Rate limiting tests passed"
```

--------------------------------

### Basic Rate Limiting Test Workflow

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Demonstrates a typical workflow for starting the server, running rate limiting tests, and analyzing the results.

```bash
# Terminal 1: Start server
./start_server.sh --clear-logs

# Terminal 2: Run tests and analyze
./test_rate_limiting_ab.sh --clear-logs
./analyze_instrumentation_log.rb -v

# Monitor in real-time
tail -f log/instrumentation.log
```

--------------------------------

### Install Apache Bench (ab) on Ubuntu/Debian

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Install the Apache Bench (ab) tool on Ubuntu or Debian-based Linux distributions using apt-get.

```bash
sudo apt-get install apache2-utils
```

--------------------------------

### ThrottleMachines Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/PLANETARY_INTEGRATION.md

Provides an example of configuring ThrottleMachines globally, including setting up a Redis storage backend with a connection pool and defining a default rate limiting algorithm.

```ruby
# config/initializers/throttle_machines.rb

# Configure your defensive systems
ThrottleMachines.configure do |config|
  # Quantum storage for distributed fleets
  redis_pool = ConnectionPool.new(size: 10) { Redis.new }
  config.storage = ThrottleMachines::Storage::Redis.new(pool: redis_pool)
  
  # Default to smooth traffic patterns
  config.default_algorithm = :gcra
end

```

--------------------------------

### Installation

Source: https://github.com/seuros/throttle_machines/blob/master/README.md

Instructions for adding ThrottleMachines to your project's Gemfile and installing dependencies.

```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

bundle install
```

--------------------------------

### Installation

Source: https://github.com/seuros/throttle_machines/blob/master/docs/MISSION_CONTROL.md

Installs the project dependencies, including the ThrottleMachines gem, using Bundler.

```bash
bundle install
```

--------------------------------

### Start Test Server

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Starts the test server, optionally clearing old logs. The server listens on port 3000 and monitors instrumentation logs.

```bash
# Start server with log monitoring
./start_server.sh

# Or start server and clear old logs
./start_server.sh --clear-logs
```

--------------------------------

### Running the Dummy App

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/README.md

Instructions to start the Rails server for the dummy application from the gem root directory.

```bash
cd test/dummy
bundle exec rails server
```

--------------------------------

### Install Apache Bench (ab) on macOS

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Install the Apache Bench (ab) tool on macOS using the Homebrew package manager. Apache Bench is used for load testing.

```bash
brew install httpd
```

--------------------------------

### ThrottleMachines Basic Usage Examples

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Provides examples of how to use ThrottleMachines for various rate limiting scenarios, including basic limiting, smooth API traffic, allowing bursts, and implementing circuit breakers.

```ruby
# Basic rate limiting
limiter = ThrottleMachines.limiter("basic", limit: 100, period: 60)

# Smooth API traffic (no thundering herds)
gcra = ThrottleMachines.limiter("api", limit: 1000, period: 60, algorithm: :gcra)

# Allow bursts
bucket = ThrottleMachines.limiter("burst", limit: 50, period: 50, algorithm: :token_bucket)

# Circuit breaker for external services
breaker = ThrottleMachines::Breaker.new("external", failure_threshold: 5, timeout: 300)
```

--------------------------------

### ThrottleMachines API Documentation

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Documentation for key ThrottleMachines functionalities used in the GeographicDefenseGrid.

```APIDOC
ThrottleMachines::RackMiddleware.throttle(name, options = {}, &block)
  Registers a new rate-limiting rule.
  Parameters:
    name: String - A unique name for the throttle rule.
    options: Hash - Configuration options for the throttle.
      limit: Integer or Proc - The maximum number of requests allowed.
      period: Integer or Proc - The time period in seconds for the limit.
      algorithm: Symbol - The rate-limiting algorithm to use (e.g., :gcra, :fixed_window, :token_bucket).
    block: Proc - A block that returns a unique key for the request, used for grouping.

ThrottleMachines::Breaker.new(key, options = {})
  Initializes a new circuit breaker.
  Parameters:
    key: String - A unique identifier for the circuit breaker.
    options: Hash - Configuration options.
      failure_threshold: Integer - The number of failures before opening the circuit.
      timeout: Integer - The duration in seconds the circuit stays open.
      storage: Object - An object for storing circuit breaker state (e.g., Redis).

ThrottleMachines.limiter(key, options = {})
  Retrieves or creates a rate limiter.
  Parameters:
    key: String - A unique identifier for the limiter.
    options: Hash - Configuration options.
      limit: Integer - The maximum number of requests allowed.
      period: Integer - The time period in seconds for the limit.

Example Usage:
  ThrottleMachines::RackMiddleware.throttle("my_throttle", limit: 100, period: 60, algorithm: :fixed_window) do |req|
    "user:#{req.env['HTTP_USER_ID']}"
  end

  breaker = ThrottleMachines::Breaker.new("service_a:circuit", failure_threshold: 5, timeout: 300)
  
  limiter = ThrottleMachines.limiter("api_calls:user123", limit: 10, period: 10)
  if limiter.allow?
    # Proceed with request
  else
    # Rate limit exceeded
  end
```

--------------------------------

### Production-Ready Setup with Advanced Throttle Machines Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/ADVANCED_FEATURES.md

Provides a comprehensive configuration example for production environments using Throttle Machines. It covers enabling async support, setting default algorithms, configuring global cascade protection for critical infrastructure, defining a service mesh with various breakers and limiters, and setting up hedged requests for external APIs.

```ruby
# config/initializers/throttle_machines_advanced.rb

# Configure async support
if defined?(Async)
  ThrottleMachines.configure do |config|
    config.default_algorithm = :gcra  # Best for async
    config.async_enabled = true
  end
end

# Global cascade protection for critical services
CRITICAL_SERVICES = ThrottleMachines::CascadingBreaker.new("critical_infra",
  failure_threshold: 10,
  timeout: 600,  # 10 minutes
  cascades_to: %w[api cache database search messaging]
)

# Service mesh configuration
SERVICE_MESH = ThrottleMachines::CircuitGroup.new("production") do
  # Database layer
  breaker :primary_db, failures: 5, timeout: 300
  breaker :read_replica, failures: 10, timeout: 60
  
  # Caching layer
  breaker :redis_cache, failures: 3, timeout: 30
  breaker :memcached, failures: 5, timeout: 30
  
  # API layer with dependencies
  limiter :public_api, limit: 10000, period: 60, 
    depends_on: [:primary_db, :redis_cache]
  limiter :admin_api, limit: 1000, period: 60,
    depends_on: [:primary_db]
end

# Hedged request configuration for external APIs
EXTERNAL_API_HEDGED = ThrottleMachines::HedgedRequest.new(
  delay: 0.1,      # 100ms between attempts
  max_attempts: 3,  # Try 3 different endpoints
  timeout: 2.0      # 2 second overall timeout
)
```

--------------------------------

### Troubleshoot Server Startup: Use Different Port

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Start the server on a different port if the default port is occupied. This is a common workaround for port conflicts.

```shell
PORT=3001 ./start_server.sh
```

--------------------------------

### Enable Instrumentation and Subscribe to Events

Source: https://github.com/seuros/throttle_machines/blob/master/docs/INSTRUMENTATION.md

Shows how to enable instrumentation and subscribe to all ThrottleMachines events using ActiveSupport::Notifications.

```ruby
ThrottleMachines.configure do |config|
  config.instrumentation_enabled = true
end

ActiveSupport::Notifications.subscribe(/throttle_machines/) do |name, start, finish, id, payload|
  Rails.logger.info "[#{name}] #{payload}"
end
```

--------------------------------

### Datacenter Routing and Circuit Breakers

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Logic for determining the nearest datacenter based on region and implementing regional circuit breakers.

```ruby
def self.nearest_datacenter(ip)
  region = detect_region_from_ip(ip)
  
  # Map regions to nearest datacenter
  case region
  when "NA" then "us-east-1"
  when "EU" then "eu-west-1"
  when "AS" then "ap-southeast-1"
  when "SA" then "sa-east-1"
  else "us-east-1"  # Default
  end
end

# Geographic circuit breakers
def self.regional_circuit_breaker(region)
  ThrottleMachines::Breaker.new(
    "region:#{region}:circuit",
    failure_threshold: 10,
    timeout: 600,  # 10 minute recovery
    storage: ThrottleMachines.configuration.storage
  )
end
```

--------------------------------

### ThrottleMachines Limiter Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Demonstrates the configuration of various limiters using the ThrottleMachines library. This includes setting limits, periods, and algorithms like fixed_window, gcra, and sliding_window.

```APIDOC
ThrottleMachines.limiter(key, limit:, period:, algorithm:)
  - Creates or retrieves a limiter instance.
  - Parameters:
    - key (String): A unique identifier for the limiter.
    - limit (Integer): The maximum number of allowed actions within the period.
    - period (Integer): The time window in seconds for the limit. 0 indicates a concurrent limit.
    - algorithm (Symbol): The throttling algorithm to use (:fixed_window, :gcra, :sliding_window).
  - Returns: A limiter object with an `allowed?` method.

Example Usage:

# Fixed Window Limiter (Concurrent Connections)
limiter = ThrottleMachines.limiter("ws:conn:#{user_id}", limit: 5, period: 0, algorithm: :fixed_window)

# GCRA Limiter (Message Rate)
limiter = ThrottleMachines.limiter("ws:msg:#{user_id}", limit: 100, period: 60, algorithm: :gcra)

# Sliding Window Limiter (Presence Updates)
limiter = ThrottleMachines.limiter("presence:#{user_id}", limit: 10, period: 60, algorithm: :sliding_window)

# Checking if an action is allowed
if limiter.allowed?
  # Perform action
else
  # Action denied due to rate limiting
end

# Getting retry information (for GCRA)
retry_after = limiter.retry_after
```

--------------------------------

### Troubleshoot Server Startup: Check Port Usage

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Check if a specific port (e.g., 3000) is already in use when the server fails to start. This helps identify port conflicts.

```bash
lsof -i :3000
```

--------------------------------

### Integration Test Example

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/README.md

An example of an integration test for the circuit breaker functionality, demonstrating normal operation, fallback behavior, circuit opening, manual resets, and health checks.

```bash
bundle exec rails test test/integration/circuit_breaker_test.rb
```

--------------------------------

### ThrottleMachines Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Configures various rate-limiting rules using ThrottleMachines::RackMiddleware. Includes regional limits, country compliance, data center routing, and GDPR compliance.

```ruby
class GeographicDefenseGrid
  REGIONS = {
    "NA" => { limit: 50_000, period: 300 },    # North America
    "EU" => { limit: 40_000, period: 300 },    # Europe (GDPR considerations)
    "AS" => { limit: 30_000, period: 300 },    # Asia
    "SA" => { limit: 10_000, period: 300 },    # South America
    "AF" => { limit: 5_000, period: 300 },     # Africa
    "OC" => { limit: 5_000, period: 300 },     # Oceania
    "AN" => { limit: 100, period: 300 }        # Antarctica (research stations only)
  }.freeze
  
  def self.configure!
    # Regional rate limiting
    ThrottleMachines::RackMiddleware.throttle("regional_limits",
      limit: ->(req) { region_limit(req) },
      period: ->(req) { REGIONS[detect_region(req)][:period] },
      algorithm: :gcra
    ) do |req|
      region = detect_region(req)
      "region:#{region}"
    end
    
    # Country-specific regulations
    ThrottleMachines::RackMiddleware.throttle("country_compliance",
      limit: ->(req) { country_limit(req) },
      period: 3600,
      algorithm: :fixed_window
    ) do |req|
      country = detect_country(req)
      restricted_countries.include?(country) ? "country:#{country}" : nil
    end
    
    # Data center proximity routing
    ThrottleMachines::RackMiddleware.throttle("datacenter_routing",
      limit: 1000,
      period: 60,
      algorithm: :token_bucket
    ) do |req|
      datacenter = nearest_datacenter(req.ip)
      "dc:#{datacenter}:#{req.ip}"
    end
    
    # GDPR-compliant limiting for EU
    ThrottleMachines::RackMiddleware.throttle("gdpr_compliance",
      limit: 100,
      period: 86400,  # Daily limit for data exports
      algorithm: :fixed_window
    ) do |req|
      if detect_region(req) == "EU" && req.path =~ /\/(export|download)/ 
        "gdpr:#{req.ip}"
      end
    end
  end
  
  # ... other methods ...
end
```

--------------------------------

### ThrottleMachines Rack Middleware Integration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Shows how to integrate ThrottleMachines as Rack middleware for comprehensive request throttling, including blocklisting and safelisting capabilities based on request attributes.

```ruby
# Rack middleware - complete defense
ThrottleMachines::RackMiddleware.throttle("defense", limit: 1000, period: 300) { |r| r.ip }
ThrottleMachines::RackMiddleware.blocklist("bad_actors") { |r| BadIP.exists?(r.ip) }
ThrottleMachines::RackMiddleware.safelist("good_guys") { |r| r.ip == "127.0.0.1" }
```

--------------------------------

### AIController Request Handling

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Handles incoming AI requests, instantiates the AIThrottleSystem, processes the request, and returns the result or an error.

```ruby
class AIController < ApplicationController
  before_action :authenticate_user!
  
  def generate
    ai_system = AIThrottleSystem.new(current_user)
    result = ai_system.process_request(params[:prompt])
    
    if result[:error]
      render json: result, status: 429
    else
      render json: result
    end
  end
end
```

--------------------------------

### Token Bucket Freighter Algorithm

Source: https://github.com/seuros/throttle_machines/blob/master/docs/MISSION_CONTROL.md

Example of creating a rate limiter using the `:token_bucket` algorithm. This algorithm allows for bursts of activity by refilling tokens over time.

```ruby
# Like a cargo ship that refills its holds gradually
freighter = ThrottleMachines.limiter("supply_freighter",
  limit: 50,
  period: 60,
  algorithm: :token_bucket
)
```

--------------------------------

### Testing ThrottleMachines Events

Source: https://github.com/seuros/throttle_machines/blob/master/docs/INSTRUMENTATION.md

Demonstrates how to test ThrottleMachines instrumentation using Minitest. It subscribes to events, records them, and asserts the expected event names and payloads during throttling scenarios.

```ruby
# In your tests
class InstrumentationTest < Minitest::Test
  def setup
    @events = []
    @subscriber = ActiveSupport::Notifications.subscribe(/throttle_machines/) do |name, _, _, _, payload|
      @events << { name: name, payload: payload }
    end
  end
  
  def teardown
    ActiveSupport::Notifications.unsubscribe(@subscriber)
  end
  
  def test_rate_limit_events
    limiter = ThrottleMachines.limiter("test", limit: 1, period: 60)
    
    limiter.throttle! { "first" }
    assert_equal "rate_limit.allowed.throttle_machines", @events.last[:name]
    
    assert_raises(ThrottleMachines::ThrottledError) do
      limiter.throttle! { "second" }
    end
    assert_equal "rate_limit.throttled.throttle_machines", @events.last[:name]
  end
end
```

--------------------------------

### Rails Application Monitoring

Source: https://github.com/seuros/throttle_machines/blob/master/docs/INSTRUMENTATION.md

Example of integrating ThrottleMachines events into a Rails application for logging and metrics tracking.

```ruby
# config/initializers/throttle_machines_instrumentation.rb

# Log important events
ActiveSupport::Notifications.subscribe("rate_limit.throttled.throttle_machines") do |*, payload|
  Rails.logger.warn "Rate limit hit: #{payload[:key]} - retry after #{payload[:retry_after]}s"
  
  # Track in your metrics system
  StatsD.increment("rate_limits.exceeded", tags: ["key:#{payload[:key]}"])
end

ActiveSupport::Notifications.subscribe("circuit_breaker.opened.throttle_machines") do |*, payload|
  Rails.logger.error "Circuit opened: #{payload[:key]} after #{payload[:failure_count]} failures"
  
  # Send alert
  AlertManager.notify(
    severity: :critical,
    message: "Circuit breaker opened for #{payload[:key]}",
    details: payload
  )
end

# Track performance metrics
ActiveSupport::Notifications.subscribe("rate_limit.checked.throttle_machines") do |name, start, finish, id, payload|
  duration = (finish - start) * 1000
  
  StatsD.timing("rate_limit.check_duration", duration, 
    tags: ["algorithm:#{payload[:algorithm]}", "allowed:#{payload[:allowed]}"]
  )
end
```

--------------------------------

### Custom Logging with JSON Output

Source: https://github.com/seuros/throttle_machines/blob/master/docs/INSTRUMENTATION.md

Example of a custom logger class that subscribes to ThrottleMachines events and logs them as JSON.

```ruby
class ThrottleLogger
  def self.setup
    ActiveSupport::Notifications.subscribe(/throttle_machines/) do |name, start, finish, id, payload|
      event_type = name.split('.').first(2).join('.')
      
      log_entry = {
        timestamp: Time.now.iso8601,
        event: event_type,
        duration_ms: ((finish - start) * 1000).round(2),
        payload: payload
      }
      
      # Log as JSON for structured logging
      Rails.logger.info log_entry.to_json
    end
  end
end

ThrottleLogger.setup
```

--------------------------------

### Modify Rate Limits Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Modify the rate limiting rules by editing the `config/initializers/throttle_machines.rb` file. This example shows how to set a custom rate limit for a specific endpoint.

```ruby
when '/your/endpoint'
  {
    key: "custom:#{req.ip}",
    limit: 15,
    period: 60,
    algorithm: :token_bucket
  }
```

--------------------------------

### Configure WebSocket Limits

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Sets up global throttling limits for WebSocket connections, messages, and subscriptions using ThrottleMachines. Defines connection limits per user, message rates, and subscription caps.

```ruby
class RealtimeThrottleSystem
  def self.configure_websocket_limits
    # Connection limits per user
    @connection_limiter = ThrottleMachines.limiter(
      "websocket:connections",
      limit: 5,  # Max 5 concurrent connections per user
      period: 0, # Concurrent limit, not time-based
      algorithm: :fixed_window
    )
    
    # Message rate limiting
    @message_limiter = ThrottleMachines.limiter(
      "websocket:messages",
      limit: 100,
      period: 60,  # 100 messages per minute
      algorithm: :gcra  # Smooth message flow
    )
    
    # Subscription limits
    @subscription_limiter = ThrottleMachines.limiter(
      "websocket:subscriptions",
      limit: 50,  # Max 50 channel subscriptions
      period: 0,  # Concurrent limit
      algorithm: :fixed_window
    )
  end
end
```

--------------------------------

### Token Bucket Freighter Example

Source: https://github.com/seuros/throttle_machines/blob/master/docs/SPACECRAFT_MANUAL.md

Demonstrates the Token Bucket algorithm for rate limiting, highlighting its ability to handle bursts. It shows how tokens are regenerated over time and consumed by requests.

```ruby
# A freighter that regenerates 1 token per second, max 50 tokens
freighter = ThrottleMachines.limiter("cargo_freighter",
  limit: 50,     # Maximum tokens in bucket
  period: 50,    # Refill rate: 50 tokens per 50 seconds = 1 token/second
  algorithm: :token_bucket
)

# Burst usage - use many tokens at once
10.times { freighter.allowed? } # All succeed if bucket was full

# Steady usage - tokens regenerate continuously
sleep 5
5.times { freighter.allowed? } # 5 new tokens available
```

--------------------------------

### API Gateway Defense System Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Configures multiple layers of rate limiting for an API gateway using ThrottleMachines::RackMiddleware. It includes global, per-IP, authenticated user, expensive endpoint, and GraphQL complexity limiting.

```ruby
class APIDefenseSystem
  def self.initialize!
    # Layer 1: Global rate limiting (the outer shield)
    ThrottleMachines::RackMiddleware.throttle("global_shield",
      limit: 10_000,
      period: 300,  # 10k requests per 5 minutes globally
      algorithm: :gcra  # Smooth distribution, no thundering herds
    ) do |req|
      "global"  # Single global key
    end
    
    # Layer 2: Per-IP rate limiting (individual ship tracking)
    ThrottleMachines::RackMiddleware.throttle("ip_tracker",
      limit: 1000,
      period: 300,  # 1k requests per 5 minutes per IP
      algorithm: :sliding_window  # Precise tracking for security
    ) do |req|
      req.ip
    end
    
    # Layer 3: Authenticated user limits (crew member privileges)
    ThrottleMachines::RackMiddleware.throttle("authenticated_crew",
      limit: 5000,
      period: 3600,  # 5k requests per hour for logged-in users
      algorithm: :token_bucket  # Allow bursts for power users
    ) do |req|
      # Extract user ID from JWT token
      token = req.env["HTTP_AUTHORIZATION"]&.split(" ")&.last
      user_id = decode_jwt(token)["user_id"] rescue nil
      user_id ? "user:#{user_id}" : nil
    end
    
    # Layer 4: Expensive endpoint protection (warp core safety)
    ThrottleMachines::RackMiddleware.throttle("expensive_operations",
      limit: 10,
      period: 60,  # Only 10 expensive operations per minute
      algorithm: :fixed_window
    ) do |req|
      if req.path =~ /\/(export|report|analyze)/ 
        req.ip  # Track by IP for expensive operations
      end
    end
    
    # Special Forces: GraphQL complexity limiting
    ThrottleMachines::RackMiddleware.throttle("graphql_complexity",
      limit: 1000,
      period: 60,  # 1000 complexity points per minute
      algorithm: :gcra
    ) do |req|
      if req.path == "/graphql" && req.post?
        # Calculate query complexity
        complexity = calculate_graphql_complexity(req.body)
        if complexity > 0
          "graphql:#{req.ip}:#{complexity}"  # Include complexity in key
        end
      end
    end
  end
  
  private
  
  def self.decode_jwt(token)
    # Your JWT decoding logic
    JWT.decode(token, Rails.application.secret_key_base)[0]
  end
  
  def self.calculate_graphql_complexity(body)
    # Parse GraphQL query and calculate complexity
    # This is a simplified example
    query = JSON.parse(body)["query"] rescue ""
    
    # Count fields and nested queries
    complexity = 0
    complexity += query.scan(/\{/).count * 10  # Each level adds complexity
    complexity += query.scan(/\w+\s*\{/).count * 5  # Each field selection
    complexity += query.scan(/\(.*?\)/).count * 20  # Arguments are expensive
    
    complexity
  end
end

# Initialize on application start
APIDefenseSystem.initialize!
```

--------------------------------

### Fixed Window Shuttle Example

Source: https://github.com/seuros/throttle_machines/blob/master/docs/SPACECRAFT_MANUAL.md

Demonstrates the usage of the Fixed Window algorithm for rate limiting. It shows how requests are allowed until the limit is reached within a period, and how the count resets at the period's boundary.

```ruby
shuttle = ThrottleMachines.limiter("hourly_shuttle",
  limit: 100,
  period: 3600,  # 1 hour in seconds
  algorithm: :fixed_window
)

# At 13:45 - 99 requests used
shuttle.allowed? # => true (last spot!)

# At 13:59:59 - 100 requests used  
shuttle.allowed? # => false

# At 14:00:00 - Window resets!
shuttle.allowed? # => true (fresh start)
```

--------------------------------

### Run Apache Bench Tests

Source: https://github.com/seuros/throttle_machines/blob/master/test/dummy/RATE_LIMITING_TEST_SETUP.md

Executes Apache Bench load tests for rate limiting scenarios. Supports clearing logs before testing and displaying help information.

```bash
# Run comprehensive rate limiting tests
./test_rate_limiting_ab.sh

# Clear logs before testing
./test_rate_limiting_ab.sh --clear-logs

# Show help
./test_rate_limiting_ab.sh --help
```

--------------------------------

### ThrottleMachines Dynamic Limits Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Illustrates how to configure dynamic rate limits that can change based on request attributes or external data sources, such as API keys or user-specific rate limits.

```ruby
# Dynamic limits
ThrottleMachines::RackMiddleware.throttle("dynamic",
  limit: ->(req) { User.find_by(api_key: req.headers["X-API-Key"])&.rate_limit || 100 },
  period: 3600
) { |req| req.headers["X-API-Key"] }
```

--------------------------------

### Regional Health Monitoring

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Monitors the health of regional rate limiters and circuit breakers, providing usage statistics.

```ruby
def self.regional_health
  REGIONS.keys.map do |region|
    breaker = regional_circuit_breaker(region)
    limiter = ThrottleMachines.limiter("region:#{region}", 
      limit: REGIONS[region][:limit], 
      period: REGIONS[region][:period]
    )
    
    {
      region: region,
      circuit_status: breaker.state,
      current_usage: limiter.current_count,
      usage_percentage: (limiter.current_count.to_f / REGIONS[region][:limit] * 100).round(2),
      healthy: breaker.state == :closed && limiter.current_count < REGIONS[region][:limit] * 0.8
    }
  end
end
```

--------------------------------

### Disable Instrumentation

Source: https://github.com/seuros/throttle_machines/blob/master/docs/INSTRUMENTATION.md

Configures ThrottleMachines to disable all instrumentation. This is useful for performance-critical paths where the overhead of instrumentation needs to be eliminated.

```ruby
# Disable all instrumentation (for performance-critical paths)
ThrottleMachines.configure do |config|
  config.instrumentation_enabled = false
end
```

--------------------------------

### ActionCable Connection Throttling

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Handles Action Cable connection logic, including user verification, connection limit checks, and tracking. It uses a per-user fixed window limiter for concurrent connections.

```ruby
class RealtimeThrottleSystem::ApplicationCable::Connection < ActionCable::Connection::Base
  identified_by :current_user
  
  def connect
    self.current_user = find_verified_user
    
    # Check connection limit
    if connection_allowed?
      track_connection
      logger.add_tags 'ActionCable', current_user.id
    else
      reject_over_limit
    end
  end
  
  def disconnect
    release_connection
  end
  
  private
  
  def find_verified_user
    if verified_user = User.find_by(id: cookies.signed[:user_id])
      verified_user
    else
      reject_unauthorized_connection
    end
  end
  
  def connection_allowed?
    limiter = ThrottleMachines.limiter(
      "ws:conn:#{current_user.id}",
      limit: connection_limit_for_user,
      period: 0,
      algorithm: :fixed_window
    )
    
    limiter.allowed?
  end
  
  def connection_limit_for_user
    case current_user.subscription_tier
    when "enterprise" then 20
    when "pro" then 10
    when "basic" then 5
    else 2
    end
  end
  
  def track_connection
    Redis.current.sadd("connections:#{current_user.id}", connection_identifier)
    Redis.current.expire("connections:#{current_user.id}", 1.hour)
  end
  
  def release_connection
    Redis.current.srem("connections:#{current_user.id}", connection_identifier)
  end
  
  def reject_over_limit
    logger.warn "Connection limit exceeded for user #{current_user.id}"
    reject_unauthorized_connection
  end
end
```

--------------------------------

### Combined Rate Limiting Strategies

Source: https://github.com/seuros/throttle_machines/blob/master/docs/SPACECRAFT_MANUAL.md

Demonstrates how to layer multiple rate limiting algorithms for comprehensive protection. This example combines fixed window for daily quotas, token bucket for burst control, and GCRA for smooth traffic.

```ruby
class HybridDefenseSystem
  def initialize
    # Layer different algorithms for comprehensive protection
    @quotas = ThrottleMachines.limiter("daily_quota", 
      limit: 10000, period: 86400, algorithm: :fixed_window)
    
    @burst_control = ThrottleMachines.limiter("burst_control",
      limit: 100, period: 10, algorithm: :token_bucket)
    
    @smooth_traffic = ThrottleMachines.limiter("smooth_traffic",
      limit: 60, period: 60, algorithm: :gcra)
  end
  
  def process_request
    # Must pass all checks
    return quota_exceeded unless @quotas.allowed?
    return burst_limit_hit unless @burst_control.allowed?
    return traffic_limit unless @smooth_traffic.allowed?
    
    handle_request
  end
end
```

--------------------------------

### GeoIP Detection Methods

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Methods for detecting geographic region and country from an IP address using MaxMind GeoIP2 database.

```ruby
def self.detect_region(request)
  # Use GeoIP database
  @geoip ||= MaxMind::GeoIP2::Reader.new('GeoLite2-City.mmdb')
  
  begin
    result = @geoip.city(request.ip)
    result.continent.code
  rescue => e
    Rails.logger.warn "GeoIP lookup failed: #{e.message}"
    "NA"  # Default to North America
  end
end

def self.detect_country(request)
  @geoip ||= MaxMind::GeoIP2::Reader.new('GeoLite2-City.mmdb')
  
  begin
    result = @geoip.city(request.ip)
    result.country.iso_code
  rescue
    "US"  # Default
  end
end
```

--------------------------------

### Rate Limiter Events

Source: https://github.com/seuros/throttle_machines/blob/master/docs/INSTRUMENTATION.md

Details the events emitted by the rate limiter, including 'checked', 'allowed', and 'throttled', along with their payloads.

```ruby
# rate_limit.checked.throttle_machines
# Payload:
# {
#   key: "api:user:123",
#   limit: 100,
#   period: 60,
#   algorithm: :gcra,
#   allowed: true,
#   remaining: 95
# }

# rate_limit.allowed.throttle_machines
# Payload:
# {
#   key: "api:user:123",
#   limit: 100,
#   period: 60,
#   algorithm: :gcra,
#   remaining: 94
# }

# rate_limit.throttled.throttle_machines
# Payload:
# {
#   key: "api:user:123",
#   limit: 100,
#   period: 60,
#   algorithm: :gcra,
#   retry_after: 45.2  # seconds until next allowed request
# }
```

--------------------------------

### Multi-Tenant Throttling Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Configures dynamic per-tenant rate limiting using ThrottleMachines. It sets up different throttling strategies including tenant quotas, noisy neighbor protection, and API endpoint-specific limits, all tailored to individual tenants.

```ruby
class MultiTenantThrottle
  def self.configure!
    # Dynamic per-tenant limiting
    ThrottleMachines::RackMiddleware.throttle("tenant_quota",
      limit: ->(req) { tenant_limit(req) },
      period: ->(req) { tenant_period(req) },
      algorithm: :gcra
    ) do |req|
      tenant_id = extract_tenant(req)
      tenant_id ? "tenant:#{tenant_id}" : nil
    end
    
    # Prevent noisy neighbors
    ThrottleMachines::RackMiddleware.throttle("noisy_neighbor_protection",
      limit: 10_000,
      period: 300,  # No single tenant can use more than 10k in 5 min
      algorithm: :sliding_window
    ) do |req|
      tenant_id = extract_tenant(req)
      tenant_id ? "tenant:burst:#{tenant_id}" : nil
    end
    
    # API endpoint specific limits per tenant
    ThrottleMachines::RackMiddleware.throttle("endpoint_limits",
      limit: ->(req) { endpoint_limit(req) },
      period: 60,
      algorithm: :token_bucket
    ) do |req|
      tenant_id = extract_tenant(req)
      endpoint = req.path.split("/")[2]  # /api/v1/[endpoint]
      tenant_id && endpoint ? "#{tenant_id}:#{endpoint}" : nil
    end
  end
  
  def self.tenant_limit(request)
    tenant = find_tenant(request)
    return 100 unless tenant  # Default for unknown tenants
    
    # Limits based on subscription plan
    case tenant.plan
    when "enterprise"
      100_000  # 100k requests per period
    when "business"
      10_000   # 10k requests per period
    when "startup"
      1_000    # 1k requests per period
    when "trial"
      100      # 100 requests per period
    else
      10       # Minimal for expired/suspended
    end
  end
  
  def self.tenant_period(request)
    tenant = find_tenant(request)
    return 3600 unless tenant  # Default 1 hour
    
    # Different reset periods by plan
    case tenant.plan
    when "enterprise"
      300    # 5 minutes (more granular)
    when "business"
      900    # 15 minutes
    when "startup"
      3600   # 1 hour
    when "trial"
      86400  # 24 hours
    else
      86400  # 24 hours for restricted
    end
  end
  
  def self.endpoint_limit(request)
    tenant = find_tenant(request)
    endpoint = request.path.split("/")[2]
    
    return 10 unless tenant && endpoint
    
    # Different limits for different endpoints
    base_limit = case endpoint
    when "search"
      100  # Search is expensive
    when "export"
      10   # Exports are very expensive
    when "webhook"
      1000 # Webhooks can be frequent
    else
      500  # Default endpoint limit
    end
    
    # Adjust by plan
    multiplier = case tenant.plan
    when "enterprise" then 10
    when "business" then 5
    when "startup" then 2
    else 1
    end
    
    base_limit * multiplier
  end
  
  def self.extract_tenant(request)
    # Try multiple methods to identify tenant
    
    # Method 1: Subdomain (acme.example.com)
    subdomain = request.host.split('.').first
    return subdomain unless subdomain == 'www' || subdomain == 'api'
    
    # Method 2: Header (X-Tenant-ID)
    return request.env["HTTP_X_TENANT_ID"] if request.env["HTTP_X_TENANT_ID"]
    
    # Method 3: JWT claim
    if auth_header = request.env["HTTP_AUTHORIZATION"]
      token = auth_header.split(' ').last
      claims = JWT.decode(token, Rails.application.secret_key_base)[0] rescue {}
      return claims["tenant_id"] if claims["tenant_id"]
    end
    
    # Method 4: API key lookup
    if api_key = request.params["api_key"] || request.env["HTTP_X_API_KEY"]
      tenant = Tenant.joins(:api_keys).where(api_keys: { key: api_key }).first
      return tenant.id if tenant
    end
    
    nil
  end
  
  def self.find_tenant(request)
    tenant_id = extract_tenant(request)
    return nil unless tenant_id
    
    # Cache tenant lookups
    Rails.cache.fetch("tenant:#{tenant_id}", expires_in: 5.minutes) do
      Tenant.find_by(id: tenant_id) || Tenant.find_by(subdomain: tenant_id)
    end
  end
end
```

--------------------------------

### Advanced Feature Events

Source: https://github.com/seuros/throttle_machines/blob/master/docs/INSTRUMENTATION.md

Details events for advanced features like cascade failures and hedged requests, including their payloads.

```ruby
# cascade.triggered.throttle_machines
# Payload:
# {
#   primary_key: "database",
#   cascaded_key: "user_service"
# }

# hedged_request.started.throttle_machines
# Payload:
# {
#   request_id: "70123456789-1234567890.123",
#   max_attempts: 3
# }

# hedged_request.winner.throttle_machines
# Payload:
# {
#   request_id: "70123456789-1234567890.123",
#   winning_attempt: 1,
#   duration: 0.127  # seconds
# }
```

--------------------------------

### Rails Integration for TransmissionsController

Source: https://github.com/seuros/throttle_machines/blob/master/docs/THE_AMAZONIAN_PROTOCOLS.md

Example of integrating the WordBasedLimiter into a Rails application's controller for handling transmissions and applying rate limits.

```ruby
# Example Rails integration (if using Rails)
class TransmissionsController < ApplicationController
  before_action :initialize_limiter

  def create
    result = @limiter.transmit(params[:message])

    if result[:status] == :throttled
      render json: result, status: 429
    else
      # Process transmission
      render json: result
    end
  end

  private

  def initialize_limiter
    @limiter = WordBasedLimiter.new(current_user.id, current_user.tier)
  end
end
```

--------------------------------

### Rate Limiting and Circuit Breaker Configuration

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

Demonstrates the configuration of a token bucket rate limiter for broadcasts and a circuit breaker for WebSocket infrastructure. It also includes methods for health monitoring, such as connection counts, message rates, and infrastructure checks.

```ruby
class ThrottleMachines::Manager
  # ... (previous code)

  def self.broadcast_limiter(channel)
    @broadcast_limiters ||= {}
    @broadcast_limiters[channel] ||= ThrottleMachines.limiter("broadcast:#{channel}",
      limit: 5,
      period: 10,  # Max 5 broadcasts per 10 seconds per channel
      algorithm: :token_bucket
    )
  end
  
  # ... (broadcast logic)

  # Circuit breaker for WebSocket infrastructure
  def self.websocket_circuit_breaker
    @ws_breaker ||= ThrottleMachines::Breaker.new(
      "websocket_infrastructure",
      failure_threshold: 10,
      timeout: 300,
      storage: ThrottleMachines.configuration.storage
    )
  end
  
  # Health monitoring
  def self.connection_health
    {
      total_connections: Redis.current.keys("connections:*").count,
      connections_by_tier: connection_breakdown,
      message_rate: calculate_message_rate,
      circuit_status: websocket_circuit_breaker.state,
      infrastructure_healthy: infrastructure_check
    }
  end
  
  private
  
  def self.connection_breakdown
    User.group(:subscription_tier).count.map do |tier, count|
      active = Redis.current.keys("connections:*").count { |k|
        user_id = k.split(":").last
        User.find(user_id).subscription_tier == tier rescue false
      }
      
      { tier: tier, total_users: count, active_connections: active }
    end
  end
  
  def self.calculate_message_rate
    # Get message counts from last minute
    keys = Redis.current.keys("throttle:ws:msg:*")
    total = keys.sum { |k| Redis.current.get(k).to_i }
    
    total.to_f / 60  # Messages per second
  end
  
  def self.infrastructure_check
    begin
      # Test ActionCable Redis connection
      ActionCable.server.pubsub.redis.ping
      true
    rescue
      false
    end
  end
end
```

--------------------------------

### GCRA Algorithm

Source: https://github.com/seuros/throttle_machines/blob/master/README.md

Example of using the Generic Cell Rate Algorithm (GCRA) for smoother rate limiting, preventing sudden drops in throughput.

```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!
```

--------------------------------

### ThrottleMachines::RackMiddleware

Source: https://github.com/seuros/throttle_machines/blob/master/docs/COMMAND_EXAMPLES.md

The core Rack middleware for ThrottleMachines, allowing integration into Rack-based web applications like Rails. It enables defining various rate-limiting strategies based on request attributes.

```APIDOC
ThrottleMachines::RackMiddleware.throttle(name, options = {}, &block)
  - Registers a new rate-limiting rule.
  - Parameters:
    - name: String - A unique identifier for the rate-limiting rule.
    - options: Hash - Configuration options for the rule:
      - limit: Integer - The maximum number of requests allowed within the period.
      - period: Integer - The time period in seconds for the limit.
      - algorithm: Symbol - The rate-limiting algorithm to use (e.g., :gcra, :sliding_window, :token_bucket, :fixed_window).
    - block: Proc - A block that takes the Rack request object and returns a key to rate limit by. If the block returns nil, the request is not rate-limited by this rule.
  - Example:
    ThrottleMachines::RackMiddleware.throttle("ip_tracker",
      limit: 1000,
      period: 300,
      algorithm: :sliding_window
    ) do |req|
      req.ip
    end

Algorithms:
  - :gcra (Generic Cell Rate Algorithm): Provides smooth request distribution, preventing thundering herds.
  - :sliding_window: Tracks requests within a sliding time window for precise rate limiting.
  - :token_bucket: Allows for bursts of requests, suitable for users with higher allowances.
  - :fixed_window: A simple windowed approach, potentially leading to bursts at window edges.
```