Rate Limiting¶
EventSourcingDB limits how many requests a single client may send, so that a client which accidentally sends far too many requests – for example because of a runaway loop – cannot overwhelm the database. Rate limiting is enabled by default and applies to the API.
How It Works¶
The limit is applied per client, identified by the source IP address of the connection. This isolates the offender: a client that sends too many requests exhausts only its own budget, so no other client gets throttled on its account. On a large machine, a single budget covers much of what the database can handle, so a runaway client can still slow the others down. Forwarded headers such as X-Forwarded-For are deliberately not trusted, because EventSourcingDB is meant to run in a protected network with controlled clients.
Requests are weighted, because writing is markedly more expensive than reading: a write counts as several requests, while a read counts as one. The limit you configure is therefore best understood as a budget of read-equivalent requests per second.
When a client exceeds its limit, the database responds with 429 Too Many Requests and a Retry-After header that tells the client how long to wait. On normal responses, the database also sends the RateLimit and RateLimit-Policy headers, so that a cooperative client can slow down before it is throttled instead of running into errors.
The remaining quota in these headers is expressed in request units, not in plain request counts – a write consumes several units, a read one. So a remaining value of, say, 4 means a read would still pass while a write would not. The Retry-After header remains the authoritative answer to when a rejected request may be retried.
Rate limiting is always active and not tied to your license; it is a safeguard, not a premium feature.
Configuring the Limit¶
By default, each client may send 1,000 read-equivalent requests per second for every CPU the database runs on, so 8,000 with 8 CPUs. In a container with a CPU limit, that limit counts rather than the CPUs of the host, rounded up to whole CPUs and at least 2. This is high enough not to interfere with ordinary workloads and low enough to contain accidents. For most deployments, you should not need to change anything.
This is an advanced setting. Only change it if you understand what you are doing and what the consequences are – setting it too high defeats the protection, while setting it too low can throttle legitimate clients.
If a legitimate workload runs into the limit, raise it above the default with the --rate-limit-requests-per-second flag, for example to twice the default on a machine with 8 CPUs:
To disable the per-client limit entirely, set the value to 0:
The recommended approach is to start with the default and raise the limit only if you actually hit it, rather than guessing a higher value up front.
For More Information¶
- To restrict who may access the database at all, see Security and Access Control.
- To temporarily disable writes, see Read-Only Mode.