Rate Limiter - built for Cloudflare Workers, using Durable Objects
Features
- Supports fixed or sliding window algorithms
- Scoped rate-limiting
- Caching
- Cleanup of stale DO data using alarm
- Responses provide all information needed to take actions (or not)
- Tested in production (well, not actually)
FAQ
How to use
You can use it as a subworker as described here.
But it doesn't rate limit anything
Yeah, that's the sad truth. The code is there to decide whether or not a request should be rate-limited, but currently it just outputs the results in a JSON response. The reason is because this is how it's being used as part of another project I'm working on. That said, I think it's a good starting point as it would require minimal changes from you to send the right responses back.
What about pricing? How it compares with CF's own rate-limiter?
Well, it all depends in the use-case. You can check out the cost calculator.
Description of JSON Body (usage)
type
: type can be one ofsliding
orfixed
and describes the algorithm that will be used.scope
: the value of this header is used as the rate-limit scope.key
: the key is the client information, can be an IP (most of the time), or a network, a username, or even a user-agent. In general, feel free to use whatever you like.limit
: the value of this header provides the request limit (e.g. 10).interval
: the interval (in seconds) upon which all calculations are based.
Responses
Response status will be one of:
200
, meaning that the request was processed without problems400
, JSON input error500
, any other error, info can be found at response body
Response body on successful requests depends on the type of the algorithm used and the outcome.
If the request should be rate-limited, you would find an error
property, with a value of rate-limited
, if not, depending on the algorithm used, you will find quota information:
- The
sliding
type might return one of the two following bodies:
{
"rate": "number, rate of the incoming requests"
}
or
{
"rate": "number, rate of the incoming requests",
"error": "rate-limited"
}
- The
fixed
type might return one of the following bodies:
{
"resets": "number, seconds since epoch",
"remaining": "number, remaining requests until rate-limiting"
}
or
{
"resets": "number, seconds since epoch",
"error": "rate-limited"
}