Rate Limit Service (RLS)¶

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

service/ratelimit/v2/rls.proto

service.ratelimit.v3.RateLimitRequest¶

[service.ratelimit.v3.RateLimitRequest proto]

Main message for a rate limit request. The rate limit service is designed to be fully generic in the sense that it can operate on arbitrary hierarchical key/value pairs. The loaded configuration will parse the request and find the most specific limit to apply. In addition, a RateLimitRequest can contain multiple “descriptors” to limit on. When multiple descriptors are provided, the server will limit on ALL of them and return an OVER_LIMIT response if any of them are over limit. This enables more complex application level rate limiting scenarios if desired.

{
  "domain": "...",
  "descriptors": [],
  "hits_addend": "..."
}

domain: (string) All rate limit requests must specify a domain. This enables the configuration to be per application without fear of overlap. E.g., “envoy”.

descriptors: (repeated extensions.common.ratelimit.v3.RateLimitDescriptor) All rate limit requests must specify at least one RateLimitDescriptor. Each descriptor is processed by the service (see below). If any of the descriptors are over limit, the entire request is considered to be over limit.

hits_addend: (uint32) Rate limit requests can optionally specify the number of hits a request adds to the matched limit. If the value is not set in the message, a request increases the matched limit by 1.

service.ratelimit.v3.RateLimitResponse¶

[service.ratelimit.v3.RateLimitResponse proto]

A response from a ShouldRateLimit call.

{
  "overall_code": "...",
  "statuses": [],
  "response_headers_to_add": [],
  "request_headers_to_add": [],
  "raw_body": "...",
  "dynamic_metadata": "{...}"
}

overall_code: (service.ratelimit.v3.RateLimitResponse.Code) The overall response code which takes into account all of the descriptors that were passed in the RateLimitRequest message.

statuses: (repeated service.ratelimit.v3.RateLimitResponse.DescriptorStatus) A list of DescriptorStatus messages which matches the length of the descriptor list passed in the RateLimitRequest. This can be used by the caller to determine which individual descriptors failed and/or what the currently configured limits are for all of them.

response_headers_to_add: (repeated config.core.v3.HeaderValue) A list of headers to add to the response

request_headers_to_add: (repeated config.core.v3.HeaderValue) A list of headers to add to the request when forwarded

raw_body: (bytes) A response body to send to the downstream client when the response code is not OK.

dynamic_metadata

(Struct) Optional response metadata that will be emitted as dynamic metadata to be consumed by the next filter. This metadata lives in a namespace specified by the canonical name of extension filter that requires it:

envoy.filters.http.ratelimit for HTTP filter.
envoy.filters.network.ratelimit for network filter.
envoy.filters.thrift.rate_limit for Thrift filter.

service.ratelimit.v3.RateLimitResponse.RateLimit¶

[service.ratelimit.v3.RateLimitResponse.RateLimit proto]

Defines an actual rate limit in terms of requests per unit of time and the unit itself.

{
  "name": "...",
  "requests_per_unit": "...",
  "unit": "..."
}

name: (string) A name or description of this limit.

requests_per_unit: (uint32) The number of requests per unit of time.

unit: (service.ratelimit.v3.RateLimitResponse.RateLimit.Unit) The unit of time.

Enum service.ratelimit.v3.RateLimitResponse.RateLimit.Unit¶

[service.ratelimit.v3.RateLimitResponse.RateLimit.Unit proto]

Identifies the unit of of time for rate limit.

UNKNOWN: (DEFAULT) ⁣The time unit is not known.

SECOND: ⁣The time unit representing a second.

MINUTE: ⁣The time unit representing a minute.

HOUR: ⁣The time unit representing an hour.

DAY: ⁣The time unit representing a day.

service.ratelimit.v3.RateLimitResponse.DescriptorStatus¶

[service.ratelimit.v3.RateLimitResponse.DescriptorStatus proto]

{
  "code": "...",
  "current_limit": "{...}",
  "limit_remaining": "...",
  "duration_until_reset": "{...}"
}

code: (service.ratelimit.v3.RateLimitResponse.Code) The response code for an individual descriptor.

current_limit: (service.ratelimit.v3.RateLimitResponse.RateLimit) The current limit as configured by the server. Useful for debugging, etc.

limit_remaining: (uint32) The limit remaining in the current time unit.

duration_until_reset: (Duration) Duration until reset of the current limit window.

Enum service.ratelimit.v3.RateLimitResponse.Code¶

[service.ratelimit.v3.RateLimitResponse.Code proto]

UNKNOWN: (DEFAULT) ⁣The response code is not known.

OK: ⁣The response code to notify that the number of requests are under limit.

OVER_LIMIT: ⁣The response code to notify that the number of requests are over limit.