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

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

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

See Behind a reverse proxy.

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
@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:

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.

See also