/
rate_limit_quota.proto
418 lines (383 loc) · 18.8 KB
/
rate_limit_quota.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
syntax = "proto3";
package envoy.extensions.filters.http.rate_limit_quota.v3;
import "envoy/config/core/v3/base.proto";
import "envoy/config/core/v3/extension.proto";
import "envoy/config/core/v3/grpc_service.proto";
import "envoy/type/v3/http_status.proto";
import "envoy/type/v3/ratelimit_strategy.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "google/rpc/status.proto";
import "xds/annotations/v3/status.proto";
import "xds/type/matcher/v3/matcher.proto";
import "udpa/annotations/status.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.extensions.filters.http.rate_limit_quota.v3";
option java_outer_classname = "RateLimitQuotaProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/rate_limit_quota/v3;rate_limit_quotav3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;
option (xds.annotations.v3.file_status).work_in_progress = true;
// [#protodoc-title: Rate Limit Quota]
// Rate Limit Quota :ref:`configuration overview <config_http_filters_rate_limit_quota>`.
// [#extension: envoy.filters.http.rate_limit_quota]
// Configures the Rate Limit Quota filter.
//
// Can be overridden in the per-route and per-host configurations.
// The more specific definition completely overrides the less specific definition.
// [#next-free-field: 7]
message RateLimitQuotaFilterConfig {
// Configures the gRPC Rate Limit Quota Service (RLQS) RateLimitQuotaService.
config.core.v3.GrpcService rlqs_server = 1 [(validate.rules).message = {required: true}];
// The application domain to use when calling the service. This enables sharing the quota
// server between different applications without fear of overlap.
// E.g., "envoy".
string domain = 2 [(validate.rules).string = {min_len: 1}];
// The match tree to use for grouping incoming requests into buckets.
//
// Example:
//
// .. validated-code-block:: yaml
// :type-name: xds.type.matcher.v3.Matcher
//
// matcher_list:
// matchers:
// # Assign requests with header['env'] set to 'staging' to the bucket { name: 'staging' }
// - predicate:
// single_predicate:
// input:
// typed_config:
// '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
// header_name: env
// value_match:
// exact: staging
// on_match:
// action:
// typed_config:
// '@type': type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings
// bucket_id_builder:
// bucket_id_builder:
// name:
// string_value: staging
//
// # Assign requests with header['user_group'] set to 'admin' to the bucket { acl: 'admin_users' }
// - predicate:
// single_predicate:
// input:
// typed_config:
// '@type': type.googleapis.com/xds.type.matcher.v3.HttpAttributesCelMatchInput
// custom_match:
// typed_config:
// '@type': type.googleapis.com/xds.type.matcher.v3.CelMatcher
// expr_match:
// # Shortened for illustration purposes. Here should be parsed CEL expression:
// # request.headers['user_group'] == 'admin'
// parsed_expr: {}
// on_match:
// action:
// typed_config:
// '@type': type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings
// bucket_id_builder:
// bucket_id_builder:
// acl:
// string_value: admin_users
//
// # Catch-all clause for the requests not matched by any of the matchers.
// # In this example, deny all requests.
// on_no_match:
// action:
// typed_config:
// '@type': type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings
// no_assignment_behavior:
// fallback_rate_limit:
// blanket_rule: DENY_ALL
//
// .. attention::
// The first matched group wins. Once the request is matched into a bucket, matcher
// evaluation ends.
//
// Use ``on_no_match`` field to assign the catch-all bucket. If a request is not matched
// into any bucket, and there's no ``on_no_match`` field configured, the request will be
// ALLOWED by default. It will NOT be reported to the RLQS server.
//
// Refer to :ref:`Unified Matcher API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>`
// documentation for more information on the matcher trees.
xds.type.matcher.v3.Matcher bucket_matchers = 3 [(validate.rules).message = {required: true}];
// If set, this will enable -- but not necessarily enforce -- the rate limit for the given
// fraction of requests.
//
// Defaults to 100% of requests.
config.core.v3.RuntimeFractionalPercent filter_enabled = 4;
// If set, this will enforce the rate limit decisions for the given fraction of requests.
// For requests that are not enforced the filter will still obtain the quota and include it
// in the load computation, however the request will always be allowed regardless of the outcome
// of quota application. This allows validation or testing of the rate limiting service
// infrastructure without disrupting existing traffic.
//
// Note: this only applies to the fraction of enabled requests.
//
// Defaults to 100% of requests.
config.core.v3.RuntimeFractionalPercent filter_enforced = 5;
// Specifies a list of HTTP headers that should be added to each request that
// has been rate limited and is also forwarded upstream. This can only occur when the
// filter is enabled but not enforced.
repeated config.core.v3.HeaderValueOption request_headers_to_add_when_not_enforced = 6
[(validate.rules).repeated = {max_items: 10}];
}
// Per-route and per-host configuration overrides. The more specific definition completely
// overrides the less specific definition.
message RateLimitQuotaOverride {
// The application domain to use when calling the service. This enables sharing the quota
// server between different applications without fear of overlap.
// E.g., "envoy".
//
// If empty, inherits the value from the less specific definition.
string domain = 1;
// The match tree to use for grouping incoming requests into buckets.
//
// If set, fully overrides the bucket matchers provided on the less specific definition.
// If not set, inherits the value from the less specific definition.
//
// See usage example: :ref:`RateLimitQuotaFilterConfig.bucket_matchers
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.bucket_matchers>`.
xds.type.matcher.v3.Matcher bucket_matchers = 2;
}
// Rate Limit Quota Bucket Settings to apply on the successful ``bucket_matchers`` match.
//
// Specify this message in the :ref:`Matcher.OnMatch.action
// <envoy_v3_api_field_.xds.type.matcher.v3.Matcher.OnMatch.action>` field of the
// ``bucket_matchers`` matcher tree to assign the matched requests to the Quota Bucket.
// Usage example: :ref:`RateLimitQuotaFilterConfig.bucket_matchers
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.bucket_matchers>`.
// [#next-free-field: 6]
message RateLimitQuotaBucketSettings {
// Configures the behavior after the first request has been matched to the bucket, and before the
// the RLQS server returns the first quota assignment.
message NoAssignmentBehavior {
oneof no_assignment_behavior {
option (validate.required) = true;
// Apply pre-configured rate limiting strategy until the server sends the first assignment.
type.v3.RateLimitStrategy fallback_rate_limit = 1;
}
}
// Specifies the behavior when the bucket's assignment has expired, and cannot be refreshed for
// any reason.
message ExpiredAssignmentBehavior {
// Reuse the last known quota assignment, effectively extending it for the duration
// specified in the :ref:`expired_assignment_behavior_timeout
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.expired_assignment_behavior_timeout>`
// field.
message ReuseLastAssignment {
}
// Limit the time :ref:`ExpiredAssignmentBehavior
// <envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior>`
// is applied. If the server doesn't respond within this duration:
//
// 1. Selected ``ExpiredAssignmentBehavior`` is no longer applied.
// 2. The bucket is abandoned. The process of abandoning the bucket is described in the
// :ref:`AbandonAction <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction>`
// message.
// 3. If a new request is matched into the bucket that has become abandoned,
// the data plane restarts the subscription to the bucket. The process of restarting the
// subscription is described in the :ref:`AbandonAction
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction>`
// message.
//
// If the field is not set, the ``ExpiredAssignmentBehavior`` time is **not limited**:
// it applies to the bucket until replaced by an ``active`` assignment.
google.protobuf.Duration expired_assignment_behavior_timeout = 1
[(validate.rules).duration = {gt {}}];
oneof expired_assignment_behavior {
option (validate.required) = true;
// Apply the rate limiting strategy to all requests matched into the bucket until the RLQS
// server sends a new assignment, or the :ref:`expired_assignment_behavior_timeout
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.expired_assignment_behavior_timeout>`
// runs out.
type.v3.RateLimitStrategy fallback_rate_limit = 2;
// Reuse the last ``active`` assignment until the RLQS server sends a new assignment, or the
// :ref:`expired_assignment_behavior_timeout
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.expired_assignment_behavior_timeout>`
// runs out.
ReuseLastAssignment reuse_last_assignment = 3;
}
}
// Customize the deny response to the requests over the rate limit.
message DenyResponseSettings {
// HTTP response code to deny for HTTP requests (gRPC excluded).
// Defaults to 429 (:ref:`StatusCode.TooManyRequests<envoy_v3_api_enum_value_type.v3.StatusCode.TooManyRequests>`).
type.v3.HttpStatus http_status = 1;
// HTTP response body used to deny for HTTP requests (gRPC excluded).
// If not set, an empty body is returned.
google.protobuf.BytesValue http_body = 2;
// Configure the deny response for gRPC requests over the rate limit.
// Allows to specify the `RPC status code
// <https://cloud.google.com/natural-language/docs/reference/rpc/google.rpc#google.rpc.Code>`_,
// and the error message.
// Defaults to the Status with the RPC Code ``UNAVAILABLE`` and empty message.
//
// To identify gRPC requests, Envoy checks that the ``Content-Type`` header is
// ``application/grpc``, or one of the various ``application/grpc+`` values.
//
// .. note::
// The HTTP code for a gRPC response is always 200.
google.rpc.Status grpc_status = 3;
// Specifies a list of HTTP headers that should be added to each response for requests that
// have been rate limited. Applies both to plain HTTP, and gRPC requests.
// The headers are added even when the rate limit quota was not enforced.
repeated config.core.v3.HeaderValueOption response_headers_to_add = 4
[(validate.rules).repeated = {max_items: 10}];
}
// ``BucketIdBuilder`` makes it possible to build :ref:`BucketId
// <envoy_v3_api_msg_service.rate_limit_quota.v3.BucketId>` with values substituted
// from the dynamic properties associated with each individual request. See usage examples in
// the docs to :ref:`bucket_id_builder
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.bucket_id_builder>`
// field.
message BucketIdBuilder {
// Produces the value of the :ref:`BucketId
// <envoy_v3_api_msg_service.rate_limit_quota.v3.BucketId>` map.
message ValueBuilder {
oneof value_specifier {
option (validate.required) = true;
// Static string value — becomes the value in the :ref:`BucketId
// <envoy_v3_api_msg_service.rate_limit_quota.v3.BucketId>` map as is.
string string_value = 1;
// Dynamic value — evaluated for each request. Must produce a string output, which becomes
// the value in the :ref:`BucketId <envoy_v3_api_msg_service.rate_limit_quota.v3.BucketId>`
// map. For example, extensions with the ``envoy.matching.http.input`` category can be used.
config.core.v3.TypedExtensionConfig custom_value = 2;
}
}
// The map translated into the ``BucketId`` map.
//
// The ``string key`` of this map and becomes the key of ``BucketId`` map as is.
//
// The ``ValueBuilder value`` for the key can be:
//
// * static ``StringValue string_value`` — becomes the value in the ``BucketId`` map as is.
// * dynamic ``TypedExtensionConfig custom_value`` — evaluated for each request. Must produce
// a string output, which becomes the value in the the ``BucketId`` map.
//
// See usage examples in the docs to :ref:`bucket_id_builder
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.bucket_id_builder>`
// field.
map<string, ValueBuilder> bucket_id_builder = 1 [(validate.rules).map = {min_pairs: 1}];
}
// ``BucketId`` builder.
//
// :ref:`BucketId <envoy_v3_api_msg_service.rate_limit_quota.v3.BucketId>` is a map from
// the string key to the string value which serves as bucket identifier common for on
// the control plane and the data plane.
//
// While ``BucketId`` is always static, ``BucketIdBuilder`` allows to populate map values
// with the dynamic properties associated with the each individual request.
//
// Example 1: static fields only
//
// ``BucketIdBuilder``:
//
// .. validated-code-block:: yaml
// :type-name: envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder
//
// bucket_id_builder:
// name:
// string_value: my_bucket
// hello:
// string_value: world
//
// Produces the following ``BucketId`` for all requests:
//
// .. validated-code-block:: yaml
// :type-name: envoy.service.rate_limit_quota.v3.BucketId
//
// bucket:
// name: my_bucket
// hello: world
//
// Example 2: static and dynamic fields
//
// .. validated-code-block:: yaml
// :type-name: envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder
//
// bucket_id_builder:
// name:
// string_value: my_bucket
// env:
// custom_value:
// typed_config:
// '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
// header_name: environment
//
// In this example, the value of ``BucketId`` key ``env`` is substituted from the ``environment``
// request header.
//
// This is equivalent to the following ``pseudo-code``:
//
// .. code-block:: yaml
//
// name: 'my_bucket'
// env: $header['environment']
//
// For example, the request with the HTTP header ``env`` set to ``staging`` will produce
// the following ``BucketId``:
//
// .. validated-code-block:: yaml
// :type-name: envoy.service.rate_limit_quota.v3.BucketId
//
// bucket:
// name: my_bucket
// env: staging
//
// For the request with the HTTP header ``environment`` set to ``prod``, will produce:
//
// .. validated-code-block:: yaml
// :type-name: envoy.service.rate_limit_quota.v3.BucketId
//
// bucket:
// name: my_bucket
// env: prod
//
// .. note::
// The order of ``BucketId`` keys do not matter. Buckets ``{ a: 'A', b: 'B' }`` and
// ``{ b: 'B', a: 'A' }`` are identical.
//
// If not set, requests will NOT be reported to the server, and will always limited
// according to :ref:`no_assignment_behavior
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.no_assignment_behavior>`
// configuration.
BucketIdBuilder bucket_id_builder = 1;
// The interval at which the data plane (RLQS client) is to report quota usage for this bucket.
//
// When the first request is matched to a bucket with no assignment, the data plane is to report
// the request immediately in the :ref:`RateLimitQuotaUsageReports
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaUsageReports>` message.
// For the RLQS server, this signals that the data plane is now subscribed to
// the quota assignments in this bucket, and will start sending the assignment as described in
// the :ref:`RLQS documentation <envoy_v3_api_file_envoy/service/rate_limit_quota/v3/rlqs.proto>`.
//
// After sending the initial report, the data plane is to continue reporting the bucket usage with
// the internal specified in this field.
// [#comment: 100000000 nanoseconds = 0.1 seconds]
google.protobuf.Duration reporting_interval = 2 [(validate.rules).duration = {
required: true
gt {nanos: 100000000}
}];
// Customize the deny response to the requests over the rate limit.
// If not set, the filter will be configured as if an empty message is set,
// and will behave according to the defaults specified in :ref:`DenyResponseSettings
// <envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings>`.
DenyResponseSettings deny_response_settings = 3;
// Configures the behavior in the "no assignment" state: after the first request has been
// matched to the bucket, and before the the RLQS server returns the first quota assignment.
//
// If not set, the default behavior is to allow all requests.
NoAssignmentBehavior no_assignment_behavior = 4;
// Configures the behavior in the "expired assignment" state: the bucket's assignment has expired,
// and cannot be refreshed.
//
// If not set, the bucket is abandoned when its ``active`` assignment expires.
// The process of abandoning the bucket, and restarting the subscription is described in the
// :ref:`AbandonAction <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction>`
// message.
ExpiredAssignmentBehavior expired_assignment_behavior = 5;
}