1syntax = "proto3";
2
3package envoy.extensions.common.ratelimit.v3;
4
5import "envoy/type/v3/ratelimit_unit.proto";
6
7import "udpa/annotations/status.proto";
8import "udpa/annotations/versioning.proto";
9import "validate/validate.proto";
10
11option java_package = "io.envoyproxy.envoy.extensions.common.ratelimit.v3";
12option java_outer_classname = "RatelimitProto";
13option java_multiple_files = true;
14option (udpa.annotations.file_status).package_version_status = ACTIVE;
15
16// [#protodoc-title: Common rate limit components]
17
18// A RateLimitDescriptor is a list of hierarchical entries that are used by the service to
19// determine the final rate limit key and overall allowed limit. Here are some examples of how
20// they might be used for the domain "envoy".
21//
22// .. code-block:: cpp
23//
24// ["authenticated": "false"], ["remote_address": "10.0.0.1"]
25//
26// What it does: Limits all unauthenticated traffic for the IP address 10.0.0.1. The
27// configuration supplies a default limit for the *remote_address* key. If there is a desire to
28// raise the limit for 10.0.0.1 or block it entirely it can be specified directly in the
29// configuration.
30//
31// .. code-block:: cpp
32//
33// ["authenticated": "false"], ["path": "/foo/bar"]
34//
35// What it does: Limits all unauthenticated traffic globally for a specific path (or prefix if
36// configured that way in the service).
37//
38// .. code-block:: cpp
39//
40// ["authenticated": "false"], ["path": "/foo/bar"], ["remote_address": "10.0.0.1"]
41//
42// What it does: Limits unauthenticated traffic to a specific path for a specific IP address.
43// Like (1) we can raise/block specific IP addresses if we want with an override configuration.
44//
45// .. code-block:: cpp
46//
47// ["authenticated": "true"], ["client_id": "foo"]
48//
49// What it does: Limits all traffic for an authenticated client "foo"
50//
51// .. code-block:: cpp
52//
53// ["authenticated": "true"], ["client_id": "foo"], ["path": "/foo/bar"]
54//
55// What it does: Limits traffic to a specific path for an authenticated client "foo"
56//
57// The idea behind the API is that (1)/(2)/(3) and (4)/(5) can be sent in 1 request if desired.
58// This enables building complex application scenarios with a generic backend.
59//
60// Optionally the descriptor can contain a limit override under a "limit" key, that specifies
61// the number of requests per unit to use instead of the number configured in the
62// rate limiting service.
63message RateLimitDescriptor {
64 option (udpa.annotations.versioning).previous_message_type =
65 "envoy.api.v2.ratelimit.RateLimitDescriptor";
66
67 message Entry {
68 option (udpa.annotations.versioning).previous_message_type =
69 "envoy.api.v2.ratelimit.RateLimitDescriptor.Entry";
70
71 // Descriptor key.
72 string key = 1 [(validate.rules).string = {min_len: 1}];
73
74 // Descriptor value.
75 string value = 2 [(validate.rules).string = {min_len: 1}];
76 }
77
78 // Override rate limit to apply to this descriptor instead of the limit
79 // configured in the rate limit service. See :ref:`rate limit override
80 // <config_http_filters_rate_limit_rate_limit_override>` for more information.
81 message RateLimitOverride {
82 // The number of requests per unit of time.
83 uint32 requests_per_unit = 1;
84
85 // The unit of time.
86 type.v3.RateLimitUnit unit = 2 [(validate.rules).enum = {defined_only: true}];
87 }
88
89 // Descriptor entries.
90 repeated Entry entries = 1 [(validate.rules).repeated = {min_items: 1}];
91
92 // Optional rate limit override to supply to the ratelimit service.
93 RateLimitOverride limit = 2;
94}
View as plain text