listeners: add unified matcher for filter chains

api/envoy/config/listener/v3/BUILD

@@ -11,6 +11,8 @@ api_proto_package(
         "//envoy/config/core/v3:pkg",
         "//envoy/type/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
         "@com_github_cncf_udpa//xds/core/v3:pkg",
+        "@com_github_cncf_udpa//xds/type/matcher/v3:pkg",
     ],
 )

api/envoy/config/listener/v3/listener.proto

@@ -13,7 +13,9 @@ import "envoy/config/listener/v3/udp_listener_config.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "xds/annotations/v3/status.proto";
 import "xds/core/v3/collection_entry.proto";
+import "xds/type/matcher/v3/matcher.proto";
 
 import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/security.proto";
@@ -36,7 +38,7 @@ message ListenerCollection {
   repeated xds.core.v3.CollectionEntry entries = 1;
 }
 
-// [#next-free-field: 32]
+// [#next-free-field: 33]
 message Listener {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Listener";
 
@@ -120,6 +122,79 @@ message Listener {
   // :ref:`FAQ entry <faq_how_to_setup_sni>`.
   repeated FilterChain filter_chains = 3;
 
+  // :ref:`Unified matcher <arch_overview_matching>` resolving the filter chain name from the network properties. This matcher is used as a replacement
+  // for the per-filter chain match condition
+  // :ref:`filter_chain_match <envoy_v3_api_field_config.listener.v3.FilterChain.filter_chain_match>`.
+  // If specified, all :ref:`filter_chains <envoy_v3_api_field_config.listener.v3.Listener.filter_chains>` must
+  // have non-empty and unique :ref:`name <envoy_v3_api_field_config.listener.v3.FilterChain.name>` fields and omit
+  // :ref:`filter_chain_match <envoy_v3_api_field_config.listener.v3.FilterChain.filter_chain_match>` field.
+  //
+  // The list of matching inputs is available :ref:`here <arch_overview_matching_network_inputs>`.
+  //
+  // Example: The following matcher selects three filter chains as follows:
+  //
+  // * if the destination port is 80, then the filter chain "http" is selected;
+  // * if the destination port is 443 and the source IP is in the range 192.0.0.0/2, then the filter chain "internal" is selected;
+  // * otherwise, if the destination port is 443, then the filter chain "https" is selected;
+  // * otherwise, the default filter chain is selected (or the connection is rejected without the default filter chain).
+  //
+  // .. validated-code-block:: yaml
+  //   :type-name: envoy.config.listener.v3.Listener
+  //
+  //   filter_chain_matcher:
+  //     matcher_tree:
+  //       input:
+  //         name: port
+  //         typed_config:
+  //           "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.network.v3.DestinationPortInput
+  //       exact_match_map:
+  //         map:
+  //           "80":
+  //             action:
+  //               name: http
+  //               typed_config:
+  //                 "@type": type.googleapis.com/google.protobuf.StringValue
+  //                 value: http
+  //           "443":
+  //             matcher:
+  //               matcher_tree:
+  //                 input:
+  //                   name: ip
+  //                   typed_config:
+  //                     "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.network.v3.SourceIPInput
+  //                 custom_match:
+  //                   name: ip-matcher
+  //                   typed_config:
+  //                     "@type": type.googleapis.com/xds.type.matcher.v3.IPMatcher
+  //                     range_matchers:
+  //                     - ranges:
+  //                       - address_prefix: 192.0.0.0
+  //                         prefix_len: 2
+  //                       on_match:
+  //                         action:
+  //                           name: internal
+  //                           typed_config:
+  //                             "@type": type.googleapis.com/google.protobuf.StringValue
+  //                             value: internal
+  //                     - ranges:
+  //                       - address_prefix: 0.0.0.0
+  //                       on_match:
+  //                         action:
+  //                           name: https
+  //                           typed_config:
+  //                             "@type": type.googleapis.com/google.protobuf.StringValue
+  //                             value: https
+  //
+  // .. note::
+  //
+  //  Once matched, each connection is permanently bound to its filter chain.
+  //  If the matcher changes but the filter chain remains the same, the
+  //  connections bound to the filter chain are not drained. If, however, the
+  //  filter chain is removed or structurally modified, then the drain for its
+  //  connections is initiated.
+  xds.type.matcher.v3.Matcher filter_chain_matcher = 32
+      [(xds.annotations.v3.field_status).work_in_progress = true];
+
   // If a connection is redirected using *iptables*, the port on which the proxy
   // receives it might be different from the original destination address. When this flag is set to
   // true, the listener hands off redirected connections to the listener associated with the

api/envoy/config/listener/v3/listener_components.proto

@@ -11,6 +11,8 @@ import "google/protobuf/any.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "xds/annotations/v3/status.proto";
+
 import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
@@ -259,10 +261,11 @@ message FilterChain {
   // establishment, the connection is summarily closed.
   google.protobuf.Duration transport_socket_connect_timeout = 9;
 
-  // [#not-implemented-hide:] The unique name (or empty) by which this filter chain is known. If no
-  // name is provided, Envoy will allocate an internal UUID for the filter chain. If the filter
-  // chain is to be dynamically updated or removed via FCDS a unique name must be provided.
-  string name = 7;
+  // The unique name (or empty) by which this filter chain is known.
+  // Note: :ref:`filter_chain_matcher
+  // <envoy_v3_api_field_config.listener.v3.Listener.filter_chain_matcher>`
+  // requires that filter chains are uniquely named within a listener.
+  string name = 7 [(xds.annotations.v3.field_status).work_in_progress = true];
 
   // [#not-implemented-hide:] The configuration to specify whether the filter chain will be built on-demand.
   // If this field is not empty, the filter chain will be built on-demand.

docs/root/intro/arch_overview/advanced/matching/inputs.rst

@@ -0,0 +1,38 @@
+.. _arch_overview_matching_inputs:
+
+Matching Inputs
+===============
+
+Matching inputs define a way to extract an input value used for matching using
+one of the pre-defined (exact, prefix) or a custom matching algorithm. The
+input functions are context-sensitive. For example, HTTP header inputs are
+applicable only in HTTP contexts, e.g. for matching HTTP requests.
+
+.. _arch_overview_matching_http_inputs:
+
+HTTP Input Functions
+####################
+
+These input  are available for matching HTTP requests.
+
+* :ref:`Request header value <envoy_v3_api_msg_type.matcher.v3.HttpRequestHeaderMatchInput>`.
+* :ref:`Request trailer value <envoy_v3_api_msg_type.matcher.v3.HttpRequestTrailerMatchInput>`.
+* :ref:`Response header value <envoy_v3_api_msg_type.matcher.v3.HttpResponseHeaderMatchInput>`.
+* :ref:`Response trailer value <envoy_v3_api_msg_type.matcher.v3.HttpResponseTrailerMatchInput>`.
+
+.. _arch_overview_matching_network_inputs:
+
+Network Input Functions
+#######################
+
+These input functions are available for matching TCP connections.
+
+* :ref:`Destination IP <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.DestinationIPInput>`.
+* :ref:`Destination port <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.DestinationPortInput>`.
+* :ref:`Source IP <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.SourceIPInput>`.
+* :ref:`Direct source IP <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.DirectSourceIPInput>`.
+* :ref:`Source port <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.SourcePortInput>`.
+* :ref:`Source type <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.SourceTypeInput>`.
+* :ref:`Server name <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.ServerNameInput>`.
+* :ref:`Transport protocol <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.TransportProtocolInput>`.
+* :ref:`Application protocol <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.ApplicationProtocolInput>`.

docs/root/intro/arch_overview/advanced/matching/matching.rst

@@ -1,7 +1,10 @@
+.. _arch_overview_matching:
+
 Generic Matching
 ================
 
 .. toctree::
   :maxdepth: 2
 
   matching_api
+  inputs

docs/root/version_history/current.rst

@@ -78,6 +78,7 @@ New Features
 * http2: re-enabled the HTTP/2 wrapper API. This should be a transparent change that does not affect functionality. Any behavior changes can be reverted by setting the ``envoy.reloadable_features.http2_new_codec_wrapper`` runtime feature to false.
 * http3: downstream HTTP/3 support is now GA! Upstream HTTP/3 also GA for specific deployments. See :ref:`here <arch_overview_http3>` for details.
 * http3: supports upstream HTTP/3 retries. Automatically retry `0-RTT safe requests <https://www.rfc-editor.org/rfc/rfc7231#section-4.2.1>`_ if they are rejected because they are sent `too early <https://datatracker.ietf.org/doc/html/rfc8470#section-5.2>`_. And automatically retry 0-RTT safe requests if connect attempt fails later on and the cluster is configured with TCP fallback. And add retry on ``http3-post-connect-failure`` policy which allows retry of failed HTTP/3 requests with TCP fallback even after handshake if the cluster is configured with TCP fallback. This feature is guarded by ``envoy.reloadable_features.conn_pool_new_stream_with_early_data_and_http3``.
+* matching: add experimental support for matching filter chains in a listener using the matching API.
 * matching: the matching API can now express a match tree that will always match by omitting a matcher at the top level.
 * outlier_detection: :ref:`max_ejection_time_jitter<envoy_v3_api_field_config.cluster.v3.OutlierDetection.base_ejection_time>` configuration added to allow adding a random value to the ejection time to prevent 'thundering herd' scenarios. Defaults to 0 so as to not break or change the behavior of existing deployments.
 * redis: support for hostnames returned in `cluster slots` response is now available.

source/extensions/common/matcher/BUILD

@@ -24,6 +24,8 @@ envoy_cc_library(
     name = "trie_matcher_lib",
     srcs = ["trie_matcher.cc"],
     hdrs = ["trie_matcher.h"],
+    # IP matching is core functionality.
+    visibility = ["//visibility:public"],
     deps = [
         "//envoy/matcher:matcher_interface",
         "//envoy/network:filter_interface",

source/server/BUILD

@@ -537,14 +537,19 @@ envoy_cc_library(
     deps = [
         ":filter_chain_factory_context_callback",
         "//envoy/config:typed_metadata_interface",
+        "//envoy/matcher:matcher_interface",
+        "//envoy/network:filter_interface",
         "//envoy/server:instance_interface",
         "//envoy/server:listener_manager_interface",
         "//envoy/server:transport_socket_config_interface",
         "//source/common/common:empty_string",
         "//source/common/config:utility_lib",
         "//source/common/init:manager_lib",
+        "//source/common/matcher:matcher_lib",
         "//source/common/network:cidr_range_lib",
         "//source/common/network:lc_trie_lib",
+        "//source/common/network/matching:data_impl_lib",
+        "//source/common/network/matching:inputs_lib",
         "//source/server:configuration_lib",
         "@envoy_api//envoy/config/listener/v3:pkg_cc_proto",
     ],