...

Text file src/github.com/datawire/ambassador/v2/api/envoy/service/ratelimit/v3/rls.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/service/ratelimit/v3

     1syntax = "proto3";
     2
     3package envoy.service.ratelimit.v3;
     4
     5import "envoy/config/core/v3/base.proto";
     6import "envoy/extensions/common/ratelimit/v3/ratelimit.proto";
     7
     8import "google/protobuf/duration.proto";
     9import "google/protobuf/struct.proto";
    10
    11import "udpa/annotations/status.proto";
    12import "udpa/annotations/versioning.proto";
    13import "validate/validate.proto";
    14
    15option java_package = "io.envoyproxy.envoy.service.ratelimit.v3";
    16option java_outer_classname = "RlsProto";
    17option java_multiple_files = true;
    18option java_generic_services = true;
    19option (udpa.annotations.file_status).package_version_status = ACTIVE;
    20
    21// [#protodoc-title: Rate Limit Service (RLS)]
    22
    23service RateLimitService {
    24  // For use_alpha to work as expected, we need to convince
    25  // proto_sync.py that the legacy package is the previous version of
    26  // either this package or the v2 package. And to do that, you'd
    27  // "normally" use the
    28  // "(udpa.annotations.versioning).previous_message_type" option; but
    29  // we don't have a 'message' to put it on, we only have a 'service'.
    30  // Fortunately, proto_sync.py's parser is sloppy, and we can fool it
    31  // with a comment:
    32  //
    33  //   previous_message_type = "pb.lyft.ratelimit.RateLimitService";
    34  //
    35  // Now, we'd also "normally" do that in the v2 package, not here.
    36  // But, because the legacy package imports the v2 package, that'd
    37  // cause a cycle.
    38  //
    39  // The lesson is that the "have legacy be an alias for v2 instead of
    40  // duplicating the files" thing we did was a bad thing to do.
    41
    42  // Determine whether rate limiting should take place.
    43  rpc ShouldRateLimit(RateLimitRequest) returns (RateLimitResponse) {
    44  }
    45}
    46
    47// Main message for a rate limit request. The rate limit service is designed to be fully generic
    48// in the sense that it can operate on arbitrary hierarchical key/value pairs. The loaded
    49// configuration will parse the request and find the most specific limit to apply. In addition,
    50// a RateLimitRequest can contain multiple "descriptors" to limit on. When multiple descriptors
    51// are provided, the server will limit on *ALL* of them and return an OVER_LIMIT response if any
    52// of them are over limit. This enables more complex application level rate limiting scenarios
    53// if desired.
    54message RateLimitRequest {
    55  option (udpa.annotations.versioning).previous_message_type =
    56      "envoy.service.ratelimit.v2.RateLimitRequest";
    57
    58  // All rate limit requests must specify a domain. This enables the configuration to be per
    59  // application without fear of overlap. E.g., "envoy".
    60  string domain = 1;
    61
    62  // All rate limit requests must specify at least one RateLimitDescriptor. Each descriptor is
    63  // processed by the service (see below). If any of the descriptors are over limit, the entire
    64  // request is considered to be over limit.
    65  repeated envoy.extensions.common.ratelimit.v3.RateLimitDescriptor descriptors = 2;
    66
    67  // Rate limit requests can optionally specify the number of hits a request adds to the matched
    68  // limit. If the value is not set in the message, a request increases the matched limit by 1.
    69  uint32 hits_addend = 3;
    70}
    71
    72// A response from a ShouldRateLimit call.
    73// [#next-free-field: 7]
    74message RateLimitResponse {
    75  option (udpa.annotations.versioning).previous_message_type =
    76      "envoy.service.ratelimit.v2.RateLimitResponse";
    77
    78  enum Code {
    79    // The response code is not known.
    80    UNKNOWN = 0;
    81
    82    // The response code to notify that the number of requests are under limit.
    83    OK = 1;
    84
    85    // The response code to notify that the number of requests are over limit.
    86    OVER_LIMIT = 2;
    87  }
    88
    89  // Defines an actual rate limit in terms of requests per unit of time and the unit itself.
    90  message RateLimit {
    91    option (udpa.annotations.versioning).previous_message_type =
    92        "envoy.service.ratelimit.v2.RateLimitResponse.RateLimit";
    93
    94    // Identifies the unit of of time for rate limit.
    95    // [#comment: replace by envoy/type/v3/ratelimit_unit.proto in v4]
    96    enum Unit {
    97      // The time unit is not known.
    98      UNKNOWN = 0;
    99
   100      // The time unit representing a second.
   101      SECOND = 1;
   102
   103      // The time unit representing a minute.
   104      MINUTE = 2;
   105
   106      // The time unit representing an hour.
   107      HOUR = 3;
   108
   109      // The time unit representing a day.
   110      DAY = 4;
   111    }
   112
   113    // A name or description of this limit.
   114    string name = 3;
   115
   116    // The number of requests per unit of time.
   117    uint32 requests_per_unit = 1;
   118
   119    // The unit of time.
   120    Unit unit = 2;
   121  }
   122
   123  message DescriptorStatus {
   124    option (udpa.annotations.versioning).previous_message_type =
   125        "envoy.service.ratelimit.v2.RateLimitResponse.DescriptorStatus";
   126
   127    // The response code for an individual descriptor.
   128    Code code = 1;
   129
   130    // The current limit as configured by the server. Useful for debugging, etc.
   131    RateLimit current_limit = 2;
   132
   133    // The limit remaining in the current time unit.
   134    uint32 limit_remaining = 3;
   135
   136    // Duration until reset of the current limit window.
   137    google.protobuf.Duration duration_until_reset = 4;
   138  }
   139
   140  // The overall response code which takes into account all of the descriptors that were passed
   141  // in the RateLimitRequest message.
   142  Code overall_code = 1;
   143
   144  // A list of DescriptorStatus messages which matches the length of the descriptor list passed
   145  // in the RateLimitRequest. This can be used by the caller to determine which individual
   146  // descriptors failed and/or what the currently configured limits are for all of them.
   147  repeated DescriptorStatus statuses = 2;
   148
   149  // A list of headers to add to the response
   150  repeated config.core.v3.HeaderValue response_headers_to_add = 3;
   151
   152  // A list of headers to add to the request when forwarded
   153  repeated config.core.v3.HeaderValue request_headers_to_add = 4;
   154
   155  // A response body to send to the downstream client when the response code is not OK.
   156  bytes raw_body = 5;
   157
   158  // Optional response metadata that will be emitted as dynamic metadata to be consumed by the next
   159  // filter. This metadata lives in a namespace specified by the canonical name of extension filter
   160  // that requires it:
   161  //
   162  // - :ref:`envoy.filters.http.ratelimit <config_http_filters_ratelimit_dynamic_metadata>` for HTTP filter.
   163  // - :ref:`envoy.filters.network.ratelimit <config_network_filters_ratelimit_dynamic_metadata>` for network filter.
   164  // - :ref:`envoy.filters.thrift.rate_limit <config_thrift_filters_rate_limit_dynamic_metadata>` for Thrift filter.
   165  google.protobuf.Struct dynamic_metadata = 6;
   166}

View as plain text