DEV: (cmds) add GCRA command page and general info.#2943
DEV: (cmds) add GCRA command page and general info.#2943dwdougherty wants to merge 2 commits intoDOC-6334from
Conversation
🛡️ Jit Security Scan Results
✅ No security findings were detected in this PR
Security scan by Jit
|
mich-elle-luna
left a comment
mich-elle-luna
left a comment
There was a problem hiding this comment.
just one change from me, thank you!
Co-authored-by: mich-elle-luna <153109578+mich-elle-luna@users.noreply.github.com>
|
Thank you for the review and comment, @mich-elle-luna! |
|
|
||
| Performs rate limiting using the [Generic Cell Rate Algorithm (GCRA)](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm). | ||
|
|
||
| GCRA is a popular rate limiting algorithm known for its simplicity and speed. It allows a sustained rate of `requests_per_period` requests per `period` seconds, with a minimum spacing (emission interval) of `period / requests_per_period` seconds between each request. The `max_burst` parameter allows for occasional spikes by granting up to `max_burst` additional requests to be consumed at once beyond the sustained rate. |
There was a problem hiding this comment.
While everything is correct, I suggest using the 'tokens' terminology.
Each request is associated with a given number of tokens (default = 1).
requests_per_period should be renamed to tokens_per_period
(max_burst is already in tokens)
|
|
||
| ## Optional arguments | ||
|
|
||
| <details open><summary><code>NUM_REQUESTS count</code></summary> |
There was a problem hiding this comment.
Suggest renaming NUM_REQUESTS to NUM_TOKENS or simply TOKENS.
|
|
||
| <details open><summary><code>NUM_REQUESTS count</code></summary> | ||
|
|
||
| is the cost (or weight) of this rate-limiting request. A higher cost drains the allowance faster. This is useful when different operations have different costs. Default value: `1`. |
There was a problem hiding this comment.
We don't need to use cost and weight, just Number of tokens. For a single request, we can use requested
tokens.
| weight: 40 | ||
| --- | ||
|
|
||
| Rate limiting controls how often a user or client can perform an action within |
There was a problem hiding this comment.
Some use cases you can add:
- Preventing DDoS attacks
- Preventing brute force attacks
- Preventing API abuse
- Preventing web scraping
- Limiting resource consumption based on subscription type
Some examples you can add:
- Credit card processing: limit the number of each user’s attempted transactions per minute
- Dating site: per user - limit profiles view per hour
- Download site: limit the number of files each free-tier user can download per day
|
|
||
| ## Examples | ||
|
|
||
| Rate limit an API endpoint to 10 requests per 60 seconds with a burst of 5: |
There was a problem hiding this comment.
10 tokens per 60 seconds with a burst of 5 tokens:
| Performs rate limiting using the [Generic Cell Rate Algorithm (GCRA)](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm). | ||
|
|
||
| GCRA is a popular rate limiting algorithm known for its simplicity and speed. It allows a sustained rate of `requests_per_period` requests per `period` seconds, with a minimum spacing (emission interval) of `period / requests_per_period` seconds between each request. The `max_burst` parameter allows for occasional spikes by granting up to `max_burst` additional requests to be consumed at once beyond the sustained rate. | ||
|
|
There was a problem hiding this comment.
One important note about this command:
It is used to either establish a new rate limiter (if the key doesn't exist) or use an existing one (if the key exists). That's why all the parameters need to be repeated on each call (clients don't need to validate that the key exists before using an existing rate limiter).
Under normal usage, max-burst, tokens-per-period, and period should not change between calls, though this command supports such changes as well.
|
|
||
| ## Comparison with other approaches | ||
|
|
||
| Before the `GCRA` command, common approaches for rate limiting in Redis |
There was a problem hiding this comment.
I suggest removing this because in future versions we plan https://redislabs.atlassian.net/browse/RED-191300
| - **External modules** like redis-cell: effective but require installing and | ||
| maintaining a separate module. | ||
|
|
||
| The built-in `GCRA` command provides the same functionality with better |
There was a problem hiding this comment.
It is not the same functionality. The rate-limiting algorithm is different.
3 participants
Redis 8.8 feature
@LiorKogan: I'm anticipating lots of "red ink" on this one! 🫠
Note
Low Risk
Low risk since this PR only adds documentation and an SVG diagram, with no runtime or API behavior changes. Primary risk is doc correctness/consistency (e.g., argument names/return description) affecting user understanding.
Overview
Adds new documentation for the Redis 8.8
GCRArate-limiting command, including full command reference metadata (arguments, ACL/categories, reply schema), usage explanation, and examples.Introduces a new Rate limiting guide under
develop/using-commandsthat explains GCRA concepts, common patterns, and client-side handling, and adds thegcrarailroad diagram SVG for syntax visualization.Written by Cursor Bugbot for commit 8afb220. This will update automatically on new commits. Configure here.