-
Notifications
You must be signed in to change notification settings - Fork 439
/
ratelimit.proto
102 lines (90 loc) · 4.31 KB
/
ratelimit.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
syntax = "proto3";
option go_package = "ratelimit";
option cc_generic_services = true;
package pb.lyft.ratelimit;
service RateLimitService {
// Determine whether rate limiting should take place.
rpc ShouldRateLimit (RateLimitRequest) returns (RateLimitResponse) {}
}
// Main message for a rate limit request. The rate limit service is designed to be fully generic
// in the sense that it can operate on arbitrary hierarchical key/value pairs. The loaded
// configuration will parse the request and find the most specific limit to apply. In addition,
// a RateLimitRequest can contain multiple "descriptors" to limit on. When multiple descriptors
// are provided, the server will limit on *ALL* of them and return an OVER_LIMIT response if any
// of them are over limit. This enables more complex application level rate limiting scenarios
// if desired.
message RateLimitRequest {
// All rate limit requests must specify a domain. This enables the configuration to be per
// application without fear of overlap. E.g., "envoy".
string domain = 1;
// All rate limit requests must specify at least one RateLimitDescriptor. Each descriptor is
// processed by the service (see below). If any of the descriptors are over limit, the entire
// request is considered to be over limit.
repeated RateLimitDescriptor descriptors = 2;
// Rate limit requests can optionally specify the number of hits a request adds to the matched limit. If the
// value is not set in the message, a request increases the matched limit by 1.
uint32 hits_addend = 3;
}
// A RateLimitDescriptor is a list of hierarchical entries that are used by the service to
// determine the final rate limit key and overall allowed limit. Here are some examples of how
// they might be used for the domain "envoy".
// 1) ["authenticated": "false"], ["ip_address": "10.0.0.1"]
// What it does: Limits all unauthenticated traffic for the IP address 10.0.0.1. The
// configuration supplies a default limit for the ip_address field. If there is a desire to raise
// the limit for 10.0.0.1 or block it entirely it can be specified directly in the
// configuration.
// 2) ["authenticated": "false"], ["path": "/foo/bar"]
// What it does: Limits all unauthenticated traffic globally for a specific path (or prefix if
// configured that way in the service).
// 3) ["authenticated": "false"], ["path": "/foo/bar"], ["ip_address": "10.0.0.1"]
// What it does: Limits unauthenticated traffic to a specific path for a specific IP address.
// Like (1) we can raise/block specific IP addresses if we want with an override configuration.
// 4) ["authenticated": "true"], ["client_id": "foo"]
// What it does: Limits all traffic for an authenticated client "foo"
// 5) ["authenticated": "true"], ["client_id": "foo"], ["path": "/foo/bar"]
// What it does: Limits traffic to a specific path for an authenticated client "foo"
//
// The idea behind the API is that (1)/(2)/(3) and (4)/(5) can be sent in 1 request if desired.
// This enables building complex application scenarios with a generic backend.
message RateLimitDescriptor {
message Entry {
string key = 1;
string value = 2;
}
repeated Entry entries = 1;
}
// Defines an actual rate limit in terms of requests per unit of time and the unit itself.
message RateLimit {
enum Unit {
UNKNOWN = 0;
SECOND = 1;
MINUTE = 2;
HOUR = 3;
DAY = 4;
}
uint32 requests_per_unit = 1;
Unit unit = 2;
}
// A response from a ShouldRateLimit call.
message RateLimitResponse {
enum Code {
UNKNOWN = 0;
OK = 1;
OVER_LIMIT = 2;
}
message DescriptorStatus {
// The response code for an individual descriptor.
Code code = 1;
// The current limit as configured by the server. Useful for debugging, etc.
RateLimit current_limit = 2;
// The limit remaining in the current time unit.
uint32 limit_remaining = 3;
}
// The overall response code which takes into account all of the descriptors that were passed
// in the RateLimitRequest message.
Code overall_code = 1;
// A list of DescriptorStatus messages which matches the length of the descriptor list passed
// in the RateLimitRequest. This can be used by the caller to determine which individual
// descriptors failed and/or what the currently configured limits are for all of them.
repeated DescriptorStatus statuses = 2;
}