docs: HTTP connection manager (#256 An error occurred )

I will defer RDS into another PR. I will also do another cleanup
pass over all of this later but want to get most of this in place
first.

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

.circleci/config.yml

@@ -18,6 +18,8 @@ jobs:
        - run: ci/do_ci.sh bazel.docs
        - add_ssh_keys
        - run: docs/publish.sh
+       - store_artifacts:
+           path: generated/docs
 
 workflows:
   version: 2

api/filter/http/http_connection_manager.proto

@@ -12,29 +12,53 @@ import "google/protobuf/duration.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
+import "validate/validate.proto";
+
+// [#protodoc-title: HTTP connection manager]
+// HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
+
 message Rds {
   // Configuration source specifier for RDS.
-  ConfigSource config_source = 1;
+  ConfigSource config_source = 1 [(validate.rules).message.required = true];
 
   // The name of the route configuration. This name will be passed to the RDS
   // API. This allows an Envoy configuration with multiple HTTP listeners (and
   // associated HTTP connection manager filters) to use different route
   // configurations.
-  string route_config_name = 2;
+  string route_config_name = 2 [(validate.rules).string.min_len = 1];
 }
 
 message HttpFilter {
   // The name of the filter to instantiate. The name must match a supported
-  // filter.
+  // filter. The built-in filters are:
-  string name = 1;
+  //
+  // [#comment:TODO(mattklein123): Auto generate the following list]
+  // * :ref:`envoy.buffer <config_http_filters_buffer>`
+  // * :ref:`envoy.cors <config_http_filters_cors>`
+  // * :ref:`envoy.fault <config_http_filters_fault_injection>`
+  // * :ref:`envoy.http_dynamo_filter <config_http_filters_dynamo>`
+  // * :ref:`envoy.grpc_http1_bridge <config_http_filters_grpc_bridge>`
+  // * :ref:`envoy.grpc_json_transcoder <config_http_filters_grpc_json_transcoder>`
+  // * :ref:`envoy.grpc_web <config_http_filters_grpc_web>`
+  // * :ref:`envoy.health_check <config_http_filters_health_check>`
+  // * :ref:`envoy.lua <config_http_filters_lua>`
+  // * :ref:`envoy.ip_tagging <config_http_filters_ip_tagging>`
+  // * :ref:`envoy.rate_limit <config_http_filters_rate_limit>`
+  // * :ref:`envoy.router <config_http_filters_router>`
+  string name = 1 [(validate.rules).string.min_len = 1];
 
   // Filter specific configuration which depends on the filter being
   // instantiated. See the supported filters for further documentation.
   google.protobuf.Struct config = 2;
 
+  // [#not-implemented-hide:]
+  // This is hidden as type has been deprecated and is no longer required.
   message DeprecatedV1 {
     string type = 1;
   }
+
+  // [#not-implemented-hide:]
+  // This is hidden as type has been deprecated and is no longer required.
   DeprecatedV1 deprecated_v1 = 3;
 }
 
@@ -46,25 +70,31 @@ message HttpConnectionManager {
     // is preferred, otherwise protocol inference is used. In almost all cases,
     // this is the right option to choose for this setting.
     AUTO = 0;
+
     // The connection manager will assume that the client is speaking HTTP/1.1.
     HTTP1 = 1;
+
     // The connection manager will assume that the client is speaking HTTP/2
     // (Envoy does not require HTTP/2 to take place over TLS or to use ALPN.
     // Prior knowledge is allowed).
     HTTP2 = 2;
   }
-  CodecType codec_type = 1;
+
+  // Supplies the type of codec that the connection manager should use.
+  CodecType codec_type = 1 [(validate.rules).enum.defined_only = true];
 
   // The human readable prefix to use when emitting statistics for the
-  // connection manager. See the statistics documentation for more information.
+  // connection manager. See the :ref:`statistics documentation <config_http_conn_man_stats>` for
-  string stat_prefix = 2;
+  // more information.
+  string stat_prefix = 2 [(validate.rules).string.min_len = 1];
 
   oneof route_specifier {
-    // The connection manager’s route table will be dynamically loaded via the
+    option (validate.required) = true;
-    // RDS API
+
+    // The connection manager’s route table will be dynamically loaded via the RDS API.
     Rds rds = 3;
-    // The route table for the connection manager is static and is specified in
+
-    // this property.
+    // The route table for the connection manager is static and is specified in this property.
     RouteConfiguration route_config = 4;
   }
 
@@ -73,31 +103,42 @@ message HttpConnectionManager {
   // processed sequentially as request events happen.
   repeated HttpFilter http_filters = 5;
 
-  // Whether the connection manager manipulates the user-agent and
+  // Whether the connection manager manipulates the :ref:`config_http_conn_man_headers_user-agent`
-  // x-envoy-downstream-service-cluster headers. See the linked documentation
+  // and :ref:`config_http_conn_man_headers_downstream-service-cluster` headers. See the linked
-  // for more information. Defaults to false.
+  // documentation for more information. Defaults to false.
   google.protobuf.BoolValue add_user_agent = 6;
 
   message Tracing {
-    // Span name will be derived from operation_name.
     enum OperationName {
+      // The HTTP listener is used for ingress/incoming requests.
       INGRESS = 0;
+
+      // The HTTP listener is used for egress/outgoing requests.
       EGRESS = 1;
     }
-    OperationName operation_name = 1;
 
-    // The header name is used to populate the tag name, and the header value is
+    // The span name will be derived from this field.
-    // used to populate the tag value. The tag is created if the specified
+    OperationName operation_name = 1 [(validate.rules).enum.defined_only = true];
-    // header name is present in the request’s headers.
+
+    // A list of header names used to create tags for the active span. The header name is used to
+    // populate the tag name, and the header value is used to populate the tag value. The tag is
+    // created if the specified header name is present in the request's headers.
     repeated string request_headers_for_tags = 2;
   }
+
+  // Presence of the object defines whether the connection manager
+  // emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider
+  // <config_tracing>`.
   Tracing tracing = 7;
 
+  // Additional HTTP/1 settings that are passed to the HTTP/1 codec.
   Http1ProtocolOptions http_protocol_options = 8;
+
+  // Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
   Http2ProtocolOptions http2_protocol_options = 9;
 
   // An optional override that the connection manager will write to the server
-  // header in responses. If not set, the default is envoy.
+  // header in responses. If not set, the default is *envoy*.
   string server_name = 10;
 
   // The idle timeout for connections managed by the connection manager. The
@@ -105,7 +146,7 @@ message HttpConnectionManager {
   // requests. If not set, there is no idle timeout. When the idle timeout is
   // reached the connection will be closed. If the connection is an HTTP/2
   // connection a drain sequence will occur prior to closing the connection. See
-  // drain_timeout.
+  // :ref:`drain_timeout <envoy_api_field_filter.http.HttpConnectionManager.drain_timeout>`.
   google.protobuf.Duration idle_timeout = 11;
 
   // The time that Envoy will wait between sending an HTTP/2 “shutdown
@@ -119,26 +160,27 @@ message HttpConnectionManager {
   // option is not specified.
   google.protobuf.Duration drain_timeout = 12;
 
-  // Configuration for HTTP access logs emitted by the connection manager.
+  // Configuration for :ref:`HTTP access logs <arch_overview_access_logs>`
+  // emitted by the connection manager.
   repeated AccessLog access_log = 13;
 
-  // If set to true, the connection manager will use the real remote address of
+  // If set to true, the connection manager will use the real remote address
-  // the client connection when determining internal versus external origin and
+  // of the client connection when determining internal versus external origin and manipulating
-  // manipulating various headers. If set to false or absent, the connection
+  // various headers. If set to false or absent, the connection manager will use the
-  // manager will use the x-forwarded-for HTTP header. See the documentation for
+  // :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header. See the documentation for
-  // x-forwarded-for, x-envoy-internal, and x-envoy-external-address for more
+  // :ref:`config_http_conn_man_headers_x-forwarded-for`,
-  // information.
+  // :ref:`config_http_conn_man_headers_x-envoy-internal`, and
-  // TODO(mattklein123): Clean this up, see also discussion in
+  // :ref:`config_http_conn_man_headers_x-envoy-external-address` for more information.
-  // https://github.com/lyft/envoy/issues/794.
   google.protobuf.BoolValue use_remote_address = 14;
 
-  // Whether the connection manager will generate the x-request-id header if it
+  // Whether the connection manager will generate the :ref:`x-request-id
-  // does not exist. This defaults to true. Generating a random UUID4 is
+  // <config_http_conn_man_headers_x-request-id>` header if it does not exist. This defaults to true.
-  // expensive so in high throughput scenarios where this feature is not desired
+  // Generating a random UUID4 is expensive so in high throughput scenarios where this feature is
-  // it can be disabled.
+  // not desired it can be disabled.
   google.protobuf.BoolValue generate_request_id = 15;
 
-  // How to handle the x-forwarded-client-cert (XFCC) HTTP header.
+  // How to handle the :ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP
+  // header.
   enum ForwardClientCertDetails {
     // Do not send the XFCC header to the next hop. This is the default value.
     SANITIZE = 0;
@@ -155,16 +197,25 @@ message HttpConnectionManager {
     // client connection is mTLS.
     ALWAYS_FORWARD_ONLY = 4;
   };
-  ForwardClientCertDetails forward_client_cert_details = 16;
 
-  // This field is valid only when forward_client_cert is append_forward or
+  // How to handle the :ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP
-  // sanitize_set and the client connection is mTLS. It specifies the fields in
+  // header.
-  // the client certificate to be forwarded. Note that in the
+  ForwardClientCertDetails forward_client_cert_details = 16
-  // x-forwarded-client-cert header, Hash is always set, and By is always set
+    [(validate.rules).enum.defined_only = true];
-  // when the client certificate presents the SAN value.
+
   message SetCurrentClientCertDetails {
+    // Whether to forward the subject of the client cert. Defaults to false.
     google.protobuf.BoolValue subject = 1;
+
+    // Whether to forward the SAN of the client cert. Defaults to false.
     google.protobuf.BoolValue san = 2;
   };
+
+  // This field is valid only when :ref:`forward_client_cert_details
+  // <envoy_api_field_filter.http.HttpConnectionManager.forward_client_cert_details>` is
+  // APPEND_FORWARD or SANITIZE_SET and the client connection is mTLS. It specifies the fields in
+  // the client certificate to be forwarded. Note that in the
+  // :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, *Hash* is always set, and
+  // *By* is always set when the client certificate presents the SAN value.
   SetCurrentClientCertDetails set_current_client_cert_details = 17;
 }

api/protocol.proto

@@ -4,20 +4,51 @@ package envoy.api.v2;
 
 import "google/protobuf/wrappers.proto";
 
+// [#protodoc-title: Protocol options]
+
+// [#not-implemented-hide:]
 message TcpProtocolOptions {
 }
 
 message Http1ProtocolOptions {
+  // Handle HTTP requests with absolute URLs in the requests. These requests
+  // are generally sent by clients to forward/explicit proxies. This allows clients to configure
+  // envoy as their HTTP proxy. In Unix, for example, this is typically done by setting the
+  // *http_proxy* environment variable.
   google.protobuf.BoolValue allow_absolute_url = 1;
 }
 
 message Http2ProtocolOptions {
+  // `Maximum table size <http://httpwg.org/specs/rfc7541.html#rfc.section.4.2>`_
+  // (in octets) that the encoder is permitted to use for the dynamic HPACK table. Valid values
+  // range from 0 to 4294967295 (2^32 - 1) and defaults to 4096. 0 effectively disables header
+  // compression.
   google.protobuf.UInt32Value hpack_table_size = 1;
+
+  // `Maximum concurrent streams <http://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2>`_
+  // allowed for peer on one HTTP/2 connection. Valid values range from 1 to 2147483647 (2^31 - 1)
+  // and defaults to 2147483647.
   google.protobuf.UInt32Value max_concurrent_streams = 2;
+
+  // `Initial stream-level flow-control window
+  // <http://httpwg.org/specs/rfc7540.html#rfc.section.6.9.2>`_ size. Valid values range from 65535
+  // (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to 268435456
+  // (256 * 1024 * 1024).
+  //
+  // NOTE: 65535 is the initial window size from HTTP/2 spec. We only support increasing the default
+  // window size now, so it's also the minimum.
+
+  // This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the
+  // HTTP/2 codec buffers.  Once the buffer reaches this pointer, watermark callbacks will fire to
+  // stop the flow of data to the codec buffers.
   google.protobuf.UInt32Value initial_stream_window_size = 3;
+
+  // Similar to *initial_stream_window_size*, but for connection-level flow-control
+  // window. Currently, this has the same minimum/maximum/default as *initial_stream_window_size*.
   google.protobuf.UInt32Value initial_connection_window_size = 4;
 }
 
+// [#not-implemented-hide:]
 message GrpcProtocolOptions {
   Http2ProtocolOptions http2_protocol_options = 1;
 }

docs/root/api-v1/api.rst

@@ -6,3 +6,4 @@ Envoy v1 API reference
   :maxdepth: 2
 
   network_filters/network_filters
+  http_filters/http_filters

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

@@ -0,0 +1,260 @@
+.. _config_http_filters_http_conn_man_v1:
+
+HTTP connection manager
+=======================
+
+* HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`.
+* HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`.
+
+.. code-block:: json
+
+  {
+    "name": "http_connection_manager",
+    "config": {
+      "codec_type": "...",
+      "stat_prefix": "...",
+      "rds": "{...}",
+      "route_config": "{...}",
+      "filters": [],
+      "add_user_agent": "...",
+      "tracing": "{...}",
+      "http1_settings": "{...}",
+      "http2_settings": "{...}",
+      "server_name": "...",
+      "idle_timeout_s": "...",
+      "drain_timeout_ms": "...",
+      "access_log": [],
+      "use_remote_address": "...",
+      "forward_client_cert": "...",
+      "set_current_client_cert": "...",
+      "generate_request_id": "..."
+    }
+  }
+
+.. _config_http_conn_man_codec_type:
+
+codec_type
+  *(required, string)* Supplies the type of codec that the connection manager should use. Possible
+  values are:
+
+  http1
+    The connection manager will assume that the client is speaking HTTP/1.1.
+
+  http2
+    The connection manager will assume that the client is speaking HTTP/2 (Envoy does not require
+    HTTP/2 to take place over TLS or to use ALPN. Prior knowledge is allowed).
+
+  auto
+    For every new connection, the connection manager will determine which codec to use. This mode
+    supports both ALPN for TLS listeners as well as protocol inference for plaintext listeners.
+    If ALPN data is available, it is preferred, otherwise protocol inference is used. In almost
+    all cases, this is the right option to choose for this setting.
+
+.. _config_http_conn_man_stat_prefix:
+
+stat_prefix
+  *(required, string)* The human readable prefix to use when emitting statistics for the
+  connection manager. See the :ref:`statistics <config_http_conn_man_stats>` documentation
+  for more information.
+
+.. _config_http_conn_man_rds_option:
+
+:ref:`rds <config_http_conn_man_rds>`
+  *(sometimes required, object)* The connection manager configuration must specify one of *rds* or
+  *route_config*. If *rds* is specified, the connection manager's route table will be dynamically
+  loaded via the RDS API. See the :ref:`documentation <config_http_conn_man_rds>` for more
+  information.
+
+.. _config_http_conn_man_route_config:
+
+:ref:`route_config <config_http_conn_man_route_table>`
+  *(sometimes required, object)* The connection manager configuration must specify one of *rds* or
+  *route_config*. If *route_config* is specified, the :ref:`route table <arch_overview_http_routing>`
+  for the connection manager is static and is specified in this property.
+
+:ref:`filters <config_http_conn_man_filters>`
+  *(required, array)* A list of individual :ref:`HTTP filters <arch_overview_http_filters>` that
+  make up the filter chain for requests made to the connection manager. Order matters as the filters
+  are processed sequentially as request events happen.
+
+.. _config_http_conn_man_add_user_agent:
+
+add_user_agent
+  *(optional, boolean)* Whether the connection manager manipulates the
+  :ref:`config_http_conn_man_headers_user-agent` and
+  :ref:`config_http_conn_man_headers_downstream-service-cluster` headers. See the linked
+  documentation for more information. Defaults to false.
+
+:ref:`tracing <config_http_conn_man_tracing>`
+  *(optional, object)* Presence of the object defines whether the connection manager
+  emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider
+  <config_tracing>`.
+
+.. _config_http_conn_man_http1_settings:
+
+http1_settings
+  *(optional, object)* Additional HTTP/1 settings that are passed to the HTTP/1 codec.
+
+  allow_absolute_url
+     *(optional, boolean)* Handle http requests with absolute urls in the requests. These requests
+     are generally sent by clients to forward/explicit proxies. This allows clients to configure
+     envoy as their http proxy. In Unix, for example, this is typically done by setting the
+     http_proxy environment variable.
+
+.. _config_http_conn_man_http2_settings:
+
+http2_settings
+  *(optional, object)* Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
+  Currently supported settings are:
+
+  hpack_table_size
+    *(optional, integer)* `Maximum table size <http://httpwg.org/specs/rfc7541.html#rfc.section.4.2>`_
+    (in octets) that the encoder is permitted to use for
+    the dynamic HPACK table. Valid values range from 0 to 4294967295 (2^32 - 1) and defaults to 4096.
+    0 effectively disables header compression.
+
+  max_concurrent_streams
+    *(optional, integer)* `Maximum concurrent streams
+    <http://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2>`_
+    allowed for peer on one HTTP/2 connection.
+    Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 2147483647.
+
+.. _config_http_conn_man_http2_settings_initial_stream_window_size:
+
+  initial_stream_window_size
+    *(optional, integer)* `Initial stream-level flow-control window
+    <http://httpwg.org/specs/rfc7540.html#rfc.section.6.9.2>`_ size. Valid values range from 65535
+    (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to 268435456
+    (256 * 1024 * 1024).
+
+    NOTE: 65535 is the initial window size from HTTP/2 spec. We only support increasing the default window
+    size now, so it's also the minimum.
+
+    This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the
+    HTTP/2 codec buffers.  Once the buffer reaches this pointer, watermark callbacks will fire to
+    stop the flow of data to the codec buffers.
+
+  initial_connection_window_size
+    *(optional, integer)* Similar to :ref:`initial_stream_window_size
+    <config_http_conn_man_http2_settings_initial_stream_window_size>`, but for connection-level flow-control
+    window. Currently , this has the same minimum/maximum/default as :ref:`initial_stream_window_size
+    <config_http_conn_man_http2_settings_initial_stream_window_size>`.
+
+  These are the same options available in the upstream cluster :ref:`http2_settings
+  <config_cluster_manager_cluster_http2_settings>` option.
+
+.. _config_http_conn_man_server_name:
+
+server_name
+  *(optional, string)* An optional override that the connection manager will write to the
+  :ref:`config_http_conn_man_headers_server` header in responses. If not set, the default is
+  *envoy*.
+
+idle_timeout_s
+  *(optional, integer)* The idle timeout in seconds for connections managed by the connection
+  manager. The idle timeout is defined as the period in which there are no active requests. If not
+  set, there is no idle timeout. When the idle timeout is reached the connection will be closed. If
+  the connection is an HTTP/2 connection a drain sequence will occur prior to closing the
+  connection. See :ref:`drain_timeout_ms <config_http_conn_man_drain_timeout_ms>`.
+
+.. _config_http_conn_man_drain_timeout_ms:
+
+drain_timeout_ms
+  *(optional, integer)* The time in milliseconds that Envoy will wait between sending an HTTP/2
+  "shutdown notification" (GOAWAY frame with max stream ID) and a final GOAWAY frame. This is used
+  so that Envoy provides a grace period for new streams that race with the final GOAWAY frame.
+  During this grace period, Envoy will continue to accept new streams. After the grace period, a
+  final GOAWAY frame is sent and Envoy will start refusing new streams. Draining occurs both
+  when a connection hits the idle timeout or during general server draining. The default grace
+  period is 5000 milliseconds (5 seconds) if this option is not specified.
+
+:ref:`access_log <config_access_log>`
+  *(optional, array)* Configuration for :ref:`HTTP access logs <arch_overview_access_logs>`
+  emitted by the connection manager.
+
+.. _config_http_conn_man_use_remote_address:
+
+use_remote_address
+  *(optional, boolean)* If set to true, the connection manager will use the real remote address
+  of the client connection when determining internal versus external origin and manipulating
+  various headers. If set to false or absent, the connection manager will use the
+  :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header. See the documentation for
+  :ref:`config_http_conn_man_headers_x-forwarded-for`,
+  :ref:`config_http_conn_man_headers_x-envoy-internal`, and
+  :ref:`config_http_conn_man_headers_x-envoy-external-address` for more information.
+
+.. _config_http_conn_man_forward_client_cert:
+
+forward_client_cert
+  *(optional, string)* How to handle the
+  :ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP header.
+  Possible values are:
+
+  1. **sanitize**: Do not send the XFCC header to the next hop. This is the default value.
+  2. **forward_only**: When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
+  3. **always_forward_only**: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
+  4. **append_forward**: When the client connection is mTLS, append the client certificate information to the request's XFCC header and forward it.
+  5. **sanitize_set**: When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
+
+  For the format of the XFCC header, please refer to
+  :ref:`config_http_conn_man_headers_x-forwarded-client-cert`.
+
+.. _config_http_conn_man_set_current_client_cert_details:
+
+set_current_client_cert_details
+  *(optional, array)* A list of strings, possible values are *Subject* and *SAN*. This field is
+  valid only when *forward_client_cert* is *append_forward* or *sanitize_set* and the client
+  connection is mTLS. It specifies the fields in the client certificate to be forwarded. Note that
+  in the :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, `Hash` is always set,
+  and `By` is always set when the client certificate presents the SAN value.
+
+generate_request_id
+  *(optional, boolean)* Whether the connection manager will generate the
+  :ref:`config_http_conn_man_headers_x-request-id` header if it does not exist. This defaults to
+  *true*. Generating a random UUID4 is expensive so in high throughput scenarios where this
+  feature is not desired it can be disabled.
+
+.. _config_http_conn_man_tracing:
+
+Tracing
+-------
+
+.. code-block:: json
+
+  {
+    "tracing": {
+      "operation_name": "...",
+      "request_headers_for_tags": []
+    }
+  }
+
+operation_name
+  *(required, string)* Span name will be derived from operation_name. "ingress" and "egress"
+  are the only supported values.
+
+request_headers_for_tags
+  *(optional, array)* A list of header names used to create tags for the active span.
+  The header name is used to populate the tag name, and the header value is used to populate the
+  tag value. The tag is created if the specified header name is present in the request's headers.
+
+.. _config_http_conn_man_filters:
+
+Filters
+-------
+
+HTTP filter :ref:`architecture overview <arch_overview_http_filters>`.
+
+.. code-block:: json
+
+  {
+    "name": "...",
+    "config": "{...}"
+  }
+
+name
+  *(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
+  filter <config_http_filters>`.
+
+config
+  *(required, object)*  Filter specific configuration which depends on the filter being
+  instantiated. See the :ref:`supported filters <config_http_filters>` for further documentation.

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

@@ -0,0 +1,8 @@
+HTTP filters
+============
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  *

docs/root/configuration/http_conn_man/filters.rst

@@ -1,21 +0,0 @@
-.. _config_http_conn_man_filters:
-
-Filters
-=======
-
-HTTP filter :ref:`architecture overview <arch_overview_http_filters>`.
-
-.. code-block:: json
-
-  {
-    "name": "...",
-    "config": "{...}"
-  }
-
-name
-  *(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
-  filter <config_http_filters>`.
-
-config
-  *(required, object)*  Filter specific configuration which depends on the filter being
-  instantiated. See the :ref:`supported filters <config_http_filters>` for further documentation.

docs/root/configuration/http_conn_man/http_conn_man.rst

@@ -5,220 +5,13 @@ HTTP connection manager
 
 * HTTP connection manager :ref:`architecture overview <arch_overview_http_conn_man>`.
 * HTTP protocols :ref:`architecture overview <arch_overview_http_protocols>`.
-
+* :ref:`v1 API reference <config_http_filters_http_conn_man_v1>`
-.. code-block:: json
+* :ref:`v2 API reference <envoy_api_msg_filter.http.HttpConnectionManager>`
-
-  {
-    "name": "http_connection_manager",
-    "config": {
-      "codec_type": "...",
-      "stat_prefix": "...",
-      "rds": "{...}",
-      "route_config": "{...}",
-      "filters": [],
-      "add_user_agent": "...",
-      "tracing": "{...}",
-      "http1_settings": "{...}",
-      "http2_settings": "{...}",
-      "server_name": "...",
-      "idle_timeout_s": "...",
-      "drain_timeout_ms": "...",
-      "access_log": [],
-      "use_remote_address": "...",
-      "forward_client_cert": "...",
-      "set_current_client_cert": "...",
-      "generate_request_id": "..."
-    }
-  }
-
-.. _config_http_conn_man_codec_type:
-
-codec_type
-  *(required, string)* Supplies the type of codec that the connection manager should use. Possible
-  values are:
-
-  http1
-    The connection manager will assume that the client is speaking HTTP/1.1.
-
-  http2
-    The connection manager will assume that the client is speaking HTTP/2 (Envoy does not require
-    HTTP/2 to take place over TLS or to use ALPN. Prior knowledge is allowed).
-
-  auto
-    For every new connection, the connection manager will determine which codec to use. This mode
-    supports both ALPN for TLS listeners as well as protocol inference for plaintext listeners.
-    If ALPN data is available, it is preferred, otherwise protocol inference is used. In almost
-    all cases, this is the right option to choose for this setting.
-
-.. _config_http_conn_man_stat_prefix:
-
-stat_prefix
-  *(required, string)* The human readable prefix to use when emitting statistics for the
-  connection manager. See the :ref:`statistics <config_http_conn_man_stats>` documentation
-  for more information.
-
-.. _config_http_conn_man_rds_option:
-
-:ref:`rds <config_http_conn_man_rds>`
-  *(sometimes required, object)* The connection manager configuration must specify one of *rds* or
-  *route_config*. If *rds* is specified, the connection manager's route table will be dynamically
-  loaded via the RDS API. See the :ref:`documentation <config_http_conn_man_rds>` for more
-  information.
-
-.. _config_http_conn_man_route_config:
-
-:ref:`route_config <config_http_conn_man_route_table>`
-  *(sometimes required, object)* The connection manager configuration must specify one of *rds* or
-  *route_config*. If *route_config* is specified, the :ref:`route table <arch_overview_http_routing>`
-  for the connection manager is static and is specified in this property.
-
-:ref:`filters <config_http_conn_man_filters>`
-  *(required, array)* A list of individual :ref:`HTTP filters <arch_overview_http_filters>` that
-  make up the filter chain for requests made to the connection manager. Order matters as the filters
-  are processed sequentially as request events happen.
-
-.. _config_http_conn_man_add_user_agent:
-
-add_user_agent
-  *(optional, boolean)* Whether the connection manager manipulates the
-  :ref:`config_http_conn_man_headers_user-agent` and
-  :ref:`config_http_conn_man_headers_downstream-service-cluster` headers. See the linked
-  documentation for more information. Defaults to false.
-
-:ref:`tracing <config_http_conn_man_tracing>`
-  *(optional, object)* Presence of the object defines whether the connection manager
-  emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider <config_tracing>`.
-
-.. _config_http_conn_man_http1_settings:
-
-http1_settings
-  *(optional, object)* Additional HTTP/1 settings that are passed to the HTTP/1 codec.
-
-  allow_absolute_url
-     *(optional, boolean)* Handle http requests with absolute urls in the requests. These requests
-     are generally sent by clients to forward/explicit proxies. This allows clients to configure
-     envoy as their http proxy. In Unix, for example, this is typically done by setting the
-     http_proxy environment variable.
-
-.. _config_http_conn_man_http2_settings:
-
-http2_settings
-  *(optional, object)* Additional HTTP/2 settings that are passed directly to the HTTP/2 codec.
-  Currently supported settings are:
-
-  hpack_table_size
-    *(optional, integer)* `Maximum table size <http://httpwg.org/specs/rfc7541.html#rfc.section.4.2>`_
-    (in octets) that the encoder is permitted to use for
-    the dynamic HPACK table. Valid values range from 0 to 4294967295 (2^32 - 1) and defaults to 4096.
-    0 effectively disables header compression.
-
-  max_concurrent_streams
-    *(optional, integer)* `Maximum concurrent streams
-    <http://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2>`_
-    allowed for peer on one HTTP/2 connection.
-    Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 2147483647.
-
-.. _config_http_conn_man_http2_settings_initial_stream_window_size:
-
-  initial_stream_window_size
-    *(optional, integer)* `Initial stream-level flow-control window
-    <http://httpwg.org/specs/rfc7540.html#rfc.section.6.9.2>`_ size. Valid values range from 65535
-    (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to 268435456
-    (256 * 1024 * 1024).
-
-    NOTE: 65535 is the initial window size from HTTP/2 spec. We only support increasing the default window
-    size now, so it's also the minimum.
-
-    This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the
-    HTTP/2 codec buffers.  Once the buffer reaches this pointer, watermark callbacks will fire to
-    stop the flow of data to the codec buffers.
-
-  initial_connection_window_size
-    *(optional, integer)* Similar to :ref:`initial_stream_window_size
-    <config_http_conn_man_http2_settings_initial_stream_window_size>`, but for connection-level flow-control
-    window. Currently , this has the same minimum/maximum/default as :ref:`initial_stream_window_size
-    <config_http_conn_man_http2_settings_initial_stream_window_size>`.
-
-  These are the same options available in the upstream cluster :ref:`http2_settings
-  <config_cluster_manager_cluster_http2_settings>` option.
-
-.. _config_http_conn_man_server_name:
-
-server_name
-  *(optional, string)* An optional override that the connection manager will write to the
-  :ref:`config_http_conn_man_headers_server` header in responses. If not set, the default is
-  *envoy*.
-
-idle_timeout_s
-  *(optional, integer)* The idle timeout in seconds for connections managed by the connection
-  manager. The idle timeout is defined as the period in which there are no active requests. If not
-  set, there is no idle timeout. When the idle timeout is reached the connection will be closed. If
-  the connection is an HTTP/2 connection a drain sequence will occur prior to closing the
-  connection. See :ref:`drain_timeout_ms <config_http_conn_man_drain_timeout_ms>`.
-
-.. _config_http_conn_man_drain_timeout_ms:
-
-drain_timeout_ms
-  *(optional, integer)* The time in milliseconds that Envoy will wait between sending an HTTP/2
-  "shutdown notification" (GOAWAY frame with max stream ID) and a final GOAWAY frame. This is used
-  so that Envoy provides a grace period for new streams that race with the final GOAWAY frame.
-  During this grace period, Envoy will continue to accept new streams. After the grace period, a
-  final GOAWAY frame is sent and Envoy will start refusing new streams. Draining occurs both
-  when a connection hits the idle timeout or during general server draining. The default grace
-  period is 5000 milliseconds (5 seconds) if this option is not specified.
-
-:ref:`access_log <config_access_log>`
-  *(optional, array)* Configuration for :ref:`HTTP access logs <arch_overview_access_logs>`
-  emitted by the connection manager.
-
-.. _config_http_conn_man_use_remote_address:
-
-use_remote_address
-  *(optional, boolean)* If set to true, the connection manager will use the real remote address
-  of the client connection when determining internal versus external origin and manipulating
-  various headers. If set to false or absent, the connection manager will use the
-  :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header. See the documentation for
-  :ref:`config_http_conn_man_headers_x-forwarded-for`,
-  :ref:`config_http_conn_man_headers_x-envoy-internal`, and
-  :ref:`config_http_conn_man_headers_x-envoy-external-address` for more information.
-
-.. _config_http_conn_man_forward_client_cert:
-
-forward_client_cert
-  *(optional, string)* How to handle the
-  :ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) HTTP header.
-  Possible values are:
-
-  1. **sanitize**: Do not send the XFCC header to the next hop. This is the default value.
-  2. **forward_only**: When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.
-  3. **always_forward_only**: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
-  4. **append_forward**: When the client connection is mTLS, append the client certificate information to the request's XFCC header and forward it.
-  5. **sanitize_set**: When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.
-
-  For the format of the XFCC header, please refer to
-  :ref:`config_http_conn_man_headers_x-forwarded-client-cert`.
-
-.. _config_http_conn_man_set_current_client_cert_details:
-
-set_current_client_cert_details
-  *(optional, array)* A list of strings, possible values are *Subject* and *SAN*. This field is
-  valid only when *forward_client_cert* is *append_forward* or *sanitize_set* and the client
-  connection is mTLS. It specifies the fields in the client certificate to be forwarded. Note that
-  in the :ref:`config_http_conn_man_headers_x-forwarded-client-cert` header, `Hash` is always set,
-  and `By` is always set when the client certificate presents the SAN value.
-
-generate_request_id
-  *(optional, boolean)* Whether the connection manager will generate the
-  :ref:`config_http_conn_man_headers_x-request-id` header if it does not exist. This defaults to
-  *true*. Generating a random UUID4 is expensive so in high throughput scenarios where this
-  feature is not desired it can be disabled.
 
 .. toctree::
   :hidden:
 
   route_config/route_config
-  filters
-  tracing
   headers
   header_sanitizing
   stats

docs/root/configuration/http_conn_man/tracing.rst

@@ -1,23 +0,0 @@
-.. _config_http_conn_man_tracing:
-
-Tracing
-=======
-
-.. code-block:: json
-  
-  {
-    "tracing": {
-      "operation_name": "...",
-      "request_headers_for_tags": []
-    }
-  }
- 
-operation_name
-  *(required, string)* Span name will be derived from operation_name. "ingress" and "egress"
-  are the only supported values.
-
-request_headers_for_tags
-  *(optional, array)* A list of header names used to create tags for the active span.
-   The header name is used to populate the tag name, and the header value is used to populate the tag value.
-   The tag is created if the specified header name is present in the request's headers. 
-

tools/protodoc/protodoc.py

@@ -35,12 +35,16 @@ NOT_IMPLEMENTED_WARN_ANNOTATION = 'not-implemented-warn'
 # field.
 NOT_IMPLEMENTED_HIDE_ANNOTATION = 'not-implemented-hide'
 
+# Comment. Just used for adding text that will not go into the docs at all.
+COMMENT_ANNOTATION = 'comment'
+
 # Where v2 differs from v1..
 V2_API_DIFF_ANNOTATION = 'v2-api-diff'
 
 VALID_ANNOTATIONS = set([
     DOC_TITLE_ANNOTATION, NOT_IMPLEMENTED_WARN_ANNOTATION,
-    NOT_IMPLEMENTED_HIDE_ANNOTATION, V2_API_DIFF_ANNOTATION
+    NOT_IMPLEMENTED_HIDE_ANNOTATION, V2_API_DIFF_ANNOTATION,
+    COMMENT_ANNOTATION
 ])
 
 
@@ -240,10 +244,14 @@ def FormatMessageAsJson(type_context, msg):
   Return:
     RST formatted pseudo-JSON string representation of message definition.
   """
-  lines = [
+  lines = []
-      '"%s": %s' % (f.name, FormatFieldTypeAsJson(type_context, f))
+  for index, field in enumerate(msg.field):
-      for f in msg.field
+    field_type_context = type_context.Extend([2, index], field.name)
-  ]
+    leading_comment, comment_annotations = field_type_context.LeadingCommentPathLookup()
+    if NOT_IMPLEMENTED_HIDE_ANNOTATION in comment_annotations:
+      continue
+    lines.append('"%s": %s' % (field.name, FormatFieldTypeAsJson(type_context, field)))
+
   return '.. code-block:: json\n\n  {\n' + ',\n'.join(IndentLines(
       4, lines)) + '\n  }\n\n'