# Rate limiting ## What this builds A limiter that sits in front of an app's routes. Each caller may make so many requests in a window. A caller over the limit gets status 429 and is told when to come back. The arithmetic is exact, so every build of this spec refuses the same requests. Read `spekkr.inputs.json` first. `default_limit` requests are allowed every `default_window_seconds` seconds. `store` says where counts are kept. `per_route_limits` decides whether R4 exists and `response_headers` whether the headers in R3 are sent. ## Out of scope - Protection against a flood meant to take the app down. That belongs in front of the app, at the network edge. - Quotas per month and billing by usage. - Queueing requests instead of refusing them. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. The limit - A limit is a number of requests and a window. A caller who has been idle can make that many requests at once, and after that one more every window divided by limit. - The limiter keeps one number per caller and limit, and follows the algorithm in `design.md` in whole milliseconds. It does not use floating point. - A refused request does not count against the caller. Accept when: the table of cases in `design.md` passes exactly, row by row. ### R2. Who the caller is - The caller is the first of these that the request has: an API key's id, a signed-in user's id, the IP address. - The IP address is the address of the connection. A forwarding header is believed only when the connection comes from an address listed in `TRUSTED_PROXIES`, and then the right-most address that is not itself a trusted proxy is used. - An IPv6 address is counted by its first 64 bits. Accept when: a forged forwarding header from an untrusted address is ignored, and two addresses in the same IPv6 /64 share one count. ### R3. The answer - A refused request gets status 429, a JSON body with a code and a message, and a `Retry-After` header: the wait in whole seconds, rounded up. - If `response_headers` is on, every answer, allowed or refused, carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. Reset is the number of seconds, rounded up, until the caller has the whole limit again. - The limiter runs before the route's own work. The default limit is checked before the request body is read. Accept when: a caller who waits exactly `Retry-After` seconds is allowed, and the headers match the table in `design.md`. ### R4. Limits for single routes Only if `per_route_limits` is on. - A route can name a limit of its own, with a name, a number and a window. For example `sign_in`: 5 requests in 900 seconds. - A named limit is counted apart from the default. A request to such a route must pass both. - A named limit can say what to count by, such as the email address in a sign-in form in place of the caller. Only such a limit reads the body. It does so after the default limit has passed, and hands the body on to the route unchanged. A request without that field is counted by the caller. Accept when: using up `sign_in` leaves the default untouched, and a request that passes one limit and fails the other is refused without counting against the one it passed. ### R5. Two requests at once - Checking and counting are one step. Two requests that arrive together can never both take the last place. Accept when: 50 requests sent at the same moment against a limit of 10 produce exactly 10 allowed and 40 refused, in every `store`. ### R6. When the store is down - If the store cannot be reached inside 100 milliseconds, the request is allowed and the failure is logged, at most once a minute. - A named limit can be marked `strict`. A strict limit refuses with status 503 when the store is down. Accept when: with the store stopped, an ordinary route answers and a strict one gets 503. ### R7. Exemptions - A health-check route is never limited. - Callers listed in `RATE_LIMIT_EXEMPT`, by API key id or IP address, are never limited. Accept when: an exempt caller makes 1,000 requests in a second and none is refused. ### R8. Keeping the store small - A caller's number is forgotten once the caller would have the whole limit again. - With `store` set to `memory`, at most 100,000 callers are remembered, and the ones idle longest are dropped first. Accept when: after a window with no requests the store holds nothing for the caller. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests set the clock; none of them sleeps. - A README explains how to put the limiter in front of a route, how to name a limit, and how to run the tests.