
# 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](server/overload.md) 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

```yaml
# 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
```

```properties
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:

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

```text
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 Requests`** with `Retry-After` in seconds and the usual [ProblemDetail](errors/problem-detail.md).
- **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-Remaining` and `RateLimit-Reset` are those of the rule that leaves the least. `spring.web.rate-limit.headers: false` turns them off.
- **Only `@RateLimiter`, no rules:** set `spring.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 `ip`** refuses a flood before a session is looked up or a password is hashed (the filter `rateLimitFilter`, order -5000).
- **A rule keyed by `user`** sees the user the security starter authenticated (the filter `authenticatedRateLimitFilter`, 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`.
- **`@RateLimiter`** runs 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.ratelimit` says so, once for the rule.

## The client's address

The address is the connection's own. Behind reverse proxies, name them:

```yaml
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-length` changes the length (`56` or `48` for providers that give out more, `128` to count every address by itself). IPv4 addresses are counted whole.
- **No address in clear in the store:** set `hash-addresses: true` and a `hash-secret`. The keys of addresses are then their HMAC-SHA-256.

See [Behind a reverse proxy](server/reverse-proxy.md).

## 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](server/isolates.md) | none |
| `memory` | in the memory of the isolate | otherwise | none |

- **`procedure`, `jdbc` and `d1`** are shared by every server and every function instance on the database, and outlive a restart.
- **`memory` and `primary-isolate`** keep at most `spring.web.rate-limit.memory.max-entries` keys (100 000). They count for one server only, and start empty after a restart.
- **A bean of your own replaces them all:**

```dart
@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-failure` then 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 request `500`, and the next request tries again. The check costs one call to the store per cold start.
- **`spring.web.rate-limit.verify-store: false`** skips 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.

## See also

- [Overload](server/overload.md)
- [Behind a reverse proxy](server/reverse-proxy.md)
- [A pool of isolates](server/isolates.md)
- [Filters](filters.md)
- [ProblemDetail](errors/problem-detail.md)
- [All properties](properties.md)
- [spring_boot_starter_edge](../spring-boot-starter-edge/index.md)
- [spring_boot_starter_supabase](../spring-boot-starter-supabase/index.md)
