|
| 1 | +syntax = "proto3"; |
| 2 | + |
| 3 | +package envoy.extensions.filters.http.local_ratelimit.v3; |
| 4 | + |
| 5 | +import "envoy/config/core/v3/base.proto"; |
| 6 | +import "envoy/extensions/common/ratelimit/v3/ratelimit.proto"; |
| 7 | +import "envoy/type/v3/http_status.proto"; |
| 8 | +import "envoy/type/v3/token_bucket.proto"; |
| 9 | + |
| 10 | +import "udpa/annotations/status.proto"; |
| 11 | +import "validate/validate.proto"; |
| 12 | + |
| 13 | +option java_package = "io.envoyproxy.envoy.extensions.filters.http.local_ratelimit.v3"; |
| 14 | +option java_outer_classname = "LocalRateLimitProto"; |
| 15 | +option java_multiple_files = true; |
| 16 | +option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/local_ratelimit/v3;local_ratelimitv3"; |
| 17 | +option (udpa.annotations.file_status).package_version_status = ACTIVE; |
| 18 | + |
| 19 | +// [#protodoc-title: Local Rate limit] |
| 20 | +// Local Rate limit :ref:`configuration overview <config_http_filters_local_rate_limit>`. |
| 21 | +// [#extension: envoy.filters.http.local_ratelimit] |
| 22 | + |
| 23 | +// [#next-free-field: 14] |
| 24 | +message LocalRateLimit { |
| 25 | + // The human readable prefix to use when emitting stats. |
| 26 | + string stat_prefix = 1 [(validate.rules).string = {min_len: 1}]; |
| 27 | + |
| 28 | + // This field allows for a custom HTTP response status code to the downstream client when |
| 29 | + // the request has been rate limited. |
| 30 | + // Defaults to 429 (TooManyRequests). |
| 31 | + // |
| 32 | + // .. note:: |
| 33 | + // If this is set to < 400, 429 will be used instead. |
| 34 | + type.v3.HttpStatus status = 2; |
| 35 | + |
| 36 | + // The token bucket configuration to use for rate limiting requests that are processed by this |
| 37 | + // filter. Each request processed by the filter consumes a single token. If the token is available, |
| 38 | + // the request will be allowed. If no tokens are available, the request will receive the configured |
| 39 | + // rate limit status. |
| 40 | + // |
| 41 | + // .. note:: |
| 42 | + // It's fine for the token bucket to be unset for the global configuration since the rate limit |
| 43 | + // can be applied at a the virtual host or route level. Thus, the token bucket must be set |
| 44 | + // for the per route configuration otherwise the config will be rejected. |
| 45 | + // |
| 46 | + // .. note:: |
| 47 | + // When using per route configuration, the bucket becomes unique to that route. |
| 48 | + // |
| 49 | + // .. note:: |
| 50 | + // In the current implementation the token bucket's :ref:`fill_interval |
| 51 | + // <envoy_v3_api_field_type.v3.TokenBucket.fill_interval>` must be >= 50ms to avoid too aggressive |
| 52 | + // refills. |
| 53 | + type.v3.TokenBucket token_bucket = 3; |
| 54 | + |
| 55 | + // If set, this will enable -- but not necessarily enforce -- the rate limit for the given |
| 56 | + // fraction of requests. |
| 57 | + // Defaults to 0% of requests for safety. |
| 58 | + config.core.v3.RuntimeFractionalPercent filter_enabled = 4; |
| 59 | + |
| 60 | + // If set, this will enforce the rate limit decisions for the given fraction of requests. |
| 61 | + // |
| 62 | + // Note: this only applies to the fraction of enabled requests. |
| 63 | + // |
| 64 | + // Defaults to 0% of requests for safety. |
| 65 | + config.core.v3.RuntimeFractionalPercent filter_enforced = 5; |
| 66 | + |
| 67 | + // Specifies a list of HTTP headers that should be added to each request that |
| 68 | + // has been rate limited and is also forwarded upstream. This can only occur when the |
| 69 | + // filter is enabled but not enforced. |
| 70 | + repeated config.core.v3.HeaderValueOption request_headers_to_add_when_not_enforced = 10 |
| 71 | + [(validate.rules).repeated = {max_items: 10}]; |
| 72 | + |
| 73 | + // Specifies a list of HTTP headers that should be added to each response for requests that |
| 74 | + // have been rate limited. This occurs when the filter is enabled and fully enforced. |
| 75 | + repeated config.core.v3.HeaderValueOption response_headers_to_add = 6 |
| 76 | + [(validate.rules).repeated = {max_items: 10}]; |
| 77 | + |
| 78 | + // The rate limit descriptor list to use in the local rate limit to override |
| 79 | + // on. The rate limit descriptor is selected by the first full match from the |
| 80 | + // request descriptors. |
| 81 | + // |
| 82 | + // Example on how to use :ref:`this <config_http_filters_local_rate_limit_descriptors>`. |
| 83 | + // |
| 84 | + // .. note:: |
| 85 | + // |
| 86 | + // In the current implementation the descriptor's token bucket :ref:`fill_interval |
| 87 | + // <envoy_v3_api_field_type.v3.TokenBucket.fill_interval>` must be a multiple |
| 88 | + // global :ref:`token bucket's<envoy_v3_api_field_extensions.filters.http.local_ratelimit.v3.LocalRateLimit.token_bucket>` fill interval. |
| 89 | + // |
| 90 | + // The descriptors must match verbatim for rate limiting to apply. There is no partial |
| 91 | + // match by a subset of descriptor entries in the current implementation. |
| 92 | + repeated common.ratelimit.v3.LocalRateLimitDescriptor descriptors = 8; |
| 93 | + |
| 94 | + // Specifies the rate limit configurations to be applied with the same |
| 95 | + // stage number. If not set, the default stage number is 0. |
| 96 | + // |
| 97 | + // .. note:: |
| 98 | + // |
| 99 | + // The filter supports a range of 0 - 10 inclusively for stage numbers. |
| 100 | + uint32 stage = 9 [(validate.rules).uint32 = {lte: 10}]; |
| 101 | + |
| 102 | + // Specifies the scope of the rate limiter's token bucket. |
| 103 | + // If set to false, the token bucket is shared across all worker threads, |
| 104 | + // thus the rate limits are applied per Envoy process. |
| 105 | + // If set to true, a token bucket is allocated for each connection. |
| 106 | + // Thus the rate limits are applied per connection thereby allowing |
| 107 | + // one to rate limit requests on a per connection basis. |
| 108 | + // If unspecified, the default value is false. |
| 109 | + bool local_rate_limit_per_downstream_connection = 11; |
| 110 | + |
| 111 | + // Defines the standard version to use for X-RateLimit headers emitted by the filter. |
| 112 | + // |
| 113 | + // Disabled by default. |
| 114 | + common.ratelimit.v3.XRateLimitHeadersRFCVersion enable_x_ratelimit_headers = 12 |
| 115 | + [(validate.rules).enum = {defined_only: true}]; |
| 116 | + |
| 117 | + // Specifies if the local rate limit filter should include the virtual host rate limits. |
| 118 | + common.ratelimit.v3.VhRateLimitsOptions vh_rate_limits = 13 |
| 119 | + [(validate.rules).enum = {defined_only: true}]; |
| 120 | +} |
0 commit comments