☰
Navigation :

ratelimit.proto

Package: ratelimit.api.solo.io

Types:

Source File: github.com/solo-io/solo-apis/api/rate-limiter/v1alpha1/ratelimit.proto

RateLimitConfigSpec

A RateLimitConfig describes a rate limit policy.

"raw": .ratelimit.api.solo.io.RateLimitConfigSpec.Raw
Field Type Description
raw .ratelimit.api.solo.io.RateLimitConfigSpec.Raw Define a policy using the raw configuration format used by the server and the client (Envoy).

Raw

This object allows users to specify rate limit policies using the raw configuration formats used by the server and the client (Envoy). When using this configuration type, it is up to the user to ensure that server and client configurations match to implement the desired behavior. The server (and the client libraries that are shipped with it) will ensure that there are no collisions between raw configurations defined on separate RateLimitConfig resources.

"descriptors": []ratelimit.api.solo.io.Descriptor
"rateLimits": []ratelimit.api.solo.io.RateLimitActions
"setDescriptors": []ratelimit.api.solo.io.SetDescriptor
Field Type Description
descriptors []ratelimit.api.solo.io.Descriptor The descriptors that will be applied to the server.
rateLimits []ratelimit.api.solo.io.RateLimitActions Actions specify how the client (Envoy) will compose the descriptors that will be sent to the server to make a rate limiting decision.
setDescriptors []ratelimit.api.solo.io.SetDescriptor The set descriptors that will be applied to the server.

RateLimitConfigStatus

The current status of the RateLimitConfig.

"state": .ratelimit.api.solo.io.RateLimitConfigStatus.State
"message": string
"observedGeneration": int
Field Type Description
state .ratelimit.api.solo.io.RateLimitConfigStatus.State The current state of the RateLimitConfig.
message string A human-readable string explaining the status.
observedGeneration int The observed generation of the resource. When this matches the metadata.generation of the resource, it indicates the status is up-to-date.

State

Name Description
PENDING
ACCEPTED
REJECTED

RateLimitConfigNamespacedStatuses

"statuses": map<string, .ratelimit.api.solo.io.RateLimitConfigStatus>
Field Type Description
statuses map<string, .ratelimit.api.solo.io.RateLimitConfigStatus>

Descriptor

A descriptor is a list of key/value pairs that the rate limit server uses to select the correct rate limit to use when limiting. Descriptors are case-sensitive.

Each configuration contains a top level descriptor list and potentially multiple nested lists beneath that. The format is:

descriptors:
  - key: <rule key: required>
    value: <rule value: optional>
    rate_limit: (optional block)
      unit: <see below: required>
      requests_per_unit: <see below: required>
    descriptors: (optional block)
      - ... (nested repetition of above)

Each descriptor in a descriptor list must have a key. It can also optionally have a value to enable a more specific match. The rate_limit block is optional and, if present, sets up an actual rate limit rule. If the rate limit is not present and there are no nested descriptors, then the descriptor is effectively whitelisted. Otherwise, nested descriptors allow more complex matching and rate limiting scenarios.

"key": string
"value": string
"rateLimit": .ratelimit.api.solo.io.RateLimit
"descriptors": []ratelimit.api.solo.io.Descriptor
"weight": int
"alwaysApply": bool
Field Type Description
key string The key of the descriptor. This field is required.
value string Optional value for the descriptor. If omitted, the server will create a rate limit for each value that is provided for this descriptor in rate limit requests.
rateLimit .ratelimit.api.solo.io.RateLimit Optional rate limit rule for the descriptor.
descriptors []ratelimit.api.solo.io.Descriptor Nested descriptors.
weight int Each top-level Descriptor defines a new Rate Limit “rule”. When a request comes in, rate limit actions are applied to the request to generate descriptor tuples that are sent to the rate limit server. If any rule is triggered then the entire request returns HTTP 429 Too Many Requests. Typically, rule priority is signalled by nesting descriptors, as the most specific rule match for the descriptor tuple generated by the rate limit actions is used. In rare cases this is too restrictive; instead you can set rule priority by setting weights on your descriptors. All rules with the highest weight are processed, if any of these rules trigger rate limiting then the entire request will return a 429. Rules that are not considered for rate limiting are ignored in the rate limit server, and their request count is not incremented in the rate limit server cache. Defaults to 0; thus all rules are evaluated by default.
alwaysApply bool A boolean override for rule priority via weighted rules. Any rule with alwaysApply set to true will always be considered for rate limiting, regardless of the rule’s weight. The rule with the highest weight will still be considered. (this can be a rule that also has alwaysApply set to true) Defaults to false.

SetDescriptor

A setDescriptor is a list of key/value pairs that the rate limit server uses to select the correct rate limit to use when limiting with the set style. Descriptors are case-sensitive.

Each configuration contains a simpleDescriptor list and a rateLimit. The format is:

set_descriptors:
 - simple_descriptors: (optional block)
     - key: <rule key: required>
       value: <rule value: optional>
     - ... (repetition of above)
   rate_limit:
     requests_per_unit: <see below: required>
     unit: <see below: required>
   always_apply: <bool value: optional>
 - ... (repetition of above)

Each SetDescriptor defines a new Rate Limit “rule”. When a request comes in, rate limit actions are applied to the request to generate descriptor tuples that are sent to the rate limit server. If any rule is triggered then the entire request returns HTTP 429 Too Many Requests.

The rate_limit block sets up an actual rate limit rule.

"simpleDescriptors": []ratelimit.api.solo.io.SimpleDescriptor
"rateLimit": .ratelimit.api.solo.io.RateLimit
"alwaysApply": bool
Field Type Description
simpleDescriptors []ratelimit.api.solo.io.SimpleDescriptor Simple descriptor key/value pairs.
rateLimit .ratelimit.api.solo.io.RateLimit Rate limit rule for the descriptor.
alwaysApply bool Typically, rule priority is signalled by rule ordering, as the first rule match for the descriptor tuple generated by the rate limit actions is used. In some cases this is too restrictive; A boolean override can be specified. Any rule with alwaysApply set to true will always be considered for rate limiting, regardless of the rule’s place in the ordered list of rules. The first rule to match will still be considered. (This can be a rule that also has alwaysApply set to true.) If any of these rules trigger rate limiting then the entire request will return a 429. Rules that are not considered for rate limiting are ignored in the rate limit server, and their request count is not incremented in the rate limit server cache. Defaults to false.

SimpleDescriptor

A simpleDescriptor is a list of key/value pairs that the rate limit server uses to select the correct rate limit to use when limiting with the set style. Descriptors are case-sensitive.

The format is:

 simple_descriptors:
   - key: <rule key: required>
     value: <rule value: optional>
   - ... (repetition of above)

Each simpleDescriptor in a simpleDescriptor list must have a key. It can also optionally have a value to enable a more specific match.

"key": string
"value": string
Field Type Description
key string The key of the descriptor. This field is required.
value string Optional value for the descriptor. If omitted, the server will create a rate limit for each value that is provided for this descriptor in rate limit requests.

RateLimitActions

Each action and setAction in the lists maps part of the request (or its context) to a descriptor. The tuple or set of descriptors generated by the provided actions is sent to the rate limit server and matched against rate limit rules. Order matters on provided actions but not on setActions, e.g. the following actions:

While the current form matches, the same tuple in reverse order would not match the following descriptor:

descriptors:

Similarly, the following setActions:

This set would match the following setDescriptor:

setDescriptors:

It would also match the following setDescriptor which includes only a subset of the setActions enumerated:

setDescriptors:

It would even match the following setDescriptor. Any setActions list would match this setDescriptor which has simpleDescriptors omitted entirely:

setDescriptors:

"actions": []ratelimit.api.solo.io.Action
"setActions": []ratelimit.api.solo.io.Action
"limit": .ratelimit.api.solo.io.Override
Field Type Description
actions []ratelimit.api.solo.io.Action
setActions []ratelimit.api.solo.io.Action
limit .ratelimit.api.solo.io.Override An optional limit override to be appended to the descriptor produced by this rate limit configuration. If the override value is invalid or cannot be resolved from metadata, no override is provided.

RateLimit

A RateLimit specifies the actual rate limit that will be used when there is a match.

"unit": .ratelimit.api.solo.io.RateLimit.Unit
"requestsPerUnit": int
Field Type Description
unit .ratelimit.api.solo.io.RateLimit.Unit
requestsPerUnit int

Unit

Name Description
UNKNOWN
SECOND
MINUTE
HOUR
DAY

Action

Copied directly from envoy https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-ratelimit-action

"sourceCluster": .ratelimit.api.solo.io.Action.SourceCluster
"destinationCluster": .ratelimit.api.solo.io.Action.DestinationCluster
"requestHeaders": .ratelimit.api.solo.io.Action.RequestHeaders
"remoteAddress": .ratelimit.api.solo.io.Action.RemoteAddress
"genericKey": .ratelimit.api.solo.io.Action.GenericKey
"headerValueMatch": .ratelimit.api.solo.io.Action.HeaderValueMatch
"metadata": .ratelimit.api.solo.io.MetaData
Field Type Description
sourceCluster .ratelimit.api.solo.io.Action.SourceCluster Rate limit on source cluster. Only one of sourceCluster, destinationCluster, requestHeaders, remoteAddress, genericKey, headerValueMatch, or metadata can be set.
destinationCluster .ratelimit.api.solo.io.Action.DestinationCluster Rate limit on destination cluster. Only one of destinationCluster, sourceCluster, requestHeaders, remoteAddress, genericKey, headerValueMatch, or metadata can be set.
requestHeaders .ratelimit.api.solo.io.Action.RequestHeaders Rate limit on request headers. Only one of requestHeaders, sourceCluster, destinationCluster, remoteAddress, genericKey, headerValueMatch, or metadata can be set.
remoteAddress .ratelimit.api.solo.io.Action.RemoteAddress Rate limit on remote address. Only one of remoteAddress, sourceCluster, destinationCluster, requestHeaders, genericKey, headerValueMatch, or metadata can be set.
genericKey .ratelimit.api.solo.io.Action.GenericKey Rate limit on a generic key. Only one of genericKey, sourceCluster, destinationCluster, requestHeaders, remoteAddress, headerValueMatch, or metadata can be set.
headerValueMatch .ratelimit.api.solo.io.Action.HeaderValueMatch Rate limit on the existence of request headers. Only one of headerValueMatch, sourceCluster, destinationCluster, requestHeaders, remoteAddress, genericKey, or metadata can be set.
metadata .ratelimit.api.solo.io.MetaData Rate limit on metadata. Only one of metadata, sourceCluster, destinationCluster, requestHeaders, remoteAddress, genericKey, or headerValueMatch can be set.

SourceCluster

The following descriptor entry is appended to the descriptor:

  ("source_cluster", "<local service cluster>")

is derived from the :option:--service-cluster option.
Field Type Description

DestinationCluster

The following descriptor entry is appended to the descriptor:

  ("destination_cluster", "<routed target cluster>")

Once a request matches against a route table rule, a routed cluster is determined by one of the following route table configuration (envoy_api_msg_RouteConfiguration) settings:
Field Type Description

RequestHeaders

The following descriptor entry is appended when a header contains a key that matches the header_name:

  ("<descriptor_key>", "<header_value_queried_from_header>")

"headerName": string
"descriptorKey": string
Field Type Description
headerName string The header name to be queried from the request headers. The header’s value is used to populate the value of the descriptor entry for the descriptor_key.
descriptorKey string The key to use in the descriptor entry.

RemoteAddress

The following descriptor entry is appended to the descriptor and is populated using the trusted address from x-forwarded-for (config_http_conn_man_headers_x-forwarded-for):

  ("remote_address", "<trusted address from x-forwarded-for>")
Field Type Description

GenericKey

The following descriptor entry is appended to the descriptor:

  ("generic_key", "<descriptor_value>")

"descriptorValue": string
Field Type Description
descriptorValue string The value to use in the descriptor entry.

HeaderValueMatch

The following descriptor entry is appended to the descriptor:

  ("header_match", "<descriptor_value>")

"descriptorValue": string
"expectMatch": .google.protobuf.BoolValue
"headers": []ratelimit.api.solo.io.Action.HeaderValueMatch.HeaderMatcher
Field Type Description
descriptorValue string The value to use in the descriptor entry.
expectMatch .google.protobuf.BoolValue If set to true, the action will append a descriptor entry when the request matches the headers. If set to false, the action will append a descriptor entry when the request does not match the headers. The default value is true.
headers []ratelimit.api.solo.io.Action.HeaderValueMatch.HeaderMatcher Specifies a set of headers that the rate limit action should match on. The action will check the request’s headers against all the specified headers in the config. A match will happen if all the headers in the config are present in the request with the same values (or based on presence if the value field is not in the config).

HeaderMatcher

"name": string
"exactMatch": string
"regexMatch": string
"rangeMatch": .ratelimit.api.solo.io.Action.HeaderValueMatch.HeaderMatcher.Int64Range
"presentMatch": bool
"prefixMatch": string
"suffixMatch": string
"invertMatch": bool
Field Type Description
name string Specifies the name of the header in the request.
exactMatch string If specified, header match will be performed based on the value of the header. Only one of exactMatch, regexMatch, rangeMatch, presentMatch, prefixMatch, or suffixMatch can be set.
regexMatch string If specified, this regex string is a regular expression rule which implies the entire request header value must match the regex. The rule will not match if only a subsequence of the request header value matches the regex. The regex grammar used in the value field is defined (here)[https://en.cppreference.com/w/cpp/regex/ecmascript]. Examples: * The regex \d{3} matches the value 123 * The regex \d{3} does not match the value 1234 * The regex \d{3} does not match the value 123.456. Only one of regexMatch, exactMatch, rangeMatch, presentMatch, prefixMatch, or suffixMatch can be set.
rangeMatch .ratelimit.api.solo.io.Action.HeaderValueMatch.HeaderMatcher.Int64Range If specified, header match will be performed based on range. The rule will match if the request header value is within this range. The entire request header value must represent an integer in base 10 notation: consisting of an optional plus or minus sign followed by a sequence of digits. The rule will not match if the header value does not represent an integer. Match will fail for empty values, floating point numbers or if only a subsequence of the header value is an integer. Examples: * For range [-10,0), route will match for header value -1, but not for 0, “somestring”, 10.9, “-1somestring”. Only one of rangeMatch, exactMatch, regexMatch, presentMatch, prefixMatch, or suffixMatch can be set.
presentMatch bool If specified, header match will be performed based on whether the header is in the request. Only one of presentMatch, exactMatch, regexMatch, rangeMatch, prefixMatch, or suffixMatch can be set.
prefixMatch string If specified, header match will be performed based on the prefix of the header value. Note: empty prefix is not allowed, please use present_match instead. Examples: * The prefix abcd matches the value abcdxyz, but not for abcxyz. Only one of prefixMatch, exactMatch, regexMatch, rangeMatch, presentMatch, or suffixMatch can be set.
suffixMatch string If specified, header match will be performed based on the suffix of the header value. Note: empty suffix is not allowed, please use present_match instead. Examples: * The suffix abcd matches the value xyzabcd, but not for xyzbcd. Only one of suffixMatch, exactMatch, regexMatch, rangeMatch, presentMatch, or prefixMatch can be set.
invertMatch bool If specified, the match result will be inverted before checking. Defaults to false. Examples: * The regex \d{3} does not match the value 1234, so it will match when inverted. * The range [-10,0) will match the value -1, so it will not match when inverted.

Int64Range

Specifies the int64 start and end of the range using half-open interval semantics [start, end).

"start": int
"end": int
Field Type Description
start int start of the range (inclusive).
end int end of the range (exclusive).

MetaData

The following descriptor entry is appended when the metadata contains a key value: ("<descriptor_key>", “<value_queried_from_metadata>")

"descriptorKey": string
"metadataKey": .ratelimit.api.solo.io.MetaData.MetadataKey
"defaultValue": string
"source": .ratelimit.api.solo.io.MetaData.Source
Field Type Description
descriptorKey string Required. The key to use in the descriptor entry.
metadataKey .ratelimit.api.solo.io.MetaData.MetadataKey Required. Metadata struct that defines the key and path to retrieve the string value. A match will only happen if the value in the metadata is of type string.
defaultValue string An optional value to use if metadata_key is empty. If not set and no value is present under the metadata_key then no descriptor is generated.
source .ratelimit.api.solo.io.MetaData.Source Source of metadata.

MetadataKey

MetadataKey provides a general interface using key and path to retrieve value from Metadata.

For example, for the following Metadata:

filter_metadata:
  envoy.xxx:
    prop:
      foo: bar
      xyz:
        hello: envoy

The following MetadataKey will retrieve a string value “bar” from the Metadata.

key: envoy.xxx
path:
- key: prop
- key: foo

"key": string
"path": []ratelimit.api.solo.io.MetaData.MetadataKey.PathSegment
Field Type Description
key string Required. The key name of Metadata to retrieve the Struct from the metadata. Typically, it represents a builtin subsystem or custom extension.
path []ratelimit.api.solo.io.MetaData.MetadataKey.PathSegment Must have at least one element. The path to retrieve the Value from the Struct. It can be a prefix or a full path, e.g. [prop, xyz] for a struct or [prop, foo] for a string in the example, which depends on the particular scenario. Note: Due to that only the key type segment is supported, the path can not specify a list unless the list is the last segment.

PathSegment

Specifies the segment in a path to retrieve value from Metadata. Currently it is only supported to specify the key, i.e. field name, as one segment of a path.

"key": string
Field Type Description
key string Required. If specified, use the key to retrieve the value in a Struct.

Source

Name Description
DYNAMIC Query dynamic metadata.
ROUTE_ENTRY Query route entry metadata.

Override

Copied directly from envoy https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-ratelimit-override

"dynamicMetadata": .ratelimit.api.solo.io.Override.DynamicMetadata
Field Type Description
dynamicMetadata .ratelimit.api.solo.io.Override.DynamicMetadata Limit override from dynamic metadata.

DynamicMetadata

Fetches the override from the dynamic metadata.

"metadataKey": .ratelimit.api.solo.io.MetaData.MetadataKey
Field Type Description
metadataKey .ratelimit.api.solo.io.MetaData.MetadataKey Metadata struct that defines the key and path to retrieve the struct value. The value must be a struct containing an integer “requests_per_unit” property and a “unit” property with a value parseable to :ref:RateLimitUnit enum <envoy_v3_api_enum_type.v3.RateLimitUnit>.