Rate Limiting

Overview

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

Hierarchical Address Levels

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

IPv4 Levels

Level Mask Description Example
Individual /32 Single IP address 192.168.1.100
Network /24 Class C network (256 IPs) 192.168.1.0/24

IPv6 Levels

Level Mask Description Example
Subnet /64 Single subnet 2001:db8:1234:5678::/64
Provider /48 ISP allocation 2001:db8:1234::/48
Multi-Level Protection

A single abusive IP can’t overwhelm the system, but neither can a botnet spread across a /24 network. Both individual and network-level limits apply.

Dual-Tier Limits

Each address level has two tiers of limits:

Tier Period Purpose
Short-term Per-second Burst protection
Long-term Per-hour Sustained abuse protection

Both tiers must pass.

Default Rate Limits

Category IPv4 Individual IPv4 Network (/24) IPv6 Subnet (/64) IPv6 Provider (/48)
Auth 5/s (burst 10), 60/h 15/s (burst 30), 200/h 5/s (burst 10), 60/h 15/s (burst 30), 200/h
Federation 100/s (burst 200), 1000/h 500/s (burst 750), 5000/h 100/s (burst 200), 1000/h 500/s (burst 750), 5000/h
General 300/s (burst 500), 5000/h 600/s (burst 1000), 50000/h 300/s (burst 500), 5000/h 600/s (burst 1000), 50000/h
WebSocket 100/s (burst 200), 1000/h 100/s (burst 200), 1000/h 100/s (burst 200), 1000/h 100/s (burst 200), 1000/h
  • Auth: Login, registration, password reset
  • Federation: Inbox, sync, token exchange
  • General: Profile viewing, action listing, file access
  • WebSocket: Notification bus, CRDT, RTDB connections

Proof-of-Work Protection

CONN (connection request) actions require proof-of-work when violations are detected from an IP address. Violations (failed signature, duplicate pending, rejected CONN) increment a counter tracked at both individual IP and network range levels. The counter decays by 1 every hour.

When PoW is required, the action token must end with N A characters (where N = counter value). For example, counter=2 requires the token to end with AA. The server responds with HTTP 428 (Precondition Required) when PoW is insufficient.

Parameter Default Description
max_counter 10 Maximum requirement (10 ‘A’ characters)
decay_interval_secs 3600 Counter decay interval (1 hour)
max_individual_entries 50,000 LRU cache size for individual IPs
max_network_entries 10,000 LRU cache size for network ranges

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
Header Description
Retry-After Seconds until request can be retried
X-RateLimit-Limit Maximum requests per period
X-RateLimit-Remaining Requests remaining in period
X-RateLimit-Reset Unix timestamp when limit resets
X-RateLimit-Level Which address level triggered the limit

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
}

See Also