RateLimitPlugin Schema

Schema definition for the Rate Limit Plugin, which provides token bucket-based rate limiting to prevent abuse and ensure fair resource usage.

Schema Information

Properties

Usage Examples

Basic IP-based Rate Limiting

<tr itemscope itemtype="https://rustybeam.net/schema/RateLimitPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_rate_limit.so</span>
    <span itemprop="requests_per_second">5</span>
    <span itemprop="burst_capacity">15</span>
</tr>

Strict API Rate Limiting

<tr itemscope itemtype="https://rustybeam.net/schema/RateLimitPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_rate_limit.so</span>
    <span itemprop="requests_per_second">2</span>
    <span itemprop="burst_capacity">5</span>
    <span itemprop="key_strategy">ip</span>
    <span itemprop="cleanup_interval">600</span>
    <span itemprop="name">api_rate_limit</span>
</tr>

User-based Rate Limiting

<tr itemscope itemtype="https://rustybeam.net/schema/RateLimitPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_rate_limit.so</span>
    <span itemprop="requests_per_second">10</span>
    <span itemprop="burst_capacity">25</span>
    <span itemprop="key_strategy">user</span>
</tr>

Global Server-wide Limiting

<tr itemscope itemtype="https://rustybeam.net/schema/RateLimitPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_rate_limit.so</span>
    <span itemprop="requests_per_second">100</span>
    <span itemprop="burst_capacity">200</span>
    <span itemprop="key_strategy">global</span>
    <span itemprop="name">server_limit</span>
</tr>

Slow Rate Limiting (Less than 1 req/sec)

<tr itemscope itemtype="https://rustybeam.net/schema/RateLimitPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_rate_limit.so</span>
    <span itemprop="requests_per_second">0.1</span>
    <span itemprop="burst_capacity">3</span>
    <span itemprop="name">strict_limit</span>
</tr>

Rate Limiting Strategies

Response Headers

The Rate Limit Plugin adds these headers to responses:

Rate Limited Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1657464955
Retry-After: 10
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 10
}

Schema Inheritance

This schema inherits from the UtilityPlugin schema, which provides:

• logfile - Log file path
• directory - Directory configuration
• enabled - Plugin enable/disable state

And ultimately from the base Plugin schema, which provides:

• library - Plugin library path
• plugin - Base plugin reference property

Configuration Recommendations

Common Rate Limiting Scenarios

Validation Rules

• requests_per_second must be a positive number (supports decimals)
• burst_capacity must be greater than or equal to requests_per_second
• key_strategy must be one of: "ip", "user", "global"
• cleanup_interval must be a positive integer (seconds)
• For "user" strategy, authentication must be configured before rate limiting
• The name property should be unique if multiple rate limit plugins are used

Memory Management

• Token Buckets: Stored in memory per client/user
• Cleanup Process: Automatically removes inactive entries
• Memory Usage: ~100 bytes per active client
• Scaling: Memory usage grows with concurrent clients
• Persistence: Limits reset on server restart

Client-Side Handling

Exponential Backoff

async function makeRequest(url) {
    let delay = 1000; // Start with 1 second
    
    for (let attempt = 0; attempt < 5; attempt++) {
        const response = await fetch(url);
        
        if (response.status === 429) {
            const retryAfter = response.headers.get('Retry-After');
            const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : delay;
            
            await new Promise(resolve => setTimeout(resolve, waitTime));
            delay *= 2; // Exponential backoff
            continue;
        }
        
        return response;
    }
    
    throw new Error('Rate limit exceeded after retries');
}

Rate Limit Headers Monitoring

function checkRateLimit(response) {
    const limit = response.headers.get('X-RateLimit-Limit');
    const remaining = response.headers.get('X-RateLimit-Remaining');
    const reset = response.headers.get('X-RateLimit-Reset');
    
    if (remaining && parseInt(remaining) < 5) {
        console.warn('Rate limit nearly exceeded:', {
            limit,
            remaining,
            resetTime: new Date(parseInt(reset) * 1000)
        });
    }
}

Integration with Other Plugins

• Authorization Plugin: Use "user" strategy for per-user limits after authentication
• Basic Auth Plugin: Authenticate users before applying user-based rate limits
• Health Check Plugin: Consider excluding health checks from rate limiting
• Access Log Plugin: Logs rate-limited requests for monitoring
• Directory Plugin: Apply different rate limits to different API versions/paths

Monitoring and Alerting

Metrics to Monitor

• Rate Limit Hits: Number of 429 responses
• Top Rate Limited IPs: Identify potential attackers
• Burst Usage: How often burst capacity is utilized
• Token Bucket States: Average remaining tokens
• Memory Usage: Number of active rate limit entries

Log Analysis

# Find rate limited requests
grep "429" access.log | head -10

# Top rate limited IPs
grep "429" access.log | awk '{print $1}' | sort | uniq -c | sort -nr

# Rate limit frequency by hour
grep "429" access.log | cut -d'[' -f2 | cut -d':' -f2 | sort | uniq -c

See Also

• UtilityPlugin Schema - Parent schema
• Rate Limit Plugin Documentation - Complete plugin documentation
• AuthorizationPlugin Schema - User-based rate limiting
• AccessLogPlugin Schema - Monitoring integration