1syntax = "proto3";
2
3package envoy.service.ratelimit.v2;
4
5import "envoy/api/v2/core/base.proto";
6import "envoy/api/v2/ratelimit/ratelimit.proto";
7
8import "udpa/annotations/migrate.proto";
9import "udpa/annotations/status.proto";
10
11option java_package = "io.envoyproxy.envoy.service.ratelimit.v2";
12option java_outer_classname = "RlsProto";
13option java_multiple_files = true;
14option go_package = "github.com/envoyproxy/go-control-plane/envoy/service/ratelimit/v2;ratelimitv2";
15option java_generic_services = true;
16option (udpa.annotations.file_status).package_version_status = FROZEN;
17
18// [#protodoc-title: Rate Limit Service (RLS)]
19
20service RateLimitService {
21 // Determine whether rate limiting should take place.
22 rpc ShouldRateLimit(RateLimitRequest) returns (RateLimitResponse) {
23 }
24}
25
26// Main message for a rate limit request. The rate limit service is designed to be fully generic
27// in the sense that it can operate on arbitrary hierarchical key/value pairs. The loaded
28// configuration will parse the request and find the most specific limit to apply. In addition,
29// a RateLimitRequest can contain multiple "descriptors" to limit on. When multiple descriptors
30// are provided, the server will limit on *ALL* of them and return an OVER_LIMIT response if any
31// of them are over limit. This enables more complex application level rate limiting scenarios
32// if desired.
33message RateLimitRequest {
34 // All rate limit requests must specify a domain. This enables the configuration to be per
35 // application without fear of overlap. E.g., "envoy".
36 string domain = 1;
37
38 // All rate limit requests must specify at least one RateLimitDescriptor. Each descriptor is
39 // processed by the service (see below). If any of the descriptors are over limit, the entire
40 // request is considered to be over limit.
41 repeated api.v2.ratelimit.RateLimitDescriptor descriptors = 2;
42
43 // Rate limit requests can optionally specify the number of hits a request adds to the matched
44 // limit. If the value is not set in the message, a request increases the matched limit by 1.
45 uint32 hits_addend = 3;
46}
47
48// A response from a ShouldRateLimit call.
49message RateLimitResponse {
50 enum Code {
51 // The response code is not known.
52 UNKNOWN = 0;
53
54 // The response code to notify that the number of requests are under limit.
55 OK = 1;
56
57 // The response code to notify that the number of requests are over limit.
58 OVER_LIMIT = 2;
59 }
60
61 // Defines an actual rate limit in terms of requests per unit of time and the unit itself.
62 message RateLimit {
63 enum Unit {
64 // The time unit is not known.
65 UNKNOWN = 0;
66
67 // The time unit representing a second.
68 SECOND = 1;
69
70 // The time unit representing a minute.
71 MINUTE = 2;
72
73 // The time unit representing an hour.
74 HOUR = 3;
75
76 // The time unit representing a day.
77 DAY = 4;
78 }
79
80 // A name or description of this limit.
81 string name = 3;
82
83 // The number of requests per unit of time.
84 uint32 requests_per_unit = 1;
85
86 // The unit of time.
87 Unit unit = 2;
88 }
89
90 message DescriptorStatus {
91 // The response code for an individual descriptor.
92 Code code = 1;
93
94 // The current limit as configured by the server. Useful for debugging, etc.
95 RateLimit current_limit = 2;
96
97 // The limit remaining in the current time unit.
98 uint32 limit_remaining = 3;
99 }
100
101 // The overall response code which takes into account all of the descriptors that were passed
102 // in the RateLimitRequest message.
103 Code overall_code = 1;
104
105 // A list of DescriptorStatus messages which matches the length of the descriptor list passed
106 // in the RateLimitRequest. This can be used by the caller to determine which individual
107 // descriptors failed and/or what the currently configured limits are for all of them.
108 repeated DescriptorStatus statuses = 2;
109
110 // A list of headers to add to the response
111 repeated api.v2.core.HeaderValue headers = 3
112 [(udpa.annotations.field_migrate).rename = "response_headers_to_add"];
113
114 // A list of headers to add to the request when forwarded
115 repeated api.v2.core.HeaderValue request_headers_to_add = 4;
116}
View as plain text