syntax = "proto3";

package envoy.api.v2;

import "validate/validate.proto";

// [#protodoc-title: Common rate limit components]

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.
// [#not-implemented-hide:] Hiding API for now.
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".
//
// .. code-block:: cpp
//
//   ["authenticated": "false"], ["remote_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 *remote_address* key. 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.
//
// .. code-block:: cpp
//
//   ["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).
//
// .. code-block:: cpp
//
//   ["authenticated": "false"], ["path": "/foo/bar"], ["remote_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.
//
// .. code-block:: cpp
//
//   ["authenticated": "true"], ["client_id": "foo"]
//
// What it does: Limits all traffic for an authenticated client "foo"
//
// .. code-block:: cpp
//
//   ["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 {
    // Descriptor key.
    string key = 1 [(validate.rules).string.min_bytes = 1];

    // Descriptor value.
    string value = 2 [(validate.rules).string.min_bytes = 1];
  }

  // Descriptor entries.
  repeated Entry entries = 1 [(validate.rules).repeated .min_items = 1];
}

// A response from a ShouldRateLimit call.
// [#not-implemented-hide:] Hiding API for now.
message RateLimitResponse {
  enum Code {
    UNKNOWN = 0;
    OK = 1;
    OVER_LIMIT = 2;
  }

  // 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;
  }

  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;
}