Configuration

RateThrottle can be configured through code, YAML files, or environment variables.

Configuration Methods

  1. Programmatic - Define rules and settings in code

  2. YAML Files - Load configuration from YAML

  3. Environment Variables - Override settings via environment

Programmatic Configuration

Basic Setup

from ratethrottle import RateThrottleCore, RateThrottleRule

limiter = RateThrottleCore()

# Add rules
limiter.add_rule(RateThrottleRule(
    name="api_public",
    limit=100,
    window=60,
    strategy="token_bucket"
))

limiter.add_rule(RateThrottleRule(
    name="api_auth",
    limit=1000,
    window=60,
    strategy="sliding_window",
    scope="user"
))

With Storage

from ratethrottle import create_limiter

limiter = create_limiter(
    storage='redis',
    redis_url='redis://localhost:6379/0',
    max_connections=50
)

YAML Configuration

Configuration File Format

# config.yaml
storage:
  type: redis
  url: redis://localhost:6379/0
  options:
    max_connections: 50
    socket_timeout: 5
    retry_on_timeout: true

rules:
  - name: api_public
    limit: 100
    window: 60
    scope: ip
    strategy: token_bucket
    burst: 120
    block_duration: 300

  - name: api_authenticated
    limit: 1000
    window: 60
    scope: user
    strategy: sliding_window
    block_duration: 600

  - name: api_expensive
    limit: 10
    window: 60
    scope: endpoint
    strategy: leaky_bucket
    block_duration: 900

ddos:
  enabled: true
  threshold: 10000
  window: 60
  auto_block: true
  block_duration: 3600

Loading Configuration

from ratethrottle import ConfigManager, create_limiter

# Load from file
config = ConfigManager('config.yaml')

# Create limiter
limiter = create_limiter()

# Access config values
rules = config.get_rules()
ddos_config = config.get('ddos')

Environment Variables

Override settings with environment variables:

export RATETHROTTLE_STORAGE_TYPE=redis
export RATETHROTTLE_REDIS_URL=redis://localhost:6379/0
export RATETHROTTLE_DEFAULT_LIMIT=100
export RATETHROTTLE_DEFAULT_WINDOW=60

Usage:

import os
from ratethrottle import create_limiter

limiter = create_limiter(
    storage=os.getenv('RATETHROTTLE_STORAGE_TYPE', 'memory'),
    redis_url=os.getenv('RATETHROTTLE_REDIS_URL')
)

Configuration Options

Rule Configuration

RateThrottleRule(
    name="rule_name",          # Required: Unique identifier
    limit=100,                 # Required: Max requests
    window=60,                 # Required: Time window (seconds)
    scope="ip",                # Optional: ip, user, endpoint, global
    strategy="token_bucket",   # Optional: Strategy algorithm
    burst=120,                 # Optional: Burst capacity
    block_duration=300         # Optional: Block time (seconds)
)

Storage Configuration

In-Memory:

from ratethrottle import InMemoryStorage

storage = InMemoryStorage()

Redis:

import redis
from ratethrottle import RedisStorage

client = redis.from_url(
    'redis://localhost:6379/0',
    max_connections=50,
    socket_timeout=5,
    retry_on_timeout=True
)
storage = RedisStorage(client)

DDoS Configuration

from ratethrottle import DDoSProtection

ddos = DDoSProtection({
    'enabled': True,
    'threshold': 10000,              # requests per window
    'window': 60,                    # seconds
    'auto_block': True,
    'block_duration': 3600,          # 1 hour
    'suspicious_threshold': 0.5,     # 0.0 to 1.0
    'max_unique_endpoints': 50,
    'burst_threshold': 100,
    'burst_window': 10
})

Analytics Configuration

from ratethrottle import RateThrottleAnalytics

analytics = RateThrottleAnalytics(
    max_history=10000,
    enable_metadata=True,
    sanitize_data=True
)

Best Practices

  1. Use YAML for Production - Easier to update without code changes - Can be version controlled separately - Supports environment-specific configs

  2. Separate Configs by Environment

config/
├── development.yaml
├── staging.yaml
└── production.yaml

  1. Use Environment Variables for Secrets

storage:
    type: redis
    url: ${REDIS_URL}  # From environment

  1. Document Your Rules

rules:
    # Public API: Conservative limit for unauthenticated users
    - name: api_public
    limit: 100
    window: 60

  1. Version Your Config Files - Track changes in git - Use descriptive commit messages - Review before deploying

Example Complete Configuration

# production.yaml
storage:
  type: redis
  url: redis://prod-redis:6379/0
  options:
    max_connections: 100
    socket_timeout: 5
    socket_connect_timeout: 5
    retry_on_timeout: true
    health_check_interval: 30

rules:
  # Public endpoints
  - name: public_api
    limit: 100
    window: 60
    scope: ip
    strategy: sliding_counter
    burst: 120
    block_duration: 300

  # Authenticated users
  - name: authenticated_api
    limit: 1000
    window: 60
    scope: user
    strategy: sliding_window
    block_duration: 600

  # Search endpoints
  - name: search
    limit: 50
    window: 60
    scope: ip
    strategy: token_bucket
    burst: 60
    block_duration: 300

  # Write operations
  - name: write_api
    limit: 20
    window: 60
    scope: user
    strategy: leaky_bucket
    block_duration: 900

  # File uploads
  - name: upload
    limit: 5
    window: 300
    scope: user
    strategy: fixed_window
    block_duration: 1800

ddos:
  enabled: true
  threshold: 50000
  window: 60
  auto_block: true
  block_duration: 7200
  suspicious_threshold: 0.6
  max_unique_endpoints: 100
  burst_threshold: 500
  burst_window: 10

Loading This Configuration:

from ratethrottle import ConfigManager, create_limiter

config = ConfigManager('production.yaml')
limiter = create_limiter()

rules = config.get_rules()

for rule in rules:
    limiter.add_rule(rule)

Next Steps