Rate limiting
The rate limiter bounds how often one client may ask: five logins a minute for an address, 120 calls a minute for a user. A request past a limit is answered 429 Too Many Requests with Retry-After. It is off until you give it a rule, or set spring.web.rate-limit.enabled: true.
Why
A server that anyone can reach is asked by anyone, as often as they like. Without a limit, one client can guess passwords all day, or take the whole server for itself. Overload protects the server as a whole; the rate limiter says how much of it one client gets.
The count must be right when requests arrive at the same moment, and the same on every server and every instance of a function. So a bucket is changed in one atomic step, and where it is kept is a choice: the memory of the server, a table of your database, a database function of a Supabase project, a D1 database of a Cloudflare Worker.
Example
# lib/resources/application.yml
spring:
web:
rate-limit:
rules:
- path: /api/auth/** # logins: by address
methods: [POST]
key: ip
limit: 5/1m
- path: /api/** # the API: by user
limit: 120/1m
spring.web.rate-limit.rules[0].path=/api/auth/**
spring.web.rate-limit.rules[0].methods=POST
spring.web.rate-limit.rules[0].key=ip
spring.web.rate-limit.rules[0].limit=5/1m
spring.web.rate-limit.rules[1].path=/api/**
spring.web.rate-limit.rules[1].limit=120/1m
And for one controller method or class:
@RestController()
class ReportController {
ReportController(this.reports);
final ReportService reports;
// Ten exports a minute for each user, whatever the rules allow.
@PostMapping('/reports/export')
@RateLimiter('10/1m', key: '#{authentication.name}')
Future<Report> export() => reports.export();
}
The sixth login of an address within a minute gets:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 12
Content-Type: application/problem+json
What a request past a limit gets
429 Too Many RequestswithRetry-Afterin seconds and the usual ProblemDetail.- Its body is not read, and nothing else of it is processed.
- Every rule that matches applies. A request passes only when all of them allow it.
- The headers
RateLimit-Limit,RateLimit-RemainingandRateLimit-Resetare those of the rule that leaves the least.spring.web.rate-limit.headers: falseturns them off. - Only
@RateLimiter, no rules: setspring.web.rate-limit.enabled: true. The start fails when a controller has the annotation and nothing turned the limiter on.
The limit
A limit reads <count>/<duration>: 5/1m, 10/s, 1000/1h. The duration needs its unit: 100/60 is refused at startup; write 100/60s.
It is a token bucket: count requests at once, then refilled evenly, one every duration / count. burst sets the size of the bucket apart from the rate: limit: 60/1m with burst: 10 allows ten at once, then one a second.
The key: who a bucket belongs to
key |
Counted by | Decided |
|---|---|---|
user (the default) |
the authenticated user, else the client's address | right after the security filter chain |
ip |
the client's address | before the sessions and the security filter chain |
#{...} |
a SpEL expression over request, headers, principal, authentication, address, method, path; nothing or an empty text counts by address |
right after the security filter chain |
| a name of your own | a RateLimitKeyResolver bean that supports it |
as the resolver says |
- A rule keyed by
iprefuses a flood before a session is looked up or a password is hashed (the filterrateLimitFilter, order -5000). - A rule keyed by
usersees the user the security starter authenticated (the filterauthenticatedRateLimitFilter, order -50, just after the security chain at -100). - A request the security chain answered itself (a 401, a 403) does not reach the rules keyed by the user. Limit those by
ip. @RateLimiterruns in an interceptor, after both filters and before the method's arguments are bound.- A header that is not sent:
#{request.headers['X-Api-Key']}counts a request without the header by its address. A header name is found in any case. - A mistake in the expression: one that cannot be parsed fails the start, naming the rule. One that reads what does not exist is only found with a request: the rule then counts by address, and one WARN line on
spring.web.ratelimitsays so, once for the rule.
The client's address
The address is the connection's own. Behind reverse proxies, name them:
spring:
web:
rate-limit:
trusted-proxies: [173.245.48.0/20, 2400:cb00::/32] # addresses and CIDR ranges
client-address-header: X-Forwarded-For # the default; or CF-Connecting-IP
- Only a connection from a trusted proxy has the header read. The client is the entry the first trusted proxy added, counting from the right. Everything to the left of it is what the client itself sent, and is ignored.
- Without trusted proxies no header is ever read, so a client cannot choose its bucket by sending a header.
- An IPv6 client is counted by its network, the first 64 bits of its address: a provider gives one client a whole /64, and the client may use another address of it for every request.
spring.web.rate-limit.ipv6-prefix-lengthchanges the length (56or48for providers that give out more,128to count every address by itself). IPv4 addresses are counted whole. - No address in clear in the store: set
hash-addresses: trueand ahash-secret. The keys of addresses are then their HMAC-SHA-256.
The store: where the buckets are kept
The store is one interface, RateLimitStore, with one atomic operation. Without spring.web.rate-limit.store, it is the most specific one the application has:
store |
The buckets are | The default when | Its table |
|---|---|---|---|
procedure |
behind a database function of a Supabase project, called through its REST API as the service role | the application uses spring_boot_starter_supabase without a database connection |
from a migration: sql/rate_limit.sql of that package |
jdbc |
in a table of the primary DataSource (PostgreSQL, SQLite) |
the application has a primary DataSource |
created by the store with spring.data.jdbc.schema: create or spring.data.jdbc.rate-limit.create-table: true; else from a migration (sql/rate_limit/ of spring_boot_starter_data) |
d1 |
in a D1 database of a Cloudflare Worker (spring_boot_starter_edge) |
spring.edge.cloudflare.rate-limit.database names a binding |
created by the store |
primary-isolate |
in the memory of the first isolate, for all of the pool | the server runs a pool of isolates | none |
memory |
in the memory of the isolate | otherwise | none |
procedure,jdbcandd1are shared by every server and every function instance on the database, and outlive a restart.memoryandprimary-isolatekeep at mostspring.web.rate-limit.memory.max-entrieskeys (100 000). They count for one server only, and start empty after a restart.- A bean of your own replaces them all:
@Component()
class KvRateLimitStore implements RateLimitStore {
@override
Future<RateLimitDecision> tryAcquire(String key, RateLimit limit,
{int permits = 1}) => ...; // one atomic step in your store
}
When the store cannot be reached
The request is refused with a 503 and Retry-After (on-store-failure: deny, the default): a limit on logins must not open when the database is down. allow lets the request through, not counted. Both can be set for one rule. One WARN line on spring.web.ratelimit names the rule, never the key.
The store is checked at startup
A store in a database needs its table or its function. The application asks the store for them once when it starts:
- Missing (a migration that was not run, a binding that is not declared, a service role that may not call the function): the application does not start, and the error says what to run. Without the check, a forgotten migration shows only at the first request under a limit, as a
503. - Not reachable at that moment (the database is down, the network): one WARN line, and the start goes on.
on-store-failurethen decides for each request. - In a function (
spring_boot_starter_edge) the start is the first request of an instance: a failed check answers that request500, and the next request tries again. The check costs one call to the store per cold start. spring.web.rate-limit.verify-store: falseskips the check and its call.- A store of your own takes part by implementing
VerifiableRateLimitStore.
Properties
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.web.rate-limit.enabled |
bool |
not set: on when rules has a rule |
Whether requests are limited. false turns the rules and the annotations off |
spring.web.rate-limit.store |
memory / primary-isolate / jdbc / procedure / d1, or the name of another library's store |
the most specific the application has | Where the buckets are kept |
spring.web.rate-limit.on-store-failure |
deny / allow |
deny |
What a request gets when the store cannot be reached |
spring.web.rate-limit.store-failure-retry-after |
Duration |
5s |
The Retry-After of that 503 |
spring.web.rate-limit.verify-store |
bool |
true |
Whether the store is asked at startup that its table, function or binding is there |
spring.web.rate-limit.trusted-proxies |
list of addresses and CIDR ranges | empty | The reverse proxies whose header is read |
spring.web.rate-limit.client-address-header |
header name | X-Forwarded-For |
The header a trusted proxy puts the client's address in |
spring.web.rate-limit.ipv6-prefix-length |
int, 1 to 128 |
64 |
How many bits of an IPv6 address say who a client is |
spring.web.rate-limit.hash-addresses |
bool |
false |
Stores the keys made of an address as their HMAC-SHA-256 |
spring.web.rate-limit.hash-secret |
String |
none | The secret of hash-addresses; the same on every server that shares a store |
spring.web.rate-limit.headers |
bool |
true |
Whether the answers carry the RateLimit-* headers |
spring.web.rate-limit.memory.max-entries |
int |
100000 |
The most keys the stores in memory keep |
spring.web.rate-limit.rules[n].name |
String |
rule-<n+1> |
The rule's name: the first part of its keys in the store, and what the logs call it |
spring.web.rate-limit.rules[n].path |
path pattern | /** |
The paths the rule is for, inside the context path |
spring.web.rate-limit.rules[n].methods |
list of HTTP methods | empty: all | The methods the rule is for |
spring.web.rate-limit.rules[n].key |
user / ip / #{...} / a name of a RateLimitKeyResolver |
user |
Who a bucket belongs to |
spring.web.rate-limit.rules[n].limit |
<count>/<duration> |
required | The limit: 5/1m, 120/1m, 10/s |
spring.web.rate-limit.rules[n].burst |
int |
the count of limit |
The most requests at once |
spring.web.rate-limit.rules[n].on-store-failure |
deny / allow |
spring.web.rate-limit.on-store-failure |
The same for this rule |
The stores in a database have keys of their own: spring.data.jdbc.rate-limit.table and .create-table (spring_boot_starter_data), spring.supabase.rate-limit.function (spring_boot_starter_supabase), spring.edge.cloudflare.rate-limit.database and .table (spring_boot_starter_edge).
In Spring (Java)
Spring has no rate limiter in its core. The nearest are Resilience4j's @RateLimiter (one limit for all callers of a method), Bucket4j, and Spring Cloud Gateway's RequestRateLimiter (a KeyResolver and a store in Redis), whose shape this one follows: a key resolver, a token bucket, and a store that does the arithmetic next to the data. All of spring.web.rate-limit.* is this starter's own, and so is the check of the store at startup.