Rate Limit Strategies (proto)

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

type.v3.RateLimitStrategy

[type.v3.RateLimitStrategy proto]

{
  "blanket_rule": ...,
  "requests_per_time_unit": {...},
  "token_bucket": {...}
}
blanket_rule

(type.v3.RateLimitStrategy.BlanketRule) Allow or Deny the requests. If unset, allow all.

Precisely one of blanket_rule, requests_per_time_unit, token_bucket must be set.

requests_per_time_unit

(type.v3.RateLimitStrategy.RequestsPerTimeUnit) Best-effort limit of the number of requests per time unit, f.e. requests per second. Does not prescribe any specific rate limiting algorithm, see RequestsPerTimeUnit for details.

Precisely one of blanket_rule, requests_per_time_unit, token_bucket must be set.

token_bucket

(type.v3.TokenBucket) Limit the requests by consuming tokens from the Token Bucket. Allow the same number of requests as the number of tokens available in the token bucket.

Precisely one of blanket_rule, requests_per_time_unit, token_bucket must be set.

type.v3.RateLimitStrategy.RequestsPerTimeUnit

[type.v3.RateLimitStrategy.RequestsPerTimeUnit proto]

Best-effort limit of the number of requests per time unit.

Allows to specify the desired requests per second (RPS, QPS), requests per minute (QPM, RPM), etc., without specifying a rate limiting algorithm implementation.

RequestsPerTimeUnit strategy does not demand any specific rate limiting algorithm to be used (in contrast to the TokenBucket, for example). It implies that the implementation details of rate limiting algorithm are irrelevant as long as the configured number of “requests per time unit” is achieved.

Note that the TokenBucket is still a valid implementation of the RequestsPerTimeUnit strategy, and may be chosen to enforce the rate limit. However, there’s no guarantee it will be the TokenBucket in particular, and not the Leaky Bucket, the Sliding Window, or any other rate limiting algorithm that fulfills the requirements.

{
  "requests_per_time_unit": ...,
  "time_unit": ...
}
requests_per_time_unit

(uint64) The desired number of requests per time_unit to allow. If set to 0, deny all (equivalent to BlanketRule.DENY_ALL).

Note

Note that the algorithm implementation determines the course of action for the requests over the limit. As long as the requests_per_time_unit converges on the desired value, it’s allowed to treat this field as a soft-limit: allow bursts, redistribute the allowance over time, etc.

time_unit

(type.v3.RateLimitUnit) The unit of time. Ignored when requests_per_time_unit is 0 (deny all).

Enum type.v3.RateLimitStrategy.BlanketRule

[type.v3.RateLimitStrategy.BlanketRule proto]

Choose between allow all and deny all.

ALLOW_ALL

(DEFAULT)

DENY_ALL