-
Notifications
You must be signed in to change notification settings - Fork 4.7k
/
rlqs.proto
251 lines (227 loc) · 12.6 KB
/
rlqs.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
syntax = "proto3";
package envoy.service.rate_limit_quota.v3;
import "envoy/type/v3/ratelimit_strategy.proto";
import "google/protobuf/duration.proto";
import "xds/annotations/v3/status.proto";
import "udpa/annotations/status.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.service.rate_limit_quota.v3";
option java_outer_classname = "RlqsProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/service/rate_limit_quota/v3;rate_limit_quotav3";
option java_generic_services = true;
option (udpa.annotations.file_status).package_version_status = ACTIVE;
option (xds.annotations.v3.file_status).work_in_progress = true;
// [#protodoc-title: Rate Limit Quota Service (RLQS)]
// The Rate Limit Quota Service (RLQS) is a Envoy global rate limiting service that allows to
// delegate rate limit decisions to a remote service. The service will aggregate the usage reports
// from multiple data plane instances, and distribute Rate Limit Assignments to each instance
// based on its business logic. The logic is outside of the scope of the protocol API.
//
// The protocol is designed as a streaming-first API. It utilizes watch-like subscription model.
// The data plane groups requests into Quota Buckets as directed by the filter config,
// and periodically reports them to the RLQS server along with the Bucket identifier, :ref:`BucketId
// <envoy_v3_api_msg_service.rate_limit_quota.v3.BucketId>`. Once RLQS server has collected enough
// reports to make a decision, it'll send back the assignment with the rate limiting instructions.
//
// The first report sent by the data plane is interpreted by the RLQS server as a "watch" request,
// indicating that the data plane instance is interested in receiving further updates for the
// ``BucketId``. From then on, RLQS server may push assignments to this instance at will, even if
// the instance is not sending usage reports. It's the responsibility of the RLQS server
// to determine when the data plane instance didn't send ``BucketId`` reports for too long,
// and to respond with the :ref:`AbandonAction
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction>`,
// indicating that the server has now stopped sending quota assignments for the ``BucketId`` bucket,
// and the data plane instance should :ref:`abandon
// <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.abandon_action>`
// it.
//
// Refer to Rate Limit Quota :ref:`configuration overview <config_http_filters_rate_limit_quota>`
// for further details.
// Defines the Rate Limit Quota Service (RLQS).
service RateLimitQuotaService {
// Main communication channel: the data plane sends usage reports to the RLQS server,
// and the server asynchronously responding with the assignments.
rpc StreamRateLimitQuotas(stream RateLimitQuotaUsageReports)
returns (stream RateLimitQuotaResponse) {
}
}
message RateLimitQuotaUsageReports {
// The usage report for a bucket.
//
// .. note::
// Note that the first report sent for a ``BucketId`` indicates to the RLQS server that
// the RLQS client is subscribing for the future assignments for this ``BucketId``.
message BucketQuotaUsage {
// ``BucketId`` for which request quota usage is reported.
BucketId bucket_id = 1 [(validate.rules).message = {required: true}];
// Time elapsed since the last report.
google.protobuf.Duration time_elapsed = 2 [(validate.rules).duration = {
required: true
gt {}
}];
// Requests the data plane has allowed through.
uint64 num_requests_allowed = 3;
// Requests throttled.
uint64 num_requests_denied = 4;
}
// All quota requests must specify the domain. This enables sharing the quota
// server between different applications without fear of overlap.
// E.g., "envoy".
//
// Should only be provided in the first report, all subsequent messages on the same
// stream are considered to be in the same domain. In case the domain needs to be
// changes, close the stream, and reopen a new one with the different domain.
string domain = 1 [(validate.rules).string = {min_len: 1}];
// A list of quota usage reports. The list is processed by the RLQS server in the same order
// it's provided by the client.
repeated BucketQuotaUsage bucket_quota_usages = 2 [(validate.rules).repeated = {min_items: 1}];
}
message RateLimitQuotaResponse {
// Commands the data plane to apply one of the actions to the bucket with the
// :ref:`bucket_id <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.bucket_id>`.
message BucketAction {
// Quota assignment for the bucket. Configures the rate limiting strategy and the duration
// for the given :ref:`bucket_id
// <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.bucket_id>`.
//
// **Applying the first assignment to the bucket**
//
// Once the data plane receives the ``QuotaAssignmentAction``, it must send the current usage
// report for the bucket, and start rate limiting requests matched into the bucket
// using the strategy configured in the :ref:`rate_limit_strategy
// <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction.rate_limit_strategy>`
// field. The assignment becomes bucket's ``active`` assignment.
//
// **Expiring the assignment**
//
// The duration of the assignment defined in the :ref:`assignment_time_to_live
// <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction.assignment_time_to_live>`
// field. When the duration runs off, the assignment is ``expired``, and no longer ``active``.
// The data plane should stop applying the rate limiting strategy to the bucket, and transition
// the bucket to the "expired assignment" state. This activates the behavior configured in the
// :ref:`expired_assignment_behavior <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.expired_assignment_behavior>`
// field.
//
// **Replacing the assignment**
//
// * If the rate limiting strategy is different from bucket's ``active`` assignment, or
// the current bucket assignment is ``expired``, the data plane must immediately
// end the current assignment, report the bucket usage, and apply the new assignment.
// The new assignment becomes bucket's ``active`` assignment.
// * If the rate limiting strategy is the same as the bucket's ``active`` (not ``expired``)
// assignment, the data plane should extend the duration of the ``active`` assignment
// for the duration of the new assignment provided in the :ref:`assignment_time_to_live
// <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction.assignment_time_to_live>`
// field. The ``active`` assignment is considered unchanged.
message QuotaAssignmentAction {
// A duration after which the assignment is be considered ``expired``. The process of the
// expiration is described :ref:`above
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction>`.
//
// * If unset, the assignment has no expiration date.
// * If set to ``0``, the assignment expires immediately, forcing the client into the
// :ref:`"expired assignment"
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.expired_assignment_behavior_timeout>`
// state. This may be used by the RLQS server in cases when it needs clients to proactively
// fall back to the pre-configured :ref:`ExpiredAssignmentBehavior
// <envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior>`,
// f.e. before the server going into restart.
//
// .. attention::
// Note that :ref:`expiring
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction>`
// the assignment is not the same as :ref:`abandoning
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction>`
// the assignment. While expiring the assignment just transitions the bucket to
// the "expired assignment" state; abandoning the assignment completely erases
// the bucket from the data plane memory, and stops the usage reports.
google.protobuf.Duration assignment_time_to_live = 2 [(validate.rules).duration = {gte {}}];
// Configures the local rate limiter for the request matched to the bucket.
// If not set, allow all requests.
type.v3.RateLimitStrategy rate_limit_strategy = 3;
}
// Abandon action for the bucket. Indicates that the RLQS server will no longer be
// sending updates for the given :ref:`bucket_id
// <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.bucket_id>`.
//
// If no requests are reported for a bucket, after some time the server considers the bucket
// inactive. The server stops tracking the bucket, and instructs the the data plane to abandon
// the bucket via this message.
//
// **Abandoning the assignment**
//
// The data plane is to erase the bucket (including its usage data) from the memory.
// It should stop tracking the bucket, and stop reporting its usage. This effectively resets
// the data plane to the state prior to matching the first request into the bucket.
//
// **Restarting the subscription**
//
// If a new request is matched into a bucket previously abandoned, the data plane must behave
// as if it has never tracked the bucket, and it's the first request matched into it:
//
// 1. The process of :ref:`subscription and reporting
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.reporting_interval>`
// starts from the beginning.
//
// 2. The bucket transitions to the :ref:`"no assignment"
// <envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.no_assignment_behavior>`
// state.
//
// 3. Once the new assignment is received, it's applied per
// "Applying the first assignment to the bucket" section of the :ref:`QuotaAssignmentAction
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction>`.
message AbandonAction {
}
// ``BucketId`` for which request the action is applied.
BucketId bucket_id = 1 [(validate.rules).message = {required: true}];
oneof bucket_action {
option (validate.required) = true;
// Apply the quota assignment to the bucket.
//
// Commands the data plane to apply a rate limiting strategy to the bucket.
// The process of applying and expiring the rate limiting strategy is detailed in the
// :ref:`QuotaAssignmentAction
// <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction>`
// message.
QuotaAssignmentAction quota_assignment_action = 2;
// Abandon the bucket.
//
// Commands the data plane to abandon the bucket.
// 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.
AbandonAction abandon_action = 3;
}
}
// An ordered list of actions to be applied to the buckets. The actions are applied in the
// given order, from top to bottom.
repeated BucketAction bucket_action = 1 [(validate.rules).repeated = {min_items: 1}];
}
// The identifier for the bucket. Used to match the bucket between the control plane (RLQS server),
// and the data plane (RLQS client), f.e.:
//
// * the data plane sends a usage report for requests matched into the bucket with ``BucketId``
// to the control plane
// * the control plane sends an assignment for the bucket with ``BucketId`` to the data plane
// Bucket ID.
//
// Example:
//
// .. validated-code-block:: yaml
// :type-name: envoy.service.rate_limit_quota.v3.BucketId
//
// bucket:
// name: my_bucket
// env: staging
//
// .. note::
// The order of ``BucketId`` keys do not matter. Buckets ``{ a: 'A', b: 'B' }`` and
// ``{ b: 'B', a: 'A' }`` are identical.
message BucketId {
map<string, string> bucket = 1 [(validate.rules).map = {
min_pairs: 1
keys {string {min_len: 1}}
values {string {min_len: 1}}
}];
}