docs: Finish RDS / ratelimit docs (#273)

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

api/rds.proto

@@ -203,6 +203,7 @@ message RouteAction {
   //   :ref:`retry overview <arch_overview_http_routing_retry>`.
   google.protobuf.Duration timeout = 8;
 
+  // HTTP retry :ref:`architecture overview <arch_overview_http_routing_retry>`.
   message RetryPolicy {
     // Specifies the conditions under which retry takes place. These are the same
     // conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and
@@ -261,6 +262,8 @@ message RouteAction {
   // Specifies a set of headers that will be added to requests matching this
   // route. Headers specified at this level are applied before headers from the
   // enclosing :ref:`envoy_api_msg_VirtualHost` and :ref:`envoy_api_msg_RouteConfiguration`.
+  // For more information see the documentation on :ref:`custom request headers
+  // <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption request_headers_to_add = 12;
 
   // Specifies a set of headers that will be added to responses to requests
@@ -282,6 +285,8 @@ message RouteAction {
   // :ref:`rate_limits <envoy_api_field_VirtualHost.rate_limits>` are not applied to the request.
   google.protobuf.BoolValue include_vh_rate_limits = 14;
 
+  // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer
+  // <arch_overview_load_balancing_types>`.
   message HashPolicy {
     message Header {
       // The name of the request header that will be used to obtain the hash
@@ -408,6 +413,13 @@ message Decorator {
   string operation = 1 [(validate.rules).string.min_len = 1];
 }
 
+// A route is both a specification of how to match a request as well as an indication of what to do
+// next (e.g., redirect, forward, rewrite, etc.).
+//
+// .. attention::
+//
+//   Envoy supports routing on HTTP method via :ref:`header matching
+//   <envoy_api_msg_HeaderMatcher>`.
 message Route {
   // Route matching parameters.
   RouteMatch match = 1 [(validate.rules).message.required = true];
@@ -447,12 +459,6 @@ message Route {
 // statistics are perfect in the sense that they are emitted on the downstream
 // side such that they include network level failures.
 //
-// Examples:
-//
-// * The regex */rides/\d+* matches the path */rides/0*
-// * The regex */rides/\d+* matches the path */rides/123*
-// * The regex */rides/\d+* does not match the path */rides/123/456*
-//
 // Documentation for :ref:`virtual cluster statistics <config_http_filters_router_stats>`.
 //
 // .. note::
@@ -464,6 +470,12 @@ message VirtualCluster {
   // Specifies a regex pattern to use for matching requests. The entire path of the request
   // must match the regex. The regex grammar used is defined `here
   // <http://en.cppreference.com/w/cpp/regex/ecmascript>`_.
+  //
+  // Examples:
+  //
+  // * The regex */rides/\d+* matches the path */rides/0*
+  // * The regex */rides/\d+* matches the path */rides/123*
+  // * The regex */rides/\d+* does not match the path */rides/123/456*
   string pattern = 1 [(validate.rules).string.min_len = 1];
 
   //  Specifies the name of the virtual cluster. The virtual cluster name as well
@@ -476,6 +488,7 @@ message VirtualCluster {
   RequestMethod method = 3;
 }
 
+// Global rate limiting :ref:`architecture overview <arch_overview_rate_limit>`.
 message RateLimit {
   // Refers to the stage set in the filter. The rate limit configuration only
   // applies to filters with the same stage number. The default stage number is
@@ -484,80 +497,126 @@ message RateLimit {
   // .. note::
   //
   //   The filter supports a range of 0 - 10 inclusively for stage numbers.
-  google.protobuf.UInt32Value stage = 1;
+  google.protobuf.UInt32Value stage = 1 [(validate.rules).uint32.lte = 10];
 
   // The key to be set in runtime to disable this rate limit configuration.
   string disable_key = 2;
 
   message Action {
     // The following descriptor entry is appended to the descriptor:
-    // ("source_cluster", "<local service cluster>")
+    //
-    message SourceCluster {
+    // .. code-block:: cpp
-    }
+    //
+    //   ("source_cluster", "<local service cluster>")
+    //
+    // <local service cluster> is derived from the :option:`--service-cluster` option.
+    message SourceCluster {}
 
     // The following descriptor entry is appended to the descriptor:
-    // ("destination_cluster", "<routed target cluster>")
+    //
-    message DestinationCluster {
+    // .. code-block:: cpp
-    }
+    //
-
+    //   ("destination_cluster", "<routed target cluster>")
-    // The following descriptor entry is appended when a header contains a key
+    //
-    // that matches the header_name:
+    // Once a request matches against a route table rule, a routed cluster is determined by one of
-    // ("<descriptor_key>", "<header_value_queried_from_header>")
+    // the following :ref:`route table configuration <envoy_api_msg_RouteConfiguration>`
+    // settings:
+    //
+    // * :ref:`cluster <envoy_api_field_RouteAction.cluster>` indicates the upstream cluster
+    //   to route to.
+    // * :ref:`weighted_clusters <envoy_api_field_RouteAction.weighted_clusters>`
+    //   chooses a cluster randomly from a set of clusters with attributed weight.
+    // * :ref:`cluster_header <envoy_api_field_RouteAction.cluster_header>` indicates which
+    //   header in the request contains the target cluster.
+    message DestinationCluster {}
+
+    // The following descriptor entry is appended when a header contains a key that matches the
+    // *header_name*:
+    //
+    // .. code-block:: cpp
+    //
+    //   ("<descriptor_key>", "<header_value_queried_from_header>")
     message RequestHeaders {
       // The header name to be queried from the request headers. The header’s
       // value is used to populate the value of the descriptor entry for the
       // descriptor_key.
-      string header_name = 1;
+      string header_name = 1 [(validate.rules).string.min_len = 1];
+
       // The key to use in the descriptor entry.
-      string descriptor_key = 2;
+      string descriptor_key = 2 [(validate.rules).string.min_len = 1];
     }
 
-    // The following descriptor entry is appended to the descriptor and is
+    // The following descriptor entry is appended to the descriptor and is populated using the
-    // populated using the trusted address from x-forwarded-for:
+    // trusted address from :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`:
-    // ("remote_address", "<trusted address from x-forwarded-for>")
+    //
-    message RemoteAddress {
+    // .. code-block:: cpp
-    }
+    //
+    //   ("remote_address", "<trusted address from x-forwarded-for>")
+    message RemoteAddress {}
 
     // The following descriptor entry is appended to the descriptor:
-    // ("generic_key", "<descriptor_value>")
+    //
+    // .. code-block:: cpp
+    //
+    //   ("generic_key", "<descriptor_value>")
     message GenericKey {
       // The value to use in the descriptor entry.
-      string descriptor_value = 1;
+      string descriptor_value = 1 [(validate.rules).string.min_len = 1];
     }
 
     // The following descriptor entry is appended to the descriptor:
-    // (“header_match”, “<descriptor_value>”)
+    //
+    // .. code-block:: cpp
+    //
+    //   ("header_match", "<descriptor_value>")
     message HeaderValueMatch {
       // The value to use in the descriptor entry.
-      string descriptor_value = 1;
+      string descriptor_value = 1 [(validate.rules).string.min_len = 1];
+
       // If set to true, the action will append a descriptor entry when the
       // request matches the headers. If set to false, the action will append a
       // descriptor entry when the request does not match the headers. The
       // default value is true.
       google.protobuf.BoolValue expect_match = 2;
+
       // Specifies a set of headers that the rate limit action should match
       // on. The action will check the request’s headers against all the
       // specified headers in the config. A match will happen if all the
       // headers in the config are present in the request with the same values
       // (or based on presence if the value field is not in the config).
-      repeated HeaderMatcher headers = 3;
+      repeated HeaderMatcher headers = 3 [(validate.rules).repeated.min_items = 1];
     }
 
     oneof action_specifier {
+      option (validate.required) = true;
+
+      // Rate limit on source cluster.
       SourceCluster source_cluster = 1;
+
+      // Rate limit on destination cluster.
       DestinationCluster destination_cluster = 2;
+
+      // Rate limit on request headers.
       RequestHeaders request_headers = 3;
+
+      // Rate limit on remote address.
       RemoteAddress remote_address = 4;
+
+      // Rate limit on a generic key.
       GenericKey generic_key = 5;
+
+      // Rate limit on the existence of request headers.
       HeaderValueMatch header_value_match = 6;
     }
   }
+
   // A list of actions that are to be applied for this rate limit configuration.
   // Order matters as the actions are processed sequentially and the descriptor
   // is composed by appending descriptor entries in that sequence. If an action
   // cannot append a descriptor entry, no descriptor is generated for the
-  // configuration. See composing actions for additional documentation.
+  // configuration. See :ref:`composing actions
-  repeated Action actions = 3;
+  // <config_http_filters_rate_limit_composing_actions>` for additional documentation.
+  repeated Action actions = 3 [(validate.rules).string.min_len = 1];
 }
 
 // .. attention::
@@ -654,7 +713,8 @@ message VirtualHost {
   // Specifies a list of HTTP headers that should be added to each request
   // handled by this virtual host. Headers specified at this level are applied
   // after headers from enclosed :ref:`envoy_api_msg_RouteAction` and before headers from the
-  // enclosing :ref:`envoy_api_msg_RouteConfiguration`.
+  // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information see the documentation
+  // on :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption request_headers_to_add = 7;
 
   // Specifies a list of HTTP headers that should be added to each response
@@ -705,7 +765,8 @@ message RouteConfiguration {
   // Specifies a list of HTTP headers that should be added to each request
   // routed by the HTTP connection manager. Headers specified at this level are
   // applied after headers from any enclosed :ref:`envoy_api_msg_VirtualHost` or
-  // :ref:`envoy_api_msg_RouteAction`.
+  // :ref:`envoy_api_msg_RouteAction`. For more information see the documentation on
+  // :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
   repeated HeaderValueOption request_headers_to_add = 6;
 
   // An optional boolean that specifies whether the clusters that the route
@@ -714,8 +775,10 @@ message RouteConfiguration {
   // load. If set to false and a route refers to a non-existent cluster, the
   // route table will load and the router filter will return a 404 if the route
   // is selected at runtime. This setting defaults to true if the route table
-  // is statically defined via the route_config option. This setting default to
+  // is statically defined via the :ref:`route_config
-  // false if the route table is loaded dynamically via the rds option. Users
+  // <envoy_api_field_filter.network.HttpConnectionManager.route_config>` option. This setting
+  // default to false if the route table is loaded dynamically via the :ref:`rds
+  // <envoy_api_field_filter.network.HttpConnectionManager.rds>` option. Users
   // may which to override the default behavior in certain cases (for example
   // when using CDS with a static route table).
   google.protobuf.BoolValue validate_clusters = 7;

docs/root/api-v1/route_config/rate_limits.rst

@@ -27,7 +27,7 @@ actions
   Order matters as the actions are processed sequentially and the descriptor is composed by
   appending descriptor entries in that sequence. If an action cannot append a descriptor entry,
   no descriptor is generated for the configuration. See :ref:`composing actions
-  <config_http_conn_man_route_table_rate_limit_composing_actions>` for additional documentation.
+  <config_http_filters_rate_limit_composing_actions>` for additional documentation.
 
 .. _config_http_conn_man_route_table_rate_limit_actions:
 
@@ -181,75 +181,3 @@ The following descriptor entry is appended to the descriptor:
 .. code-block:: cpp
 
   ("header_match", "<descriptor_value>")
-
-.. _config_http_conn_man_route_table_rate_limit_composing_actions:
-
-Composing Actions
------------------
-
-Each action populates a descriptor entry. A vector of descriptor entries compose a descriptor. To
-create more complex rate limit descriptors, actions can be composed in any order. The descriptor
-will be populated in the order the actions are specified in the configuration.
-
-Example 1
-^^^^^^^^^
-
-For example, to generate the following descriptor:
-
-.. code-block:: cpp
-
-  ("generic_key", "some_value")
-  ("source_cluster", "from_cluster")
-
-The configuration would be:
-
-.. code-block:: json
-
-  {
-    "actions" : [
-      {
-        "type" : "generic_key",
-        "descriptor_value" : "some_value"
-      },
-      {
-        "type" : "source_cluster"
-      }
-    ]
-  }
-
-Example 2
-^^^^^^^^^
-
-If an action doesn't append a descriptor entry, no descriptor is generated for
-the configuration.
-
-For the following configuration:
-
-.. code-block:: json
-
-  {
-    "actions" : [
-      {
-        "type" : "generic_key",
-        "descriptor_value" : "some_value"
-      },
-      {
-        "type" : "remote_address"
-      },
-      {
-        "type" : "souce_cluster"
-      }
-    ]
-  }
-
-If a request did not set :ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for>`,
-no descriptor is generated.
-
-If a request sets :ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for>`, the
-the following descriptor is generated:
-
-.. code-block:: cpp
-
-  ("generic_key", "some_value")
-  ("remote_address", "<trusted address from x-forwarded-for>")
-  ("source_cluster", "from_cluster")

docs/root/configuration/http_conn_man/http_conn_man.rst

@@ -3,8 +3,8 @@
 HTTP connection manager
 =======================
 
-* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`.
+* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`
-* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`.
+* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`
 * :ref:`v1 API reference <config_network_filters_http_conn_man_v1>`
 * :ref:`v2 API reference <envoy_api_msg_filter.network.HttpConnectionManager>`
 

docs/root/configuration/http_conn_man/rds.rst

@@ -1,7 +1,7 @@
 .. _config_http_conn_man_rds:
 
-Route discovery service
+v1 Route discovery service (RDS)
-=======================
+================================
 
 The route discovery service (RDS) API is an optional API that Envoy will call to dynamically fetch
 :ref:`route configurations <config_http_conn_man_route_table>`. A route configuration includes both

docs/root/configuration/http_filters/rate_limit_filter.rst

@@ -47,6 +47,84 @@ 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
+-----------------
+
+.. attention::
+
+  This section is written for the v1 API but the concepts also apply to the v2 API. It will be
+  rewritten to target the v2 API in a future release.
+
+Each :ref:`rate limit action <config_http_conn_man_route_table_rate_limit_config>` on the route or
+virtual host populates a descriptor entry. A vector of descriptor entries compose a descriptor. To
+create more complex rate limit descriptors, actions can be composed in any order. The descriptor
+will be populated in the order the actions are specified in the configuration.
+
+Example 1
+^^^^^^^^^
+
+For example, to generate the following descriptor:
+
+.. code-block:: cpp
+
+  ("generic_key", "some_value")
+  ("source_cluster", "from_cluster")
+
+The configuration would be:
+
+.. code-block:: json
+
+  {
+    "actions" : [
+    {
+      "type" : "generic_key",
+      "descriptor_value" : "some_value"
+    },
+    {
+      "type" : "source_cluster"
+    }
+    ]
+  }
+
+Example 2
+^^^^^^^^^
+
+If an action doesn't append a descriptor entry, no descriptor is generated for
+the configuration.
+
+For the following configuration:
+
+.. code-block:: json
+
+  {
+    "actions" : [
+    {
+      "type" : "generic_key",
+      "descriptor_value" : "some_value"
+    },
+    {
+      "type" : "remote_address"
+    },
+    {
+      "type" : "souce_cluster"
+    }
+    ]
+  }
+
+If a request did not set :ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for>`,
+no descriptor is generated.
+
+If a request sets :ref:`x-forwarded-for<config_http_conn_man_headers_x-forwarded-for>`, the
+the following descriptor is generated:
+
+.. code-block:: cpp
+
+  ("generic_key", "some_value")
+  ("remote_address", "<trusted address from x-forwarded-for>")
+  ("source_cluster", "from_cluster")
+
 Statistics
 ----------
 

tools/protodoc/protodoc.py

@@ -357,8 +357,11 @@ def FormatMessageAsJson(type_context, msg):
     lines.append('"%s": %s' % (field.name,
                                FormatFieldTypeAsJson(type_context, field)))
 
-  return '.. code-block:: json\n\n  {\n' + ',\n'.join(IndentLines(
+  if lines:
-      4, lines)) + '\n  }\n\n'
+    return '.. code-block:: json\n\n  {\n' + ',\n'.join(IndentLines(
+        4, lines)) + '\n  }\n\n'
+  else:
+    return '.. code-block:: json\n\n  {}\n\n'
 
 
 def NormalizeFQN(fqn):