docs: rate limit and misc (#307)

Signed-off-by: Matt Klein <mklein@lyft.com>

api/BUILD

@@ -146,16 +146,19 @@ proto_library(
         ":lds",
         ":protocol",
         ":rds",
+        ":rls",
         "//api/filter/accesslog",
         "//api/filter/http:buffer",
         "//api/filter/http:fault",
         "//api/filter/http:health_check",
         "//api/filter/http:lua",
+        "//api/filter/http:rate_limit",
         "//api/filter/http:router",
         "//api/filter/http:transcoder",
         "//api/filter/network:client_ssl_auth",
         "//api/filter/network:http_connection_manager",
         "//api/filter/network:mongo_proxy",
+        "//api/filter/network:rate_limit",
         "//api/filter/network:redis_proxy",
         "//api/filter/network:tcp_proxy",
     ],

api/discovery.proto

@@ -31,7 +31,10 @@ message DiscoveryRequest {
   // as applied or the previous API config version respectively. Each type_url
   // (see below) has an independent version associated with it.
   string version_info = 1;
+
+  // The node making the request.
   Node node = 2;
+
   // List of resources to subscribe to, e.g. list of cluster names or a route
   // configuration name. If this is empty, all resources for the API are
   // returned. LDS/CDS expect empty resource_names, since this is global
@@ -39,11 +42,13 @@ message DiscoveryRequest {
   // a number of resources that need to be fetched via EDS/RDS, which will be
   // explicitly enumerated in resource_names.
   repeated string resource_names = 3;
+
   // Type of the resource that is being requested, e.g.
   // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This is implicit
   // in requests made via singleton xDS APIs such as CDS, LDS, etc. but is
   // required for ADS.
   string type_url = 4;
+
   // nonce corresponding to DiscoveryResponse being ACK/NACKed. See above
   // discussion on version_info and the DiscoveryResponse nonce comment. This
   // may be empty if no nonce is available, e.g. at startup or for non-stream
@@ -52,8 +57,13 @@ message DiscoveryRequest {
 }
 
 message DiscoveryResponse {
+  // The version of the response data.
   string version_info = 1;
+
+  // The response resources. These resources are typed and depend on the API being called.
   repeated google.protobuf.Any resources = 2;
+
+  // [#not-implemented-hide:]
   // Canary is used to support two Envoy command line flags:
   //
   // * --terminate-on-canary-transition-failure. When set, Envoy is able to
@@ -68,10 +78,12 @@ message DiscoveryResponse {
   // * --dry-run-canary. When set, a canary response will never be applied, only
   //   validated via a dry run.
   bool canary = 3;
+
   // Type URL for resources. This must be consistent with the type_url in the
   // Any messages for resources if resources is non-empty. This effectively
   // identifies the xDS API when muxing over ADS.
   string type_url = 4;
+
   // For gRPC based subscriptions, the nonce provides a way to explicitly ack a
   // specific DiscoveryResponse in a following DiscoveryRequest. Additional
   // messages may have been sent by Envoy to the management server for the

api/filter/http/rate_limit.proto

@@ -4,27 +4,31 @@ package envoy.api.v2.filter.http;
 
 import "google/protobuf/duration.proto";
 
-// HTTP rate limit filter configuration. The HTTP rate limit filter will
-// call the rate limit service when the request’s route or virtual host has
-// one or more rate limit configurations that match the filter stage
-// setting. The route can optionally include the virtual host rate limit
-// configurations. More than one configuration can apply to a request. Each
-// configuration results in a descriptor being sent to the rate limit
-// service. If the rate limit service is called, and the response for any
-// of the descriptors is over limit, a 429 response is returned.
+import "validate/validate.proto";
+
+// [#protodoc-title: Rate limit]
+// Rate limit :ref:`configuration overview <config_http_filters_rate_limit>`.
+
 message RateLimit {
   // The rate limit domain to use when calling the rate limit service.
-  string domain = 1;
+  string domain = 1 [(validate.rules).string.min_bytes = 1];
+
   // Specifies the rate limit configurations to be applied with the same
-  // stage number. If not set, the default stage number is 0. NOTE: The
-  // filter supports a range of 0 - 10 inclusively for stage numbers.
-  uint32 stage = 2;
-  // The type of requests the filter should apply to. The supported types
-  // are internal, external or both. A request is considered internal if
-  // x-envoy-internal is set to true. If x-envoy-internal is not set or
-  // false, a request is considered external. The filter defaults to both,
-  // and it will apply to all request types.
+  // stage number. If not set, the default stage number is 0.
+  //
+  // .. note::
+  //
+  //  The filter supports a range of 0 - 10 inclusively for stage numbers.
+  uint32 stage = 2 [(validate.rules).uint32.lte = 10];
+
+  // The type of requests the filter should apply to. The supported
+  // types are *internal*, *external* or *both*. A request is considered internal if
+  // :ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is set to true. If
+  // :ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is not set or false, a
+  // request is considered external. The filter defaults to *both*, and it will apply to all request
+  // types.
   string request_type = 3;
+
   // The timeout in milliseconds for the rate limit service RPC. If not
   // set, this defaults to 20ms.
   google.protobuf.Duration timeout = 4;

api/filter/network/rate_limit.proto

@@ -5,14 +5,21 @@ package envoy.api.v2.filter.network;
 import "api/rls.proto";
 import "google/protobuf/duration.proto";
 
-// TCP rate limit filter configuration
+import "validate/validate.proto";
+
+// [#protodoc-title: Rate limit]
+// Rate limit :ref:`configuration overview <config_network_filters_rate_limit>`.
+
 message RateLimit {
-  // The prefix to use when emitting statistics.
-  string stat_prefix = 1;
+  // The prefix to use when emitting :ref:`statistics <config_network_filters_rate_limit_stats>`.
+  string stat_prefix = 1 [(validate.rules).string.min_bytes = 1];
+
   // The rate limit domain to use in the rate limit service request.
-  string domain = 2;
+  string domain = 2 [(validate.rules).string.min_bytes = 1];
+
   // The rate limit descriptor list to use in the rate limit service request.
-  repeated RateLimitDescriptor descriptors = 3;
+  repeated RateLimitDescriptor descriptors = 3 [(validate.rules).repeated .min_items = 1];
+
   // The timeout in milliseconds for the rate limit service RPC. If not
   // set, this defaults to 20ms.
   google.protobuf.Duration timeout = 4;

api/rls.proto

@@ -2,6 +2,10 @@ 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) {
@@ -15,14 +19,17 @@ service RateLimitService {
 // 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;
@@ -31,34 +38,59 @@ message RateLimitRequest {
 // 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".
-// 1) ["authenticated": "false"], ["ip_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 ip_address field. 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.
-// 2) ["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).
-// 3) ["authenticated": "false"], ["path": "/foo/bar"], ["ip_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.
-// 4) ["authenticated": "true"], ["client_id": "foo"]
-//    What it does: Limits all traffic for an authenticated client "foo"
-// 5) ["authenticated": "true"], ["client_id": "foo"], ["path": "/foo/bar"]
-//    What it does: Limits traffic to a specific path for an authenticated client "foo"
+//
+// .. 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 {
-    string key = 1;
-    string value = 2;
+    // Descriptor key.
+    string key = 1 [(validate.rules).string.min_bytes = 1];
+
+    // Descriptor value.
+    string value = 2 [(validate.rules).string.min_bytes = 1];
   }
 
-  repeated Entry entries = 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;

docs/build.sh

@@ -35,6 +35,7 @@ PROTO_RST="
   /api/health_check/api/health_check.proto.rst
   /api/lds/api/lds.proto.rst
   /api/rds/api/rds.proto.rst
+  /api/rls/api/rls.proto.rst
   /api/sds/api/sds.proto.rst
   /api/filter/accesslog/accesslog/api/filter/accesslog/accesslog.proto.rst
   /api/filter/fault/api/filter/fault.proto.rst
@@ -42,11 +43,13 @@ PROTO_RST="
   /api/filter/http/fault/api/filter/http/fault.proto.rst
   /api/filter/http/health_check/api/filter/http/health_check.proto.rst
   /api/filter/http/lua/api/filter/http/lua.proto.rst
+  /api/filter/http/rate_limit/api/filter/http/rate_limit.proto.rst
   /api/filter/http/router/api/filter/http/router.proto.rst
   /api/filter/http/transcoder/api/filter/http/transcoder.proto.rst
   /api/filter/network/client_ssl_auth/api/filter/network/client_ssl_auth.proto.rst
   /api/filter/network/http_connection_manager/api/filter/network/http_connection_manager.proto.rst
   /api/filter/network/mongo_proxy/api/filter/network/mongo_proxy.proto.rst
+  /api/filter/network/rate_limit/api/filter/network/rate_limit.proto.rst
   /api/filter/network/redis_proxy/api/filter/network/redis_proxy.proto.rst
   /api/filter/network/tcp_proxy/api/filter/network/tcp_proxy.proto.rst
   /api/protocol/api/protocol.proto.rst

docs/root/api-v1/http_filters/rate_limit_filter.rst

@@ -0,0 +1,39 @@
+.. _config_http_filters_rate_limit_v1:
+
+Rate limit
+==========
+
+Rate limit :ref:`configuration overview <config_http_filters_rate_limit>`.
+
+.. code-block:: json
+
+  {
+    "name": "rate_limit",
+    "config": {
+      "domain": "...",
+      "stage": "...",
+      "request_type": "...",
+      "timeout_ms": "..."
+    }
+  }
+
+domain
+  *(required, string)* The rate limit domain to use when calling the rate limit service.
+
+stage
+  *(optional, integer)* Specifies the rate limit configurations to be applied with the same stage
+  number. If not set, the default stage number is 0.
+
+  **NOTE:** The filter supports a range of 0 - 10 inclusively for stage numbers.
+
+request_type
+  *(optional, string)* The type of requests the filter should apply to. The supported
+  types are *internal*, *external* or *both*. A request is considered internal if
+  :ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is set to true. If
+  :ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is not set or false, a
+  request is considered external. The filter defaults to *both*, and it will apply to all request
+  types.
+
+timeout_ms
+  *(optional, integer)* The timeout in milliseconds for the rate limit service RPC. If not set,
+  this defaults to 20ms.

docs/root/api-v1/network_filters/rate_limit_filter.rst

@@ -0,0 +1,40 @@
+.. _config_network_filters_rate_limit_v1:
+
+Rate limit
+==========
+
+Rate limit :ref:`configuration overview <config_network_filters_rate_limit>`.
+
+.. code-block:: json
+
+  {
+    "name": "ratelimit",
+    "config": {
+      "stat_prefix": "...",
+      "domain": "...",
+      "descriptors": [],
+      "timeout_ms": "..."
+    }
+  }
+
+stat_prefix
+  *(required, string)* The prefix to use when emitting :ref:`statistics
+  <config_network_filters_rate_limit_stats>`.
+
+domain
+  *(required, string)* The rate limit domain to use in the rate limit service request.
+
+descriptors
+  *(required, array)* The rate limit descriptor list to use in the rate limit service request. The
+  descriptors are specified as in the following example:
+
+  .. code-block:: json
+
+    [
+      [{"key": "hello", "value": "world"}, {"key": "foo", "value": "bar"}],
+      [{"key": "foo2", "value": "bar2"}]
+    ]
+
+timeout_ms
+  *(optional, integer)* The timeout in milliseconds for the rate limit service RPC. If not set,
+  this defaults to 20ms.

docs/root/api-v2/api.rst

@@ -22,4 +22,5 @@ v2 API reference
   address.proto
   protocol.proto
   discovery.proto
+  rls.proto
   filter/filter

docs/root/configuration/http_filters/rate_limit_filter.rst

@@ -3,7 +3,9 @@
 Rate limit
 ==========
 
-Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`.
+* Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`
+* :ref:`v1 API reference <config_http_filters_rate_limit_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.http.RateLimit>`
 
 The HTTP rate limit filter will call the rate limit service when the request's route or virtual host
 has one or more :ref:`rate limit configurations<config_http_conn_man_route_table_route_rate_limits>`
@@ -14,39 +16,6 @@ apply to a request. Each configuration results in a descriptor being sent to the
 If the rate limit service is called, and the response for any of the descriptors is over limit, a
 429 response is returned.
 
-.. code-block:: json
-
-  {
-    "name": "rate_limit",
-    "config": {
-      "domain": "...",
-      "stage": "...",
-      "request_type": "...",
-      "timeout_ms": "..."
-    }
-  }
-
-domain
-  *(required, string)* The rate limit domain to use when calling the rate limit service.
-
-stage
-  *(optional, integer)* Specifies the rate limit configurations to be applied with the same stage
-  number. If not set, the default stage number is 0.
-
-  **NOTE:** The filter supports a range of 0 - 10 inclusively for stage numbers.
-
-request_type
-  *(optional, string)* The type of requests the filter should apply to. The supported
-  types are *internal*, *external* or *both*. A request is considered internal if
-  :ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is set to true. If
-  :ref:`x-envoy-internal<config_http_conn_man_headers_x-envoy-internal>` is not set or false, a
-  request is considered external. The filter defaults to *both*, and it will apply to all request
-  types.
-
-timeout_ms
-  *(optional, integer)* The timeout in milliseconds for the rate limit service RPC. If not set,
-  this defaults to 20ms.
-
 .. _config_http_filters_rate_limit_composing_actions:
 
 Composing Actions

docs/root/configuration/network_filters/rate_limit_filter.rst

@@ -3,41 +3,9 @@
 Rate limit
 ==========
 
-Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`.
-
-.. code-block:: json
-
-  {
-    "name": "ratelimit",
-    "config": {
-      "stat_prefix": "...",
-      "domain": "...",
-      "descriptors": [],
-      "timeout_ms": "..."
-    }
-  }
-
-stat_prefix
-  *(required, string)* The prefix to use when emitting :ref:`statistics
-  <config_network_filters_rate_limit_stats>`.
-
-domain
-  *(required, string)* The rate limit domain to use in the rate limit service request.
-
-descriptors
-  *(required, array)* The rate limit descriptor list to use in the rate limit service request. The
-  descriptors are specified as in the following example:
-
-  .. code-block:: json
-
-    [
-      [{"key": "hello", "value": "world"}, {"key": "foo", "value": "bar"}],
-      [{"key": "foo2", "value": "bar2"}]
-    ]
-
-timeout_ms
-  *(optional, integer)* The timeout in milliseconds for the rate limit service RPC. If not set,
-  this defaults to 20ms.
+* Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`
+* :ref:`v1 API reference <config_network_filters_rate_limit_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.network.RateLimit>`
 
 .. _config_network_filters_rate_limit_stats: