Rate Limiting

Overview

Cloudillo implements a sophisticated rate limiting system to protect against abuse, DDoS attacks, and credential stuffing. The system uses the Generic Cell Rate Algorithm (GCRA) with hierarchical address grouping and dual-tier limits.

Algorithm: GCRA

The rate limiter uses GCRA (Generic Cell Rate Algorithm), also known as the “leaky bucket as a meter” algorithm. GCRA provides:

• Smooth rate limiting: Distributes requests evenly over time
• Burst tolerance: Allows short bursts within limits
• Memory efficiency: O(1) per key, no per-request storage
• Precision: Nanosecond-level timing accuracy

Hierarchical Address Levels

Requests are rate-limited at multiple network levels simultaneously. All levels must pass for a request to succeed.

IPv4 Levels

IPv6 Levels

Dual-Tier Limits

Each address level has two tiers of limits:

Both tiers must pass. This prevents:

• Burst attacks: Limited by short-term tier
• Slow-and-steady attacks: Limited by long-term tier

Endpoint Categories

Different endpoints have different rate limit profiles:

Auth Category

Strict limits for authentication endpoints to prevent credential stuffing.

Default limits (per individual IPv4):

• Short-term: 2 req/s, burst 5
• Long-term: 30 req/h, burst 30

Federation Category

Moderate limits for inter-instance communication.

Default limits (per individual IPv4):

• Short-term: 5 req/s, burst 15
• Long-term: 1000 req/h, burst 100

General Category

Relaxed limits for normal browsing and API usage.

Default limits (per individual IPv4):

• Short-term: 20 req/s, burst 50
• Long-term: 5000 req/h, burst 500

WebSocket Category

Moderate limits for WebSocket connections.

Default limits (per individual IPv4):

• Short-term: 10 req/s, burst 20
• Long-term: 200 req/h, burst 100

Default Rate Limits Table

Proof-of-Work Protection

CONN (connection request) actions require proof-of-work when suspicious behavior is detected from an IP address.

How It Works

1. Violation detected: Failed signature, duplicate pending, or rejected CONN increments counter
2. Counter determines requirement: Token must end with N ‘A’ characters (where N = counter)
3. Two-level tracking: Both individual IP and network range are tracked
4. Automatic decay: Counter decreases by 1 every hour without new violations

Violation Types

PoW Requirement

The PoW requirement is a simple suffix check on the action token:

Counter = 0: No requirement
Counter = 1: Token must end with "A"
Counter = 2: Token must end with "AA"
Counter = 3: Token must end with "AAA"
...
Counter = 10: Token must end with "AAAAAAAAAA"

When PoW is required, the server responds with HTTP 428 (Precondition Required) and the required suffix.

Verification Flow

CONN action received at /api/inbox
    ↓
Check PoW requirement for source IP
    ↓
Requirement > 0?
  ├─ Yes → Check token.ends_with("A" × N)
  │         ├─ Pass → Process action
  │         └─ Fail → 428 Precondition Required
  └─ No → Process action
    ↓
Violation during processing?
  ├─ Yes → Increment counter for IP/network
  └─ No → Continue

Configuration

Address Tracking

The effective requirement is the maximum of individual and network counters.

HTTP Response Headers

Rate-limited responses include informative headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735003600
X-RateLimit-Level: ipv4_individual

Configuration

Rate limits can be configured per-tenant via settings:

{
  "rateLimit.auth.ipv4Individual.shortRps": 2,
  "rateLimit.auth.ipv4Individual.shortBurst": 5,
  "rateLimit.auth.ipv4Individual.longRph": 30,
  "rateLimit.auth.ipv4Individual.longBurst": 30
}

Monitoring

The rate limiter exposes statistics for monitoring:

Best Practices

For API Clients

1. Implement exponential backoff: On 429 responses, wait and retry
2. Respect Retry-After: Don’t retry before the indicated time
3. Use authentication: Authenticated requests may have higher limits
4. Batch requests: Combine multiple operations where possible

For Administrators

1. Monitor rate limit metrics: Watch for patterns indicating attacks
2. Adjust limits per workload: Increase limits for known good IPs
3. Review ban lists: Periodically check for false positives
4. Enable PoW for spam-prone endpoints: Add protection to vulnerable actions

See Also

• System Overview - Architecture overview
• Actions API - Action rate limits
• Federation - Federation rate limits