local_rate_limit.proto

syntax = "proto3";

package envoy.extensions.filters.http.local_ratelimit.v3;

import "envoy/config/core/v3/base.proto";
import "envoy/type/v3/http_status.proto";
import "envoy/type/v3/token_bucket.proto";

import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.extensions.filters.http.local_ratelimit.v3";
option java_outer_classname = "LocalRateLimitProto";
option java_multiple_files = true;
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Local Rate limit]
// Local Rate limit :ref:`configuration overview <config_http_filters_local_rate_limit>`.
// [#extension: envoy.filters.http.local_ratelimit]

// [#next-free-field: 7]
message LocalRateLimit {
  // The human readable prefix to use when emitting stats.
  string stat_prefix = 1 [(validate.rules).string = {min_len: 1}];

  // This field allows for a custom HTTP response status code to the downstream client when
  // the request has been rate limited.
  // Defaults to 429 (TooManyRequests).
  //
  // .. note::
  //   If this is set to < 400, 429 will be used instead.
  type.v3.HttpStatus status = 2;

  // The token bucket configuration to use for rate limiting requests that are processed by this
  // filter. Each request processed by the filter consumes a single token. If the token is available,
  // the request will be allowed. If no tokens are available, the request will receive the configured
  // rate limit status.
  //
  // .. note::
  //   It's fine for the token bucket to be unset for the global configuration since the rate limit
  //   can be applied at a the virtual host or route level. Thus, the token bucket must be set
  //   for the per route configuration otherwise the config will be rejected.
  //
  // .. note::
  //   When using per route configuration, the bucket becomes unique to that route.
  //
  // .. note::
  //   In the current implementation the token bucket's :ref:`fill_interval
  //   <envoy_api_field_type.v3.TokenBucket.fill_interval>` must be >= 50ms to avoid too aggressive
  //   refills.
  type.v3.TokenBucket token_bucket = 3;

  // If set, this will enable -- but not necessarily enforce -- the rate limit for the given
  // fraction of requests.
  // Defaults to 0% of requests for safety.
  config.core.v3.RuntimeFractionalPercent filter_enabled = 4;

  // If set, this will enforce the rate limit decisions for the given fraction of requests.
  //
  // Note: this only applies to the fraction of enabled requests.
  //
  // Defaults to 0% of requests for safety.
  config.core.v3.RuntimeFractionalPercent filter_enforced = 5;

  // Specifies a list of HTTP headers that should be added to each response for requests that
  // have been rate limited.
  repeated config.core.v3.HeaderValueOption response_headers_to_add = 6
      [(validate.rules).repeated = {max_items: 10}];
}