1syntax = "proto3";
2
3package envoy.service.ratelimit.v3;
4
5import "envoy/config/core/v3/base.proto";
6import "envoy/extensions/common/ratelimit/v3/ratelimit.proto";
7
8import "google/protobuf/duration.proto";
9import "google/protobuf/struct.proto";
10
11import "udpa/annotations/status.proto";
12import "udpa/annotations/versioning.proto";
13import "validate/validate.proto";
14
15option java_package = "io.envoyproxy.envoy.service.ratelimit.v3";
16option java_outer_classname = "RlsProto";
17option java_multiple_files = true;
18option java_generic_services = true;
19option (udpa.annotations.file_status).package_version_status = ACTIVE;
20
21// [#protodoc-title: Rate Limit Service (RLS)]
22
23service RateLimitService {
24 // For use_alpha to work as expected, we need to convince
25 // proto_sync.py that the legacy package is the previous version of
26 // either this package or the v2 package. And to do that, you'd
27 // "normally" use the
28 // "(udpa.annotations.versioning).previous_message_type" option; but
29 // we don't have a 'message' to put it on, we only have a 'service'.
30 // Fortunately, proto_sync.py's parser is sloppy, and we can fool it
31 // with a comment:
32 //
33 // previous_message_type = "pb.lyft.ratelimit.RateLimitService";
34 //
35 // Now, we'd also "normally" do that in the v2 package, not here.
36 // But, because the legacy package imports the v2 package, that'd
37 // cause a cycle.
38 //
39 // The lesson is that the "have legacy be an alias for v2 instead of
40 // duplicating the files" thing we did was a bad thing to do.
41
42 // Determine whether rate limiting should take place.
43 rpc ShouldRateLimit(RateLimitRequest) returns (RateLimitResponse) {
44 }
45}
46
47// Main message for a rate limit request. The rate limit service is designed to be fully generic
48// in the sense that it can operate on arbitrary hierarchical key/value pairs. The loaded
49// configuration will parse the request and find the most specific limit to apply. In addition,
50// a RateLimitRequest can contain multiple "descriptors" to limit on. When multiple descriptors
51// are provided, the server will limit on *ALL* of them and return an OVER_LIMIT response if any
52// of them are over limit. This enables more complex application level rate limiting scenarios
53// if desired.
54message RateLimitRequest {
55 option (udpa.annotations.versioning).previous_message_type =
56 "envoy.service.ratelimit.v2.RateLimitRequest";
57
58 // All rate limit requests must specify a domain. This enables the configuration to be per
59 // application without fear of overlap. E.g., "envoy".
60 string domain = 1;
61
62 // All rate limit requests must specify at least one RateLimitDescriptor. Each descriptor is
63 // processed by the service (see below). If any of the descriptors are over limit, the entire
64 // request is considered to be over limit.
65 repeated envoy.extensions.common.ratelimit.v3.RateLimitDescriptor descriptors = 2;
66
67 // Rate limit requests can optionally specify the number of hits a request adds to the matched
68 // limit. If the value is not set in the message, a request increases the matched limit by 1.
69 uint32 hits_addend = 3;
70}
71
72// A response from a ShouldRateLimit call.
73// [#next-free-field: 7]
74message RateLimitResponse {
75 option (udpa.annotations.versioning).previous_message_type =
76 "envoy.service.ratelimit.v2.RateLimitResponse";
77
78 enum Code {
79 // The response code is not known.
80 UNKNOWN = 0;
81
82 // The response code to notify that the number of requests are under limit.
83 OK = 1;
84
85 // The response code to notify that the number of requests are over limit.
86 OVER_LIMIT = 2;
87 }
88
89 // Defines an actual rate limit in terms of requests per unit of time and the unit itself.
90 message RateLimit {
91 option (udpa.annotations.versioning).previous_message_type =
92 "envoy.service.ratelimit.v2.RateLimitResponse.RateLimit";
93
94 // Identifies the unit of of time for rate limit.
95 // [#comment: replace by envoy/type/v3/ratelimit_unit.proto in v4]
96 enum Unit {
97 // The time unit is not known.
98 UNKNOWN = 0;
99
100 // The time unit representing a second.
101 SECOND = 1;
102
103 // The time unit representing a minute.
104 MINUTE = 2;
105
106 // The time unit representing an hour.
107 HOUR = 3;
108
109 // The time unit representing a day.
110 DAY = 4;
111 }
112
113 // A name or description of this limit.
114 string name = 3;
115
116 // The number of requests per unit of time.
117 uint32 requests_per_unit = 1;
118
119 // The unit of time.
120 Unit unit = 2;
121 }
122
123 message DescriptorStatus {
124 option (udpa.annotations.versioning).previous_message_type =
125 "envoy.service.ratelimit.v2.RateLimitResponse.DescriptorStatus";
126
127 // The response code for an individual descriptor.
128 Code code = 1;
129
130 // The current limit as configured by the server. Useful for debugging, etc.
131 RateLimit current_limit = 2;
132
133 // The limit remaining in the current time unit.
134 uint32 limit_remaining = 3;
135
136 // Duration until reset of the current limit window.
137 google.protobuf.Duration duration_until_reset = 4;
138 }
139
140 // The overall response code which takes into account all of the descriptors that were passed
141 // in the RateLimitRequest message.
142 Code overall_code = 1;
143
144 // A list of DescriptorStatus messages which matches the length of the descriptor list passed
145 // in the RateLimitRequest. This can be used by the caller to determine which individual
146 // descriptors failed and/or what the currently configured limits are for all of them.
147 repeated DescriptorStatus statuses = 2;
148
149 // A list of headers to add to the response
150 repeated config.core.v3.HeaderValue response_headers_to_add = 3;
151
152 // A list of headers to add to the request when forwarded
153 repeated config.core.v3.HeaderValue request_headers_to_add = 4;
154
155 // A response body to send to the downstream client when the response code is not OK.
156 bytes raw_body = 5;
157
158 // Optional response metadata that will be emitted as dynamic metadata to be consumed by the next
159 // filter. This metadata lives in a namespace specified by the canonical name of extension filter
160 // that requires it:
161 //
162 // - :ref:`envoy.filters.http.ratelimit <config_http_filters_ratelimit_dynamic_metadata>` for HTTP filter.
163 // - :ref:`envoy.filters.network.ratelimit <config_network_filters_ratelimit_dynamic_metadata>` for network filter.
164 // - :ref:`envoy.filters.thrift.rate_limit <config_thrift_filters_rate_limit_dynamic_metadata>` for Thrift filter.
165 google.protobuf.Struct dynamic_metadata = 6;
166}
View as plain text