Rate limiting
RateLimit is a middleware that stops a client that sends too many requests.
You should use it on login, sign up and other routes that bots like to hammer.
Limiting a route
Add RateLimit to the route. The defaults are max: 60 and per: Duration(minutes: 1):
Route.post('/auth/login', <dynamic>[
RateLimit(max: 5, per: Duration(minutes: 1)),
(AuthController c) => c.login,
]);
Now each client (by ip) can send 5 login requests per minute. The 6th request gets a 429:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
{"code":"too_many_requests","message":"Too Many Requests"}
Retry-After is the number of seconds until the client can try again. Every answer, also a normal one, has the X-RateLimit-Limit and X-RateLimit-Remaining headers. The error goes through your exception handler, so it has the same JSON shape as your other errors.
Limiting every route
To limit all routes, put it in globalMiddleware:
AppConfig appConfig = AppConfig(
globalMiddleware: <dynamic>[
RateLimit(max: 120),
],
// ...
);
Counting by user
By default each ip has its own count. Sometimes you want to count per user instead. Give a key function, which returns any String. For example, count by user id after AuthMiddleware:
Route.get('/reports', <dynamic>[
AuthMiddleware(),
RateLimit(
max: 100,
key: (DoxRequest req) => '${req.auth?.user<User>()?.id ?? req.ip()}',
),
(ReportController c) => c.index,
]);
Do not count by a raw header, like req.header('X-Api-Key'). A client can send a new value with each request and get a new count each time. Count by a value that you checked first, like the id of the logged in user.
Two limits with the same settings
Two RateLimit with the same max and per share one count for the same client. If you want separate counts, give each one a name:
Route.post('/auth/login', <dynamic>[
RateLimit(max: 5, name: 'login'),
(AuthController c) => c.login,
]);
Route.post('/auth/register', <dynamic>[
RateLimit(max: 5, name: 'register'),
(AuthController c) => c.register,
]);
Behind a proxy
Behind Caddy, nginx or a load balancer, every request comes from the proxy ip, so all clients share one count. Add the proxy to AppConfig.trustedProxies, so req.ip() is the real client ip. See App config.
Where the counts live
When the default cache store is Redis, the counts are in Redis, so all isolates and all servers share them. Use this when you run more than one server.
With any other default store, the counts are kept in the main isolate of each server. All isolates of one server share them, but each server has its own counts. So with 3 servers, a client can send up to 3 times max.
To use a store by name, pass store:
Sliding window
By default the count starts at 0 at the start of each window. So a client can send max requests at the end of one minute, and max more at the start of the next. That is fine for most apps.
If you want to stop this burst, set sliding: true:
The count is then the count of this window, plus a part of the window before. That part gets smaller as the window goes on. It costs one more read per request.
Details
- A blocked request still counts, so a client that keeps sending while it is blocked stays blocked.
- In the main isolate mode, each limited request sends one small message to the main isolate.
- A
memorystore named instorealso counts in the main isolate. A store passed incacheStoreis used as it is. - Sliding window example: 4 requests last minute, 1 this minute, 15 seconds in: the count is
4 x 45/60 + 1 = 4.X-RateLimit-Remainingismaxminus this count, rounded up. Each count is kept for 2 windows.