https: Unhide alt svc cache (#18101)

http: Unhide the AlternateProtocolCache configuration
and move some docs from http3_upstream.md to connection_pooling.rst

Risk Level: N/A - Docs only
Testing: N/A - Docs only
Docs Changes: Unhide the AlternateProtocolCache configuration and move some docs from http3_upstream.md to connection_pooling.rst
Release Notes: Added
Platform Specific Features: N/A

Signed-off-by: Ryan Hamilton <[email protected]>

api/envoy/extensions/filters/http/alternate_protocols_cache/v3/alternate_protocols_cache.proto

@@ -15,10 +15,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // Configuration for the alternate protocols cache HTTP filter.
 // [#extension: envoy.filters.http.alternate_protocols_cache]
-// TODO(RyanTheOptimist): Move content from source/docs/http3_upstream.md to
-// docs/root/intro/arch_overview/upstream/connection_pooling.rst when unhiding the proto.
 message FilterConfig {
-  // [#not-implemented-hide:]
   // If set, causes the use of the alternate protocols cache, which is responsible for
   // parsing and caching HTTP Alt-Svc headers. This enables the use of HTTP/3 for upstream
   // servers that advertise supporting it.

api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto

@@ -118,7 +118,6 @@ message HttpProtocolOptions {
     //   is alpha is not guaranteed to be API-stable.
     config.core.v3.Http3ProtocolOptions http3_protocol_options = 3;
 
-    // [#not-implemented-hide:]
     // The presence of alternate protocols cache options causes the use of the
     // alternate protocols cache, which is responsible for parsing and caching
     // HTTP Alt-Svc headers. This enables the use of HTTP/3 for origins that

docs/root/intro/arch_overview/upstream/connection_pooling.rst

@@ -50,8 +50,7 @@ pool will drain the affected connection. Once a connection reaches its :ref:`max
 stream limit <envoy_v3_api_field_config.core.v3.QuicProtocolOptions.max_concurrent_streams>`, it
 will be marked as busy until a stream is available. New connections are established anytime there is
 a pending request without a connection that can be dispatched to (up to circuit breaker limits for
-connections). HTTP/3 upstream support is currently only usable in situations where HTTP/3 is guaranteed
-to work, but automatic failover to TCP is coming soon!.
+connections).
 
 Automatic protocol selection
 ----------------------------
@@ -69,10 +68,21 @@ then 300ms later, if a QUIC connection is not established, will also attempt to
 Whichever handshake succeeds will be used for the initial
 stream, but if both TCP and QUIC connections are established, QUIC will eventually be preferred.
 
-Upcoming versions of HTTP/3 support will include only selecting HTTP/3 if the upstream advertises support
-either via `HTTP Alternative Services <https://tools.ietf.org/html/rfc7838>`_,
-`HTTPS DNS RR <https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04>`_, or "QUIC hints" which
-will be manually configured. This path is alpha and rapidly undergoing improvements with the goal of having
+If an alternate protocol cache is configured via
+:ref:`alternate_protocols_cache_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig.alternate_protocols_cache_options>`
+then HTTP/3 connections will only be attempted to servers which
+advertise HTTP/3 support either via `HTTP Alternative Services <https://tools.ietf.org/html/rfc7838>`, (eventually
+the `HTTPS DNS resource record<https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04>` or "QUIC hints"
+which will be manually configured).
+If no such advertisement exists, then HTTP/2 or HTTP/1 will be used instead.
+
+If no alternate protocol cache is configured, then HTTP/3 connections will be attempted to
+all servers, even those which do not advertise HTTP/3.
+
+Further, HTTP/3 runs over QUIC (which uses UDP) and not over TCP (which HTTP/1 and HTTP/2 use).
+It is not uncommon for network devices to block UDP traffic, and hence block HTTP/3. This
+means that upstream HTTP/3 connection attempts might be blocked by the network and will fall
+back to using HTTP/2 or HTTP/1.  This path is alpha and rapidly undergoing improvements with the goal of having
 the default behavior result in optimal latency for internet environments, so please be patient and follow along with Envoy release notes
 to stay aprised of the latest and greatest changes.
 

docs/root/version_history/current.rst

@@ -104,6 +104,7 @@ New Features
 * bootstrap: added :ref:`inline_headers <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.inline_headers>` in the bootstrap to make custom inline headers bootstrap configurable.
 * contrib: added new :ref:`contrib images <install_contrib>` which contain contrib extensions.
 * grpc reverse bridge: added a new :ref:`option <envoy_v3_api_field_extensions.filters.http.grpc_http1_reverse_bridge.v3.FilterConfig.response_size_header>` to support streaming response bodies when withholding gRPC frames from the upstream.
+* http: added :ref:`alternate_protocols_cache_options <envoy_v3_api_msg_config.core.v3.AlternateProtocolsCacheOptions>` for enabling HTTP/3 connections to servers which advertise HTTP/3 support via `HTTP Alternative Services <https://tools.ietf.org/html/rfc7838>`_.
 * http: added :ref:`string_match <envoy_v3_api_field_config.route.v3.HeaderMatcher.string_match>` in the header matcher.
 * http: added :ref:`x-envoy-upstream-stream-duration-ms <config_http_filters_router_x-envoy-upstream-stream-duration-ms>` that allows configuring the max stream duration via a request header.
 * http: added support for :ref:`max_requests_per_connection <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.max_requests_per_connection>` for both upstream and downstream connections.