Skip to main content

CL.THROTTLE

Syntax​

CL.THROTTLE <key> <max_burst> <count per period> <period> [<quantity>]

Time complexity: O(1)

ACL categories: @throttle

This command provides functionality for implementing a rate limiter and is based on a Redis module called redis-cell.

The command implements the fairly sophisticated generic cell rate algorithm (GCRA), which is a leaky bucket-type scheduling algorithm providing a rolling time window and doesn't depend on a background drip process.

By using the CL.THROTTLE command, which is natively supported in Dragonfly, you can replace (directly or with code modification) existing Redis modules or libraries implementing a leaky bucket or a token bucket rate limiter, such as the following:

Parameter Explanations​

  • key: An identifier to rate limit against, such as a user ID or an IP address.
  • The rest of the parameters are self-explanary:
dragonfly$> CL.THROTTLE user123 20 120 60 1
#                          ^     ^   ^  ^ ^
#                          |     |   |  | └───── apply 1 token (default if omitted)
#                          |     |   └──┴─────── 120 tokens / 60 seconds
#                          |     └────────────── 20 max_burst
#                          └──────────────────── key "user123"

Return Values​

An array of 5 integers with the following values:

  1. Whether to limit the related action (0 for allowed, 1 for limited).
  2. The total limit of the key. (Equivalent to X-RateLimit-Limit)
  3. The remaining limit of the key. (Equivalent to X-RateLimit-Remaining)
  4. Number of seconds to wait until a retry if the related action should be limited, else -1. (Equivalent to Retry-After)
  5. Number of seconds until the limit is fully restored. (Equivalent to X-RateLimit-Reset)

Examples​

dragonfly$> CL.THROTTLE user123 0 1 10 1
1) (integer) 0
2) (integer) 1
3) (integer) 0
4) (integer) -1
5) (integer) 11

dragonfly$> CL.THROTTLE user123 0 1 10 1
1) (integer) 1
2) (integer) 1
3) (integer) 0
4) (integer) 10
5) (integer) 10